@estebanforge/pi-antigravity-bridge 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.4.1] - 2026-09-04
+
+### Added
+
+- Self-service ACP setup (`src/acp/setup.ts`): `/agy engine acp` now prepares the whole engine instead of printing instructions. It installs the official server binary from the antigravity-acp registry entry (`agentclientprotocol/registry`) into the pinned layout `~/.local/opt/agy-acp/<build>/` with a `current` symlink and the zip sha256 recorded (no upstream checksums exist; plan §12), points `acp.bin` at it, and prepares the login: `oauth-personal` by default, which is the user's own Antigravity subscription (the same Google account and plan as the `agy` CLI; the server opens the browser on the first ACP message, tokens persist). Credential values are never read or written (`acp_token.json` is only stat()ed); `gemini-api-key` stays a manual headless option, never the default. A `session_start` self-heal repeats the check silently when everything is ready and surfaces the manual steps only on failure; `AcpDriverOptions.bin` accepts a resolver so a mid-session install is picked up by the next turn without a restart; `/agy doctor` shows binary source and auth type. Tests inject the registry, archive, and unpacker, so the suite stays offline.
+
+### Fixed
+
+- Stream-json frames split across pipe chunks are now reassembled instead of dropped: `AgyDriver` buffers the trailing partial stdout line (the scheme `JsonRpcSession.feed` already used on the ACP engine). Previously a large `tool` frame or the `result` frame split by a pipe boundary was lost whole, which could turn a successful turn into a bogus "agy exited with status 0" error. Regression test drives a fake agy whose reply is deliberately split mid-line.
+- Both drivers attach an `'error'` listener on the child's stdin: an async pipe failure (EPIPE when agy/the ACP server dies mid-write) now fails the turn (ACP: tears the connection down) instead of escaping as an uncaught exception that kills the whole pi process.
+- ACP permission answering is fail-closed: `session/request_permission` selects the first reject option unless the turn runs with `skipPermissions`. Previously every request was auto-approved regardless of the `permissions` setting shown by `/agy status`. The unsupported `engine=acp` + `mode=plan` combination is now refused at `/agy engine`, `/agy mode`, and the settings picker, and fails the turn with a visible error instead of silently running non-plan (ACP has no review-only mode in RC01).
+- Startup-log fix hardening: four genuine ACP failure events (`session-load-failed-creating-fresh`, `connection-exited`, `cancel-failed`, `unsupported-server-request`) surface again; the dead MCP entries (`capability-missing`, `self-patch-error`) are gone; `call-tool-fail` no longer toasts for the routine fail-all on turn end / session shutdown.
+- Startup log leaks: the ACP driver log sink now forwards only genuine failures (`start-failed`, `spawn-error`, `parse-error`, `write-failed`, `mode-apply-failed`, `timeout`, `stall`, `auth-required`) to stderr; routine lifecycle (`driver-created`, spawn, session new/load) stays in the `#lifecycle` ring buffer under `/agy doctor`. The MCP bridge logger no longer toasts (or headless-stderr-logs) normal startup/teardown events (`listening`, `bridge-config-written`, `bridge-config-removed`, `closed`); only failures surface, as warning toasts. The stream-json engine already had no terminal sink.
+
 ## [1.4.0] - 2026-09-04
 
 ### Added

package/README.md

@@ -25,7 +25,7 @@ Turns run through one of two engines behind the same provider surface (`config.e
 
 Engine-dependent features: pi image attachments ride natively only on the ACP engine (the picker offers image attach automatically when `config.engine` is `acp`; the stream-json CLI prompt is text-only). With the optional G1 digest enabled, its delivery also differs: ACP ships it as a native `embeddedContext` resource block, stream-json prepends it to the prompt text.
 
-Switch with `/agy engine acp|stream-json` (takes effect on restart). ACP needs the server binary installed locally (`AGY_ACP_BIN` or `config.acp.bin`; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](docs/ACP-ADOPTION-PLAN.md)), and its own one-time credential setup: run `/agy acp-auth` for the steps. The ACP server keeps its own auth state; the token never touches this code. Sessions are engine-scoped, so switching engines never crosses conversations.
+Switch with `/agy engine acp|stream-json` (takes effect on restart). Setup is automatic: switching to `acp` installs Google's official ACP server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) (`~/.local/opt/agy-acp/<build>/` + a `current` symlink, zip sha256 recorded; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](docs/ACP-ADOPTION-PLAN.md)) and prepares the login. The login is your Antigravity subscription: on your first ACP message the server opens the Google login in your browser, and you sign in with the same account and plan you use for the Antigravity CLI (`agy`). It is no different from logging into the CLI; the server just keeps its own token file on your machine, like any Google tool, and this extension never sees your credentials. If you also export `GEMINI_API_KEY`, it is ignored: the server uses the auth type in settings.json, and setup always writes `oauth-personal`. A session start self-heals the same way, silently when everything is ready. Manual instructions (`/agy acp-auth`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.
 
 ## What it cannot do
 
@@ -125,8 +125,8 @@ Env overrides: `AGY_BRIDGE_TOOLS`, `AGY_DIGEST`, `AGY_SYSTEM_PROMPT`. Env wins o
 /agy thinking low|medium|high default thinking tier for the AskAntigravity tool
 /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 engine acp|stream-json   switch the turn engine (restart to apply; default stream-json)
-/agy acp-auth                 one-time credential setup for the ACP engine
+/agy engine acp|stream-json   switch the turn engine (restart to apply; default stream-json; acp runs self-service setup: binary install + auth bootstrap)
+/agy acp-auth                 manual ACP credential setup (fallback; auto-setup normally covers this; default login = your Antigravity subscription, same account as the agy CLI)
 /agy patch-cleanup        restore the original pi files if an older version patched them
 /agy clear                drop all session bindings (force fresh conversations)
 ```
@@ -149,7 +149,7 @@ For isolation when running any agent that executes commands without a confirmati
 | --- | --- |
 | `AGY_BIN` | Path to the agy binary. Defaults to `agy` on PATH. |
 | `AGY_ENGINE` | Turn engine: `stream-json` (default) or `acp`. Wins over the config file. |
-| `AGY_ACP_BIN` | Path to the ACP server binary (`agy_acp_server.par`). Defaults to `agy_acp_server.par` on PATH. Wins over `config.acp.bin`. |
+| `AGY_ACP_BIN` | Path to the ACP server binary (`agy_acp_server.par`). Defaults to `agy_acp_server.par` on PATH. Wins over `config.acp.bin`. When neither points at a binary, auto-setup installs one. |
 | `AGY_EXTRA_ARGS` | Extra args appended to every invocation. Whitespace-split. |
 | `AGY_CONVERSATIONS_DIR` | Override the conversations DB directory. |
 | `AGY_MODE` | Override execution mode: `plan` (review-only) or `accept-edits` (default). Wins over the config file. |

package/docs/ACP-ADOPTION-PLAN.md

@@ -6,7 +6,7 @@ PASS through the full stack. Gate F VERIFIED live (`scripts/smoke-acp-bridge.mjs
 the real server lists bridge tools and completes a tool call through the
 registered mcpServers entry. §6 parity run LIVE on both engines: 14/14
 (`scripts/parity-live.mjs`). Phase-1 acceptance: ALL `[x]` (docs included).
-Gates: A PASS, B ABSENT (managed — legacy engine retained
+Gates: A PASS, B ABSENT (managed — streaming engine retained
 until upstream ships usage), C PASS, D FAIL on RC01 (kill+reload fallback
 VERIFIED live, incl. the stale-exit race fix), E PASS, F PASS (verified
 live 2026-09-03). Verdicts in section 8.1; full captured protocol data in
@@ -20,7 +20,7 @@ Peer review 2: Antigravity (agy), 2026-09-03. Verdict PROCEED WITH CHANGES.
 7 findings integrated: Gate A made a blocking gate for the default flip (the
 ACP binary takes no model flags, so the recycle fallback could not carry a
 model), sessions re-keyed per engine (`@acp` suffix) after the engine-field
-design was shown to erase legacy bindings on rollback, parked-timer pause
+design was shown to erase streaming bindings on rollback, parked-timer pause
 changed to remaining-budget semantics, acp-permission plumbing specified
 through a TurnDriver interface, session/cancel + session/close pulled into
 phase 1, AskAntigravity migration moved from phase 3 to phase 4.
@@ -47,7 +47,7 @@ Adopt the official Google ACP server (`agy_acp_server.par`, registry id
 switch. The existing stream-json engine stays the default until the ACP
 engine proves parity. Every change is an improvement or a one-to-one
 replacement. No functionality is removed until a later phase deletes the
-legacy engine on purpose.
+streaming engine on purpose.
 
 Cross-references: [ARCHITECTURE.md](./ARCHITECTURE.md),
 [PI-BRIDGE-GAPS.md](./PI-BRIDGE-GAPS.md), [DEVELOPMENT.md](./DEVELOPMENT.md).
@@ -165,8 +165,8 @@ is an unmaintained contract. ACP is the maintained one.
 | Module | Role today | Disposition under ACP |
 | --- | --- | --- |
 | `src/provider.ts` | streamSimple: pi Context to agy turn to pi events; G9 round-trips; G1 digest; G10 system prompt | KEEP unchanged (additive thought-delta `if` only). Engine-agnostic by contract |
-| `src/driver.ts` | persistent stream-json process, turn queue, recycle, timers | KEEP as legacy engine. DELETE in phase 4 |
-| `src/stream-events.ts` | NDJSON parser + usage mapping | KEEP as legacy. DELETE in phase 4 |
+| `src/driver.ts` | persistent stream-json process, turn queue, recycle, timers | KEEP as streaming engine. DELETE in phase 4 |
+| `src/stream-events.ts` | NDJSON parser + usage mapping | KEEP as streaming. DELETE in phase 4 |
 | `src/sessions.ts` | pi session to agy conversation store | KEEP. Add `engine` tag (section 9.4) |
 | `src/config.ts` | runtime config | KEEP. Add engine + acp block (section 9.5) |
 | `src/models.ts` | `agy models` to pi Model projection | KEEP. Catalog source stays the CLI until ACP exposes one (probe A.6) |
@@ -256,10 +256,10 @@ Every box must be `[x]` on the ACP engine before phase 4 flips the default.
 Tested with the parity suite (section 11) and `scripts/parity-live.mjs`
 (live, both engines: 14/14, 2026-09-03).
 
-- [x] Text streams token-adjacent to legacy (no full-text re-sends) — live
+- [x] Text streams token-adjacent to streaming (no full-text re-sends) — live
       both engines, delta stream + cumulative-resend guard held
 - [x] Multi-turn conversation continuity via `session/load` or our store —
-      live: ACP `session/load` (history suppressed, clean reply), legacy
+      live: ACP `session/load` (history suppressed, clean reply), streaming
       `--conversation` resume; the provider's session store supplies the id
 - [x] Turn serialization: two concurrent streamSimple calls never interleave
       — live both engines (queue releases only on settle) + driver tests
@@ -276,23 +276,23 @@ Tested with the parity suite (section 11) and `scripts/parity-live.mjs`
 - [x] Abort: pi user abort produces `aborted`, the server process survives,
       the next turn on the session works — live both engines (aborted=true,
       recovery turn OK). "Process survives" holds on NEITHER engine and is
-      the documented Gate D behavior: legacy kills the child; RC01 has no
+      the documented Gate D behavior: streaming kills the child; RC01 has no
       cancel, ACP tears down after the -32601 probe and reloads next turn
 - [x] pi session restart resumes the right conversation (engine-tagged) —
       engine-scoped key tests + live `session/load`
 - [x] Engine rollback preserves the other engine's conversation bindings
       (engine-scoped keys, 9.4) — sessions tests (per-entry engine field
-      rejected precisely because set() would erase the legacy binding)
+      rejected precisely because set() would erase the streaming binding)
 - [x] Model catalog: same `antigravity/*` model ids and effort tiers resolve
       — shared provider catalog, engine-independent by construction
 - [x] Model/effort switch takes effect (gate A mechanism) — live: ACP
-      `set_config_option` on a LOADED session; legacy recycle+resume
+      `set_config_option` on a LOADED session; streaming recycle+resume
 - [x] G1 digest and G10 system prompt reach the prompt identically — shared
       prompt assembly in the provider; the driver receives the final prompt
 - [x] Skills `activate_skill` answered by the bridge as today — bridge
       server dep, same server serves both engines (ACP transport live)
 - [x] Usage counters: present (mapped) or documented-absent (zero-usage),
-      per gate B — live: legacy mapped, ACP absent (Gate B row in the
+      per gate B — live: streaming mapped, ACP absent (Gate B row in the
       parity matrix)
 - [x] `/agy doctor` shows connection state, session id, prompt/session stats,
       lifecycle log — implemented engine-aware (phase 1); re-verify in pi
@@ -303,7 +303,7 @@ Tested with the parity suite (section 11) and `scripts/parity-live.mjs`
       as a visible `ACP session failed: Invalid params` turn error in the
       first parity attempt, exactly as designed
 - [x] `ask-tool` one-shot returns text, duration, abort/timeout states, and a
-      resumable session id — unchanged legacy `agy -p` path (phase-2 probe
+      resumable session id — unchanged `agy -p` path (phase-2 probe
       decides whether it moves to ACP)
 - [x] Overall-turn timer pauses while any round-trip is parked; a slow human
       permission decision cannot kill the turn — fake tests (park/kickIdle
@@ -396,8 +396,8 @@ What to record for each gate:
 | A | Model + effort switch per session? | `set_config_option` (or equivalent) switches both; next prompt uses them | NONE viable: the ACP binary takes no model flags, so respawn-per-switch cannot carry a model; a settings.json rewrite per switch is the only theoretical path and is rejected (unproven, racy). Gate A FAIL blocks the phase 4 default flip; ACP stays opt-in; the gap goes upstream |
 | B | Usage anywhere? | Any update or `_meta` carries token counts | Zero-usage documented; README notes it |
 | C | `tool_call` content richness | rawInput/output/locations enough to retire WrapperReplay + native-tools | Keep current replay machinery unchanged |
-| D | Cancel latency + state | `stopReason: cancelled` within ~2s; session reusable after | Keep kill semantics on legacy; on ACP keep kill as escalation path |
-| E | Startup cost | Cold start < 5s, steady RSS sane for a long-lived process | Spawn per turn-group only (like legacy recycle cadence) |
+| D | Cancel latency + state | `stopReason: cancelled` within ~2s; session reusable after | Keep kill semantics on streaming; on ACP keep kill as escalation path |
+| E | Startup cost | Cold start < 5s, steady RSS sane for a long-lived process | Spawn per turn-group only (like the streaming recycle cadence) |
 | F | MCP `mcpServers` registration | Bridge `tools/list` visible to the agent mid-turn | Keep bridge wired some other protocol-sanctioned way; if none, G9 parking breaks and phase 1 is BLOCKED |
 | F.7 | Slash behavior | Commands not auto-expanded against our prompt text | Prefix-safe prompt assembly unchanged |
 
@@ -478,7 +478,7 @@ scripts/smoke-acp.mjs  live smoke, gated by AGY_ACP_LIVE=1 (spends quota),
 `AcpDriver` matches the existing `AgyDriver` public surface: `state`,
 `activeHandle`, `run()`, `reentry()`, `kickIdle()`, `set onTurnEnd()`,
 `snapshot()`, `close()`. `DriverActivity` gains one additive variant; the
-legacy engine never emits it:
+streaming engine never emits it:
 
 ```ts
 // stream-events/driver today:            { type: "thought"; tokens: number }
@@ -487,7 +487,7 @@ legacy engine never emits it:
 ```
 
 `provider.ts` change: when `delta` is present call `appendThinking`, else keep
-the current token-count behavior. One `if`, additive, legacy untouched.
+the current token-count behavior. One `if`, additive, streaming untouched.
 
 Interface extraction (review 2, finding 7): `provider.ts` imports the
 concrete `AgyDriver` class today; deleting `driver.ts` in phase 4 would break
@@ -504,7 +504,7 @@ correlation-map entry (the pending `session/prompt` request, any unanswered
 client-side requests), the driver settles the turn outcome as
 `ERROR`/`aborted` (never left pending), and `onTurnEnd` fires so the
 provider's `roundTrips.failAll()` fails parked round-trips exactly as the
-legacy driver's `failTurn` path does. Nothing is ever written to a dead
+streaming driver's `failTurn` path does. Nothing is ever written to a dead
 socket; no promise survives the kill. Mirrors `ToolRoundTrips.failAll()`.
 
 Event mapping (`src/acp/events.ts`):
@@ -524,7 +524,7 @@ Event mapping (`src/acp/events.ts`):
 | `refusal` / `max_turn_requests` / `max_tokens` | TurnOutcome ERROR / OK+note | `error` / `stop` + `errorMessage` |
 | `user_message_chunk` (during `session/load` only) | suppressed (history replay) | never emitted to pi as live text |
 
-Defensive guard ported from the legacy engine: if an `agent_message_chunk`
+Defensive guard ported from the streaming engine: if an `agent_message_chunk`
 repeats the full accumulated text instead of a delta, detect and slice (the
 `isCumulativeResend` lesson; same agy binary lineage, same quirk class).
 Guard plus test ship in phase 1. Honest labeling: the ACP spec defines chunks
@@ -575,24 +575,24 @@ parked and, on settle, re-arms it with the REMAINING budget (`deadline -
 now`), never a fresh cap: the overall timer is a turn DEADLINE, not an
 inactivity guard. Every park carries its own timeout (`BRIDGE_TIMEOUT_MS`),
 so a paused deadline cannot hang forever. Driver-local (AcpDriver only);
-legacy behavior untouched; ships in phase 1.
+streaming behavior untouched; ships in phase 1.
 
 ### 9.4 Sessions schema (engine-scoped keys)
 
 The first design (a per-entry `engine` field) was rejected in review 2:
 `set()` overwrites the single `sid:<pi-session>` key, so one ACP turn ERASES
-the legacy conversation binding, and a rollback loses continuity, breaking
+the streaming conversation binding, and a rollback loses continuity, breaking
 the section 13 guarantee. Engines scope at the KEY level instead:
 
 ```jsonc
 // ~/.pi/agent/antigravity-bridge/sessions.json
 {
-  "sid:<pi-session>":     { "conversationId": "<legacy id>", "lastStepIdx": -1, "lastMessageCount": 42 },
+  "sid:<pi-session>":     { "conversationId": "<streaming id>", "lastStepIdx": -1, "lastMessageCount": 42 },
   "sid:<pi-session>@acp": { "conversationId": "<ACP sessionId>", "lastStepIdx": -1, "lastMessageCount": 42 }
 }
 ```
 
-- Un-suffixed keys belong to the legacy engine, byte-compatible with every
+- Un-suffixed keys belong to the streaming engine, byte-compatible with every
   persisted store; ACP keys carry an `@acp` suffix appended by
   `sessionKey()` when `config.engine === "acp"`.
 - Engines never touch each other's keys: rollback keeps both continuations,
@@ -747,11 +747,11 @@ ACP-PROTOCOL-REFERENCE.md "Phase-2 probe findings".
 
 ### Phase 3: consolidation (immediate priority, opt-in only)
 
-Hard rule: Keep both engines in the extension. Default engine remains `stream-json`. All items below are non-breaking opt-in enhancements for the ACP engine that do NOT alter default behavior or touch legacy paths.
+Hard rule: Keep both engines in the extension. Default engine remains `stream-json`. All items below are non-breaking opt-in enhancements for the ACP engine that do NOT alter default behavior or touch streaming paths.
 
 Queue:
-1. [x] Gate C evaluation: `native-tools.ts` + `WrapperReplay` retired on the ACP engine (retained for legacy `stream-json` engine). ACP turns emit thinking labels for tool executions without parking turns for synthetic re-execution or wrapper cards; bridge MCP tools (`bridge_call`) continue parking natively. Verified: live parity 14/14 held.
-2. [x] Retire `diff-render.ts` (git path) on the ACP engine — DONE 2026-09-04. The phase-2 probe proved ACP surfaces edit diffs natively (`tool_call` `content[]` `{type:"diff", path, oldText?, newText}`), which is richer AND cheaper than the git-sourced path: implemented as (a) `events.ts` extracts the first diff entry into the `tool_done` activity (`AcpEditDiff`); (b) `provider.ts` renders it on ACP turns via the new `formatInlineDiff` (in-memory `generateDiffString`, same line-numbered format, ZERO git subprocesses) instead of `TurnDiffContext.diffEdit`; (c) `diff-render.ts` git machinery remains solely for the `stream-json` engine. Tests: diff extraction (with/without `oldText`), ACP thinking-stream rendering (`+2 B` line-numbered), label-only fallback, no parking, legacy path unchanged. Verified: 165/165 vitest, tsc clean, live parity 14/14.
+1. [x] Gate C evaluation: `native-tools.ts` + `WrapperReplay` retired on the ACP engine (retained for the streaming (`stream-json`) engine). ACP turns emit thinking labels for tool executions without parking turns for synthetic re-execution or wrapper cards; bridge MCP tools (`bridge_call`) continue parking natively. Verified: live parity 14/14 held.
+2. [x] Retire `diff-render.ts` (git path) on the ACP engine — DONE 2026-09-04. The phase-2 probe proved ACP surfaces edit diffs natively (`tool_call` `content[]` `{type:"diff", path, oldText?, newText}`), which is richer AND cheaper than the git-sourced path: implemented as (a) `events.ts` extracts the first diff entry into the `tool_done` activity (`AcpEditDiff`); (b) `provider.ts` renders it on ACP turns via the new `formatInlineDiff` (in-memory `generateDiffString`, same line-numbered format, ZERO git subprocesses) instead of `TurnDiffContext.diffEdit`; (c) `diff-render.ts` git machinery remains solely for the `stream-json` engine. Tests: diff extraction (with/without `oldText`), ACP thinking-stream rendering (`+2 B` line-numbered), label-only fallback, no parking, streaming path unchanged. Verified: 165/165 vitest, tsc clean, live parity 14/14.
 3. [x] `/agy doctor` diagnostics expansion — DONE 2026-09-04. The ACP
       snapshot now carries `reconnects` (connections beyond the first =
       Gate D kills + stale-exit replacements) and the handshake `agentInfo`
@@ -773,17 +773,17 @@ Status: 🚧 Phase 3 remaining items are COMPLETE (2026-09-04): 168/168 tests,
 tsc clean, live parity 14/14, embeddedContext verified live (resource block
 with a secret word answered correctly). Remaining phase-3 acceptance:
 deleted-code census lands with phase 4's deletions (nothing deletes in
-phase 3 — the legacy modules stay for the `stream-json` engine).
+phase 3 — the streaming modules stay for the `stream-json` engine).
 
-### Phase 4: default flip and legacy deletion (deferred, next month)
+### Phase 4: default flip and streaming deletion (deferred, next month)
 
 All items below are deferred until a full soak cycle of both engines has completed and upstream conditions are met:
 
-1. AskAntigravity migration to ACP one-shot (migrating while `stream-json` is default breaks legacy-only users who haven't onboarded ACP auth; legacy conversation ids cannot resume under ACP). `mode: "plan"` delegations keep the legacy `agy -p --mode plan` path (committed exception).
+1. AskAntigravity migration to ACP one-shot (migrating while `stream-json` is default breaks streaming-only users who haven't onboarded ACP auth; streaming conversation ids cannot resume under ACP). `mode: "plan"` delegations keep the `agy -p --mode plan` path (committed exception).
 2. Delete `src/discovery.ts` (`/proc` fd-scan) once AskAntigravity migration completes.
 3. Default flip: `config.engine` default becomes `"acp"` after one full release soak cycle with both engines shipping. Gate A PASS is verified.
 4. Upstream Gate B resolution: Google ships usage counters in ACP payloads.
-5. Legacy engine deletion: `src/driver.ts`, `src/stream-events.ts`, and legacy tests deleted one release after the flip AND only once Gate B has lifted (so zero-usage is never forced).
+5. Streaming engine deletion: `src/driver.ts`, `src/stream-events.ts`, and streaming tests deleted one release after the flip AND only once Gate B has lifted (so zero-usage is never forced).
 
 Acceptance: default-flip release ships with the parity suite as acceptance evidence; deletion release has zero references to the removed modules.
 
@@ -801,7 +801,7 @@ Acceptance: default-flip release ships with the parity suite as acceptance evide
 - **Provider**: the existing `provider-streaming` / `provider-digest` /
   `provider-sysprompt` suites run against both engines via the shared driver
   contract. New case: thought delta path.
-- **Sessions**: engine-tag matching, legacy-file compatibility (no tag),
+- **Sessions**: engine-tag matching, streaming-file compatibility (no tag),
   cross-engine miss starts fresh.
 - **Config**: narrowing of stale/garbage `engine` values, env precedence.
 - **Parity suite**: the section 6 checklist encoded as an integration run
@@ -836,8 +836,8 @@ Install layout:
 ## 13. Rollback
 
 At any phase: `AGY_ENGINE=stream-json` (or `/agy engine stream-json`) returns
-to the legacy engine. Sessions are keyed per engine (9.4), so the legacy
-engine resumes its own conversations untouched. The legacy engine is only deleted in
+to the streaming engine. Sessions are keyed per engine (9.4), so the streaming
+engine resumes its own conversations untouched. The streaming engine is only deleted in
 phase 4, one release after the flip, so rollback stays possible throughout.
 
 ## 14. Documentation updates
@@ -856,7 +856,7 @@ phase 4, one release after the flip, so rollback stays possible throughout.
 | # | Risk | L | I | Response |
 | --- | --- | --- | --- | --- |
 | R1 | Gate A fails (no model switch) | M | H | default flip blocked; ACP stays opt-in; escalate upstream. No ship-anyway: model switching is not optional |
-| R2 | Gate F fails (bridge not registrable) | L | H | BLOCKS phase 1; escalate upstream, keep legacy |
+| R2 | Gate F fails (bridge not registrable) | L | H | BLOCKS phase 1; escalate upstream, keep streaming |
 | R3 | Usage absent (CONFIRMED, Gate B) | H | M | zero-usage documented on ACP; stream-json retained as secondary engine; phase-4 deletion conditioned on Gate B lift (review 4) |
 | R4 | Binary churn (hourly registry, RC builds) | M | M | pin by build id, record sha256 |
 | R5 | Server rejects second simultaneous session | L | M | one session per connection (today's model), N connections instead |

package/docs/ACP-PROTOCOL-REFERENCE.md

@@ -247,7 +247,7 @@ unreachable on RC01 — no cancel method).
 
 - Chunks are pure DELTAS. Verified by content: numbers split mid-token across
   chunk boundaries (`"...\n39\n40\n4"` then `"1\n42\n43..."`), and no chunk
-  ever contained a full prefix of the accumulated text. The legacy
+  ever contained a full prefix of the accumulated text. The stream-json
   cumulative-resend failure mode was NOT observed over ACP (defensive guard
   stays cheap insurance).
 - Throughput: 300 numbers (~600 tokens) completed within one 25 s poll;

package/extensions/index.ts

@@ -38,7 +38,7 @@ import { SessionStore } from "../src/sessions.js";
 import { ToolRoundTrips, WrapperReplay, createStreamSimple } from "../src/provider.js";
 import { AgyDriver } from "../src/driver.js";
 import { AcpDriver } from "../src/acp/driver.js";
-import { resolveAcpBinary } from "../src/acp/connection.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 { registerAskAntigravityTool, toolModelsFromRaw } from "../src/ask-tool.js";
@@ -97,14 +97,32 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// MCP bridge handle, declared early: the ACP engine reads the bridge port
 	// at session/new / session/load time.
 	let mcpHandle: McpServerHandle | null = null;
+	// ACP self-heal runs once per process (session_start re-fires on /reload;
+	// a ready setup is two file stats, so re-running is harmless anyway).
+	let acpSelfHealRan = false;
 	// Two turn engines behind one contract (plan §9): stream-json (tested
 	// default) and the official ACP server (opt-in via config.engine, off by
 	// default). Neither spawns anything until its first turn.
+	// ACP log routing: only genuine failures reach stderr. Routine lifecycle
+	// (driver-created, spawn, session-new, ...) stays in the driver's
+	// #lifecycle ring buffer, visible via /agy doctor. An unfiltered sink fired
+	// console.error at extension load ("driver-created"), before any UI exists,
+	// and leaked raw driver lines into the terminal on every startup.
+	const acpFailures = new Set([
+		"start-failed", "spawn-error", "parse-error", "write-failed",
+		"mode-apply-failed", "timeout", "stall", "auth-required",
+		"session-load-failed-creating-fresh", "connection-exited", "cancel-failed",
+		"unsupported-server-request",
+	]);
 	const legacyDriver = new AgyDriver();
 	const acpDriver = new AcpDriver({
-		bin: resolveAcpBinary(loadConfig().acp.bin),
-		log: (msg, data) =>
-			console.error(`[antigravity-bridge acp] ${msg}${data !== undefined ? " " + JSON.stringify(data) : ""}`),
+		// Resolved per connection: the setup flow can install the binary and
+		// update acp.bin mid-session; the next turn picks it up (no restart).
+		bin: () => loadConfig().acp.bin,
+		log: (msg, data) => {
+			if (!acpFailures.has(msg)) return;
+			console.error(`[antigravity-bridge acp] ${msg}${data !== undefined ? " " + JSON.stringify(data) : ""}`);
+		},
 		mcpServers: () => {
 			const handle = mcpHandle;
 			if (!handle) return [];
@@ -233,29 +251,52 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		} catch {
 			/* detection is best-effort */
 		}
-		// Bridge lifecycle/error logger. Routes through ctx.ui.notify (an
-		// ephemeral toast that fades) instead of stderr: pi's TUI captures stderr
-		// and pins it above the input for the whole session, which left the
-		// startup "bridge-config-written" / "listening" lines stuck on screen all
-		// session. Headless modes (print/json, hasUI === false) have no toast, so
-		// fall back to stderr there. Per-turn success events (list-tools /
-		// call-tool) stay silent either way.
+		// ACP self-heal: engine=acp needs a server binary + auth. Silent when
+		// everything is ready; installs from the registry and bootstraps auth
+		// otherwise; manual instructions only on failure. Fire-and-forget: it
+		// must not delay session start (and nothing spawns until the first turn).
+		if (engine === "acp" && !acpSelfHealRan) {
+			acpSelfHealRan = true;
+			void ensureAcpReady({ configBin: loadConfig().acp.bin }).then((status) => {
+				if (status.ok) {
+					if (status.binarySource === "installed" || status.binarySource === "existing") {
+						saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
+					}
+					if (status.needsLogin) {
+						const msg =
+							"ACP: one-time Google login pending. Your next antigravity message opens the browser; sign in with your Antigravity subscription account (the same login as the agy CLI). Tokens stay on your machine.";
+						if (ctx.hasUI) ctx.ui.notify(msg, "info");
+						else console.error(`[antigravity-bridge] ${msg}`);
+					}
+					return;
+				}
+				const msg = `ACP auto-setup failed (${status.error}).\n${status.manual}`;
+				if (ctx.hasUI) ctx.ui.notify(msg, "warning");
+				else console.error(`[antigravity-bridge] ${msg}`);
+			});
+		}
+		// Bridge failure logger. Routine lifecycle (listening,
+		// bridge-config-written/removed, closed) is normal startup/teardown
+		// traffic: toasting it every session, or pinning it via stderr in
+		// headless mode, was noise. Only genuine failures surface - as a
+		// 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 surfaced = new Set([
-				"listening", "capability-missing", "http-error", "closed",
-				"bridge-config-written", "bridge-config-removed", "bridge-config-write-failed",
-				"call-tool-fail", "transport-error", "handleRequest-error",
-				"request-error", "request-handler-error", "unauthorized", "self-patch-error",
+			// 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 (!surfaced.has(s)) return;
+			if (!failures.has(s)) return;
 			const msg = `[antigravity-bridge mcp] ${s}${d !== undefined ? " " + JSON.stringify(d) : ""}`;
-			if (ctx.hasUI) {
-				const ok = s === "listening" || s === "bridge-config-written"
-					|| s === "bridge-config-removed" || s === "closed";
-				ctx.ui.notify(msg, ok ? "info" : "warning");
-			} else {
-				console.error(msg);
-			}
+			if (ctx.hasUI) ctx.ui.notify(msg, "warning");
+			else console.error(msg);
 		};
 		// Start the bridge unless the user turned it off. No patch gate, no
 		// consent flow: calls route through pi's normal toolUse loop.
@@ -413,9 +454,32 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 			}
 			if (sub === "engine") {
 				if (val === "acp" || val === "stream-json") {
+					if (val === "acp" && loadConfig().mode === "plan") {
+						ui?.notify("mode is plan; the ACP engine has no plan mode. /agy mode accept-edits first.", "warning");
+						return;
+					}
 					const next = saveConfig({ engine: val });
+					if (next.engine !== "acp") {
+						ui?.notify("engine set to stream-json. Takes effect on the next pi start (or /reload).", "info");
+						return;
+					}
+					// Self-service setup: install the server from the official
+					// registry and bootstrap auth now, so the restart just works.
+					// Manual instructions only when a step fails.
+					ui?.notify("engine set to acp. Preparing the server (binary + auth)…", "info");
+					const status = await ensureAcpReady({
+						configBin: loadConfig().acp.bin,
+						onProgress: (m) => ui?.notify(m, "info"),
+					});
+					if (!status.ok) {
+						ui?.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
+						return;
+					}
+					saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
 					ui?.notify(
-						`engine set to ${next.engine}. Takes effect on the next pi start (or /reload).${next.engine === "acp" ? "\nRequires the official ACP server binary (AGY_ACP_BIN or acp.bin) and a one-time auth: /agy acp-auth" : ""}`,
+						status.needsLogin
+							? "ACP engine ready. Your first ACP message opens the Google login in your browser: sign in with the account of your Antigravity subscription (the same login as the Antigravity CLI, agy). One-time; tokens stay on your machine and this extension never sees them. Takes effect on the next pi start (or /reload)."
+							: `ACP engine ready (auth: ${status.auth}). Takes effect on the next pi start (or /reload).`,
 						"info",
 					);
 				} else {
@@ -426,17 +490,26 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 			if (sub === "acp-auth") {
 				ui?.notify(
 					[
-						"ACP engine authentication (one-time):",
-						"1. Install the server binary (agy_acp_server.par from the ACP registry",
-						"   build URL) and point acp.bin or AGY_ACP_BIN at it.",
-						"2. Pick one credential path:",
-						'   - oauth-personal: put {"auth":{"type":"oauth-personal"}} in',
-						"     ~/.gemini/antigravity-acp/settings.json, run one turn, and open the",
-						"     login URL the server produces (headless: tunnel 127.0.0.1:<port>",
-						"     over ssh, then open the URL on your machine).",
-						'   - gemini-api-key: export GEMINI_API_KEY and set',
-						'     {"auth":{"type":"gemini-api-key"}} (headless-friendly; metered).',
-						"   The agent never reads or writes your credentials.",
+						"ACP engine authentication (one-time; usually automatic -",
+						"/agy engine acp and session start set this up for you):",
+						"",
+						"The server is Google's official Antigravity ACP, installed from Google's",
+						"own registry. Logging in uses your Antigravity subscription: the same",
+						"Google account and plan as the Antigravity CLI (agy). It is no different",
+						"from logging into the CLI; the server just keeps its own token file on",
+						"your machine, like any Google tool. This extension never sees your",
+						"credentials.",
+						"",
+						"1. Server binary: auto-setup installs it. Manual: agy_acp_server.par from",
+						"   the antigravity-acp registry; point acp.bin or AGY_ACP_BIN at it.",
+						'2. Default: put {"auth":{"type":"oauth-personal"}} in',
+						"   ~/.gemini/antigravity-acp/settings.json, run one turn, and complete the",
+						"   Google login that opens in your browser (headless: tunnel 127.0.0.1:<port>",
+						"   over ssh, then open the URL on your machine).",
+						'   Headless alternative: GEMINI_API_KEY + {"auth":{"type":"gemini-api-key"}}',
+						"   (metered paid API - not your Antigravity plan). The key is used only",
+						"   when that type is selected; with the default oauth-personal in place,",
+						"   an exported key is ignored.",
 						"3. Run one turn; /agy doctor shows the server version when auth is OK.",
 					].join("\n"),
 					"info",
@@ -469,11 +542,22 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 					lines.push("  lifecycle (last 5):");
 					for (const entry of snap.lifecycle.slice(-5)) lines.push(`    ${entry}`);
 				}
+				if (engine === "acp") {
+					const setup = inspectAcpSetup({ configBin: config.acp.bin });
+					lines.push(
+						`  acp binary:    ${setup.bin ?? "not found (auto-setup offers install)"}${setup.source ? ` (${setup.source})` : ""}`,
+						`  acp auth:      ${setup.auth ?? "not configured (auto-setup bootstraps)"}`,
+					);
+				}
 				ui?.notify(lines.join("\n"), "info");
 				return;
 			}
 			if (sub === "mode") {
 				if (val === "plan" || val === "accept-edits") {
+					if (val === "plan" && ctx.engine === "acp") {
+						ui?.notify("the ACP engine has no plan mode (RC01). /agy engine stream-json first, or /agy mode accept-edits.", "warning");
+						return;
+					}
 					const next = saveConfig({ mode: val as AgyMode });
 					ui?.notify(`mode set to ${next.mode}`, "info");
 				} else {
@@ -638,6 +722,11 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 	)
 		return;
 
+	if (pending.mode === "plan" && ctx.engine === "acp") {
+		ui.notify("the ACP engine has no plan mode (RC01). Switch /agy engine stream-json first.", "warning");
+		return;
+	}
+
 	try {
 		const next = saveConfig(pending);
 		const changed = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "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",
@@ -59,9 +59,10 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.84.3",
-    "@earendil-works/pi-coding-agent": "^0.84.3",
-    "@earendil-works/pi-tui": "^0.84.3",
+    "@earendil-works/pi-ai": "^0.85.0",
+    "@earendil-works/pi-coding-agent": "^0.85.0",
+    "@earendil-works/pi-server": "^0.85.0",
+    "@earendil-works/pi-tui": "^0.85.0",
     "@types/node": "^22.0.0",
     "tsx": "^4.19.0",
     "typebox": "^1.1.38",

package/src/acp/connection.ts

@@ -11,8 +11,9 @@
 //     the effort tier baked in, e.g. gemini-3.8-flash-low)
 //   - session/cancel returns -32601 on RC01 (not implemented) — the driver
 //     treats that as "cancel unsupported" and falls back to teardown+kill
-//   - session/request_permission is answered in-connection: single `auto`
-//     policy, first allow option selected (plan §9.3)
+//   - session/request_permission is answered in-connection: policy per turn
+//     (skipPermissions on -> first allow option; off -> first reject option,
+//     fail-closed)
 //   - session/load replays history as notifications BEFORE its response; the
 //     driver suppresses updates while the load is in flight
 //   - mcpServers entries: {name, type:"http", url, headers:[]} — headers is a
@@ -58,6 +59,10 @@ export interface AcpConnectionOptions {
 	/** mcpServers entries for session/new AND session/load (run 6: load takes
 	 *  the same param). Evaluated lazily per call. */
 	mcpServers?: () => AcpMcpServer[];
+	/** Permission policy for session/request_permission, evaluated per request:
+	 *  "auto" selects the first allow option; "deny" fail-closes to the first
+	 *  reject option. Absent = deny (fail closed). */
+	permissions?: () => "auto" | "deny";
 }
 
 const INIT_TIMEOUT_MS = 30_000;
@@ -114,6 +119,13 @@ export class AcpConnection {
 		this.#child = child;
 		child.stdout?.setEncoding("utf8");
 		child.stderr?.setEncoding("utf8");
+		// Pipe failures arrive asynchronously as stream 'error' events; the sync
+		// try/catch in #write cannot see them. Without this listener an EPIPE
+		// (server died mid-handshake) is uncaught and kills pi.
+		child.stdin?.on("error", (err) => {
+			this.#opts.log("stdin-error", { message: err.message });
+			if (!this.#exited && !this.#killed) this.#finish(err.message);
+		});
 
 		const rpc = new JsonRpcSession({
 			send: (frame) => this.#write(frame),
@@ -253,9 +265,10 @@ export class AcpConnection {
 		await this.guarded("session/close", { sessionId }, SESSION_OP_TIMEOUT_MS);
 	}
 
-	/** Protocol-level abort: single `auto` policy (plan §9.3) — select the
-	 *  first allow option. Never hangs: options are data from the server and
-	 *  the answer is computed synchronously. */
+	/** Protocol-level permission answering: policy from the driver ("auto"
+	 *  selects the first allow option; "deny" fail-closes to the first reject
+	 *  option). Never hangs: options are data from the server and the answer
+	 *  is computed synchronously. */
 	#onServerRequest(method: string, params: unknown): Promise<unknown> {
 		if (method === "session/request_permission") {
 			const options = (
@@ -263,9 +276,10 @@ export class AcpConnection {
 			) as Array<{ optionId?: string; kind?: string }> | undefined;
 			const allow = options?.find((o) => typeof o.kind === "string" && o.kind.startsWith("allow"));
 			const deny = options?.find((o) => typeof o.kind === "string" && o.kind.startsWith("reject"));
-			const chosen = allow ?? deny ?? options?.[0];
-			this.#opts.log("permission", { optionId: chosen?.optionId ?? "allow", policy: "auto" });
-			return Promise.resolve({ outcome: { outcome: "selected", optionId: chosen?.optionId ?? "allow" } });
+			const policy = this.#opts.permissions?.() ?? "deny";
+			const chosen = policy === "auto" ? (allow ?? deny ?? options?.[0]) : (deny ?? options?.[0]);
+			this.#opts.log("permission", { optionId: chosen?.optionId, policy });
+			return Promise.resolve({ outcome: { outcome: "selected", optionId: chosen?.optionId } });
 		}
 		// fs/* and terminal/* are declined: our client capabilities are off and
 		// agy keeps executing its own tools (plan §8 capability posture).

package/src/acp/driver.ts

@@ -34,8 +34,10 @@ import type {
 const LIFECYCLE_LIMIT = 24;
 
 export interface AcpDriverOptions {
-	/** Config acp.bin value (may be empty). Env AGY_ACP_BIN wins. */
-	bin: string;
+	/** Config acp.bin value (may be empty). Env AGY_ACP_BIN wins. A function
+	 *  is resolved per connection: setup can install the binary and update
+	 *  config mid-session, and the next turn picks it up without a restart. */
+	bin: string | (() => string);
 	/** Extra argv for the binary (tests: node + fake-server script). */
 	binArgs?: string[];
 	extraEnv?: Record<string, string>;
@@ -88,11 +90,11 @@ export function acpModelSlug(model: string, effort?: string): string {
 	return `${model}-${effort}`;
 }
 
-/** Map our config knobs onto ACP session modes. Under the single `auto`
- *  policy the practical effect of the modes converges (everything is
- *  approved); the mapping keeps the server-side counters honest.
- *  Known gap: the CLI's `--mode plan` has no ACP equivalent (review 4,
- *  finding 4) — plan delegations stay on the legacy path. */
+/** Map our config knobs onto ACP session modes. skipPermissions=false also
+ *  fail-closes the in-connection permission handler (reject options), so the
+ *  modes keep their server-side meaning. Known gap: the CLI's `--mode plan`
+ *  has no ACP equivalent (review 4, finding 4) — plan + acp is refused at the
+ *  command level and fails the turn visibly. */
 export function acpMode(mode: string, skipPermissions: boolean): string {
 	if (skipPermissions) return "yolo";
 	return mode === "plan" ? "default" : "auto_edit";
@@ -122,7 +124,7 @@ export class AcpDriver implements TurnDriver {
 
 	constructor(opts: AcpDriverOptions) {
 		this.#opts = opts;
-		this.#log("driver-created", { bin: resolveAcpBinary(opts.bin) });
+		this.#log("driver-created", { bin: typeof opts.bin === "function" ? "(resolved per turn)" : resolveAcpBinary(opts.bin) });
 	}
 
 	get state(): DriverState {
@@ -417,17 +419,19 @@ export class AcpDriver implements TurnDriver {
 		this.#state = "starting";
 		this.#stats.spawns += 1;
 		const conn = new AcpConnection({
-			bin: resolveAcpBinary(this.#opts.bin),
+			bin: resolveAcpBinary(typeof this.#opts.bin === "function" ? this.#opts.bin() : this.#opts.bin),
 			binArgs: this.#opts.binArgs,
 			extraEnv: this.#opts.extraEnv,
 			cwd: request.cwd,
 			mcpServers: this.#opts.mcpServers,
 			log: (msg, data) => this.#log(msg, data),
+			// Fail-closed permissions: only turns with skipPermissions answer allow.
+			permissions: () => (this.#active?.request.skipPermissions ? "auto" : "deny"),
 			onUpdate: (sessionId, update) => this.#onConnectionUpdate(sessionId, update),
 			onExit: (info) => this.#onConnectionExit(conn, info),
 		});
 		this.#conn = conn;
-		this.#log("spawn", { bin: resolveAcpBinary(this.#opts.bin) });
+		this.#log("spawn", { bin: resolveAcpBinary(typeof this.#opts.bin === "function" ? this.#opts.bin() : this.#opts.bin) });
 		return conn
 			.start()
 			.then(() => {

package/src/acp/setup.ts

@@ -0,0 +1,355 @@
+// ACP engine self-service setup: binary install from the official registry
+// and auth bootstrap. Everything is automatic when possible; the caller
+// surfaces `manual` only when a step fails. Instructions-as-first-resort is
+// gone: /agy engine acp and session_start self-heal silently when ready.
+//
+// Sources: docs/ACP-ADOPTION-PLAN.md §2.1 (registry entry), §12 (pinned
+// install layout: ~/.local/opt/agy-acp/<build>/ + current symlink, zip
+// sha256 recorded at install time), docs/ACP-PROTOCOL-REFERENCE.md
+// (settings.json auth shapes; the server opens the oauth browser itself).
+// Credential rule: this module never reads or writes credential VALUES —
+// acp_token.json is only stat()ed, gemini-api-key is read by the server
+// from the environment.
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const REGISTRY_URL =
+	"https://raw.githubusercontent.com/agentclientprotocol/registry/main/antigravity-acp/agent.json";
+
+const INSTALL_TIMEOUT_MS = 30 * 60_000;
+
+export interface SetupOptions {
+	/** Registry agent.json URL. Overridable for tests. */
+	registryUrl?: string;
+	/** Install root. Default ~/.local/opt/agy-acp. */
+	installRoot?: string;
+	/** Server settings dir. Default ~/.gemini/antigravity-acp. */
+	geminiDir?: string;
+	/** acp.bin from config (second resolution priority after AGY_ACP_BIN). */
+	configBin?: string;
+	/** Environment. Default process.env (test injection). */
+	env?: NodeJS.ProcessEnv;
+	/** Progress messages for the user (throttled by the caller's UI). */
+	onProgress?: (msg: string) => void;
+	fetchImpl?: typeof fetch;
+	/** Archive unpacker. Default: `unzip` subprocess (tests inject a copier). */
+	unpack?: (archive: string, dest: string) => Promise<void>;
+	/** Download when the binary is missing. Default true. */
+	install?: boolean;
+}
+
+export type AcpSetupStatus =
+	| {
+			ok: true;
+			bin: string;
+			binarySource: "env" | "config" | "installed" | "existing";
+			auth: string;
+			/** True when auth was just set to oauth-personal: the server opens
+			 *  Google login in the browser on the first ACP message. */
+			needsLogin: boolean;
+			/** Human-readable actions taken (empty when everything was ready). */
+			actions: string[];
+	  }
+	| { ok: false; stage: "install" | "auth"; error: string; manual: string };
+
+export const MANUAL_SETUP = [
+	"For some unknown reason, Google ships its ACP server as a separate",
+	"binary from the Agy CLI. So, as with any other part of its Antigravity",
+	"suite (Agy Desktop, Agy Editor, Agy CLI), you need to log in to",
+	"this one as well. Separately ¯\\_(ツ)_/¯",
+	"ACP manual setup:",
+	"1. Download the server zip for your platform from the antigravity-acp",
+	"   registry entry (github.com/agentclientprotocol/registry, folder",
+	"   antigravity-acp/agent.json) and unzip it, e.g. to",
+	"   ~/.local/opt/agy-acp/<build>/; chmod +x agy_acp_server.par.",
+	"2. Point AGY_ACP_BIN or /agy config acp.bin at the binary",
+	"   (~/.local/opt/agy-acp/current/agy_acp_server.par works; 'current' is a",
+	"   symlink to the build dir).",
+	'3. Log in: put {"auth":{"type":"oauth-personal"}} in',
+	"   ~/.gemini/antigravity-acp/settings.json and complete the Google login that",
+	"   opens in your browser on your first ACP message. That login IS your",
+	"   Antigravity subscription (Google AI Plus/Pro/Ultra).",
+	"Details: /agy acp-auth",
+].join("\n");
+
+export function platformKey(): string {
+	const goos = process.platform === "darwin" ? "darwin" : process.platform === "win32" ? "windows" : "linux";
+	const goarch = process.arch === "arm64" ? "aarch64" : "x86_64";
+	return `${goos}-${goarch}`;
+}
+
+/** Build id from a registry archive URL:
+ *  …/agy-acp-server-<build>-<platform>-<arch>.zip. */
+export function buildIdFromArchive(url: string): string {
+	const base = path.posix.basename(url, ".zip");
+	const m = base.match(/^agy-acp-server-(.+)-(darwin|linux|windows)-(?:arm64|x86_64)$/);
+	if (!m) throw new Error(`unrecognized registry archive name: ${base}`);
+	return m[1];
+}
+
+function defaultInstallRoot(): string {
+	return path.join(os.homedir(), ".local", "opt", "agy-acp");
+}
+
+function defaultGeminiDir(opts: SetupOptions): string {
+	return opts.geminiDir ?? path.join(os.homedir(), ".gemini", "antigravity-acp");
+}
+
+/** Expand a leading ~ (spawn does not). Mirrors resolveAcpBinary. */
+function expandTilde(p: string): string {
+	return p === "~" || p.startsWith("~/") ? path.join(os.homedir(), p.slice(1)) : p;
+}
+
+export function executableFile(p: string): boolean {
+	try {
+		fs.accessSync(p, fs.constants.X_OK);
+		return fs.statSync(p).isFile();
+	} catch {
+		return false;
+	}
+}
+
+interface RegistryBinary {
+	archive: string;
+	cmd?: string;
+}
+
+async function fetchRegistryBinary(opts: SetupOptions, key: string): Promise<RegistryBinary> {
+	const fetchImpl = opts.fetchImpl ?? fetch;
+	const res = await fetchImpl(opts.registryUrl ?? REGISTRY_URL, { signal: AbortSignal.timeout(15_000) });
+	if (!res.ok) throw new Error(`registry fetch failed: HTTP ${res.status}`);
+	const json = (await res.json()) as { distribution?: { binary?: Record<string, RegistryBinary> } };
+	const entry = json.distribution?.binary?.[key];
+	if (!entry?.archive) throw new Error(`registry has no ${key} binary`);
+	return entry;
+}
+
+function defaultUnpack(archive: string, dest: string): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const child = spawn("unzip", ["-o", "-q", archive, "-d", dest], { stdio: "ignore" });
+		child.on("error", (err) => reject(new Error(`unzip is not available: ${err.message}`)));
+		child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`unzip exited with ${code}`))));
+	});
+}
+
+async function downloadTo(
+	url: string,
+	dest: string,
+	fetchImpl: typeof fetch,
+	onProgress?: (msg: string) => void,
+): Promise<string> {
+	const res = await fetchImpl(url, { signal: AbortSignal.timeout(INSTALL_TIMEOUT_MS) });
+	if (!res.ok || !res.body) throw new Error(`download failed: HTTP ${res.status}`);
+	const hash = createHash("sha256");
+	const total = Number(res.headers.get("content-length") ?? 0);
+	const out = fs.createWriteStream(dest);
+	let done = 0;
+	let lastPct = -1;
+	for await (const chunk of res.body) {
+		const buf = Buffer.from(chunk as unknown as Uint8Array);
+		hash.update(buf);
+		done += buf.length;
+		if (total > 0) {
+			const pct = Math.floor((done / total) * 100);
+			if (pct >= lastPct + 10) {
+				lastPct = pct;
+				onProgress?.(`downloading ACP server: ${pct}%`);
+			}
+		}
+		if (!out.write(buf)) await new Promise<void>((r) => out.once("drain", r));
+	}
+	await new Promise<void>((resolve, reject) => {
+		out.on("finish", () => resolve());
+		out.on("error", reject);
+		out.end();
+	});
+	return hash.digest("hex");
+}
+
+export interface InstallResult {
+	bin: string;
+	build: string;
+	sha256: string;
+	downloaded: boolean;
+}
+
+/** Fetch the pinned registry build for this platform and install it under
+ *  <root>/<build>/ with a `current` symlink (plan §12). No-op when the
+ *  build is already installed. Registry publishes no checksums; the zip
+ *  sha256 is recorded at install time for drift detection. */
+export async function installAcpBinary(opts: SetupOptions = {}): Promise<InstallResult> {
+	const root = opts.installRoot ?? defaultInstallRoot();
+	const entry = await fetchRegistryBinary(opts, platformKey());
+	const build = buildIdFromArchive(entry.archive);
+	const cmd = (entry.cmd ?? "./agy_acp_server.par").replace(/^\.\//, "");
+	const dir = path.join(root, build);
+	const bin = path.join(dir, cmd);
+	if (executableFile(bin)) {
+		return { bin, build, sha256: readRecordedSha(dir), downloaded: false };
+	}
+
+	fs.mkdirSync(root, { recursive: true });
+	fs.mkdirSync(dir, { recursive: true });
+	const tmpZip = path.join(root, `.download-${build}.zip`);
+	opts.onProgress?.(`downloading ACP server (build ${build})…`);
+	const sha = await downloadTo(entry.archive, tmpZip, opts.fetchImpl ?? fetch, opts.onProgress);
+	opts.onProgress?.("unpacking ACP server…");
+	const unpack = opts.unpack ?? defaultUnpack;
+	await unpack(tmpZip, dir);
+	fs.rmSync(tmpZip, { force: true });
+	if (!executableFile(bin)) throw new Error(`${cmd} not found in the archive after unpacking`);
+	fs.chmodSync(bin, 0o755);
+	fs.writeFileSync(path.join(dir, "zip.sha256"), `${sha}  ${path.basename(entry.archive)}\n`);
+
+	// Re-point `current` at the new build. The link is ours (managed layout).
+	const link = path.join(root, "current");
+	fs.rmSync(link, { force: true });
+	fs.symlinkSync(build, link);
+	opts.onProgress?.("ACP server installed.");
+	return { bin, build, sha256: sha, downloaded: true };
+}
+
+function readRecordedSha(dir: string): string {
+	try {
+		return fs.readFileSync(path.join(dir, "zip.sha256"), "utf8").split(/\s+/)[0] ?? "";
+	} catch {
+		return "";
+	}
+}
+
+export interface AuthState {
+	configured: boolean;
+	/** settings.json auth.type, "token" (acp_token.json present), or undefined. */
+	type?: string;
+}
+
+/** Auth state WITHOUT reading any credential value: settings.json carries
+ *  only auth.type (+ non-secret gcp placement), acp_token.json is stat()ed. */
+export function readAuthState(dir?: string): AuthState {
+	const target = dir ?? path.join(os.homedir(), ".gemini", "antigravity-acp");
+	try {
+		const raw = JSON.parse(fs.readFileSync(path.join(target, "settings.json"), "utf8")) as {
+			auth?: { type?: unknown };
+		};
+		const type = typeof raw.auth?.type === "string" ? raw.auth.type : undefined;
+		if (type) return { configured: true, type };
+	} catch {
+		/* absent or garbage = unconfigured */
+	}
+	try {
+		fs.statSync(path.join(target, "acp_token.json"));
+		return { configured: true, type: "token" };
+	} catch {
+		return { configured: false };
+	}
+}
+
+/** Write a minimal auth block into settings.json. The server reads this file
+ *  at STARTUP, so this must happen before the first server spawn. */
+export function writeAuthType(type: "gemini-api-key" | "oauth-personal", dir?: string): void {
+	const target = dir ?? path.join(os.homedir(), ".gemini", "antigravity-acp");
+	fs.mkdirSync(target, { recursive: true, mode: 0o700 });
+	const file = path.join(target, "settings.json");
+	let settings: Record<string, unknown> = {};
+	try {
+		settings = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+	} catch {
+		/* fresh file */
+	}
+	const prevAuth = (typeof settings.auth === "object" && settings.auth !== null ? settings.auth : {}) as Record<string, unknown>;
+	fs.writeFileSync(file, `${JSON.stringify({ ...settings, auth: { ...prevAuth, type } }, null, 2)}\n`, { mode: 0o600 });
+}
+
+export interface BinaryResolution {
+	bin: string | null;
+	source: "env" | "config" | "existing" | "installed" | null;
+}
+
+/** Read-only binary resolution: AGY_ACP_BIN > acp.bin > installed `current`
+ *  layout. Does NOT install and does NOT fall back to the bare PATH name. */
+export function resolveInstalledBinary(opts: SetupOptions = {}): BinaryResolution {
+	const env = opts.env ?? process.env;
+	const root = opts.installRoot ?? defaultInstallRoot();
+	const candidates: Array<[string, BinaryResolution["source"]]> = [
+		[env.AGY_ACP_BIN?.trim() ?? "", "env"],
+		[opts.configBin?.trim() ?? "", "config"],
+		[path.join(root, "current", "agy_acp_server.par"), "existing"],
+	];
+	for (const [raw, source] of candidates) {
+		if (!raw) continue;
+		const bin = expandTilde(raw);
+		if (executableFile(bin)) return { bin, source };
+	}
+	return { bin: null, source: null };
+}
+
+/** Read-only setup state (for /agy doctor): no installs, no writes. */
+export function inspectAcpSetup(opts: SetupOptions = {}): { bin: string | null; source: string | null; auth: string | null } {
+	const binary = resolveInstalledBinary(opts);
+	const auth = readAuthState(defaultGeminiDir(opts));
+	return { bin: binary.bin, source: binary.source, auth: auth.configured ? (auth.type ?? "token") : null };
+}
+
+/** Orchestrate everything the ACP engine needs, in order: binary (install
+ *  from the registry when missing), then auth (oauth-personal: the user's
+ *  own Antigravity subscription - the same Google account and plan as the
+ *  agy CLI login; the server opens the browser itself on the first message).
+ *  Every step is skipped when already satisfied; failures return `manual`
+ *  text for the caller to surface. */
+export async function ensureAcpReady(opts: SetupOptions = {}): Promise<AcpSetupStatus> {
+	const actions: string[] = [];
+
+	// 1. Binary.
+	let binary = resolveInstalledBinary(opts);
+	if (!binary.bin) {
+		if (opts.install === false) {
+			return { ok: false, stage: "install", error: "no ACP server binary found", manual: MANUAL_SETUP };
+		}
+		try {
+			const installed = await installAcpBinary(opts);
+			binary = { bin: installed.bin, source: "installed" };
+			actions.push(installed.downloaded ? `installed ACP server build ${installed.build}` : `found installed ACP server build ${installed.build}`);
+		} catch (err) {
+			return {
+				ok: false,
+				stage: "install",
+				error: err instanceof Error ? err.message : String(err),
+				manual: MANUAL_SETUP,
+			};
+		}
+	}
+
+	// 2. Auth. settings.json is read at server STARTUP; setup always runs
+	// before the first spawn, so a fresh write takes effect. oauth-personal is
+	// THE default: it is the Antigravity subscription (same Google account and
+	// plan as the agy CLI login). gemini-api-key (metered paid API) stays a
+	// manual option for headless boxes (/agy acp-auth); never the default.
+	const gdir = defaultGeminiDir(opts);
+	const auth = readAuthState(gdir);
+	if (!auth.configured) {
+		try {
+			writeAuthType("oauth-personal", gdir);
+			actions.push("configured oauth-personal auth (your Antigravity subscription login)");
+			return { ok: true, bin: binary.bin!, binarySource: binary.source!, auth: "oauth-personal", needsLogin: true, actions };
+		} catch (err) {
+			return {
+				ok: false,
+				stage: "auth",
+				error: err instanceof Error ? err.message : String(err),
+				manual: MANUAL_SETUP,
+			};
+		}
+	}
+	return {
+		ok: true,
+		bin: binary.bin!,
+		binarySource: binary.source!,
+		auth: auth.type ?? "token",
+		needsLogin: false,
+		actions,
+	};
+}

package/src/driver.ts

@@ -132,6 +132,10 @@ export class AgyDriver implements TurnDriver {
 	#queueTail: Promise<void> = Promise.resolve();
 	#shutdown = false;
 	#stderrTail = "";
+	// Frames can split across pipe chunks; the trailing partial line lives here
+	// until its newline arrives (same scheme as JsonRpcSession.feed). Dropping
+	// it ate large tool frames and could hide the result frame of a turn.
+	#stdoutBuf = "";
 	#lifecycle: string[] = [];
 	#onTurnEnd: ((outcome: TurnOutcome) => void) | undefined;
 	#stats = {
@@ -332,7 +336,16 @@ export class AgyDriver implements TurnDriver {
 			windowsHide: true,
 		});
 		this.#child = child;
+		this.#stdoutBuf = "";
 		this.#stats.spawns += 1;
+		// Pipe write failures surface asynchronously as stream 'error' events;
+		// the sync try/catch around stdin.write cannot see them. Without this
+		// listener an EPIPE (agy died mid-write) is uncaught and kills pi.
+		child.stdin!.on("error", (err) => {
+			if (generation !== this.#generation) return;
+			const turn = this.#active;
+			if (turn && !turn.closed) this.#failTurn(turn, `agy stdin write failed: ${err.message}`);
+		});
 		this.#log(`spawn:${child.pid ?? "?"}:${request.conversationId ? "resume" : "fresh"}`);
 		this.#state = "ready";
 
@@ -379,10 +392,15 @@ export class AgyDriver implements TurnDriver {
 	}
 
 	#onStdout(chunk: string): void {
+		// Buffer the trailing partial line: a frame split across pipe chunks is
+		// reassembled when its newline arrives (mirrors JsonRpcSession.feed).
+		this.#stdoutBuf += chunk;
+		const lines = this.#stdoutBuf.split("\n");
+		this.#stdoutBuf = lines.pop() ?? "";
 		const turn = this.#active;
 		if (!turn || turn.closed) return;
 		if (turn.idleTimer) turn.idleTimer.refresh();
-		for (const line of chunk.split("\n")) {
+		for (const line of lines) {
 			if (!line.trim()) continue;
 			this.#applyParsed(turn, parseAgyLine(line));
 			if (turn.closed) return;
@@ -585,6 +603,7 @@ export class AgyDriver implements TurnDriver {
 		if (!child) return;
 		this.#child = undefined;
 		this.#generation += 1;
+		this.#stdoutBuf = "";
 		try {
 			child.stdout?.removeAllListeners();
 			child.stderr?.removeAllListeners();

package/src/provider.ts

@@ -846,6 +846,14 @@ export function createStreamSimple(
 		const config = loadConfig();
 		const engine = deps.engine ?? config.engine;
 		const selected = engine === "acp" && deps.acpDriver ? deps.acpDriver : deps.driver;
+		// RC01: ACP modes are permission modes, there is no review-only plan.
+		// A plan turn on ACP would silently run non-plan; fail visibly instead.
+		if (selected === deps.acpDriver && config.mode === "plan") {
+			const partial = newAssistant(model);
+			const blocks: BlockState = { partial, textIdx: null, thinkingIdx: null, started: false };
+			finalize(stream, blocks, "error", "ACP engine has no plan mode. /agy mode accept-edits, or /agy engine stream-json.");
+			return stream;
+		}
 		if (selected && roundTrips) {
 			void runTurnDriver(stream, model, context, options, entries, store, {
 				driver: selected,