feat(bin): trigger the 70% compaction doctrine from Claude's host-computed context telemetry

[sbracewell64]

Intent

The developer (operating through a "firstmate" supervisor) tasked an autonomous agent with GSD Phase 4 fleet telemetry: wiring Claude Code's statusline JSON context_window payload (remaining_percentage, used_percentage, total_tokens, current_usage) into the firstmate repo so the existing "compact at ~70% context pressure" doctrine can be triggered from a real host-computed instrument rather than a worker's self-estimate. Requirements included making the compact-at-70% trigger fireable from that reading (with design latitude over whether it surfaces in the statusline display, a hook, or a crew brief advisory), plus tests and docs per repo conventions. A hard boundary was set: the change must not alter firstmate's routing, supervision, worker lifecycle, state integrity, isolation, or completion detection. The work had to be done on branch fm/gsd-p4-fleet-telemetry in an isolated worktree and validated through the no-mistakes pipeline before shipping a PR, including an in-fork mirror PR to work around CI not running on cross-fork PRs. During validation, the developer ruled that dated verification evidence be added to the docs (verified 2026-07-24 against Claude Code 2.1.219, confirming the context_window object), and after repairing a GitHub credential missing workflow scope, directed the agent to resume from pipeline head 92e7c2e and complete the push, PR, and mirror.

What Changed

• Added bin/fm-context-statusline.sh, wired as the Claude Code statusLine command in tracked .claude/settings.json: it renders the real host-computed used/remaining context percentages from the context_window payload and appends a COMPACT NOW: /compact advisory at 70% used or higher. Only the two trigger percentages are required — missing optional fields (total_tokens, current_usage) are named in the display instead of silently darkening the instrument, and invalid payloads produce no display and clear any stale snapshot.
• bin/fm-spawn.sh now gives spawned Claude crewmates a git-excluded settings.local.json that runs the same script with --record, atomically writing a context-pressure.json snapshot (present fields, missing_optional_fields, derived compact_recommended) under the existing per-task /tmp/fm-<id> root; bin/fm-brief.sh adds a "Context pressure" section to ship/scout briefs telling workers to read that snapshot at phase boundaries and /compact when recommended, and secondmate charters carry the same CTX-row trigger. Routing, supervision, lifecycle, and completion detection are untouched.
• Added behavior tests (tests/fm-context-statusline.test.sh, tests/fm-brief.test.sh additions, spawn-dispatch assertions) covering the exact-70% trigger, truncation, snapshot resilience, and the per-agent-kind brief contract, plus docs in docs/configuration.md (including dated verification of the payload contract against Claude Code 2.1.219) and docs/scripts.md.

Risk Assessment

✅ Low: The round-2 commit faithfully implements the user's ruled contract (hard-require only the two trigger percentages, visibly name missing optional fields, preserve-only-present snapshot fields) with matching docs and exact-assertion tests, and leaves all previously verified invariants — atomic writes, fail-silent handling, spawn/brief wiring, and the no-lifecycle-change boundary — intact.

Testing

Ran the four touched behavior-test files through the repo's runner (all pass), then demonstrated the feature end-to-end: real statusLine payloads through the tracked settings command produced the CTX display, the exact-70% COMPACT NOW advisory, the atomic worker snapshot JSON, and silent cleanup on malformed input; generated briefs show the compaction contract on every agent kind, and the payload field contract was independently re-confirmed in the Claude Code 2.1.219 binary.

Evidence: Statusline E2E transcript (display, 70% trigger, snapshot, malformed-input cleanup)

$ echo '{"context_window":{..."used_percentage":72.4...}}' | fm-context-statusline.sh --record /tmp/fm-evidence-demo/context-pressure.json CTX 72.4% used / 27.6% left (200k) | COMPACT NOW: /compact $ cat /tmp/fm-evidence-demo/context-pressure.json { "context_window": { "remaining_percentage": 27.6, "used_percentage": 72.4, "total_tokens": 200000, "current_usage": {...} }, "compact_at_used_percentage": 70, "compact_recommended": true } (69.99% renders 'CTX 69.9% used / 30% left (200k)' with no advisory; malformed payload prints nothing, exits 0, removes the stale snapshot)

=== End-to-end: Claude Code statusLine payload -> CTX display + worker snapshot ===
Tracked .claude/settings.json statusLine command: "$CLAUDE_PROJECT_DIR"/bin/fm-context-statusline.sh

--- 1. Healthy session (42.3% used): plain pressure readout, no advisory ---
$ echo '{"context_window":{"remaining_percentage":57.7,"used_percentage":42.3,"total_tokens":200000,"current_usage":{"input_tokens":80123,"output_tokens":4477,"cache_read_input_tokens":12000}}}' | fm-context-statusline.sh --record /tmp/fm-evidence-demo/context-pressure.json
CTX 42.3% used / 57.7% left (200k)

--- 2. Just under threshold (69.99% used): truncates down, trigger stays silent ---
$ echo '{"context_window":{"remaining_percentage":30.01,"used_percentage":69.99,"total_tokens":200000,"current_usage":{"input_tokens":1,"output_tokens":1}}}' | fm-context-statusline.sh --record /tmp/fm-evidence-demo/context-pressure.json
CTX 69.9% used / 30% left (200k)

--- 3. At/over threshold (72.4% used): compact-at-70% doctrine fires ---
$ echo '{"context_window":{"remaining_percentage":27.6,"used_percentage":72.4,"total_tokens":200000,"current_usage":{"input_tokens":140000,"output_tokens":4800,"cache_read_input_tokens":100}}}' | fm-context-statusline.sh --record /tmp/fm-evidence-demo/context-pressure.json
CTX 72.4% used / 27.6% left (200k) | COMPACT NOW: /compact

--- Snapshot recorded for the spawned worker (what the crewmate reads) ---
$ cat /tmp/fm-evidence-demo/context-pressure.json
{
  "context_window": {
    "remaining_percentage": 27.6,
    "used_percentage": 72.4,
    "total_tokens": 200000,
    "current_usage": {
      "input_tokens": 140000,
      "output_tokens": 4800,
      "cache_read_input_tokens": 100
    }
  },
  "compact_at_used_percentage": 70,
  "compact_recommended": true
}

--- 4. Malformed payload (self-estimate shape): silent, stale snapshot cleared ---
$ (no output, exit 0)
$ ls /tmp/fm-evidence-demo/context-pressure.json -> removed (stale advisory cannot linger)

Evidence: Worker-facing brief and charter context-pressure sections

=== Worker-facing surfaces generated by fm-brief.sh ===

--- Ship-task crewmate brief (data/evidence-ship-1/brief.md), '# Context pressure' section ---
# Context pressure
Claude Code sessions receive host-computed context-window telemetry in the bottom status line.
For a spawned Claude worker, the same reading is written to `/tmp/fm-evidence-ship-1/context-pressure.json`.
At natural phase boundaries, read that file when it exists and use it instead of a self-estimate.
When `compact_recommended` is `true` (70 percent used or higher), run `/compact` before continuing.
The file is optional because other worker runtimes do not expose this verified telemetry contract; never fabricate a reading when it is absent.

--- Secondmate charter (data/evidence-mate-1/brief.md), CTX-row compaction instruction ---
In Claude Code, the bottom `CTX` row is host-computed context pressure; when it shows `COMPACT NOW: /compact` at 70 percent used or higher, run `/compact` before continuing instead of relying on a self-estimate.

Evidence: Independent context_window contract verification against Claude Code 2.1.219 binary

=== Independent re-verification of the statusLine context_window contract ===
$ ls -l /home/shane/.local/share/claude/versions/2.1.219  (installed Claude Code 2.1.219 bundle)
-rwxr-xr-x 1 shane shane 275004400 Jul 24 13:14 /home/shane/.local/share/claude/versions/2.1.219

$ strings occurrences of the four payload fields inside the bundle:
  context_window         21
  remaining_percentage   4
  used_percentage        11
  total_tokens           33
  current_usage          3

$ context snippet showing the context_window object construction:
$ payload-consumption snippets embedded in the bundle (Claude Code's own statusline examples):
context_window.remaining_percentage // empty'); [ -n "$remaining" ] && echo "Context: $remaining% remaining"
context_window.used_percentage // empty'); [ -n "$used" ] && echo "Context: $used% used"

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

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

• ℹ️ bin/fm-context-statusline.sh:53 - In clearStaleRecord, the catch branch if (error.code !== "ENOENT") return; is a no-op: both the ENOENT and non-ENOENT paths fall out of the function identically since nothing follows the if. It reads as if a non-ENOENT unlink failure is handled differently when it isn't. Simplify to an empty catch (or a comment) so the intent — best-effort unlink — is explicit.
• ℹ️ bin/fm-context-statusline.sh:85 - The trigger's availability is coupled to current_usage (line 85) even though only used_percentage/remaining_percentage drive the display and the 70% advisory. If a future Claude Code release renames or drops that unused-for-display field, the entire telemetry line and compaction trigger silently go dark fleet-wide, and briefs forbid workers from falling back to self-estimates. The docs state this fail-dark contract deliberately and it was verified against 2.1.219, so this may be intentional — but confirm whether the display/trigger should degrade gracefully when only the two percentages are present, keeping the snapshot strict.
• ℹ️ bin/fm-context-statusline.sh:92 - The snapshot writer mkdirSync-recreates the predictable world-readable path /tmp/fm-<id> and writes a temp file with a guessable name (.context-pressure.json.<pid>.tmp) via fs.writeFileSync, which follows symlinks. On a multi-user host, a local attacker who pre-creates /tmp/fm-<id> could plant a symlink at the temp path to make the user clobber an arbitrary file. This matches the repo's existing /tmp/fm-<id> convention (fm-spawn's gotmp) and content is non-sensitive telemetry written 0600, so it does not worsen the established threat model — noting the tradeoff only.

🔧 Fix: require only trigger percentages, name missing optional telemetry fields
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• bin/fm-test-run.sh tests/fm-context-statusline.test.sh tests/fm-brief.test.sh — all 27 behavior tests pass, including exact-70% trigger, truncation, snapshot resilience, and per-agent-kind brief contract
• bin/fm-test-run.sh tests/fm-spawn-dispatch-profile.test.sh tests/fm-subagent-pretool-check.test.sh — all pass, including the new assertion that a spawned Claude worker's git-excluded settings.local.json wires fm-context-statusline.sh with a task-scoped --record path
• Manual E2E: piped realistic Claude Code statusLine payloads (42.3%, 69.99%, 72.4% used, and a malformed self-estimate shape) through the tracked .claude/settings.json command, verifying the CTX display line, the /compact advisory firing at ≥70%, the recorded context-pressure.json snapshot with compact_recommended=true, and silent stale-snapshot cleanup on invalid input
• Manual E2E: generated a ship brief and a secondmate charter via bin/fm-brief.sh and extracted the worker-facing '# Context pressure' section and CTX-row compaction instruction
• Read-only re-verification of the context_window payload contract by grepping the installed Claude Code 2.1.219 binary for all four documented fields and its embedded statusline usage examples

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[kunchenguid]

Automated reminder: thanks for the PR! This branch currently has a merge conflict with the base branch.

When you get a chance, please rebase onto (or merge) the latest base branch, resolve the conflict, and push. After that, checks will re-run and the PR will get looked at again.

_{Noted for firstmate#1270 at 2360e785.}

[kunchenguid]

Automated reminder: thanks for the PR! This branch currently has a merge conflict with the base branch.

When you get a chance, please rebase onto (or merge) the latest base branch, resolve the conflict, and push. After that, checks will re-run and the PR will get looked at again.

_{Noted for firstmate#1270 at 0435c09d.}