docs: clarify live supervision constraints

[kunchenguid]

Intent

Encode two structural supervision rules into AGENTS.md for the firstmate orchestrator template. Section 1 should explicitly say firstmate delegates changes to shared firstmate-repo material such as AGENTS.md, bin, workflows, and skills to a crewmate while any fleet is live, while preserving direct self-edits when the fleet is empty and preserving firstmate ownership of operational fleet state. Section 8 should state that while any task is in flight, firstmate must not run long foreground-blocking operations such as its own no-mistakes pipeline or long builds, and must background such work so watcher wakes can interleave and supervision remains responsive. This is a documentation-only change that should touch AGENTS.md only, match the terse one-sentence-per-line voice, and avoid touching scripts.

What Changed

• Documented that firstmate keeps ownership of operational fleet state but delegates shared firstmate-repo edits to crewmates while any fleet tasks are live.
• Clarified that direct edits to firstmate materials remain allowed when the fleet is empty.
• Added supervision guidance to keep long validation or build work in the background so watcher wakes can still be handled.

Risk Assessment

✅ Low: Documentation-only change scoped to AGENTS.md that directly encodes the requested supervision constraints without altering executable behavior.

Testing

Checked the baseline-to-target diff, confirmed only AGENTS.md changed, manually verified the added documentation covers live-fleet delegation, empty-fleet direct edits, operational fleet state ownership, and non-blocking supervision during in-flight work, captured the documentation diff as evidence, and confirmed testing left the worktree clean.

Evidence: AGENTS.md supervision rules diff

Shows the exact user-facing documentation additions in Section 1 and Section 8.

diff --git a/AGENTS.md b/AGENTS.md
index 6b370eb..089f137 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,28 +21,32 @@ Hard rules, in priority order:
    The single exception is tool-driven project initialization (section 6).
 2. **Never merge a PR without the captain's explicit word.**
 3. **Never tear down a worktree that holds work not on a remote.**
    `bin/fm-teardown.sh` enforces this; never bypass it with `--force` unless the captain explicitly said to discard the work.
    The one carve-out: a scout task's worktree is declared scratch from the start - its deliverable is the report, and teardown lets the worktree go once that report exists (section 7).
 4. **Crewmates never address the captain.**
    All crewmate communication flows through you.
    The captain may watch or type into any crewmate window directly; treat such intervention as authoritative and reconcile your records at the next heartbeat.
 5. Report outcomes faithfully.
    If a crewmate failed, say so plainly with the evidence.
 
 You may freely write to this repo itself (backlog, briefs, state, even this file when the captain approves a change).
+Operational fleet state stays yours to maintain even when crewmates are live.
+When one or more crewmates are in flight, delegate changes to shared repo material (AGENTS.md, README.md, CONTRIBUTING.md, .github/workflows/, bin/, agent skill files) to a crewmate through the normal scout or ship machinery instead of hand-editing them yourself.
+When the fleet is empty, you may make those firstmate-repo changes directly.
+Hands-on firstmate work competes with live supervision for the same single thread of attention.
 This repo is a shared template, not the captain's personal project.
 The tracking principle: anything shared (AGENTS.md, README.md, CONTRIBUTING.md, .github/workflows/, bin/, agent skill files) is tracked under git; anything personal to this captain's fleet (data/, state/, config/, projects/, .no-mistakes/) is not.
 Commit durable changes to the shared, tracked material with terse messages.
-This repo is itself behind the no-mistakes gate: ship tracked changes (AGENTS.md, README.md, CONTRIBUTING.md, .github/workflows/, bin/, agent skill files) through the pipeline yourself - branch, commit, run the pipeline, PR - and the captain's merge rule applies here exactly as it does to projects.
+This repo is itself behind the no-mistakes gate: ship tracked changes (AGENTS.md, README.md, CONTRIBUTING.md, .github/workflows/, bin/, agent skill files) through the pipeline - branch, commit, run the pipeline, PR - and the captain's merge rule applies here exactly as it does to projects.
 Never add an agent name as co-author.
 
 ## 2. Layout and state
 
 `` `
 AGENTS.md            this file (CLAUDE.md is a symlink to it)
 CONTRIBUTING.md      contributor workflow and repo conventions
 README.md            public overview and development notes
 .github/workflows/   shared CI and PR enforcement, committed
 .agents/skills/      shared skills, committed
 .claude/skills       symlink to .agents/skills for claude compatibility
 bin/                 helper scripts, committed; read each script's header before first use
@@ -318,24 +322,28 @@ On wake, in order of cheapness:
 Heartbeats back off exponentially while they are the only wakes firing (600s doubling to a 2h cap - an idle fleet stops burning turns); any signal, stale, or check wake resets the cadence to the base interval.
 
 Never rely on hooks or status files alone; the heartbeat review of every window is mandatory and unconditional.
 tmux is the ground truth.
 
 **Watcher liveness is guarded, not just disciplined.**
 Restarting the watcher is the last action of every wake-handling turn - but the protocol no longer relies on remembering that.
 While running, `fm-watch.sh` touches `state/.last-watcher-beat` every poll cycle.
 The supervision scripts (`fm-peek`, `fm-send`, `fm-spawn`, `fm-teardown`, `fm-pr-check`, `fm-promote`) call `bin/fm-guard.sh` first, which warns to stderr when any task is in flight (`state/*.meta` exists) but that beacon is missing or older than `FM_GUARD_GRACE` (default 300s).
 So the next time you touch the fleet with no watcher alive, the tool output itself tells you to restart it - a pull-based guard that works on any harness, since it rides the script output you already read rather than a harness-specific hook.
 The grace window keeps normal handling (watcher briefly down between a wake and its restart) silent.
 If a guard warning fires, restart the watcher before doing anything else.
+Watcher liveness is not enough if you are foreground-blocked.
+Whenever one or more tasks are in flight, do not run long foreground-blocking operations in your own session.
+This includes your own no-mistakes pipeline, long builds, and any other multi-minute command.
+Background that work so watcher wakes can interleave with it and the supervision loop stays responsive.
 
 Token discipline: status files before panes; default peeks to 40 lines; never stream a pane repeatedly through yourself; batch what you tell the captain.
 
 ### Stuck-crewmate playbook (escalate in order)
 
 1. Peek the pane.
 2. Crewmate is waiting on a question its brief already answers: answer in one line via fm-send.
 3. Crewmate is confused or looping: interrupt with the adapter's interrupt key (the window's harness is recorded as `harness=` in `state/<id>.meta`; e.g. `bin/fm-send.sh <window> --key Escape`), then redirect with one corrective line.
 4. Crewmate is context-exhausted or wedged: exit the agent with the adapter's exit command, relaunch with the same brief plus a `progress so far` note you append to it. The worktree and commits persist; this is cheap.
 5. Second relaunch fails too: write `failed` to backlog, tell the captain with evidence.
 
 ## 9. Escalation and captain etiquette

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• git diff --stat 0cfbc844d587bcdc41cc17a26b934cff45540bb6..17f2dc37b62501f2ec0fefa4cbdbbeff84fc9a39
• git diff --name-only 0cfbc844d587bcdc41cc17a26b934cff45540bb6..17f2dc37b62501f2ec0fefa4cbdbbeff84fc9a39
• git diff --unified=80 0cfbc844d587bcdc41cc17a26b934cff45540bb6..17f2dc37b62501f2ec0fefa4cbdbbeff84fc9a39 -- AGENTS.md
• grep search for Operational fleet state|When one or more crewmates are in flight|When the fleet is empty|foreground-blocking|Background that work in AGENTS.md
• Captured reviewer-visible documentation diff to /var/folders/5x/4nqprlbx0518k3ybcb1sz6gr0000gn/T/no-mistakes-evidence/01KTYVYRWAAXPEVQ135ESNETBV/agents-supervision-rules.diff
• git status --short

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.