Close out the 2026-08 architecture review

[blooop]

Destination

Every finding from the 2026-08-21 architecture review is closed: the two critical defects (capture-timeout hang, --force flag-verb bypass) fixed test-first, each hand-maintained duplicate of one fact single-sourced or machine-guarded, and the public-API freeze re-scoped so its diff signals again — each landed as a reviewed PR.

Notes

Steering (2026-08-21): decision tickets on this map are settled with the human in the loop — grill, do not agent-decide. Research and prototype tickets likewise wait for the executing run; nothing was auto-fired at charting. Execution is handed to a separate agent.

Source: the 2026-08-21 architecture review of this repo at d890ad1 (v0.3.3); findings carry file:line evidence and are restated in each ticket. Sibling map Drift-proofing rapid development explores the standing practices that stop these classes recurring; this map fixes today's instances. Build tickets run wf-tdd; type-shaping tickets consult constructive-modeling. Ordering note: the builds that churn many pub paths (lifecycle split, WorkspaceId threading, the api::Launch pair) are blocked on the snapshot re-scope build Split the API snapshots so the snapshot files move once, not twice. Update (2026-08-28): that blocker is cleared, #338 is merged, so #314, #316, #339, #340, #346 and #352 are unblocked; the 2026-08-22 handoff's picture of blocked PRs no longer holds. Of these, #340 is itself the gate for #397 and #411 on map #406.

Decisions so far

• Kill strategy for a timed-out capture — revised after measurement: the process-group/killpg half is dropped (it made captures take SIGTTIN on terminal reads and orphaned them on Ctrl-C); the drain joins are bounded on both the timeout and success paths, and that alone is the fix (human)
• Worktree-backend README section: delete or implement — delete: drop the never-implemented --shared/--warm examples and the false worktree claims, keep the accurate push-then-launch subsection, retire the stale spec
• One conformance corpus for both devpod fakes — one shared argv→outcome JSON corpus in test/fixtures/devpod/, driven by a Rust test over DevpodMachine and a pytest over the shim
• Re-scope the public-API snapshots — devlaunch-runner gets its own snapshot; core's splits into api-only (the promise) and rest (the tripwire); no visibility shrink
• Make api::Launch self-sufficient and type ColdRefused — the real ColdMachinery/Provision impls move into core with injectable sinks, api re-exports every constructor parameter type, and ColdRefused becomes a sum over the startup reasons
• portable-pty and assert_cmd: drop or build the pty harness — half overtaken on main (aid's pty harness now exists); drop the unused assert_cmd only, no dl pty harness
• Capture and session timeout hang fixed: the drain joins are bounded on both paths, the killpg reversion is pinned by pty tests that go red if it comes back (#302, PR Fix the capture and session timeout hang #343)
• The --force flag-verb bypass is dead, but not via its PR: Close the --force flag-verb bypass #344 was approved then closed unmerged, and the --rm is docker's --rm: retire --stop, --autorm and the suffix override (0.9.0) #369 --rm rework deleted verb_command and refuses --rm --force unconditionally ahead of every ordering; the argv-space property guard never landed, that residue is The word grammar's --force rule is unguarded in the same way #354 (#303)
• SIGTERM and SIGHUP now run the SIGINT drain (#304, PR SIGTERM and SIGHUP run the SIGINT drain #348)
• The never-implemented worktree-backend docs are deleted and the README is guarded against --help in both directions, zero exemptions, no allowlist (#307, PR Delete the never-implemented worktree-backend docs, and guard README against --help #356)
• --ignore-not-found fixed and one shared argv corpus drives both devpod fakes, its seven unverified rows since measured against real devpod; guard-decay residue is The conformance corpus's guards can lose a row silently #357 (#310, PR Fix --ignore-not-found and drive one conformance corpus through both devpod fakes #353)
• dl.bash's completion tables are guarded against cli.rs and the five missing flags completed (#311, PR Guard dl.bash's tables against the grammar, and complete the five missing flags #351)
• The JSON escaper and shell quote are single-copied onto core's, proven a byte-for-byte no-op by a full-scalar-space differential sweep; the DEL divergence split out to metadata.json writes DEL as a raw byte where CPython escapes it #349 (#315, PR Single-copy the JSON escaper and the shell quote #345)
• The API snapshots are split: devlaunch-runner has its own, core's is a true line partition into api-only and rest, with a control proving the CI guard non-vacuous (#338, PR Split the API snapshots: runner crate, api-vs-rest #347)
• The unused assert_cmd dev-dependency is dropped, six crates leave the lockfile (#341, PR Drop the unused assert_cmd dev-dependency #342)

Not yet specified

Out of scope