docs(acp): document the local ACP development loop

[probepark]

Why

Rebuilding the binary does nothing for ACP until the SDK broker is restarted, and there is currently no documentation that says so.

gjc acp is a thin stdio front end — it attaches to the long-lived broker published for the agent directory, and that broker spawns a sdk session-host-internal child per session from the entrypoint it was started with. So after bun run install:dev:bin you get a new gjc on PATH talking to an eight-hour-old broker that keeps running the old code. The change appears to have no effect, which is indistinguishable from the fix being wrong.

I lost real time to exactly this while smoke-testing #3950 against Paseo:

19466  08:25:00  /Users/probe/git/probepark/gajae-code/packages/coding-agent/dist/gjc sdk broker-internal

bun run restart:sdk-broker was documented only as one sentence inside the JetBrains Air subsection of external-control-readiness.md, phrased as a description of what the script does — not as a step you must run. Nothing connects it to "your ACP change is not live".

What

New docs/acp-local-development.md covering:

• the build → install → restart loop, and why the restart is not optional
• how to tell which build is actually serving (ps on broker-internal, before/after)
• --agent-dir / --close-session-hosts for scratch or full restarts
• driving GJC from Paseo: provider registration, run/logs/ls/stop, and reading the JSON-RPC payload out of ~/.paseo/daemon.log when the CLI prints Failed to create agent: [object Object]
• the bare stdio initialize handshake
• which ACP transitions to smoke-test, because unit tests don't cover them — notably that a prompt whose agent continues mid-turn strands the client for 30 minutes rather than erroring, so "still running" is the signal, not a failure message

external-control-readiness.md gets a link to it from the ACP readiness section. That doc keeps its role as the protocol/support contract; this one is the dev loop.

Verification

Every command in the doc was run against a live Paseo 0.2.5 daemon on macOS, including a real broker restart and a --agent-dir restart verified not to disturb the main broker. docs-index.generated.ts is gitignored, so there is nothing to regenerate in-tree.

[Yeachan-Heo]

Holding this PR pending two independent gates.

The exact-head CI failure is repository-global, not docs content: the docs-only canonical plan contained the docs-index test plus the dedicated native-linux-x64 producer, but the shard matrix also emitted the producer because its legacy in-memory task lacks explicit capabilities. Evidence validation correctly excluded the producer and rejected the extra receipt. Baseline repair: #3979.

The completed read-only docs red-team also identified content corrections required before terminal disposition:

• make the primary source-exact loop stale-session-host-safe with --close-session-hosts, including interruption scope and fresh/reloaded Paseo session guidance;
• replace the incorrect scratch credential reference to models.db (agent.db is the local credential database) and show how GJC_CODING_AGENT_DIR reaches the provider process/Paseo daemon;
• separate Paseo lifecycle states from run --wait-timeout results and from GJC's 30-minute prompt deadline;
• remove or make deterministic the categorical second-agent_start continuation claim;
• state the POSIX/Linux/macOS and Paseo v0.2.5 support boundary.

No terminal verdict is attached until the exact-head evidence producer passes.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]

[probepark]

All five content corrections landed in 0fcbf7c. I re-verified them against a live Paseo 0.2.5 daemon, since that commit records Not-tested: live Paseo daemon — everything holds, and the --close-session-hosts promotion turns out to be more load-bearing than the review implied.

--close-session-hosts in the primary loop — confirmed, and stronger than stated

I hit the exact failure the correction guards against, by accident. After deleting the git worktree I had been building from, restarting the broker from the new checkout, and rebuilding the binary, 21 of 35 live session hosts were still executing from the deleted worktree path:

99593  58:14     bun --config=/Users/probe/.gjc/wt/acp-integration/.../internal-source.bunfig.toml \
                 /Users/probe/.gjc/wt/acp-integration/packages/coding-agent/src/cli.ts sdk session-host-internal
97465  01:58:36  (same, from the same removed directory)

Nothing about the environment looked wrong — which gjc, the broker's entrypoint and the checkout were all correct. A broker-only restart cannot reach these. With the flag:

$ bun run restart:sdk-broker -- --close-session-hosts
SDK broker 17323 -> 46571 (closed 35 session hosts)

stale worktree hosts: 21 -> 0

So the reviewed wording ("Without the flag, live hosts keep their old entrypoint") holds even when the old entrypoint no longer exists on disk.

The claim that it "never closes interactive gjc TUI sessions" also holds: all 35 hosts were closed and the interactive GJC session issuing the command survived, matching isSessionHostProcess's sdk session-host-internal filter in scripts/restart-sdk-broker.ts.

A fresh ACP turn through Paseo after the flagged restart: completed in 23s.

paseo ls lifecycle vocabulary — confirmed

paseo ls reports running / idle / error only. completed and timeout appear in paseo run's result table, never in ls — an agent that finishes shows completed from run and then idle in ls. The separation the correction makes is the real behaviour.

Not re-verified

The agent.db credential correction is right per docs/models.md and docs/porting-from-pi-mono.md, but I did not exercise the scratch-GJC_CODING_AGENT_DIR path with a copied agent.db, so the "copy only while no process is using either database" guidance is unverified by me.

No further content changes from my side. Holding on #3979 for the exact-head producer baseline.

[Yeachan-Heo]

MERGE_READY

Bounded terminal docs review is bound to exact head 7d5dd53b8b569183c2923946a10e9b02f17d4c9f on current dev 82c47e73cc35693b89c38a6199e2ba068ae1ee9b (source hash sha256:15f2e12d4f4d0a8c5c529d5cc4c14ecda58494415085f825514f5a99493e1636).

Verified:

• docs-only diff; no ACP implementation files changed;
• source-exact restart guidance closes broker-spawned hosts and states the interruption boundary;
• scratch credentials correctly name agent.db and explain provider/Paseo environment propagation;
• Paseo lifecycle, wait timeout, and GJC prompt deadline are separated;
• continuation smoke guidance uses settlement rather than a false fixed event-count invariant;
• POSIX and Paseo v0.2.5 support boundaries are explicit;
• local docs-index regression: 5 passed;
• exact-head Dev CI 31146092038: success;
• exact-head Public site sync 31146091923: success;
• 11 successful checks, 7 intentional skips, no active or failed checks.

No blocking findings remain.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]