test(e2e): live validation of ACP agents, docs and ADR acceptance

[FreshlyBrewedCode]

Summary

This is the last layer of the ACP stack. It validates the whole change live, updates the docs, and accepts ADR 0013.

• Live leg (docs/findings/14-acp-live-leg.md). Setup:
  • factory serve on a spare port (3067), never 3005;
  • a scratch project scaffolded with factory init;
  • a local bare origin and a fake gh, so no write-back reaches GitHub;
  • a test db;
  • the UI driven with playwright-cli.
• Docs cover agent and model choice, agent.default / models / hostSettings, --agent/--model, and the requirements: a Claude login, or opencode on PATH.
• ADRs:
  • ADR 0013 is accepted, with the implementation's amendments.
  • ADR 0007 is superseded.
  • ADR 0012 gets a note that §3/§6 are amended.
  • Finding 13 gets "Later corrections".
• Fix (this layer): fix(web): every page load logged a TypeError (import.meta.env is undefined in factory serve's bundle).

Scenario results

#	scenario	result
1	implement-issue (implement → test → fix → test → structured pr-metadata → write-back) on Claude/haiku, started from the UI	pass: 57.0 s, $0.104. Run detail shows 24.5k/200k ctx · $0.059 per step
2	the same on opencode/big-pickle, started with factory start --agent opencode and watched in the UI	pass: 133.6 s. The branch collided and was retried with a suffix (D32)
3	two concurrent runs, one per agent	pass: 1 and 2 overlapped for 45 s, and no processes were left
4	opencode external_directory ask	pass: an ask for /tmp/…/outside, answered always; file written, tree clean
5	agent crash mid-turn (kill -9)	the step fails with the exit code and stderr tail. But the agent's in-flight tool processes are orphaned → #74
6	error from an agent	pass: a provider error (opencode-go/…-contributor) fails the step with the agent's message. Refusal (RUN_ERROR) could not be provoked live: Anthropic's test string gave end_turn on haiku and sonnet. The fake-agent unit test covers it
7	cancel from the UI (Claude, opencode)	pass: 0 of 4 / 0 of 2 processes alive 3 s later
8	daemon SIGTERM with both agents mid-tool	pass: exits in 108 ms, both runs RunCancelled, 0 of 6 processes alive 3 s later. #73's 1 s-vs-2 s concern did not show (agents settle cancel in ms) and is noted in #74

ADR 0013 amendments (from #69/#71/#72/#73 handoffs and this leg)

• §2:
  • the model is always set (claude-agent-acp reports the user's model, not the one it runs);
  • an unresolved model fails at step start, not run start;
  • there is no built-in model;
  • the run level is --agent/--model / POST /api/runs agent.
• §3:
  • the opencode isolation mechanism: XDG_CONFIG_HOME + a shell.env plugin + OPENCODE_TEST_HOME (undocumented);
  • the credential env vars the scrub keeps;
  • residue: Claude Code sources a snapshot of the operator's login shell (~/.claude/shell-snapshots). This is accepted, because CLAUDE_CONFIG_DIR holds the login.
• §4: write-back's data/ cleanup was removed.
• §5:
  • cost is the latest reported;
  • Claude's mid-turn window is 1M;
  • the acp.tool-call chunk.
• §6:
  • absolute cwd;
  • process cleanup (fix(runtime): a SIGKILLed agent leaves its in-flight tool processes running #74).
• Replay corpus format.

Issues filed

• fix(runtime): a SIGKILLed agent leaves its in-flight tool processes running #74 (bug, sub-issue of Epic: agents over ACP — opencode and Claude Code in workflows #62): a SIGKILLed agent leaves its in-flight tool processes running.
• feat(web): choose agent and model in the New run dialog #75 (task, sub-issue of Epic: agents over ACP — opencode and Claude Code in workflows #62): choose agent and model in the New run dialog. The UI can only start runs on the default agent today.
• fix(workspace): clone the run's tree at repo.baseBranch, not the origin's HEAD #76 (bug, pre-existing, not ACP): the workspace clones the origin's HEAD, not repo.baseBranch.

Checks

• bun run check: green (451 tests).
• nix develop --command bun run test:e2e: 17 passed.

Closes #67
Part of #62

🤖 Generated with Claude Code