feat(runner): provision pinned Google Antigravity native runtime (#18187)

## Thinking Path

> - Paperclip manages agents and their work.
> - Native Runner providers need verified executables before they can
run.
> - Google Antigravity ships a native ACP server and a helper
executable.
> - An archive hash alone does not verify the installed runtime or its
child process cleanup.
> - This pull request adds a pinned installer and a small, verified
compatibility patch.
> - Later pull requests add Runner execution, account setup, and the
recorded user journey eval.

## Linked Issues or Issue Description

Refs: #12503, #14938. Those pull requests use the legacy CLI adapter.
This stack adds native Runner ACP support.

**Agent or provider**

Google Antigravity ACP 1.4.3.

**Why this adapter is useful**

Users need a reproducible runtime before they can select Antigravity for
a Paperclip agent.

**How the agent is invoked**

The installer prepares the native ACP server and helper. This pull
request does not enable task execution. Default execution remains closed
pending qualification.

## What Changed

- Pin the complete macOS ARM64 runtime closure. Keep other platforms as
inventory only.
- Verify archive entries, installed bytes, ownership, and cache layout.
- Patch exact upstream code anchors for model admission, instruction
loading, native process ownership, and per-call file tool completion.
- Package a self-contained installer and expose `paperclipai runtime
setup antigravity`.
- Record candidate limitations and historical acceptance evidence.

## Verification

- Runtime provisioning, packaging, metadata, and patch support tests: 62
passed. The separate exact pinned native patch run passed all 5 tests
with no skips and no Google authentication.
- CLI runtime setup tests: 5 passed.
- Map contract check passed. Staged diff whitespace check passed.
- The first test command ran before dependency installation and failed
on missing esbuild. The same command passed after installation.
- Current master has a stale lockfile. Dependencies were resolved
locally with scripts disabled. The generated lockfile is excluded from
this pull request.

- Final head: required `ci / verify` and `ci / e2e` passed, and Greptile
is 5/5 with both review threads resolved. The optional external
Paperclip Review remains queued. Two original timing failures are
retained; one failed-job rerun passed without source or deadline
changes.

## Risks

- The patch depends on exact upstream native code. A new upstream
release must get a new verified closure.
- Only macOS ARM64 has a complete verified runtime. Installation does
not qualify authentication, task execution, or other platforms.
- The installer downloads official Google assets when the verified cache
is absent.

## Model Used

OpenAI Codex (GPT-6). The host did not expose the exact model revision
or context limit. The model used tools for code edits, test execution,
and review.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

cli/src/__tests__/runtime-setup.test.ts

@@ -3,17 +3,17 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { afterEach, expect, it } from "vitest";
-import { resolveCursorProvisioner } from "../commands/runtime.js";
+import { resolveAntigravityProvisioner, resolveCursorProvisioner } from "../commands/runtime.js";
 
 const roots: string[] = [];
 afterEach(async () => { await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))); });
-async function fixture() {
+async function fixture(provider = "cursor") {
   const root = await realpath(await mkdtemp(join(tmpdir(), "cursor-public-setup-")));
   roots.push(root);
   await mkdir(join(root, "dist/vendor/paperclip-runner/cli"), { recursive: true });
   await writeFile(join(root, "package.json"), JSON.stringify({ name: "@paperclipai/server" }));
   await writeFile(join(root, "dist/index.js"), "throw new Error('must not import server');");
-  const provisioner = join(root, "dist/vendor/paperclip-runner/cli/provision-cursor.cjs");
+  const provisioner = join(root, `dist/vendor/paperclip-runner/cli/provision-${provider}.cjs`);
   await writeFile(provisioner, "fixture");
   return { root, provisioner, url: pathToFileURL(join(root, "dist/index.js")).href };
 }
@@ -36,3 +36,15 @@ it("rejects a provisioner linked outside the installed package", async () => {
   await rm(f.provisioner); await symlink(other.provisioner, f.provisioner);
   await expect(resolveCursorProvisioner(f.url)).rejects.toThrow("escapes");
 });
+
+it("resolves Antigravity setup from the public server without importing it", async () => {
+  const f = await fixture("antigravity");
+  expect(await resolveAntigravityProvisioner(f.url)).toBe(f.provisioner);
+});
+
+it("rejects an Antigravity provisioner outside the installed server", async () => {
+  const f = await fixture("antigravity"); const other = await fixture("antigravity");
+  await rm(f.provisioner); await symlink(other.provisioner, f.provisioner);
+  await expect(resolveAntigravityProvisioner(f.url)).rejects.toThrow("escapes");
+  await expect(resolveAntigravityProvisioner(`${f.url}?redirect=1`)).rejects.toThrow("installed Paperclip server");
+});

cli/src/__tests__/runtime.test.ts

@@ -28,7 +28,7 @@ it("rejects foreign package identity and a setup entrypoint outside that package
 });
 it("rejects unsupported runtime setup providers before resolution", async () => {
   const program = new Command(); registerRuntimeCommands(program);
-  await expect(program.parseAsync(["node", "paperclipai", "runtime", "setup", "untrusted"])).rejects.toThrow("Supported runtime setup: paperclipai runtime setup pi or cursor");
+  await expect(program.parseAsync(["node", "paperclipai", "runtime", "setup", "untrusted"])).rejects.toThrow("Supported runtime setup: paperclipai runtime setup pi, cursor, or antigravity");
 });
 
 it("resolves the companion importer only inside the actual public server tar layout", async () => {

cli/src/commands/runtime.ts

@@ -93,6 +93,43 @@ export async function setupCursorRuntime(): Promise<void> {
   } finally { process.off("SIGINT", cancel); process.off("SIGTERM", cancel); }
 }
 
+/** Resolve Antigravity setup without importing the server or starting a provider. */
+export async function resolveAntigravityProvisioner(serverUrl: string): Promise<string> {
+  const url = new URL(serverUrl);
+  if (url.protocol !== "file:" || url.search || url.hash) throw new Error("Antigravity setup requires an installed Paperclip server");
+  const entry = await realpath(fileURLToPath(url));
+  if (!entry.endsWith("/dist/index.js")) throw new Error("Antigravity setup requires the published server layout");
+  const root = resolve(dirname(entry), "..");
+  const manifest = join(root, "package.json");
+  const info = await lstat(manifest);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > 65536 || JSON.parse(await readFile(manifest, "utf8")).name !== "@paperclipai/server") throw new Error("Antigravity setup server package identity is invalid");
+  const provisioner = join(root, "dist/vendor/paperclip-runner/cli/provision-antigravity.cjs");
+  if (await realpath(provisioner) !== provisioner || !(await lstat(provisioner)).isFile()) throw new Error("Antigravity setup entrypoint escapes its server package");
+  return provisioner;
+}
+
+export async function setupAntigravityRuntime(): Promise<void> {
+  const provisioner = await resolveAntigravityProvisioner(import.meta.resolve("@paperclipai/server"));
+  const child = spawn(process.execPath, ["--use-env-proxy", provisioner], {
+    // Setup only downloads public assets. Reuse the existing network allowlist;
+    // runtime credentials and process-loader settings never reach this child.
+    stdio: "inherit", env: buildPiSetupEnvironment(),
+  });
+  const cancel = () => { if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM"); };
+  process.on("SIGINT", cancel); process.on("SIGTERM", cancel);
+  try {
+    await new Promise<void>((accept, reject) => {
+      let spawnError: Error | undefined;
+      child.on("error", error => { spawnError = error; });
+      child.once("close", (code, signal) => {
+        if (spawnError) reject(spawnError);
+        else if (code !== 0 || signal) reject(new Error("Antigravity setup did not finish. Review its error; an invalid installation is never replaced automatically."));
+        else accept();
+      });
+    });
+  } finally { process.off("SIGINT", cancel); process.off("SIGTERM", cancel); }
+}
+
 
 export function registerRuntimeCommands(program: Command): void {
   const runtime = program.command("runtime").description("Manage explicitly installed agent runtimes");
@@ -112,10 +149,11 @@ export function registerRuntimeCommands(program: Command): void {
       } finally { process.off("SIGINT", cancel); process.off("SIGTERM", cancel); }
     });
   runtime.command("setup <provider>")
-    .description("Install and verify the pinned Pi or Cursor runtime for this host (public downloads; no model calls)")
+    .description("Install and verify a pinned Pi, Cursor, or Antigravity runtime (public downloads; no model calls)")
     .action(async (provider: string) => {
       if (provider === "pi") await setupPiRuntime();
       else if (provider === "cursor") await setupCursorRuntime();
-      else throw new Error("Supported runtime setup: paperclipai runtime setup pi or cursor");
+      else if (provider === "antigravity") await setupAntigravityRuntime();
+      else throw new Error("Supported runtime setup: paperclipai runtime setup pi, cursor, or antigravity");
     });
 }