@estebanforge/pi-antigravity-bridge 1.4.9 → 1.5.0

package/src/approval-hook.ts

@@ -0,0 +1,252 @@
+// Staging for the approval-gate hooks.json (docs/TODO.md 2.5).
+//
+// The ACP server and the agy CLI fire workspace `.agents/hooks.json`
+// PreToolUse hooks (V2: deny honored, reason reaches the model; V3: hook
+// TIMEOUT = soft-pass, agy proceeds ungated). Therefore:
+//   - the staged handler timeout must exceed the whole park budget with
+//     margin (never rely on timeout as a deny), and
+//   - the staged command delegates to the bundled poll script, which
+//     early-acks and polls the bridge for the terminal decision.
+//
+// Merge rules: never clobber a foreign hooks.json. Parse failures abort
+// staging; first-time modification of an existing file writes a
+// timestamped backup next to it (the 2026-09-05 incident rule: every
+// destructive path gets a guard).
+//
+// Run: npm test
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const HOOK_GROUP = "pi-bridge-gate";
+
+/** Group-key namespace. Each pi session stages its OWN group keyed per-pid
+ *  (`pi-bridge-gate-<pid>`): hooks.json lives in the SHARED workspace, and
+ *  two concurrent sessions must never remove or overwrite each other's gate
+ *  (audit 2026-09-07: a single shared key let a gate-off session silently
+ *  strip a gate-on session's PreToolUse matchers). */
+export const GATE_GROUP_PREFIX = "pi-bridge-gate";
+
+/** This session's group key. */
+export function gateGroupKey(pid: number = process.pid): string {
+	return `${GATE_GROUP_PREFIX}-${pid}`;
+}
+
+/** True if the process is running (EPERM counts: alive but not ours). */
+function pidAlive(pid: number): boolean {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		return (e as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/** Which session a gate group belongs to, parsed from the script path its
+ *  command embeds (`.../approval-hook-<pid>.js`). The pid is the ownership
+ *  proof: the script is per-pid (0600, written by that session). Returns
+ *  null for groups we cannot attribute (foreign/future formats - never
+ *  touched). */
+function gateGroupPid(group: unknown): number | null {
+	const m = /approval-hook-(\d+)\.js/.exec(JSON.stringify(group));
+	return m ? Number(m[1]) : null;
+}
+
+/** agy native tools worth gating: everything that mutates the machine. */
+export const GATED_AGY_TOOLS =
+	"create_file|write_to_file|replace_file_content|multi_replace_file_content|edit_file|run_command";
+
+/** The same list as a set, for the bridge's POST /approval validation: a
+ *  payload for anything else is answered with a direct deny (defense in
+ *  depth - the hooks matcher should never let one through). */
+export const GATED_AGY_TOOL_SET: ReadonlySet<string> = new Set(GATED_AGY_TOOLS.split("|"));
+
+export interface StageOptions {
+	/** Bridge HTTP port (the approval endpoints live on the bridge server). */
+	port: number;
+	/** Bridge shared secret (x-bridge-token). */
+	token: string;
+	/** Path to the bundled poll script (written by the caller). */
+	scriptPath: string;
+	/** Full park budget in ms; the staged hook timeout exceeds it. */
+	parkBudgetMs: number;
+}
+
+/** Source of the staged poll script. Written to disk by the caller (data
+ *  dir), referenced by absolute path from the staged hooks.json. Early-acks
+ *  via POST /approval, then polls GET /approval/<ticket> until a terminal
+ *  decision or the deadline. Terminal: prints the JSON decision on stdout.
+ *  Deadline hit: prints {"decision":"deny", ...} (fail closed) - agy may
+ *  still soft-pass a timed-out hook, but a printed deny is honored (V2). */
+export function hookScriptSource(opts: { port: number; token: string; deadlineMs: number }): string {
+	return `#!/usr/bin/env node
+// Bridge approval hook (generated; do not edit). Polls the pi-antigravity-bridge.
+const PORT = ${opts.port};
+const TOKEN = ${JSON.stringify(opts.token)};
+const DEADLINE = Date.now() + ${opts.deadlineMs};
+let body = "";
+process.stdin.setEncoding("utf8");
+for await (const chunk of process.stdin) body += chunk;
+let ticket = "";
+try {
+	const res = await fetch(\`http://127.0.0.1:\${PORT}/approval\`, {
+		method: "POST",
+		headers: { "content-type": "application/json", "x-bridge-token": TOKEN },
+		body,
+	});
+	const json = await res.json();
+	// Ungated payloads get a terminal decision right on the POST (no park).
+	if (json && typeof json === "object" && "decision" in json) {
+		console.log(JSON.stringify(json.decision));
+		process.exit(0);
+	}
+	ticket = json.ticket ?? "";
+} catch {}
+if (!ticket) {
+	console.log(JSON.stringify({ decision: "deny", reason: "approval gate unreachable (bridge down?)" }));
+	process.exit(0);
+}
+while (Date.now() < DEADLINE) {
+	await new Promise((r) => setTimeout(r, 500));
+	try {
+		const res = await fetch(\`http://127.0.0.1:\${PORT}/approval/\${encodeURIComponent(ticket)}\`, {
+			headers: { "x-bridge-token": TOKEN },
+		});
+		const json = await res.json();
+		if (json.status !== "pending") {
+			console.log(JSON.stringify(json.decision ?? { decision: "deny", reason: "gate returned no decision" }));
+			process.exit(0);
+		}
+	} catch {}
+}
+console.log(JSON.stringify({ decision: "deny", reason: "approval gate deadline exceeded" }));
+`;
+}
+
+/** Hook timeout (seconds) staged for a given park budget: the budget plus a
+ *  60s margin, minimum 60s. V3: a timed-out hook soft-passes, so this must
+ *  never be smaller than the human can plausibly need. */
+export function stagedTimeoutSeconds(parkBudgetMs: number): number {
+	return Math.max(60, Math.ceil(parkBudgetMs / 1000) + 60);
+}
+
+/** Build our hooks.json group for one workspace staging. */
+export function buildGateGroup(opts: StageOptions): Record<string, unknown> {
+	const command = `node ${JSON.stringify(opts.scriptPath)}`;
+	return {
+		enabled: true,
+		PreToolUse: [
+			{
+				matcher: GATED_AGY_TOOLS,
+				hooks: [
+					{
+						type: "command",
+						command,
+						timeout: stagedTimeoutSeconds(opts.parkBudgetMs),
+					},
+				],
+			},
+		],
+	};
+}
+
+export interface StageResult {
+	wrote: boolean;
+	/** Backup file written before first modification of a foreign file. */
+	backup?: string;
+	/** Why nothing was written (parse failure, already current, ...). */
+	reason?: string;
+}
+
+/** Stage the gate group into <workspaceDir>/.agents/hooks.json under THIS
+ *  session's per-pid key. Merge-safe:
+ *  - foreign groups are preserved;
+ *  - gate groups of DEAD sessions are swept (their bridge is gone; the hook
+ *    would fail closed forever), groups of live sessions never touched;
+ *  - a foreign file is backed up before its first modification;
+ *  - unparseable files are never touched. */
+export function stageGateHooks(workspaceDir: string, opts: StageOptions): StageResult {
+	const dir = path.join(workspaceDir, ".agents");
+	const file = path.join(dir, "hooks.json");
+	const group = buildGateGroup(opts);
+	const ownKey = gateGroupKey();
+	let current: Record<string, unknown> = {};
+	const existed = fs.existsSync(file);
+	if (existed) {
+		try {
+			if (fs.lstatSync(file).isSymbolicLink()) {
+				return { wrote: false, reason: "hooks.json is a symlink; refusing to follow it" };
+			}
+		} catch {
+			return { wrote: false, reason: "hooks.json vanished while staging" };
+		}
+		try {
+			const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+				return { wrote: false, reason: "hooks.json is not an object; refusing to touch it" };
+			}
+			current = parsed as Record<string, unknown>;
+		} catch {
+			return { wrote: false, reason: "hooks.json is not valid JSON; refusing to touch it" };
+		}
+		// Sweep gate groups whose owning session is gone. Never touch groups of
+		// live sessions (concurrent pi sessions share this workspace) or groups
+		// we cannot attribute.
+		let swept = 0;
+		for (const key of Object.keys(current)) {
+			if (key === ownKey) continue;
+			const isGateGroup = key === GATE_GROUP_PREFIX || key.startsWith(`${GATE_GROUP_PREFIX}-`);
+			if (!isGateGroup) continue;
+			const pid = gateGroupPid(current[key]);
+			if (pid === null || pidAlive(pid)) continue;
+			delete current[key];
+			swept += 1;
+		}
+		if (swept > 0 && JSON.stringify(current[ownKey]) === JSON.stringify(group)) {
+			// Own group already current; the pass only swept dead peers.
+			fs.writeFileSync(file, JSON.stringify(current, null, 2) + "\n");
+			return { wrote: true, reason: `swept ${swept} dead gate group(s)` };
+		}
+		if (JSON.stringify(current[ownKey]) === JSON.stringify(group)) {
+			return { wrote: false, reason: "already staged" };
+		}
+	}
+	const backup =
+		existed && current[ownKey] === undefined
+			? `${file}.backup-${new Date().toISOString().replace(/[:.]/g, "-")}`
+			: undefined;
+	if (backup) fs.copyFileSync(file, backup);
+	current[ownKey] = group;
+	fs.mkdirSync(dir, { recursive: true });
+	fs.writeFileSync(file, JSON.stringify(current, null, 2) + "\n");
+	return { wrote: true, backup };
+}
+
+/** Remove ONLY this session's gate group (or the given pid's). Other
+ *  sessions' groups - including live ones in a shared workspace - are never
+ *  touched: a gate-off session must not strip a gate-on session's matchers
+ *  (audit 2026-09-07). Foreign content stays; an object file is left in
+ *  place (harmless). */
+export function removeGateHooks(workspaceDir: string, pid: number = process.pid): StageResult {
+	const file = path.join(workspaceDir, ".agents", "hooks.json");
+	if (!fs.existsSync(file)) return { wrote: false, reason: "no hooks.json" };
+	try {
+		if (fs.lstatSync(file).isSymbolicLink()) {
+			return { wrote: false, reason: "hooks.json is a symlink; refusing to follow it" };
+		}
+	} catch {
+		return { wrote: false, reason: "hooks.json vanished while removing" };
+	}
+	try {
+		const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+		if (!parsed || typeof parsed !== "object") return { wrote: false, reason: "not an object; refusing" };
+		const ownKey = gateGroupKey(pid);
+		if (parsed[ownKey] === undefined) return { wrote: false, reason: "not staged" };
+		delete parsed[ownKey];
+		fs.writeFileSync(file, JSON.stringify(parsed, null, 2) + "\n");
+		return { wrote: true };
+	} catch {
+		return { wrote: false, reason: "not valid JSON; refusing" };
+	}
+}

package/src/config.ts

@@ -44,6 +44,35 @@ export type AgyMode = "accept-edits" | "plan";
 export type ThinkingTier = "low" | "medium" | "high";
 export type BridgeTools = "none" | "mcp" | "all";
 
+/** How ACP turns report token usage while Gate B stands (agy sends none).
+ *  "estimate" (default): word-boundary regex over prompt/response/thought
+ *  text (pi-token-speed's mechanism). "direct": 1 token per streamed delta.
+ *  "off": keep zero-usage. Real server usage (usageSeen latch) always wins. */
+export type UsageEstimate = "estimate" | "direct" | "off";
+
+/** How the approval gate activates (docs/TODO.md section 2.5).
+ *
+ *  "auto" (default): OFF until a third-party pi permission extension is
+ *  detected (src/approval-detect.ts). When one is found, the gate runs in
+ *  "shadow" mode so that extension gates agy's native tool calls with zero
+ *  configuration on its side.
+ *
+ *  "shadow" / "dedicated": force the gate on in that shape. "off": never
+ *  gate, even when a permission extension is installed. NOTE: "dedicated"
+ *  currently stages the same shadow tools as "shadow" (warn-logged remap);
+ *  the explicit antigravity_approve variant is planned - see docs/TODO.md. */
+export type GateMode = "auto" | "shadow" | "dedicated" | "off";
+
+/** Fallback decision when no extension blocked a gated call: "ask" uses
+ *  ctx.ui.confirm (headless = deny, fail-closed), "allow" auto-approves,
+ *  "deny" auto-rejects. */
+export type GateAskMode = "ask" | "allow" | "deny";
+
+export interface GateConfig {
+	gateMode: GateMode;
+	mode: GateAskMode;
+}
+
 export interface AcpConfig {
 	/** Path to agy_acp_server.par. Empty = env AGY_ACP_BIN > PATH. */
 	bin: string;
@@ -51,6 +80,10 @@ export interface AcpConfig {
 	 *  (parity with skipPermissions). Kept as a key so future policies do not
 	 *  change the config shape. */
 	permissions: "auto";
+	/** 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. */
+	usageEstimate: UsageEstimate;
 }
 
 export interface AgyConfig {
@@ -108,6 +141,11 @@ export interface AgyConfig {
 	 *  digest (per-turn) is not. Turn off for agy-native behavior (agy's own
 	 *  system prompt only). */
 	systemPrompt: boolean;
+	/** Approval gate over agy NATIVE tool calls (create_file, run_command,
+	 *  ...). pi tools agy calls already pass through pi's gates via the G9
+	 *  round-trip; this covers the rest. Default auto (off until a
+	 *  third-party permission extension is detected). See docs/TODO.md 2.5. */
+	approvals: GateConfig;
 }
 
 const DEFAULTS: AgyConfig = {
@@ -120,7 +158,8 @@ const DEFAULTS: AgyConfig = {
 	bridgeTools: "all",
 	digest: false,
 	systemPrompt: true,
-	acp: { bin: "", permissions: "auto" },
+	approvals: { gateMode: "auto", mode: "ask" },
+	acp: { bin: "", permissions: "auto", usageEstimate: "estimate" },
 };
 
 /** Load config merged over defaults. Env vars override the file when set. */
@@ -189,12 +228,33 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		? ["1", "true", "on"].includes(envSys.toLowerCase())
 		: file.systemPrompt ?? DEFAULTS.systemPrompt;
 
+	// Approval gate (docs/TODO.md 2.5). Unknown values fall back to "auto"
+	// so a typo can never silently force the gate on.
+	const gateRaw = (process.env.AGY_APPROVALS ?? file.approvals?.gateMode ?? DEFAULTS.approvals.gateMode).toLowerCase();
+	const gateMode: GateMode =
+		gateRaw === "shadow" || gateRaw === "dedicated" || gateRaw === "off"
+			? gateRaw
+			: "auto";
+	const askRaw = (process.env.AGY_APPROVALS_MODE ?? file.approvals?.mode ?? DEFAULTS.approvals.mode).toLowerCase();
+	const gateAskMode: GateAskMode =
+		askRaw === "allow" || askRaw === "deny"
+			? askRaw
+			: "ask";
+
 	const fileAcp = (typeof file.acp === "object" && file.acp !== null ? file.acp : {}) as Partial<AcpConfig>;
+	// Unknown values fall back to "estimate" (same narrow-parse pattern as
+	// gateMode: a typo must never silently change behavior).
+	const usageRaw = String(
+		process.env.AGY_USAGE_ESTIMATE ?? fileAcp.usageEstimate ?? DEFAULTS.acp.usageEstimate,
+	).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),
 		permissions: "auto",
+		usageEstimate,
 	};
 
 	return {
@@ -208,6 +268,7 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		bridgeTools,
 		digest,
 		systemPrompt,
+		approvals: { gateMode, mode: gateAskMode },
 		patchCleanupNotified: file.patchCleanupNotified === true,
 	};
 }

package/src/driver-types.ts

@@ -1,9 +1,9 @@
 // Engine-agnostic turn-driver contract.
 //
-// Both turn engines (legacy stream-json driver in `driver.ts`, ACP driver in
+// Both turn engines (stream-json driver in `driver.ts`, ACP driver in
 // `acp/driver.ts`) implement `TurnDriver`, and everything above them — the
 // provider's stream loop, the G9 round-trip store, the extension wiring —
-// depends on this interface only. Types live here so the legacy module can be
+// depends on this interface only. Types live here so the stream module can be
 // deleted (phase 4) without breaking imports.
 //
 // The ACP driver implements the same surface with protocol-native mechanics:
@@ -21,17 +21,17 @@ export interface DriverProfile {
 }
 
 export interface DriverTurnRequest extends DriverProfile {
-	/** Existing conversation/session to resume. Legacy: agy conversation id via
+	/** Existing conversation/session to resume. Stream-json: agy conversation id via
 	 *  `--conversation`. ACP: sessionId via `session/load` (falls back to
 	 *  `session/new` when the server no longer knows it). */
 	conversationId?: string | null;
 	prompt: string;
 	/** Image blocks riding with the prompt. ACP forwards them as typed
 	 *  content blocks (probe 2026-09-03: 64x64 two-tone PNG answered
-	 *  correctly); the legacy CLI prompt is text-only and ignores them. */
+	 *  correctly); the stream-json CLI prompt is text-only and ignores them. */
 	images?: Array<{ data: string; mimeType: string }>;
 	/** ACP only: pi-side context delivered as a native `embeddedContext`
-	 *  resource block instead of inline prompt text (G1 on ACP). Legacy
+	 *  resource block instead of inline prompt text (G1 on ACP). Stream-json
 	 *  embeds the digest in the prompt string and ignores this. */
 	contextBlock?: { uri: string; text: string };
 	signal?: AbortSignal;
@@ -52,7 +52,7 @@ export type AgyUsage = {
 
 export type DriverActivity =
 	| { type: "text"; delta: string }
-	/** Legacy emits a token count only; ACP carries the actual thought text in
+	/** Stream-json emits a token count only; ACP carries the actual thought text in
 	 *  `delta`. The provider renders whichever is present. */
 	| { type: "thought"; tokens?: number; delta?: string }
 	| { type: "tool_start"; stepId?: number; name: string; args: Record<string, unknown> }
@@ -64,7 +64,7 @@ export type DriverActivity =
 			output?: string;
 			durationSeconds?: number;
 			/** ACP only: the server's native edit diff from `tool_call`
-			 *  content[] ({type:"diff", path, oldText?, newText}). Legacy never
+			 *  content[] ({type:"diff", path, oldText?, newText}). Stream-json never
 			 *  sets it; the provider renders it without any git subprocess. */
 			diff?: { path: string; oldText?: string; newText: string };
 	  }
@@ -108,7 +108,7 @@ export interface DriverSnapshot {
 		recycleReasons: Record<string, number>;
 	};
 	lifecycle: string[];
-	/** Present on ACP snapshots; absent on legacy. */
+	/** Present on ACP snapshots; absent on stream-json. */
 	engine?: "acp";
 	acp?: {
 		sessionId?: string;
@@ -133,7 +133,7 @@ export interface DriverSnapshot {
 }
 
 /** The engine contract. Everything above the driver depends on this interface
- *  only; `AgyDriver` and `AcpDriver` both implement it. */
+ *  only; `StreamDriver` and `AcpDriver` both implement it. */
 export interface TurnDriver {
 	readonly state: DriverState;
 	readonly activeHandle: TurnHandle | null;

package/src/driver.ts

@@ -122,7 +122,7 @@ export function shouldFlipToCumulative(accumulated: string, next: string): boole
 	return accumulated.length >= CUMULATIVE_FLIP_MIN_CHARS && isCumulativeResend(accumulated, next);
 }
 
-export class AgyDriver implements TurnDriver {
+export class StreamDriver implements TurnDriver {
 	#state: DriverState = "idle";
 	#child: ChildProcess | undefined;
 	#generation = 0;
@@ -130,7 +130,6 @@ export class AgyDriver implements TurnDriver {
 	#boundConversation: string | undefined;
 	#active: ActiveTurn | undefined;
 	#queueTail: Promise<void> = Promise.resolve();
-	#shutdown = false;
 	#stderrTail = "";
 	// Frames can split across pipe chunks; the trailing partial line lives here
 	// until its newline arrives (same scheme as JsonRpcSession.feed). Dropping
@@ -218,7 +217,10 @@ export class AgyDriver implements TurnDriver {
 	}
 
 	async #runExclusive(request: DriverTurnRequest): Promise<TurnHandle> {
-		if (this.#shutdown) throw new Error("agy driver is shut down.");
+		// No shutdown latch: pi fires session_shutdown on /new, /resume and
+		// /fork (not only process exit), so a closed driver must respawn on the
+		// next turn instead of rejecting forever. Parity with the ACP driver
+		// fix (regression 2026-09-07).
 		if (request.signal?.aborted) throw new Error("aborted before start");
 
 		const cause = this.#recycleCause(request);
@@ -588,7 +590,6 @@ export class AgyDriver implements TurnDriver {
 	}
 
 	async close(reason: "recycle" | "shutdown", cause?: string): Promise<void> {
-		if (reason === "shutdown") this.#shutdown = true;
 		const child = this.#child;
 		if (!child) {
 			this.#state = reason === "shutdown" ? "dead" : "idle";
@@ -602,7 +603,7 @@ export class AgyDriver implements TurnDriver {
 		this.#log(`close:${reason}${cause ? `:${cause}` : ""}`);
 		const turn = this.#active;
 		if (turn && !turn.closed) {
-			this.#failTurn(turn, `agy driver ${reason}ed mid-turn${cause ? ` (${cause})` : ""}`);
+			this.#failTurn(turn, `agy driver ${reason === "recycle" ? "recycled" : "shut down"} mid-turn${cause ? ` (${cause})` : ""}`);
 		}
 		this.#killChild();
 		this.#state = reason === "shutdown" ? "dead" : "idle";

package/src/engine-picker.ts

@@ -0,0 +1,155 @@
+// 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,
+// 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).
+//
+// UI: tui.md "Pattern 1" - SelectList framed by DynamicBorder inside pi's
+// native overlay (the window feel pi-rtk builds its modal on).
+
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import {
+	Container,
+	type SelectItem,
+	SelectList,
+	Spacer,
+	Text,
+} from "@earendil-works/pi-tui";
+import fs from "node:fs";
+import path from "node:path";
+import type { Engine } from "./config.js";
+
+/** Picker order is the default answer order: stream-json first. */
+export const ENGINE_PICKER_ITEMS: SelectItem[] = [
+	{
+		value: "stream-json",
+		label: "Stream-JSON CLI",
+		description: "default, recommended",
+	},
+	{
+		value: "acp",
+		label: "ACP server (official Google)",
+		description: "second sign-in, ~1.5 GB binary download",
+	},
+];
+
+/** Intro paragraph above the list. Text wraps, so explanations stay here and
+ *  SelectItem descriptions stay one-liners (SelectList truncates long lines). */
+export const ENGINE_PICKER_INTRO = [
+	"Pick the engine that runs your Antigravity turns. Switch anytime with /agy engine (restart applies it).",
+	"",
+	"stream-json: the `agy` CLI you already installed and authenticated. Persistent process, streamed output. Tested default.",
+	"ACP: 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).",
+].join("\n");
+
+/** True only for a genuine first interactive run: no saved config yet (any
+ *  existing file means the user has been here before) and no AGY_ENGINE env
+ *  (env wins over the file, so the wizard would fight it). Fails closed to
+ *  false - an fs error must never nag the user with a dialog. */
+export function shouldOfferEnginePicker(
+	configPath: string,
+	env: NodeJS.ProcessEnv = process.env,
+): boolean {
+	if (env.AGY_ENGINE !== undefined) return false;
+	try {
+		return !fs.existsSync(configPath);
+	} catch {
+		return false;
+	}
+}
+
+/** Narrow a picker value to an Engine. Items are our own constants, but an
+ *  unknown value must never reach config as a cast string: it falls back to
+ *  the tested default. */
+export function toEngine(value: string): Engine {
+	return value === "acp" ? "acp" : "stream-json";
+}
+
+/** 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. */
+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: stream-json. Restart pi to apply.";
+}
+
+/** 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("/")) {
+		try {
+			return fs.statSync(binRef).isFile();
+		} catch {
+			return false;
+		}
+	}
+	return (env.PATH ?? "")
+		.split(path.delimiter)
+		.filter(Boolean)
+		.some((dir) => {
+			try {
+				return fs.statSync(path.join(dir, binRef)).isFile();
+			} catch {
+				return false;
+			}
+		});
+}
+
+/** Toast copy for the missing-CLI warning. Fires every pi start while the
+ *  stream-json engine is active and the binary is absent. */
+export function agyMissingMessage(): string {
+	return "The `agy` CLI is not installed. Install it from https://antigravity.google/product/antigravity-cli and log in on it to use Antigravity models.";
+}
+
+/** Render the picker overlay. Resolves with the chosen engine, or null when
+ *  the user pressed esc (decide later - nothing is persisted). */
+export async function showEnginePicker(ctx: ExtensionUIContext): Promise<Engine | null> {
+	return ctx.custom<Engine | null>(
+		(tui, theme, _keybindings, done) => {
+			const container = new Container();
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+			container.addChild(
+				new Text(theme.fg("accent", theme.bold("Antigravity Bridge: choose your engine")), 1, 0),
+			);
+			container.addChild(new Text(theme.fg("muted", ENGINE_PICKER_INTRO), 1, 0));
+			container.addChild(new Spacer(1));
+
+			const list = new SelectList(ENGINE_PICKER_ITEMS, ENGINE_PICKER_ITEMS.length, {
+				selectedPrefix: (t: string) => theme.fg("accent", t),
+				selectedText: (t: string) => theme.fg("accent", t),
+				description: (t: string) => theme.fg("muted", t),
+				scrollInfo: (t: string) => theme.fg("dim", t),
+				noMatch: (t: string) => theme.fg("warning", t),
+			});
+			list.onSelect = (item) => done(toEngine(item.value));
+			list.onCancel = () => done(null);
+			container.addChild(list);
+
+			container.addChild(new Spacer(1));
+			container.addChild(
+				new Text(theme.fg("dim", "↑↓ navigate · enter select · esc decide later"), 1, 0),
+			);
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+			return {
+				render: (width: number) => container.render(width),
+				invalidate: () => container.invalidate(),
+				handleInput: (data: string) => {
+					list.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		},
+		{
+			overlay: true,
+			overlayOptions: { anchor: "center" as const, width: 80, maxHeight: "85%" as const, margin: 1 },
+		},
+	);
+}