feat: add supplemental fleet sweep reconciliation

[hsuperman]

Intent

Create a short, explicit, self-contained user-invocable operator skill named fleet-sweep under .agents/skills/fleet-sweep for the shared Firstmate repository. It must run only when the captain explicitly invokes /fleet-sweep and supplement without replacing, duplicating, scheduling, or creating another owner for watcher, wake-drain, Bearings, AFK, secondmate supervision, pending-reply, remote-reply, or capacity behavior. Begin from the durable wake drain and structured fleet snapshot, treat status appends as wake events rather than current-state truth, reconcile every registered secondmate and every recorded child against live current state, and prove each requested update reached the parent append-only status and pending-reply path and was drained using the existing process-event and pending-reply owners; targeted status reads are delivery evidence only. The captain explicitly selected a registry-aware aggregate-failure fallback and every registered secondmate remains in scope: resolve registered placement, use bin/fm-on.sh fm-fleet-snapshot.sh --secondmate-home-summary for registered remote homes, and use the existing validated local-home execution path owned by bin/fm-fleet-snapshot.sh to run fm-fleet-snapshot.sh --secondmate-home-summary inside registered local homes. This route-by-registry ruling supersedes any earlier wording that could be read as requiring remote-only fm-on uniformly. Never classify a local home clear merely because fm-on is inapplicable, and report a lane unavailable if its correct bounded targeted route also fails. Reconcile stale terminal and validation run-step evidence against newer live ownership so an older cancelled or failed run cannot override a newer actively working run, classify that worker as progressing, and do not interrupt, relaunch, or call it failed solely from the stale run. Check remote transport, pending replies, open decisions, merge or migration-ready work, blocked or inactive workers, and whether parent updates are arriving and draining. Load and follow orca-linear before a current-cycle Linear sweep across every home, classify every item as progressing, genuinely blocked by a named unresolved dependency, or concretely capacity constrained, repair or route fictitious blockers, and correct stale Linear status only when live evidence proves it stale. Respect latest captain-shared routing and parking rules, require concrete slot or host-resource evidence for capacity, and move already-authorized ready work through existing controls without creating a scheduler. Within standing authority the sweep may nudge or safely recover existing workers, clear fictitious blockers, dispatch already-authorized ready work, and correct stale Linear status, but it must not invent work, contradict current priorities, change scope or priority, merge without captain authority, perform destructive or irreversible actions, or broaden external effects. Keep normal supervision active while replies are pending and finish only after replies are durably ingested and drained or named transport failures are surfaced. Report explicit categories for captain actions, autonomous repairs dispatches and Linear corrections, progressing work, blockers with owners, capacity constraints with evidence, unavailable lanes, and unreconciled items so omissions cannot hide. Keep the workflow in one concise SKILL.md unless a deterministic helper is demonstrably necessary, compose existing Firstmate commands, add only the minimum AGENTS.md trigger pointer, follow existing user-invocable conventions, one-owner placement, one sentence per Markdown line, plain dashes, and no incident-specific REC policy. Preserve PR #2729 and every commit, update it through the no-mistakes path, never merge, and never claim absent CI is green; if the fork still requires maintainer workflow approval after all local pipeline stages pass, leave that as a paused external wait.

What Changed

• Add the user-invocable /fleet-sweep skill for bounded fleet-wide reconciliation across worker state, registered secondmates, pending replies, Linear work, blockers, capacity, and unavailable lanes.
• Register and document the command in the runtime instructions, README command table, and documentation audience manifest.

Risk Assessment

✅ Low: The change is a well-bounded operator skill that satisfies the required registry-aware fleet and Linear fallback behavior while preserving existing supervision, transport, and scheduling owners.

Testing

The baseline and final wake drains were empty, the structured live snapshot showed a valid registry with zero secondmates, targeted executable tests passed for correlated pending replies, remote reply ingestion/draining, stale-state reconciliation, and registry-aware unavailable fallbacks, while the live Linear read correctly failed as unlinked; evidence was captured, but a real multi-home cycle could not run because this isolated home has no registered fleet.

Evidence: Fleet-sweep validation report

Source: Fleet-sweep validation report

FLEET SWEEP VALIDATION RESULT
Captain actions: provide a registered staging/live secondmate home if a real multi-home reply cycle must be witnessed.
Autonomous repairs, dispatches, Linear corrections: none; no live items were present and no stale state was proven.
Progressing work: none recorded in this isolated gate home.
Blockers: none proven.
Capacity constraints: none; no slot or host-resource evidence exists.
Unavailable lanes: main-home Linear current-cycle lane (worktree is not linked to Linear).
Unreconciled items: live multi-home pending-reply/Linear fallback cycle (zero registered secondmates in the structured registry).
Executable proof: marked sends create correlated pending-reply records; captured remote replies ingest, deduplicate, acknowledge, and re-arm; registry snapshot failures remain explicit unknown/unavailable.

Evidence: Structured live fleet baseline

Source: Structured live fleet baseline

{
  "schema": "fm-fleet-snapshot.v1",
  "generated": "2026-08-21T10:26:34Z",
  "fm_home": "/Users/byronhsu/.no-mistakes/worktrees/497bd902d278/01M0H7N58RN9SVRCCNSY41F2RB",
  "roots": {
    "fm_root": "/Users/byronhsu/.no-mistakes/worktrees/497bd902d278/01M0H7N58RN9SVRCCNSY41F2RB",
    "state": "/Users/byronhsu/.no-mistakes/worktrees/497bd902d278/01M0H7N58RN9SVRCCNSY41F2RB/state",
    "data": "/Users/byronhsu/.no-mistakes/worktrees/497bd902d278/01M0H7N58RN9SVRCCNSY41F2RB/data",
    "config": "/Users/byronhsu/.no-mistakes/worktrees/497bd902d278/01M0H7N58RN9SVRCCNSY41F2RB/config",
    "projects": "/Users/byronhsu/.no-mistakes/worktrees/497bd902d278/01M0H7N58RN9SVRCCNSY41F2RB/projects"
  },
  "backlog": {
    "path": "/Users/byronhsu/.no-mistakes/worktrees/497bd902d278/01M0H7N58RN9SVRCCNSY41F2RB/data/backlog.md",
    "present": false,
    "records": []
  },
  "tasks": [],
  "main_inventory": {
    "valid": true,
    "reason": null,
    "orphan_in_flight": [],
    "unstructured_current_count": 0
  },
  "scout_reports": [],
  "secondmate_current": {
    "registry": {
      "present": false,
      "available": true,
      "complete": true,
      "reason": null,
      "provenance": "registered-table",
      "path": "/Users/byronhsu/.no-mistakes/worktrees/497bd902d278/01M0H7N58RN9SVRCCNSY41F2RB/data/secondmates.md",
      "freshness": {
        "status": "fresh",
        "observed_at": "2026-08-21T10:26:34Z"
      },
      "records": [],
      "input_truncated": false,
      "records_truncated": false,
      "reasons": [],
      "lines_in_window": 0,
      "records_in_window": 0
    },
    "records": [],
    "total_registered": 0,
    "total": 0,
    "shown": 0,
    "truncated": 0
  },
  "secondmate_landed": {
    "records": [],
    "truncated": [],
    "unreadable": [],
    "partial": []
  },
  "secondmate_guidance": {
    "note": "For kind=secondmate, bearings selects validated structured state from that registered home; parent events and bounded terminal evidence are fallback-only supplements and never current-state authority."
  }
}

Evidence: Pending-reply and remote-reply tests

Source: Pending-reply and remote-reply tests

$ tests/fm-send-secondmate-marker.test.sh
ok - fm-send: a kind=secondmate target gets the from-firstmate marker and corr prepended
ok - fm-send: an exact kind=secondmate task id is marked with corr exactly once
ok - fm-send: exact-id and stable-label kind=ship selectors are sent unmarked
ok - fm-send: explicit endpoints stay unmarked with or without local metadata
ok - fm-send: the --key path carries no marker (no literal text is typed)
ok - fm-send: the marker is '[fm-from-firstmate]' + terminal-safe U+2063, while direct captain text stays unmarked
ok - fm-marker: from-firstmate transformation is idempotent
ok - fm-send: marked secondmate payload preserves trailing newline bytes
$ tests/fm-remote-reply.test.sh
ok - a blocking non-destructive remote delta reaches durable process-event capture
ok - a captured delta is applied, acknowledged, and re-armed without a handler
ok - ingest appends one validated line, fetches its document, and advances the cursor
ok - replayed capture has one deduplicated append and one durable handling identity
ok - later generations cannot invalidate an unacknowledged ingested result
ok - the remote status and decision model mirrors and the cursor advances
ok - a remote mate's new decision folds open exactly as a local mate's does
ok - a replayed mirrored delta is idempotent in both the stream and the cursor
ok - transported control bytes are normalized in place and never stop the stream
ok - payload protocol-field names cannot collide with transport metadata
ok - NUL bytes are normalized in place before shell line processing
ok - local document storage failures remain retryable until delivery succeeds
ok - a mirrored reserved-key line cannot squat or clear the parent's own decision
ok - a reply that arrives after escalation resolves it and clears the open decision
ok - a preempted reply poll cannot publish channel freshness
ok - a quiet reply window publishes the caught-up watermark the reply guard reads
ok - a cursor-loss whole-log recapture is acknowledged quietly with no duplicate wake
ok - truncation is detected, escalated once, and not silently rebased
ok - remote reply retirement quiesces and refuses unhandled captured results
ALL TESTS PASSED
$ tests/fm-fleet-snapshot-view.test.sh
ok - empty fleet snapshot and view use explicit absence markers
ok - fixture snapshot covers task rows, backlog rows, pointers, and stable ordering
ok - main_inventory discloses orphan/unstructured and clears when inventory is consistent
ok - backlog normalization preserves strict roles and resolves every blocker compatibly
ok - snapshot event hints follow reconciled current state
ok - durable fold keeps an open decision past a later unrelated event
ok - a live secondmate endpoint preserves unrelated open decisions
ok - durable captain-held transfer closes the duplicate live status decision
ok - durable fold clears a decision only on a keyed resolution
ok - a completed scout's stale decision surfaces as a report pointer, not pending
ok - a scout still parked at a decision stays pending (terminal clear does not over-fire)
ok - snapshot includes durable scout reports after teardown
ok - snapshot parses tasks-axi rows and respects operational overrides
ok - fleet view renders the snapshot without secondmate peek guidance
ok - fleet view renders secondmate agent liveness

Evidence: Registry-aware routing tests

Source: Registry-aware routing tests

ok - Domain Alpha structured state overrides a stale parent Phase 7 event
ok - GNU stat file reads select -c without BSD filesystem-report pollution
ok - parent activity evidence is bounded and disclosed
ok - Bearings excludes a status-only child decision
ok - a structured child captain hold reaches Captain's Call
ok - missing, invalid, unreadable, malformed, and timed-out homes stay explicit unknowns
ok - an oversized secondmate summary retains the strict empty unknown fallback
ok - secondmate and per-home child counts are bounded, disclosed, and explicitly expandable
ok - parent decisions remain untrusted contradiction evidence
ok - parent evidence reconciliation distinguishes matching holds, blocks, and decisions
ok - nonprogressing child states are explicit and inconsistent terminal rows invalidate
ok - registry unavailability and bounded truncation remain explicit
ok - repeated snapshots keep the same current landed baseline and ignore prior reports
ok - default output is bounded, local-only, and marks omitted surfaces
ok - TOON and JSON are parity representations of the same model
ok - landed includes secondmate-managed merges alongside main-home merges
ok - default landed selection balances one dominant home with sparse homes
ok - landed selection refills capacity after sparse homes exhaust
ok - landed selection uses deterministic home order when homes exceed the cap
ok - landed selection preserves deterministic home and internal tie ordering
ok - landed selection handles no landed items
ok - --all-landed keeps the complete global landed output
ok - landed stays bounded with per-home + overall caps and omitted[] disclosure
ok - Bearings keeps a live blocker in structured live state and never converts it to Charted Next queue work
ok - action-free items (working/done/queued/landed) do not leak into Captain's Call
ok - main orphan in-flight stays out of Underway and is disclosed in omitted/gates
ok - main unstructured current is disclosed while structured siblings still project
ok - counterfactual meta clears main inventory warning and projects the live task
ok - mixed secondmate roles, partial state, and captain readiness project independently
ok - main and secondmate captain actionability use the same blocker readiness
ok - a completed scout with decision-like report prose is a pointer, not pending
ok - an authoritative captain hold surfaces end-to-end
ok - current report pointers surface
ok - superseded queued items are dropped by default and restored with --all-queued
ok - --include-prs is the only path that fetches, and it enriches correctly
ok - a partial GitHub failure degrades gracefully
ok - Perl fallback bounds stalled GitHub calls without coreutils timeout
ok - all fleet-sized sections are capped with counted opt-in expansion
ok - live PR enrichment caps repositories with counted expansion
ok - per-repository open-PR caps are disclosed with an expansion knob
ok - projection and TOON rendering failures exit nonzero with diagnostics

Evidence: Linear lane result

Source: Linear lane result

{
  "id": "1f97f122-2e17-4824-af3b-8afff204917c",
  "ok": false,
  "error": {
    "code": "linear_no_linked_issue",
    "message": "The current worktree is not linked to Linear.",
    "data": {
      "nextSteps": [
        "Open a Linear-linked worktree or pass an explicit issue id."
      ]
    }
  },
  "_meta": {
    "runtimeId": "10ab89eb-1744-458e-8619-5ab16fcb64cc"
  }
}

- Evidence: [Final wake drain](https://github.com/hsuperman/firstmate/blob/92628a4882fe3d02d5692b917e5773b00afdbad2/.no-mistakes/evidence/fm/fleet-sweep-skill/fleet-sweep-final-drain.txt) - Outcome: ⚠️ 1 warning across 2 runs (11m21s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed ✅

• 🚨 .agents/skills/fleet-sweep/SKILL.md:33 - The intent requires a “current-cycle Linear sweep across every home,” but the aggregate-report fallback only runs fm-fleet-snapshot.sh --secondmate-home-summary, whose output contains fleet/backlog state but no Linear inventory. If a secondmate report is unavailable while this snapshot succeeds, that home's Linear items remain unchecked without the lane necessarily being classified unavailable. Require a placement-correct bounded Linear fallback, or explicitly classify that home's Linear lane as unavailable and unreconciled.

🔧 Fix: Add placement-aware Linear fallback reconciliation
✅ Re-checked - no issues remain.

⚠️ **Test** - 1 warning

• ⚠️ .agents/skills/fleet-sweep/SKILL.md:1 - The live harness proves /fleet-sweep is discoverable and enforces its operational boundary, but a complete multi-home sweep was not executed because it would mutate real fleet, pending-reply, and Linear state. Full end-to-end proof requires an authorized staging fleet or permission to exercise live operational state.
• git diff --find-renames 1cb900c28faf23fe23c9bb54e63f7c3b436ea096..ebda14583e10eeec6bedd17008f9af1d6145465b
• tests/fm-documentation-audiences.test.sh
• bin/fm-doc-audience-check.sh
• claude -p '/fleet-sweep' --permission-mode plan --allowedTools Read Glob Grep --no-session-persistence --output-format json --max-budget-usd 0.25 (inconclusive setup probe: budget exhausted)
• claude -p '/fleet-sweep' --permission-mode plan --allowedTools Read Glob Grep --no-session-persistence --output-format json --max-budget-usd 0.65
• git status --short && git rev-parse HEAD && git diff --check 1cb900c28faf23fe23c9bb54e63f7c3b436ea096..ebda14583e10eeec6bedd17008f9af1d6145465b

🔧 Fix: Confirm fleet-sweep paths; no reproducible failure
1 warning still open:

• ⚠️ .agents/skills/fleet-sweep/SKILL.md:1 - The authorized live sweep found zero registered secondmates and no recorded workers or pending replies in this isolated gate home, while the worktree was not linked to Linear. Executable fixture tests prove the correlated pending-reply, remote ingest/drain, registry-aware routing, stale-state reconciliation, and unavailable-lane behavior, but a genuine live multi-home cycle remains unreconciled until a registered staging or live secondmate home is available.
• bin/fm-wake-drain.sh before and after the sweep
• bin/fm-fleet-snapshot.sh --json
• orca skills get orca-linear
• orca status --json
• orca linear issue --current --full --json
• tests/fm-send-secondmate-marker.test.sh
• tests/fm-remote-reply.test.sh
• tests/fm-fleet-snapshot-view.test.sh
• tests/fm-bearings-snapshot.test.sh
• Manual category-by-category fleet-sweep report generated from the live snapshot, final drain, and Linear result
• git status --short confirmed testing left the worktree unchanged

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aba95c5e88

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Route local secondmates through their local homes

Captain, when a registered secondmate is local and its aggregate report is unavailable or partial, this fallback always invokes fm-on.sh; that command’s documented contract says “Routes come only from remote records” (bin/fm-on.sh:7-8), while the snapshot owner explicitly uses an environment-scoped local-home execution for local secondmates (bin/fm-fleet-snapshot.sh:1190-1209). The sweep therefore falsely classifies every affected local lane as unavailable instead of reconciling it, so branch on registered placement and reuse the validated local-home path.

AGENTS.md reference: AGENTS.md:L49-L52

Useful? React with 👍 / 👎.

[kunchenguid]

Speaking as Kun's firstmate:

VISION verdict: align as opt-in composition. /fleet-sweep is user-invocable, exact-invocation only, and it composes wake-drain, fleet-snapshot, send, crew-state, and existing recovery/dispatch owners rather than inventing a new task shape.

Class: opt-in. Not default-on. Ordinary status still goes through Bearings. The skill's standing-authority bounds (no invented work, no merge without captain authority, no destructive action) match VISION.

Note, not a merge blocker here: the fallback bin/fm-on.sh <id> fm-fleet-snapshot.sh --secondmate-home-summary is remote-only by contract, so a local secondmate whose aggregate report fails will be labeled unavailable. The primary path still uses fm-send.sh.

No security issue. Approving first-time fork workflow runs. Not merge-eligible until CI including no-mistakes is green.