@zerwiz/ymir 0.1.16 → 0.1.18

package/assets/reference/docs/subagent-guard.md

@@ -0,0 +1,383 @@
+# Primary-session delegation guard
+
+This document is the authoritative human-readable contract for the guard that stops a firstmate primary from delegating work outside the fleet.
+
+The shipped mechanism is `bin/fm-subagent-pretool-check.sh`, a PreToolUse guard that denies a delegation-SHAPED tool name in a genuine primary home.
+Claude primaries should also use an untracked per-home local `permissions.deny` list as hardening for known Claude delegation tools, because it removes them from the model's schema entirely.
+That deny list must not ship in tracked `.claude/settings.json` because it is Claude-only rather than harness-agnostic, and because tracked project settings propagate into linked worktrees where they disarm legitimate crewmates.
+
+## Why this exists
+
+On 2026-07-22 a firstmate primary ran four workers through Claude Code's built-in subagent tool instead of `bin/fm-spawn.sh`.
+Three consequences were observed, not hypothesized.
+
+- The fleet view showed zero work under way for the whole run, because no `state/<id>.meta` and no `data/<id>/brief.md` were ever created.
+- When the primary session restarted, two of those workers died mid-flight and their work was lost.
+  A real crewmate lives in its own backend session with durable state and survives a primary restart.
+- The supervision cycle then stayed down for 73 minutes unnoticed, which silently killed the captain's Workflowy intake channel, since that channel only fires while a watch cycle runs.
+
+The deeper defect is that the bypass did not merely skip dispatch, it made the in-flight-work branch of the guard stack structurally inert.
+Only `bin/fm-spawn.sh` writes `state/<id>.meta`, so untracked project work contributes nothing to the in-flight count used by `bin/fm-supervision-lib.sh` and `bin/fm-turnend-guard.sh`.
+Work started through the harness's own delegation tool writes no metadata, so the in-flight count stayed at zero and the turn-end guard never blocked a blind turn end.
+
+That is the reason the fence has to sit on the harness tool surface, before the primary can create untracked work.
+No additional guard keyed on task metadata can catch this class of failure, because the failure is precisely the absence of that metadata.
+
+## Purpose and boundary
+
+The guard addresses one concrete, mechanically identifiable event: the primary session reaching for a tool that creates work the fleet will not know about.
+
+It deliberately does **not** address the broader question of whether a given piece of work should be delegated at all.
+That question is a judgment boundary over read-and-think work, it has no tool-shape signal, and a hook that tried to police it would degrade into an advisory nag.
+The scope line is therefore: wrong tool reached for, deny; wrong amount of thinking done before reaching for a tool, out of scope.
+
+The guard is also not a dispatch-quality check.
+It says nothing about whether the resulting brief, project, or delivery mode is correct.
+
+## Shipped mechanism
+
+`bin/fm-subagent-pretool-check.sh` is the shipped layer.
+It classifies the tool NAME by shape rather than against a fixed list.
+The tracked Claude PreToolUse matcher is `.*`, so every Claude tool name reaches the script and the script is the single owner of classification.
+A stem-enumerating matcher would reintroduce the fail-open-by-enumeration problem this guard exists to solve, because any future tool name outside the matcher would be silently missed before the script could inspect it.
+A tool is delegation-shaped when its normalized lowercase name contains one of these stems:
+
+```text
+agent  subagent  task  workflow  cron  schedul  worktree
+delegate  spawn  dispatch  handoff  remote  sendmessage  monitor
+```
+
+Three exclusions keep the shape test from producing false positives.
+
+- A name beginning `mcp__` is never classified.
+  An MCP server chooses its own tool names, a task or agent noun there is common, and it has no bearing on fleet dispatch.
+- `OBSERVE_ONLY_TOOLS`: the exact names `taskoutput`, `taskstop`, `taskget`, `tasklist`, `cronlist`, `bashoutput`, and `killshell` are allowed.
+  These observe or stop work that already exists rather than creating it, and denying them at this layer could strand already-running work with no way to inspect or end it.
+  A Claude primary's optional local deny list may still remove them from the schema.
+  The shipped guard stays narrower on purpose so it can never be the reason a runaway task cannot be stopped.
+- `PLAN_ONLY_TOOLS`: the exact names `taskcreate` and `taskupdate` are allowed.
+  These write, which is why they are a separate list rather than more entries in the observe-or-stop one, but what they write is the harness's session-local todo list.
+  That list has no executor: it spawns no agent, allocates no worktree, registers no schedule, and starts nothing that could outlive the session or escape a firstmate guard.
+  So it is not the "work, agent, schedule, or isolated workspace that firstmate would not know about" the guard exists to stop, and the stem match on `task` is a false positive rather than a policy.
+  The cost of the false positive was concrete: the primary could not track its own plan, and the deny text told it to run `bin/fm-brief.sh` and `bin/fm-spawn.sh` to create a todo entry.
+
+Both exclusion lists match the whole normalized name, never a substring, so neither can widen by accident: `TaskCreateAgent` and `RemoteTaskCreate` stay denied.
+Folding the two lists together would be the drift risk, because the observe-or-stop rationale is not true of a tool that writes.
+
+The shipped guard fires on every delegation-shaped name that reaches it, including future names that no deny list knows about yet.
+That future-name behavior is the reason the tracked matcher must match all tools and let the script filter.
+
+## Recommended Local Claude Deny List
+
+Claude primaries should add this deny list in untracked per-home local settings, never in tracked `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Task",
+      "Agent",
+      "Workflow",
+      "RemoteTrigger",
+      "Monitor",
+      "ScheduleWakeup",
+      "SendMessage",
+      "EnterWorktree",
+      "ExitWorktree",
+      "CronCreate",
+      "CronDelete",
+      "CronList",
+      "TaskGet",
+      "TaskList",
+      "TaskStop",
+      "TaskOutput"
+    ]
+  }
+}
+```
+
+A denied name is removed from the model's schema entirely.
+The model is never offered the tool, so there is no call to intercept, no matcher to get wrong, no fail-open path, and no dependence on the model's cooperation.
+This is removal, not interception, and it is strictly stronger than any hook.
+
+This list is recommended local hardening because it closes the known Claude surface before the hook is needed.
+It is not tracked for two reasons.
+
+- It is Claude-only, so it can never be the harness-agnostic shipped fix.
+- A tracked `.claude/settings.json` propagates into linked worktrees and disarms legitimate crewmates.
+  This was verified when a Claude session in a task worktree of this repo lost its `Agent` tool.
+
+The width of the list remains a captain-owned decision, because denying some of these changes how the captain works with the primary session.
+Keep it as one flat local array that is reviewable at a glance and narrowable in one line.
+In particular `TaskOutput`, `TaskStop`, `TaskGet`, `TaskList`, and `CronList` only observe or stop work that already exists, yet the recommended local deny list still removes all five by default.
+The hook deliberately allows those five, so the shipped guard can never strand a runaway task with no way to inspect or end it, and it allows `TaskCreate` and `TaskUpdate` too, so it can never be the reason the primary cannot track its own plan.
+The two session-local todo tools are no longer recommended for local denial at all, because they write only the harness's session-local todo list, which has no executor and spawns nothing, so removing them from the schema removes no delegation power.
+Denying them there would instead reproduce at a stronger layer the exact false positive the shipped guard now avoids, leaving anyone who adopts this list verbatim unable to let a primary track its own plan.
+Narrowing the list further, including the five observe-or-stop names, is the captain's call, and this local list is the only layer that can remove a todo tool from the primary's schema.
+
+`permissions.allow` is a pre-approval list, not an availability list, so there is no fail-closed positive allowlist available.
+That is why any fixed deny list is fail-open against future tools and why the shape-based guard still exists.
+The hook cannot re-enable a tool removed from the schema; it only handles a tool name that still reaches PreToolUse.
+
+### Both `Task` and `Agent` are valid deny keys
+
+The tool presents to the model as `Agent`.
+A prior investigation recorded that the deny key must be `Task` and that using `Agent` "silently does nothing at all".
+That is not what this machine shows.
+
+A five-way A/B with a control, each run in its own directory to rule out settings caching, found that `Task` and `Agent` each independently remove the tool, and that a nonsense name leaves it present.
+The full evidence is in the validation record below.
+
+Pinning both names in the recommended local deny list is correct regardless of which build is running.
+It costs one line and removes the failure mode where a rename or a rollback silently reopens the surface.
+
+## Scope
+
+The shipped hook fires only in a genuine firstmate primary home, using the shared predicate `fm_primary_scope_matches` from `bin/fm-primary-scope-lib.sh`.
+This is the same predicate `bin/fm-sessionstart-nudge.sh` and `bin/fm-turnend-guard.sh` use, so the three tracked primary-scoped hooks cannot drift apart.
+
+A home is in scope when it has `AGENTS.md`, a `bin/` directory, an existing state directory, and either a plain checkout where git-dir equals git-common-dir or a valid `.fm-secondmate-home` marker.
+A marked secondmate home is in scope on purpose: it operates its own fleet and must dispatch through it for the same durability reasons.
+
+A crewmate's disposable task worktree is a linked git worktree, which is the shape `bin/fm-spawn.sh` always hands out, so it is out of scope.
+A crewmate using delegation tools inside its own task worktree is legitimate and stays allowed.
+A non-firstmate repo is out of scope.
+Any failure to confirm the home is inert, never a block, so a broken environment can never deny a tool call.
+
+A local Claude deny list is upstream of hook scope and removes known Claude delegation tools wherever Claude applies it.
+Do not put that list in tracked project settings, because linked worktrees inherit those settings and would lose legitimate delegation tools.
+The hook scope is the shipped enforcement boundary, and the linked-worktree negative case proves the script itself does not block legitimate crewmate delegation.
+
+## Escape hatch
+
+`FM_ALLOW_SUBAGENT=1` in the session environment allows the call at the shipped hook.
+This is the only escape hatch and the guard fails closed on every other value, including empty, `0`, `yes`, and `true`.
+
+It is an environment variable rather than a flag, a config file, or a state file because that makes it unforgeable in-session.
+The variable must be present when the harness process is launched, so no tool call the agent makes can enable it for the call that follows.
+A deliberate use therefore requires restarting the session with the variable set, which is a conscious act, while an accidental use is impossible.
+
+The escape hatch does not affect any local Claude deny list.
+A tool removed from the schema stays removed, so a genuinely intended use of a locally denied tool also requires narrowing or removing that local entry before launch.
+
+## Output contract
+
+- Allow returns exit 0 with both streams empty.
+- Deny returns exit 2 and writes `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny"},"systemMessage":"[subagent-dispatch] ..."}` to stderr.
+- Default deny mode also writes `{"decision":"deny","reason":"[subagent-dispatch] ..."}` to stdout for Grok.
+- `--claude` suppresses stdout completely, because Claude Code ignores a PreToolUse deny when stdout is nonempty.
+  This is the same verified quirk recorded in [`arm-pretool-check.md`](arm-pretool-check.md), and the tracked Claude hook therefore passes `--claude`.
+- Malformed or empty stdin, invalid JSON, a payload with no tool name, and missing `jq` for stdin transport all fail open with exit 0 and no output.
+
+The deny message names the real dispatch path.
+When `bin/fm-scout.sh` exists in the home the message first defers to the `AGENTS.md` intake classification, then routes work already classified as a scout there and authorized ship work with its bounded research to `bin/fm-brief.sh` then `bin/fm-spawn.sh`.
+When that script is absent the message still defers to intake classification and degrades to naming `bin/fm-brief.sh` then `bin/fm-spawn.sh` for dispatched work, rather than pointing at a script that is not there.
+
+## Harness wiring
+
+Every supported primary harness was reviewed.
+Applicability turns on one question: does the harness expose built-in delegation tools that a primary session could use instead of `bin/fm-spawn.sh`?
+
+| Harness | Delegation surface | Status |
+| --- | --- | --- |
+| Claude | 16 known tools, listed above | Scoped guard wired and live-verified; untracked local deny list verified and recommended. |
+| Codex | none | Not applicable, verified empirically below. Codex 0.144.1 exposes no subagent, sub-task, or delegated-agent tool, so there is nothing to remove or intercept. `.codex/hooks.json` is unchanged. |
+| Grok | present, exact tokens unconfirmed | Not wired pending live verification. See below. |
+| OpenCode | present, exact tokens unconfirmed | Not wired pending live verification. See below. |
+| Pi | none reported | Not wired pending live verification. See below. |
+
+### Codex, verified not applicable
+
+Codex 0.144.1 was asked to enumerate its own tools in a scratch git repo on 2026-07-22.
+
+```sh
+codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
+  "List the exact names of every tool available to you in this session, one per line, nothing else. Then state on a final line whether you have any tool that spawns a subagent, sub-task, or delegated agent: answer SUBAGENT_TOOL=yes or SUBAGENT_TOOL=no."
+```
+
+Exact reported tool set and verdict:
+
+```text
+web.run
+functions.exec_command
+functions.write_stdin
+functions.list_mcp_resources
+functions.list_mcp_resource_templates
+functions.read_mcp_resource
+functions.update_plan
+functions.request_user_input
+functions.request_plugin_install
+functions.view_image
+functions.get_goal
+functions.create_goal
+functions.update_goal
+functions.apply_patch
+image_gen.imagegen
+tool_search.tool_search_tool
+multi_tool_use.parallel
+SUBAGENT_TOOL=no
+```
+
+`multi_tool_use.parallel` batches calls to the tools above; it does not spawn an agent.
+Codex is therefore not applicable today, and this table row is the tripwire: if a future Codex release adds a delegated-agent tool, wire `.codex/hooks.json` the same way its `Bash` PreToolUse entries already forward stdin to a checker.
+
+### Grok, OpenCode, and Pi, inspected but not wired
+
+The integration surface of each was inspected and each is structurally wireable for the shipped guard.
+
+- Grok's tracked hooks (`.grok/hooks/fm-primary-pretool-check.json`, `.grok/hooks/fm-primary-cd-check.json`) use a `PreToolUse` matcher, currently `Bash`, and pipe stdin to a checker.
+  The checker already reads Grok's `.toolName` field, so only the matcher token is missing.
+  Grok does expose a delegation surface: `docs/supervision-protocols/grok.md` documents `get_command_or_subagent_output(<task_id>)`, which implies a corresponding dispatch tool.
+- OpenCode's tracked plugins gate on `input?.tool !== "bash"` inside `tool.execute.before`, and block by throwing.
+  Swapping that comparison for a call into this checker with `--tool` is the whole change.
+- Pi's tracked extension gates on `event.toolName !== "bash"` inside `pi.on("tool_call", ...)` and blocks by returning `{block: true}`.
+  The same change applies. A parallel evaluation reports that Pi exposes no delegation tool at all, which would make it not applicable, but that was not verified here.
+
+None of the three is wired in this change because none of the three binaries is installed on the host where this work was done, so the exact tool-name tokens could not be confirmed and the wiring could not be validated against the real harness.
+This repo's rule in the `firstmate-coding-guidelines` skill is that a harness hook must be validated in a scratch project before it is trusted, and `arm-pretool-check.md` records the concrete cost of guessing: a Grok hook whose `command` string is even slightly wrong fails to launch the hook at all.
+Wiring an unvalidated matcher would trade a known gap for an unknown breakage.
+
+The bounded follow-up for each is identical to the Codex procedure above.
+On a host with the binary installed, ask the harness to enumerate its tools, then wire the matcher and re-run the live matrix below.
+`bin/fm-subagent-pretool-check.sh` needs no change for any of them: it already accepts Grok's stdin shape and the `--tool` CLI form OpenCode and Pi use, and it already emits the Grok stdout decision object by default.
+
+## Live validation record, 2026-07-22
+
+Harness version:
+
+```text
+2.1.217 (Claude Code)
+```
+
+Every run used a scratch project under this task worktree.
+No modified file was installed into the primary checkout or a live harness configuration, and no live watcher, fleet state, or task metadata was used.
+The launch command throughout was:
+
+```sh
+claude -p "$PROMPT" --dangerously-skip-permissions --output-format text
+```
+
+### Tool name and matcher mechanics
+
+The tool name delivered to PreToolUse hooks was established before any matcher was written, using a throwaway project whose only hook appended `.tool_name` to a log for matcher `.*`.
+It logged `Agent` and `Bash`.
+A second project using matcher `^(Task|Agent)$` logged `Agent` only, confirming both the live tool name and that Claude Code honors regex anchors in a PreToolUse matcher.
+The tracked matcher is now `.*`, matching the throwaway-project evidence above so any future tool name reaches the script classifier.
+
+### Deny-key A/B, with control
+
+Prompt: `List the exact names of every tool available to you, comma-separated on one line, nothing else.`
+Each variant ran in its own fresh directory to rule out settings caching.
+
+| `.claude/settings.json` | `Agent` in tool list? |
+| --- | --- |
+| `{}` | Yes |
+| `{"permissions":{"deny":["Task"]}}` | No |
+| `{"permissions":{"deny":["Agent"]}}` | No |
+| `{"permissions":{"deny":["ZzzNotARealTool"]}}` | Yes |
+| `{"permissions":{"deny":["Task","Agent"]}}` | No |
+
+The nonsense-name control is what makes this conclusive: the tool disappears only when a real name is denied, so the removal is caused by the deny entry rather than by run-to-run variation.
+Both `Task` and `Agent` are therefore working deny keys on this build, correcting the earlier claim that only `Task` works.
+
+The observed baseline surface was 29 tools:
+
+```text
+Agent, Bash, Edit, Read, ReportFindings, ScheduleWakeup, Skill, ToolSearch, Workflow, Write,
+CronCreate*, CronDelete*, CronList*, DesignSync*, EnterWorktree*, ExitWorktree*, Monitor*,
+NotebookEdit*, PushNotification*, RemoteTrigger*, SendMessage*, TaskCreate*, TaskGet*,
+TaskList*, TaskOutput*, TaskStop*, TaskUpdate*, WebFetch*, WebSearch*
+```
+
+A `*` marks a deferred tool, which is lazy-loaded through `ToolSearch` and does not appear in a plain tool list unless the prompt asks for deferred entries.
+This distinction matters when reading the next result: a tool absent from a plain listing is not necessarily denied.
+
+### Local deny-list hardening
+
+Run in a scratch firstmate-shaped project containing `AGENTS.md`, `state/`, a full copy of `bin/`, and a Claude settings file containing the local deny list exactly as recommended on that date, which was the 18-name form that still included `TaskCreate` and `TaskUpdate`.
+The result validates that local deny list rather than tracked repo state, and the recommendation above has since dropped those two session-local todo tools.
+Asking for deferred entries explicitly returned:
+
+```text
+Bash, Edit, Read, ReportFindings, Skill, ToolSearch, Write,
+DesignSync*, NotebookEdit*, PushNotification*, WebFetch*, WebSearch*
+```
+
+All 18 locally denied names are gone and every ordinary working tool remains, including the five deferred ones.
+Comparing against the 29-tool baseline confirms the removal set is exactly the deny list and nothing else.
+
+### Shipped guard, the case a fixed deny list cannot cover
+
+To reproduce a future tool that ships before a local deny list is updated, `Workflow` was removed from the deny list in the same scratch project while the guard stayed wired.
+
+Prompt: `Call the Workflow tool to run any trivial workflow. You must actually attempt the Workflow tool call.`
+
+Claude reported:
+
+```text
+I attempted the Workflow tool call as requested. It was blocked by a PreToolUse hook in this repo:
+
+> [subagent-dispatch] the firstmate primary dispatches through the fleet, not the harness's own
+> delegation tools... (blocked tool: Workflow). Launch the session with FM_ALLOW_SUBAGENT=1 for a
+> deliberate exception.
+```
+
+This is the load-bearing result: the shipped guard denied a delegation tool that the deny list did not cover, which is the future-name case the shape classifier exists for.
+
+### Shipped guard scope, the negative case
+
+The same `Workflow` prompt was then run in a `git worktree add` linked worktree of that scratch project, carrying the identical tracked hook and checker bytes, with no escape hatch.
+
+```text
+The Workflow tool call was not blocked by a hook. It executed normally: launched, ran 1 agent,
+and completed successfully returning {"result":"ok"}.
+```
+
+Same hook, same bytes, deny in the primary home and allow in a crewmate-shaped worktree.
+This is the scoping contract working end to end rather than a hook that simply never fires.
+
+### Escape hatch
+
+The same `Workflow` prompt in the scratch primary home, launched as `FM_ALLOW_SUBAGENT=1 claude -p ...`:
+
+```text
+Result: the Workflow tool call was NOT blocked by a hook. It launched and ran to completion.
+```
+
+### Empty-stdout requirement
+
+A Claude deny is honored only when the hook's stdout is empty.
+`tests/fm-subagent-pretool-check.test.sh` asserts stdout is empty on every `--claude` deny and that default mode still emits the Grok object on stdout.
+The live consequence is confirmed by the shipped-guard result above: Claude honored the deny and reported the reason text.
+
+## Automated validation
+
+`tests/fm-subagent-pretool-check.test.sh` owns the acceptance matrix and is registered in the `pure-contract-unit` family in `bin/fm-test-run.sh`.
+It covers the tracked Claude settings boundary that forbids a `permissions` key; the match-all Claude hook registration; denial of every work-creating delegation tool by shape; denial of twelve hypothetical future tool names that appear on no list; the observe-or-stop, plan-only, and MCP exclusions; the exactness of the plan-only exclusion against six near-miss names a substring or shorter-stem widening would release; the scout-present and scout-absent message variants; the escape hatch including its fail-closed values; inertness in a linked task worktree and in a non-firstmate repo; in-scope enforcement for a marked secondmate home; both stdin transports; the empty-stdout requirement; fail-open transport behavior; and the preserved `Bash` seatbelts and `Stop` guard.
+
+Run:
+
+```sh
+bash -n bin/fm-subagent-pretool-check.sh
+bin/fm-lint.sh
+tests/fm-subagent-pretool-check.test.sh
+```
+
+## Known residual gap
+
+The other tracked Claude hook entries in `.claude/settings.json` refuse to run under Grok's Claude-compatible settings loading (docs/turnend-guard.md "Harness integrations"), because Grok already covers each of those events through its own `.grok/hooks/` registration and running both creates a duplicate path.
+This entry is the deliberate exception and stays unguarded: Grok is "inspected but not wired" above, so no `.grok/hooks/` registration covers the subagent-spawn event at all, and guarding it would remove the guard from Grok entirely rather than deduplicate it.
+The coverage it leaves is partial rather than correct - the tracked entry passes `--claude`, which suppresses exactly the stdout decision object Grok consumes - so treat this as incidental reach, not as Grok being wired.
+Wiring Grok properly still requires the matcher-token verification described above, and that is what closes this exception.
+The same exception now also covers Cursor, which loads the tracked Claude settings as well: `.cursor/hooks.json` registers no subagent-spawn matcher, so this entry stays unguarded there for the same reason, and its `--claude` rendering leaves Cursor the exit-2 and stderr path rather than Cursor's own decision object.
+Cursor's subagent tool name has not been verified, and registering an unverified matcher would be a guess rather than coverage, so closing it needs the same verification step.
+
+This change does not close the deeper harness-agnostic defect.
+Every firstmate guard's in-flight-work branch keys off `state/<id>.meta`, and only `bin/fm-spawn.sh` writes that record.
+`bin/fm-supervision-lib.sh` also recognizes a Relay poll as supervision need, but unaccounted primary work still contributes nothing to that predicate.
+Without an independent Relay need, unaccounted primary work therefore reads as idle rather than suspicious.
+
+The durable fix for that class is to make the guards treat "the primary is doing project-shaped work with zero `state/*.meta` files" as a suspicious state rather than an idle one.
+That would catch this class on any harness, including work created through `Bash`.
+This change fences only the Claude tool surface.
+That is a separate change to `bin/fm-supervision-lib.sh` and `bin/fm-turnend-guard.sh` and is out of scope here.

package/assets/reference/docs/supervision-protocols/claude.md

@@ -0,0 +1,27 @@
+Mode: Claude Stop-hook-owned supervision.
+
+When this session owns supervision and away mode is not active:
+1. Drain first with `bin/fm-wake-drain.sh`.
+   After handling all emitted wakes and reconciling open decisions and unread status lines, run the exact `--ack-through` command printed as `WAKE_ACK_REQUIRED`; until then the work remains durable for idempotent re-handling after interruption.
+2. Routine watcher arm and re-arm are owned by the Stop `asyncRewake` hook (`bin/fm-claude-stop-autoarm.sh`), never by you.
+   Every turn end while supervision is needed launches or attaches one home-scoped watcher cycle with no model command and no model tokens.
+   An actionable close wakes you through the hook's exit-2 rewake, delivered as a `Stop hook feedback` message.
+3. On a `Stop hook feedback` wake (`signal:`, `stale:`, `check:`, or `heartbeat`), run `bin/fm-wake-drain.sh` first and handle the wake.
+   Do not run `bin/fm-watch-arm.sh` after an ordinary wake; the next turn end re-arms automatically when supervision is still needed.
+   Do not invent a wake from an attach-status line alone; drain and act only on real wake records, the drain's `OPEN DECISIONS` and `UNREAD STATUS` entries, or a real watcher reason line.
+4. On the one `Stop hook feedback` automatic-mechanism failure notice (`firstmate watcher auto-arm FAILED ...`), drain, inspect the automatic mechanism failure, and do not turn the notice into a repeating manual-arm loop.
+5. If the Stop hook does not claim the home or reports an exhausted failure, inspect its registration and watcher startup path before ending blind.
+   Keep the Stop-owned automatic mechanism as the only Claude arm owner.
+6. Treat `watcher: started ...` and `watcher: attached ...` inside automatic arm output as proof that one live cycle exists.
+   On attach, the arm follows verified identity-matched successors instead of exiting when the first cycle ends.
+7. The durable wake queue preserves actionable events between a rewake and the next Stop-launched arm, while the bounded turn-end guard prevents a blind Stop when recovery did not start.
+   No PreToolUse hook denies fleet commands based on watcher status.
+   [`watcher-continuity.md`](../watcher-continuity.md) owns the exact session-lock recovery boundary.
+8. The turn-end guard (`bin/fm-turnend-guard.sh --claude`) remains the final backstop.
+   It requires the PID-strict live-watcher and fresh-beacon predicate at the Stop boundary, while the mid-turn pull guard accepts a fresh beacon without a live process under Claude's between-turns auto-arm model.
+   It allows the stop when a watcher is healthy or an open auto-arm generation claim owns recovery, while fresh failure epochs advance the bounded one-time attended fail-open progression described in [`turnend-guard.md`](../turnend-guard.md).
+9. Waiting on the hook-owned cycle is silent: do not send idle progress while the watcher is parked.
+
+The watcher itself remains `bin/fm-watch.sh`, and `bin/fm-watch-arm.sh` remains the verified arm wrapper that the Stop hook foregrounds.
+Re-arm attaches to an existing healthy cycle when one is already present and follows its verified successor chain.
+See [`watcher-continuity.md`](../watcher-continuity.md) for the arm-layer successor and clean-close failure contract and the Claude ownership model.

package/assets/reference/docs/supervision-protocols/codex.md

@@ -0,0 +1,16 @@
+Mode: Codex foreground checkpoint.
+
+When this session owns supervision and away mode is not active:
+1. Drain first with `bin/fm-wake-drain.sh`.
+   After handling all emitted wakes and reconciling open decisions and unread status lines, run the exact `--ack-through` command printed as `WAKE_ACK_REQUIRED`; until then the work remains durable for idempotent re-handling after interruption.
+2. Source `__FM_X_MODE_ENV__` first when Relay is active.
+3. First cycle: run one foreground watcher checkpoint with `bin/fm-watch-checkpoint.sh --seconds "${FM_CODEX_WATCH_CHECKPOINT:-180}"`.
+4. Ordinary wake: if the command prints `signal:`, `stale:`, `check:`, or `heartbeat`, drain queued wakes, handle that wake, then start the next checkpoint.
+5. If the command prints `checkpoint:` or exits 124 with no wake, drain queued wakes anyway, process any queued user message now visible to Codex, then start the next checkpoint.
+6. Never use shell `&` or Codex background tasks for firstmate watcher supervision.
+7. Do not run `bin/fm-watch-arm.sh` as Codex's normal supervision command.
+   If it is ever shelled anyway, a backgrounded, piped, or bundled anti-pattern is denied automatically by the PreToolUse seatbelt (`bin/fm-arm-pretool-check.sh`) registered in `.codex/hooks.json`.
+8. Failure or missing cycle only: drain queued wakes, inspect the failure, then start a fresh foreground checkpoint.
+
+Codex cannot reason while a foreground tool call is running.
+The bounded checkpoint returns control regularly so user messages and queued wakes can be handled without relying on background-task wake semantics.

package/assets/reference/docs/supervision-protocols/cursor.md

@@ -0,0 +1,31 @@
+Mode: Cursor stop-hook-owned park.
+
+When this session owns supervision and away mode is not active:
+1. Drain first with `bin/fm-wake-drain.sh`.
+   After handling all emitted wakes and reconciling open decisions, run the exact `--ack-through` command printed as `WAKE_ACK_REQUIRED`; until then the work remains durable for idempotent re-handling after interruption.
+2. Routine watcher arm and re-arm are owned by the `stop` hook (`bin/fm-turnend-guard-cursor.sh`), never by you.
+   Cursor runs that hook synchronously and awaits it, so every turn end while supervision is needed parks the turn boundary open on one home-scoped watcher cycle, with no model command and no model tokens spent while parked.
+3. An actionable close wakes you as a follow-up turn carrying the `watcher` operational kind.
+   On that wake, run `bin/fm-wake-drain.sh` first and handle it.
+   Do not run `bin/fm-watch-arm.sh` after an ordinary wake; the next turn end parks again automatically when supervision is still needed.
+   Do not invent a wake from an attach-status line alone; drain and act only on real wake records, the drain's `OPEN DECISIONS` entries, or a real watcher reason line.
+4. The captain keeps control while the hook is parked.
+   A message typed into a parked Cursor pane is accepted and runs its turn immediately, but the older park remains the recorded owner until that turn ends and the next `stop` hook claims the baton.
+   An actionable watcher close in that window can still be delivered by the older park as one follow-up.
+   This is bounded and safe: only one park exists in that window, so the event is a real wake rather than a stale duplicate of another park's wake, the durable wake queue makes handling idempotent, and the next `stop` claim makes an older park that is still running stand down without emitting.
+   The private supersession records are `state/.cursor-park-owner` and its short publication and commit lock `state/.cursor-park-owner.lock`.
+5. On a `turn-end-guard` follow-up, the park could not establish a live cycle.
+   Inspect the watcher startup path rather than turning the notice into a repeating manual-arm loop; the nag is bounded by `FM_CURSOR_TURNEND_BLOCK_BUDGET` (default 3) and then stops on its own.
+6. Treat `watcher: started ...` and `watcher: attached ...` inside park output as proof that one live cycle exists.
+   On attach, the arm follows verified identity-matched successors instead of exiting when the first cycle ends.
+7. The durable wake queue preserves actionable events between a follow-up and the next park.
+   [`watcher-continuity.md`](../watcher-continuity.md) owns the exact session-lock recovery boundary.
+8. Waiting on the hook-owned park is silent: do not send idle progress while the watcher is parked.
+
+The watcher itself remains `bin/fm-watch.sh`, and `bin/fm-watch-arm.sh` remains the verified arm wrapper that the `stop` hook runs as its own tracked child.
+Re-arm attaches to an existing healthy cycle when one is already present and follows its verified successor chain.
+See [`watcher-continuity.md`](../watcher-continuity.md) for the arm-layer successor and clean-close failure contract.
+
+Exit status 2 is a silent no-op on Cursor's `stop` step, so this adapter never blocks a turn end and instead forces one bounded follow-up, which [`turnend-guard.md`](../turnend-guard.md) accepts as an equal alternative.
+That document owns the double loop bound, the supersession contract, the Pi-host stand-down, and the compatibility limits, including that a Cursor primary must be launched with `--trust` for its project hooks to load at all.
+Cursor's `beforeSubmitPrompt` step fires once for a real captain message and not for hook-driven follow-ups, so it could invalidate the baton at the start of this window, but that registration is deliberately deferred alongside the `preCompact` surface.

package/assets/reference/docs/supervision-protocols/grok.md

@@ -0,0 +1,39 @@
+Mode: Grok background-notify supervision.
+
+When this session owns supervision and away mode is not active:
+1. Drain first with `bin/fm-wake-drain.sh`.
+   After handling all emitted wakes and reconciling open decisions and unread status lines, run the exact `--ack-through` command printed as `WAKE_ACK_REQUIRED`; until then the work remains durable for idempotent re-handling after interruption.
+2. Source `__FM_X_MODE_ENV__` first when Relay is active.
+3. First cycle: arm with Grok's tracked background tool, as its own call:
+
+   `run_terminal_command` with `background: true` on:
+   `[ -f __FM_X_MODE_ENV_SH__ ] && . __FM_X_MODE_ENV_SH__; exec bin/fm-watch-arm.sh`
+
+4. Trust only the arm's one-line status.
+5. `watcher: started ...` or `watcher: attached ...` means a live cycle exists.
+   On attach, the background task follows verified identity-matched successors instead of exiting when the first cycle ends.
+6. Failure or missing cycle only: `watcher: FAILED ...` means supervision is down; fix and re-arm.
+7. After a successful start or attach status, end the turn.
+   The background arm remains the live wait until it returns an actionable wake or failure.
+8. Waiting is silent.
+9. Never use shell `&` for firstmate supervision.
+10. Never bundle the arm onto another command.
+    A shell `&`, a truncating pipe, or bundling is denied automatically by the PreToolUse seatbelt (`bin/fm-arm-pretool-check.sh`) whenever this project's Grok hooks are trusted.
+
+Grok injects a synthetic user message with `synthetic_reason: task_completed` when the background arm completes.
+When you see a background-task-completed system reminder for the arm:
+1. Run `bin/fm-wake-drain.sh` first.
+2. Optionally fetch arm output with `get_command_or_subagent_output(<task_id>)` for the reason line.
+3. Handle `signal`, `stale`, `check`, or `heartbeat` using the harness-neutral contract in `AGENTS.md`.
+4. Ordinary wake: re-arm the next cycle with the same background `bin/fm-watch-arm.sh` call if work remains in flight or Relay still needs polling.
+5. Do not invent a wake from an attach-status line alone.
+   Drain the queue and act only on real wake records, the drain's `OPEN DECISIONS` and `UNREAD STATUS` entries, or a real watcher reason line.
+   Re-arm attaches to an existing healthy cycle when one is already present and follows its verified successor chain.
+   See [`watcher-continuity.md`](../watcher-continuity.md) for the arm-layer successor and clean-close failure contract.
+
+The primary project Stop hook runs `bin/fm-turnend-guard-grok.sh` as a backstop, not the normal wake path.
+[`turnend-guard.md`](../turnend-guard.md) owns its running-payload capability selection between native same-process blocking and the pre-native bounded resume fallback.
+After any forced continuation, arm the watcher with the background protocol above.
+
+Interactive TUI primary sessions are the supported supervision host.
+Headless `grok -p` may wait for background process exit but does not reliably surface full auto-wake model output; do not run the primary firstmate as a one-shot headless process.

package/assets/reference/docs/supervision-protocols/opencode.md

@@ -0,0 +1,17 @@
+Mode: OpenCode TUI plugin background wake.
+
+When this session owns supervision and away mode is not active:
+1. Drain first with `bin/fm-wake-drain.sh`.
+   After handling all emitted wakes and reconciling open decisions and unread status lines, run the exact `--ack-through` command printed as `WAKE_ACK_REQUIRED`; until then the work remains durable for idempotent re-handling after interruption.
+2. First cycle: let `.opencode/plugins/fm-primary-watch-arm.js` arm supervision after the OpenCode session goes idle.
+3. The plugin listens for `session.idle`, spawns `bin/fm-watch-arm.sh --restart` without awaiting it in the idle handler, and owns every later successor launch.
+4. After an actionable child close, the plugin rechecks session-lock ownership and verifies one singleton successor before it calls `client.session.promptAsync`; its bounded fallback is defined in `docs/watcher-continuity.md`.
+5. Ordinary wake: do not ask the model to re-arm because continuity is plugin-owned.
+6. An unexpected child close enters bounded exponential retry, and an exhausted retry or lost session lock is surfaced as a watcher failure instead of disappearing.
+7. Failure or missing cycle only: if the plugin reports a watcher failure, drain queued wakes, inspect the failure text, and use `bin/fm-watch-arm.sh` manually only as a short recovery probe.
+8. Never use shell `&` for watcher supervision.
+   The arm mechanism above is plugin-owned, not a model tool call, but a manual recovery probe that backgrounds, pipes, or bundles the arm is denied automatically by the PreToolUse seatbelt (`.opencode/plugins/fm-primary-pretool-check.js`, `bin/fm-arm-pretool-check.sh`).
+9. Do not rely on this plugin in headless `opencode run`; firstmate primary supervision targets persistent OpenCode TUI sessions.
+
+OpenCode's persistent TUI plugin runtime is the wake mechanism.
+The plugin applies in the main primary checkout and a secondmate's own home, and stays silent only in child crewmate and scout worktrees.

package/assets/reference/docs/supervision-protocols/pi.md

@@ -0,0 +1,33 @@
+Mode: Pi extension background wake.
+
+When this session owns supervision and away mode is not active:
+1. Drain first with `bin/fm-wake-drain.sh`.
+   After handling all emitted wakes and reconciling open decisions and unread status lines, run the exact `--ack-through` command printed as `WAKE_ACK_REQUIRED`; until then the work remains durable for idempotent re-handling after interruption.
+2. Confirm the Pi primary auto-loaded both project extensions (plain `pi` or `pi-signed`, after approving project trust once per clone); if not, restart the selected executable with `-e __FM_PI_TURNEND_EXT__ -e __FM_PI_EXT__` as a trust-free fallback.
+3. First cycle only: make the one required `fm_watch_arm_pi` call.
+   Use `/fm-watch-arm-pi` only as a human-entered fallback.
+   Never run `bin/fm-watch-arm.sh` through Pi's bash tool because that foreground arm can wedge the agent and bypasses extension-owned cleanup.
+4. If the extension says no live session holds the lock, run `bin/fm-session-start.sh` to reclaim the session lock, then call `fm_watch_arm_pi` again.
+5. The extension starts `bin/fm-watch-arm.sh --restart`, keeps the child attached to the live Pi process, and owns every later successor launch.
+6. Ordinary same-process session replacement (`/new`, `/resume`, `/fork`, reload) retires only the prior generation; call `fm_watch_arm_pi` once for the first cycle of the replacement session without restarting Pi.
+   The generation-owner contract lives in `.pi/extensions/fm-primary-pi-watch.ts`.
+7. After an actionable child close, the extension rechecks session-lock ownership and verifies one successor before it delivers the follow-up wake; its bounded fallback is defined in `docs/watcher-continuity.md`.
+8. Ordinary work, turn completion, and ordinary signal, stale, check, heartbeat, or other wake handling: do not call `fm_watch_arm_pi` again because continuity is extension-owned rather than model-memory-owned.
+9. An unexpected child close enters bounded exponential retry, and an exhausted retry or lost session lock is surfaced as a watcher failure instead of disappearing.
+10. Missing, failed, or unhealthy cycle only: if a later notification explicitly reports one of those repair conditions, drain queued wakes, inspect the failure text, call `fm_watch_arm_pi`, and restart the selected Pi-family executable with both extensions loaded if needed.
+   A redundant call while the extension owns an arm child or scheduled retry is an ownership-based `watcher: unchanged` no-op, not an independent health claim.
+11. Never use shell `&` for watcher supervision.
+   The arm mechanism above is extension-owned, not a model tool call, but a manual recovery probe that backgrounds, pipes, or bundles the arm is denied automatically by the PreToolUse seatbelt (`bin/fm-arm-pretool-check.sh`, wired into the turn-end guard extension at `__FM_PI_TURNEND_EXT__`).
+
+The supervision branch is default-on (docs/pi-supervision-branch.md): whenever this session owns the fleet lock and away mode is not active, the watcher extension hands eligible task-local rows from ordinary actionable wakes, plus selected fleet-wide heartbeat reviews, to the persistent in-process supervision branch while main-only rows remain queued for this conversation.
+A no-change heartbeat outcome explicitly reported with `task=fleet` and `silent=true` is delivered silently with no rendered note, while every other routine outcome returns as an appended, rendered note that leads with ⛵ then the dim outcome text.
+A captain-facing outcome instead opens exactly one follow-up turn on this conversation - MAIN must produce its captain-visible response in that turn, and no separate note is printed here.
+Before MAIN steers, controls lifecycle, or cleans up a task, claim its lease with `bin/fm-lease.sh claim <task>` and release it afterwards; a refused claim means the branch is acting on that task right now.
+This conversation still receives every other fleet-wide or unresolvable wake, the branch's wakes when it is unavailable or away mode is active, and every watcher-failure alarm regardless, so the arm and repair contract above is unchanged.
+Treat the merged fleet event as already handled for fleet operations: MAIN must not re-drain, re-run, or acknowledge it.
+Separately, MAIN applies judgment about whether and how to surface, summarize, reference, or incorporate a merged sailboat outcome in the captain conversation; event ownership does not decide the conversational treatment.
+Read the durable outcome store with the fm_branch_outcomes tool when the captain asks what happened.
+
+The turn-end guard extension lives at `__FM_PI_TURNEND_EXT__`.
+The watcher extension lives at `__FM_PI_EXT__`.
+Both are tracked, project-local `.pi/extensions/*.ts` files that Pi auto-discovers once the project is trusted; `bin/fm-session-start.sh` reports when the running Pi session has not loaded both required extensions.

package/assets/reference/docs/supervision-protocols/unknown.md

@@ -0,0 +1,13 @@
+Mode: Unknown harness fallback.
+
+This primary harness does not have a verified watcher wake adapter.
+Follow the generic supervision contract in `AGENTS.md`.
+First cycle: drain queued wakes, then choose a supervision wait that the harness can actually wake from.
+Ordinary wake: drain, handle all emitted wakes, reconcile open decisions and unread status lines, and run the exact `--ack-through` command printed as `WAKE_ACK_REQUIRED`, then repeat that verified wait while supervision is still required.
+Before that acknowledgement, interruption leaves the work durable for idempotent re-handling.
+Use `bin/fm-watch-arm.sh` only when the harness has a tracked background mechanism that survives the tool call and notifies the model on process exit.
+Use a bounded foreground wait over `bin/fm-watch.sh` when that wake mechanism is not verified.
+Never use shell `&` for watcher supervision.
+Failure or missing cycle only: inspect the failure and restore the same verified wait shape.
+
+Record new verification evidence before promoting an unknown harness to a named snippet.