@estebanforge/pi-antigravity-bridge 1.4.3 → 1.4.4

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.4.4] - 2026-09-04
+
+### Added
+
+- The Google sign-in URL now surfaces in pi. The ACP server hands the OAuth URL only to the browser-open call (nothing on stdout/stderr, headless or not), so a `BROWSER` wrapper script records the URL and forwards to the real opener; the connection watches the record file and logs it as an `auth-url` event. The extension toasts it at warning level with the ssh port-forward command for the redirect port, so logins work from SSH sessions on remote machines; local users keep the automatic browser open and get the URL as a fallback. An existing `BROWSER` setting is chained, not replaced.
+
+### Fixed
+
+- ACP login pending was reported only at the moment setup wrote `settings.json`, so after the restart, with `settings.json` in place but the browser login never completed, every check went silent: no toast, no hint, while the first ACP message had no token to use. `needsLogin` now tracks the token file (stat only, never read): `oauth-personal` without `acp_token.json` is login-pending, so the switch-time toast, the picker, and the `session_start` self-heal keep saying so on every start until the login is done.
+
+### Changed
+
+- Engine switching is command-only now: `/agy engine stream-json|acp`. The bare-`/agy` settings picker no longer carries an Engine row (nor the post-save setup run), so the switch surface cannot be hit accidentally; `/agy engine acp` keeps the self-service setup (binary + auth) and the login warning. The picker's plan+acp (RC01) guard stays in a narrower form: the mode row alone can still produce `plan` while the engine is `acp`.
+- ACP login-pending messages rewritten for end users: what happens (the server opens the Google sign-in page in your browser on the first Antigravity message), when (after the restart or immediately, per moment), and which account (your Antigravity subscription, the same Google account as the `agy` CLI). No URL to open manually. All remaining moments (engine switch, session start) now toast at warning level so the pending action stands out.
+- The "Turn engine" wording became "Engine" in the README env table, the config comment, and the architecture doc heading; the picker row itself is gone (engine switching is command-only, see above).
+
 ## [1.4.3] - 2026-09-04
 
 ### Added

package/README.md

@@ -25,7 +25,7 @@ Turns run through one of two engines behind the same provider surface (`config.e
 
 Engine-dependent features: pi image attachments ride natively only on the ACP engine (the picker offers image attach automatically when `config.engine` is `acp`; the stream-json CLI prompt is text-only). With the optional G1 digest enabled, its delivery also differs: ACP ships it as a native `embeddedContext` resource block, stream-json prepends it to the prompt text.
 
-Switch with `/agy engine acp|stream-json` (takes effect on restart). Setup is automatic: switching to `acp` installs Google's official ACP server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) (`~/.local/opt/agy-acp/<build>/` + a `current` symlink, zip sha256 recorded; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](docs/ACP-ADOPTION-PLAN.md)) and prepares the login. The login is your Antigravity subscription: on your first ACP message the server opens the Google login in your browser, and you sign in with the same account and plan you use for the Antigravity CLI (`agy`). It is no different from logging into the CLI; the server just keeps its own token file on your machine, like any Google tool, and this extension never sees your credentials. If you also export `GEMINI_API_KEY`, it is ignored: the server uses the auth type in settings.json, and setup always writes `oauth-personal`. A session start self-heals the same way, silently when everything is ready. Manual instructions (`/agy acp-auth`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.
+Switch with `/agy engine acp|stream-json` (takes effect on restart). Setup is automatic: switching to `acp` installs Google's official ACP server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) (`~/.local/opt/agy-acp/<build>/` + a `current` symlink, zip sha256 recorded; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](docs/ACP-ADOPTION-PLAN.md)) and prepares the login. The login is your Antigravity subscription: on your first ACP message the server opens the Google login in your browser, and you sign in with the same account and plan you use for the Antigravity CLI (`agy`). If no browser is available (an SSH session on a remote machine), pi shows the sign-in URL to copy, plus the ssh port-forward command for the login redirect. It is no different from logging into the CLI; the server just keeps its own token file on your machine, like any Google tool, and this extension never sees your credentials. If you also export `GEMINI_API_KEY`, it is ignored: the server uses the auth type in settings.json, and setup always writes `oauth-personal`. A session start self-heals the same way, silently when everything is ready. Manual instructions (`/agy acp-auth`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.
 
 ## What it cannot do
 
@@ -154,7 +154,7 @@ For isolation when running any agent that executes commands without a confirmati
 | Variable | Purpose |
 | --- | --- |
 | `AGY_BIN` | Path to the agy binary. Defaults to `agy` on PATH. |
-| `AGY_ENGINE` | Turn engine: `stream-json` (default) or `acp`. Wins over the config file. |
+| `AGY_ENGINE` | Engine: `stream-json` (default) or `acp`. Wins over the config file. |
 | `AGY_ACP_BIN` | Path to the ACP server binary (`agy_acp_server.par`). Defaults to `agy_acp_server.par` on PATH. Wins over `config.acp.bin`. When neither points at a binary, auto-setup installs one. |
 | `AGY_EXTRA_ARGS` | Extra args appended to every invocation. Whitespace-split. |
 | `AGY_CONVERSATIONS_DIR` | Override the conversations DB directory. |

package/docs/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 How the provider works internally. For build/test/debug workflow see [DEVELOPMENT.md](./DEVELOPMENT.md).
 
-## Turn engine
+## Engine
 
 The provider ships two turn engines behind one contract (`TurnDriver`,
 `src/driver-types.ts`): the default **stream-json engine** (below) and the

package/extensions/index.ts

@@ -40,6 +40,7 @@ import { SessionStore } from "../src/sessions.js";
 import { ToolRoundTrips, WrapperReplay, createStreamSimple } from "../src/provider.js";
 import { AgyDriver } from "../src/driver.js";
 import { AcpDriver } from "../src/acp/driver.js";
+import { setupAuthUrlCapture } from "../src/acp/browser-capture.js";
 import { ensureAcpReady, inspectAcpSetup } from "../src/acp/setup.js";
 import type { TurnDriver } from "../src/driver-types.js";
 import { CONFIG_PATH, loadConfig, saveConfig, type AgyMode, type BridgeTools, type Engine, type ThinkingTier } from "../src/config.js";
@@ -58,6 +59,12 @@ import { mapAgyToolToNative } from "../src/native-tools.js";
 import { Type } from "typebox";
 import { patchStatus, restorePatch } from "../src/patch-cleanup.js";
 
+// Last UI seen (session_start / /agy commands). The ACP login URL arrives
+// via the driver log sink, which has no command context; the stash lets that
+// sink toast instead of only logging to stderr. Module scope: both the
+// default export (session_start, log sink) and registerAgyCommand assign it.
+let activeUi: ExtensionUIContext | null = null;
+
 function resolveAgyBinary(): string {
 	return process.env.AGY_BIN || "agy";
 }
@@ -102,6 +109,17 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// ACP self-heal runs once per process (session_start re-fires on /reload;
 	// a ready setup is two file stats, so re-running is harmless anyway).
 	let acpSelfHealRan = false;
+	// OAuth URL capture: the server hands the login URL only to the
+	// browser-open call (nothing on stdio), so a BROWSER wrapper records it
+	// and the driver logs it as "auth-url". Local users keep the automatic
+	// browser open; over SSH the URL surfaces for copy-paste with the
+	// port-forward command.
+	const authCapture = setupAuthUrlCapture();
+	if (!authCapture && process.platform !== "win32") {
+		// Rare (unwritable data dir). Surfacing the diagnostic: without it,
+		// login URLs would silently stop appearing on headless boxes.
+		console.error("[antigravity-bridge] OAuth URL capture unavailable; login URL surfacing is off (setup failed).");
+	}
 	// Two turn engines behind one contract (plan §9): stream-json (tested
 	// default) and the official ACP server (opt-in via config.engine, off by
 	// default). Neither spawns anything until its first turn.
@@ -121,7 +139,17 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		// Resolved per connection: the setup flow can install the binary and
 		// update acp.bin mid-session; the next turn picks it up (no restart).
 		bin: () => loadConfig().acp.bin,
+		...(authCapture ? { extraEnv: authCapture.browserEnv, authUrlFile: authCapture.file } : {}),
 		log: (msg, data) => {
+			if (msg === "auth-url") {
+				const { url, port } = (data ?? {}) as { url?: string; port?: number | null };
+				if (!url) return;
+				const ssh = port ? `\nSSH session? Forward the port on your machine first:\n  ssh -N -L ${port}:127.0.0.1:${port} <user@host>` : "";
+				const text = `Google sign-in URL for the ACP engine:\n${url}${ssh}`;
+				if (activeUi) activeUi.notify(text, "warning");
+				else console.error(`[antigravity-bridge acp] ${text}`);
+				return;
+			}
 			if (!acpFailures.has(msg)) return;
 			console.error(`[antigravity-bridge acp] ${msg}${data !== undefined ? " " + JSON.stringify(data) : ""}`);
 		},
@@ -241,6 +269,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// normal toolUse loop (native cards, permissions, hooks) - no patch, no
 	// privileged API. Started on session_start, torn down on session_shutdown.
 	pi.on("session_start", async (_event, ctx) => {
+		if (ctx.hasUI) activeUi = ctx.ui;
 		// Legacy cleanup: users who ran the old consent-gated patcher still
 		// carry pi.invokeTool in their installed pi. Inert, but tell them once
 		// and offer /agy patch-cleanup. Never auto-edits the install.
@@ -270,8 +299,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 						saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
 					}
 					if (status.needsLogin) {
-						const msg = acpLoginPending("Your next antigravity message opens the browser;");
-						if (ctx.hasUI) ctx.ui.notify(msg, "info");
+						const msg = acpLoginPending("Your next Antigravity message opens the Google sign-in page in your browser.");
+						if (ctx.hasUI) ctx.ui.notify(msg, "warning");
 						else console.error(`[antigravity-bridge] ${msg}`);
 					}
 					return;
@@ -372,6 +401,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		}
 	});
 	pi.on("session_shutdown", async () => {
+		// The UI is going away; a later auth-url must fall back to stderr
+		// instead of toasting into a dead UI (where it would be lost).
+		activeUi = null;
 		const h = mcpHandle;
 		mcpHandle = null;
 		await h?.close();
@@ -384,11 +416,11 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 // --- /agy command -----------------------------------------------------------
 
 /** Shared body for every ACP-login-pending moment (session_start self-heal,
- *  /agy engine acp, picker): names the component so users know WHAT they are
- *  logging into, and that it is the same Google account as the agy CLI with
- *  its own token file. `browserTrigger` says when the browser opens. */
+ *  /agy engine acp, picker). End-user simple: what happens, when, which
+ *  account. The server opens the browser itself, so there is no URL to
+ *  open manually. `browserTrigger` says when that happens. */
 function acpLoginPending(browserTrigger: string): string {
-	return `One-time Google login pending for the antigravity-acp server, Google's own ACP binary and a separate component of the Antigravity suite (agy desktop, agy editor, agy cli, agy acp). ${browserTrigger} Sign in with your Antigravity subscription account: the same Google account as your agy CLI login, but its own login and token file. One-time; tokens stay on your machine and this extension never sees them.`;
+	return `One-time sign-in needed to finish ACP setup. ${browserTrigger} Use the Google account of your Antigravity subscription (the same account as your agy CLI login). If no browser opens, pi shows the sign-in URL to copy. The token stays on your machine; this extension never sees it.`;
 }
 
 interface AgyCommandCtx {
@@ -403,7 +435,6 @@ interface AgyCommandCtx {
 }
 
 interface PendingConfig {
-	engine?: Engine;
 	mode?: AgyMode;
 	skipPermissions?: boolean;
 	defaultModel?: string;
@@ -447,6 +478,7 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 			"Antigravity provider: status, doctor, settings picker, clear sessions. Usage: /agy [status|doctor|engine stream-json|acp|mode plan|accept-edits|permissions on|off|ask on|off|model <alias>|thinking low|medium|high|bridge all|mcp|none|digest on|off|system-prompt on|off|acp-bin <path|auto>|acp-auth|patch-cleanup|clear]",
 		handler: async (args, cmdCtx: ExtensionCommandContext) => {
 			const ui = cmdCtx.ui;
+			if (ui) activeUi = ui;
 			const mode = cmdCtx.mode;
 			const sub = (args ?? "").trim().split(/\s+/)[0]?.toLowerCase();
 			const val = (args ?? "").trim().split(/\s+/)[1]?.toLowerCase();
@@ -501,12 +533,14 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 						return;
 					}
 					saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
-					ui?.notify(
-						status.needsLogin
-							? `ACP engine ready. ${acpLoginPending("Your first ACP message (after the next pi start or /reload) opens the browser;")}`
-							: `ACP engine ready (auth: ${status.auth}). Takes effect on the next pi start (or /reload).`,
-						"info",
-					);
+					if (status.needsLogin) {
+						ui?.notify(
+							`ACP engine set. ${acpLoginPending("After the restart (pi restart or /reload), your first Antigravity message opens the Google sign-in page in your browser.")}`,
+							"warning",
+						);
+					} else {
+						ui?.notify(`ACP engine ready (auth: ${status.auth}). Takes effect on the next pi start (or /reload).`, "info");
+					}
 				} else {
 					ui?.notify(`current engine: ${loadConfig().engine}\nusage: /agy engine stream-json|acp`, "info");
 				}
@@ -547,8 +581,10 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 						"   the antigravity-acp registry; point acp.bin or AGY_ACP_BIN at it.",
 						'2. Default: put {"auth":{"type":"oauth-personal"}} in',
 						"   ~/.gemini/antigravity-acp/settings.json, run one turn, and complete the",
-						"   Google login that opens in your browser (headless: tunnel 127.0.0.1:<port>",
-						"   over ssh, then open the URL on your machine).",
+						"   Google login that opens in your browser. No browser (SSH session)?",
+						"   pi shows the sign-in URL to copy; forward the redirect port over ssh",
+						"   (ssh -N -L <port>:127.0.0.1:<port> <user@host>), then open the URL",
+						"   on your machine.",
 						'   Headless alternative: GEMINI_API_KEY + {"auth":{"type":"gemini-api-key"}}',
 						"   (metered paid API - not your Antigravity plan). The key is used only",
 						"   when that type is selected; with the default oauth-personal in place,",
@@ -711,23 +747,15 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 	});
 }
 
-/** Interactive settings picker (TUI only). Rows: the full runtime config
- *  surface (engine, mode, permissions, model, thinking, bridge, digest,
- *  system prompt). Picking acp runs the same self-service setup as
- *  `/agy engine acp` (binary + auth) right after the save. */
+/** Interactive settings picker (TUI only). Rows: the runtime config surface
+ *  (mode, permissions, model, thinking, bridge, digest, system prompt).
+ *  Engine switching is command-only: /agy engine stream-json|acp (the
+ *  command also runs self-service binary + auth setup for acp). */
 async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promise<void> {
 	const config = loadConfig();
 	const pending: PendingConfig = {};
 
 	const items: SettingItem[] = [
-		{
-			id: "engine",
-			label: "Turn engine",
-			description:
-				"stream-json: the streaming engine (default, supported). acp: Google's official ACP server (experimental, opt-in). Switch takes effect on the next pi start (or /reload); acp also runs binary + auth setup on save.",
-			currentValue: config.engine,
-			values: ["stream-json", "acp"],
-		},
 		{
 			id: "mode",
 			label: "Execution mode",
@@ -804,9 +832,7 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 			Math.min(items.length + 4, 15),
 			getSettingsListTheme(),
 			(id, newValue) => {
-				if (id === "engine") {
-					pending.engine = newValue as Engine;
-				} else if (id === "mode") {
+				if (id === "mode") {
 					pending.mode = newValue as AgyMode;
 				} else if (id === "permissions") {
 					pending.skipPermissions = newValue === "auto-approved";
@@ -840,16 +866,13 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 
 	if (Object.keys(pending).length === 0) return;
 
-	// The engine latches at load: a plan mode active while the effective
-	// engine is (or will be) acp would silently run non-plan. ACP has no
-	// review-only mode (RC01); refuse the combination. Both sides fall back
-	// to the on-disk config so a fresh engine pick over a saved plan (and
-	// vice versa) is caught too.
-	const nextEngine = pending.engine ?? ctx.engine;
+	// The picker cannot switch engines (command-only: /agy engine), but the
+	// mode row can still produce plan while the latched engine is acp. ACP
+	// has no review-only mode (RC01); refuse the combination.
 	const nextMode = pending.mode ?? config.mode;
-	if (nextMode === "plan" && nextEngine === "acp") {
+	if (nextMode === "plan" && ctx.engine === "acp") {
 		ui.notify(
-			"plan + acp is not supported (RC01): the ACP engine has no review-only mode. Save mode accept-edits or pick the stream-json engine first.",
+			"plan + acp is not supported (RC01): the ACP engine has no review-only mode. /agy engine stream-json first, or /agy mode accept-edits.",
 			"warning",
 		);
 		return;
@@ -858,7 +881,6 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 	try {
 		const next = saveConfig(pending);
 		const changed = [
-			pending.engine !== undefined ? `engine=${next.engine}` : null,
 			pending.mode ? `mode=${next.mode}` : null,
 			pending.skipPermissions !== undefined
 				? `permissions=${next.skipPermissions ? "auto-approved" : "prompt"}`
@@ -873,26 +895,6 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 			.filter(Boolean)
 			.join(", ");
 		ui.notify(`Saved: ${changed}`, "info");
-		if (pending.engine === "acp") {
-			// Same flow as /agy engine acp: persist the switch, then prepare
-			// the server so the restart just works.
-			ui.notify("Preparing the ACP server (binary + auth)…", "info");
-			const status = await ensureAcpReady({
-				configBin: loadConfig().acp.bin,
-				onProgress: (m) => ui.notify(m, "info"),
-			});
-			if (status.ok) {
-				saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
-				ui.notify(
-					status.needsLogin
-						? `ACP server ready. ${acpLoginPending("Your first ACP message (after the restart) opens the browser;")}`
-						: `ACP server ready (auth: ${status.auth}).`,
-					"info",
-				);
-			} else {
-				ui.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
-			}
-		}
 	} catch (err) {
 		ui.notify(
 			`Failed to save config: ${err instanceof Error ? err.message : String(err)}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "description": "Gemini provider for Pi on the Antigravity ACP server (official Google ACP) or the stream-json agy CLI. antigravity/* models in Pi's /model picker, no-patch MCP bridge: agy runs Pi's tools. ToS safe to use.",
   "keywords": [
     "pi-package",

package/src/acp/browser-capture.ts

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// The ACP server hands the Google OAuth URL ONLY to the browser-open call:
+// nothing on stdout or stderr, headless or not (verified per
+// docs/ACP-PROTOCOL-REFERENCE.md). The capture makes the URL visible:
+// BROWSER points at a wrapper that appends the URL to a record file and then
+// execs the real opener, and the connection watches the record file to log
+// "auth-url". Local users keep the automatic browser open; over SSH the user
+// copies the URL and forwards the redirect port.
+
+export interface AuthUrlCapture {
+	/** Spawn env for the ACP server (BROWSER -> wrapper script). */
+	browserEnv: Record<string, string>;
+	/** Record file the connection watches. */
+	file: string;
+	/** Most recent URL in the record file, or null. */
+	lastUrl(): string | null;
+}
+
+/** First existing executable named `name` on `env.PATH`, or null. */
+export function findOnPath(name: string, env: NodeJS.ProcessEnv = process.env): string | null {
+	for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+		if (!dir) continue;
+		const candidate = path.join(dir, name);
+		try {
+			const st = fs.statSync(candidate);
+			if (st.isFile() && (st.mode & 0o111) !== 0) return candidate;
+		} catch {
+			/* not here */
+		}
+	}
+	return null;
+}
+
+/** Last http(s) line of `file`, or null (absent/unreadable counts as empty). */
+export function readLastUrl(file: string): string | null {
+	try {
+		const lines = fs.readFileSync(file, "utf8").split("\n").filter((l) => /^https?:\/\//.test(l));
+		return lines.at(-1) ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/** Port of the OAuth loopback redirect (redirect_uri param), or null. */
+export function parseAuthPort(url: string): number | null {
+	try {
+		const redirect = new URL(url).searchParams.get("redirect_uri");
+		if (!redirect) return null;
+		const port = new URL(redirect).port;
+		return port ? Number(port) : null;
+	} catch {
+		return null;
+	}
+}
+
+const shQuote = (s: string): string => `'${s.replace(/'/g, "'\\''")}'`;
+
+/** Create the capture (record file + wrapper script) and return the spawn
+ *  env. Idempotent: the wrapper is rewritten only when content changes. The
+ *  opener to forward to is resolved once, at write time: an existing BROWSER
+ *  wins, then xdg-open, then macOS open; with none available the wrapper
+ *  records the URL and exits (headless: capture without an opener). The
+ *  forward word-splits the BROWSER value, so flag forms (`open -a Chrome`)
+ *  work; a BROWSER path containing spaces does not (rare, and BROWSER lists
+ *  are not honored either - the first entry is what chains). Windows browser
+ *  resolution differs; no capture there. */
+export function setupAuthUrlCapture(dataDir = path.join(os.homedir(), ".pi", "agent", "antigravity-bridge"), env: NodeJS.ProcessEnv = process.env): AuthUrlCapture | null {
+	if (process.platform === "win32") return null;
+	const file = path.join(dataDir, "acp-auth-urls.log");
+	const wrapper = path.join(dataDir, "acp-browser-wrapper.sh");
+	try {
+		fs.mkdirSync(dataDir, { recursive: true });
+		// Truncate: the file mirrors the current login attempt only. OAuth
+		// URLs carry state + PKCE challenges, so keep the record private.
+		fs.writeFileSync(file, "", { mode: 0o600 });
+		const opener = env.BROWSER?.trim() || findOnPath("xdg-open", env) || findOnPath("open", env) || "";
+		const body = [
+			"#!/usr/bin/env sh",
+			"# Antigravity bridge: records the Google OAuth URL the ACP server hands",
+			"# to the browser, then forwards to the real opener. The bridge watches",
+			"# the record file and shows the URL in pi (copy it when logging in over",
+			"# SSH; forward the redirect port first).",
+			`printf '%s\\n' "$@" >> ${shQuote(file)}`,
+			`REAL=${shQuote(opener)}`,
+			'if [ -n "$REAL" ]; then set -f; exec $REAL "$@"; fi',
+			"",
+		].join("\n");
+		const write = (p: string, content: string, mode: number): void => {
+			try {
+				if (fs.readFileSync(p, "utf8") === content) return;
+			} catch {
+				/* new file */
+			}
+			fs.writeFileSync(p, content, { mode });
+		};
+		write(wrapper, body, 0o755);
+		return { browserEnv: { BROWSER: wrapper }, file, lastUrl: () => readLastUrl(file) };
+	} catch {
+		return null; // capture is best effort; login still works without it
+	}
+}

package/src/acp/connection.ts

@@ -20,8 +20,10 @@
 //     LIST; a dead URL is accepted at session time (lazy connect)
 
 import { spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { parseAuthPort, readLastUrl } from "./browser-capture.js";
 import { JsonRpcResponseError, JsonRpcSession } from "./jsonrpc.js";
 
 export interface AcpMcpServer {
@@ -63,6 +65,11 @@ export interface AcpConnectionOptions {
 	 *  "auto" selects the first allow option; "deny" fail-closes to the first
 	 *  reject option. Absent = deny (fail closed). */
 	permissions?: () => "auto" | "deny";
+	/** Record file for BROWSER-captured OAuth URLs (src/acp/browser-capture.ts).
+	 *  The server hands the login URL only to the browser-open call, so the
+	 *  wrapper records it there; the connection watches the file and logs
+	 *  "auth-url" {url, port} for every new URL. */
+	authUrlFile?: string;
 }
 
 const INIT_TIMEOUT_MS = 30_000;
@@ -80,6 +87,8 @@ export class AcpConnection {
 	agentInfo: Record<string, unknown> | undefined;
 	/** Last known mode/model config echo from set_config_option results. */
 	lastConfigOptions: unknown = undefined;
+	#authUrlWatcher: fs.FSWatcher | undefined;
+	#lastAuthUrl: string | null = null;
 
 	constructor(opts: AcpConnectionOptions) {
 		this.#opts = opts;
@@ -117,6 +126,7 @@ export class AcpConnection {
 			...(this.#opts.extraEnv ? { env: { ...process.env, ...this.#opts.extraEnv } } : {}),
 		});
 		this.#child = child;
+		if (this.#opts.authUrlFile) this.#watchAuthUrl();
 		child.stdout?.setEncoding("utf8");
 		child.stderr?.setEncoding("utf8");
 		// Pipe failures arrive asynchronously as stream 'error' events; the sync
@@ -373,9 +383,36 @@ export class AcpConnection {
 		}
 	}
 
+	/** Surface OAuth login URLs captured by the BROWSER wrapper: every new
+	 *  URL in the record file is logged once as "auth-url" {url, port}. Best
+	 *  effort only - a broken watch never affects turns. */
+	#watchAuthUrl(): void {
+		const file = this.#opts.authUrlFile!;
+		try {
+			const watcher = fs.watch(file, () => this.#emitAuthUrl());
+			// Without a listener, a watch 'error' event escapes as uncaught.
+			watcher.on("error", () => {
+				/* record file gone: login URL surfacing is off until respawn */
+			});
+			this.#authUrlWatcher = watcher;
+		} catch {
+			/* no watch; the one-shot check below still covers earlier writes */
+		}
+		this.#emitAuthUrl(); // URLs recorded before the watch started
+	}
+
+	#emitAuthUrl(): void {
+		const url = readLastUrl(this.#opts.authUrlFile!);
+		if (!url || url === this.#lastAuthUrl) return;
+		this.#lastAuthUrl = url;
+		this.#opts.log("auth-url", { url, port: parseAuthPort(url) });
+	}
+
 	#finish(reason: string): void {
 		if (this.#exited) return;
 		this.#exited = true;
+		this.#authUrlWatcher?.close();
+		this.#authUrlWatcher = undefined;
 		this.abortAll(`connection exited: ${reason || "process gone"}`);
 		this.#opts.onExit({ code: null, signal: null, stderrTail: this.#stderrTail });
 	}

package/src/acp/driver.ts

@@ -41,6 +41,9 @@ export interface AcpDriverOptions {
 	/** Extra argv for the binary (tests: node + fake-server script). */
 	binArgs?: string[];
 	extraEnv?: Record<string, string>;
+	/** Record file for BROWSER-captured OAuth URLs; passed to the connection,
+	 *  which logs "auth-url" when the server tries to open a login. */
+	authUrlFile?: string;
 	/** Bridge registration for session/new AND session/load. */
 	mcpServers?: () => AcpMcpServer[];
 	log?: (msg: string, data?: unknown) => void;
@@ -422,6 +425,7 @@ export class AcpDriver implements TurnDriver {
 			bin: resolveAcpBinary(typeof this.#opts.bin === "function" ? this.#opts.bin() : this.#opts.bin),
 			binArgs: this.#opts.binArgs,
 			extraEnv: this.#opts.extraEnv,
+			authUrlFile: this.#opts.authUrlFile,
 			cwd: request.cwd,
 			mcpServers: this.#opts.mcpServers,
 			log: (msg, data) => this.#log(msg, data),

package/src/acp/setup.ts

@@ -227,6 +227,18 @@ export interface AuthState {
 	type?: string;
 }
 
+/** Token presence WITHOUT reading any credential value: acp_token.json is
+ *  stat()ed, never opened. The token only exists after the browser login
+ *  round-trip, so this is the real proof of a completed login. */
+function tokenPresent(target: string): boolean {
+	try {
+		fs.statSync(path.join(target, "acp_token.json"));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 /** Auth state WITHOUT reading any credential value: settings.json carries
  *  only auth.type (+ non-secret gcp placement), acp_token.json is stat()ed. */
 export function readAuthState(dir?: string): AuthState {
@@ -240,12 +252,7 @@ export function readAuthState(dir?: string): AuthState {
 	} catch {
 		/* absent or garbage = unconfigured */
 	}
-	try {
-		fs.statSync(path.join(target, "acp_token.json"));
-		return { configured: true, type: "token" };
-	} catch {
-		return { configured: false };
-	}
+	return tokenPresent(target) ? { configured: true, type: "token" } : { configured: false };
 }
 
 /** Write a minimal auth block into settings.json. The server reads this file
@@ -344,12 +351,18 @@ export async function ensureAcpReady(opts: SetupOptions = {}): Promise<AcpSetupS
 			};
 		}
 	}
+	// settings.json alone proves nothing: setup writes it before the login,
+	// the token file only appears after the browser round-trip. oauth-personal
+	// without a token = login still pending, and every caller (switch toast,
+	// session_start self-heal) must keep saying so until the token exists.
+	// gemini-api-key has no browser login; a present token file means done.
+	const needsLogin = auth.type !== "gemini-api-key" && !tokenPresent(gdir);
 	return {
 		ok: true,
 		bin: binary.bin!,
 		binarySource: binary.source!,
 		auth: auth.type ?? "token",
-		needsLogin: false,
+		needsLogin,
 		actions,
 	};
 }

package/src/config.ts

@@ -39,7 +39,7 @@ export interface AcpConfig {
 }
 
 export interface AgyConfig {
-	/** Turn engine. Switching requires a pi restart (drivers wire at load). */
+	/** Engine. Switching requires a pi restart (drivers wire at load). */
 	engine: Engine;
 	/** Official-server ACP engine options (used when engine = "acp"). */
 	acp: AcpConfig;