@estebanforge/pi-antigravity-bridge 1.9.3 → 1.10.1

package/src/agents.ts

@@ -8,7 +8,7 @@
 //
 // A picked name rides the turn request as `--agent` (same flag our web
 // tools already pass for their throwaway agents). ACP has no agent slot in
-// the protocol (RC01), so selection is refused at the command level there.
+// per-turn agent selection, so the bridge refuses it at the command level.
 
 import { spawnAgyRaw } from "./models.js";
 

package/src/agy-install.ts

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import { isAgyInstalled } from "./engine-picker.js";
+
+export interface AgyInstallCommand {
+	command: string;
+	args: string[];
+}
+
+export function agyInstallCommand(platform: NodeJS.Platform = process.platform): AgyInstallCommand {
+	if (platform === "win32") {
+		return {
+			command: "powershell.exe",
+			args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", "irm https://antigravity.google/cli/install.ps1 | iex"],
+		};
+	}
+	return {
+		command: "bash",
+		args: ["-c", "set -o pipefail; curl -fsSL https://antigravity.google/cli/install.sh | bash"],
+	};
+}
+
+export function agyAuthenticationMessage(): string {
+	return "Run `agy` in your terminal and complete the Google sign-in. Restart pi afterwards.";
+}
+
+type InstallRunner = (command: AgyInstallCommand, timeoutMs: number) => Promise<{ code: number | null; output: string }>;
+
+const defaultRunner: InstallRunner = ({ command, args }, timeoutMs) =>
+	new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			stdio: ["ignore", "pipe", "pipe"],
+			detached: process.platform !== "win32",
+			windowsHide: true,
+		});
+		let output = "";
+		let settled = false;
+		const append = (chunk: Buffer) => {
+			output = (output + chunk.toString("utf8")).slice(-64_000);
+		};
+		const fail = (err: Error) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(watchdog);
+			reject(err);
+		};
+		child.stdout?.on("data", append);
+		child.stderr?.on("data", append);
+		child.on("error", fail);
+		child.on("close", (code) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(watchdog);
+			resolve({ code, output: output.trim() });
+		});
+		const watchdog = setTimeout(() => {
+			try {
+				if (child.pid && process.platform === "win32") {
+					const killer = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+					killer.on("error", () => {});
+					killer.unref();
+				} else if (child.pid) process.kill(-child.pid, "SIGKILL");
+				else child.kill("SIGKILL");
+			} catch {
+				// The process may have exited between the deadline and kill.
+			}
+			fail(new Error("Antigravity CLI installer exceeded 10 minutes"));
+		}, timeoutMs);
+	});
+
+export async function installAgyCli(opts: {
+	platform?: NodeJS.Platform;
+	run?: InstallRunner;
+	verify?: () => boolean | Promise<boolean>;
+	timeoutMs?: number;
+} = {}): Promise<{ ok: true; output: string } | { ok: false; error: string }> {
+	try {
+		const result = await (opts.run ?? defaultRunner)(agyInstallCommand(opts.platform), opts.timeoutMs ?? 10 * 60_000);
+		if (result.code !== 0) return { ok: false, error: result.output || `installer exited with code ${result.code ?? "unknown"}` };
+		const verify = opts.verify ?? (() => isAgyInstalled(process.env.AGY_BIN || "agy"));
+		if (!(await verify())) return { ok: false, error: "installer finished, but agy is not available in this pi process; open a new terminal, run `agy --version`, then restart pi" };
+		return { ok: true, output: result.output };
+	} catch (err) {
+		return { ok: false, error: err instanceof Error ? err.message : String(err) };
+	}
+}

package/src/agy-paths.ts

@@ -1,9 +1,7 @@
 // agy per-engine state dirs ("brain" trees).
 //
-// Both engines keep per-conversation state on disk; the roots differ
-// (live-probed 2026-09-24, this machine):
-//   stream-json CLI:  ~/.gemini/antigravity-cli/brain/<conversationId>/
-//   ACP server:       ~/.gemini/antigravity-acp/brain/<conversationId>/
+// Both engines keep per-conversation state in the native CLI tree:
+//   ~/.gemini/antigravity-cli/brain/<conversationId>/
 // The ACP tree mirrors the CLI layout (.system_generated/tasks/,
 // .system_generated/steps/), so downstream scans (tasks, artifacts) work
 // unchanged once the right root is picked. A third tree exists —
@@ -18,8 +16,7 @@ import type { Engine } from "./config.js";
 
 /** Brain root for one engine. `home` injectable for tests. */
 export function agyBrainRoot(engine: Engine, home: string = os.homedir()): string {
-	const scope = engine === "acp" ? "antigravity-acp" : "antigravity-cli";
-	return path.join(home, ".gemini", scope, "brain");
+	return path.join(home, ".gemini", "antigravity-cli", "brain");
 }
 
 /** Per-conversation state dir. `conversationId` is the raw id agy reports

package/src/agy-setup.ts

@@ -0,0 +1,72 @@
+import { agyAuthenticationMessage, agyInstallCommand, installAgyCli } from "./agy-install.js";
+
+export interface AgySetupUi {
+	confirm: (title: string, body: string) => Promise<boolean>;
+	notify: (message: string, level: "info" | "warning") => void;
+	setStatus: (id: string, text?: string) => void;
+}
+
+export function createAgySetupOffer(opts: {
+	ui: AgySetupUi;
+	binaryOverride?: string;
+	install?: typeof installAgyCli;
+	missingMessage: () => string;
+	log: (event: string, data: unknown, level: "warn" | "info") => void;
+}): () => Promise<void> {
+	let offered = false;
+	let inFlight: Promise<void> | null = null;
+	const install = opts.install ?? installAgyCli;
+	const notify = (message: string, level: "info" | "warning") => {
+		try {
+			opts.ui.notify(message, level);
+		} catch (err) {
+			opts.log("agy-install", { error: String(err) }, "warn");
+		}
+	};
+
+	return () => {
+		if (inFlight) return inFlight;
+		if (offered) return Promise.resolve();
+		offered = true;
+		inFlight = (async () => {
+			try {
+				if (opts.binaryOverride) {
+					notify(
+						`AGY_BIN points to ${opts.binaryOverride}, which is missing or unsupported. Fix or unset AGY_BIN. The official installer cannot change this override.`,
+						"warning",
+					);
+					return;
+				}
+				const spec = agyInstallCommand();
+				const command = [spec.command, ...spec.args].join(" ");
+				const approved = await opts.ui.confirm(
+					"Antigravity CLI required",
+					`Both engines require the agy CLI. Run Google's official installer now?\n\n${command}`,
+				);
+				if (!approved) {
+					notify(opts.missingMessage(), "warning");
+					return;
+				}
+				opts.ui.setStatus("agy-install", "Installing Antigravity CLI…");
+				const result = await install();
+				if (!result.ok) {
+					opts.log("agy-install", { error: result.error }, "warn");
+					notify(`Antigravity CLI installation failed: ${result.error}\n${opts.missingMessage()}`, "warning");
+					return;
+				}
+				notify(`Antigravity CLI installed. ${agyAuthenticationMessage()}`, "info");
+			} catch (err) {
+				opts.log("agy-install", { error: String(err) }, "warn");
+				notify(`Antigravity CLI setup failed: ${String(err)}\n${opts.missingMessage()}`, "warning");
+			} finally {
+				try {
+					opts.ui.setStatus("agy-install", undefined);
+				} catch {
+					// UI teardown must not reject a shared setup promise.
+				}
+				inFlight = null;
+			}
+		})();
+		return inFlight;
+	};
+}

package/src/agy-version.ts

@@ -7,16 +7,15 @@
 // `agy --version`, memoized per binary because discovery already spawns agy
 // once per load and the version will not change mid-process.
 //
-// The ACP server reports its own version at initialize (agentInfo.version,
-// e.g. "agy_acp_server_1.1.1") and /agy doctor already prints it. ACP build
-// numbering is a different lineage from the CLI, so no floor is enforced
-// there: the one known-good build must not be locked out by a CLI number.
+// The ACP server reports the CLI version at initialize. agy acp has its own
+// floor because older CLI releases do not ship the subcommand.
 
 import { spawn } from "node:child_process";
 
 /** Floor for the stream-json CLI. Matches the protocol grammar our driver
  *  and the event mapping rely on; older agy predates verified fields. */
 export const MIN_AGY_VERSION = "1.1.22";
+export const MIN_AGY_ACP_VERSION = "1.5.3";
 
 const VERSION_TIMEOUT_MS = 5_000;
 

package/src/ask-tool.ts

@@ -747,7 +747,7 @@ export async function registerAskAntigravityTool(
 			if (args.includeContext) tags.push("context=full");
 			if (args.background) tags.push("bg");
 
-			let text = theme.fg("mdLink", theme.bold("AskAntigravity "));
+			let text = theme.fg("success", theme.bold("AskAntigravity "));
 			text += `${theme.fg("accent", `[${tags.join(", ")}]`)} `;
 
 			const prompt = String(args.prompt ?? "");
@@ -763,7 +763,7 @@ export async function registerAskAntigravityTool(
 			const d = result.details as AgyDetails | undefined;
 			if (isPartial) {
 				const status = result.content[0]?.type === "text" ? result.content[0].text : "working...";
-				return new Text(theme.fg("mdLink", "◉ AskAntigravity ") + theme.fg("muted", status), 0, 0);
+				return new Text(theme.fg("success", "◉ AskAntigravity ") + theme.fg("muted", status), 0, 0);
 			}
 
 			const body = result.content[0]?.type === "text" ? result.content[0].text : "";
@@ -772,7 +772,7 @@ export async function registerAskAntigravityTool(
 
 			let text = errored
 				? theme.fg("error", "✗ AskAntigravity error")
-				: theme.fg("mdLink", "✓ AskAntigravity");
+				: theme.fg("success", "✓ AskAntigravity");
 
 			const rTags: string[] = [];
 			if (d?.resolvedModel || d?.model) rTags.push(`model=${d?.resolvedModel ?? d?.model}`);

package/src/config.ts

@@ -38,15 +38,13 @@ export function logsDir(): string {
 	);
 }
 
-/** Which turn engine drives turns. "acp" (the official server) is the
- *  default for new installs; "stream-json" (the `agy` CLI) remains a fully
- *  supported fallback. */
+/** Native `agy acp` is the default for new installs; stream-json remains
+ *  a fully supported fallback. */
 export type Engine = "stream-json" | "acp";
 
 /** The engine a fresh install runs when nothing is configured (no file key,
  *  no AGY_ENGINE): the official ACP server. Unknown/stale stored values also
- *  fall back here; the first startup's acp self-heal installs the binary and
- *  chains the sign-in. */
+ *  fall back here. Startup checks that the required agy CLI is available. */
 export const DEFAULT_ENGINE: Engine = "acp";
 export type AgyMode = "accept-edits" | "plan";
 export type ThinkingTier = "low" | "medium" | "high";
@@ -82,8 +80,6 @@ export interface GateConfig {
 }
 
 export interface AcpConfig {
-	/** Path to agy_acp_server.par. Empty = env AGY_ACP_BIN > PATH. */
-	bin: string;
 	/** Gate B stopgap: client-side token estimates for ACP turns so pi's
 	 *  usage surfaces show nonzero numbers. Estimates are labeled as such in
 	 *  /agy doctor and auto-disable when the server sends real usage. */
@@ -100,7 +96,7 @@ export interface AgyConfig {
 	 *  is refused visibly: the agy CLI has no review-only enforcement on any
 	 *  path (probed 2026-10-07, upstream #1181: plan mode stages a plan and
 	 *  executes the write in the same turn on -p and stream-json alike; the
-	 *  ACP engine has no plan mode at all). Built for callers like
+	 *  provider plan turns are refused on ACP too). Built for callers like
 	 *  `pi -p --no-tools` health checks that must never mutate a workspace
 	 *  and prefer a visible refusal over a write-capable turn. Wins over
 	 *  `mode`; the AskAntigravity delegation tool is refused while this is on
@@ -215,7 +211,7 @@ const DEFAULTS: AgyConfig = {
 	turnTimeoutMin: 0, // placeholder: the real default is resolved per loadConfig call (defaultTurnTimeoutMin)
 	inactivityTimeoutMin: 5,
 	approvals: { gateMode: "auto", mode: "ask" },
-	acp: { bin: "", usageEstimate: "estimate" },
+	acp: { usageEstimate: "estimate" },
 };
 
 /** Hard ceiling for a free-typed turn cap: one day, in minutes. */
@@ -255,6 +251,21 @@ function readConfigFile(configPath: string): Partial<AgyConfig> {
 	return {};
 }
 
+/** Strip the retired acp.bin key from the raw config file; returns true when
+ *  removed. Raw passthrough on purpose (no defaults merge): users keep their
+ *  minimal hand-edited shape instead of gaining the full default set. */
+export function removeLegacyAcpBin(configPath: string = CONFIG_PATH): boolean {
+	const file = readConfigFile(configPath) as Record<string, unknown>;
+	if (!file.acp || typeof file.acp !== "object" || Array.isArray(file.acp)) return false;
+	const acp = file.acp as Record<string, unknown>;
+	if (!("bin" in acp)) return false;
+	delete acp.bin;
+	// Rename would replace a dotfiles-managed symlink with a regular file;
+	// write through the resolved target so the link survives.
+	writeConfigJson(fs.realpathSync(configPath), file);
+	return true;
+}
+
 /** Load config merged over defaults. Env vars override the file when set. */
 export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 	let file: Partial<AgyConfig> = readConfigFile(configPath);
@@ -268,8 +279,7 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 	// One absence exception: a config file WITHOUT an engine key belongs to an
 	// existing install (saveConfig persists the resolved legacy engine), and
 	// the acp default is for new installs only - an existing install keeps
-	// the legacy stream-json engine instead of silently starting the ~1.5 GB
-	// acp download. existsSync is false on EACCES too, which reads as fresh
+	// the legacy stream-json engine. existsSync is false on EACCES too, which reads as fresh
 	// and picks acp; an unreadable config dir is a broken install either way.
 	const freshInstall = !fs.existsSync(configPath);
 	const engineFallback = freshInstall || file.engine !== undefined ? DEFAULT_ENGINE : "stream-json";
@@ -379,12 +389,7 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 	).toLowerCase();
 	const usageEstimate: UsageEstimate =
 		usageRaw === "direct" || usageRaw === "off" ? usageRaw : "estimate";
-	const acp: AcpConfig = {
-		bin:
-			process.env.AGY_ACP_BIN ??
-			(typeof fileAcp.bin === "string" ? fileAcp.bin : DEFAULTS.acp.bin),
-		usageEstimate,
-	};
+	const acp: AcpConfig = { usageEstimate };
 
 	// Custom agent for stream-json turns (--agent). Env wins over the file
 	// (same pattern as mode). Normalized (trim/cap/control-strip); an empty
@@ -421,6 +426,24 @@ function narrowEngine(raw: string): Engine {
 	return raw === "acp" || raw === "stream-json" ? raw : DEFAULT_ENGINE;
 }
 
+/** Atomic JSON write (temp + rename, 0600) shared by every config writer. */
+function writeConfigJson(configPath: string, value: unknown): void {
+	const dir = path.dirname(configPath);
+	fs.mkdirSync(dir, { recursive: true });
+	const tmp = `${configPath}.${process.pid}.tmp`;
+	try {
+		fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+		fs.renameSync(tmp, configPath);
+	} catch (err) {
+		try {
+			fs.unlinkSync(tmp);
+		} catch {
+			/* nothing to clean */
+		}
+		throw err;
+	}
+}
+
 /** Atomically persist a config patch (temp + rename). Merges onto the RAW
  *  FILE values, never loadConfig(): env overrides must not be baked into the
  *  file (AGY_READONLY=1 in the env would otherwise persist readOnly: true to
@@ -438,14 +461,14 @@ export function saveConfig(patch: Partial<AgyConfig>, configPath: string = CONFI
 	// must never be baked into the file). A legacy file without an engine key
 	// persists "stream-json": the bare DEFAULTS spread below would otherwise
 	// write the acp default into an existing install's file on any unrelated
-	// save, arming the ~1.5 GB download on the next start.
+	// save, switching an existing install to ACP on the next start.
 	const persistedEngine = patch.engine ?? file.engine
 		?? (fs.existsSync(configPath) ? "stream-json" : DEFAULT_ENGINE);
 	const next: AgyConfig = {
 		...DEFAULTS,
 		...file,
 		...(file.acp !== undefined
-			? { acp: { bin: fileAcp.bin ?? DEFAULTS.acp.bin, usageEstimate: fileAcp.usageEstimate ?? DEFAULTS.acp.usageEstimate } }
+			? { acp: { usageEstimate: fileAcp.usageEstimate ?? DEFAULTS.acp.usageEstimate } }
 			: {}),
 		...(file.approvals !== undefined
 			? { approvals: { gateMode: fileApprovals.gateMode ?? DEFAULTS.approvals.gateMode, mode: fileApprovals.mode ?? DEFAULTS.approvals.mode } }
@@ -453,20 +476,7 @@ export function saveConfig(patch: Partial<AgyConfig>, configPath: string = CONFI
 		...patch,
 		engine: narrowEngine(String(persistedEngine).toLowerCase()),
 	};
-	const dir = path.dirname(configPath);
-	fs.mkdirSync(dir, { recursive: true });
-	const tmp = `${configPath}.${process.pid}.tmp`;
-	try {
-		fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
-		fs.renameSync(tmp, configPath);
-	} catch (err) {
-		try {
-			fs.unlinkSync(tmp);
-		} catch {
-			/* nothing to clean */
-		}
-		throw err;
-	}
+	writeConfigJson(configPath, next);
 	return next;
 }
 

package/src/driver-types.ts

@@ -7,8 +7,8 @@
 // deleted (phase 4) without breaking imports.
 //
 // The ACP driver implements the same surface with protocol-native mechanics:
-// no process recycle on profile drift, teardown-based abort (Gate D), and
-// `session/load` resume. See docs/ACP-ADOPTION-PLAN.md section 9.
+// no process recycle on profile drift, notification cancel with teardown
+// fallback, and `session/load` resume. See docs/ACP-ADOPTION-PLAN.md section 9.
 
 export type DriverState = "idle" | "starting" | "ready" | "running" | "dead";
 
@@ -19,7 +19,7 @@ export interface DriverProfile {
 	mode: string;
 	skipPermissions: boolean;
 	/** Custom agy agent (stream-json `--agent`). ACP has no agent slot in the
-	 *  protocol (RC01) and ignores it; the /agy agent command refuses to set
+	 *  per-turn agent selection and ignores it; the /agy agent command refuses to set
 	 *  one while the ACP engine is active. */
 	agent?: string;
 }
@@ -138,8 +138,6 @@ export interface DriverSnapshot {
 		sessionsCreated: number;
 		sessionsLoaded: number;
 		kills: number;
-		/** null = never probed on this server process. */
-		cancelSupported: boolean | null;
 		serverVersion?: string;
 		/** Connections beyond the first this driver process made = server
 		 *  restarts (Gate D kills + stale-exit replacements). */

package/src/engine-picker.ts

@@ -1,11 +1,9 @@
 // First-run onboarding: the engine picker plus the agy-presence warning.
 //
 // On the first interactive start (no config file yet, no AGY_ENGINE env) pi
-// asks which turn engine to use: the stream-json `agy` CLI or Google's
-// official ACP server. The choice persists via saveConfig({ engine }) and,
+// asks which native agy engine to use: stream-json or `agy acp`. The choice persists via saveConfig({ engine }) and,
 // like /agy engine, takes effect on the next pi start (drivers wire at load).
-// Every start with the stream-json engine active also re-checks that the
-// `agy` binary exists and warns until it does (re-auth is out of scope).
+// Startup checks the CLI once per process and offers setup when needed.
 //
 // UI: the shared framed choice modal from @estebanforge/pi-tui-dialogs
 // (dialogChoice): one decision statement, a closed option list, esc cancels.
@@ -21,8 +19,8 @@ import { DEFAULT_ENGINE, type Engine } from "./config.js";
 export const ENGINE_PICKER_ITEMS: ChoiceOption[] = [
 	{
 		value: "acp",
-		label: "ACP server (official Google)",
-		description: "default · official Google server",
+		label: "ACP (agy acp)",
+		description: "default · ACP server in the agy CLI",
 	},
 	{
 		value: "stream-json",
@@ -36,7 +34,7 @@ export const ENGINE_PICKER_ITEMS: ChoiceOption[] = [
 export const ENGINE_PICKER_INTRO = [
 	"Pick the engine that runs your Antigravity turns. Switch anytime with /agy engine (restart applies it).",
 	"",
-	"ACP (default): Google's official server (agy_acp_server.par). Needs a second Google sign-in and a ~1.5 GB server binary downloaded from Google (automatic, one-time, unavoidable: the server is not part of the agy CLI).",
+	"ACP (default): `agy acp`, the ACP server built into the agy CLI. Uses the same installation and Google sign-in as the CLI.",
 	"stream-json (fallback): the `agy` CLI you already installed and authenticated. Persistent process, streamed output.",
 ].join("\n");
 
@@ -63,12 +61,10 @@ export function toEngine(value: string): Engine {
 	return value === "acp" || value === "stream-json" ? value : DEFAULT_ENGINE;
 }
 
-/** Toast copy shown after the choice is saved. ACP names the promise that
- *  matters: the binary download starts NOW (not on restart), sign-in follows
- *  when it lands, restart applies the engine. */
+/** Toast copy shown after the choice is saved. */
 export function savedEngineMessage(engine: Engine): string {
 	return engine === "acp"
-		? "Engine saved: acp. The ~1.5 GB server binary downloads now; the Google sign-in opens when it lands. Restart applies the engine."
+		? "Engine saved: acp. Turns will use `agy acp` and your existing CLI authentication. Restart applies the engine."
 		: "Engine saved: stream-json. Restart pi to apply.";
 }
 
@@ -84,33 +80,56 @@ export function engineSettingsRow(engine: Engine): DialogRow {
 		id: ENGINE_SETTINGS_ROW_ID,
 		label: "Switch engine",
 		description:
-			"Open the engine picker (stream-json CLI vs the official ACP server). Enter opens it and closes settings; esc in the picker changes nothing. Restart applies a switch.",
+			"Open the engine picker (stream-json CLI vs agy acp). Enter opens it and closes settings; esc in the picker changes nothing. Restart applies a switch.",
 		currentValue: engine,
 	};
 }
 
-/** True when the `agy` CLI binary can be found. A binRef with a path
- *  separator (AGY_BIN=/opt/agy/agy) must exist as a file; a bare name is
- *  searched on PATH. statSync cannot throw through the guards, but a race
- *  (file removed between listing and stat) fails closed to false. */
-export function isAgyInstalled(binRef: string, env: NodeJS.ProcessEnv = process.env): boolean {
-	if (binRef.includes("/")) {
+/** Bare-name suffix candidates per platform. Windows pins the probe to
+ *  agy.exe: that is the only artifact Google ships there, and .bat/.cmd
+ *  cannot spawn anyway (shell:false + EINVAL since CVE-2024-27980). */
+function executableSuffixes(platform: NodeJS.Platform): string[] {
+	return platform === "win32" ? [".EXE"] : [""];
+}
+
+/** True when the `agy` CLI binary can be found. A binRef carrying a path
+ *  separator must exist as a file - backslashes count as separators on
+ *  win32, where path.join would mangle a bare "C:\..." AGY_BIN into a PATH
+ *  segment. Otherwise the bare name is searched on PATH, appending the
+ *  Windows candidate (agy.exe only: Google ships nothing else there, and
+ *  an extensionless or .cmd file cannot be spawned anyway). A bare
+ *  AGY_BIN that already ends in .exe probes the raw name too. Only a
+ *  regular file counts; races fail closed. */
+export function isAgyInstalled(
+	binRef: string,
+	env: NodeJS.ProcessEnv = process.env,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	if (binRef.includes("/") || (platform === "win32" && binRef.includes("\\"))) {
 		try {
 			return fs.statSync(binRef).isFile();
 		} catch {
 			return false;
 		}
 	}
+	let suffixes = executableSuffixes(platform);
+	// A bare AGY_BIN=agy.exe already carries the extension; name+suffix
+	// would stat agy.exe.EXE and miss the real file (issue #11 class).
+	if (platform === "win32" && path.extname(binRef).toLowerCase() === ".exe") {
+		suffixes = ["", ...suffixes];
+	}
 	return (env.PATH ?? "")
 		.split(path.delimiter)
 		.filter(Boolean)
-		.some((dir) => {
-			try {
-				return fs.statSync(path.join(dir, binRef)).isFile();
-			} catch {
-				return false;
-			}
-		});
+		.some((dir) =>
+			suffixes.some((suffix) => {
+				try {
+					return fs.statSync(path.join(dir, binRef) + suffix).isFile();
+				} catch {
+					return false;
+				}
+			}),
+		);
 }
 
 /** Toast copy for the missing-CLI warning. Fires every pi start while the

package/src/mcp-registration.ts

@@ -8,7 +8,7 @@
 //   { "mcpServers": { "<name>": { "disabled": false,
 //        "headers": { "x-bridge-token": "..." }, "serverUrl": "http://..." } } }
 //
-// The ACP engine does not use this file (mcpServers ride session/new).
+// Native ACP gets a sanitized private copy; stream-json reads this file.
 //
 // Merge rules: foreign servers are preserved; corrupt JSON is refused (the
 // file is shared user config - never clobber); writes are atomic.
@@ -36,19 +36,29 @@ export interface BridgeServerEntry {
 
 type McpConfig = { mcpServers: Record<string, unknown> };
 
+/** Tolerant read of the global mcp_config.json: strips a UTF-8 BOM and
+ *  treats the CLI's fresh-install 0-byte file as no config (issue #11).
+ *  Content that is not a JSON object still throws; ENOENT propagates.
+ *  A malformed mcpServers value is NOT normalized here - staging wants
+ *  strictness; registration normalizes at its own call site. */
+export function readGlobalMcpConfig(file: string): McpConfig {
+	const raw = fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "");
+	const parsed = raw.trim() === "" ? { mcpServers: {} } : JSON.parse(raw);
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error("mcp_config.json is not an object");
+	}
+	return parsed as McpConfig;
+}
+
 function readConfig(file: string): { ok: true; config: McpConfig } | { ok: false; reason: string } {
-	let parsed: unknown;
+	let config: McpConfig;
 	try {
-		parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+		config = readGlobalMcpConfig(file);
 	} catch (err) {
 		const code = (err as NodeJS.ErrnoException).code;
 		if (code === "ENOENT") return { ok: true, config: { mcpServers: {} } };
 		return { ok: false, reason: `mcp_config.json is not valid JSON; refusing to touch it (${String(err)})` };
 	}
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-		return { ok: false, reason: "mcp_config.json is not an object; refusing to touch it" };
-	}
-	const config = parsed as McpConfig;
 	if (!config.mcpServers || typeof config.mcpServers !== "object" || Array.isArray(config.mcpServers)) {
 		config.mcpServers = {};
 	}

package/src/mcp-server.ts

@@ -155,7 +155,7 @@ export function bridgeMcpConfigExists(): boolean {
 	return fs.existsSync(bridgeMcpConfigPath());
 }
 
-function isPidAlive(pid: number): boolean {
+export function isPidAlive(pid: number): boolean {
 	try {
 		process.kill(pid, 0);
 		return true;
@@ -166,10 +166,10 @@ function isPidAlive(pid: number): boolean {
 }
 
 /** Best-effort cleanup of stale per-pid dirs left by crashed sessions. */
-function sweepStaleBridgeDirs(): void {
+export function sweepStaleBridgeDirs(baseDir: string = BRIDGE_BASE, alive: (pid: number) => boolean = isPidAlive): void {
 	let entries: string[];
 	try {
-		entries = fs.readdirSync(BRIDGE_BASE);
+		entries = fs.readdirSync(baseDir);
 	} catch {
 		return;
 	}
@@ -177,9 +177,9 @@ function sweepStaleBridgeDirs(): void {
 		if (!name.startsWith("agy-mcp-")) continue;
 		const pid = Number(name.slice("agy-mcp-".length));
 		if (!Number.isInteger(pid) || pid === process.pid) continue;
-		if (isPidAlive(pid)) continue;
+		if (alive(pid)) continue;
 		try {
-			fs.rmSync(path.join(BRIDGE_BASE, name), { recursive: true, force: true });
+			fs.rmSync(path.join(baseDir, name), { recursive: true, force: true });
 		} catch {
 			/* best effort */
 		}

package/src/provider.ts

@@ -1213,7 +1213,7 @@ function acpEditFileArg(args: Record<string, unknown>): string | undefined {
 			// Edit display has TWO paths on ACP:
 			//   a) native diff in tool_call content[] (future builds / the
 			//      permission-request flow carries it; phase-2 probe shape);
-			//   b) RC01 with the auto policy sends NO content: the file simply
+			//   b) auto-approved edits can send NO content: the file simply
 			//      lands on disk. Read it and diff against git HEAD - the same
 			//      output the stream-json engine produces, one readFileSync.
 			if (feats.engine === "acp") {
@@ -1802,8 +1802,8 @@ export function createStreamSimple(
 		const config = loadConfig();
 		const engine = deps.engine ?? config.engine;
 		const selected = engine === "acp" && deps.acpDriver ? deps.acpDriver : deps.driver;
-		// Plan-shaped provider turns are fail-closed on BOTH engines. ACP has
-		// no plan mode at all (RC01). Stream-json is worse and probed
+		// Plan-shaped provider turns are fail-closed on BOTH engines because
+		// agy does not enforce review-only writes. Stream-json, probed
 		// 2026-10-07: the engine WARNS that --mode plan is a no-op while
 		// --disable-slash-commands is set, executes file writes even with
 		// slash expansion left on (it stages a plan.md and still writes in the
@@ -1828,7 +1828,7 @@ export function createStreamSimple(
 				stream,
 				blocks,
 				"error",
-				"Plan mode cannot be enforced on provider turns: the agy CLI stages a plan and executes writes in the same turn (probed 2026-10-07, google-antigravity/antigravity-cli#1181), and the ACP engine has no plan mode (RC01). /agy mode accept-edits, and enforce review-only in the host.",
+				"Plan mode cannot be enforced on provider turns: the agy CLI stages a plan and executes writes in the same turn (probed 2026-10-07, google-antigravity/antigravity-cli#1181), and provider plan turns are disabled on ACP too. /agy mode accept-edits, and enforce review-only in the host.",
 			);
 			return stream;
 		}