@estebanforge/pi-antigravity-bridge 1.4.6 → 1.4.7

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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

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.
 
@@ -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)
@@ -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,9 +148,41 @@ 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;
@@ -190,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.
@@ -204,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({
@@ -216,6 +271,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		replay,
 		nativeActive,
 		engine,
+		log: fileLog.log.bind(fileLog),
 	});
 
 	pi.registerProvider("antigravity", {
@@ -246,6 +302,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		engine,
 		getMcpPort: () => mcpHandle?.port ?? null,
 		acpLog,
+		fileLog,
 		authCapture: authCapture ?? null,
 	});
 
@@ -258,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
@@ -309,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 } });
@@ -332,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");
@@ -449,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;
@@ -502,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") {
@@ -548,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;
@@ -576,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;
@@ -595,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 {
@@ -665,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.6",
+  "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/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

@@ -329,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. */
@@ -540,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
@@ -740,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;
 		}
@@ -750,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;
 		}
@@ -792,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;
 		}
@@ -860,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;
 		}
@@ -874,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;