fix(acp): settle prompts correctly and make content, limits, and cancellation spec-conformant

[probepark]

Fixes #3949. Fixes #3962.

Two rounds of work from smoke-testing GJC's ACP mode against the Paseo client (CLI/daemon 0.2.5), then auditing the implementation against the ACP v1 spec.

1. session/prompt never settled when the agent continued mid-prompt (#3949)

api.on("agent_start") unconditionally claimed the next queued correlation. A continuation (todo reminder, TTSR resume, auto-continue) re-enters the agent loop within the same prompt and emits a second agent_start, so shift() on the already-empty queue returned undefined and clobbered the live correlation:

22:03:06.954 accept push   correlation={cmd:3bad218a…, turn:ad08c3c8…}  pending=1
22:03:06.963 agent_start   correlation={3bad218a…, ad08c3c8…}           pendingAfter=0
22:03:11.667 agent_start   correlation=undefined   <-- clobbered
22:03:11.667 agent_end     correlation=undefined   <-- terminalizePrompt never called

agent_end then took the uncorrelated branch, so no terminal was published and ACP's #handleSdkFrame dropped it for lack of a complete correlation — the client hung until the 30-minute deadline despite the answer having already streamed.

agent_start now claims a pending correlation only when the session has no active one, and #checkTodoCompletion holds the predecessor agent_end like every other #scheduleAgentContinue call site.

2. ACP conformance defects (#3962)

• User messages and image attachments now render. A live turn emitted no user_message_chunk at all (it existed only on the session/load replay path), so an attached image reached the model but never appeared in the client transcript. session/prompt now echoes the prompt's text and image content blocks before dispatching the turn.
• Oversize prompts fail with a typed error instead of killing the session. The SDK WebSocket server caps a frame at 256 KiB and answers oversize with CloseCode::Size, which reached clients as an opaque -32603 connection_closed. The prompt is now measured inside its real control_request envelope (the {type,operation,input,id} wrapper SdkClient adds) and rejected with -32602 naming the actual and permitted size.
• session/cancel and session/close settle the prompt as cancelled. A cancel landing during preflight rejected with busy, and session/close rejected with connection_closed; both showed the user a spurious error for their own action. Involuntary teardown still rejects.
• mcpCapabilities.sse is no longer advertised. Legacy MCP HTTP+SSE (deprecated in the MCP spec) is not implemented — sse configs route to the Streamable HTTP transport, which never performs the endpoint-event handshake. Locally configured sse entries still resolve through createTransport and keep working; only the false advertisement to ACP clients is removed.
• Reverse ACP responses are measured as the full serialized frame, not just the inner result, so a near-limit fs/read_text_file result raises the typed payload_too_large instead of tripping the total-frame ceiling and closing the session.
• todo_write accepts complete/completed as aliases for done. The status this op sets is spelled completed, so models repeatedly emitted op:"complete" and hit a hard mid-turn tool failure. The vocabulary is otherwise unchanged and a completion still requires a task or phase target.

Verification

Regression tests, each confirmed failing before its fix and passing after:

• sdk-host-wiring.test.ts — continuation agent_start keeps the correlation (times out on the old code, reproducing the hang)
• sdk-reverse-rpc.test.ts + sdk-acp-adapter.test.ts — inner result under the cap whose full frame exceeds it is rejected
• tools/todo-write.test.ts — complete/completed aliases, canonical done still works, unknown ops still rejected, and an aliased completion without a target is still rejected
• acp-prompt-conformance.test.ts — image blocks survive payload conversion; frame-size boundary arithmetic
• runtime-mcp-sse-transport.test.ts — pins that an sse config really is served by Streamable HTTP

Suites: 134 pass / 0 fail across the ACP, SDK, reverse-RPC, todo, and host-wiring files. bun --cwd=packages/coding-agent run check (biome + tsc) clean.

Live, after bun run build:native && bun run install:dev:bin:

• paseo run --provider gjc --image <out-of-workspace png> → status: completed, answered magenta, black, yellow (unguessable, tools disabled)
• wire capture now shows user_message_chunk carrying mime image/png b64len 372 (previously zero image-bearing updates)
• oversize image → -32602 Invalid params: ACP prompt is 261 KiB, over the 256 KiB transport limit with the session still alive (previously -32603 connection_closed)

Not covered

Two findings from the same audit are left open and documented in #3962: session/load replay drops user images (transcriptReplayContent always reports images:{available:false}), and promptCapabilities.embeddedContext is advertised while non-image blob resources are rejected. ACP cancel racing a continuation agent_start is also untested.

[thisisjun786]

I reproduced the #3949 correlation loss through a Hermes -> GJC ralplan approval gate and validated the correlation commit at this PR head.

Evidence:

• The existing continuation regression passes with the fix and times out waiting for the correlated terminal when only the bus fix is reverted.
• I extended that regression locally with a real BrokerWorkflowGateEmitter: accept one turn.prompt, run agent_start twice, emit a ralplan approval gate, and assert the pending gate runtime_turn_id equals the accepted turnId.
• With the fix, the strengthened test passes. With only the source fix reverted, it fails immediately because runtime_turn_id is absent. This matches the coordinator missing_runtime_turn observed in the live dispatch.
• Full sdk-host-wiring.test.ts: 80 pass / 0 fail / 427 expects.
• Focused coordinator malformed-gate test: 1 pass / 0 fail.
• Biome check and the coding-agent package typecheck pass.

Would you be open to folding this small assertion into the existing continuation test? The local test-only diff is:

+ const emitter = new BrokerWorkflowGateEmitter(sessionId, new FileGateStore(path.join(cwd, ".gjc", "state", "workflow-gates.json")));
- const sessionContext = context(cwd, sessionId);
+ const sessionContext = context(cwd, sessionId, "main", {}, emitter);
  // ... accept prompt, first agent_start, second agent_start
+ const advance = emitter.emitGate({
+   stage: "ralplan",
+   kind: "approval",
+   schema: { type: "string", enum: ["approve"] },
+ });
+ const gate = emitter.listWorkflowGateQueryRecords!()[0];
+ expect(gate).toMatchObject({ tag: "pending", runtime_turn_id: turnId });
+ await emitter.resolveGate!({
+   gate_id: gate!.gate_id,
+   answer: "approve",
+   idempotency_key: "continuation-gate-runtime-turn",
+ });
+ expect(await advance).toBe("approve");

This is complementary to #3951: this PR preserves the SDK prompt turn ID through continuation starts; #3951 addresses coordinator state-file/current-turn propagation.

[thisisjun786]

Correction to my previous comment: an exact isolated Hermes -> GJC ralplan smoke against this PR head still reproduced the coordinator failure.

• Accepted runtime turn: 0e04ed4c-b8a1-4fbb-a44b-65c4ff0952ed
• Ralplan gate reached after Planner/Critic/Architect: wg_b8260e58_ralplan_000001
• Persisted gate runtime_turn_id: absent
• Coordinator therefore still cannot materialize the approval question.

The current regression proves the duplicate agent_start case, but the live nested-subagent lifecycle has at least one additional boundary that clears the parent correlation. Please treat my earlier sufficiency claim as withdrawn and do not fold the proposed assertion as proof of a complete fix yet. I am tracing the remaining event sequence and will follow up with a discriminating regression and minimal patch.

[probepark]

Local verification against Paseo (CLI/daemon 0.2.5)

Tested this branch in isolation — upstream/dev + this PR only, no other PR merged in — on a compiled binary (bun run build:native && bun run install:dev:bin) with the SDK broker restarted (bun run restart:sdk-broker) so the agent loop actually runs this code.

Note for anyone repeating this: rebuilding the binary is not enough. A long-lived sdk broker-internal process keeps spawning session hosts from the old build, so the fix appears not to work. bun run restart:sdk-broker is required.

#3949 — prompt never settles on continuation

Reproduced the exact path and it now settles. Transcript shows the two agent_start sequence (todo_write → text → continuation → todo_write → text):

[User] Reply with exactly: ACP-3950-OK
[Think] todo_write
- [ ] Parse literal reply requirement from user request
- [ ] Emit exact token ACP-3950-OK with no extras
- [ ] Confirm response matches requested literal exactly
ACP-3950-OK
[Think] todo_write
- [x] ... (all three checked)
ACP-3950-OK

completed in 27s. On the pre-fix build the identical prompt sat at running indefinitely, last update 5s after creation.

Follow-up turn on the same session (write a file, then confirm): completed in 43s, file written correctly.

#3962 — conformance

Check	Result
initialize	mcpCapabilities is {"http":true} — no sse
user_message_chunk	user's own message renders in the Paseo transcript ([User] ...)
cancel mid-turn	agent settles to idle, no transport error surfaced

Gates

• bun test — ACP + acp/ + sdk-acp-* + sdk-host-wiring + sdk-reverse-rpc + tools/todo-write + runtime-mcp-sse-transport: 168 pass / 0 fail (11 files)
• bun --cwd=packages/coding-agent run check — tsc clean; the single biome warning is pre-existing in smithery-env-trust.test.ts (untouched by this PR)

Merge conflict

Merged upstream/dev in. The only conflict was the CHANGELOG.md unreleased section; both sides' entries are kept, no code change. The resulting tree is byte-identical to the one smoke-tested above.

[Yeachan-Heo]

Ownership transfer: managed legacy-local → #3976

Dropped the parallel managed-session-storage / task-managed-descendants captureTree self-heal from this PR (commit 044ffc580 reverts those files to origin/dev).

Sole owner: #3976 (merged 1ae41a1ca) owns managed legacy-local mode_mismatch self-heal on resume.

#3950 scope retained: ACP prompt correlation, content/limits/cancellation, todo synonym acceptance, bootstrap timing only.

Waiting fresh exact-head CI on 044ffc580 before merge.

—
ACP emergency lane red-team (terminal)

[Yeachan-Heo]

Red-team — MERGE_READY / CLEAR

Exact head: 044ffc58051e6856db504679339cc1d11b3ecc8b | Dev CI: run 31145275075 success (24 success / 6 skipped / 0 failure)

Scope (after strip of managed-legacy-local)

ACP prompt settlement, content/limits/cancellation conformance, mid-prompt correlation, todo-write synonym/addressing, reverse-leases/host wiring tests. Explicitly dropped managed-session-storage ownership (belongs to #3976, already merged).

Review

• Large but coherent ACP/SDK contract surface with proportional tests.
• Non-overlapping with #3979 CI matrix.
• mergeable_state: clean on current dev.

Verdict

MERGE_READY / CLEAR

— census terminal red-team

[Yeachan-Heo]

Terminal red-team (exact head 044ffc5)

Verdict: MERGE_READY / APPROVE

• Contract: ACP prompt settlement, content/limits/cancellation conformance; todo-write continue correlation.
• Scope (post-cleanup): ACP adapter, agent-session continue path, todo-write, tests — no managed-session-storage / baseline mode_mismatch ownership (that lives in merged #3976).
• Exact-head CI: green (24 success / 6 skipped); mergeable=clean; contains current origin/dev.
• Independent of #3846/#3764 perf red chains and notifications baseline.

Merge authorized.

[probepark]

Re-verified the reduced-scope head 044ffc580 live, since my earlier Paseo evidence was collected before the managed-legacy-local ownership transfer to #3976. Everything still holds with those files back at origin/dev.

Compiled binary from 044ffc580, broker restarted with --close-session-hosts so no stale host could serve the turn.

Check	Result
continuation prompt (#3949 path)	completed in 26s
follow-up turn + file write	completed in 19s, file correct
cancel mid-turn	settles to idle, no transport error
initialize	mcpCapabilities = {"http":true}

Transcript confirms the regression path is exercised — the same session/prompt covers a todo_write, the answer, a continuation, and a second todo_write:

[User] Reply with exactly: SCOPED-3950-OK
[Think] todo_write
- [ ] Confirm literal reply token requested by user
- [ ] Emit exact token SCOPED-3950-OK verbatim
- [ ] Verify reply contains no extra text
SCOPED-3950-OK
[Think] Failed: todo_write        <- typed rejection from this PR; model self-corrects
[Think] todo_write
- [x] (all three)
SCOPED-3950-OK

Tests on 044ffc580: 175 pass / 0 fail across acp/, acp-prompt-conformance, acp-initialize-conformance, sdk-acp-adapter, sdk-acp-production-path, sdk-host-wiring, sdk-reverse-rpc, tools/todo-write, task/no-session-output-refs.

One note on task/no-session-output-refs, since I nearly filed it as a regression: I saw shares one root and ID space with authorized descendants but denies foreign trees time out at 5s twice on this head while it passed on dev. It reproduces only immediately after a restart:sdk-broker --close-session-hosts that tore down ~35 hosts; three consecutive clean runs on the same head pass 17/17. So it is teardown-adjacent flake in my environment, not a scope-transfer regression — flagging in case the same 5s timeout shows up on a contended CI shard.

[Yeachan-Heo]

Red-team verdict: MERGE_READY → merging

Head: 044ffc580 | CI: 24 success / 0 fail

Scope (ACP/prompt only after ownership strip)

• Prompt correlation across mid-prompt continuations (ACP session/prompt never settles when the agent continues mid-prompt (hangs until the 30-minute deadline) #3949)
• ACP prompt content echo, size limits, cancel/close → cancelled
• Bootstrap session updates after response names session (ACP conformance: user images never render, oversize prompts kill the session, cancel surfaces as an error, MCP SSE falsely advertised #3962)
• todo_write synonym acceptance
• No managed-session-storage / legacy-local authority (owned by fix(session): resecure managed legacy-local mode_mismatch on resume #3976)

Adversarial checks

• Correlation claim only when no active correlation; continuation holds predecessor agent_end
• Oversize prompt fails typed without killing session
• Managed-authority duplicate removed; sole owner remains fix(session): resecure managed legacy-local mode_mismatch on resume #3976

Residual risk

• Low-medium: multi-commit ACP surface; exact-head green + conformance tests

Verdict: MERGE_READY

—
ACP emergency lane red-team (terminal)