Builder context reset should be a first-class flow: save-state → /clear → re-orient

[waleedkadous]

Problem

Long-running builders (multi-phase ASPIR/SPIR lanes) exhaust their context window repeatedly. afx spawn --resume reattaches 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:

1. Architect instructs the builder: write complete working state to an UNTRACKED file at the worktree root (role, receipts, open questions, standing orders — written for a cold reader; untracked because porch done sweeps staged files).
2. Architect verifies the file exists and is substantive before proceeding (ours was 203 lines).
3. Architect sends /clear via afx send <builder> --raw.
4. Architect sends a re-orientation message: role + protocol + worktree/branch, pointer to the state file, plus anything that post-dates the save.

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> (or afx 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 --resume does.

Related prior art: the boundary-recycle pattern (/exit + spawn --resume) that this improves on, and codev#1260's target-by-convention discussion.

[waleedkadous]

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; done loops — loop after loop inside one turn, 45+ minutes. Because the turn never ended, every afx 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:

1. 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.
2. 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.

[waleedkadous]

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 until afx interrupt exists.
• 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 interrupt is small and high-leverage (AIR-sized), afx reset is the larger design (the save-verify-clear-reorient sequence has real failure modes worth porch-style sequencing).