@estebanforge/pi-antigravity-bridge 1.4.5 → 1.4.7

package/CHANGELOG.md

@@ -2,11 +2,42 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.4.7] - 2026-09-05
+
+### Added
+
+- Daily debug log on disk, sorted by day: `~/.pi/extensions-data/estebanforge/pi-antigravity-bridge/logs/<YYYY-MM-DD>.ndjson`, one JSON record per line, 14-day retention. Built for support: when something breaks, the last days' files replay the failure (engine, session, bridge call, error) without reproducing it. Both engines and everything around them feed it: turn start/outcome with error text, driver failures (stall, abort, timeout, nonzero exit), ACP session load/new and connection exits, bridge tool calls and round-trip failures, AskAntigravity runs, `/agy` commands, ACP setup/self-heal/auth, and the login URL (query string stripped). Secret-shaped values (tokens, API keys, credentials, header blocks) are redacted; prompt text, tool arguments, and tool output never land in the log; an unwritable directory is skipped silently and retried. `/agy doctor` prints the directory.
+- Two verbosity tiers keep the disk cost negligible: by default only the info/warn/error skeleton is written (a handful of records per turn). `AGY_DEBUG=1` (or `true`/`on`) restores the full per-event trail: spawn/exit, session load/new, unparks, recycle causes, raw bridge chatter. Turn it on to reproduce, then off.
+- Pre-dispatch turn errors now reach the log (previously they only surfaced as a one-line pi error and were lost): driver start failures, stray tool results with no active turn, the ACP plan-mode refusal, and a miswired extension.
+- The engine capabilities comparison table in the README: 20 rows comparing `stream-json` vs `acp` (thinking text, token usage, image/audio input, plan mode, slash-command handling, model/effort switching, process lifecycle, session resume, abort, bridge routing, edit diffs, permissions, digest and system-prompt delivery, auth, wire protocol, doctor diagnostics), peer-reviewed against the code and the live probes.
+
+### Changed
+
+- `/agy doctor` prints the log directory with a hint to attach recent days' files when reporting issues.
+- README, architecture module map, and the regression-test list document the logger, its support flow, and the `AGY_DEBUG` gate.
+
+## [1.4.6] - 2026-09-04
+
+### Added
+
+- Tool-priority note in the system prompt block (`systemPrompt` setting, on by default): agy runs embedded in pi, so its native interactive tools (the live example was `ask_question` vs the bridge's `ask_user_question`) never reach the user. The note tells agy to always prefer the Pi Bridge tool when one covers the same purpose. The old preamble sentence that allowed "your own tools or the pi tool bridge" is gone, since that ambiguity was the cause.
+
+### Fixed
+
+- `/agy auth` reports a distinct failure instead of a false "Signed in." when the server accepts the sign-in but `acp_token.json` never appears within the 5 s post-authenticate grace window (peer-review find; the poll result was never read).
+- Test-infra: the fake ACP server's request log was lost on SIGTERM (buffered write stream + Gate D teardown), which flaked the Gate D abort test ~1-in-3 suite runs; the log now appends synchronously.
+
+### Changed
+
+- The sign-in URL toast fences the URL with blank lines so it stays readable and copyable next to the ssh port-forward hint.
+
 ## [1.4.5] - 2026-09-04
 
 ### Added
 
-- `/agy auth` subcommand: runs the antigravity-acp sign-in on demand (spawns the server, sends `authenticate`, waits for the browser round-trip to complete; minutes-scale). Signing in no longer rides the first Antigravity message, and both login-pending moments now point at `/agy auth`. The sign-in URL toast (and its ssh port-forward hint) fires during `/agy auth` exactly as it does during turns. After the authenticate reply the run waits up to 5 s for `acp_token.json` before killing the sign-in server, and a second concurrent `/agy auth` fails fast instead of racing the token write.
+- Tool-priority note in the system prompt block (`systemPrompt` setting, on by default): agy runs embedded in pi, so its native interactive tools (the live example was `ask_question` vs the bridge's `ask_user_question`) never reach the user. The note tells agy to always prefer the Pi Bridge tool when one covers the same purpose. The old preamble sentence that allowed "your own tools or the pi tool bridge" is gone, since that ambiguity was the cause.
+
+- `/agy auth` subcommand: runs the antigravity-acp sign-in on demand (spawns the server, sends `authenticate`, waits for the browser round-trip to complete; minutes-scale). Signing in no longer rides the first Antigravity message, and both login-pending moments now point at `/agy auth`. The sign-in URL toast (and its ssh port-forward hint) fires during `/agy auth` exactly as it does during turns, and a second concurrent `/agy auth` fails fast instead of racing the token write.
 
 ### Changed
 

package/README.md

@@ -23,7 +23,30 @@ Turns run through one of two engines behind the same provider surface (`config.e
 - **stream-json** (default): the persistent `agy` CLI process. The tested default; live token usage; conversation resume via `--conversation`.
 - **acp**: Google's official ACP server (`agy_acp_server.par`), JSON-RPC 2.0 over stdio. Opt-in while it matures: the current build (RC01) ships no usage fields (token display shows zero) and no cancel (abort tears the server down and reloads it next turn). Everything else is parity-verified live - text streaming, multi-turn resume via `session/load`, bridge tools, effort switching, serialization, abort recovery - see `scripts/parity-live.mjs`.
 
-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.
+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. The `AskAntigravity` delegation tool is unaffected by `config.engine` and runs the `stream-json` CLI (`agy -p`) across both configurations.
+
+| Capability | `stream-json` (default) | `acp` |
+| --- | --- | --- |
+| Show thinking text | No (token count only, floor 64, no text body) | Yes (streams thought text via `agent_thought_chunk`; sparse on RC01 where reasoning often arrives in message text) |
+| Live token usage | Yes (live metrics from CLI step events) | No (absent in RC01, displays zero tokens) |
+| Image prompt input | No (CLI prompt is text-only; images dropped) | Yes (native image blocks forwarded to server) |
+| Audio prompt input | No (dropped) | Protocol advertised (`promptCapabilities.audio: true`) |
+| Review-only plan mode | Yes (`--mode plan` review-only via `/agy mode plan`) | No (RC01 modes are permission levels; plan mode refused) |
+| Leading slash commands in prompt | Disabled via `--disable-slash-commands` (sent as plain text) | Server intercepts recognized commands (e.g. `/plan`) and executes them under the active policy |
+| Dynamic model / effort switch | Recycles process on model or effort change | Dynamic per-turn via `session/set_config_option` (no restart) |
+| Process lifecycle | 1 persistent `agy` process per provider; recycles on drift | 1 persistent server process hosting N sessions concurrently |
+| Session resume & persistence | Client-side map in `sessions.json` via `--conversation <id>` | Server-side session store via `session/load` and `session/new` |
+| Turn cancel / abort | Kills process group; in-flight turn terminates | Teardown, kill, and auto-reload on RC01 (-32601 fallback) |
+| MCP tool bridge routing | Injected filesystem config via `--add-dir` | Direct `mcpServers` param in `session/new` and `session/load` |
+| Tool execution & visibility | Native re-exec (read-only) + wrapper replay (mutating) | Server executes tools natively; events stream with content |
+| Inline file edit diffs | Sourced from git working tree in thinking block | Sourced from `tool_call content[]` or disk vs git HEAD |
+| Permission handling | `--dangerously-skip-permissions` (unattended CLI requirement) | Protocol-native `session/request_permission` (auto-approve when `skipPermissions` is on; auto-deny when off) |
+| Context digest delivery (G1) | Prepend plain text inline in prompt | Native `embeddedContext` resource block |
+| System prompt delivery (G10) | Prepend to first prompt of conversation | Prepend to first prompt of conversation |
+| Authentication methods | Inherits existing `agy` CLI OAuth state | 4 methods: `oauth-personal`, `oauth-business`, `gemini-api-key`, `agent-platform` |
+| Wire protocol | Undocumented CLI NDJSON stream format | Versioned JSON-RPC 2.0 over stdio (`protocolVersion: 1`) |
+| Diagnostics (`/agy doctor`) | Child PID, state, process spawns, recycles, queue stats | Server version, agentInfo, session counts, reconnect count, cancel support |
+| Integration channel | Spawns internal CLI stream-json dialect | Official Google first-party ACP server binary |
 
 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: the same account and plan you use for the Antigravity CLI (`agy`). Sign in explicitly with `/agy auth` (engine `acp` selected): it opens the Google login in your browser and completes when you finish it. 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 auth-manual`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.
 
@@ -107,7 +130,7 @@ If `agy models` fails at load (binary missing, auth not done, network stall), a
 | `askTool` | `on` (register the AskAntigravity delegation tool), `off` (no delegation tool; provider and models only) | `on` |
 | `bridgeTools` | `none` (bridge off), `all` (every non-builtin tool, incl. other `Ask*` delegations), `mcp` (pi-mcp-adapter tools + skills bridge only) | `all` |
 | `digest` | `off` (stable prompts; agy's prompt cache hits) or `on` (inject a delta of pi-side context - compaction summaries, other-provider turns - into each agy prompt; the delta changes every turn, so agy re-bills the full context). Enable for mixed-provider sessions where agy must see pi-side context | `off` |
-| `systemPrompt` | `on` (prepend pi's system prompt - operating instructions plus the global agent-dir `AGENTS.md` and ancestor `AGENTS.md`/`CLAUDE.md` - to the first prompt of each new agy conversation) or `off` (agy-native behavior) | `on` |
+| `systemPrompt` | `on` (prepend pi's system prompt - operating instructions plus the global agent-dir `AGENTS.md` and ancestor `AGENTS.md`/`CLAUDE.md` - to the first prompt of each new agy conversation, plus a tool-priority note: Pi Bridge tools win over agy's native interactive ones, which never reach the user) or `off` (agy-native behavior) | `on` |
 
 Env overrides: `AGY_BRIDGE_TOOLS`, `AGY_ASK_TOOL`, `AGY_DIGEST`, `AGY_SYSTEM_PROMPT`. Env wins over the file, so while `AGY_DIGEST` or `AGY_SYSTEM_PROMPT` is set, the matching `/agy digest` or `/agy system-prompt` toggle persists a value that never takes effect.
 
@@ -120,7 +143,7 @@ The `activate_skill` catalog mirrors pi's directory-based skill discovery: the t
 ```
 /agy                      status, or open the full settings picker (TUI)
 /agy status               print current settings + session counts
-/agy doctor               bridge state, driver counters, bridge port, last lifecycle events
+/agy doctor               bridge state, driver counters, bridge port, last lifecycle events, log dir
 /agy auth                 run the antigravity-acp sign-in now (engine acp): opens the Google login in your browser, shows the URL when no browser opens
 /agy mode plan            review-only: agy plans but writes nothing
 /agy mode accept-edits    agy applies edits directly (default)
@@ -129,7 +152,7 @@ The `activate_skill` catalog mirrors pi's directory-based skill discovery: the t
 /agy model flash|pro|gemini   fallback model for the AskAntigravity tool; callers may override per call
 /agy thinking low|medium|high fallback thinking tier for the AskAntigravity tool; callers may override per call
 /agy digest on|off        inject pi-side context into agy prompts (default off; see table above)
-/agy system-prompt on|off send pi's system prompt + AGENTS.md to new agy conversations (default on)
+/agy system-prompt on|off send pi's system prompt + AGENTS.md + the Pi Bridge tool-priority note to new agy conversations (default on)
 /agy bridge all|mcp|none  which pi tools the MCP bridge exposes to agy (default all; none = bridge off)
 /agy acp-bin <path|auto>  point the ACP engine at a specific server binary (auto = setup installs, or AGY_ACP_BIN; applies on the next ACP turn)
 /agy engine acp|stream-json   switch the turn engine (restart to apply; default stream-json; acp runs self-service setup: binary install + auth bootstrap)
@@ -163,6 +186,26 @@ For isolation when running any agent that executes commands without a confirmati
 | `AGY_SKIP_PERMISSIONS` | `1`/`true` (default) to pass `--dangerously-skip-permissions` so commands don't hang on an unanswerable prompt in `-p` mode. `0`/`false` to prompt (hangs any `run_command` non-interactively). Wins over the config file. |
 | `AGY_DEFAULT_MODEL` | Default model alias for the `AskAntigravity` tool (`flash`/`pro`/`gemini`, or a tier/version qualifier). Wins over the config file. |
 | `AGY_DEFAULT_THINKING` | Default thinking tier for the `AskAntigravity` tool: `low`/`medium`/`high`. Anything else falls back to `medium`. Wins over the config file. |
+| `AGY_DEBUG` | `1`/`true`/`on` writes verbose debug records to the daily log (driver lifecycle, raw bridge traffic). Default off: only the light info/warn/error stream. |
+
+## Debug logs
+
+The extension keeps a daily log on your machine, sorted by day:
+
+```
+~/.pi/extensions-data/estebanforge/pi-antigravity-bridge/logs/<YYYY-MM-DD>.ndjson
+```
+
+One JSON record per line. Two verbosity tiers keep the disk cost negligible for regular users: by default only `info`/`warn`/`error` records land on disk, which is the useful skeleton: turn starts and outcomes with error text (both engines), bridge tool calls and round-trip failures, `AskAntigravity` runs, `/agy` commands, ACP setup/self-heal, auth URLs, and every driver failure (stall, abort, timeout, nonzero exit). Set `AGY_DEBUG=1` before reproducing a problem for the full trail: per-event driver lifecycle (spawn, exit, session load/new, unparks), list-tools traffic, recycle causes, and the raw bridge chatter. `/agy doctor` prints the log directory.
+
+Notes:
+
+- Retention: 14 days. Older files are pruned automatically.
+- Privacy: prompt text, tool arguments, and tool output never land in the log. Secret-shaped values (tokens, API keys, credentials, header blocks) are redacted, and long strings are truncated. The `auth-url` record strips the login URL's query string.
+- Logging never throws: an unwritable directory is skipped silently and retried on the next record.
+- SSD wear: default volume is a handful of records per turn. Verbose mode (`AGY_DEBUG=1`) writes more; turn it off after reproducing.
+
+When you report an issue, attach the last day or two of files from that directory. For anything that needs reproduction, run with `AGY_DEBUG=1` once and attach that day's file. They usually contain the exact failure sequence (engine, session, bridge call, error) with no need to guess.
 
 ## Development
 

package/docs/ARCHITECTURE.md

@@ -24,6 +24,7 @@ src/discovery.ts      conversation-id binding for the AskAntigravity one-shot to
 src/models.ts         agy models -> pi Model projection (full catalog, per-model effort)
 src/sessions.ts       atomic JSON store: pi session -> agy conversation + watermark
 src/config.ts         persisted runtime config (engine + acp block, bridgeTools, digest, mode, permissions, model/thinking defaults)
+src/daily-log.ts      daily NDJSON support log (one file per day, 14-day retention, secret redaction, AGY_DEBUG verbose gate); fed by both drivers, the bridge, round-trips, /agy, and ask-tool
 src/ask-tool.ts       the AskAntigravity one-shot delegation tool (model/thinking defaults)
 src/mcp-server.ts     MCP tool bridge server: ferries tools/list + tools/call; calls park in the provider round-trip
 src/diff-render.ts    stream-json: render agy's file edits as git diffs in pi's thinking stream; formatInlineDiff (no git) renders ACP's native diffs

package/docs/DEVELOPMENT.md

@@ -85,6 +85,7 @@ Most "stuck" reports trace to one of:
 - `tests/acp-events.test.ts` - ACP session/update mapping onto pi activities (text, thought, tool cards) and the session/load replay suppression.
 - `tests/acp-driver.test.ts` - the ACP driver over the fake server (`tests/helpers/fake-acp-server.mjs`, scenario-selected): happy flow, load-replay, permission auto-answer, Gate D abort (cancel probe, teardown, `cancelSupported` memory), the stale-exit race (a killed connection's late exit must not fail its replacement - `ACP_FAKE_SLOW_DEATH_MS`), auth errors, park/kickIdle timer pause with remaining budget.
 - `tests/acp-config.test.ts` - engine selection narrowing (`AGY_ENGINE`/`config.engine`), acp block parsing.
+- `tests/daily-log.test.ts` - the support log: day rotation, retention cutoff boundary, secret redaction (incl. header blocks), the 4 KB record cap, never-throw on a broken dir, and the two-tier gate (debug records dropped unless `AGY_DEBUG`).
 
 ## Module map
 

package/extensions/index.ts

@@ -43,8 +43,9 @@ import { AcpDriver } from "../src/acp/driver.js";
 import { runAcpAuth } from "../src/acp/auth.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";
+import type { TurnDriver, TurnOutcome } from "../src/driver-types.js";
+import { CONFIG_PATH, loadConfig, logsDir, saveConfig, type AgyMode, type BridgeTools, type Engine, type ThinkingTier } from "../src/config.js";
+import { createDailyLogger, type DailyLogger } from "../src/daily-log.js";
 import { registerAskAntigravityTool, toolModelsFromRaw } from "../src/ask-tool.js";
 import { startMcpServer, TOKEN_HEADER, type McpServerHandle } from "../src/mcp-server.js";
 import {
@@ -103,6 +104,17 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	const modelInput: Array<"text" | "image"> = engine === "acp" ? ["text", "image"] : ["text"];
 	const models = entries.map((e) => toPiModel(e, modelInput));
 
+	// Daily file log: every sink below feeds ~/.pi/extensions-data/
+	// estebanforge/pi-antigravity-bridge/logs/<YYYY-MM-DD>.ndjson (see
+	// src/daily-log.ts). Fire-and-forget, secrets redacted, old days pruned.
+	// Support flow: "attach the last days' files from that dir".
+	const fileLog = createDailyLogger({ dir: logsDir() });
+	fileLog.log(
+		"extension-load",
+		{ engine, models: models.length, fallback: usingFallback, bridge: loadConfig().bridgeTools, askTool: loadConfig().askTool },
+		"info",
+	);
+
 	const store = new SessionStore();
 	// MCP bridge handle, declared early: the ACP engine reads the bridge port
 	// at session/new / session/load time.
@@ -136,14 +148,55 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		"unsupported-server-request",
 	]);
 	const legacyDriver = new AgyDriver();
+	// Mirror the legacy driver's lifecycle ring into the daily file log
+	// (spawn/exit/abort/stall/recycle). The ACP driver reaches the same file
+	// through acpLog below.
+	legacyDriver.log = (msg, data) => {
+		// Level classification mirrors acpLog's failure set: stalls, aborts,
+		// timeouts and nonzero exits are the "what broke" greps (warn);
+		// turn-start is the per-turn skeleton (info); everything else is
+		// verbose-only (debug, needs AGY_DEBUG).
+		const failed =
+			msg.startsWith("timeout:") ||
+			msg.startsWith("stall:") ||
+			msg.startsWith("abort:") ||
+			(msg.startsWith("exit:") && msg !== "exit:0");
+		const level = failed ? "warn" : msg === "turn-start" ? "info" : "debug";
+		fileLog.log(msg, data, level);
+	};
 	// Shared ACP log sink (driver turns AND /agy auth): the login URL event
 	// toasts so SSH users can copy it; genuine failures reach stderr.
 	const acpLog = (msg: string, data?: unknown): void => {
+		// The daily file log gets EVERY driver event (auth-url stripped of its
+		// query string - it carries one-time login state); the filters below
+		// only decide what reaches the user.
+		const fileData =
+			msg === "auth-url"
+				? { port: (data as { port?: number | null } | undefined)?.port ?? null, url: String((data as { url?: string } | undefined)?.url ?? "").split("?")[0] }
+				: data;
+		// Failures warn; turn-start + auth-url are the always-on skeleton;
+		// routine per-event lifecycle (spawn, session-load, unparked, ...) is
+		// verbose-only.
+		const level = acpFailures.has(msg)
+			? "warn"
+			: msg === "turn-start" || msg === "auth-url"
+				? "info"
+				: "debug";
+		fileLog.log(msg, fileData, level);
 		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}`;
+			// Blank lines fence the URL off from the rest of the text: it is long
+			// and wraps, so separation keeps it readable and copyable.
+			const parts = ["Google sign-in URL for the ACP engine:", "", url];
+			if (port) {
+				parts.push(
+					"",
+					"SSH session? Forward the port on your machine first:",
+					`  ssh -N -L ${port}:127.0.0.1:${port} <user@host>`,
+				);
+			}
+			const text = parts.join("\n");
 			if (activeUi) activeUi.notify(text, "warning");
 			else console.error(`[antigravity-bridge acp] ${text}`);
 			return;
@@ -181,7 +234,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// The no-patch pi-tool round-trip store: the MCP bridge parks calls here;
 	// the provider emits them as real pi toolUse turns and completes them from
 	// the next call's toolResult.
-	const roundTrips = new ToolRoundTrips(activeDriver);
+	const roundTrips = new ToolRoundTrips(activeDriver, (s, d) => fileLog.log(s, d, s === "round-trip-fail" ? "warn" : "debug"));
 	const replay = new WrapperReplay();
 	// Native re-exec only emits for builtins actually active in the session;
 	// anything else (or an unknown name) falls back to the wrapper card.
@@ -195,7 +248,18 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	};
 	// A settled turn cannot answer its parked calls; the driver never sees
 	// ToolRoundTrips, so the provider bridges the two here (both engines).
-	const onTurnEnd = () => roundTrips.failAll("antigravity turn ended with an unresolved pi tool call");
+	// The file log records the outcome first: ERROR/aborted turns are the
+	// single most useful support signal.
+	const onTurnEnd = (outcome: TurnOutcome) => {
+		fileLog.log(
+			"turn-end",
+			// Error text can embed the child's stderr tail; cap it in line with
+			// the ACP driver's 200-char stderr slices.
+			{ status: outcome.status, error: outcome.error?.slice(0, 500), aborted: outcome.aborted },
+			outcome.status === "OK" ? "info" : "warn",
+		);
+		roundTrips.failAll("antigravity turn ended with an unresolved pi tool call");
+	};
 	legacyDriver.onTurnEnd = onTurnEnd;
 	acpDriver.onTurnEnd = onTurnEnd;
 	const streamSimple = createStreamSimple({
@@ -207,6 +271,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		replay,
 		nativeActive,
 		engine,
+		log: fileLog.log.bind(fileLog),
 	});
 
 	pi.registerProvider("antigravity", {
@@ -237,6 +302,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		engine,
 		getMcpPort: () => mcpHandle?.port ?? null,
 		acpLog,
+		fileLog,
 		authCapture: authCapture ?? null,
 	});
 
@@ -249,7 +315,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// Note: the active flag below is set regardless of askTool, so
 	// pi-ask-antigravity keeps deferring even then: off means NO delegation
 	// tool from either package, not a fallback to pi-ask-antigravity.
-	if (loadConfig().askTool) await registerAskAntigravityTool(pi, toolModels);
+	if (loadConfig().askTool) await registerAskAntigravityTool(pi, toolModels, fileLog.log.bind(fileLog));
 
 	// Display-only wrapper tool: the provider emits mutating agy steps as
 	// toolCalls against it (never re-executed - execute() replays the output
@@ -300,6 +366,13 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		if (engine === "acp" && !acpSelfHealRan) {
 			acpSelfHealRan = true;
 			void ensureAcpReady({ configBin: loadConfig().acp.bin }).then((status) => {
+				fileLog.log(
+					"acp-self-heal",
+					status.ok
+						? { ok: true, binarySource: status.binarySource, needsLogin: status.needsLogin }
+						: { ok: false, error: status.error },
+					status.ok ? "info" : "warn",
+				);
 				if (status.ok) {
 					if (status.binarySource === "installed" || status.binarySource === "existing") {
 						saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
@@ -323,17 +396,28 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		// warning toast (ctx.ui.notify, ephemeral) or stderr when headless.
 		// Per-turn success events (list-tools / call-tool) stay silent.
 		const mcpLog = (s: string, d?: unknown) => {
+			const failures = new Set([
+				"http-error", "bridge-config-write-failed", "call-tool-fail",
+				"transport-error", "handleRequest-error", "request-error",
+				"request-handler-error", "unauthorized",
+			]);
+			// Daily file log gets every bridge event (call-tool/list-tools
+			// traffic included - it is how a parked round-trip is traced); the
+			// filters below only decide what reaches the user. Bridge calls
+			// start/end at info (one record per tool call, the fragile-path
+			// skeleton); list-tools and startup chatter stay verbose.
+			const level = failures.has(s)
+				? "warn"
+				: s === "call-tool" || s === "call-tool-ok"
+					? "info"
+					: "debug";
+			fileLog.log(s, d, level);
 			// Routine abort traffic: failAll fires on turn end / session shutdown
 			// and the bridge answers every parked call with an error. Not a fault.
 			if (s === "call-tool-fail") {
 				const detail = (d as { msg?: string } | undefined)?.msg ?? "";
 				if (detail.includes("unresolved pi tool call") || detail.includes("session shut down")) return;
 			}
-			const failures = new Set([
-				"http-error", "bridge-config-write-failed", "call-tool-fail",
-				"transport-error", "handleRequest-error", "request-error",
-				"request-handler-error", "unauthorized",
-			]);
 			if (!failures.has(s)) return;
 			const msg = `[antigravity-bridge mcp] ${s}${d !== undefined ? " " + JSON.stringify(d) : ""}`;
 			if (ctx.hasUI) ctx.ui.notify(msg, "warning");
@@ -440,6 +524,8 @@ interface AgyCommandCtx {
 	getMcpPort: () => number | null;
 	/** Shared ACP log sink (login URL surfacing + failure events). */
 	acpLog: (msg: string, data?: unknown) => void;
+	/** Daily file logger (src/daily-log.ts); command + doctor surfacing. */
+	fileLog: DailyLogger;
 	/** BROWSER-capture handles; null when unavailable (Windows, unwritable
 	 *  data dir). /agy auth passes them to the sign-in process. */
 	authCapture: { browserEnv: Record<string, string>; file: string } | null;
@@ -493,6 +579,7 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 			const mode = cmdCtx.mode;
 			const sub = (args ?? "").trim().split(/\s+/)[0]?.toLowerCase();
 			const val = (args ?? "").trim().split(/\s+/)[1]?.toLowerCase();
+			ctx.fileLog.log("agy-command", { args }, "info");
 
 			// Direct subcommands work everywhere (headless + TUI).
 			if (sub === "clear") {
@@ -539,6 +626,13 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 						configBin: loadConfig().acp.bin,
 						onProgress: (m) => ui?.notify(m, "info"),
 					});
+					ctx.fileLog.log(
+						"acp-setup",
+						status.ok
+							? { ok: true, binarySource: status.binarySource, needsLogin: status.needsLogin }
+							: { ok: false, error: status.error },
+						status.ok ? "info" : "warn",
+					);
 					if (!status.ok) {
 						ui?.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
 						return;
@@ -567,6 +661,13 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 				}
 				ui?.notify("Preparing the ACP server (binary + auth settings)…", "info");
 				const status = await ensureAcpReady({ configBin: loadConfig().acp.bin, onProgress: (m) => ui?.notify(m, "info") });
+				ctx.fileLog.log(
+					"acp-setup",
+					status.ok
+						? { ok: true, binarySource: status.binarySource, needsLogin: status.needsLogin }
+						: { ok: false, error: status.error },
+					status.ok ? "info" : "warn",
+				);
 				if (!status.ok) {
 					ui?.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
 					return;
@@ -586,6 +687,7 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 					authUrlFile: ctx.authCapture?.file,
 					log: ctx.acpLog,
 				});
+				ctx.fileLog.log("acp-auth", r.ok ? { ok: true } : { ok: false, error: r.error }, r.ok ? "info" : "warn");
 				if (r.ok) {
 					ui?.notify("Signed in. The ACP engine is ready; takes effect on the next pi start (or /reload).", "info");
 				} else {
@@ -656,6 +758,7 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 					`  sessions:      ${ctx.store.size} bound`,
 					`  models:        ${ctx.entries.length} ${ctx.usingFallback ? "FALLBACK (agy models failed)" : "discovered"}`,
 					`  config:        ${CONFIG_PATH}`,
+					`  logs:          ${logsDir()} (attach recent days' files when reporting issues)`,
 				];
 				if (snap.engine === "acp" && snap.acp) {
 					lines.push(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.4.5",
+  "version": "1.4.7",
   "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/auth.ts

@@ -18,10 +18,14 @@ export interface AcpAuthOptions {
 	cwd?: string;
 	extraEnv?: Record<string, string>;
 	authUrlFile?: string;
+	/** Directory holding acp_token.json. Default: ~/.gemini/antigravity-acp.
+	 *  Tests point this at a fixture dir; production callers use the default. */
+	tokenDir?: string;
 	/** The server is expected to have written acp_token.json by the time
 	 *  authenticate replies, but write-after-reply is unverified; after a
 	 *  successful reply the run polls for the token up to this long before
-	 *  SIGTERM, so a laggard write is never killed mid-flight. */
+	 *  SIGTERM, so a laggard write is never killed mid-flight. A token that
+	 *  never appears is a distinct failure, not silent success. */
 	tokenGraceMs?: number;
 	timeoutMs?: number;
 	log?: (msg: string, data?: unknown) => void;
@@ -53,7 +57,13 @@ export function runAcpAuth(opts: AcpAuthOptions): Promise<AcpAuthResult> {
 			await conn.start();
 			await conn.request("authenticate", { methodId: "oauth-personal" }, opts.timeoutMs ?? AUTH_TIMEOUT_MS);
 			const deadline = Date.now() + grace;
-			while (!hasAcpToken() && Date.now() < deadline) await sleep(200);
+			while (!hasAcpToken(opts.tokenDir) && Date.now() < deadline) await sleep(200);
+			if (!hasAcpToken(opts.tokenDir)) {
+				return {
+					ok: false,
+					error: `the server accepted the sign-in, but no token file appeared in ${opts.tokenDir ?? "~/.gemini/antigravity-acp"} within ${Math.round(grace / 1000)}s`,
+				};
+			}
 			return { ok: true };
 		} catch (err) {
 			return { ok: false, error: err instanceof Error ? err.message : String(err) };

package/src/acp/driver.ts

@@ -197,6 +197,14 @@ export class AcpDriver implements TurnDriver {
 		this.#active = turn;
 		this.#state = "running";
 		this.#stats.turns += 1;
+		this.#log("turn-start", {
+			model: request.model,
+			effort: request.effort,
+			mode: request.mode,
+			conversation: request.conversationId ?? null,
+			images: request.images?.length ?? 0,
+			contextBlock: request.contextBlock ? true : undefined,
+		});
 
 		// Abort wiring first: a kill during session setup must still settle the
 		// turn (Gate D teardown applies from the first request).

package/src/ask-tool.ts

@@ -266,6 +266,10 @@ const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
 export async function registerAskAntigravityTool(
 	pi: ExtensionAPI,
 	entries: ModelEntry[],
+	/** Daily file log sink (src/daily-log.ts). Records lifecycle, never
+	 *  prompt text. Level matches DailyLogger: debug is the AGY_DEBUG-only
+	 *  verbose tier; info/warn/error always land. */
+	log?: (event: string, data?: unknown, level?: "debug" | "info" | "warn" | "error") => void,
 ): Promise<void> {
 	pi.registerTool({
 		name: "AskAntigravity",
@@ -469,6 +473,11 @@ export async function registerAskAntigravityTool(
 				: finalPrompt;
 
 			const args: string[] = ["--add-dir", cwd];
+			log?.(
+				"ask-start",
+				{ model: resolved.model, thinking: resolved.effort ?? config.defaultThinking, mode, digest: useDigest, continue: isContinuation, timeoutMin },
+				"info",
+			);
 			const extra = extraArgs();
 			if (extra.length) args.push(...extra);
 			if (resolved.model) args.push("--model", resolved.model);
@@ -625,6 +634,11 @@ export async function registerAskAntigravityTool(
 				details.aborted = outcome.aborted;
 				details.timedOut = outcome.timedOut;
 				details.durationMs = Date.now() - start;
+				log?.(
+					"ask-end",
+					{ exitCode: outcome.exitCode, aborted: outcome.aborted, timedOut: outcome.timedOut, durationMs: details.durationMs, conversationId: details.conversationId },
+					outcome.exitCode !== 0 || outcome.aborted || outcome.timedOut ? "warn" : "info",
+				);
 
 				if (!isContinuation && !details.conversationId && snapshot) {
 					for (let attempt = 0; attempt < DISCOVERY_POLL_ATTEMPTS; attempt++) {
@@ -680,6 +694,7 @@ export async function registerAskAntigravityTool(
 				if (statusInterval) clearInterval(statusInterval);
 				details.durationMs = Date.now() - start;
 				const msg = err instanceof Error ? err.message : String(err);
+				log?.("ask-fail", { error: msg, durationMs: details.durationMs }, "error");
 				return { content: [{ type: "text", text: `failed to run agy: ${msg}` }], details };
 			}
 			finally {

package/src/config.ts

@@ -22,6 +22,21 @@ const CONFIG_PATH = path.join(
 	"config.json",
 );
 
+/** Daily debug logs land here, sorted by day, for post-mortems and user
+ *  support (see src/daily-log.ts). Same homedir convention as CONFIG_PATH;
+ *  lives under the scoped extensions-data convention shared with other
+ *  EstebanForge extensions. */
+export function logsDir(): string {
+	return path.join(
+		os.homedir(),
+		".pi",
+		"extensions-data",
+		"estebanforge",
+		"pi-antigravity-bridge",
+		"logs",
+	);
+}
+
 /** Which turn engine drives turns. "stream-json" is the tested default;
  *  "acp" is the official-server engine, opt-in (plan §9.5). */
 export type Engine = "stream-json" | "acp";

package/src/daily-log.ts

@@ -0,0 +1,182 @@
+// Daily NDJSON debug log for support and post-mortems.
+//
+// One file per local day: <dir>/YYYY-MM-DD.ndjson, one JSON record per line.
+// Everything the extension logs (driver lifecycle, bridge traffic, round
+// trips, turn outcomes, /agy commands) lands here so a broken session can be
+// replayed from disk instead of from a user's memory. Users attach the last
+// days' files when reporting issues.
+//
+// Hard rules (learned from the pi-token-cost-ledger writer):
+//   - Never throw, never await in the hot path. Logging must never disrupt
+//     a turn; a broken/unwritable dir is swallowed.
+//   - One appendFile per record: O_APPEND keeps single-line writes atomic,
+//     so two pi tabs sharing the dir stay line-consistent.
+//   - No secrets, no prompt content: values of secret-shaped keys are
+//     redacted and long strings are truncated before they reach disk.
+//   - Retention: files older than `retentionDays` are pruned once per
+//     process, so the dir cannot grow unbounded.
+//   - Two tiers, to keep SSD wear negligible for regular users: only
+//     info/warn/error records (failures, turn/tool boundaries, commands,
+//     setup) are written by default. Full verbose trails (per-event driver
+//     lifecycle, raw bridge traffic) require AGY_DEBUG=1.
+
+import { appendFile, mkdir, readdir, unlink } from "node:fs/promises";
+import path from "node:path";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface DailyLoggerOptions {
+	/** Target directory (created on first write). */
+	dir: string;
+	/** Files older than this many days are pruned once per process. Default 14. */
+	retentionDays?: number;
+	/** Verbose gate. When false (default), debug-level records are dropped:
+	 *  only info/warn/error land on disk, the light stream regular users
+	 *  keep. AGY_DEBUG=1 (or this option) restores the full trail. */
+	debug?: boolean;
+	/** Injectable clock for tests. */
+	now?: () => Date;
+}
+
+export interface DailyLogger {
+	log(event: string, data?: unknown, level?: LogLevel): void;
+	/** Resolves when every queued write settled (tests, shutdown). */
+	flush(): Promise<void>;
+	readonly dir: string;
+	/** Path of the file the next record lands in (doctor display). */
+	todayPath(): string;
+}
+
+/** Local-date key, lexicographically sortable: 2026-02-05. */
+function dayKey(d: Date): string {
+	const p = (n: number) => String(n).padStart(2, "0");
+	return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+const MAX_STRING = 2000;
+const MAX_DEPTH = 6;
+/** Cap for one serialized line: keeps the O_APPEND atomic-write guarantee
+ *  honest for PIPE_BUF-sized writes even when many capped fields combine. */
+const MAX_RECORD = 4000;
+// Key-name redaction. `headers` is included wholesale: MCP server configs
+// carry auth material under headers[] ({name, value} pairs) and the token
+// lives in `value`, which a name-only regex would miss.
+const SECRET_KEY = /token|secret|password|passphrase|authorization|api[-_]?key|cookie|headers/i;
+
+/** Redact secret-shaped values and cap runaway strings before disk. */
+function scrub(value: unknown, depth: number): unknown {
+	if (value === null || value === undefined) return value;
+	if (value instanceof Error) {
+		return { name: value.name, message: value.message, stack: scrub(value.stack, depth) };
+	}
+	if (typeof value === "string") {
+		return value.length > MAX_STRING ? value.slice(0, MAX_STRING) + "…(truncated)" : value;
+	}
+	if (typeof value === "number" || typeof value === "boolean") return value;
+	if (depth >= MAX_DEPTH) return "(depth limit)";
+	if (Array.isArray(value)) return value.slice(0, 50).map((v) => scrub(v, depth + 1));
+	if (typeof value === "object") {
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+			out[k] = SECRET_KEY.test(k) ? "[redacted]" : scrub(v, depth + 1);
+		}
+		return out;
+	}
+	return String(value);
+}
+
+/** Matches the truthy set used across the extension's env parsing. */
+function isEnvTruthy(v: string | undefined): boolean {
+	return v !== undefined && ["1", "true", "on"].includes(v.toLowerCase());
+}
+
+export function createDailyLogger(opts: DailyLoggerOptions): DailyLogger {
+	const dir = opts.dir;
+	const retentionDays = opts.retentionDays ?? 14;
+	const verbose = opts.debug ?? isEnvTruthy(process.env.AGY_DEBUG);
+	const now = opts.now ?? (() => new Date());
+	// Serialized write chain: keeps day-rotation (mkdir + prune) ordered
+	// ahead of the records that triggered it. Volume is lifecycle-events
+	// low, so chaining costs nothing.
+	let chain: Promise<void> = Promise.resolve();
+	let ensuredDay = "";
+	let pruned = false;
+
+	async function prune(): Promise<void> {
+		if (pruned) return;
+		pruned = true;
+		const cutoff = dayKey(new Date(now().getTime() - retentionDays * 86_400_000));
+		const names = await readdir(dir).catch(() => [] as string[]);
+		for (const name of names) {
+			if (!name.endsWith(".ndjson")) continue;
+			if (name.slice(0, 10) >= cutoff) continue;
+			await unlink(path.join(dir, name)).catch(() => {
+				/* in use or gone: keep the rest */
+			});
+		}
+	}
+
+	function write(level: LogLevel, event: string, data: unknown): void {
+		const d = now();
+		const day = dayKey(d);
+		// Build the line outside the chain but guarded: scrub()/stringify run
+		// synchronously in log(), and a throwing getter in a future caller's
+		// data must not break the never-throw contract.
+		let line: string;
+		try {
+			const record: Record<string, unknown> = {
+				ts: d.toISOString(),
+				level,
+				event,
+			};
+			if (data !== undefined) record.data = scrub(data, 0);
+			line = JSON.stringify(record);
+			if (line.length > MAX_RECORD) {
+				record.data = `(record exceeded ${MAX_RECORD} bytes; payload dropped)`;
+				line = JSON.stringify(record);
+			}
+			line += "\n";
+		} catch {
+			line = `${JSON.stringify({ ts: d.toISOString(), level, event, data: "(unserializable)" })}\n`;
+		}
+		// Single chained task per record: an append failure retries ONCE inside
+		// the same task (day gate reset -> recursive mkdir rebuild -> append
+		// again). flush() therefore always waits past the retry, and a
+		// persistent failure costs at most two fs attempts, never a loop.
+		chain = chain.then(async () => {
+			try {
+				if (ensuredDay !== day) {
+					await mkdir(dir, { recursive: true });
+					ensuredDay = day;
+					await prune();
+				}
+				await appendFile(path.join(dir, `${day}.ndjson`), line, "utf8");
+			} catch {
+				try {
+					ensuredDay = "";
+					await mkdir(dir, { recursive: true });
+					ensuredDay = day;
+					await appendFile(path.join(dir, `${day}.ndjson`), line, "utf8");
+				} catch {
+					/* swallow: an unwritable dir must not disrupt the chat */
+				}
+			}
+		});
+	}
+
+	return {
+		log(event, data, level = "debug") {
+			// Volume gate: debug is the verbose tier. Default installs write
+			// only info/warn/error so the disk cost stays negligible.
+			if (level === "debug" && !verbose) return;
+			write(level, event, data);
+		},
+		flush() {
+			return chain.catch(() => {});
+		},
+		dir,
+		todayPath() {
+			return path.join(dir, `${dayKey(now())}.ndjson`);
+		},
+	};
+}

package/src/driver.ts

@@ -137,6 +137,9 @@ export class AgyDriver implements TurnDriver {
 	// it ate large tool frames and could hide the result frame of a turn.
 	#stdoutBuf = "";
 	#lifecycle: string[] = [];
+	/** Optional external lifecycle sink (the extension's daily file log).
+	 *  Fire-and-forget: the ring buffer stays the source for /agy doctor. */
+	log?: (msg: string, data?: unknown) => void;
 	#onTurnEnd: ((outcome: TurnOutcome) => void) | undefined;
 	#stats = {
 		spawns: 0,
@@ -227,6 +230,13 @@ export class AgyDriver implements TurnDriver {
 		this.#active = turn;
 		this.#state = "running";
 		this.#stats.turns += 1;
+		this.#log("turn-start", {
+			model: request.model,
+			effort: request.effort,
+			mode: request.mode,
+			conversation: request.conversationId ?? null,
+			images: request.images?.length ?? 0,
+		});
 		this.#armTimers(turn);
 
 		const line = `${JSON.stringify({
@@ -628,8 +638,10 @@ export class AgyDriver implements TurnDriver {
 		}
 	}
 
-	#log(msg: string): void {
-		this.#lifecycle.push(`${nowIso()} ${msg}`);
+	#log(msg: string, data?: unknown): void {
+		const line = `${nowIso()} ${msg}${data !== undefined ? ` ${JSON.stringify(data)}` : ""}`;
+		this.#lifecycle.push(line);
 		if (this.#lifecycle.length > LIFECYCLE_LIMIT) this.#lifecycle.shift();
+		this.log?.(msg, data);
 	}
 }

package/src/provider.ts

@@ -108,10 +108,19 @@ const DIGEST_PREAMBLE =
 // afterwards, and agy's server-side prompt cache keeps hitting.
 
 export const SYSTEM_PROMPT_PREAMBLE =
-	"[The following is the system prompt of the pi session that spawned this conversation: operating instructions plus project context (AGENTS.md files). Apply it for this whole conversation. Tool guidance may reference pi-side tools; use your own tools or the pi tool bridge for those actions.]";
+	"[The following is the system prompt of the pi session that spawned this conversation: operating instructions plus project context (AGENTS.md files). Apply it for this whole conversation.]";
 
 export const SYSTEM_PROMPT_END = "[END SYSTEM PROMPT]";
 
+/** Brief tool-priority note appended inside every system prompt block: agy
+ *  runs embedded in pi, so its native interactive tools never reach the
+ *  user. Equivalent Pi Bridge tools must win. Concrete clash observed live:
+ *  agy picked its native ask_question over the bridge's ask_user_question
+ *  and the question never displayed. Rides the systemPrompt gate: the note
+ *  ships only when the system prompt ships. */
+export const TOOL_PRIORITY_NOTE =
+	"[Tool priority: this conversation runs inside pi, not as a standalone agy session; the user only sees what surfaces in pi. Native interactive tools, for example ask_question, never reach the user. When a Pi Bridge tool covers the same purpose, always use the Pi Bridge tool; for user questions use ask_user_question.]";
+
 /** Assemble the full agy prompt: system prompt block, pi-side digest, user
  *  prompt. Empty parts are dropped. Pure; exported for unit testing.
  *  Pass systemPrompt only on a fresh conversation (see runTurnDriver). */
@@ -122,7 +131,7 @@ export function buildFullPrompt(
 ): string {
 	const parts: string[] = [];
 	if (systemPrompt) {
-		parts.push(`${SYSTEM_PROMPT_PREAMBLE}\n\n${systemPrompt}\n\n${SYSTEM_PROMPT_END}`);
+		parts.push(`${SYSTEM_PROMPT_PREAMBLE}\n\n${systemPrompt}\n\n${TOOL_PRIORITY_NOTE}\n\n${SYSTEM_PROMPT_END}`);
 	}
 	if (digest) {
 		parts.push(`${DIGEST_PREAMBLE}\n\n${digest}`);
@@ -320,6 +329,9 @@ export interface StreamSimpleDeps {
 	 *  read decides (tests); production wiring always passes it so a
 	 *  mid-session config flip cannot move one side of a parked turn. */
 	engine?: "stream-json" | "acp";
+	/** Daily file log sink (src/daily-log.ts). Records pre-dispatch turn
+	 *  errors that never create a driver turn (and so never reach onTurnEnd). */
+	log?: (event: string, data?: unknown, level?: "debug" | "info" | "warn" | "error") => void;
 }
 
 /** pi thinking-effort order mirrors agy's, for clamping. */
@@ -531,6 +543,8 @@ export interface DriverDeps {
 	nativeActive?: (name: string) => boolean;
 	/** Active engine (config), for engine-scoped session keys. */
 	engine: "stream-json" | "acp";
+	/** Daily file log sink for pre-dispatch errors (see StreamSimpleDeps). */
+	log?: (event: string, data?: unknown, level?: "debug" | "info" | "warn" | "error") => void;
 }
 
 /** Map one DriverActivity onto the open pi stream. Returns "parked" when the
@@ -731,6 +745,7 @@ async function runTurnDriver(
 	if (isContinuation) {
 		const active = deps.driver.reentry();
 		if (!active) {
+			deps.log?.("turn-error", { reason: "tool-result-no-active-turn" }, "warn");
 			finalize(stream, blocks, "error", "tool result arrived but no antigravity turn is running");
 			return;
 		}
@@ -741,6 +756,7 @@ async function runTurnDriver(
 		// An image-only message (no text) is valid on the ACP engine; only fail
 		// when there is nothing at all to send.
 		if (!prompt && images.length === 0) {
+			deps.log?.("turn-error", { reason: "no-user-message" }, "debug");
 			finalize(stream, blocks, "error", "No user message to send to agy.");
 			return;
 		}
@@ -783,6 +799,7 @@ async function runTurnDriver(
 			});
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
+			deps.log?.("turn-error", { reason: "driver-start-failed", error: msg }, "error");
 			finalize(stream, blocks, "error", `agy failed to start: ${msg}`);
 			return;
 		}
@@ -851,6 +868,7 @@ export function createStreamSimple(
 		if (selected === deps.acpDriver && config.mode === "plan") {
 			const partial = newAssistant(model);
 			const blocks: BlockState = { partial, textIdx: null, thinkingIdx: null, started: false };
+			deps.log?.("turn-error", { reason: "acp-plan-refused" }, "warn");
 			finalize(stream, blocks, "error", "ACP engine has no plan mode. /agy mode accept-edits, or /agy engine stream-json.");
 			return stream;
 		}
@@ -865,12 +883,14 @@ export function createStreamSimple(
 				// and keying the session as @acp would store a legacy
 				// conversationId under the wrong engine scope.
 				engine: selected === deps.acpDriver ? "acp" : "stream-json",
+				log: deps.log,
 			});
 		} else {
 			// Miswired extension: no driver means no engine. Fail the turn visibly
 			// instead of silently producing an empty assistant message.
 			const partial = newAssistant(model);
 			const blocks: BlockState = { partial, textIdx: null, thinkingIdx: null, started: false };
+			deps.log?.("turn-error", { reason: "driver-not-configured" }, "warn");
 			finalize(stream, blocks, "error", "antigravity driver not configured");
 		}
 		return stream;