Repository navigation
Close out the 2026-08 architecture review #299
Description
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/--warmexamples 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 overDevpodMachineand a pytest over the shim - Re-scope the public-API snapshots —
devlaunch-runnergets 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/Provisionimpls move into core with injectable sinks,apire-exports every constructor parameter type, andColdRefusedbecomes 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_cmdonly, 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
--forceflag-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--rmrework deletedverb_commandand refuses--rm --forceunconditionally 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
--helpin both directions, zero exemptions, no allowlist (#307, PR Delete the never-implemented worktree-backend docs, and guard README against --help #356) --ignore-not-foundfixed and one shared argv corpus drives both devpod fakes, its sevenunverifiedrows 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-runnerhas 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_cmddev-dependency is dropped, six crates leave the lockfile (#341, PR Drop the unused assert_cmd dev-dependency #342)
Activity
1 remaining item
docs: name the third escaper copy instead of claiming there is one
blooop commentedon Aug 22, 2026
handoff
Run paused 2026-08-22 — out of credits, not a blocker on the work. Four in-flight subagents were stopped deliberately; their worktrees and branches survive, so nothing is lost.
Where we are. All six decision tickets are closed. Nine PRs are open; none can merge without a human, which is the binding constraint on the rest of this map.
First moves on resume, in order.
DRAINED/INHERITED_IGNOREagreement test; Split the API snapshots: runner crate, api-vs-rest #347's green-on-nothing process substitution, same-device staging, and the README claim about failed runs; Guard dl.bash's tables against the grammar, and complete the five missing flags #351's two vacuous extractors, the falsedl.bashcomment, and the mis-blamingDL_VALUE_OPTIONSreuse.Fog that graduated during the run, all parented here and all discovered by reviewers reproducing rather than trusting: #346, #349, #352, #354, #355, #356n(=#357). Each is blocked on the PR whose work it depends on.
One standing note for whoever resumes. Every review on this map has been worth its cost — three of the first four returned reproduced defects, and reviewers twice overturned a builder's claim and once overturned a decision the human had made (#301's process-group half, reversed on measurement). The recurring defect class is not broken code but claims the code does not honour: docstrings, README lines, CI guards and one decision record. Three PRs were sent back for it. Keep holding that line — it is what this map is for.
blooop commentedon Aug 22, 2026
breadcrumb: the base moved under this map, and it invalidates work in substance rather than only in text.
mainis now 68 commits ahead of this map's base (a1c6fe8, the review commit). Three of those commits land inside work this map has open:b6b637f— "--rmis docker's--rm; retire--stop,--autormand the suffix override."--stopand--autormare now recognised-and-refused at exit 1, and--rmmeans what--autormmeant. This invalidates part of PR #351 (Guard dl.bash's tables against cli.rs #311): its first slice adds--stopand--autormto the completion table, and its third slice asserts that a word the CLI recognises only to refuse must never be completable. Against current main the PR contradicts its own principle.5e39c45and8976829both changepublic-api.txt, the file PR #347 (Split the API snapshots: runner crate, api-vs-rest #338) splits. Its three checked-in snapshots are generated from a stale source, and the union-equals-original property has to be re-established against the new original — the 37 + 2284 = 2321 and "42 of 79" figures will have moved.f5e0fddtouches the prune/force refusal wording, adjacent to PR #344 (Close the --force flag-verb bypass #303), which is nowCONFLICTINGinrust/dl/src/cli.rsandgrammar.rs.Mergeability right now: #344 and #347 conflicting; #342, #343, #345, #348, #351, #353, #356 mergeable.
A gate hazard worth writing down, found by #304's builder rather than by me. GitHub computes no merge commit for a conflicting PR, so the
pull_requesttrigger produces no run at all — not pending, not failed. The checks list looks sparse rather than red, and the last green reads as though it covered the new head. Any approval on this map recorded while a PR was conflicting rests on CI that never ran for that commit. From here, mergeability is checked alongside the checks, and a run is confirmed to exist for the head SHA before a gate is called passed.No decision is needed for the rebasing itself — it is forced work. What needs judging per ticket is whether the move changed the premise: #311 is the clear case, and its ticket needs re-reading against the new grammar before its PR is fixed.