persist · git:20261021.50a3d1b · 2026-10-21 · sha256 03e48f4f1381cb72

persist git:20261021.50a3d1bA

Immutable. This exact content never changes and is served at /api/v1/blob/03e48f4f1381cb72.

---
name: persist
tier: D
primitive: P12
category: orchestration
description: "bstack P12 — Persistent Loop Discipline. Cross-context restart loop where state lives in the filesystem (PROMPT.md + git tree + state.jsonl), not in the conversation. Each iteration spawns a fresh agent context. Solves the failure mode where work that must outlive one session loses its state when the session ends, and where a loop that keeps re-trying one fix never gets a clean start. Validation backpressure comes from compilers/tests/linters, not model self-grading. Use persist when: (1) starting work that must outlive the session (overnight, unattended), (2) the same fix failing repeatedly in one session, (3) coordinating long-horizon work that needs to survive crashes / context exhaustion, (4) running parallel work streams (one persist loop per worktree, composed with bstack P5). Triggers on 'persist', 'long-horizon loop', 'context restart', 'fresh-context iteration', 'P12', 'Ralph loop', 'filesystem-state loop'."
---

# 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](https://metr.org/blog/2026-1-29-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

```bash
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](https://github.com/broomva/bstack/blob/main/references/primitives.md) — full primitive contract

## Background

Pattern popularized by Geoffrey Huntley as ["everything is a ralph loop"](https://ghuntley.com/loop/) (Jan 2026). Anthropic shipped a [`ralph-wiggum` plugin](https://github.com/anthropics/claude-code/blob/main/plugins/ralph-wiggum/README.md); OpenAI shipped [`/goal` in Codex CLI 0.128.0](https://simonwillison.net/2026/Apr/30/codex-goals/). bstack's P12 is the same mechanism with non-anthropomorphized naming and explicit composition with the rest of the bstack contract.