@zerwiz/ymir 0.1.16 → 0.1.18

package/assets/reference/docs/voice-relay.md

@@ -0,0 +1,295 @@
+# The spoken interface
+
+Talk to a voice agent that sits in front of the first mate. It answers questions
+about what is happening from the first mate's own records, and when you ask for
+real work it says so out loud and queues the request rather than pretending to
+do it.
+
+This is step one of three: a spoken round trip that works. Interrupting the agent
+mid-sentence and carrying context from one question to the next are step three,
+and [what this build does not do](#what-this-build-does-not-do) is explicit about
+where the edge is.
+
+## The shape
+
+Your laptop captures the audio and plays the reply. This desktop holds the
+conversation with the model. Nothing in between needs AWS credentials on the
+laptop, which is the whole reason for this shape.
+
+```
+laptop                          this desktop                      AWS
+------                          ------------                      ---
+microphone --> fm-voice-client.py --(ssh)--> fm-voice-relay.py --> Nova Sonic 2
+speaker    <-------------------------------------------------      (your region)
+                                        |
+                                        +--> the first mate's records (read)
+                                        +--> fm-inbox.sh note (queue real work)
+```
+
+The two ends share one bidirectional byte stream over an SSH exec channel, so
+audio and control travel together and need framing. `bin/fm_voice_frame.py` is
+the owner of that format and is the only file both machines run.
+
+The relay reads records and queues work. It never changes a project, and the
+queueing half is `bin/fm-inbox.sh note`, the same surface the captain's own
+out-of-band capture already uses, rather than a second queue.
+
+## What it costs in time
+
+Measured on 2026-08-21 against the reviewed relay code, `amazon.nova-2-sonic-v1:0` in `eu-north-1`, on a spoken question that makes the agent read the records before it can answer, which is the slowest ordinary case.
+Six runs each, all six answered each way.
+
+| Path | First audio out, seconds | Median |
+| --- | --- | --- |
+| Direct from this desktop, no relay | 1.165 1.190 1.215 1.250 1.281 1.352 | 1.232 |
+| Over the relay, real client and framing | 1.138 1.165 1.171 1.174 1.177 1.283 | 1.172 |
+
+The clock starts the instant the captain stops speaking and stops when the first byte of reply audio arrives.
+An earlier measurement of the same question, on the same model and region and also reading the records, put the direct path at 1.164 seconds median over five runs, and this control reproduces it to within the noise floor below.
+That measurement is not published here, so read it as corroboration rather than as something to open: the direct column stands as a control on its own, because it was taken in the same pass, on the same clip, model, region and read scope, with only the relay removed.
+
+**The relay's own cost is smaller than this measurement can resolve.**
+The relay median lands below the direct control, which does not mean the relay is faster: two direct-control passes twenty minutes apart differ by 0.070 seconds of median, so that is the floor, and framing and the extra process hop are both under it.
+The earlier measurement above independently agrees on that floor, spreading 0.087 seconds across its own five runs, and two measurements agreeing on the noise are worth more than one asserting it.
+Read the two rows as the same number.
+
+The first pass, on the relay as first written, put it 0.22 seconds behind the control, and that gap read as framing, the process hop and the per-turn reconnect.
+It was none of them, and the difference is worth keeping, because a wrong number invites a re-measurement while a wrong cause invites a fix to the wrong part of the relay.
+Each relay run is six turns in one session, so a per-turn defect shows up as a step: that pass stepped from 1.229 on turn one to a 1.447 median across turns two to six, and the same step appeared independently on the talk-end-to-tool-request mark, 0.599 rising to 0.730.
+The re-measured passes are flat, stepping 0.009 and 0.021.
+The 0.22 seconds was the relay resolving AWS credentials again for every turn's session, which review found and fixed: `Credentials` in `bin/fm-voice-relay.py` resolves once, and every later session reuses that answer, so a reconnect costs a reconnect.
+This is the second time credential resolution has dominated a voice path's latency on a host like this one, because earlier prototype work measured the local credential helper at about a second per call and found that fixed per-call overhead exceeded the model's own cost.
+So it is the first thing to suspect when a spoken path is slower than the model, and it is worth checking that anything new doing per-turn work resolves credentials once rather than once per session.
+
+What the relay figure does NOT include, and could not be measured from here:
+
+- **The SSH hop itself.**
+  These runs drove the relay as a local child process, which is the identical relay command with only the `ssh -T <host>` prefix omitted, so the client, the framing, the uplink ordering, the relay, the records read and the handover are all real and only the SSH subprocess is absent.
+  Two facts bound what its absence can be hiding.
+  A constant transport cost cannot produce the turn-by-turn step that the credential defect produced, and the first pass, which did run over `ssh localhost`, put its own first turn 0.009 seconds above its own direct control.
+  Neither of those is a measurement of the SSH path on this code, and neither is offered as one.
+- **Your laptop's round trip to this desktop.**
+  Add roughly your own round trip time: the audio goes up and the reply comes back, so it lands about once.
+- **Microphone capture and speaker output latency.**
+  This desktop has no microphone and no speaker, so every measurement used audio files.
+  The client reports both device figures in its own output, so your first live run measures them rather than guessing.
+
+So your number is about 1.15 to 1.3 seconds plus your round trip time plus your audio devices.
+It is worth saying plainly that this came in under the bottom of the 1.5 to 2.5 second estimate the relay shape was given before it was built.
+The safer shape, with no credentials on the laptop, is not the slower one.
+
+## Setting up this desktop
+
+The model is only reachable over HTTP/2 bidirectional streaming, which the AWS
+CLI cannot drive and `boto3` cannot either. It needs the experimental SDK, in a
+virtual environment of its own:
+
+```
+python3 -m venv ~/.fm-voice-venv
+~/.fm-voice-venv/bin/pip install aws-sdk-bedrock-runtime
+```
+
+Then tell this home which account and model to use.
+The relay carries no default for any of these, because a region, a model id and an AWS profile name somebody's account and somebody's choices, and inheriting those from whoever wrote the code is not a sensible way to start talking to a paid API.
+Each value is one line in your gitignored `config/` directory, and each has an environment variable that overrides it for a single run.
+
+| File | Environment | Holds |
+| --- | --- | --- |
+| `config/voice-region` | `FM_VOICE_REGION` | The Bedrock region to open the session in, required. |
+| `config/voice-model` | `FM_VOICE_MODEL` | The Nova Sonic model id, required. |
+| `config/voice-profile` | `FM_VOICE_PROFILE` | The AWS profile to export credentials from, optional: with no profile the relay uses only credentials that are already in its environment. |
+| `config/voice-id` | `FM_VOICE_ID` | The output voice, optional and `matthew` when unset. |
+
+A missing required value refuses with the path to write, so an unconfigured home cannot start the relay by accident, and that configuration is the whole opt-in.
+`docs/configuration.md` is the registry for these files.
+
+Check it end to end without a microphone, using a recorded question:
+
+```
+cd <your firstmate home>
+~/.fm-voice-venv/bin/python bin/fm-voice-relay.py --self-test <clip.pcm>
+```
+
+The clip is headerless 16000 Hz mono signed 16-bit little-endian PCM and must end
+on speech, not silence. It prints one JSON line: what it heard, what it said, how
+long each stage took, whether it answered at all, and, in `relay_error`, what
+broke when a turn broke rather than merely going unanswered, so an
+infrastructure failure is not read as a slow answer. Feed it a clip that
+already ends in silence and it will tell you the timings are measured from the
+wrong instant rather than printing a number that looks fast.
+
+## Setting up the laptop
+
+**The audio devices are not verified.** No worker can reach the captain's laptop, so neither the microphone nor the speaker has ever been opened.
+Treat the first live run as their test, and expect the device setup to be where it fails.
+Everything around them is exercised with files.
+That includes the speaker's own byte accounting, the arithmetic deciding which turn a chunk of reply audio is credited to and whose first-audio clock it stamps, which runs against a stub stream in the test suite.
+Covering that arithmetic says nothing about how a real output device behaves.
+
+Copy the two files the laptop needs, and install the one dependency:
+
+```
+scp <desktop>:<firstmate home>/bin/fm-voice-client.py .
+scp <desktop>:<firstmate home>/bin/fm_voice_frame.py .
+python3 -m pip install sounddevice
+```
+
+`sounddevice` needs PortAudio, which on macOS is `brew install portaudio`. macOS
+will ask for microphone permission for whichever terminal you run this from, once.
+
+Then talk:
+
+```
+python3 fm-voice-client.py --host <desktop> \
+  --relay <firstmate home>/bin/fm-voice-relay.py \
+  --relay-python ~/.fm-voice-venv/bin/python
+```
+
+The client has no built-in idea of where the relay lives on your desktop, so `--relay` is required and `FM_VOICE_RELAY` sets it once for a shell.
+
+Press Enter to start talking, press Enter again when you have finished. It prints
+the timings for each turn as JSON on stdout and everything human on stderr, so
+`--runs 5 > runs.jsonl` gives you your own spread to compare against the table
+above.
+
+Every record carries `relay_error`, which is null when nothing broke and otherwise names what did.
+Where this end is left to infer what happened, it tells the two mid-turn failures apart, because they are not the same fault: a turn that got no reply audio at all says the connection ended, or was lost, or the relay stopped, or the session ended, before that turn was answered, while a turn whose answer had already started playing says the same thing happened before the reply finished.
+The second still reads `answered: true`, because sound did reach you and `first_audio_s` is a real measurement of when.
+Two other shapes carry neither clause, so do not read the pair above as the whole list: a fault the relay names itself arrives as the relay's own words, which point at the desktop and are kept unaltered because it knows what this end can only guess at.
+A reason opening `this end could not handle the relay's reply` is the one that points at your laptop instead, so a healthy relay is not where to look for it.
+
+The exit code is non-zero if any turn went unanswered, if any record carries a `relay_error`, or if the session stopped before it had taken the runs you asked for.
+A truncated answer therefore fails the run rather than passing it, so a spread computed from `runs.jsonl` cannot quietly average an infrastructure failure into a latency figure.
+
+If the audio devices are not the ones you want, `--input-device` and `--output-device` take a name or an index.
+Neither the client nor this guide can yet tell you which device it resolved, so an unexpected device is diagnosed by trying the other name or index rather than by reading a log line.
+If it fails before any audio, add `--verbose` and look for the handshake: a chatty login shell on the desktop printing to stdout is the one failure that looks like a protocol error and is not.
+
+## What it may read
+
+An unconfigured home gets the narrow scope: counts of what is in flight, what is waiting on the captain and what is open for review, with no identifier, title or link assembled at all.
+Widening that is one line the captain of those records writes into `config/voice-read-scope` themselves.
+Two whole classes of record are excluded at every scope, and excluded by construction rather than filtered on the way out:
+
+- **Finished work in the backlog's done history**, because a spoken "what is
+  happening" answer is about open work, and old engagements accumulate there.
+- **Free-form note bodies**, because they are written for someone with the whole
+  file in front of them, and they are where commercial detail gets quoted.
+
+Only open work and this home's own runtime records are ever assembled.
+A task keeps its runtime record until teardown, so the count of workers on deck
+and the states beside it still include one whose item is already done; both are a
+number and a state word, never anything written in a record.
+Verified against the captain's live records on 2026-08-21: every occurrence of
+the one customer identifier those records contain sits in finished work or a note
+body, so nothing a status answer can say names a customer.
+`tests/fm-voice-relay.test.sh` holds that boundary as an executable check, so
+widening the reader later fails a test instead of quietly widening what is sent.
+
+Two settings control it, both optional and both in `config/`:
+
+| File | Effect |
+| --- | --- |
+| `voice-read-scope` | `counts` (the default, and what an absent file means) sends counts only, with no record free text assembled at all. `full` sends counts plus the names, titles and pull request links of open work. |
+| `voice-read-deny` | One plain case-insensitive substring per line; `#` comments. Each open item is matched once, against its identifier, its title, its tag values and its pull request link together, and a match is withheld from every list it could have appeared in and reduced to a count, so the agent still says how much is waiting without saying what it is. An absent file means an empty list. |
+
+`voice-read-deny` exists so that one future open item carrying a customer name
+can be excluded in a single line rather than by turning the feature off.
+
+The wider scope is not free. Measured on 2026-08-21 on the same question, on the
+relay as first written, so compare the two sides with each other rather than with
+the table above: the wide answer is 2872 bytes against 445, and it costs both time
+and consistency, at 1.348, 1.866 and 2.273 seconds against 1.351, 1.299 and 1.376.
+If the spoken answer only ever needs to be "three jobs running, two decisions
+waiting", `counts` is faster and steadier as well as narrower.
+
+An unreadable or misspelled `voice-read-scope` refuses rather than falling back
+to the wider setting, because falling back would widen what is sent on the
+strength of a typo.
+
+## Push to talk, and the setting that refuses
+
+Push to talk is the default: the microphone is closed until you ask for it. That
+is `$0.0101` per minute against `$0.0151` for an open microphone, and it is the
+setting nobody has decided yet, so this build does not choose the expensive one
+on the captain's behalf.
+
+`--listen open-mic` exists as a setting and refuses at startup today.
+An open microphone needs something to decide when you stopped speaking, and the client has no end-of-speech detection, so the mode would open a turn, stream audio forever and never mark a boundary, which leaves the relay appending to a session that has already answered.
+That detection belongs with carrying context across turns, which is step three, so the flag refuses before it opens an SSH connection or spends anything rather than half working.
+The setting stays where it is so that turning it on later is a small change rather than a new flag.
+
+## One turn per session, and what that gives up
+
+The relay reconnects to the model at the start of each turn. That is not
+tidiness, it is a measured requirement.
+
+A second question inside a session that has already answered one is treated as an
+interruption, unconditionally: the model raises it the instant the audio block
+opens. Waiting does not help. Six consecutive turns were tried with no wait, with
+a wait until all the reply audio had arrived, and with a wait of the reply's full
+spoken duration on top of that. Every one interrupted every second turn. Worse,
+an interrupted turn that needs to read the records is lost outright: the model
+asks for the records, takes them, and then never answers at all.
+
+Reconnecting costs 0.02 seconds and happens while the captain is pressing the
+talk key rather than while they are waiting for a reply, so it is invisible. With
+it, six turns in a row all answered.
+
+The same path covers a session the model ends on its own, mid-conversation: that
+costs the turn it was in and not the relay, and the next talk key builds a
+replacement. Either way the client hears about it at once rather than waiting out
+the whole reply timeout in silence.
+A turn still waiting for its answer when either happens names why in its own `relay_error`, and [setting up the laptop](#setting-up-the-laptop) describes those reasons.
+
+**What it gives up is memory.** Every question starts fresh, so "and what about
+that one" will not work. Carrying context across turns means handling
+interruption properly, which is step three.
+
+## Two traps worth keeping
+
+Both cost real time to find the first time. The code comments own the detail;
+these are the shapes.
+
+1. **The end of a reply is not the event that says the reply ended.** The obvious
+   completion event never arrives on its own. The real end is the content-end
+   event carrying an end-of-turn reason.
+2. **A clip with no trailing silence is never answered.** The model truncates it
+   and waits forever. The relay appends 400 ms of silence. Measured, this is a
+   content requirement and not a timing one: 0 ms and 100 ms were never answered,
+   while 200, 300, 400 and 800 ms all answered inside the same spread, because the
+   padding is sent as fast as the socket takes it. 400 ms is free margin above the
+   floor where answers start.
+
+## What this build does not do
+
+- **Interrupting the agent mid-sentence.** Nova Sonic supports it, measured, on
+  both model versions, so the capability is there when it is wanted. The concrete
+  thing step three has to solve is the interruption finding above: today any
+  second question in a session is treated as an interruption, and an interrupted
+  turn that reads the records produces no answer at all.
+- **Remembering the last question.** See above.
+- **Doing any project work.** Real work is queued for the first mate and the
+  agent says so out loud. It has no tool that changes a project.
+
+## Cost
+
+`$0.00293` per exchange, derived from the first pass's token counts and session seconds, which is roughly a dollar for three hundred and forty questions.
+The re-measured exchange is about a quarter of a second shorter, worth about `$0.00004` at the session rate below, so the figure is unchanged at the precision it is quoted to.
+Push to talk is `$0.0101` per minute of session against `$0.0151` with an open microphone.
+
+Text in and out is materially dearer on this model version than the one it
+replaces, so a long system prompt or a large record answer is a real cost as well
+as a real delay. That is the second reason the reader caps its lists rather than
+sending every row.
+
+## Owners
+
+| Concern | Owner |
+| --- | --- |
+| Wire format between the two machines | `bin/fm_voice_frame.py` |
+| The relay, the model session, the tools | `bin/fm-voice-relay.py` |
+| The laptop end, capture and playback | `bin/fm-voice-client.py` |
+| What may be read, and queueing real work | `bin/fm_voice_records.py` |
+| The queue the handover writes to | `bin/fm-inbox.sh` |
+| The boundary as an executable check | `tests/fm-voice-relay.test.sh` |

package/assets/reference/docs/watcher-continuity.md

@@ -0,0 +1,119 @@
+# Watcher continuity
+
+The watcher remains intentionally one-shot: one actionable reason closes one watcher cycle.
+Must-work continuity now lives above that process boundary instead of depending on the model remembering a re-arm step.
+
+## Ownership
+
+Pi's `.pi/extensions/fm-primary-pi-watch.ts` and OpenCode's `.opencode/plugins/fm-primary-watch-arm.js` own continuous re-arm after an actionable child close.
+Each adapter starts the next arm before delivering the wake prompt, checks current session-lock ownership at launch, preserves one child or scheduled retry at a time, and applies bounded exponential retry after an unexpected or failed close.
+A failed follow-up never cancels continuity restoration.
+Pi same-process session replacement follows the generation-owner contract in `.pi/extensions/fm-primary-pi-watch.ts`.
+Cursor's `.cursor/hooks.json` `stop` hook (`bin/fm-turnend-guard-cursor.sh`) owns routine tokenless re-arm for a Cursor primary by parking that awaited hook on `bin/fm-watch-arm.sh` and returning an actionable close as one follow-up; [`turnend-guard.md`](turnend-guard.md#harness-integrations) owns its Pi-host stand-down, loop bounds, and supersession baton.
+Claude's `.claude/settings.json` Stop `asyncRewake` hook (`bin/fm-claude-stop-autoarm.sh`) owns routine tokenless re-arm.
+The hook fires on every Stop, and an eligible primary with supervision need admits one home-scoped owner that foregrounds `bin/fm-watch-arm.sh` inside the hook-owned process tree.
+A numeric session-lock owner that fails the shared `fm_harness_pid_alive` predicate is reclaimed through `bin/fm-lock.sh` before auto-arm state changes, while a live owner, absent lock, or malformed lock keeps the competing hook inert.
+The stale-owner claim occurs only after the existing AFK and supervision-need gates pass.
+After each non-actionable arm close, the hook rechecks the identity-matched watcher lock and fresh beacon before retrying a bounded number of times.
+A cycle-end failure is benign when that live-watcher predicate is true, and the hook suppresses the arm output and continues silently.
+Only an exhausted failure with no verified watcher commits one last-resort notice for the continuous failure episode; a refused notice commit stays silent for a later retry, and after a successful notice later Stop cycles exit 2 without repeating it until the turn-end guard consumes the attended fail-open.
+The Claude turn-end guard owns that notice commit contract, the monotonic failure progression, one-time attended fail-open, post-alarm continuation suppression, and positive recovery reset described in [`turnend-guard.md`](turnend-guard.md#harness-integrations).
+While supervision is still needed and away mode remains inactive, an actionable close wakes the idle session through exit 2.
+
+## Actionable wake ordering
+
+After an actionable Pi or OpenCode child close, the adapter starts and verifies one singleton successor before it delivers the original wake.
+It confirms the handling handoff against that successor before scheduling the follow-up, retries once against the current generation and successor, and treats a failed confirmation as a restoration failure: it classifies the error, retires a successor that is no longer alive, and surfaces exactly one typed message.
+A failed confirmation is never swallowed.
+It waits at most one readiness timeout per attempt, then sends TERM and waits a bounded retirement confirmation before the next lock-verified exponential retry.
+If the unready arm does not retire within that bound, the adapter keeps ownership, starts no overlapping retry, and delivers the typed fallback immediately.
+When that retained arm later closes, its actual close is classified as a new supervised event without replaying the earlier fallback.
+After the configured retry bound is exhausted, it delivers the original wake with a typed continuity-restoration failure even if every successor arm hung without reporting readiness.
+This is deliberate Option B ordering: the fleet is protected before the model handles the wake whenever restoration succeeds, but the model is never left blind when it does not.
+
+Claude's Stop hook starts the successor arm at the next Stop after the handling turn, rather than before notification as Pi and OpenCode do.
+The durable wake queue preserves actionable events during the residual active-turn window, and the bounded turn-end guard enforces recovery at Stop when no watcher is live and no open generation claim is still deciding, so a finished, hung, or identity-mismatched claim cannot suppress it ([`turnend-guard.md`](turnend-guard.md#harness-integrations) owns that boundary).
+The recovery-episode contract below owns once-per-generation announcement.
+A handling successor does not re-announce; it enters its poll loop immediately and keeps scanning signals, stale panes, and checks.
+The model no longer re-arms after ordinary wakes.
+No PreToolUse hook denies fleet commands based on watcher status.
+A genuine auto-arm failure describes the automatic mechanism as broken and never directs a routine manual background arm.
+Terminal arm-output classification (`started`, `attached`, or `FAILED`) remains defense in depth for the manual recovery path.
+Codex retains its bounded foreground checkpoint protocol.
+Grok retains its tracked background-task notification protocol.
+No adapter starts a replacement with shell `&`.
+
+The turn-end guard remains the final backstop rather than the normal continuity mechanism and cooperates with the auto-arm in its `--claude` mode.
+
+## Recovery episode acknowledgement
+
+A recovery episode is one generation of `state/.watcher-down`, and it is retired only by the generation-bound acknowledgement the drain prints as `WAKE_ACK_REQUIRED`.
+An unacknowledged downtime generation is announced at most once: the first recovery marks that generation announced, and later arms wait until a new down stretch mints a new generation.
+A non-successor watcher start after an announced-but-unacked episode is a new down stretch and mints a fresh generation so buried decisions still resurface once.
+Every watcher close and every durable queue append publishes downtime, so a downtime republication of any pending episode reuses its generation instead of minting a new one, and an already-announced generation stays announced.
+That reuse keeps a watcher close inside the handling window from orphaning the acknowledgement already presented and trapping later arms in repeated recovery presentation.
+An acknowledgement carries two separable facts: queue-row consumption is bound to the monotonic `--ack-through` sequence (further scoped per actor - see "Per-actor acknowledgement" below), while only retiring the episode is bound to `--recovery-generation`.
+A generation mismatch therefore does not block consumption of rows through that sequence; it is a non-fatal result that names its own remedy - re-drain, then acknowledge the newer episode.
+The acknowledgement retires the marker only when no rows remain after sequence-bound consumption.
+A concurrently appended wake has a higher sequence, remains queued, and keeps the episode pending for presentation.
+Consequently, an empty-queue downtime publication during handling can be retired by the outstanding acknowledgement without a dedicated recovery turn.
+An acknowledged episode does not freeze the generation, because the next downtime after it opens an episode of its own.
+
+## Per-actor acknowledgement
+
+`bin/fm-wake-drain.sh` consumes the queue per actor, not per whole-queue cutoff, using `bin/fm-lease-lib.sh`'s existing `fm_lease_actor` identity (`FM_SUPERVISION_ACTOR`, unset or `main` for every non-Pi harness and Pi's own main session; `branch` only inside the Pi supervision branch's own bash tool calls, injected deterministically by the extension - never agent memory).
+Every presented row is claimed to exactly one actor under the durable queue lock.
+Main records its presented set in `state/.main-eligible-rows`.
+A branch grant is published through `bin/fm-wake-grant.sh` under that same lock in `state/.branch-eligible-rows`, bound to the live branch process and extension generation recorded in `state/.branch-eligible-owner`, and publication is refused if main already claimed any requested row.
+A main drain validates that owner evidence under the queue lock and reclaims the grant when its process is gone or its identity no longer matches.
+A main drain claims every currently unclaimed row and excludes an active branch grant from both presentation and acknowledgement.
+Its `--ack-through <SEQ>` deletes only claimed main rows at or below the cutoff, while a branch acknowledgement deletes only claimed branch rows at or below its cutoff.
+Every settled branch prompt releases any residual grant, so an omitted or failed acknowledgement leaves the durable row available to a later main drain; a successful acknowledgement has already removed it.
+If a branch offer loses the claim race to main, it falls back to a main follow-up rather than assuming the earlier main delivery is still live.
+[`pi-supervision-branch.md`](pi-supervision-branch.md#components-and-their-owners) owns branch eligibility, mixed-queue dispatch, the pre-drain recheck, and heartbeat's all-or-nothing rule.
+A check-kind row is main-owned in every mode, including a heartbeat review, so it is never part of a branch claim and never defers one; main is woken for it on that check's own triggering close.
+`fm-wake-drain.sh` never reclassifies a row itself: it filters the queue to the current actor's opaque claim before same-key deduplication, then presents and acknowledges only that actor-local view.
+A missing or empty branch snapshot is refused loudly rather than read as "nothing eligible", because reaching the drain without the non-empty handoff promised by the extension is a wiring bug.
+Because branch claims contain no check-kind rows, a branch acknowledgement skips check-specific receipt scans.
+`tests/fm-wake-queue.test.sh`'s mixed-queue actor tests drive both directions against the real scripts: branch acknowledgement cannot swallow a main row, and a concurrent main turn cannot present or acknowledge an active branch grant.
+`tests/fm-pi-branch-extension.test.sh` pins extension-side classification, claim publication and release, and the pre-drain recheck.
+
+## Arm-layer cycle contract
+
+`bin/fm-watch-arm.sh` never returns a clean empty success.
+An actionable child output returns that reason normally.
+A zero/empty child return rechecks the home lock and beacon, attaches to a verified healthy successor when one exists, or resolves the close against the watcher's bounded terminal-delivery ledger.
+An attached arm follows verified identity-matched successors and resolves the same way when that chain ends without one, because it holds no handle on the watcher's stdout and cannot read the reason line itself.
+Before releasing its singleton lock after printing an actionable reason, the watcher records that reason with its PID and process identity in `state/.watch-deliveries.log`.
+A matching PID and identity lets an attached arm report the delivered reason and exit zero even after its durable wake was handled and acknowledged, while an unrelated queue producer or a recycled PID cannot satisfy the match.
+Only a cycle with no matching delivery record emits `watcher: FAILED - cycle ended without an actionable reason` and exits nonzero.
+
+The arm layer appends one tab-separated record per observed cycle to `state/.watch-cycle-exits.log`.
+Each record includes arm and watcher PIDs, start and end timestamps, exit code and signal, classified reason, beacon age, lock identity before and after close, and successor disposition.
+The file is size-capped through `FM_WATCH_CYCLE_LOG_MAX_BYTES` and `FM_WATCH_CYCLE_LOG_KEEP_LINES`.
+`state/.watch-triage.log` remains only the watcher's bounded absorbed-wake debug log and carries no lifecycle semantics.
+
+The default 300-second grace is unchanged.
+Only the watcher process touches `state/.last-watcher-beat`; no helper process can make a wedged watcher appear healthy.
+
+## Regression coverage
+
+`tests/fm-pi-watch-extension.test.sh` checks Pi's first-cycle-or-explicit-repair tool metadata and ownership-based redundant-call no-ops, then simulates actionable and empty child closes against the actual Pi and OpenCode close handlers, blocks prompt delivery to prove the successor launches first, verifies single-flight behavior, changes the session lock before close to prove ownership is rechecked, and hangs each successor arm to prove bounded fallback delivery includes the typed restoration failure.
+The same suite covers ordinary same-process session replacement for `/new`, `/resume`, and `/fork`, same-instance shutdown-plus-start, stale prior-generation callbacks, repeated transitions with exactly one live cycle, disappearance of the shutting-down refusal after a valid replacement activates, and terminal quit still refusing late rearm.
+`tests/fm-watch-arm.test.sh` covers durable queue replay, real remote parent-replies ingestion into the authoritative status log, decision-only OPEN DECISIONS recovery, interrupted handling replay, generation-bound acknowledgement, a persistent live successor after recovery, a watcher close inside the handling window that must leave the printed acknowledgement valid, and the self-healing moved-generation acknowledgement that consumes its handled rows and names its remedy.
+`tests/fm-watch-recovery-loop.test.sh` covers the once-per-generation announcement bound with the real Pi extension against a refused handling handshake, and a handling successor that must surface a real crew event instead of going blind.
+`tests/fm-watcher-lock.test.sh` covers verified-successor attach, recovery publication before stale-lock removal, the typed self-eviction failure, bounded and successor-linked lifecycle rows, and a SIGSTOP counterfactual that distinguishes a live PID from a stale beacon before classifying termination.
+`tests/fm-subagent-pretool-check.test.sh` proves Claude retains only the non-status Bash seatbelts.
+`tests/fm-claude-stop-autoarm.test.sh` covers the auto-arm's scope, stale and live session owners, unchanged AFK and need boundaries, single-flight, bounded failure retries, benign live-watcher cycle ends, one-notice failure episodes, and exit-2 translation.
+It also covers generation-claim single-flight, stuck-claim supersession, superseded-owner silence, notice-marker refusal and retry, ownership-atomic episode reset, and the legacy upgrade shim; [`turnend-guard.md`](turnend-guard.md) owns those behavior contracts.
+`FM_CLAUDE_LIVE_E2E=1 tests/fm-claude-stop-autoarm-live-e2e.test.sh` starts with the reproduced stale-lock state, runs session start first, completes two tokenless cycles, and checks the competing-live-owner negative control.
+`tests/fm-turnend-guard.test.sh` covers the cooperative `--claude` guard, including monotonic failed-epoch progression, the integrated bounded fail-open, post-alarm continuation suppression, and positive recovery reset; [`turnend-guard.md`](turnend-guard.md#regression-coverage) lists that suite's full generation and legacy claim coverage.
+
+## Active limits and verification
+
+The goal is continuity without a Pi or OpenCode model-memory re-arm step.
+No zero-latency guarantee is claimed because lock verification, watcher startup, and bounded retry delays remain deliberate safety work.
+OpenCode support targets persistent TUI sessions rather than headless `opencode run`.
+Claude depends on the Stop `asyncRewake` rewake, Cursor depends on its awaited stop-hook park, Grok retains native background-completion notifications, and Codex retains bounded foreground checkpoints.
+
+[`verification/supervision.md`](verification/supervision.md#watcher-continuity) records the current five-harness live evidence, the 2026-07-24 Stop-owned Claude auto-arm results, and exact opt-in commands.

package/assets/reference/docs/wedge-alarm.md

@@ -0,0 +1,39 @@
+# Away-mode injection wedge alarm
+
+The away-mode sub-supervisor (`bin/fm-supervise-daemon.sh`) buffers escalations and injects them into Firstmate's own pane.
+When injection cannot confirm a submit past `FM_MAX_DEFER_SECS`, `inject_wedge_alarm` raises a loud, rate-limited alarm so the stall never stays invisible.
+The active alert is pane-independent because a tmux status-line flash has no cross-backend equivalent and cannot reach an unattended captain reliably.
+The durable marker and tmux flash remain as additional signals.
+
+## Channels
+
+`config/wedge-alarm` is local and gitignored.
+It lists channel directives, one per non-empty, non-comment line, and every listed non-`off` channel fires best-effort.
+`FM_WEDGE_ALARM_CHANNEL` overrides the file with one directive for focused testing.
+
+- `off` disables every active alert while retaining the durable marker and tmux flash.
+- `auto` or `default` resolves to `osascript` on macOS.
+  Other platforms have no built-in OS channel, so configure `command:` when a durable marker alone is insufficient.
+- `osascript` posts a macOS Notification Center banner outside the terminal pane.
+- `herdr` calls `herdr notification show` outside the supervised pane.
+- `command:<cmd>` runs `<cmd>` through `sh -c` with the alarm summary as `$1` and on stdin, allowing delivery to a phone or pager service.
+
+An absent `config/wedge-alarm` behaves as `auto`, which is default-on on macOS.
+This is deliberate because the alarm fires only after a genuine max-defer wedge and is rate-limited to at most once per max-defer window.
+
+Each channel is best-effort.
+A missing binary or non-zero exit logs a warning and continues to the next channel without crashing the daemon loop.
+Every invocation is process-group bounded by `FM_WEDGE_ALARM_TIMEOUT_SECS`, which defaults to 10 seconds, including `command:`, `osascript`, `herdr`, and the test seam.
+On timeout or daemon shutdown, the notifier process group is terminated and the next configured channel may run.
+AppleScript receives the summary as an argv item rather than interpolated source, so summary text cannot alter the script.
+See [`examples/wedge-alarm`](examples/wedge-alarm) for a copyable config.
+
+## Test safety
+
+Every notifier routes through `FM_WEDGE_ALARM_EXEC` in `wedge_alarm_emit`.
+When the daemon is sourced as a library, that seam defaults to `discard`, so a test cannot accidentally post a real notification.
+`tests/wake-helpers.sh` replaces it with a recorder when a suite needs to assert channel selection and summary propagation.
+Production leaves the seam unset and uses the configured real channels.
+
+`tests/fm-daemon.test.sh` covers directive parsing, rate limiting, timeout and process-group cleanup, argv-safe dispatch, channel fallback, and safe `command:` summary delivery.
+[`verification/supervision.md`](verification/supervision.md#wedge-alarm-channels) records the bounded manual macOS and Herdr channel proof.

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

@@ -0,0 +1,114 @@
+# Zellij runtime backend
+
+Zellij is an experimental explicit-only session backend.
+It provides the terminal session while Treehouse continues to provide task worktrees.
+[`configuration.md`](configuration.md#runtime-backend-configbackend--fm_backend) owns shared selection and metadata semantics.
+
+## Setup
+
+Pick Zellij when you already use it as a terminal multiplexer and accept its current focus, liveness, and polling limits.
+
+Prerequisites:
+
+- Zellij 0.44 or newer.
+- `jq` for JSON responses.
+- The universal harness and toolchain requirements in [`configuration.md`](configuration.md#toolchain).
+
+Select it with local `config/backend` containing `zellij`, `FM_BACKEND=zellij` for one launch, or an explicit request to Firstmate.
+It is never auto-detected.
+A spawn stops before creating a session or acquiring a worktree when Zellij or `jq` is missing or Zellij is below 0.44.
+
+Firstmate uses one shared session named `firstmate` by default.
+`FM_ZELLIJ_SESSION` can select another name for isolated verification.
+Attach with:
+
+```sh
+zellij attach <session-name>
+```
+
+Routine supervision does not require attachment.
+Use `bin/fm-peek.sh <id>` and `FM_HOME=<home> bin/fm-send.sh <id> '<text>'` against the metadata-routed endpoint.
+
+Verify setup by spawning a small task and confirming metadata contains `backend=zellij`, `zellij_session=`, `zellij_tab_id=`, and `zellij_pane_id=`.
+
+## Task shape and home isolation
+
+Every task receives one tab in the shared Zellij session.
+The caller-facing label remains `fm-<id>`, while the visible title is home-scoped as `fm-<home-label>-<id>`.
+The home label is `firstmate` or `2ndmate-<id>` plus a short stable hash of the resolved Firstmate root.
+This prevents task-id collisions between a primary, secondmates, and separate Firstmate installations sharing one session.
+
+Zellij does not enforce tab-name uniqueness, so the adapter performs its own duplicate check against the scoped title.
+Create, recover, list, and cleanup paths all use the same scoped title owner in `bin/fm-backend-hometag-lib.sh`.
+Moving a Firstmate installation changes its path hash and leaves old titles unmatched, consistent with worktree paths also becoming stale after a move.
+
+A pre-home-tag task remains reachable through its recorded metadata only when exactly one live tab has the old unscoped title.
+Multiple old tabs with the same title cause a refusal rather than a guess.
+Bulk recovery never adopts unscoped legacy tabs because it has no safe home identity for them.
+
+```text
+backend=zellij
+window=<session>:<pane-id>
+zellij_session=<session>
+zellij_tab_id=<tab-id>
+zellij_pane_id=<pane-id>
+```
+
+Recorded pane ids are numeric and are never trusted alone after a session recreation.
+Metadata-routed operations also verify the owning tab's expected scoped or unambiguous legacy title.
+An explicit raw `session:pane` target remains a pane-existence-only operator escape hatch.
+
+## Current operation and safety
+
+Zellij's CLI action commands return exit 0 even for missing sessions or panes.
+The adapter therefore verifies session, terminal pane, and expected title before an operation and validates JSON or integer response shapes afterward.
+A pane can still disappear between verification and the operation; downstream submit, worktree-discovery, and stale detection report that narrow race rather than treating exit 0 as success.
+
+Every pane operation passes an explicit `--pane-id` because a new session can focus its release-notes plugin pane, whose numeric plugin id is in a separate namespace from terminal pane ids.
+
+`pane_cwd` follows a top-level shell `cd` but not the foreground subshell opened by `treehouse get`.
+Worktree discovery therefore sends begin and end markers around `pwd`, captures the marked block, and joins wrapped path lines.
+This active probe is scoped to spawn-time worktree discovery and is not advertised as a general live-cwd API.
+
+`new-tab` has no no-focus flag and temporarily focuses the created tab in attached clients.
+The adapter records the previously active tab and immediately restores it with `go-to-tab-by-id`.
+There is a narrow visible race between those calls that no current Zellij flag can remove.
+
+An ordinary metadata-routed `fm-send.sh` text steer becomes a durable steering-inbox record, and only its best-effort constant doorbell passes through Zellij's submit machinery.
+On the typed plane, literal send uses bracketed paste followed by a separate explicit Enter.
+Before sending Enter, the adapter proves that the selected composer's normalized content changed by exactly the pasted text; an unreadable composer, a paste that lands elsewhere, or unrelated pane output fails without submitting.
+The adapter supports `Enter`, `Esc`, and the one-argument key expression `Ctrl c` through the shared key vocabulary.
+Zellij exposes no cursor-row or native agent-state signal, but `dump-screen --ansi` (verified at 0.44.0) preserves styling, so the composer is read through the same fleet-wide classifier as tmux and herdr (`bin/fm-composer-lib.sh`), with ghost and placeholder text stripped before the verdict.
+Submit acknowledgement requires a positively classified empty composer.
+The retired content-delta acknowledgement could report a message delivered whenever the pane changed for any reason - a spinner, streaming output, a clock - which could silently close a decision record for a message the crew never received; a pane that merely changed no longer confirms anything.
+A dead pane still fails safe: Zellij's unconditional-exit-0 actions dump nothing, and an empty dump classifies `unknown`, never a confirmation.
+
+Viewport capture has no line-bound option.
+Routine reads use `dump-screen` and larger peeks use `dump-screen --full`, followed by local trimming.
+A short viewport may expose fewer lines than requested.
+
+Closing a pane leaves an empty tab.
+Cleanup resolves and verifies the owning tab, then uses `close-tab-by-id` so both the task pane and tab disappear.
+Real test cleanup uses only an isolated non-`firstmate` session and the guard in `tests/zellij-test-safety.sh`; it never calls all-session deletion commands.
+
+## Active limits
+
+- Zellij is experimental and explicit-only.
+- All homes share one session and tab bar; scoped titles prevent cross-home identity collisions but do not create per-home visual containers.
+- There is no native busy or push-event signal, so supervision uses capture/hash polling for screen changes and each harness adapter's semantic lifecycle for worker state.
+  Grok alone retains its isolated rendered-tail fallback.
+- There is no verified agent-process liveness signal, so a dead Zellij secondmate is reported inconclusive rather than auto-respawned.
+- New-tab focus restoration has a narrow visible race.
+- CLI exit status is not meaningful; a target can still disappear after structural readiness checks.
+- Worktree cwd discovery requires the spawn-time marker probe.
+- An ambiguous unscoped legacy title requires manual cleanup and respawn.
+
+## Regression entry points
+
+```sh
+tests/fm-backend-zellij.test.sh
+tests/fm-backend-zellij-smoke.test.sh
+```
+
+The real smoke test uses a unique session and guarded deletion.
+[`verification/runtime-backends.md`](verification/runtime-backends.md#zellij) records the active CLI matrix and lifecycle evidence.