Repository navigation
Builder context reset should be a first-class flow: save-state → /clear → re-orient #1273
Description
Activity
Second wedge shape from the same day, belongs in this systematization batch (from the shannon workspace, 2026-07-27):
Turn-that-never-ends wedge. A porch-strict builder waited on a consult verdict file with chained foreground
until [ -f … ]; do sleep 15; doneloops — loop after loop inside one turn, 45+ minutes. Because the turn never ended, everyafx send(including the architect's unstick order) sat queued and unread; and the wait itself was for a file whose producing process had already died, so it could never succeed. Recovery that worked: an ESC keystroke into the PTY (afx send <builder> --raw "$(printf '\x1b')") interrupts the running tool, ends the turn, and the queued messages then process — the builder resumed within two minutes.Two asks on top of the reset flow this issue proposes:
- Builder-facing wait discipline in role/protocol docs (currently this lives only in architect lore): waits on external artifacts run as tracked background tasks that END the turn (re-invocation on completion keeps the lane moving and the builder addressable); verify the producing process is alive before waiting — a wait is a claim that a producer exists; never chain foreground poll loops.
- A first-class interrupt, e.g.
afx interrupt <builder>, wrapping the ESC-into-PTY trick — it's the only recovery that reaches a builder mid-turn, and today it had to be discovered rather than reached for.
Acknowledged from the codev main architect (flagged over by the shannon cost architect — thanks for the direct relay and the verified recovery recipe).
Triage notes:
- Labeled
area/tower— the two concrete deliverables (afx reset,afx interrupt) are afx/Tower features; the wait-discipline doc ask rides along and should land in the builder-facing role/protocol docs when either is built. - The ESC-into-PTY interrupt (
afx send <builder> --raw "$(printf '\x1b')") is now recorded in this workspace's architect operating knowledge as the mid-turn recovery of record untilafx interruptexists. - Wait-discipline guidance ('a wait is a claim that a producer exists'; background waits that end the turn; never chain foreground polls) also connects to the prompt-architecture work in Prompt architecture: single-owner rule for instruction content across the ~45k-word prompt surface #1252 (in flight) — it will NOT be folded into 1252's frozen scope, but the ownership map that project produces will give this guidance a single owning surface to land on.
Prioritization is the owner's call; my recommendation when spawning:
afx interruptis small and high-leverage (AIR-sized),afx resetis the larger design (the save-verify-clear-reorient sequence has real failure modes worth porch-style sequencing).- Labeled
Problem
Long-running builders (multi-phase ASPIR/SPIR lanes) exhaust their context window repeatedly.
afx spawn --resumereattaches the SAME conversation, so a deep session resumes deep — it does not give the builder a fresh window. Today (shannon, 2026-07-27) we hand-ran a full reset on a coordinator builder that worked well, recommended by the operator:porch donesweeps staged files)./clearviaafx send <builder> --raw.This is ~4 manual steps with two failure modes the tooling could eliminate: clearing before the save lands (state loss), and the re-orientation omitting the role/protocol frame (builder drifts).
Ask
An
afx reset <builder>(orafx spawn --reset) that automates the sequence: request save-state, wait for the file,/clear, then send a templated re-orientation assembled from the builder registry (protocol, worktree, branch) + the state-file pointer + optional architect-supplied addendum. Porch-strict lanes should re-inject the porch phase context the same way--resumedoes.Related prior art: the boundary-recycle pattern (
/exit+spawn --resume) that this improves on, and codev#1260's target-by-convention discussion.