persist — bstack P12 Persistent Loop Discipline

Cross-context restart loop. State in filesystem, not conversation.

The defining moves:

1. The agent writes a goal + state snapshot to PROMPT.md
2. persist iterate PROMPT.md spawns a fresh agent context per iteration
3. State persists in the filesystem (PROMPT.md + git tree + state.jsonl)
4. Validation backpressure: compilers/tests/linters, not model self-grading
5. Loop exits when success_condition fires OR budget exhausted OR user interrupts

Why this exists

Work that must outlive one session needs state that survives the conversation. Persist restarts the context every iteration while keeping state in the filesystem, so the loop survives session ends, crashes and repeated failed attempts. METR's Time Horizon 1.1 put Opus 4.6's 80%-reliability horizon at about an hour; that is a measurement of an older model, and current models run a 1M context with automatic compaction in Claude Code, so it is context for the design, not a trigger.

When to invoke

The reflexive trigger rule (full text in workspace AGENTS.md §P12):

1. Before starting work that must outlive this session — write PROMPT.md, decide budget, pick success condition. Call persist iterate when it should run unattended (an overnight run); when it is paused for a later session, leave PROMPT.md for the session that resumes it.
2. When the same fix has been attempted ≥3 times without convergence — stop the in-context loop; write the diff history to PROMPT.md and start fresh.
3. When orchestrating long-horizon work — default to persist with periodic checkpoints; compose with P5 worktrees for parallel persist loops.

CLI

persist iterate PROMPT.md \
  --max-iterations 50 \
  --max-wall-clock 14400 \
  --success-condition "grep:DONE:STATUS" \
  --agent-cmd "claude -p '{}'"

persist status                  # show open loops
persist status --json           # machine-readable
persist abandon <loop-id>       # terminal: mark ABANDONED, free slot
persist doctor                  # health-check (state dir, git available)
persist conformance             # run test battery

The {} token in --agent-cmd is replaced with the prompt file's contents. Default agent is claude -p '{}'. Codex: --agent-cmd "codex {}". Gemini CLI: --agent-cmd "gemini -p '{}'".

Usage and rate limits don't burn the budget (BRO-3350). Sometimes a failed run ends with the harness's own limit message in its last 20 lines, such as "You've hit your weekly limit", "usage limit reached", "would exceed your account's rate limit" or "out of credits". That run is not counted as an iteration. Successful agent prose that merely mentions those strings is not treated as a limit. The loop records a PAUSED event with reason: rate_limited, waits, and retries the same iteration. The wait starts at --limit-backoff-base (60 s), doubles after each consecutive limited run, and is capped at --limit-backoff-max (3600 s), but never sleeps past the remaining --max-wall-clock budget. Before this fix, one weekly limit burned 80/80 and 160/160 iterations in minutes.

Success conditions

Three forms:

• exit-code-0 — last agent invocation returned 0
• file-exists:PATH — agent writes a sentinel file when done
• grep:PATTERN:FILE — agent writes a status line that matches PATTERN

The agent is responsible for updating PROMPT.md or writing the sentinel file at the end of each iteration. The script doesn't try to interpret agent output — that's the backpressure must come from external signals invariant.

State machine

SPAWNED ──→ ITERATING ──→ ITERATING ──→ ... ──→ SUCCESS (terminal)
                  │                          ╲
                  ↓                           ↘ BUDGET_EXHAUSTED (terminal)
              PAUSED ──→ ITERATING            
                  │
                  ↓
              ABANDONED (terminal)

State events append to ~/.config/broomva/persist/state.jsonl (JSONL append-only with flock).

Composition with bstack

primitive	composes via
P5 Parallel Agents	run N persist loops, one per git worktree
P7 CI Watcher	each iteration's pushed PR uses p9 watch for productive-wait
P10 Worktree Hygiene	clean tree before iteration; janitor after each merge
P11 Empirical Feedback	per-iteration validation; persist's success_condition is multi-modal evidence
P6 Bookkeeping	persist loops produce graph-relevant material → bookkeeping replay between loops

Invariants

• State lives in the filesystem. Each iteration starts from PROMPT.md content, not conversation history.
• Validation backpressure is external. Don't ask the agent "are you done?" — check exit codes, file presence, or status pattern.
• Budget bounds must be honored. Default 50 iterations / 4h wall-clock.
• State.jsonl is append-only. Loop terminations are terminal — no resurrection. To restart, spawn a new loop with a new ID.
• Each iteration is a fresh process. persist calls the agent CLI in a subprocess; agent context never persists between iterations except via filesystem state.

See also

• bstack workspace AGENTS.md §P12 — the binding reflexive trigger rule
• bstack/references/primitives.md — full primitive contract

Background

Pattern popularized by Geoffrey Huntley as "everything is a ralph loop" (Jan 2026). Anthropic shipped a ralph-wiggum plugin; OpenAI shipped /goal in Codex CLI 0.128.0. bstack's P12 is the same mechanism with non-anthropomorphized naming and explicit composition with the rest of the bstack contract.