feat(fleet): add per-crew usage rows

[adibirzu]

Intent

Add a fleet-wide per-crew usage row (harness, model, context percentage, provider quota) to firstmate's canonical fleet snapshot and the bearings Underway view, and verify the Codex statusline proxy renders live, per the captain-approved fm-harness-usage-bar report Slices 0-2: (1) verify the Codex statusline proxy already wired to LIFEOS_StatusLine.sh actually renders and is input-sensitive; (2) extend fm-fleet-snapshot.sh and bin/fm-crew-usage-lib.sh so every live pane's row carries harness, model, context percentage where available, and provider quota from quota-axi spendPriority, with no new poller and quota gated opt-in since it is a live network call; (3) add light adapters for opencode/pi/cline usage data only where their output was confirmed to carry real per-task token/context data usable for a live row, and record findings where it does not. Slices 3 and 4 (upstream feature requests, Cursor editor extension) are explicitly out of scope. Captain-decided review-gate fixes to apply: R2 wire context_pct through fm-statusline-quota.sh where supported; R3 propagate secondmate child usage through secondmate_home_summary_json into the parent snapshot and Bearings view; R6 capture the rendered bar from a live Codex pane read-only (do not launch a new Codex session) and record it in the verification doc; plus auto-fixes R1 (quota caching survives the production call path, not just subshells), R4 (harness mapping covers cursor and agy, not only cursor-agent), R5 (quota reads/caching are bound to the worker's own account identity, reporting unavailable when that identity cannot be established), and R7 (FM_CREW_USAGE_QUOTA_TIMEOUT validated positive before use).

What Changed

• Add per-crew harness, model, live context percentage, and opt-in account-bound provider quota fields to fleet snapshots, including secondmate children and Bearings’ Underway data.
• Preserve verified account and harness metadata during account-based spawns, and extend quota provider mapping for cursor and agy.
• Document Codex statusline and unsupported harness findings, with coverage for usage-row, quota, timeout, and account-spawn behavior.

Risk Assessment

✅ Low: The change is bounded to on-demand snapshot telemetry, preserves account isolation before quota attribution, and handles unsupported or stale readings as unavailable.

Testing

Focused behavior tests passed for context validation/timeouts, opt-in account-bound quota caching, and account-launch isolation. A controlled end-to-end snapshot-to-Bearings run produced the reviewer-visible Codex usage row with model, live context percentage, and provider quota; the worktree remains clean.

Evidence: End-to-end Bearings usage row

Source: End-to-end Bearings usage row

{ "schema": "fm-bearings.v1", "in_flight": [ { "id": "usage-demo", "usage_harness": "codex", "usage_model": "gpt-5.6-terra", "usage_context_pct": "40", "usage_quota": "-3.25" } ] }

{
  "schema": "fm-bearings.v1",
  "in_flight": [
    {
      "id": "usage-demo",
      "usage_harness": "codex",
      "usage_model": "gpt-5.6-terra",
      "usage_context_pct": "40",
      "usage_quota": "-3.25"
    }
  ]
}

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

🔧 **Rebase** - 3 issues found → auto-fixed ✅

• ⚠️ bin/fm-bearings-snapshot.sh - merge conflict rebasing onto origin/main
• ⚠️ bin/fm-fleet-snapshot.sh - merge conflict rebasing onto origin/main
• ⚠️ docs/documentation-audiences.json - merge conflict rebasing onto origin/main

🔧 Fix applied.
✅ Re-checked - no issues remain.

🔧 **Review** - 6 issues found → auto-fixed (10) ✅

• 🚨 bin/fm-fleet-snapshot.sh:758 - Required R1 says quota-axi must be fetched once in the task-loop shell so every mapped worker shares one call. This hunk invokes fm_crew_usage_json via command substitution; it then command-substitutes the quota helper, so its cache mutations are discarded for every row. With two mapped tasks and quota enabled, quota-axi runs twice instead of once.
• 🚨 bin/fm-crew-usage-lib.sh:84 - Required R2 says to wire context_pct through fm-statusline-quota where supported. The new function always returns n/a; a live Codex pane with Context 40% left still produces usage.context_pct="n/a".
• ⚠️ bin/fm-crew-usage-lib.sh:68 - Required R4 covers normal cursor plus agy. The new lookup delegates to the existing mapping, which has neither mapping, so enabled quota rows for either harness silently render n/a despite available provider telemetry.
• ⚠️ bin/fm-crew-usage-lib.sh:58 - Required R5 requires worker-account-bound quota or unavailable. This path runs bare quota-axi under the snapshot process credentials and accepts no worker account/isolation identity, so two Codex workers on different accounts both receive the snapshot account's spendPriority.
• ⚠️ bin/fm-crew-usage-lib.sh:48 - Required R7 requires a positive timeout validation. FM_CREW_USAGE_QUOTA_TIMEOUT is only defaulted; setting it to 0 reaches fm_run_timed, whose documented contract disables the deadline for non-positive bounds.
• 🚨 docs/verification/fm-harness-usage-bar.md:32 - Required R6 requires evidence captured read-only from an already-running Codex pane. The added document explicitly says its evidence is synthetic stdin only and does not prove the interactive TUI path, so the required live-pane capture remains absent.

🔧 Fix: Fix account-bound cached crew usage telemetry
3 errors still open:

• 🚨 docs/verification/fm-harness-usage-bar.md:32 - Required R6 says to “capture the rendered bar from a live Codex pane read-only … and record it.” This document still records synthetic stdin invocation and explicitly says it does not prove the interactive TUI path, so the required live-pane evidence remains absent.
• 🚨 .agents/skills/bearings/SKILL.md:145 - The required usage row includes context percentage in the Bearings Underway view, but this new renderer instruction says usage_context_pct is always n/a and to never render it. A Codex row with context_pct:"40" is therefore silently rendered without its available context value.
• 🚨 bin/fm-crew-usage-lib.sh:118 - R2 requires context_pct through the statusline path where supported, including Claude panes reporting Context N% left. The statusline parser labels that shape source=codex; this equality check rejects it for a Claude task, returning n/a despite a valid displayed context percentage.

🔧 Fix: Render available crew context percentages
2 issues (1 error, 1 warning) still open:

• 🚨 docs/verification/fm-harness-usage-bar.md:32 - The required criterion says to “capture the rendered bar from a live Codex pane read-only … and record it in the verification doc.” The added verification record instead says its only evidence is synthetic stdin and explicitly admits it does not prove the interactive TUI path, so the required live-pane evidence is still absent.
• ⚠️ bin/fm-crew-usage-lib.sh:118 - context_pct accepts any digit string from the statusline diagnostic. For a captured footer such as Context 999% left, it silently emits "999" as a percentage rather than marking the malformed reading unavailable. Restrict accepted values to 0–100 before placing them in the fleet row.

🔧 Fix: Validate context percentage bounds
1 error still open:

• 🚨 bin/fm-spawn-acct.sh:43 - The wrapper now deliberately forwards --account, but the existing executable wrapper-contract test still asserts exactly three forwarded arguments. Its normal invocation will receive four (T-1, /proj, launch command, --account, claude-alt actually five—note the test's three-argument premise), increment fails, and exit 1. Update that test to assert the account flag/value in addition to the composed launch.

🔧 Fix: Update account spawn wrapper contract test
1 warning still open:

• ⚠️ bin/fm-fleet-snapshot.sh:70 - The newly documented snapshot contract says context_pct is always "n/a", but the same change now emits a validated live Codex/Claude statusline value (for example 40) when available. Update this contract text (and the matching stale library header) to describe "n/a" only when unavailable, so consumers are not instructed to ignore a required output field.

🔧 Fix: Clarify live context output contract
1 error still open:

• 🚨 bin/fm-spawn.sh:1460 - Required R5 says quota reads must be “bound to the worker's own account identity” and unavailable when it cannot be established. This hunk preserves account=codex-alt during fm-spawn.sh --relaunch, but relaunch deliberately clears the original raw account-isolated launch and starts the normal harness command. Concrete path: a task originally launched through fm-spawn-acct with CODEX_HOME=...codex-alt is relaunched by fm-control.sh; the replacement uses the default Codex account while its metadata still says codex-alt, so the snapshot invokes quota-axi under codex-alt and silently attributes that quota to the default-account worker. Bind account metadata at the spawn boundary to a launch isolation that is actually reapplied, or drop it on generic relaunches.

🔧 Fix: Drop unproven account inheritance on relaunch
3 issues (1 error, 2 warnings) still open:

• 🚨 bin/fm-spawn.sh:4156 - --account is accepted and persisted without proving that the launch applied that account’s isolation. For example, fm-spawn.sh T /project codex --account codex-alt launches normal/default Codex but writes account=codex-alt; an opt-in snapshot then runs quota-axi as codex-alt and attributes that quota to the default-account pane. This leaves required R5 (“bound to the worker's own account identity … unavailable when that identity cannot be established”) reachable. Persist an account only from a spawn path that applies/verifies its isolation, or omit/refuse direct unverified --account attribution.
• ⚠️ bin/fm-crew-usage-lib.sh:114 - The new live context read invokes fm-statusline-quota.sh synchronously for every Codex/Claude row, but has no timeout. Its backend capture can block on an unresponsive pane/backend CLI, serially stalling the canonical snapshot even with quota opt-in disabled. Run this diagnostic through a validated bounded call and emit n/a on expiry.
• ⚠️ bin/fm-fleet-snapshot.sh:760 - Usage context is read from the current task-id selector after the captured-generation check. If a task relaunches between prefetch and this call, the selector reads the replacement pane while the row retains old captured harness/model metadata, silently misattributing its context percentage. Recheck generation after this read and discard usage on mismatch, or collect it inside the existing generation-guarded observation boundary.

🔧 Fix: Bound live usage reads and account attribution
1 error still open:

• 🚨 bin/fm-spawn.sh:4156 - Required criterion: “quota reads/caching are bound to the worker's own account identity, reporting unavailable when that identity cannot be established.” The new metadata guard trusts the caller-controlled FM_SPAWN_ACCT_ISOLATED=1 as that proof. For example, fm-spawn-acct.sh T /proj --account codex-alt --harness codex forwards --harness after its isolated raw command; fm-spawn.sh replaces that raw command with normal/default Codex, but this line still records account=codex-alt. (A direct FM_SPAWN_ACCT_ISOLATED=1 fm-spawn.sh ... codex --account codex-alt has the same result.) With quota enabled, the snapshot reads codex-alt quota for a default-account pane. Verify/own the isolated launch contract at the spawn boundary before persisting account, otherwise emit unavailable.

🔧 Fix: Verify isolated account launch metadata
1 error still open:

• 🚨 bin/fm-spawn-acct.sh:45 - The required criterion says “every live pane's row carries harness, model, context percentage where available, and provider quota.” A valid account config directory containing spaces is shell-quoted by fm_account_compose_launch, then this wrapper sends it as a raw launch. fm-spawn.sh splits that quoted string on whitespace and records spaces' rather than claude/codex as the harness. The pane launches correctly, but its usage row loses the supported context/quota mapping. Preserve the verified account harness at the spawn boundary (or parse the composed command without shell word-splitting).

🔧 Fix: Preserve verified account harness metadata
1 error still open:

• 🚨 docs/verification/fm-harness-usage-bar.md:41 - Required intent says to “verify the Codex statusline proxy already wired to LIFEOS_StatusLine.sh actually renders” and capture that bar from a live pane. This capture shows only a native-looking gpt-5.6-terra high · <cwd> footer, not any LifeOS bar fields described at lines 26–29, so it does not establish that the configured proxy rendered live.

🔧 Fix: Correct live proxy verification evidence
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-crew-usage-lib.test.sh
• bash tests/federation/test_spawn_account.sh
• bash /Users/adrianb/.no-mistakes/evidence/01M1XCRT7JYY1Y6VQWHYYYXDEN/fm-usage-e2e.sh with controlled Codex statusline, account-isolated quota-axi, canonical snapshot, and Bearings projection

✅ **Document** - passed

✅ No issues found.

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

• ⚠️ linter found issues (exit code 1)

🔧 Fix: Suppress intentional inner-shell expansion lint warnings
✅ Re-checked - no issues remain.

✅ **Push** - passed

✅ No issues found.