@zerwiz/ymir 0.1.16 → 0.1.18

package/assets/reference/docs/captain-hold-lifecycle.md

@@ -0,0 +1,96 @@
+# Captain-hold lifecycle mechanism
+
+The normative policy is owned by `.agents/skills/captain-hold-lifecycle/SKILL.md` and is not restated here.
+This document records the deterministic mechanism, structured surfaces, compatibility contract, and privacy-safe regression evidence.
+
+## Mechanism
+
+A decision is not a separate thing in this system: it is an ordinary backlog task held for the captain, and the task id is the identity every surface and channel uses.
+`bin/fm-captain-hold.sh` is the only lifecycle command layered on that primitive.
+The command runs tasks-axi in the active `FM_HOME`, so the existing backlog remains the only durable work database and a secondmate-owned captain call stays in the secondmate home.
+It never reads report bodies, review artifacts, terminal output, or chat.
+
+The `hold` subcommand places an existing task under an active captain hold, or creates the task when nothing exists to hold, then verifies the hold through `tasks-axi hold <id> --reason <reason> --kind captain`.
+Repeats are idempotent, a closed task is refused rather than reopened, and `--until` stores the captain's own deferral date through tasks-axi's date gate.
+
+The `answer` subcommand records the captain's exact words and closes the call in the same act.
+It requires a non-empty captain decision file of at most 8192 bytes, writes a resolution block carrying the decision digest and a `Resolution mode:` at the top of the task body (the previous body is preserved below the block and archived through tasks-axi `--archive-body`), then runs `tasks-axi done` - or `tasks-axi unhold` under `--release`, so a captain-gated work item resumes instead of closing.
+An exact retry is idempotent only when the requested close mode matches the newest record; a drifted answer or mode mismatch is rejected, while a re-held task accepts a new answer as a new record on top.
+On a task closed outside the script, `answer` records the missing block only when the captain-hold annotations tasks-axi preserves through a close prove the captain owned it, and it verifies the task stays closed.
+A hold whose `--until` date has passed keeps those annotations while tasks-axi reports it no longer held, so an expired deferral remains answerable.
+
+The `complete` subcommand unions the reviewed captain-held task ids into `decision_keys=` and appends `decisions_reviewed=1` while originating task metadata is live.
+A post-teardown visual review can complete against the surviving report and durable tasks without recreating volatile task metadata.
+It accepts `--none` as an explicit semantic inventory result, refused while the origin still has a lifecycle-open keyed status decision, and verifies every listed task against tasks-axi before recording completion.
+With a non-empty inventory it appends a `captain-held [key=<key>]: tracked by <inventory>` transfer event for every still-open keyed status decision, which `bin/fm-classify-lib.sh` recognizes as closing the live status copy without claiming that the captain has answered it.
+
+Scout teardown calls the read-only `verify` subcommand after checking for the report and before removing any source state.
+`verify` requires the recorded attestation, requires every recorded inventory entry to still be durable (actively captain-held, or carrying a recorded answer), and fails on any keyed status decision that opened after the last `complete`, which makes re-running `complete` the repair.
+The `--force` path remains the explicit captain-approved discard escape hatch.
+
+## Answer-time closure
+
+"A keyed answer closes its matching captain-held task" is one capability with one owner.
+`answers` is its channel-agnostic entry point: it reads `<task-id>\t<answer>\t<label>[\t<mode>]` lines and closes each named task through the same `answer` path, so every guard applies identically no matter which channel the answer arrived on.
+The optional mode column carries a card-declared close: `done` (default) completes the task and `release` lifts the hold so held work resumes; any other value is skipped.
+A key that names no task, names a task that is not captain-held, or names a task already closed is reported as `skipped:` and feeds nothing; a replay whose answer and requested close mode match the newest record is an idempotent `closed:`, while a mode mismatch is skipped; and the command exits nonzero when any key was skipped.
+`--source` is provenance text recorded in the durable decision, never a behavior switch, and the command carries no per-channel branch.
+
+`bind`, `unbind`, and `binding` record that a captured-answer source feeds this intake, as a private record under `state/decision-bindings/`; an unbound source feeds nothing, so the path is opt-in per source, and `bind` deliberately does not require the source to exist yet.
+
+Two channels feed that one intake today, and both are ordinary callers rather than special cases.
+`bin/fm-send.sh --resolve-key` is the chat channel: its status-log close is unchanged for a key the status log still owns, and a key the status log no longer owns is resolved to a still-open captain-held task - the key as a task id, then the legacy derived identity - and fed as one keyed line.
+`bin/fm-procevent.sh` is the captured-result channel: after capture, a bound built-in source has its result passed to `bin/fm-procevent-<adapter>.sh answers <result-file>` and whatever that prints is piped into the intake, so any built-in adapter with an `answers` command works and the runner names no adapter, parses no result, and carries no decision rule.
+Trusted external process-event adapters intentionally expose no answer operation and cannot feed this authority-bearing intake; [`extension-bindings.md`](extension-bindings.md#trust-boundary) owns that boundary.
+`bin/fm-procevent-lavish.sh answers` is one such adapter command; it reads only rows tagged `choice`, relays a card's declared close mode, and can never let freeform captain prose forge a task id or a mode.
+
+## Structured read surfaces
+
+`bin/fm-fleet-snapshot.sh` parses canonical tasks-axi `(hold: ...)`, `(hold-kind: ...)`, and `(hold-until: ...)` metadata alongside existing backlog fields.
+It resolves every repeated `blocked-by:` edge against structured Done records, keeps missing blockers unresolved, and classifies a captain hold as `captain_actionable` - waiting on the captain now - only when it is queued, unblocked, and due, whatever kind its row carries.
+It also emits a presentation-only `deferred_marker` when a hold's reason or body carries an explicit SUPERSEDED / NOT REQUIRED / DEFERRED marker.
+Its secondmate-home summary classifies an actionable captain hold as `captain_decision` and preserves blocked or deferred captain holds as queued work in the owning home.
+
+`bin/fm-bearings-snapshot.sh` projects actionable captain holds into `decisions_open` and leaves blocked captain holds in ordinary queued gates.
+A date-deferred captain hold renders as a gate with its `until <date>:` reason; a prose-deferred one leaves the default views with an `omitted[]` disclosure, revealed by `--all-decisions` / `--all-queued`.
+Recently Landed excludes a record that closed while still held for the captain (surviving `hold-kind: captain` on a Done row), so answered questions do not masquerade as shipped work; a work item released before completion keeps no hold annotations and lands normally.
+The projection remains read-only and does not inspect historical prose beyond the canonical snapshot's marker.
+
+## Record divergence
+
+A captain call can have two records, and closing one does not close the other.
+A `resolved [key=...]` line closes the status-log fold; the structured captain-held task closes only through `answer`.
+Until this guard existed, closing on the status side alone left no trace of the disagreement: the fold went quiet, the durable record kept saying the captain owed an answer, and nothing warned.
+
+`bin/fm-captain-hold.sh diverged` is the read-only report of that state, and `bin/fm-wake-drain.sh` prints it as a bounded `RECORD DIVERGENCE` section beside OPEN DECISIONS on every drain.
+It flags exactly one condition: a task still open and still carrying the captain-hold annotations, whose key was closed on the status side by the resolve verb, resolved through the collapsed identity (the key is the task id) or the legacy derived one.
+It closes nothing, ever - a captain call closed wrongly leaves review entirely, so both reconciliation directions stay human-owned and the printed hint names both.
+
+Three states are deliberately not divergence.
+A `captain-held [key=...]` close is the verified transfer `complete` writes, so the structured row staying open behind it is correct; `bin/fm-classify-lib.sh`'s `status_key_closing_verb` is what keeps the two closing verbs distinguishable.
+A still-open keyed status decision belongs to the OPEN DECISIONS fold.
+And the absence of a routed work item is legitimate rather than incomplete - when the decision is the deliverable there is nothing to route - so routed work is no part of the test.
+
+Cost stays flat: one `tasks-axi list`, one key scan per status log, and the precise per-key fold only for a key that already names a still-open task.
+The comparison is refused unless the status directory is the active home's own, since tasks-axi reads that home's backlog and a mismatch would report one home's logs against another's tasks.
+If tasks-axi is unavailable or its listing cannot be parsed, the guard cannot read the structured record and prints nothing.
+
+## Compatibility with pre-collapse installs
+
+Older installs created derived `<origin>-decision-<key>` identities through the retired `bin/fm-decision-hold.sh`.
+Those rows are already plain task ids, so they render, answer, verify, and close through the collapsed surfaces with no data migration.
+Three legacy inputs are resolved in place: a `decision_keys=` metadata entry that names no task resolves through `<origin>-decision-<entry>`; a channel key that names no task resolves the same way when the source's binding carries a concrete legacy origin; and resolution records written by the old script are recognized wherever a record is read.
+The shim recognizes an exact replay of a pre-collapse routed resolution by its historical answer digest and routed ids, then finishes any still-recorded dependency-edge cleanup without rewriting the old decision text.
+`bin/fm-decision-hold.sh` itself remains for one release as a thin command-mapping shim over `bin/fm-captain-hold.sh`, so in-flight work briefed before the collapse keeps working; its header owns the exact mapping.
+
+## Verification record
+
+Verification date: 2026-08-21.
+
+The focused end-to-end regression suite is `tests/fm-captain-hold-lifecycle.test.sh`, using only synthetic `sample` identities and decision text.
+It proves: the reconstructed silent-divergence case is signalled - a status resolution over a still-open captain-held task reaches both `diverged` and the drain's `RECORD DIVERGENCE` section, under the collapsed and the legacy identity alike, while the backlog task, its hold, and the status log all survive the report unchanged and the printed hint names both reconciliation directions; the false-signal boundary holds - a captain call with no routed work item, a verified `captain-held` transfer, a still-open status decision, an already answered call, and an ordinary task whose keyed question was answered all stay silent; a report-only unresolved captain call refuses `--none` completion before teardown can erase the source; non-forced scout teardown always requires the durable inventory verification; the recorded-answer guard (a bare `tasks-axi done` close fails `verify` until `answer` records the captain's word, and an ordinary finished task cannot be dressed up as an answered call); answer-time closure through a bound channel with task-id keys, including the `release` close mode, mode-matched replay idempotence, and the refusal of drifted, mode-mismatched, absent, unheld, and already-closed keys; the chat channel reaching the same intake; deferral through `--until` leaving `captain_actionable` false until due; and every legacy path (composed identities through the shim, pre-collapse `decision_keys=` metadata, routed-resolution replay, and a concrete-origin binding).
+
+`tests/fm-classify-decision-key.test.sh` pins `status_key_closing_verb` itself: it separates a resolution from the durable-transfer close and from a still-open key, reports the last real transition across re-openings and both key positions, and treats a prose mention as no transition.
+
+Projection regressions live in `tests/fm-fleet-snapshot-view.test.sh` (hold-until parsing, the due gate, kind-independent captain actionability, deferred_marker, title stripping) and `tests/fm-bearings-snapshot.test.sh` (Captain's Call membership, the dated-gate rendering, prose-deferral suppression with disclosure, and the landed exclusion by surviving captain-hold annotations).
+The exact commands and their summarized outputs are recorded in the shipping PR's evidence; run the four suites above plus `tests/fm-send-resolve-key.test.sh`, `tests/fm-bearings-board.test.sh`, and `bin/fm-lint.sh` to refresh this record.

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

@@ -0,0 +1,165 @@
+# cd-guard PreToolUse seatbelt
+
+This document is the authoritative human-readable contract for the cd-guard PreToolUse seatbelt.
+`bin/fm-cd-command-policy.mjs` is the single decision owner.
+`bin/fm-cd-pretool-check.sh` is the stable harness transport, primary-checkout scope, and output renderer.
+The tracked harness adapters forward command text without classifying it.
+
+It is the third member of a family of primary-session guards that share the same cross-harness hook machinery:
+the watcher-arm PreToolUse seatbelt (`bin/fm-arm-pretool-check.sh`, `docs/arm-pretool-check.md`) and the turn-end supervision guard (`bin/fm-turnend-guard.sh`, `docs/turnend-guard.md`).
+
+## Purpose and boundary
+
+The primary firstmate shell persists its working directory across tool calls.
+A stray persistent top-level `cd projects/<clone>` therefore silently relocates the shell, so the next firstmate-owned command - a backlog write, an `fm-*` lifecycle call, `tasks-axi` - runs inside a project clone instead of the home.
+That has actually happened: a persistent top-level `cd` caused a firstmate-owned backlog write to execute inside a project clone rather than the home.
+The seatbelt denies exactly that command shape - a cwd change that persists to the primary shell - before it runs.
+
+This guard is not a general sandbox.
+It classifies shell command positions only; it never evaluates, expands, sources, or runs any byte of the submitted command.
+Its threat model is agent mistakes, the same as the watcher-arm seatbelt: an accidental bare `cd projects/foo`, not a deliberately obfuscated bypass.
+
+## Scope: plain firstmate checkouts only
+
+The guard fires only in a plain firstmate checkout where git-dir equals git-common-dir.
+It is a silent no-op (exit 0, no output) everywhere else, so it never interferes with a crewmate or scout that legitimately works inside its own project or firstmate task worktree.
+
+`bin/fm-cd-pretool-check.sh` owns its checkout detection; the turn-end guard's marker-aware scope is a separate contract (`docs/turnend-guard.md`).
+A plain, non-worktree checkout has `git rev-parse --git-dir` equal to `git rev-parse --git-common-dir`.
+A crewmate or scout task worktree - the shape `bin/fm-spawn.sh` always hands out - is a linked git worktree where the two differ, so the guard is inert there.
+The checkout must also carry `AGENTS.md` and `bin/`, and any failure to confirm the primary is treated as inert, never as a block.
+
+The cd-guard does not inspect `.fm-secondmate-home`.
+It therefore applies in a git-cloned secondmate home where git-dir equals git-common-dir, but remains inert in a treehouse-leased secondmate home that is itself a linked worktree.
+Secondmate child crew and scout worktrees are likewise inert under the linked-worktree test.
+
+## Block vs allow
+
+The discriminator is persistence to the parent shell's cwd, not the mere presence of the token `cd`.
+
+The guard **blocks** a `cd`, `pushd`, or `popd` builtin that runs in an executed top-level position in the parent shell, because such a command persistently changes the primary shell's own working directory.
+This covers a bare `cd projects/foo`, `cd ..`, `cd`, `cd -`, an absolute `cd /some/path` (still a persistent relocation of the parent shell), `pushd <dir>`, `popd`, a leading-assignment form such as `X=1 cd foo`, quoted or escaped command-word fragments that cook to a bare builtin, and any list form where the builtin runs in the parent shell (`cd x && cmd`, `cmd; cd x`, `cmd || cd x`, `command cd x`, `command -p cd x`, `command -- cd x`, `builtin cd x`, `command builtin cd x`, `cd x >/dev/null`, and newline-separated lists).
+
+The guard **allows** everything else, including these safe scoped forms that must never be blocked:
+
+- A command that reaches a target without changing the shell's own cwd: `git -C <dir> ...`, `make -C <dir> ...`, or an absolute path on the command itself.
+- A directory change that does not persist to the parent shell: a subshell `(cd x && ...)`, a `bash -c 'cd ...'` / `sh -c` / `zsh -c` payload, an `env -C <dir> ...`, a `find ... -execdir` runner, a pipeline stage (`cd x | cmd`), or a backgrounded `cd x &`.
+- A `cd` behind a forking or exec'ing wrapper (`env`, `sudo`, `nohup`, `timeout`, `gtimeout`, `exec`), which runs in a child and never persists (and generally just fails, since `cd` is a builtin with no external program).
+- A path-qualified external command named `cd`, `command`, or `builtin`, such as `./cd`, `/usr/bin/cd`, `./command`, `/usr/bin/command`, or `./builtin`, because it runs as a child process and cannot change the parent shell's cwd.
+- A `command` query such as `command -v cd`, `command -V cd`, or a clustered form such as `command -pv cd`, because it reports command resolution without executing the named builtin.
+- The token `cd` appearing as data: quoted text (`echo "cd projects/foo"`), a comment, a substring of another word (`cdk`, `abcd`, `record`), a `printf` payload, or any later argument word.
+
+An absolute-path `cd` is blocked on purpose: the ALLOW carve-out for absolute paths is for commands that address a target by absolute path, not for `cd`, which relocates the shell itself regardless of whether its argument is relative or absolute.
+Blocking a top-level `cd` is safe in the strong sense: the guard's steady state is "always at the home", so a return-to-home `cd` is redundant rather than necessary, and the block never causes a wrong-directory write.
+
+### Accepted non-goals
+
+Consistent with the agent-mistake threat model, the guard deliberately does not chase every obfuscated bypass:
+
+- A `cd` reconstructed by a command substitution (`$(echo c)d x`) or hidden inside a brace group (`{ cd x; }`) is not blocked. Brace-group recursion is avoided because this classifier cannot reliably tell a brace group `{ cd; }` from brace expansion `{cd,foo}`, and a false block there is worse than the missed exotic bypass.
+- Malformed or untokenizable syntax fails open (allow). Unlike the watcher-arm seatbelt, which fails closed on unclassifiable protected commands, the cd-guard prioritizes zero false blocks over catching a malformed bypass, because a blocked backlog write is a correctness hazard while a missed exotic `cd` is only the pre-existing status quo.
+
+If a genuinely ambiguous command shape is found that risks a false block, the guard is not extended by guesswork; the ambiguity is escalated and the guard stays precise rather than over-eager.
+
+## Stable reason code
+
+Every deny carries one stable code in square brackets before its prose reason.
+
+| Code | Meaning |
+| --- | --- |
+| `persistent-cd` | A top-level `cd`/`pushd`/`popd` would persistently change the primary shell's own working directory. |
+
+The reason directs the caller to reach the target without moving the shell by using `git -C <dir>`, placing an absolute path on the intended command itself, or scoping the `cd` to a subshell.
+It does not permit `cd /home/project`, because an absolute-path `cd` remains a persistent directory change and is denied.
+
+## Transport and fail-open behavior
+
+`bin/fm-cd-pretool-check.sh` supports every harness-engine entry shape used by the tracked adapters, with pi-signed sharing Pi's shape:
+
+- Claude sends stdin JSON at `.tool_input.command` and adds `--claude` to preserve Claude's stderr-only deny requirement.
+- Codex sends stdin JSON at `.tool_input.command` without `--claude`.
+- Grok sends stdin JSON at `.toolInput.command`.
+- OpenCode sends the exact command string through `--command <exact string>`.
+- Pi and pi-signed send the exact command string through `--command <exact string>`.
+- Cursor sends stdin JSON at `.tool_input.command` and adds `--cursor`, which renders the deny as Cursor's own returned decision object.
+
+Processing order is cheapest-first: a strict-superset prefilter, then the primary-checkout scope, then the Node policy owner.
+The prefilter removes ordinary single quotes, double quotes, backslashes, carriage returns, and newlines before fast-allowing any command that carries no `cd`, `pushd`, or `popd` substring and no quoting-decoder marker (`$'` ANSI-C or `$"` locale), so quoted or escaped command-word fragments delegate to the policy while most commands never pay for the git scoping calls or the Node process.
+The quoting-decoder marker set is coupled to the classifier's decoder set in `bin/fm-arm-command-policy.mjs`: adding any new quote or expansion form the classifier decodes requires extending the prefilter marker set in the same change, or it stops being a strict superset.
+
+Empty stdin, unparseable JSON, missing `jq` on the stdin path, missing Node, a missing policy owner, or an invalid policy response all fail open with exit 0 and no output.
+A broken hook must never deny every shell tool call.
+
+## Output contract
+
+Identical in shape to `docs/arm-pretool-check.md`:
+
+- Allow (and inert-outside-primary) returns exit 0 with both streams empty.
+- Deny returns exit 2 and writes `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny"},"systemMessage":"[persistent-cd] reason"}` to stderr.
+- Default deny mode also writes `{"decision":"deny","reason":"[persistent-cd] reason"}` to stdout for Grok.
+- `--claude` suppresses stdout completely because Claude ignores a PreToolUse deny when stdout is nonempty.
+- Codex blocks on exit 2 and displays stderr.
+- OpenCode throws only when the checker exits 2.
+- Pi and pi-signed return `{block: true}` only when the checker exits 2.
+
+## Shared classifier ownership
+
+`bin/fm-cd-command-policy.mjs` imports the shell tokenizer and command-position analysis (`Lexer`, `splitProgram`, `commandPosition`) from `bin/fm-arm-command-policy.mjs`, the sole owner of firstmate's shell classification.
+`basename` remains a private helper of the shared arm classifier because the cd policy identifies shell builtins by exact cooked-word identity.
+The cd-guard never duplicates shell lexing; it adds only the cd-specific decision on top of that shared classifier.
+`bin/fm-arm-command-policy.mjs` runs its own CLI entry point only when invoked directly, never on import, so the two policies stay independent CLIs over one parser.
+
+## Harness wiring
+
+| Harness | Entry | Adapter behavior on checker exit 2 |
+| --- | --- | --- |
+| Claude | `.claude/settings.json` PreToolUse Bash hook forwarding stdin with `--claude` | Blocks the tool call; stderr deny object, stdout empty. |
+| Codex | `.codex/hooks.json` PreToolUse hook that anchors from `pwd -P`, verifies the hook-loaded firstmate root, and forwards the payload | Blocks on exit 2 and displays stderr. |
+| Grok | `.grok/hooks/fm-primary-cd-check.json` PreToolUse hook anchored on `${GROK_WORKSPACE_ROOT:-}` | Consumes the stdout `decision=deny` object. |
+| OpenCode | `.opencode/plugins/fm-primary-cd-check.js` `tool.execute.before` | Throws, which surfaces as the failed tool result. |
+| Pi | `.pi/extensions/fm-primary-turnend-guard.ts` `tool_call` handler | Returns `{block: true}`; piggybacks on the already-loaded primary extension so no extra `-e` flag is needed. |
+| Cursor | `.cursor/hooks.json` `preToolUse` hook matching `tool_name` `Shell`, forwarding stdin with `--cursor` | Prints Cursor's own `{"permission":"deny","user_message":...}` object on stdout and exits 0, because Cursor reads the returned object rather than the exit status. Without `--cursor` the Cursor-delivered payload is the Claude-settings duplicate Cursor also loads, and allows; `docs/arm-pretool-check.md` owns that shared predicate. |
+
+Each harness runs the cd-guard alongside the watcher-arm seatbelt; the two are independent checks, and either deny blocks the command.
+Every shell variable reference in the Grok hook command carries an inline default (`${GROK_WORKSPACE_ROOT:-}`) because Grok expands the raw hook command before `bash -lc` runs it, the same requirement documented in `docs/arm-pretool-check.md`.
+
+## Automated validation
+
+`tests/fm-cd-pretool-check.test.sh` owns the acceptance matrix.
+Every block and allow case runs through Codex-shaped stdin, Claude-shaped stdin, Grok-shaped stdin, OpenCode-shaped CLI, and Pi-shaped CLI entry forms.
+The suite also proves the end-to-end cwd-leak regression (a firstmate-owned backlog write leaking into a project clone, then denied at the exact command), the checkout scoping (fires in a git-cloned secondmate fixture, inert in a crewmate/scout linked worktree, inert outside a firstmate checkout, inert outside a git repo), the fail-open transport behavior, the prefilter fast path, the policy CLI output contract, and the per-harness wiring.
+
+Run:
+
+```sh
+bash -n bin/fm-cd-pretool-check.sh
+shellcheck bin/fm-cd-pretool-check.sh tests/fm-cd-pretool-check.test.sh
+node --check bin/fm-cd-command-policy.mjs
+node --check bin/fm-arm-command-policy.mjs
+tests/fm-cd-pretool-check.test.sh
+tests/fm-arm-pretool-check.test.sh
+```
+
+## Live validation record, 2026-07-11
+
+Each harness ran against a scratch primary-shaped firstmate checkout: a plain git repo with `AGENTS.md`, `bin/` holding the real `fm-cd-pretool-check.sh`, `fm-cd-command-policy.mjs`, and `fm-arm-command-policy.mjs` plus a no-op dummy `fm-arm-pretool-check.sh`, a `projects/foo/` stand-in clone, and the tracked harness hook config.
+No live watcher, fleet state, or the captain's real primary checkout was involved.
+Each harness was told to run, as separate tool calls, a top-level `cd projects/foo && touch <abs>/BLOCKED` (must be denied) and a subshell `(cd projects/foo && touch <abs>/ALLOWED)` (must run), with the sentinel files as the observable.
+
+Harness versions and outcomes:
+
+- **Claude Code 2.1.207** - blocked. Claude reported the top-level command "denied by the `PreToolUse` hook (`fm-cd-pretool-check.sh`)", the `BLOCKED` sentinel was absent, and the subshell form was permitted to run. A prior control `touch` proved the harness executed commands.
+- **codex-cli 0.144.0** - blocked. Codex logged `error=Command blocked by PreToolUse hook: {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny"},"systemMessage":"[persistent-cd] a persistent top-level directory change ..."}`, the `BLOCKED` sentinel was absent, and the subshell `ALLOWED` sentinel was created. Both the arm and cd PreToolUse hooks ran per command (two `hook: PreToolUse Completed` lines), confirming Codex re-feeds the payload to each hook in the array.
+- **OpenCode 1.17.18** - blocked. `opencode run` printed `✗ cd projects/foo && touch ... failed` with `Error: {"hookSpecificOutput":...,"permissionDecision":"deny"},"systemMessage":"[persistent-cd] ..."}`, the `BLOCKED` sentinel was absent, and the subshell `ALLOWED` sentinel was created.
+- **Pi 0.80.6** - blocked. The `BLOCKED` sentinel was absent while the subshell `ALLOWED` sentinel was created; that differential (top-level denied, subshell run, in the same session) can only come from the guard.
+- **grok 0.2.93** - inconclusive live run: the Grok Build API returned `402 Payment Required: Grok Build usage balance exhausted`, so the model never issued the probe commands. The grok cd hook (`.grok/hooks/fm-primary-cd-check.json`) is structurally identical to the arm-seatbelt grok hook already live-validated on 2026-07-09 (`docs/arm-pretool-check.md`) - same `${GROK_WORKSPACE_ROOT:-}` anchoring and same PreToolUse deny consumption - and the grok-shaped stdin path (`.toolInput.command` in, `{"decision":"deny"}` out) is covered by `tests/fm-cd-pretool-check.test.sh`. Re-run once the Grok balance is restored to close the live gap.
+
+The launch commands mirrored `docs/arm-pretool-check.md`'s validation:
+
+```sh
+claude -p "$PROMPT" --dangerously-skip-permissions --output-format text
+codex exec --dangerously-bypass-hook-trust --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check "$PROMPT"
+OPENCODE_CONFIG_CONTENT='{"permission":{"*":"allow"}}' opencode run --print-logs --log-level INFO "$PROMPT"
+pi -p -e .pi/extensions/fm-primary-turnend-guard.ts --no-context-files --no-session "$PROMPT"
+grok --trust -p "$PROMPT" --permission-mode bypassPermissions --output-format plain
+```

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

@@ -0,0 +1,133 @@
+# cmux runtime backend
+
+cmux is an experimental macOS GUI terminal backend.
+It provides task workspaces and surfaces while Treehouse continues to provide git worktrees.
+[`configuration.md`](configuration.md#runtime-backend-configbackend--fm_backend) owns shared selection and metadata semantics.
+
+## Setup
+
+Pick cmux when you already use the app as your terminal and want task workspaces in its sidebar.
+cmux is macOS-only, GUI-first, and unsuitable for a headless or SSH-only Firstmate session.
+
+Prerequisites:
+
+- cmux 0.64 or newer, installed from [cmux.com](https://cmux.com) or with `brew install --cask cmux`.
+- `jq` for JSON responses.
+- The universal harness and toolchain requirements in [`configuration.md`](configuration.md#toolchain).
+
+The CLI is not always installed on `PATH` with the app.
+The adapter prefers `command -v cmux` and otherwise uses `/Applications/cmux.app/Contents/Resources/bin/cmux`.
+
+### Required socket access
+
+cmux defaults to a control mode that rejects external shells, while Firstmate always controls it from an external process.
+Open Settings > Automation and choose a viable Socket Control Mode before the first cmux-backed spawn.
+
+| Setting | Value | Firstmate support | Security boundary |
+| --- | --- | --- | --- |
+| Off | `off` | No | The socket listener is disabled. |
+| cmux processes only | `cmuxOnly` | No | Only descendants of the cmux app can connect. |
+| Automation mode | `automation` | Yes, recommended | The owner-only 0600 socket admits processes of the current macOS user. |
+| Password mode | `password` | Yes | The 0600 socket also requires an auth handshake. |
+| Full open access | `allowAll` | Yes, not recommended | The 0666 socket admits every local user without authentication. |
+
+Automation mode is the recommended same-user boundary.
+`allowAll` can execute commands through a world-writable control socket and should be selected only as an explicit security tradeoff.
+
+For Password mode, store the password as the first line of local gitignored `config/cmux-socket-password` or provide `CMUX_SOCKET_PASSWORD` in Firstmate's environment.
+The adapter reads the file fresh from the effective config directory and does not overwrite an ambient password when the file is absent.
+Configure the mode and password through the cmux UI rather than editing `cmux.json`; the app does not retain a hand-added password key, and socket-based reload cannot fix a socket that is rejecting the caller.
+
+Select cmux with local `config/backend` containing `cmux`, `FM_BACKEND=cmux` for one launch, or an explicit request to Firstmate.
+It can also be runtime auto-detected when Firstmate itself runs inside cmux.
+A spawn stops with an actionable setup message when the app, minimum version, `jq`, socket access, or password is unavailable.
+The adapter may launch the app with `open -a cmux` only when the socket is down; it does not relaunch the app for access-denied or authentication errors.
+
+Routine supervision uses `bin/fm-peek.sh <id>` and `FM_HOME=<home> bin/fm-send.sh <id> '<text>'` without bringing the cmux window forward.
+Task workspace and surface creation use `focus=false`.
+
+Verify setup by spawning a small task and confirming metadata contains `backend=cmux`, `cmux_workspace_id=`, and `cmux_surface_id=`.
+
+## Runtime detection
+
+`CMUX_WORKSPACE_ID` is the primary cmux runtime marker.
+`CMUX_SOCKET_PATH` is not sufficient because operators may set it outside cmux.
+Detection checks tmux first, then Herdr, then cmux, so a multiplexer nested inside cmux remains the active backend.
+
+cmux's bundled Claude wrapper can remove every `CMUX_*` variable when its internal socket probe fails, including in Password mode.
+On macOS only, detection therefore falls back first to `__CFBundleIdentifier=com.cmuxterm.app`, then to process ancestry reaching the running cmux app.
+Those fallbacks are consulted only when neither tmux nor Herdr already won.
+An environment-scrubbed or launchd-reparented process with no reliable marker is not auto-detected.
+
+Auto-detection selects only the backend.
+It never changes socket access or grants credentials.
+The spawn refusal explains how to finish cmux setup or opt back into tmux.
+
+## Task shape and metadata
+
+Each task owns one cmux workspace with one surface.
+The caller-facing label remains `fm-<id>`, while the visible workspace title is `fm-<home-label>-<id>`.
+The home label is `firstmate` or `2ndmate-<id>` plus a stable short hash of the resolved Firstmate root.
+cmux does not enforce title uniqueness, so create, recovery, list, and cleanup paths all validate this scoped title.
+Relocating the Firstmate installation changes the hash and leaves old titles unmatched, consistent with recorded worktree paths also becoming stale.
+
+```text
+backend=cmux
+window=<workspace-uuid>:<surface-uuid>
+cmux_workspace_id=<workspace-uuid>
+cmux_surface_id=<surface-uuid>
+```
+
+The UUID pair is the active endpoint authority within one app run.
+Workspace UUIDs are not stable across an app relaunch, so recovery searches by the scoped title and then resolves the current surface id.
+
+## Current operation and safety
+
+A genuinely fresh surface returns an internal error from `read-screen` until something has been written.
+Target readiness therefore uses the structural `list-panes` response instead of a content read.
+Capture remains bounded and locally trimmed after `read-screen` becomes available.
+
+`current_directory` follows a top-level shell `cd` but not the foreground subshell opened by `treehouse get`.
+Spawn-time worktree discovery sends begin and end markers around `pwd`, captures the marked block, and joins wrapped path lines.
+
+An ordinary metadata-routed `fm-send.sh` text steer becomes a durable steering-inbox record, and only its best-effort constant doorbell passes through cmux's submit machinery.
+On the typed plane, literal send and Enter are separate calls.
+Enter, Escape, and Ctrl-C are supported.
+The composer verifier is a thin adapter: it captures a bounded plain-text tail and hands it with cmux's capability facts to the fleet-wide classifier in `bin/fm-composer-lib.sh`, which owns every shape, including Claude's borderless `❯` row with its U+00A0 separator.
+`read-screen` is plain text with no cursor primitive, so the shared classifier degrades a glyph row carrying trailing text to `unknown` rather than misreading a harness's own idle suggestion as unsent input.
+An unstructured bare prompt is `unknown`, and a slash-popup placeholder remains `pending`, so only Enter is retried and text is never retyped.
+cmux exposes no native generic agent busy 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.
+
+A task workspace's last surface cannot be closed directly.
+Cleanup owns the whole workspace and uses `close-workspace`.
+cmux also refuses to remove the only workspace in a macOS window while returning a misleading success response.
+When the task is last in its window, Firstmate creates one unfocused unnamed sibling workspace in that same window, closes the task workspace, and leaves the window with cmux's fresh default workspace.
+The sibling never carries an `fm-` title and is ignored by recovery.
+
+The exact window membership is re-read before this operation.
+A selected workspace that is not last closes normally; selection itself is not the trigger.
+Firstmate does not attempt to close the macOS window because cmux's socket cannot close a window holding a live terminal.
+
+Real tests share the captain's running app rather than creating an isolated cmux session.
+`tests/cmux-test-safety.sh` permits cleanup only for an exact currently listed `fm-test-` workspace and never enumerates and closes unrelated workspaces or relaunches the app.
+
+## Active limits
+
+- cmux is experimental, macOS-only, GUI-first, and requires the app running.
+- Socket access requires a one-time manual Settings change.
+- Secondmate spawns are unsupported until a per-home lifecycle design is verified.
+- There is no native busy or push-event signal.
+- A target can disappear after structural readiness and before the operation.
+- The only-workspace cleanup path leaves a fresh default workspace and cannot close the window.
+- Label lookup and recovery are currently scoped to the current cmux window, so a task moved to a non-current window is a known recovery blind spot.
+- Workspace ids do not survive app relaunch and are never recovery authority.
+
+## Regression entry points
+
+```sh
+tests/fm-backend-cmux.test.sh
+tests/fm-backend-cmux-smoke.test.sh
+```
+
+[`verification/runtime-backends.md`](verification/runtime-backends.md#cmux) records the active source and live evidence, including socket modes and last-in-window cleanup.

package/assets/reference/docs/codex-app-backend.md

@@ -0,0 +1,57 @@
+# Codex App backend boundary
+
+Codex App is not a selectable Firstmate runtime backend.
+Codex Desktop host tools can create and supervise visible threads and those threads can write Firstmate status files when given an authorized path, but Firstmate has no supported shell-callable bridge to those host tools.
+A manual thread ledger is not a backend.
+
+## Acceptance contract
+
+A future Codex App backend must satisfy the same lifecycle contract as terminal-backed adapters:
+
+1. Create a task endpoint and return a durable thread id.
+2. Send the initial instructions and later operator messages to that endpoint.
+3. Read enough live state or bounded transcript to supervise the task.
+4. Archive, kill, or otherwise stop the exact endpoint.
+5. Let the thread append Firstmate's normal lifecycle lines to `state/<id>.status`.
+
+The status return channel is mandatory.
+A visible thread that cannot report into Firstmate's normal lifecycle is not a complete backend.
+
+## Current blocker
+
+Firstmate backend scripts are shell entry points and can call tmux, Herdr, Zellij, Orca, and cmux directly.
+Codex Desktop host tools are available to a Desktop conversation, not to arbitrary Firstmate subprocesses.
+The missing component is a Codex Desktop-supported shell-callable transport, not another local ledger.
+
+`codex app-server --stdio` exposes useful JSON-RPC pieces such as thread start, turn start, thread read, and thread archive.
+A one-process probe could create and archive a thread record, but no supported bridge was found that lets Firstmate create, continue, read, and archive the same visible Desktop-owned endpoint over its full lifetime.
+A raw Desktop control-socket proxy is not a supported transport.
+These partial pieces do not authorize adding `codex-app` to the known or spawn-capable backend registries.
+
+## Required bridge
+
+Implementation can begin after Codex Desktop exposes one supported interface:
+
+- a CLI wrapper for create, send, read, and archive host-tool operations;
+- a documented JSON-RPC or MCP transport with stable framing; or
+- a maintained helper that speaks the supported transport and returns plain JSON to a shell adapter.
+
+The bridge must provide these semantics:
+
+```text
+create: task id, worktree request, initial instructions -> thread id, cwd, state
+send: thread id, text -> accepted or rejected
+read: thread id, bounded cursor -> transcript and live state
+archive: thread id -> archived or stopped
+return: thread appends state/<id>.status lifecycle lines
+```
+
+Once available, Firstmate should add a real `bin/backends/codex-app.sh`, persist `backend=codex-app` and `codex_app_thread_id=`, and route spawn, send, peek, watch, and cleanup through the shared dispatcher.
+
+## Rollout
+
+Ship and scout tasks come first.
+Secondmate support remains out of scope until create, send, read, status return, and archive are proven through the normal backend dispatcher.
+Until then, Codex App remains a blocked backend boundary with a verified host-tool capability record, not a selectable backend.
+
+[`verification/runtime-backends.md`](verification/runtime-backends.md#codex-app-host-tools) owns the active Desktop host-tool smoke without exposing task-specific thread ids or local paths.