Loop Supervisor

Loop Supervisor

Scaffold a SUPERVISOR.md runbook that captures how to supervise a specific agent loop. A fresh agent session (or a future you) reads that file, launches or attaches to the loop in tmux, watches state files, and intervenes sparingly per a project-specific taxonomy.

The supervisor's golden rule is always the same shape: operate the harness, don't do the inner loop's work. What counts as "harness" vs "inner work" is project-specific — that's what discovery pins down.

When to use

Invoke when the user has (or is about to have):

• A task-loop / ralph-loop / rl-style outer runner driving fresh agent

sessions against a PROMPT.md or equivalent contract

• State artefacts like run-log.md, loop-state.md, backlog.md, or

a domain-specific index (hypothesis tree, frontier state, etc.)

• A tmux session (or intent to launch one) where the loop runs

The output is a single file: TASKS/<name>/SUPERVISOR.md, co-located with the loop's other artefacts. Git-tracked — it's a contract that evolves with the project between runs, not ephemeral state.

What SUPERVISOR.md contains

Eight sections. Self-contained for taxonomy + golden rule so the file stands alone; references-based for mechanics (trusts the consumer has the tmux skill loaded rather than inlining capture-pane syntax).

Use references/runbook-template.md as the skeleton when generating the file.

1. Role + golden rule — one line setting the frame. 2. Mission + stop conditions — what success looks like, what exhaustion looks like, when to stop. 3. State files to watch — paths the supervisor reads each cycle. 4. Intervention taxonomy — project-specific triggers + responses. 5. Out-of-scope / don't-touch — the inner loop's domain. 6. Budgets — max interventions, poll cadence. 7. Escalation — Ctrl-C the loop pane, explain in the final message. No dedicated escalation file; the supervisor's last chat turn is the report. 8. Launch — tmux session name + launch command. Consumer runs tmux has-session -t <name> first; launches if absent, attaches if present (safety against double-start).

Process

1. Locate the loop

Find the loop this supervisor will watch:

• Glob TASKS/*/ for PROMPT.md + run-log.md pairs (task-loop shape)
• If multiple loops exist, ask which one
• If none, ask whether to scaffold one first via /task-loop — don't

try to supervise a loop that doesn't exist yet

2. Auto-infer silently

Before asking any questions, read what's already on disk:

• Tmux session name — tmux ls to see if a session is running

that matches the loop's directory name; if none, derive one from TASKS/<name>/ (e.g. <name>-loop)

• State file paths — anything in TASKS/<name>/ that looks like

state: run-log.md, loop-state.md, backlog.md, plus any INDEX.md, frontier-state.*, or similar domain-specific indices

• Stop token — whatever the loop's own contract declares as its

completion signal. Grep PROMPT.md / README.md / project docs for file-existence markers (e.g. FOUND_SECRET.txt) and emit tokens (e.g. __PROMISE_RL_DONE__ if the loop is task-loop / rl-shaped). Inherit what the loop already says rather than imposing a default.

• Launch command — if the loop ships a run command in its README

or PROMPT.md, use it verbatim. For task-loop / rl-shaped loops this typically looks like rl <N> -- cxys '<PROMPT.md path>'. Iteration count defaults to 100 unless specified or mentioned.

• Existing contract / preconditions — read the loop's PROMPT.md

(or equivalent) end-to-end. Absorb its declared preconditions (e.g. "build must be green before committing"), its own stop conditions, its scope boundaries. The supervisor should inherit these organically — they're not separate rules, they're already in the loop's contract.

• Context priors — read AGENTS.md / CLAUDE.md / project README

for terminology, conventions, existing supervision patterns.

Don't bother the user with any of this if it can be inferred.

3. Interview (grill-me style, one question per turn)

Ask only what needs human judgement. Aim for ~5 focused questions. Surface the catalogues from references/ as menus — the user picks from worked examples rather than generating from scratch.

Q1 — Golden rule (one line). What's the inner loop's domain, and what's the supervisor's domain? Frame with a motivating example: hackmonty's was "operate the harness, don't do the research"; for a source-port project it might be "keep lanes balanced and worktrees clean". Read references/golden-rule-examples.md for seed material.

Q2 — Top 3–5 project-specific triggers. Offer the catalogue from references/trigger-examples.md and ask which apply, plus any bespoke ones. Each trigger is a pair: detection signal (what you'd see in state files) + response (what the supervisor does).

Q3 — Authority stance. Pick from references/authority-stances.md: escalate-only (read + Ctrl-C + report), harness-only (edit loop contract, commit infra fixes, mark indices — never touch loop-domain artefacts), or autonomous (may commit anything, highest risk). Different projects justifiably want different stances.

Q4 — Intervention budget. Default 3 before hard stop. Lower for tight supervisors, higher for long runs where more drift is expected.

Q5 — Out-of-scope paths. What the supervisor must never touch. For harness-only: probe code, task implementations, hypothesis bodies. For autonomous: still worth listing anything sacred (secrets, migrations, production configs).

Skip any question the auto-inference in step 2 already answered.

4. Write SUPERVISOR.md

Fill in references/runbook-template.md with the interview results and inferred values. Write to TASKS/<name>/SUPERVISOR.md.

The consumer (a future agent session, potentially you, potentially a human) reads this file top-to-bottom. Make it self-contained enough that a fresh agent with just the tmux skill loaded can execute it.

5. Present and hand off

Tell the user:

• Where the file was written
• Which triggers + authority stance got captured
• How to start supervising: open a fresh agent session (or tell the

current one) to "read TASKS/<name>/SUPERVISOR.md and follow it." The runbook handles the rest — checks for the tmux session, launches if absent, attaches if present, begins supervision.

If the user wants to run it right now in the current session, just read the runbook back in and execute it. Otherwise hand off.

Composition

• `tmux` skill — the consumer loads this for session management.

SUPERVISOR.md never inlines capture-pane / send-keys — it describes what to watch, not how to read a pane.

• `task-loop` skill — scaffolds the loop SUPERVISOR.md watches.

If no loop exists yet, suggest /task-loop first.

• `task-plan` skill — produces the backlog that task-loop consumes.

Upstream of this skill by two steps.

• `grill-me` skill — the interview flow in step 3 follows its

one-question-per-turn discipline.

What this skill does not do

• No runtime execution. This skill only scaffolds the runbook.

Starting the loop + watching it happens when a consumer reads SUPERVISOR.md — not here.

• No runtime scripts bundled. Pure prompt + reference material.

The consumer uses its own tool access (tmux, filesystem, git).

• No live-update of SUPERVISOR.md mid-run. The supervisor treats

it as read-only during a run. New failure classes surface in the supervisor's final message; the human folds them in before the next run. Keeps the contract stable within a run.

• No generic shipped taxonomy. Everything in the generated

SUPERVISOR.md is project-specific. The references/ directory holds examples to pick from, not defaults to inherit.

Authority Stances

What the supervisor is permitted to do when it intervenes. Pick one stance as the project's baseline; individual triggers can still declare exceptions (e.g. "for this trigger specifically, only escalate").

Stances lie on a spectrum from hands-off to hands-on. Different projects justifiably pick different points. A tight pentest engagement might want escalate-only; a long-running source-port project with trusted infra tooling might want autonomous.

escalate-only

The supervisor does not write anything. It observes, reasons, and when it sees a trigger, sends Ctrl-C to the loop pane and explains in its final message.

• Reads: all state files, tmux pane, git log
• Writes: nothing — no files, no commits, no edits to the loop

contract

• Stops: yes, Ctrl-C on any trigger that would otherwise require

a write

• Good for: first-time supervision of a new loop (before you

trust what "off the rails" means here), security-sensitive work, loops where any side effect could leak or pollute state

Trade-off: Everything becomes a human escalation. Cheap to reason about, expensive in human attention.

harness-only (recommended default)

The supervisor may edit the loop's harness but never its domain. This is the hackmonty pattern.

• Reads: all state files, tmux pane, git log
• Writes:
• PROMPT.md — one-line clarifications / rhythm bullets, never

wholesale rewrites

• Index files (INDEX.md, frontier-state.yaml, equivalents) —

status transitions + one-line operator notes, never hypothesis bodies or task descriptions

• Runner / Docker / hook configs — full edits; these are harness

infrastructure

• Commits: yes, for harness / infra fixes only. Conventional

commit prefix chore(supervisor): or project equivalent. Never commit research artefacts or completed task output — that's the loop's job.

• Stops: yes, on success / exhaustion / budget.
• Forbidden: writing probe code, implementing tasks, filling in

hypothesis bodies, editing run-log.md (append-only, loop's territory), editing loop-state.md (ephemeral, loop's territory).

Good for: most autonomous research + task-loop setups. The supervisor can unblock genuine infra breakage without risking the loop's findings.

Trade-off: Requires a clear harness/domain boundary. If the project doesn't separate them cleanly, the supervisor keeps needing to ask "is this mine or the loop's?"

autonomous

The supervisor may touch anything. It uses judgement to decide whether to intervene harness-only or step into loop-domain work to unblock progress.

• Reads: everything
• Writes: everything, including loop-domain code, task

implementations, and hypothesis bodies if that's the pragmatic unblock

• Commits: yes, any category
• Stops: yes, on success / exhaustion / budget; also may pause

the loop, do work itself, then resume

• Guardrails the user should still declare:
• Secrets and credentials — never commit
• Production configs / migrations — touch only with explicit

annotation

• SUPERVISOR.md itself — not edited mid-run (regardless of

stance; see SKILL.md)

Good for: mature long-running projects where the user trusts the supervisor's judgement and wants maximum throughput. Also good for "just do the thing" modes when the user is away for a weekend and wants the loop to keep progressing even through novel failures.

Trade-off: Highest risk. The supervisor can mask real loop bugs by fixing symptoms itself, and can introduce scope creep that doesn't match what the user would have done. Require post-run review of all supervisor-authored commits.

Mixed stances

Nothing stops a SUPERVISOR.md from declaring a baseline and then listing per-trigger exceptions:

Baseline: harness-only.

>

Exceptions:

>

- mutation-corrupts-main-worktree → escalate-only (this is

never safe to fix automatically)

- silent-runner-death → autonomous (restart the runner with

any pragmatic fix, restart the loop)

Use this sparingly — it's easier to reason about a single baseline with one or two exceptions than a menu of stances per trigger.

Choosing

Ask the user:

1. How much do you trust the loop's harness? (Mature → autonomous; new → harness-only; brand-new → escalate-only) 2. How hands-on do you want to be between runs? (Reviewing every supervisor commit → escalate-only; happy to batch-review → harness-only or autonomous) 3. What's the blast radius of a bad intervention? (High → tight stance; low → looser)

Golden Rule Examples

The golden rule is the one-line frame for the supervisor — what's inside its domain and what's outside. It's load-bearing: every ambiguous judgement call during supervision should trace back to it.

Use these as seed material for the interview. Offer 2–3 as prompts and let the user adapt one, or write their own.

By project shape

Autonomous research / hypothesis-driven loops

Operate the harness. Fixing a broken runner or freeing a stuck

hypothesis is your job. Writing probes, forming hypotheses,

interpreting results is the inner loop's job.

Source: hackmonty. The clean harness/research split made supervision predictable — when a question came up, the rule answered it.

Source-port / long-running multi-lane projects

Keep lanes balanced and worktrees clean. Unblock the autonomy loop

from harness and isolation bugs. Writing game logic, reverse-

engineering the original, and deciding what to port next is the

inner loop's job.

Source: KC-style source-port work. The big failure modes are lane thrashing and worktree corruption, both harness concerns.

Build-green / CI-driven loops

Keep the build gate green and the runner healthy. Fix flakes,

missing dependencies, and infra races. The inner loop chooses

what to build, fix, or refactor.

Good for loops aimed at a specific passing-test or passing-build milestone.

Task-loop / backlog execution

Keep the loop consuming the backlog without tripping over infra

or state. Marking items blocked, fixing runner errors, and nudging

rhythm is your job. Implementing tasks is the inner loop's job.

Good default for `/task-loop`-scaffolded projects that just need to run a backlog to completion.

By authority stance

Escalate-only

Watch the loop. When anything looks wrong, stop it and tell me.

Don't try to fix anything yourself.

Pair with escalate-only authority. Suitable for first-ever supervision of a new project.

Autonomous

Keep the loop making progress. Fix anything that stops it,

implement anything it can't, commit when the project's conventions

say so. Use judgement on what I'd want. Flag anything surprising

in your final message.

Pair with autonomous authority. Suitable for mature projects where the supervisor is essentially a second pair of hands.

Patterns across all of them

Every good golden rule says two things:

1. What's yours — usually some variant of "harness", "infra", "loop rhythm", "unblock" 2. What's theirs — usually some variant of "the actual work", "domain decisions", "the research / code / content"

If the rule only says what's yours, the supervisor will drift into loop-domain work when things get hard. If it only says what's theirs, the supervisor won't know when it's allowed to act.

Keep it one sentence. The moment it becomes a paragraph, it stops being a rule and starts being a policy — and policies get skimmed, not internalised.

Runbook Template

Skeleton for TASKS/<name>/SUPERVISOR.md. Fill in the bracketed bits from the discovery interview + auto-inferred values. Leave the overall section order unchanged — the consumer reads this file top-to-bottom and the order matters (launch before watch, watch before intervene).

Template

# Supervisor — <project / loop name>

You are the supervisor for an autonomous loop running in this repo.
You have the `tmux` skill loaded and can read the filesystem + run git.
Follow this runbook in order.

## 1. Role + golden rule

<One-line role definition. Load-bearing.>

Example: "Operate the harness around the <name> research loop. Fixing
a broken runner or freeing a stuck hypothesis is your job. Writing
probes, forming hypotheses, interpreting results is the inner loop's
job."

## 2. Mission + stop conditions

**Mission:** <what the loop is trying to achieve, one or two sentences>

**Stop immediately on any of:**

- <success condition — e.g. `FOUND_SECRET.txt` exists at repo root>
- <exhaustion condition — e.g. all items in `backlog.md` checked, or
  all hypotheses in terminal state in `INDEX.md`>
- <budget condition — e.g. `rl 100` complete, intervention budget
  (3) spent, or wall-clock cap (12h) reached>
- <hard-failure condition — e.g. novel failure class, runner fix
  didn't hold, anything outside the taxonomy below>

On stop: send Ctrl-C to the tmux pane (see §8), wait for the current
iteration to finish cleanly, then summarise what happened in your
final message. No dedicated escalation file.

## 3. State files to watch

Read these each supervision cycle:

- `<path to run-log.md>` — append-only execution history; tail the
  last N entries
- `<path to loop-state.md>` — ephemeral per-iteration state (may be
  gitignored); look for status transitions
- `<path to backlog.md or index>` — work items + statuses
- <any domain-specific index: `hypotheses/INDEX.md`,
  `frontier-state.yaml`, etc.>
- `git log --oneline -n 20` — recent commits (catches scope creep)

Poll cadence: every 60–120 seconds is usually enough. Between polls,
capture the tmux pane once to catch crashes / harness errors the
state files won't show.

## 4. Intervention taxonomy

Each trigger has a detection signal, a response, and an authority
cap. Fire a response when you see a detection; stop (Ctrl-C + report)
if the authority cap says so.

<3–5 triggers, each formatted like:>

### <trigger-name>

- **Detect:** <what to read / grep / check>
- **Respond:** <concrete action, bounded by the authority stance>
- **Stops the run?** <yes / no>

<Example triggers:>

### stuck-hypothesis

- **Detect:** Same hypothesis ID in last 3+ `run-log.md` entries with
  barely-changing "probes planned"
- **Respond:** Flip status to `pruned` in `hypotheses/INDEX.md` with
  one-line operator note. Do not touch the hypothesis body.
- **Stops the run?** No

### runner-errors-twice

- **Detect:** Two consecutive `run-log.md` entries with verdict
  `error`
- **Respond:** Root-cause the runner / Dockerfile / hook; fix and
  commit. Never bypass checks.
- **Stops the run?** No

### mutation-in-main-worktree

- **Detect:** `git status` shows mutation markers in tracked source
  files
- **Respond:** Stop. This is never safe to auto-fix.
- **Stops the run?** Yes

## 5. Out-of-scope / don't-touch

You must not:

- <list of paths / categories the supervisor must not edit>

Examples:

- Probe / task implementation code under `<path>/`
- Hypothesis bodies (status field + one-line operator note only)
- `run-log.md` (append-only, inner loop's territory)
- `loop-state.md` (ephemeral, inner loop's territory)
- `SUPERVISOR.md` itself (no live-update; surface new failure classes
  in your final message for the human to fold in)

## 6. Budgets

- **Max interventions before hard stop:** <N, default 3>
- **Poll cadence:** 60–120 seconds between full state-file reads
- **What counts as one intervention:** <project-specific; e.g. "one
  commit OR one PROMPT.md edit OR one index-status flip">

When you hit the intervention cap, stop regardless of whether triggers
are still firing. The loop may need more than surface fixes and that
belongs with the human.

## 7. Escalation

There is no dedicated escalation file or notification channel.

When you need to stop (success, exhaustion, budget, hard failure, or
anything you can't classify):

1. Send Ctrl-C to the tmux pane (see §8 for pane coordinates). First
   Ctrl-C interrupts the current iteration cleanly; second Ctrl-C
   exits the `rl` outer loop if you need to end immediately.
2. Capture the pane tail into your message.
3. Summarise in your final chat turn:
   - What you supervised (wall-clock, iterations run)
   - What stopped the run (which condition fired)
   - What interventions you made, in order, with commit SHAs
   - Anything outside the current taxonomy that's worth folding in
     next time (the human edits `SUPERVISOR.md` between runs; you
     do not edit it mid-run)
4. Leave the tmux session alive unless the user said otherwise —
   they may want to inspect the pane.

## 8. Launch

**Tmux session:** `<session-name>`

**Launch command (only if the session doesn't already exist):**

<launch command, e.g. rl 100 -- cxys 'TASKS/<name>/PROMPT.md'>

**Startup sequence:**

1. `tmux has-session -t <session-name>` — check for an existing session
2. If the session does not exist:
   - Create it and run the launch command
   - Wait for the first `run-log.md` entry to appear (confirms the
     loop is actually making progress, not stuck at a harness error)
3. If the session already exists:
   - Attach by capturing the pane, confirm it looks healthy
   - Do not re-launch — re-launching a running loop will corrupt
     state
4. Begin §3–§4 supervision cycle.

Adaptation notes

• Keep each section short. The consumer reads this top-to-bottom

every session. Bloated sections waste tokens and dilute the actually-important triggers.

• Inline the golden rule (§1). Don't offload it to a reference.

It's the single most load-bearing line in the file.

• Don't inline tmux syntax. The consumer has the tmux skill.

Describe what to watch; let the skill handle how.

• Keep §4 triggers copy-pasteable. A future human reading the

file should be able to fold a new trigger in without cross-referencing this template.

• Name the tmux session deterministically. Something derived from

the loop directory (e.g. <name>-loop) so re-invocations find the same session. Ad-hoc names break the has-session check.

Stop Conditions

When the supervisor ends the run. Every SUPERVISOR.md needs at least one stop condition per category: success, exhaustion, and failure. Otherwise the supervisor has no reason to ever stop watching.

Pick from the patterns below, combine, or write project-specific ones.

Success patterns

File-existence marker

The loop writes a specific file at the repo root (or agreed path) when it achieves its goal. Supervisor polls for the file each cycle.

• Examples: FOUND_SECRET.txt (hackmonty bounty), BUILD_PASSED.md

(build-green milestone), RELEASE_READY.txt (deploy gate)

• Detection: [ -f path/to/marker ] && stop
• Why it works: Atomic (the loop writes it last), durable

(survives crashes), un-ambiguous

• Caveat: Make sure the loop contract says what goes in the

file (e.g. the secret + exploit path for hackmonty) so the supervisor's final message can report it

Emit-token

The loop prints a sentinel string on its own final line when done. rl picks this up and exits the outer runner; the supervisor sees the tmux pane return to a shell prompt.

• Default: __PROMISE_RL_DONE__ (task-loop's built-in)
• Custom: __WEEKEND_BUILD_DONE__, project-specific tokens
• Detection: grep the tmux pane for the token, or watch for

the shell prompt returning without a re-launch

• Why it works: No extra file state; cleanly integrates with

rl's promise-token handling

All-work-exhausted

All tracked work items reach a terminal state.

• Backlog loops: no [ ] checkboxes remain in backlog.md
• Hypothesis loops: all hypotheses confirmed / refuted / pruned

in INDEX.md

• Multi-lane loops: every lane's frontier state is closed
• Detection: grep/parse the relevant index file each cycle
• Why it works: Aligns with the loop's own definition of done

Exhaustion patterns

Iteration budget spent

The outer runner's iteration count is complete.

• Detection: rl N runs the loop N times then exits; the tmux

pane returns to a shell prompt. Or: count run-log.md entries and compare to N.

• Why it works: Guarantees bounded wall-clock; forces periodic

human review

• Caveat: The loop might not have finished useful work — the

final message should make "what's left" obvious

Wall-clock cap

Cap the total run time.

• Detection: Capture start time at launch; each cycle, compare

now vs start + budget. Default: 12h for overnight runs, 48h for weekend runs.

• Why it works: Bounds real-world cost (compute, your

attention). Good layered with iteration budget

• Caveat: Needs a persistent start-time record if the supervisor

session might restart mid-run

Intervention budget spent

The supervisor has hit its maximum allowed interventions (default 3 from the skill's convention).

• Detection: Supervisor counts its own interventions in its

reasoning; stops on the N+1th.

• Why it works: Forces escalation when the loop needs more than

surface fixes. Prevents the supervisor becoming the inner loop by accident.

• Caveat: Needs a sharp definition of what counts as "an

intervention" (one commit? one trigger firing? one PROMPT.md edit?). Document it in SUPERVISOR.md §6.

Failure patterns

Hard-stop triggers

Some triggers are D-class — they stop the run immediately regardless of budget. See trigger-examples.md.

• Examples: mutation corrupting main worktree, secrets leaking to

commit messages, the loop somehow modifying SUPERVISOR.md or other supervisor-owned files

• Response: Ctrl-C the pane, explain, stop. Don't try to fix.

Repeated runner failure after fix

Supervisor fixes a runner error; next iteration errors again the same way.

• Detection: run-log.md shows two error verdicts with the

same class, with a supervisor commit between them that should have fixed it

• Response: Stop. The fix didn't work; escalate to the human.

Novel failure outside the taxonomy

Something happened that isn't in the current SUPERVISOR.md taxonomy, and the supervisor can't classify it.

• Detection: supervisor's own judgement — a state that doesn't

match any trigger pattern

• Response: Stop. Final message explains the novel state. Human

folds it into the taxonomy before the next run (live-update is explicitly disallowed mid-run).

Minimum viable set

At absolute minimum, every SUPERVISOR.md needs:

• One success condition — so the supervisor knows what winning

looks like

• One exhaustion condition — so the supervisor doesn't watch

forever on an unwinnable run

• The generic failure escalation — Ctrl-C + final message on

anything novel

Three lines of YAML-or-markdown covers this; more is fine.

Trigger Examples

Catalogue of "off the rails" patterns seen in autonomous loops. Each entry is a trigger the user can lift wholesale, adapt, or ignore. Don't copy the whole list into SUPERVISOR.md — pick the 3–5 that match the project.

Each trigger has three parts:

• Detection — what the supervisor reads to notice it (file

content, git state, tmux pane scan, commit streak)

• Response — what the supervisor does. Bounded by the project's

authority stance (see authority-stances.md)

• Provenance — where the pattern came from, so the user can

judge whether it transfers

Research / hypothesis-driven loops

Same hypothesis/task N iterations, no narrowing

• Detection: The same task ID or hypothesis ID appears in the last

N run-log.md entries (default N=3), and its "next step" / "probes planned" / "checklist" barely changes between entries.

• Response: Mark the item as exhausted in its index file (e.g.

flip status to pruned with a one-line operator note explaining why — "cycled 3× without narrowing scope"). Do not rewrite the hypothesis or task body. Let the loop pick the next item naturally.

• Provenance: hackmonty H007 — 11 probes cycled through variants

of "go colder / longer delay" without info-gain; one intervention marked it pruned, loop resumed and terminated cleanly.

Inner loop locked onto one branch, ignoring breadth

• Detection: Recent run-log.md entries all touch the same

task/hypothesis while other high-promise unchecked items sit idle for N+ iterations, violating the loop's own selection rules.

• Response: Add one terse clarification bullet to the loop

contract (PROMPT.md) nudging toward the selection rule the agent is drifting from. Don't rewrite the prompt. Commit if the change was to harness files.

• Provenance: hackmonty iter 12–82 — agent bisected H001 for 8+

probes ignoring untouched H003/H004/H011 with higher info-gain priority. One-bullet nudge to PROMPT.md §5 flipped behaviour on the next iteration.

Infrastructure / runner failures

Runner errors twice in a row

• Detection: Two consecutive run-log.md entries with verdict

error / runner_failed / Docker / permission / harness fault.

• Response: Root-cause the runner / Dockerfile / hook / template.

Fix and commit (if harness files). Never bypass checks (no --no-verify, no chmod 0777 shortcuts). Resume with remaining iterations.

• Provenance: hackmonty docker/run-probe.sh had transient

permission races; expected failure mode.

Loop silently stopped

• Detection: tmux pane shows shell prompt (not an rl

iteration), run-log.md hasn't grown in > threshold wall-clock, and no completion token was emitted.

• Response: Capture the pane tail into the supervisor's notes,

inspect for crash cause (OOM, segfault, network), fix if trivial, otherwise escalate.

• Provenance: general pattern — runners die silently more often

than expected.

Scope creep / contract violations

Inner loop editing files outside its domain

• Detection: git diff HEAD~<N>..HEAD --name-only shows files

outside the paths the loop contract lists as its domain (e.g. loop touched PROMPT.md, SUPERVISOR.md, or repo-level configs).

• Response: Depends on authority stance. Harness-only supervisor:

revert the out-of-scope hunks with explanation, add a clarifying bullet to PROMPT.md §out-of-scope. Escalate-only: stop and report. Autonomous: judge case-by-case — sometimes the loop correctly noticed a harness bug and fixed it.

• Provenance: hackmonty out-of-scope list explicitly forbade the

loop from committing research state; a stray commit would trigger this.

Loop rewriting its own contract

• Detection: PROMPT.md shows modifications in git log attributed

to loop iterations (not operator interventions).

• Response: Revert. The loop contract is the supervisor's

(or human's) domain — the loop can surface complaints but not edit. Add a don't-touch bullet if missing.

• Provenance: hackmonty classified this as intervention-C

("bad loop rhythm") — a symptom the agent was burning tokens on meta rather than probes.

Source-port / long-running multi-lane loops

Mutation / stress testing corrupting main worktree

• Detection: git status in the main worktree shows modifications

to source files that weren't part of any commit — tool-injected mutation markers, test fixtures left in place.

• Response: Stop immediately. This is a D-class trigger (hard

stop, not fix-and-resume) — background agents must run in isolated worktrees. Document the fix requirement in the final message.

• Provenance: KC — cargo mutants --in-place running against

the main worktree repeatedly corrupted enemies.rs, blocks.rs, physics.rs. Root cause: missing worktree isolation in the autonomy spawner.

Strategy lane thrashing

• Detection: Recent commits or run-log entries cycle across

multiple strategy lanes (coverage-drive → mutation-testing → enemy-audit → …) without completing any one, or the loop selects the same strategy N+ times consecutively without varying.

• Response: Pin the loop to a single lane for M iterations (edit

the strategy-selector config if the harness exposes one). Surface in the supervisor's final notes if the root cause is a broken prioritiser in the loop contract.

• Provenance: KC autonomy — "loc-coverage-drive" had no throttle

and produced busywork; selector was blind to ledgers.

Ignored handoff / ledger

• Detection: Loop produces a handoff doc (next-agent.md) or

rejected-hypothesis ledger, but subsequent iterations don't read it — visible in run-log entries that repeat prior dead-ends.

• Response: Add a read step to the loop contract's preamble

pointing at the handoff file. If the loop already has one and is skipping it, escalate — the loop has a reading-order bug, not a rhythm bug.

• Provenance: KC — rejected-hypothesis ledger was written but

never consumed, leading to repeated dead ends.

Rhythm / meta drift

Agent burning tokens on meta

• Detection: tmux pane shows long think blocks, reads the same

files repeatedly, minimal tool calls relative to iteration wall-clock. run-log.md entries show high token counts with no code changes.

• Response: Add a terse bullet to PROMPT.md preamble reminding

the agent of its scope and the one-read-per-file convention. Don't rewrite the prompt.

Skipping required steps

• Detection: run-log.md entries missing fields the contract

declares mandatory (e.g. no commit SHA, no verification output).

• Response: Bullet in PROMPT.md enforcing the field. If the

agent keeps skipping, it's a D-class escalation — something deeper is wrong.

Stop conditions (not triggers, but live in the same section)

Success signal

• Detection: The project's success file exists (e.g.

FOUND_SECRET.txt, BUILD_PASSED.md) or the loop emitted its stop token (__PROMISE_RL_DONE__).

• Response: Stop immediately. Don't run "just one more iteration".

Report in final message.

All work exhausted

• Detection: No unchecked [ ] items in backlog.md; all

hypotheses in terminal state (confirmed / refuted / pruned); all lanes closed.

• Response: Stop. Loop is done.

Budget exhausted

• Detection: Iteration count (rl N) complete, wall-clock cap

reached, or intervention budget spent.

• Response: Stop. Report what was achieved vs planned.