@zerwiz/ymir 0.1.16 → 0.1.18

package/assets/reference/docs/orca-backend.md

@@ -0,0 +1,84 @@
+# Orca runtime backend
+
+Orca is an experimental macOS backend in which the Orca app owns both the task worktree and terminal endpoint.
+The crewmate harness remains the agent process launched inside that endpoint.
+Firstmate agents load [`firstmate-orca`](../.agents/skills/firstmate-orca/SKILL.md) before operating or recovering this backend.
+
+## Setup
+
+Pick Orca when you already use the Orca macOS app and want Orca-managed worktrees and terminals instead of Treehouse plus a session multiplexer.
+Orca is macOS-only, explicit-only, and does not support secondmate spawns.
+
+Prerequisites:
+
+- `/Applications/Orca.app` installed, running, and ready.
+- The `orca` CLI, installed with `brew install orca`.
+- The universal harness and toolchain requirements in [`configuration.md`](configuration.md#toolchain).
+
+Select Orca with local `config/backend` containing `orca`, `FM_BACKEND=orca` for one launch, or an explicit request to Firstmate.
+It is never auto-detected.
+
+Before any spawn mutates repository state, Firstmate requires `orca status --json` to report `reachable=true` and `state="ready"`.
+The first task for a project registers that repository with `orca repo add --path` when needed.
+No manual repository registration is required.
+
+Open the Orca app to watch a task's terminal.
+Routine supervision uses the recorded endpoint through `bin/fm-peek.sh <id>` and `FM_HOME=<home> bin/fm-send.sh <id> '<text>'`.
+Enter and Ctrl-C are supported; Escape is not.
+
+## Task shape and metadata
+
+Each task has one Orca-managed git worktree and one Orca terminal.
+`fm-spawn.sh` does not call Treehouse for Orca tasks.
+The normal isolation and unlanded-work refusal rules still apply.
+
+```text
+backend=orca
+window=fm-<id>
+terminal=<orca terminal handle>
+orca_worktree_id=<orca worktree id>
+worktree=<absolute Orca worktree path>
+```
+
+`window=` remains the caller-facing Firstmate alias.
+`terminal=` and `orca_worktree_id=` are the backend authority used by operation and cleanup paths.
+
+## Current lifecycle and safety
+
+Spawn registers the repository, creates an independent worktree, reuses only the verified `result.terminal.handle` returned by Orca or creates a terminal explicitly, installs harness hooks, records metadata, and launches the selected harness.
+Exact command flags and response parsing are owned by `bin/backends/orca.sh` and script help.
+
+`fm-peek.sh` reads with `orca terminal read`.
+An ordinary metadata-routed `fm-send.sh` text steer becomes a durable steering-inbox record, and only its best-effort constant doorbell passes through Orca's submit machinery.
+On the typed plane, `fm-send.sh` verifies composer clearance through the fleet-wide classifier in `bin/fm-composer-lib.sh`, retrying Enter without retyping when a slash popup first fills an argument placeholder.
+The composer read is one bounded tail of the live terminal and never pages backward into scrollback, so a stale startup banner cannot compete with the bottom-anchored composer.
+A bare shell row is `unknown`, not an empty agent composer, and plain-text captures degrade a glyph row carrying trailing text to `unknown` rather than a false `pending`.
+The watcher has no native Orca busy signal, so each harness adapter's semantic lifecycle supplies worker state.
+Grok alone retains its isolated rendered-tail fallback.
+
+Cleanup keeps all shared Firstmate safety checks.
+A scout still requires its report and completed decision inventory.
+A ship still refuses dirty or unlanded work.
+Before release, cleanup resolves the recorded Orca worktree id and verifies its path matches the recorded worktree path.
+A missing, unreadable, or mismatched identity preserves metadata and stops rather than deleting anything.
+After those checks, Firstmate closes the exact terminal and releases the exact worktree with Orca's worktree command.
+It never raw-deletes an Orca worktree.
+
+## Active limits
+
+- Orca is macOS-only and explicit-only.
+- The app must be running and report ready.
+- Secondmate spawns are unsupported.
+- Escape is unsupported.
+- Orca exposes no stable CLI version or protocol marker, so readiness is the compatibility gate rather than a version floor.
+- Only the verified terminal-handle and worktree result fields are accepted; speculative response shapes are rejected.
+
+## Regression entry points
+
+```sh
+tests/fm-backend-orca.test.sh
+tests/fm-backend.test.sh
+tests/fm-bootstrap.test.sh
+```
+
+[`verification/runtime-backends.md`](verification/runtime-backends.md#orca) records the real readiness and response-shape smoke.

package/assets/reference/docs/pi-supervision-branch-poster.svg

@@ -0,0 +1,125 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 860" width="1200" height="860" role="img" aria-labelledby="poster-title poster-desc">
+  <title id="poster-title">Multi-brain agent architecture</title>
+  <desc id="poster-desc">One agent. Two branches of attention. Events are commits. A git-graph poster of one fix: silent notes merge with zero turns; only the merge that matters wakes the main brain.</desc>
+  <defs>
+    <pattern id="poster-grid" width="36" height="36" patternUnits="userSpaceOnUse">
+      <path d="M 36 0 L 0 0 0 36" fill="none" stroke="#8CAAE6" stroke-opacity="0.06" stroke-width="1"/>
+    </pattern>
+  </defs>
+  <rect width="1200" height="860" fill="#0D1321"/>
+  <rect width="1200" height="860" fill="url(#poster-grid)"/>
+  <rect x="0.5" y="0.5" width="1199" height="859" fill="none" stroke="#94B4FF" stroke-opacity="0.20" stroke-width="1"/>
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace">
+    <text x="48" y="56" fill="#E6EDF3" font-size="36" font-weight="700">Multi-brain agent architecture</text>
+    <text x="48" y="86" fill="#8CA3C7" font-size="18">One agent. Two branches of attention. Events are commits.</text>
+    <text x="1152" y="56" text-anchor="end" fill="#8CA3C7" fill-opacity="0.7" font-size="14">fig. 1 - firstmate</text>
+  </g>
+  <g transform="translate(0 100)" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace">
+<title id="mb-title">Multi-brain agent architecture drawn as a git graph: one fix's lifecycle. The worker finishes and CI runs (silent note), the captain's merge-when-green instruction is cherry-picked down, a flaky test is rerun (silent note), and when CI goes green the supervision brain merges and one note wakes the main brain.</title>
+        <defs>
+          <marker id="ah-cyan" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7.5" markerHeight="7.5" orient="auto-start-reverse">
+            <path d="M 0 0 L 10 5 L 0 10 z" fill="#56C8FF"></path>
+          </marker>
+          <marker id="ah-amber" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7.5" markerHeight="7.5" orient="auto-start-reverse">
+            <path d="M 0 0 L 10 5 L 0 10 z" fill="#FFB454"></path>
+          </marker>
+          <marker id="ah-time" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+            <path d="M 0 0 L 10 5 L 0 10 z" fill="#8CA3C7"></path>
+          </marker>
+          <linearGradient id="merge-up" x1="0" y1="1" x2="1" y2="0">
+            <stop offset="0" stop-color="#56C8FF"></stop>
+            <stop offset="1" stop-color="#FFB454"></stop>
+          </linearGradient>
+        </defs>
+
+        <!-- ================= LANE LINES ================= -->
+        <line x1="280" y1="210" x2="1140" y2="210" stroke="#FFB454" stroke-width="3" stroke-linecap="round"></line>
+        <path d="M 310 221 C 310 380, 330 490, 420 490" fill="none" stroke="#56C8FF" stroke-width="3" stroke-linecap="round"></path>
+        <line x1="420" y1="490" x2="1140" y2="490" stroke="#56C8FF" stroke-width="3" stroke-linecap="round"></line>
+
+        <!-- ================= LANE LABELS ================= -->
+        <text x="64" y="200" fill="#FFB454" font-size="24" font-weight="700">MAIN SESSION</text>
+        <text x="64" y="230" fill="#E6EDF3" opacity="0.6" font-size="16">talks with the captain</text>
+        <text x="64" y="480" fill="#56C8FF" font-size="24" font-weight="700">SUPERVISION SESSION</text>
+        <text x="64" y="510" fill="#E6EDF3" opacity="0.6" font-size="16">handles the routine,</text>
+        <text x="64" y="534" fill="#E6EDF3" opacity="0.6" font-size="16">decides to wake main brain or not</text>
+
+        <!-- ================= CROSS-LANE ARCS (all arrowed, drawn under chips) ================= -->
+        <path id="arc-quiet-1" d="M 460 479 C 490 400, 520 300, 545 221" fill="none" stroke="#56C8FF" stroke-width="2.5" stroke-dasharray="1 7" stroke-linecap="round" opacity="0.6" marker-end="url(#ah-cyan)"></path>
+        <path id="arc-cherry" d="M 620 221 C 645 300, 675 400, 700 479" fill="none" stroke="#FFB454" stroke-width="2.5" stroke-dasharray="2 8" stroke-linecap="round" opacity="0.8" marker-end="url(#ah-amber)"></path>
+        <path id="arc-quiet-2" d="M 760 479 C 785 400, 810 300, 830 221" fill="none" stroke="#56C8FF" stroke-width="2.5" stroke-dasharray="1 7" stroke-linecap="round" opacity="0.6" marker-end="url(#ah-cyan)"></path>
+        <path id="arc-wake" d="M 940 479 C 975 410, 1015 300, 1038 226" fill="none" stroke="url(#merge-up)" stroke-width="4" stroke-linecap="round" marker-end="url(#ah-amber)"></path>
+
+        <!-- ================= EXAMPLE CHIPS ON THE ARCS ================= -->
+        <g id="chip-quiet-1">
+          <title>A silent note: nothing needs the captain yet</title>
+          <rect x="385" y="312" width="230" height="36" rx="6" fill="#0D1321" stroke="#56C8FF" stroke-width="1.5" opacity="0.95"></rect>
+          <text x="500" y="336" text-anchor="middle" fill="#B9E5FF" font-size="16">&#8220;PR opened, CI running&#8221;</text>
+        </g>
+        <g id="chip-cherry">
+          <title>The captain's own instruction, cherry-picked down as context</title>
+          <rect x="530" y="377" width="260" height="36" rx="6" fill="#0D1321" stroke="#FFB454" stroke-width="1.5" opacity="0.95"></rect>
+          <text x="660" y="401" text-anchor="middle" fill="#FFD9A0" font-size="16">you: &#8220;merge when CI green&#8221;</text>
+        </g>
+        <g id="chip-quiet-2">
+          <title>A silent note: the supervision brain already fixed it</title>
+          <rect x="665" y="272" width="270" height="36" rx="6" fill="#0D1321" stroke="#56C8FF" stroke-width="1.5" opacity="0.95"></rect>
+          <text x="800" y="296" text-anchor="middle" fill="#B9E5FF" font-size="16">&#8220;flaky test: reran, passed&#8221;</text>
+        </g>
+        <g id="chip-wake">
+          <title>The outcome the captain asked for: this note wakes the main brain</title>
+          <rect x="865" y="342" width="250" height="38" rx="6" fill="#0D1321" stroke="#FFB454" stroke-width="2"></rect>
+          <text x="990" y="367" text-anchor="middle" fill="#FFB454" font-size="17" font-weight="600">&#8220;merged: your fix is in&#8221;</text>
+        </g>
+
+        <!-- ================= MAIN COMMITS ================= -->
+        <g id="main-commits">
+          <title>The captain's conversation, commit by commit</title>
+          <circle cx="310" cy="210" r="11" fill="#0D1321" stroke="#FFB454" stroke-width="3.5"></circle>
+          <circle cx="620" cy="210" r="11" fill="#0D1321" stroke="#FFB454" stroke-width="3.5"></circle>
+          <circle cx="1120" cy="210" r="11" fill="#0D1321" stroke="#FFB454" stroke-width="3.5"></circle>
+        </g>
+        <!-- silent-note landings -->
+        <g id="silent-landings">
+          <title>Notes merged silently into the conversation: no one is woken</title>
+          <circle cx="545" cy="210" r="7" fill="#0D1321" stroke="#56C8FF" stroke-width="3" opacity="0.85"></circle>
+          <circle cx="830" cy="210" r="7" fill="#0D1321" stroke="#56C8FF" stroke-width="3" opacity="0.85"></circle>
+        </g>
+        <text x="545" y="174" text-anchor="middle" fill="#56C8FF" opacity="0.8" font-size="13.5">silent merge. zero turns</text>
+        <text x="830" y="174" text-anchor="middle" fill="#56C8FF" opacity="0.8" font-size="13.5">silent merge. zero turns</text>
+        <!-- the merge commit that wakes the main brain -->
+        <g id="merge-commit">
+          <title>Merged and surfaced: the main brain is woken exactly once</title>
+          <circle cx="1040" cy="210" r="13" fill="#FFB454"></circle>
+          <circle cx="1040" cy="210" r="21" fill="none" stroke="#FFB454" stroke-width="1.5" opacity="0.5"></circle>
+          <path d="M 1019 189 A 30 30 0 0 1 1061 189" fill="none" stroke="#FFB454" stroke-width="2.5" stroke-linecap="round" opacity="0.8"></path>
+          <path d="M 1011 181 A 41 41 0 0 1 1069 181" fill="none" stroke="#FFB454" stroke-width="2.5" stroke-linecap="round" opacity="0.5"></path>
+        </g>
+        <text x="1040" y="148" text-anchor="middle" fill="#FFB454" font-size="18" font-weight="700">wakes the main brain</text>
+
+        <!-- ================= BRANCH COMMITS + EVENT EXAMPLES ================= -->
+        <g id="branch-commits">
+          <title>One fix's routine events, handled on the supervision brain</title>
+          <circle cx="460" cy="490" r="10" fill="#0D1321" stroke="#56C8FF" stroke-width="3.5"></circle>
+          <circle cx="760" cy="490" r="10" fill="#0D1321" stroke="#56C8FF" stroke-width="3.5"></circle>
+          <circle cx="940" cy="490" r="10" fill="#0D1321" stroke="#56C8FF" stroke-width="3.5"></circle>
+        </g>
+        <!-- cherry-pick landing -->
+        <circle cx="700" cy="490" r="8" fill="#0D1321" stroke="#FFB454" stroke-width="3"></circle>
+
+        <line x1="460" y1="503" x2="460" y2="530" stroke="#56C8FF" stroke-width="1.5" opacity="0.35"></line>
+        <text x="460" y="554" text-anchor="middle" fill="#E6EDF3" opacity="0.75" font-size="16">worker finishes the fix</text>
+        <line x1="760" y1="503" x2="760" y2="530" stroke="#56C8FF" stroke-width="1.5" opacity="0.35"></line>
+        <text x="760" y="554" text-anchor="middle" fill="#E6EDF3" opacity="0.75" font-size="16">a flaky test fails</text>
+        <line x1="940" y1="503" x2="940" y2="530" stroke="#56C8FF" stroke-width="1.5" opacity="0.35"></line>
+        <text x="940" y="554" text-anchor="middle" fill="#E6EDF3" opacity="0.75" font-size="16">CI goes green</text>
+
+        <!-- ================= TIME AXIS ================= -->
+        <line x1="1010" y1="660" x2="1110" y2="660" stroke="#8CA3C7" stroke-width="2" stroke-linecap="round" marker-end="url(#ah-time)"></line>
+        <text x="1128" y="665" fill="#8CA3C7" font-size="15">time</text>
+
+        <!-- ================= MORAL ================= -->
+        <text x="560" y="700" text-anchor="middle" fill="#E6EDF3" opacity="0.6" font-size="18">Routine merges back silently. Only what needs you wakes the main brain.</text>
+  </g>
+</svg>

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

@@ -0,0 +1,96 @@
+# Pi supervision branch
+
+![Multi-brain agent architecture: one agent, two branches of attention, events are commits](pi-supervision-branch-poster.svg)
+
+The poster is the visual of the idea.
+This document stays the owner and the contract.
+
+Fleet supervision on the Pi primary harness runs on a second, persistent conversation - the supervision branch - inside the same `pi` process as the captain's chat.
+Supervision is default-on: once a Pi primary session owns this home's fleet lock, the branch handles eligible task-local rows from ordinary actionable wakes plus heartbeat scans that the cheap bash-level scan flags as possibly captain-relevant, then merges each outcome back by appending a short note to the captain conversation's tail.
+Ordinary main-only rows remain on main even when eligible task-local rows share their queue.
+An unresolvable row makes the scan unsafe and returns the whole wake to main, and every watcher-failure alarm also stays on main.
+Only captain-relevant branch outcomes open a turn on main; the generated [Pi supervision protocol](supervision-protocols/pi.md) requires MAIN to produce the captain-visible response in that turn, while Pi never separately prints or renders a captain-facing merge note.
+The design source is the captain-approved forked-supervision architecture board, a captain-private fleet record (a self-contained HTML explainer with the measured cache and judgment evidence); this document records the shape it landed as, and the delivering PR cites the board artifact itself.
+
+This feature is Pi-only by construction and changes nothing anywhere else:
+
+- The branch lives in `.pi/extensions/fm-branch-supervision.ts`, which only a Pi primary ever loads; no other harness gains or loses behavior.
+- The bash-side additions (leases, the outcome store, session-start recovery) are inert in a home that never runs the branch: no lease files exist, no actor variable is set, every guard passes silently, and no new state appears (`tests/fm-branch-supervision.test.sh` holds this).
+- It does not change which harness is primary and never moves a home to Pi.
+
+## Components and their owners
+
+- Wake dispatch: `.pi/extensions/fm-primary-pi-watch.ts` stays the dispatcher; `.pi/extensions/lib/fm-branch-dispatch.ts` owns the offer handshake and row eligibility, while [`watcher-continuity.md`](watcher-continuity.md#per-actor-acknowledgement) owns the per-actor consume contract.
+  A successful row grant transfers ownership of exactly the currently branch-eligible rows to the branch; a check-kind triggering close (merge-confirmation polls, Relay mentions, credential/auth failures, and every other legitimately main-only class) is never offered even when other rows are eligible, no acceptor (extension absent, away mode, branch broken) keeps today's wake-to-main path for that close, and watcher-failure alarms always go to main because only main can repair the watcher cycle.
+  A fleet-wide heartbeat keeps its own all-or-nothing rule (see "Heartbeat routing" below): it takes every branch-ownable unread row or none of them.
+  A co-present main-owned check row no longer defers that review to main, because it is not fleet context the branch is missing and main is woken for it on its own triggering close.
+- The branch itself: `.pi/extensions/fm-branch-supervision.ts` creates and reopens the persistent branch session, serializes wakes, mirrors dialog, and merges outcomes.
+  It checks the current extension generation and `state/.lock` ownership before each guarded branch side effect so replacement or lock loss cannot let an old continuation mutate the new session.
+  Every path that cannot reach a working branch falls back to delivering the wake to main - a broken branch degrades to today's behavior, never to a lost wake.
+- Branch model and effort selection: the same extension registers `/supervision-model`, which picks the branch's model and then its reasoning effort, and applies both at the branch-session creation boundary; [configuration.md](configuration.md#pi-supervision-branch-model-and-effort-configsupervision-branch-model-configsupervision-branch-effort) owns the operator-facing schema and behavior.
+- Branch system prompt: `bin/fm-branch-prompt.sh`; its header owns the byte-stable-prefix contract (no timestamps, no fleet snapshot, no per-wake content).
+- Outcome store: `bin/fm-branch-outcome.sh`; its header owns the append-only format and the read cursor.
+  Outcomes are written to the store before any note is handed to Pi, and rows that never reach that handoff replay once through the next locked session-start digest.
+- Consistency: `bin/fm-lease-lib.sh` owns the per-task lease contract, the main-only role partition, and the deliberate CONFUSED-AGENT-GRADE threat model these guards target (captain-decided; adversarial-grade separation is out of scope and tracked as follow-up design work); `bin/fm-lease.sh` is the command surface.
+  The guards are wired into `fm-send.sh`, `fm-control.sh`, and `fm-teardown.sh` (overlap, lease-checked, with claim serialization retained through the mutation) and `fm-pr-merge.sh`, `fm-merge-local.sh`, and `fm-spawn.sh` (main-owned, branch refused; a relaunch through `fm-control` stays branch-legal recovery).
+- Autonomy: supervision is default-on for every task once a Pi primary session owns the fleet lock (docs/configuration.md "Pi supervision branch"); no captain grant file is required.
+  A fleet-wide heartbeat is separately eligible only when every non-check row in the unread queue is a heartbeat row or a resolvable task-local row (see "Heartbeat routing" below); every other fleet-wide or unresolvable wake, and every watcher-failure alarm, stays on main.
+  The branch recomputes eligibility immediately before prompting the branch to drain and publishes the exact eligible row set to `state/.branch-eligible-rows` through `writeEligibleRowsSnapshot`.
+  A newly-arrived main-owned row observed at that recheck no longer defers the whole queue to main: it is excluded from the eligible set, so whatever else is currently eligible still reaches the branch, and the main-owned row stays queued for main's own later drain.
+  [`watcher-continuity.md`](watcher-continuity.md#per-actor-acknowledgement) owns the consume-side guarantee that neither actor can present or acknowledge the other's claim.
+  Heartbeat keeps its own all-or-nothing recheck over the rows it can claim: it takes every branch-ownable unread row or none of them, and an unresolvable task-local row still defers the whole review to main.
+  A producer can still append a row in the instant between that final check and drain startup; this accepted residual follows the confused-agent-grade boundary above rather than claiming adversarial queue isolation.
+  Away mode and a broken branch keep today's wake-to-main behavior.
+
+## How the branch knows what the captain said
+
+Main's captain and assistant text - never tool calls, tool results, operational injections, or the branch's own merged notes - is mirrored into the branch as read-only `fm-main-mirror` messages.
+The idle path mirrors at main's turn end.
+At `before_agent_start`, Pi's authoritative prompt is staged verbatim before SessionManager persists that user entry, so the complete current captain message precedes any branch wake accepted after that boundary; the later persisted copy is suppressed and older dialog entries remain bounded.
+The mirror cursor is durable (`state/.branch-mirror-cursor`), so a restart replays only the not-yet-mirrored dialog from main's session file, and a replacement main session re-anchors from its start.
+The branch prompt frames mirrored text as context for judgment, never as instructions addressed to the branch; an authorization addressed to main (for example "you may merge when green") does not relax the branch's role limits.
+
+## Two-stage noise filter
+
+Stage one is unchanged: the bash watcher absorbs everything provably fine at zero token cost.
+Stage two is the branch's verdict on each handled event, reported through its `fm_branch_report` tool: `routine` merges without a follow-up turn, while `captain` merges with exactly one follow-up turn.
+The generated [Pi supervision protocol](supervision-protocols/pi.md) requires MAIN to produce the captain-visible response in the one follow-up turn a `captain` verdict opens, so its merge note is delivered silently and never printed or rendered in Pi.
+Because Pi gives the model only a custom message's `content`, that silent note normally carries both a relay instruction and the `branch-outcome` operational kind owned by `bin/fm-operational-input.sh` inside its own text.
+This self-description lets main distinguish a new supervision outcome from its own earlier captain-facing answer; without it, main can mistake the outcome for that answer and lose the outcome while deciding how to handle it.
+The generated [Pi supervision protocol](supervision-protocols/pi.md) owns main's event-ownership and conversational-treatment instructions for merged outcomes.
+If envelope encoding fails, the captain-facing note degrades to the same runtime instruction as plain text rather than losing the outcome or opening another turn.
+A no-change heartbeat outcome explicitly reported with `task=fleet` and `silent=true` is also delivered silently with no rendered note, while every other `routine` outcome stays rendered with its sailboat prefix.
+The branch prompt owns the verdict criteria, including its unconditional explicit-request rule; unsolicited routine outcomes remain routine sailboat notes, unchanged fleet reviews remain silent, and doubt escalates.
+Main can read the durable outcome store on demand through its `fm_branch_outcomes` tool.
+
+## Heartbeat routing
+
+The cheap bash-level heartbeat scan absorbs a genuinely no-op pass before it reaches Pi, unchanged from before.
+Only a scan already flagged as possibly captain-relevant emits the bare `heartbeat` wake; `.pi/extensions/fm-primary-pi-watch.ts` flags that offer `heartbeat: true`, and the branch accepts it without a project only when every non-check row observed in the unread-queue eligibility check is either heartbeat-kind or a resolvable task-local signal or stale event.
+
+A heartbeat is never vetoed or ridden into main by a co-present check row.
+A check row is permanently main-owned in every mode: it is excluded from what the branch may claim and left queued for main, which is woken for it on that check's own watcher cycle, so nothing starves by being left behind.
+Deferring the fleet review to main merely because some unrelated merge poll or Relay mention happened to be sitting unread put a routine review in the captain's chat for a reason that had nothing to do with the fleet, and that coupling is gone.
+What all-or-nothing still guarantees is unchanged: the branch takes every branch-ownable unread row or none of them, and an unresolvable task-local row, an unknown row kind, or an unreadable queue still defers the whole review to main.
+The branch runs its normal operating procedure for the wake (`bin/fm-branch-prompt.sh` "Handling a wake") and performs the deeper fleet review that main previously performed.
+A review that found literally nothing worth reporting uses verdict `routine`, `task=fleet`, and `silent=true` so it has no rendered note, while a fleet-wide routine action omits `silent` and keeps its rendered sailboat note.
+Only a captain-worthy finding reports verdict `captain` and opens a main turn.
+Every other fleet-wide or unresolvable wake - including watcher-failure alarms, which are never offered to the branch - keeps today's wake-to-main path.
+
+## Cost model and the byte-stable prefix
+
+The captain accepted the normal provider prompt-caching strategy: a byte-identical branch prefix generated once per firstmate version, the same tool set in the same order on every request, and one shared `prompt_cache_key` per home for all branch sessions (set in a `before_provider_request` hook, and only for providers whose requests already carry that field); main keeps its own per-session key.
+Budget roughly 60% cache hits on a fresh branch session's first call and 95% on later calls of the persistent session; reuse is best-effort, never guaranteed.
+The branch can also run on a cheaper model and a shallower reasoning effort than main, both pinned with the Pi `/supervision-model` command; [configuration.md](configuration.md#pi-supervision-branch-model-and-effort-configsupervision-branch-model-configsupervision-branch-effort) owns those pins' operator-facing schema and unpinned behavior.
+No caching machinery beyond this exists, deliberately: any later dynamic content in the branch prefix silently removes most of the cache benefit, which is why `bin/fm-branch-prompt.sh`'s header is the contract's single owner and `tests/fm-branch-supervision.test.sh` pins the output to byte identity.
+
+## Away mode
+
+Away mode carries over unchanged: while `state/.afk` exists the away daemon owns supervision, and the branch declines every wake offer for the duration.
+What is new is only the attended path: outside away mode, the branch absorbs the routine majority that previously interrupted the captain's conversation, applying the same escalation etiquette the daemon applies while away.
+
+## Verification
+
+Portable regressions: `tests/fm-pi-branch-extension.test.sh` (dispatch, default-on eligibility, main-only classification, requested-versus-unsolicited outcome delivery, pre-turn-end complete-current-request mirroring, fleet-event ownership, main outcome access, eligible-row claim lifecycle, partial pre-drain recheck, fallback, filter, model-visible captain-outcome typing and plain-instruction fallback, cache key, persistence, model pin and searchable picker, effort pin), `tests/fm-branch-supervision.test.sh` (prompt stability, store append-only, leases, guards, non-branch-home invariance), the branch-offer, heartbeat-offer, heartbeat-not-ridden-by-a-check, and main-only-check-class tests in `tests/fm-pi-watch-extension.test.sh`, the recovery test in `tests/fm-session-start.test.sh`, and the per-actor consume regression in `tests/fm-wake-queue.test.sh`.
+Live guard: `FM_PI_BRANCH_LIVE_E2E=1 tests/fm-pi-branch-live-e2e.test.sh` exercises the real installed Pi SDK's custom-message conversion and branch-session surfaces with no user credentials and no provider call; run it after every Pi upgrade and record the dated result in [docs/verification/runtime-backends.md](verification/runtime-backends.md).
+The strict typecheck in `tests/fm-pi-primary-types.test.sh` pins the extension against the installed Pi package.