Merge pull request #2 from ruby-dlee/codex/agent-fleet-integration

feat: add agent fleet routing and durable completion reports

Author: ruby-dlee

.agents/skills/bootstrap-diagnostics/SKILL.md

@@ -2,7 +2,7 @@
 name: bootstrap-diagnostics
 description: >-
   Agent-only handling playbook for session-start bootstrap diagnostics.
-  Use whenever the session-start digest's bootstrap section prints any diagnostic or capability line - MISSING, MISSING_MANUAL, BACKEND_INVALID, NEEDS_GH_AUTH, TANGLE, CREW_HARNESS_OVERRIDE, CREW_DISPATCH, FLEET_SYNC, SECONDMATE_SYNC, SECONDMATE_LIVENESS, TASKS_AXI, NUDGE_SECONDMATES, or FMX - or when a standalone bin/fm-bootstrap.sh run prints one.
+  Use whenever the session-start digest's bootstrap section prints any diagnostic or capability line - MISSING, MISSING_MANUAL, BACKEND_INVALID, ACCOUNT_ROUTING, NEEDS_GH_AUTH, TANGLE, CREW_HARNESS_OVERRIDE, CREW_DISPATCH, FLEET_SYNC, SECONDMATE_SYNC, SECONDMATE_LIVENESS, TASKS_AXI, NUDGE_SECONDMATES, REPORT_RETENTION, or FMX - or when a standalone bin/fm-bootstrap.sh run prints one.
   A silent bootstrap section means all good and needs no skill load.
 user-invocable: false
 metadata:
@@ -22,6 +22,7 @@ The inline rules in `AGENTS.md` section 3 still bind: detect, then consent, then
   For `quota-axi`, bootstrap requires it because crew-dispatch `quota-balanced` may call it; `bin/fm-dispatch-select.sh` still degrades at runtime when quota data is unavailable.
 - `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.
+- `ACCOUNT_ROUTING: invalid routing policy - <reason>` - the environment or `config/account-routing-mode` cannot resolve to exactly one of `off`, `observe`, or `enforce`; fix the reported source before dispatch because managed spawns will fail closed on the same policy error.
 - `NEEDS_GH_AUTH` - ask the captain to run `! gh auth login` (interactive; you cannot run it for them).
 - `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.
@@ -45,5 +46,7 @@ The inline rules in `AGENTS.md` section 3 still bind: detect, then consent, then
 - `NUDGE_SECONDMATES: fm-<id>...` - the secondmate sweep fast-forwarded one or more *running* secondmate homes to firstmate's current version and their instruction surface (`AGENTS.md`, `bin/`, or `.agents/skills/`) actually changed; send a one-line re-read nudge with `FM_HOME=<this-firstmate-home> bin/fm-send.sh <id> 'firstmate was updated to the latest - please re-read your AGENTS.md to pick up the new instructions.'` unless `FM_HOME` is already set to the active firstmate home.
   This mirrors `/updatefirstmate`'s `nudge-secondmates:` report: it is a gentle steer, never an interruption, and the fast-forward already landed safely.
   A secondmate that was skipped, already current, or whose advance changed no instructions is not listed and must not be disturbed.
+- `REPORT_RETENTION: unavailable: <reason>` - the machine-global report-retention LaunchAgent is absent, stale, unloaded, or has not reported a recent successful prune, so opportunistic bounded pruning remains available but post-minimum-age cleanup is not guaranteed to run while Firstmate is idle.
+  Surface the failure, wait for the captain's consent, then run `bin/fm-bootstrap.sh install report-retention`; never install or activate it without that consent.
 - `FMX: X mode on ...` / `FMX: X mode off ...` - bootstrap confirmed or removed the local X-mode poll artifacts (`docs/configuration.md` "X mode (.env)").
   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.

.agents/skills/firstmate-orca/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Agent-only operator checklist for Firstmate's Orca runtime backend. Use when recovering or supervising eligible legacy Orca-backed work, testing Orca backend behavior, debugging Orca task state, or reconciling Orca-backed task metadata.
 user-invocable: false
 metadata:
   internal: true
@@ -25,18 +25,19 @@ Use raw `orca` only when the helper surface cannot answer the inspection questio
 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:
+Before recovering a task onto 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.
+- Confirm the task meets the eligibility contract in `docs/orca-backend.md`; new work must use tmux, Herdr, zellij, or cmux.
+- Confirm Orca is intentionally selected for this eligible recovery through `--backend orca` or `FM_BACKEND=orca`.
+- Confirm the Orca app is running and the backend readiness checks pass before expecting the respawn 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.
+- Do not set Orca as the durable backend for a home that launches new tasks.
 - 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.
+Use `bin/fm-spawn.sh` for an eligible pre-cutover respawn so firstmate creates the worktree, terminal, metadata, status file, and watcher surface together.
+New task spawns refuse `backend=orca` before any owned mutation; `docs/orca-backend.md` owns the rationale and exact legacy eligibility rule.
 
 After spawn, check the task with firstmate helpers:
 
@@ -45,7 +46,7 @@ After spawn, check the task with firstmate helpers:
 - `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 create the Orca worktree or terminal for an eligible firstmate recovery.
 Do not manually patch metadata to make an externally-created Orca terminal look like a firstmate task.
 
 ## Supervision
@@ -73,19 +74,18 @@ For a messy Orca-backed task:
 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.
-Ship work can be torn down only after the work is landed by its project mode.
+Teardown remains governed by `docs/orca-backend.md`'s eligible legacy task contract; follow its report and landing rules exactly.
 
-## Smoke Test
+## Regression Verification
 
-Keep Orca smoke tests focused on lifecycle plumbing:
+Do not synthesize legacy metadata or spawn a disposable Orca task merely to smoke-test the backend.
+Run the focused fake-Orca suite in `docs/orca-backend.md` to verify lifecycle plumbing.
+When an actual eligible legacy recovery is already required, verify it through the normal lifecycle:
 
-1. Select Orca intentionally for a disposable task or scout.
-2. Spawn through `bin/fm-spawn.sh`.
+1. Confirm the task metadata has no `report_required` marker and select Orca for that recovery.
+2. Respawn 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.
+Do not mix adapter verification with unrelated feature work.

.agents/skills/fmx-respond/SKILL.md

@@ -139,7 +139,7 @@ Treat `state/x-inbox/` as the source of truth and process **every** file you fin
       **Destructive, irreversible, or security-sensitive work is the exception** (X mode is a public, relayed channel and does not carry full in-session trust): do not execute it from the mention. Flag it to the captain through the normal trusted channel first - the same carve-out as `yolo` (AGENTS.md §1, §7) - act only on the captain's word, and in step 2d say only that it has been flagged for the captain.
       **If the request spawned a real, longer-running task** (you ran `bin/fm-spawn.sh`), link that task to this mention so milestone and completion follow-ups can be posted: `bin/fm-x-link.sh <task-id> <request_id>`.
       **Link here, in step 2c, before the step 2f inbox cleanup** - `bin/fm-x-link.sh` can copy both the mention's reply platform and explicit budget from the still-present inbox payload without a relay lookup.
-      If that local context is incomplete it uses the durable resolution contract in `docs/configuration.md` and warns loudly, while the follow-up path refuses to post unless both values can be resolved authoritatively.
+      If that local context is incomplete it uses the durable resolution contract in `docs/configuration.md` and warns loudly, while the follow-up path proceeds when either the platform or a valid explicit budget of at least 50 characters is resolved authoritatively and refuses only when neither is available.
       Then step 2d's reply is an **acknowledgement** ("on it, captain"), and genuine milestone updates plus the final outcome come later as follow-ups (see "Completion follow-up" below), with the terminal one posted using `--final`.
       If the work completed in this turn (a backlog item filed, a question answered), there is no task to link and step 2d reports the outcome directly.
    d. **Compose the reply.** For a **question**, answer `.text` from the fleet state gathered in step 1. For an **actionable request that completed now**, report the outcome of step 2c (what was done, or - for escalated work - that it has been flagged for the captain). For an **actionable request that spawned a linked task**, acknowledge that you have the order and are on it - milestone updates and the final outcome follow later as completion follow-ups, so do not promise a result you do not yet have. Either way keep it short, in firstmate's voice, and public-safe.
@@ -199,7 +199,8 @@ This skill's own responsibility during the mention-handling turn is linking the
   When the update carries one real visual artifact, add `--image <path>`; the helper forwards it to `bin/fm-x-reply.sh --followup` so the same image contract used for ordinary replies applies here too.
 - On a terminal wake (PR merged / scout report / local merge / failed), firstmate posts the task's **final** outcome ("done, here's the result"; for a failure, an honest "this one didn't pan out") with `bin/fm-x-followup.sh <task-id> --final --text-file <path>`, which always clears the link after that post regardless of how many follow-ups remain under the cap.
 - Every follow-up is held to the exact same public-safety bar as every reply here: outcomes only, no task ids, internals, captain-private material, or secrets. Past the window, past the cap, or on the relay's own rejection of an exhausted binding, a follow-up attempt is skipped silently and the link is cleared - never treated as a failure worth retrying.
-- If either a follow-up's platform or explicit budget cannot be authoritatively resolved from per-request context, inbox payload, or relay answer, `bin/fm-x-followup.sh` does NOT post it: the fail-safe holds it (the link is kept, exit non-zero) rather than use a local default. This is a retryable hold - a later milestone wake retries it once both values are recoverable.
+- If neither a follow-up's platform nor a valid explicit budget of at least 50 characters can be authoritatively resolved from per-request context, inbox payload, or relay answer, `bin/fm-x-followup.sh` does NOT post it: the fail-safe holds it (the link is kept, exit non-zero) rather than use a local default.
+  This is a retryable hold - a later milestone wake retries it once either value is recoverable.
 
 ## Notes
 

.agents/skills/reports/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: reports
+description: Browse, search, open, or summarize Firstmate's durable completion report stack. Use when the captain asks what Firstmate or its crews finished, wants a completion report or visual evidence, asks to review recent work, or invokes /reports.
+user-invocable: true
+metadata:
+  internal: true
+---
+
+# Completion reports
+
+Use `bin/fm-report-stack.mjs` from the Firstmate installation that loaded this skill.
+
+Run `bin/fm-report-stack.mjs open` to regenerate and open the searchable offline stack.
+Run `bin/fm-report-stack.mjs list` for a concise inventory, or add `--json` when structured filtering or summarization is needed.
+Run `bin/fm-report-stack.mjs path <task-id>` to locate one report without opening it.
+Run `bin/fm-report-stack.mjs open <task-id>` to open one report directly.
+
+When the captain asks for a summary in chat, read the selected entry's `manifest.json` and `report.md`, then summarize the outcome, verification, visual evidence, and follow-ups.
+Do not inspect provider account homes or raw session state for report browsing.
+Treat the report stack as the durable completion ledger and the source task state as volatile.
+
+Read `docs/report-stack.md` only when diagnosing publication, explaining the storage contract, or intentionally publishing a pre-cutover task.

.agents/skills/reports/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Completion Reports"
+  short_description: "Browse completed Firstmate task reports"
+  default_prompt: "Use $reports to open and summarize the Firstmate report stack."