Write-Ahead Intent Belongs Before Dispatch
Aug 17, 2026
A terminal-native runner looks like a CLI task: parse flags, call a host, print a result. That framing hides the real problem. The surface sits beside lifecycle authority, process dispatch, durable operational records, and mutable worktrees. If it can start workspace-writing work, it needs a structural safety design — not just command parsing.
The hidden failure is interruption after dispatch and before an outcome is recorded. In that window, a process that "started work" can leave no durable, addressable trace. Continuation then becomes guesswork. Write-ahead intent belongs before dispatch. Conservative halt belongs when that intent is unwitnessed.
The problem
A façade over an engine can make three mistakes that look like implementation details:
- treating a candidate transition as a permitted transition
- proving worktree safety in adapter tests while the production caller never compares
- inferring that the live command path is closed because helper-level tests are green
Those gaps matter most in the interruption window. Dispatch has happened. Outcome has not. If the runner crashes, the operator's next move has no honest record to continue from — unless intent was written first, and unless unwitnessed intent is treated as a halt rather than a resume.
What actually happened
One delivery that added a terminal execution surface stayed thin in authority. It reused the existing session host and dispatch seams. Transition candidates remained declared data, not permission. Recovery and reconciliation behaviour were deliberately out of scope.
The first specification still missed the interruption window. There was no durable, run-addressable trace between dispatch and recorded outcome. The rework added write-ahead attempt intent plus an unwitnessed-intent gate. That was a substantive correction, not terminology cleanup.
Build review then found three production-path defects that helper tests would not have caught:
- damaged manifest bindings could still be consumed
- worktree comparison was not being performed by the runner caller
- a post-transition manifest append failure was discarded
Each was fixed in the live command path, not only in helpers.
Compatibility constrained the worktree work. A stronger legacy adapter had to remain byte-identical, so the generic path used a parallel identity implementation with differential tests rather than a clean shared extraction. That preserved compatibility. It also left a documented duplicate-maintenance cost.
Verification stayed honest. A large hermetic suite, including targeted runner tests, passed independently. Live-provider smoke stayed segregated, with environment sensitivity recorded rather than folded into the hermetic gate. Residual risks were retained: conservative false halts after unwitnessed workspace-write intents, filesystem durability limits, timing sensitivity, live-provider dependence, and the deliberate compatibility deviations.
The lesson
Terminal runners that can dispatch workspace-writing workers need two things before they need a richer command set:
- Durable pre-dispatch intent — a write-ahead record that is addressable after a crash.
- Conservative continuation — if that intent is unwitnessed, halt rather than invent a recovery path.
Keep the runner thin. Use the host and dispatch seams that already own lifecycle. Do not let the CLI become a second controller.
Prove side-effect evidence at the production caller, not only at adapters. If a public manifest consumer can accept damaged bindings, helper tests that never reach that consumer are not closure.
The broader principle
Lifecycle-adjacent CLI work is auditable when plans name proof obligations across authority, worktree safety, dispatch, operational storage, and signals — and when build review asks whether each prior fix is reached through the production command path.
Independent verification should rerun the suite rather than trust builder counts. Live-provider proofs should remain separate from hermetic gates. Closeout should retain residual risk instead of overstating certainty.
One bookkeeping trap is worth naming because it is easy to copy: a closeout record that must name the commit that creates the same record. Design the ledger field as a documentation commit, or as a defined two-commit sequence. Do not require a document to tell the truth about a hash that does not exist yet.
How to apply it
- Start terminal and runtime-host items with an interruption matrix and write-ahead durability design before coding.
- Keep candidate transitions distinct from permitted transitions when a façade sits above an engine.
- Require tests at every public manifest consumer and at the production caller responsible for side-effect evidence.
- When a compatibility invariant forces a parallel implementation, add differential tests and record the maintenance cost.
- Keep real-provider smoke tests separate, with environment limitations stated plainly.
- In build review, ask: is each prior fix reached through the production command path?
- Check post-side-effect operational writes, including failures after the engine call returns.
- Do not infer production-path closure from helper tests or green totals.
