@zerwiz/ymir 0.1.16 → 0.1.18

package/assets/reference/skills/bootstrap-diagnostics/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: bootstrap-diagnostics
+description: >-
+  Agent-only handling playbook for session-start bootstrap diagnostics.
+  Use whenever the session-start digest's bootstrap or network-checks section prints an actionable diagnostic line - MISSING, MISSING_MANUAL, BACKEND_INVALID, NEEDS_GH_AUTH, TANGLE, STARTUP_MEMORY_BUDGET, CREW_DISPATCH invalid, FLEET_SYNC, NETWORK_CHECKS, HOME_SUMMARY, BACKLOG_RECONCILE, SECONDMATE_SYNC, SECONDMATE_LIVENESS, SECONDMATE_HANDOFF, NUDGE_SECONDMATES, or FMX - or reports that an interrupted backlog cleanup may have left an endpoint or local copy, or when a standalone bin/fm-bootstrap.sh or bin/fm-startup-network.sh run prints one of those lines.
+  A silent bootstrap section, or any other BOOTSTRAP_INFO fact, means no skill load.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# bootstrap-diagnostics
+
+Handle each printed line as below, before dispatching work that depends on it.
+The line formats themselves are owned by `bin/fm-bootstrap.sh`'s header; this playbook owns the response to actionable lines.
+The inline rules in `AGENTS.md` section 3 still bind: detect, then consent, then install - never install anything the captain has not approved in this session - and no work is dispatched until the tools it needs are present and GitHub auth is good.
+When any diagnostic needs captain attention, report the plain consequence and requested action using `AGENTS.md` section 9's captain-facing translation contract; do not name the diagnostic label unless the captain needs to paste it into a command or issue.
+
+- `MISSING: <tool> (install: <command>)` - list the missing tools to the captain with a one-line purpose each plus the printed install commands, wait for consent (one approval may cover the list), then run `bin/fm-bootstrap.sh install <approved tools...>`.
+  For `treehouse`, this also covers an installed version whose `treehouse get` lacks `--lease`; treat it as an upgrade request.
+  For `no-mistakes`, this also covers an installed version older than 1.46.0, because this repo's PR gate requires structured pipeline attestation that older builds do not write.
+  For any axi-family tool - `gh-axi`, `lavish-axi`, `tasks-axi`, `quota-axi` - an installed version below its floor is a plain upgrade request; [`bin/fm-bootstrap.sh`](../../../bin/fm-bootstrap.sh) owns the floor policy, and never argue the floor down to whatever the home happens to have installed.
+  For `tasks-axi`, this additionally covers an installed build that fails the separate feature probe (`bin/fm-tasks-axi-lib.sh` owns the definition); `config/backlog-backend=manual` only suppresses the verbose `BOOTSTRAP_INFO: tasks-axi available` fact, not this missing-tool report.
+  For `quota-axi`, bootstrap requires it because firstmate reads its current output directly before resolving every crew-dispatch profile array; without it, report the missing requirement and do not choose around an unexamined candidate.
+- `MISSING_MANUAL: <tool> (instructions: <url>)` - tell the captain why the tool is required and give them the printed instructions URL, but do not pass the tool to `bin/fm-bootstrap.sh install`; wait for the captain to complete the manual installation, then rerun session start to confirm the dependency is present.
+- `BACKEND_INVALID: <name> (known: <names>)` - the resolved runtime backend has no verified dependency or lifecycle contract, so do not dispatch work until the invalid `FM_BACKEND` or `config/backend` value is corrected to one of the listed backends.
+- `NEEDS_GH_AUTH` - ask the captain to run `! gh auth login` (interactive; you cannot run it for them).
+  This probe now arrives from the deferred network stage, so it is also how an unreachable network shows up: `gh` cannot validate its token offline and reports the same failure. Confirm reachability before asking the captain to re-authenticate a credential that may be fine.
+- `NETWORK_CHECKS: <what did not complete>; rerun <command>` - the deferred network stage itself could not finish, so the checks it names are simply unknown, not failed.
+  Rerun the printed command; it is idempotent and re-derives every finding.
+  A `hit the ...s bound` line means one of those checks is slow or unreachable - most often a remote secondmate host - and the stage stopped rather than letting it wedge; a `lock was no longer held` line means the session that asked for the sweeps no longer owns them, so leave them to the session that does.
+- `TANGLE: <remediation>` - the primary checkout is stranded on a feature branch instead of its default branch; `AGENTS.md` section 8 explains why this guard exists and what it protects.
+  The work is safe on that branch ref; restore the primary to its default branch with the printed `git -C <root> checkout <default>`, then re-validate that branch in a proper worktree.
+  This is the only sanctioned firstmate-initiated git write to the primary, and it is a non-destructive branch switch that strands nothing.
+- `STARTUP_MEMORY_BUDGET: invalid config/startup-memory-budget - <reason>` - the visible startup-memory budget is not a safe one-line positive decimal file; do not infer the default or propagate it.
+  Correct the local primary file, then rerun session start so the normal convergence path can deliver the validated value to secondmate homes.
+- `CREW_DISPATCH: invalid config/crew-dispatch.json - <reason>` - the optional dispatch profile file exists but failed low-cost bootstrap validation; stop profile-based dispatch, report the actionable error, and require correction of the malformed schema, unverified harness name, or invalid harness/effort pair rather than falling back around it or selecting a bad profile.
+- `FLEET_SYNC: <repo>: skipped: <reason>` - a benign one-off skip (offline, no origin, local-only); bootstrap continued, investigate only if it blocks work.
+  A skip can also report the bounded fleet-refresh timeout (`FM_FLEET_SYNC_BOOTSTRAP_TIMEOUT`, or a fleet-size-aware default with a 20 second floor); a timeout never blocks startup.
+- `FLEET_SYNC: <repo>: recovered: <detail>` - the clone had drifted onto a clean detached HEAD holding no unique commits and the sync self-healed it (re-attached the default branch and fast-forwarded); no action needed, it is reported only so the self-heal is visible.
+- `FLEET_SYNC: <repo>: STUCK: on <state>, N commits behind <base> - needs attention` - the clone is dirty, on a non-default branch, detached with unique commits, or diverged, so the sync left it untouched (never forcing or discarding); it will keep falling behind until you look.
+  A loud STUCK, especially a growing N across bootstraps, means that clone needs hands-on attention; dispatch a crewmate or resolve it before it strands work.
+- `HOME_SUMMARY: this home has never published state/home-summary.json` or `... has not been republished since <stamp>` - this home's structured summary publication has failed repeatedly, and the line carries the failure count and the newest recorded reason from `state/.home-summary-refresh.log`.
+  Publication is deliberately best-effort, so it cannot change another session-start, spawn, teardown, or watcher-poll result, and the watcher runs it detached so a slow attempt cannot delay the liveness beacon.
+  Read the named record for the recorded reasons, then reproduce with a direct `bin/fm-home-summary-refresh.sh` (no `--best-effort`, which is what keeps the failure quiet) so the refresh error reaches you.
+  A recorded deadline means the complete refresh did not finish inside `FM_HOME_SUMMARY_TIMEOUT`, so inspect lock acquisition and producer completion before validation or publication, and fix the blocked phase rather than raising this load-bearing bound.
+
+- `BOOTSTRAP_INFO: closed the backlog item for <id> after interrupted cleanup; its endpoint or local copy may remain and should be reconciled` - replay closed the item, but the durable close says physical cleanup was interrupted.
+  Verify process reaping, the local-copy return, and endpoint closure, then reconcile any surviving resource.
+- `BACKLOG_RECONCILE: <id>: recorded backlog close could not be replayed: <reason>` - this session start found a pending-close record but could not land it.
+  A valid teardown record proves the close was authorized and recorded, but physical cleanup may be partial: verify process reaping, the local-copy return, and endpoint closure before assuming those resources are gone.
+  A validation error means the record cannot be trusted, so do not assume cleanup completed or follow any path or argument stored in it.
+  Read the named reason, inspect the marker as inert data when validation failed, fix the record or backlog-file problem, and rerun session start so a valid recorded close replays.
+  Never hand-close the item by deleting `state/<id>.backlog-close` - that can discard a completion link the cleanup captured, and the surviving marker prevents the record sweep from starting the item meanwhile.
+- `BACKLOG_RECONCILE: <id>: worker record exists but its backlog item could not be read: <reason>` - this home could not determine whether the item matches its worker record.
+  Resolve the named backlog read problem and rerun session start; never guess by starting or closing an unreadable item.
+- `BACKLOG_RECONCILE: <id>: worker record exists but its backlog item could not be moved to In flight: <reason>` - this home owns a worker whose backlog item is still queued, and the reconciliation could not correct it.
+  Until it is corrected, the fleet view reads that worker as work no backlog item owns; resolve the named backlog problem and rerun session start.
+- `SECONDMATE_SYNC: secondmate <id>: skipped: <reason>` - secondmate convergence left a live home on its existing checkout because the home was dirty, diverged, unsafe, on the wrong branch, missing its placement-specific target commit, unreachable, or otherwise not fast-forwardable, or because inherited local-material propagation failed; bootstrap continued, but inspect the reason because the secondmate's tracked instructions, inherited settings, or shared captain preferences may be stale after a primary update.
+- `SECONDMATE_LIVENESS: secondmate <id>: skipped: <reason>|respawn failed after <cause>: <reason>` - the session-start liveness sweep could not guarantee that the registered secondmate is running a real agent process.
+  Investigate the reason because that secondmate is not guaranteed live.
+- `SECONDMATE_HANDOFF: secondmate <id>: pending delivery: <n> item(s)` - queued work has already left the main dispatchable backlog and remains safe in the named remote route's backlog-format outbox, pending backlog receipt or receiver-wake confirmation.
+  Preserve that outbox and rerun `bin/fm-backlog-handoff.sh --resume-pending` after the route or endpoint problem is resolved; never re-add or dispatch the items from the main backlog.
+  An unsafe-outbox variant requires path and file-type inspection before any retry.
+- `NUDGE_SECONDMATES: secondmate <id>: send failed: <reason>` - secondmate convergence changed a running home's loaded instructions or inherited config, but the deterministic `fm-send.sh fm-<id>` re-read nudge failed.
+  Inspect the reason, keep the pending marker under `state/.secondmate-nudge-pending/` intact, and rerun session start after the endpoint or metadata issue is fixed so bootstrap can retry the exact same marked send on the same local or remote route.
+- `FMX: X mode on ...` / `FMX: X mode off ...` - bootstrap confirmed or removed the local Relay poll artifacts (`docs/configuration.md` "Relay (.env)"); the emitted line still carries Relay's former `X mode` wording.
+  Only when a running watcher needs the cadence transition applied immediately, restart the home-scoped watcher through the emitted harness supervision protocol; bootstrap deliberately never restarts the watcher itself.

package/assets/reference/skills/captain-hold-lifecycle/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: captain-hold-lifecycle
+description: >-
+  Agent-only policy for completing investigations and visual reviews without losing unresolved captain calls, and for closing what the captain owns with his actual words.
+  Load before treating an investigation, scout report, structured review, or Lavish review as complete, before ending a visual review that exposed a captain decision, when recording or routing the captain's answer, and on any RECORD DIVERGENCE line the wake drain prints.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Captain-hold lifecycle
+
+A decision is not a separate thing: it is simply a task waiting on the captain.
+The one primitive is an ordinary backlog task held for the captain (`tasks-axi hold <id> --kind captain`), its identity is the task id, and `bin/fm-captain-hold.sh` owns the deterministic mechanics this policy relies on.
+The agent performs the semantic inventory because scripts must not infer captain calls from report prose, visual-review artifacts, terminal output, or chat.
+
+## Policy
+
+Every unresolved question that belongs to the captain and is discovered while producing, reading, presenting, or ending an investigation or visual review must be carried by a captain-held task in the authoritative backlog of the home that owns the originating work before that work or review may be treated as complete.
+Prefer holding the work item the question gates over minting a new row; create a new task only when no work item exists to hold.
+Put the question and its options in the hold reason, and keep one held task per genuine gate: a multi-question review is one held task pointing at its report, not a row per question. Represent that task with exactly one board card that consolidates its questions and options; never fan one task id into duplicate same-key cards.
+Register or re-hold through `bin/fm-captain-hold.sh hold`, which is idempotent per task id.
+After inventorying the whole report and review surface, run `bin/fm-captain-hold.sh complete` with every captain-held task id, or with `--none` only when the reviewed surface leaves nothing waiting on the captain.
+A completed investigation and an ended visual review use this same owner and completion command; a visual tool, including Lavish, never owns a parallel completion policy.
+Run the command in the originating work's authoritative `FM_HOME`; secondmate-owned work registers in that secondmate home's backlog, and a question already held anywhere is never re-registered as a second row.
+Do not close a captain-held task merely because the originating investigation completed, its report was archived, its visual review ended, or its task was torn down.
+
+Never close anything the captain owns without recording what he actually said: `bin/fm-captain-hold.sh answer` writes his exact words into the task and closes it in the same act, with `--release` when the answer frees a captain-gated work item to proceed instead of completing a question.
+When the captain says "later", that is an answer too: re-hold with `tasks-axi hold <id> ... --until <date>` so the item leaves the live Captain's Call and resurfaces on its date, instead of leaving a live-looking card or fabricating a closure.
+"A keyed answer closes its matching captain-held task" is one capability with one owner, `bin/fm-captain-hold.sh answers`, and every channel that carries a captain answer feeds it the same task id and answer; a channel never maps keys to tasks, records a decision, or closes anything itself.
+Chat already feeds it through `bin/fm-send.sh --resolve-key`, and a captured-answer source feeds it once bound with `bin/fm-captain-hold.sh bind <source-id>`; bind before arming the source, and key each structured question by the held task's id.
+An unbound source and a key that names no captain-held task both simply feed nothing: the answer is still captured and firstmate is still woken, and closing falls back to the direct command above.
+A captain-held task closed outside this owner leaves no durable answer, so the completion gate keeps failing until `answer` records the decision the captain actually gave.
+Resolved findings, recommendations that need no captain choice, and prose that merely sounds decision-like do not create held tasks.
+Bearings reads the resulting structured state and must never compensate by scraping historical reports, visual-review artifacts, terminal output, chat, or other prose.
+
+A captain call can be written down twice - as the keyed status decision the fold reads, and as the backlog task held for the captain - and those two records can disagree without either surface saying so.
+`bin/fm-captain-hold.sh diverged` reports that contradiction and the wake drain prints it as `RECORD DIVERGENCE`; it closes nothing, because a captain call closed wrongly leaves review entirely, which is worse than the noise.
+Read such a line as "these two records disagree", never as "the captain ruled and someone forgot to file it": a call can dissolve because its premise was false, or turn out to have been a question of fact rather than the captain's to answer.
+Reconcile it with what actually happened - `answer` when the captain's own words exist to record, and a fresh `needs-decision` line re-opening the status decision when that resolution was not the captain's word.
+The absence of a routed work item is not a divergence and the guard never requires one: when the decision IS the deliverable there is nothing to route.
+
+## Operating sequence
+
+1. Read the complete investigation result and complete the visual review before declaring either complete.
+2. Inventory only genuine unresolved choices that require the captain, and find the task each one gates.
+3. Hold that task - or create one captain-held task for the review's open questions - with a concise reason carrying the question and options.
+4. Run `complete` with the full captain-held inventory for that review pass.
+5. Relay the choices to the captain as decisions from Bearings' Captain's Call section under `AGENTS.md` section 9; do not use the word hold in captain chat.
+6. Close each call only through `answer` (or a channel that feeds `answers`), through `--until` when the captain defers it, or confirm a channel already closed it.
+7. Confirm Bearings reflects the outcome: answered calls leave Captain's Call, released work resumes, and deferred calls sit in Charted Next with their date.
+
+`bin/fm-captain-hold.sh --help` owns command syntax, close modes, legacy-identity compatibility, completion attestation, retry behavior, and close ordering.
+`docs/captain-hold-lifecycle.md` records the mechanism and regression evidence without restating this policy.

package/assets/reference/skills/decision-hold-lifecycle/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: decision-hold-lifecycle
+description: >-
+  Renamed pointer kept for in-flight briefs: the decisions concept collapsed into "a task held for the captain".
+  Load captain-hold-lifecycle instead; this stub only redirects and will be removed one release after the collapse.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# decision-hold-lifecycle (renamed)
+
+The separate decision concept was collapsed into the one primitive the captain cares about: a task held for the captain.
+Read and follow `.agents/skills/captain-hold-lifecycle/SKILL.md`; it owns the completion gate, the recorded-answer rule, and every command this skill used to describe.
+Where an older brief says `bin/fm-decision-hold.sh`, that command still works as a one-release compatibility shim over `bin/fm-captain-hold.sh`.

package/assets/reference/skills/diagnostic-reasoning/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: diagnostic-reasoning
+description: >-
+  Agent-only procedure for diagnosing reported bugs.
+  Use before scoping a reported bug and before acting on a diagnostic report.
+  Owns end-user-aligned reproduction, causal separation, divergent-path and history inspection, counterfactual testing, and disconfirming evidence.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# diagnostic-reasoning
+
+Use this procedure before scoping a reported bug and before acting on a diagnostic report.
+This skill is the single owner of Firstmate's bug-diagnosis reasoning procedure.
+Firstmate applies it when briefing delegated investigation and evaluating the resulting evidence, without taking over project-specific investigation itself.
+
+## Establish the observed behavior
+
+Start from the end user's experience rather than an internal error string or an implementation hypothesis.
+Require an end-to-end reproduction aligned with the real user path whenever it is feasible and safe.
+If a faithful reproduction is not feasible, record the exact limitation and use the closest representative path without presenting it as equivalent evidence.
+Capture the expected behavior, observed behavior, setup, inputs, and repeatability before assigning a cause.
+
+Separate these three facts explicitly:
+
+- The **initiating trigger** is the event, input, or transition that starts the faulty behavior.
+- The **masking condition** is the independent state, environment, timing, cache, configuration, or path difference that hides or exposes the fault.
+- The **visible symptom** is what the end user or operator can actually observe.
+
+Do not collapse those facts into one label.
+A masking condition may explain why a fault appears only sometimes without being the initiating cause, and the visible symptom may be several layers downstream from both.
+
+## Test the causal explanation
+
+Inspect the failing path and a proven path where the intended behavior is known to work.
+Compare their inputs, state transitions, dependencies, timing, and control flow to find the earliest meaningful divergence.
+Inspect relevant history, including blame, commits, migrations, and prior implementations, when it can explain why the paths diverged or which invariant was intended.
+Do not treat the most recent nearby change as causal without evidence.
+
+Identify the smallest counterfactual that should change the outcome if the leading explanation is true.
+Change one condition at a time where practical, and record whether the symptom appears, disappears, or remains unchanged.
+Seek disconfirming evidence deliberately: name what observation would falsify the leading explanation, run that check when feasible, and retain contradictory results instead of explaining them away.
+Compare the final explanation against the proven path and show why the proposed causal boundary accounts for both the failure and the success.
+
+## Scope and act on the result
+
+A diagnosis brief should ask for the reproduction, trigger/mask/symptom separation, divergent and proven path comparison, relevant history, smallest counterfactual, and disconfirming evidence in the report.
+A diagnostic report should distinguish observed facts from hypotheses and state any unresolved uncertainty that could change the recommended scope.
+Before acting on the report, verify that its claimed cause explains the end-user reproduction and the proven path without relying on an untested masking condition.
+If a load-bearing element is missing, route a focused follow-up investigation instead of treating confidence or implementation detail as proof.
+A diagnosis or implementation-ready recommendation is evidence, not authorization to change code.
+Implementation still requires the captain's request or another existing lifecycle authority, and the reproduction should become the regression test when a fix is authorized.

package/assets/reference/skills/firstmate-codexapp/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: firstmate-codexapp
+description: >-
+  Agent-only playbook for coordinating visible Codex Desktop threads alongside Firstmate without pretending they are a selectable shell backend.
+  Use before creating, reading, steering, archiving, debugging, or reviewing a Codex App visible thread for Firstmate work, and before responding to requests to make Codex App native to Firstmate.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# firstmate-codexapp
+
+## Overview
+
+Use this playbook when Firstmate work needs a visible Codex Desktop thread.
+The current supported shape is Desktop host-tool choreography plus an explicit status-file return-channel check, not a `codex-app` value in `FM_BACKEND`.
+
+## Boundary
+
+Codex Desktop visible threads are companion host-tool workflows, not a selectable Firstmate backend.
+Read `docs/codex-app-backend.md` when it exists in this checkout; that document owns the acceptance contract, bridge requirement, status-return requirement, and staged rollout.
+
+If local helper scripts exist for Codex App work, use only helpers explicitly provided by the operator or maintained by Firstmate.
+For helpers outside `bin/`, inspect the source or header before running `--help`.
+
+## Preflight
+
+1. Confirm this session is running inside Codex Desktop and that the host tools are exposed.
+   Search exact names when needed: `create_thread`, `list_threads`, `read_thread`, `send_message_to_thread`, `archive`, and `set_thread_archived`.
+2. Confirm the target repository is already saved as a Codex Desktop project.
+   No host tool currently creates Codex App projects for an agent, so the human must add the project in Desktop before a created thread can reliably land there.
+3. Do not create projectless threads for repo work.
+   If the project is absent, stop and ask for the project to be added or use a normal Firstmate backend instead.
+4. Decide whether this is a real Firstmate-managed task or a visible companion thread.
+   A real task needs a task id, an isolated worktree or Desktop-owned cwd, a branch plan, and a writable `state/<id>.status` path.
+
+## Create And Send
+
+When creating a visible thread, use the Desktop host tool, not shell imitation.
+Target the saved project and ask the worker to start by reporting:
+
+```text
+pwd
+git rev-parse --show-toplevel
+git branch --show-current
+git log --oneline --max-count=3
+```
+
+For writable repo work, instruct the worker to use the Codex-created current directory.
+Do not tell it to `cd` into the saved project checkout for edits, commits, no-mistakes, pushes, or PR work.
+
+When sending follow-up instructions, use `send_message_to_thread`.
+If the user types directly into the visible thread, treat that as authoritative and reconcile from `read_thread` instead of undoing it.
+
+## Status Return Channel
+
+A Desktop-owned Codex thread can append to Firstmate status files only when the prompt gives an absolute path and the Desktop permission context can write that checkout.
+That makes status writes a verified return-channel requirement, not a fact to assume.
+
+For a Firstmate-managed task, include an explicit status instruction:
+
+```text
+Append supervisor-visible status lines to <absolute-firstmate-home>/state/<task-id>.status.
+Use only these prefixes for status changes: working:, needs-decision:, blocked:, paused:, done:, failed:.
+Use paused: only for a deliberate known external wait that should be rechecked later, never for a blocker that needs firstmate to act.
+Before doing substantive work, append "working: Codex Desktop thread started".
+```
+
+Verify the return channel before treating the thread as supervised:
+
+- `read_thread` shows the worker attempted the status write.
+- The local `state/<task-id>.status` file contains the expected line.
+- If available, the transcript includes a file-change entry for that status file.
+
+If the thread cannot write the status file, keep it as a visible companion thread only.
+Do not claim it is a complete Firstmate backend.
+
+## Observe And Reconcile
+
+Use `read_thread` for thread truth.
+Use `list_threads` only to find or recover a visible thread id, not as a replacement for reading the transcript.
+
+For Firstmate reconciliation, prefer concrete evidence:
+
+- thread id and project
+- current Desktop-owned cwd
+- branch name
+- last meaningful thread state
+- latest status file line
+- PR URL when one exists
+
+Avoid repeating long transcripts into Firstmate docs or PR bodies.
+Summarize only the host-tool calls, the status-file result, and the archive result.
+When reporting a Desktop-thread result to the captain, translate status prefixes and return-channel evidence through `AGENTS.md` section 9.
+
+## Archive
+
+Archive through the Desktop host tool: `archive` when that is the exposed primitive, or `set_thread_archived(threadId=<id>, archived=true)` when that is the exposed tool name.
+Archiving can remove the thread from normal sidebar/project views, but it should not erase the transcript or landed work.
+
+For companion threads, archive the thread and report where the durable work landed.
+If there is a real Firstmate task record, leave teardown decisions to the normal Firstmate task flow instead of this skill.
+
+## Failure Signals
+
+- Missing Desktop project: ask the human to add the target project in Codex Desktop, or use a normal backend.
+- Missing host tools: do not simulate them with shell files; use a terminal backend instead.
+- Status file not updated: treat the thread as unsupervised until the return channel is proven.
+- Worker editing the saved project checkout instead of its Desktop cwd: stop and decide whether to salvage the branch before continuing.
+- Production `codex-app` backend request: read `docs/codex-app-backend.md` and do not invent a local adapter.

package/assets/reference/skills/firstmate-codexapp/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Firstmate Codex App"
+  short_description: "Operate visible Codex Desktop threads"
+  default_prompt: "Use $firstmate-codexapp to coordinate visible Codex Desktop threads without pretending they are a shell backend."

package/assets/reference/skills/firstmate-coding-guidelines/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: firstmate-coding-guidelines
+description: >-
+  Agent-only reference for changing firstmate's shared, tracked material per AGENTS.md section 1.
+  Use before editing any of that material, whether working as firstmate directly or as a crewmate briefed on a firstmate-repo task.
+  Covers the knowledge-placement decision tree, the one-owner rule for contracts, the inline-stub pattern for content moved into a skill, AGENTS.md size discipline, trigger hygiene for new skills, and repo style rules (one sentence per line, plain dash, no agent co-author, shellcheck-clean bin scripts, colocated tests, and maintainer-verification evidence).
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# firstmate-coding-guidelines
+
+Load this before changing firstmate's shared, tracked material, as defined by `AGENTS.md` section 1.
+It exists because `AGENTS.md` grew from 585 to 958 lines between its last two restructures, entirely from conditional detail added inline instead of routed to its right home.
+Applying the rules below on every change is what keeps that from happening again.
+
+## Knowledge-placement decision tree
+
+Before writing a new fact anywhere in this repo, ask where it belongs, in this order.
+
+1. Does the firstmate AGENT need this on every session or every turn to operate?
+   If yes: `AGENTS.md`, inline.
+2. Does the agent need it only in a nameable situation - a spawn, a recovery, a specific wake type, a specific lifecycle step?
+   If yes: an agent-only skill under `.agents/skills/`, plus a one-line trigger pointer left inline in `AGENTS.md` (usually section 13).
+3. Is it public product, setup, or user/operator reference?
+   If yes: the surface classified for that audience in [`docs/documentation-audiences.md`](../../../docs/documentation-audiences.md), limited to current behavior, setup, supported limits, stable invariants, concise rationale, and current verification entry points.
+4. Is it contributor/maintainer architecture?
+   If yes: the classified maintainer-architecture owner for stable ownership, extension points, mechanism boundaries, and safety rationale.
+5. Is it active reusable verification for a current guarantee?
+   If yes: an explicitly classified maintainer-verification record may keep current dates, versions, exact commands, and exact output.
+6. Is it task or incident evidence - chronology, transcripts, branches, temporary paths, failed hypotheses, or delivery proof?
+   If yes: keep it in the private task report or PR evidence by default, after distilling every unique current fact into its authoritative owner.
+7. Is it mechanics - exact flags, exact commands, exact paths?
+   If yes: the script's own header comment plus its `--help` output, not prose in `AGENTS.md`, a skill, or a second documentation owner.
+
+Stop at the first tier that answers yes.
+Do not place a fact at a more convenient tier than the one this tree gives you.
+The machine-consumed inventory in [`docs/documentation-audiences.json`](../../../docs/documentation-audiences.json) is the single classification owner for maintained prose surfaces; do not add parallel front matter or a second audience list.
+
+## One-owner rule
+
+Every contract - a data format, a state machine, a decision procedure - is stated in full exactly once.
+Every other mention of it is a one-line cross-reference, never a restatement.
+A single deliberate one-line reinforcement at a genuine risk point is allowed, for example a "don't forget X" placed exactly where forgetting X is costly.
+Restating the contract's substance a second time is not allowed: the two copies will drift the moment only one is edited.
+When you touch a contract, patch, replace, or prune the owner's existing language rather than appending a new clause or paragraph wherever possible, then grep the repo for its other mentions and update the cross-references, not duplicate the change into a second full copy.
+
+## Inline-stub pattern
+
+When content moves out of `AGENTS.md` into a skill, decide what stays behind by asking one question: what must survive with no skill loaded?
+That is the trigger condition for loading the skill, plus any safety-critical fact that fires on a wake the skill itself is not loaded for.
+Everything else - the procedure, the mechanism, the surrounding detail - moves out completely.
+Do not leave a partial restatement behind "just in case".
+A partial copy is exactly the duplication the one-owner rule forbids.
+The model to copy is `AGENTS.md` section 8's "Away-mode stub": it keeps only the marker format, the ownership-transfer rule, and the exit condition inline, and points everything else at the `/afk` skill.
+
+## Size discipline
+
+Apply the decision tree above to every line you are about to add to `AGENTS.md`.
+If an addition needs more than a few lines of conditional detail (detail that matters only in a specific situation) or reference detail (a wire format, an exact schema, historical rationale), you are almost certainly adding it to the wrong file.
+`AGENTS.md`'s token cost is paid by every session of every fleet member, every time, whether or not that session ever hits the situation the new lines describe.
+A skill's cost is paid only by the sessions that actually load it.
+When in doubt, write the fact into the skill or doc first by patching that owner's existing language, and add only the one-line trigger to `AGENTS.md`.
+
+## Trigger hygiene
+
+A new skill is dead weight if nothing loads it.
+Every new skill needs its load trigger declared inline: section 13 for agent-only reference skills, or the relevant operating section for anything else.
+State the trigger as a condition ("load before X", "load on Y wake"), never as a vague pointer.
+Briefs for tasks that touch firstmate's own tracked material should tell the crewmate to load this skill.
+`bin/fm-brief.sh`'s `REPO` argument is a caller-supplied string with no reliable signal that it names firstmate's own repo, unlike a project registered in `data/projects.md`, so there is no clean point inside the scaffold to detect this case automatically.
+Firstmate adds this skill's load instruction to firstmate-repo briefs by hand instead.
+`CONTRIBUTING.md`'s "Development" section carries the same instruction as a durable reminder.
+
+## Compatibility and enforcement
+
+Before changing shared tracked behavior, review every affected supported primary harness and runtime backend rather than checking only the adapters active in the current fleet.
+Mark an axis not applicable only after inspecting its integration surface, and update the corresponding verification evidence when behavior changes.
+
+For critical safety, routing, startup, and supervision infrastructure, prefer deterministic and idempotent enforcement over relying on agent memory alone.
+Keep instructions as the authority and discovery layer, but make repeated execution converge safely and make invalid or unsafe states fail closed wherever the runtime can enforce them.
+
+### Harness-dependent checks
+
+This section is the single owner of the rule and of how to satisfy it.
+
+A check is harness-dependent when its verdict comes from something the vendor emits: a process name, rendered output, a spinner or keybind glyph, a banner, or a key the harness binds.
+Anything in that class must be proven end to end against the real harness, because a stub or fake agent can only confirm the assumption already written into the stub.
+That proof is authorized to spend tokens; the cost is small against a check that silently stops working.
+
+Build the check on the most structural signal that answers the question, and prefer a kernel or protocol fact over anything a release note could change.
+When a rendered surface is genuinely the only source, read more than one independent signal and let any of them carry a positive verdict, so no single vendor string is load-bearing.
+Where a surface signal is unavoidable, back it with a guard that fails loudly naming the harness and version rather than degrading quietly.
+
+Every such check needs two tests, because they fail for different reasons:
+
+- A portable regression in `tests/` that pins the logic with real processes and no harness, so CI enforces the classifier everywhere it runs tmux.
+  Drive the signals apart deliberately and assert the verdict survives losing one; assert the divergence itself so the case cannot go quietly vacuous.
+  Confirm which signal a given construction actually blinds on each supported platform rather than assuming, because the same trick can break different sources on macOS and Linux.
+- A live guard in the `live-harness-optin` family (`bin/fm-test-run.sh`), env-gated and self-skipping, that exercises every INSTALLED harness for real and fails naming the harness and version.
+  Report an absent harness explicitly rather than passing silently over it, and refuse a pass that checked nothing.
+  This guard is opt-in and on-demand because standard CI has neither harness binaries nor credentials; run it after every harness upgrade and before trusting refreshed per-harness evidence.
+
+Record the dated per-harness result in `docs/verification/runtime-backends.md`, and point at the live guard as the command that refreshes it, rather than leaving a version-scoped observation to rot into a false claim.
+
+## Documentation change review
+
+For every changed maintained prose surface, identify its inventory audience, authoritative owner, current-behavior relevance, destination for supporting evidence, and any unique safety fact that removal could lose.
+Move or delete evidence only after the current owner and regression pointer are verified.
+After all documentation, review-fix, and lint-fix commits, review the complete branch diff again against those criteria rather than reviewing only the latest commit.
+Run `bin/fm-doc-audience-check.sh`; it enforces classification, README setup routing, local link targets, and owner pointers without keyword-linting legitimate evidence prose.
+
+## Repo style rules
+
+- Put one full sentence per line in tracked Markdown.
+- Never wrap multiple sentences onto one physical line.
+- Plain dash `-`, never an em dash.
+- Never add an agent name as a commit co-author.
+- `bin/*.sh` and `bin/backends/*.sh` must pass `shellcheck`.
+- Run `bin/fm-lint.sh` before treating a script change as done; it is the single owner of the lint definition (file set, config, pinned shellcheck version, and pinned actionlint workflow lint) that CI and the no-mistakes pre-push gate both invoke, and it refuses to run under any other version of either linter.
+- When a task names a specific tool, implement the work with that tool, or explicitly flag the substitution and its new dependency footprint for review before shipping.
+- Colocate tests with the existing pattern in `tests/`, name them `<subject>.test.sh`, and extend an existing script rather than inventing a new runner.
+- Tests must exercise behavior through an executable or public interface and must never assert implementation-source bytes, including through parsers, regexes, snapshots, or indirect wrappers.
+- A maintainer-verification record under `docs/verification/` records active empirical facts, not assumptions or task chronology.
+- Include the date, version, exact commands run, and exact output needed to support the current guarantee.
+- Keep incident chronology and delivery evidence in private task reports or PR evidence unless a concise rationale is required to maintain a current safety boundary.

package/assets/reference/skills/firstmate-orca/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: firstmate-orca
+description: Agent-only operator checklist for Firstmate's Orca runtime backend. Use when switching to Orca, spawning or supervising Orca-backed work, smoke-testing Orca backend behavior, debugging Orca task state, or reconciling Orca-backed task metadata.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# firstmate-orca
+
+Use this as the operator checklist for Firstmate's experimental Orca runtime backend.
+It does not replace `AGENTS.md`, `docs/orca-backend.md`, or `harness-adapters`.
+
+Orca is a runtime backend, not an agent harness.
+The runtime backend owns the task endpoint and, for Orca, the task worktree.
+The harness is the agent process launched inside that endpoint, such as `claude`, `codex`, `opencode`, `pi`, `pi-signed`, `grok`, or `kimi`.
+Load `harness-adapters` for harness-specific launch, interrupt, resume, trust-dialog, and skill-invocation facts.
+
+Implementation details, metadata fields, teardown guarantees, and limitations live in `docs/orca-backend.md`.
+`docs/verification/runtime-backends.md` "Orca" owns active smoke evidence.
+Prefer the `bin/fm-*` helpers over raw `orca` commands.
+Use raw `orca` only when the helper surface cannot answer the inspection question, and keep the recorded firstmate metadata as the task identity.
+
+## Preflight
+
+Work from the current firstmate home or repo root.
+If `FM_HOME` is set, remember that operational state lives under `$FM_HOME` while the helper scripts still run from this repo's `bin/`.
+
+Before switching or spawning against Orca:
+
+- Confirm Orca is intentionally selected through `--backend orca`, `FM_BACKEND=orca`, or local `config/backend`.
+- Confirm the Orca app is running and the backend readiness checks pass before expecting spawn to work.
+- Inspect active `state/*.meta` records before changing backend selection.
+- Treat a backend switch as affecting future spawns only; existing tasks keep their recorded backend.
+- Reconcile watcher wakes before unrelated work, especially if Orca tasks are already in flight.
+
+## Spawn
+
+Use `bin/fm-spawn.sh` so firstmate creates the brief, worktree, terminal, metadata, status file, and watcher surface together.
+Pass `--backend orca` for a one-off Orca task, or rely on the already-selected Orca backend when that selection is intentional.
+
+After spawn, check the task with firstmate helpers:
+
+- `bin/fm-peek.sh fm-<id>` for launch failures, trust dialogs, or first output.
+- `state/<id>.meta` for `backend=orca`, `terminal=`, `orca_worktree_id=`, and `worktree=`.
+- `bin/fm-crew-state.sh <id>` when the current run state matters.
+- `bin/fm-watch.sh` whenever there are tasks in flight and this session owns supervision.
+
+Do not manually create the Orca worktree or terminal for a normal firstmate task.
+Do not manually patch metadata to make an externally-created Orca terminal look like a firstmate task.
+
+## Supervision
+
+Use `bin/fm-peek.sh`, `bin/fm-send.sh`, `bin/fm-crew-state.sh`, and `bin/fm-teardown.sh` for routine operation.
+For steer messages, use `bin/fm-send.sh <id> '...'`; the stable `fm-<id>` alias also works, and ordinary local text steers may contain newlines because they ride the durable inbox.
+Keep initial scope in the task brief; a temporary file remains useful when the instruction includes supporting material the worker should inspect separately.
+
+When supervising, treat `state/<id>.meta` as the routing record and Orca's own ids as backend implementation details.
+The stable firstmate alias is `fm-<id>`.
+The recorded `terminal=` and `orca_worktree_id=` fields are what backend helpers use under the hood.
+
+If an ordinary steer fails to enqueue, or a typed-plane `fm-send` fails to submit, do not immediately repeat the instruction.
+Read the reported failure and peek first, then decide whether the record exists or the target is busy, waiting on a prompt, stuck behind a popup, or genuinely wedged.
+For harness-specific interrupts or exits, load `harness-adapters`.
+
+## Recovery
+
+For a messy Orca-backed task:
+
+1. Read `state/<id>.meta` and the relevant status tail first.
+2. Confirm the task is actually Orca-backed before using Orca-specific assumptions.
+3. Use the recorded `terminal=`, `orca_worktree_id=`, and `worktree=` as the task identity.
+4. Prefer firstmate helpers for peek, send, state, and teardown.
+5. Avoid raw deletion of Orca worktrees or manual branch cleanup.
+6. Stop and inspect if the recorded worktree path, Orca worktree id, or project checkout no longer matches expectations.
+
+Teardown remains governed by the normal firstmate landing rules.
+Scout work can be torn down after the report exists and the `captain-hold-lifecycle` completion gate passes.
+Ship work can be torn down only after the work is landed by its project mode.
+
+## Smoke Test
+
+Keep Orca smoke tests focused on lifecycle plumbing:
+
+1. Select Orca intentionally for a disposable task or scout.
+2. Spawn through `bin/fm-spawn.sh`.
+3. Confirm metadata records the Orca backend, terminal, Orca worktree id, and isolated worktree path.
+4. Verify `bin/fm-peek.sh`, a short `bin/fm-send.sh` steer, watcher wake behavior, and `bin/fm-crew-state.sh`.
+5. Tear down through `bin/fm-teardown.sh` after the task is safely disposable or landed.
+6. Restore the previous backend selection if Orca was selected only for the smoke test.
+
+Do not mix a backend smoke test with unrelated feature work.