feat(bin): opt-in idle-worker pre-cache-expiry compaction (config/idle-compact)

[NewAiCoder]

Motivation

On a subscription-billed Claude account the prompt cache has a one-hour TTL. A crewmate that has been idle for longer than that (parked at a gate, waiting on an owner decision, done and awaiting merge) reprocesses its entire context uncached on the next steer, which is real quota burn - and on a busy fleet those revivals add up to a large share of the daily budget.

Proposal: opt-in idle-worker pre-cache-expiry compaction

An opt-in housekeeping pass that compacts a genuinely idle Claude crewmate while its cache is still warm, so a later revival is cheap. Ships inert exactly like Relay: an absent, gitignored config/idle-compact means no behavior change anywhere. When present, its first non-empty line is the idle threshold in whole minutes (recommended 30); an empty-but-present file enables the documented default; a malformed value behaves like an absent file so a typo can never fail the watcher loop.

Shared owner bin/fm-idle-compact.sh, called from both bin/fm-watch.sh's main loop and bin/fm-supervise-daemon.sh's housekeeping tick on their existing cadence (one classifier, two callers - the same shape as fm-classify-lib.sh).

Eligibility is the strict intersection of:

• kind != secondmate and harness is claude (the only harness with a verified /compact today);
• bin/fm-crew-state.sh's reconciled state is parked, done, blocked, or paused - never working;
• the task's last activity of any kind (meta, status log, turn-ended marker, pane-activity stamp) is at least the threshold old;
• a live safety gate immediately before typing: fm_busy_classify reports an exact idle verdict and the composer reads affirmatively empty; a busy pane, an unproven verdict, or a non-empty composer defers to the next sweep.

A durable per-task marker (state/.idle-compact-<task>) drives a 4-phase state machine so one idle episode produces at most one compaction:

1. eligible -> guarded message asking the crewmate to write its open decision keys, current gate/step, next actions, and key file paths to data/<id>/precompact-notes.md (survives teardown);
2. notes present -> send /compact;
3. after the compaction -> steer the crewmate to re-read its notes;
4. the marker doubles as the activity stamp the next idle window is measured from, so a compacted worker is not re-compacted until it has been active again.

Everything is verified by the existing daemon test shard plus a new tests/fm-daemon.test.sh case; docs in docs/configuration.md ("Idle-worker pre-compaction"), docs/architecture.md, docs/scripts.md, and docs/verification/runtime-backends.md.

Relationship to #2341

#2341 standardizes durable pre-compaction task notes as part of the worker brief contract. This proposal is the trigger side: it produces exactly that note before compacting and re-reads it afterward, so the two compose - #2341's note format could become the file this pass asks for.

Reference implementation

A working implementation on top of main (single commit, ~860 lines incl. tests and docs) is at https://github.com/NewAiCoder/firstmate/tree/keep/idle-compact-eec826e - happy to rebase it onto current main and open a PR if the shape is welcome, or to adapt it to whatever contract you prefer.

[kunchenguid]

Speaking as Kun's firstmate:

Opt-in idle-worker pre-cache-expiry compaction via absent-means-off config/idle-compact (threshold minutes when present). Unconfigured homes stay unchanged. Eligibility is parked/done/blocked/paused Claude only, with a live idle+empty-composer gate and a one-compaction-per-idle-episode marker. Aligns with token efficiency and explicit authority; composes with #2341's durable precompact notes rather than replacing them.

VISION (per rule):

• One captain, one interface — aligns. Housekeeping stays below deck; captain sees cheaper revivals, not new noise.
• Authority is explicit — aligns. Absent gitignored config means no behavior; enable is an explicit grant.
• Scripts own the mechanics — aligns. Shared bin/fm-idle-compact.sh classifier with two existing callers.
• A restart is a non-event — aligns. Durable per-task marker and data/<id>/precompact-notes.md survive teardown.
• Delegation with a spine — aligns. Does not invent a new task shape; composes with existing crew-state and busy classify.
• The fleet outlives any vendor — mixed/aligns. Scoped to Claude's verified /compact today; other harnesses stay untouched until verified.
• Scope — aligns. Command-layer housekeeping, not workshop merge policy.

Contract-class: opt-in.

Not on latest main (no idle-compact owner). No covering open PR in this pass. Leave for a contributor PR; do not open a competing one.

[tiago-peixoto]

A Codex-specific data point for any future extension beyond this proposal's Claude-only scope: across 31,138 requests over September 4–5, 94 (0.30%) met a cache-miss heuristic—context had not shrunk, yet less than half the estimated reusable prefix was billed as cached input.

Those events account for an estimated 10.4M additional fresh tokens, or about 2.0% of the sample's token cost under published per-model credit rates. This does not identify cache expiry as the cause or demonstrate that pre-expiry compaction would recover that cost; it also says nothing about Claude's TTL or savings.

In the same Codex workload, lowering the compaction ceiling to 120–150k projected a 22–32% cost reduction, with continuity and rework still unmeasured. The methodology and limitations are in this evidence comment. These are distinct mechanisms to measure separately.

[kunchenguid]

Speaking as Kun's firstmate:

Restamp after newer activity (tiago-peixoto Codex cache-miss commentary 2026-09-05T19:37:21Z — data point for a possible future harness extension; not a PR and not a contract change).

Still opt-in as previously stamped: absent-means-off config/idle-compact; Claude-only verified /compact; parked/done/blocked/paused + live idle/empty-composer gate; one compaction per idle episode; composes with #2341 notes.

VISION.md (each rule)

• One captain, one interface — aligns. Housekeeping below deck; captain sees cheaper revivals, not new noise.
• Authority is explicit — aligns. Absent gitignored config means no behavior; enable is an explicit grant.
• Scripts own the mechanics — aligns. Shared classifier script with existing daemon callers; token efficiency is first-class.
• A restart is a non-event — aligns. Durable per-task marker and data/<id>/precompact-notes.md survive teardown.
• Delegation with a spine — aligns. No new task shape; composes with crew-state / busy classify / Standardize durable pre-compaction and cross-harness task notes #2341.
• The fleet outlives any vendor — mixed/aligns. Scoped to Claude's verified /compact today; other harnesses untouched until verified (Codex commentary is out-of-scope for this issue's contract).
• Scope — aligns. Command-layer housekeeping, not workshop merge policy.

Contract-class: opt-in.

Still absent on latest main d6660d75d0fc (no bin/fm-idle-compact.sh / config/idle-compact / idle-compact tree entries). No covering open PR for this feature in this pass (compact-named PRs are unrelated: Pi footer, autocompact Codex, stow nudge, etc.). Leave ready-for-pr; do not open a competing triage PR. Not a merge vote. Captain-flag: no.

[NewAiCoder-bot]

Filed from the reporter's secondary account because the primary one (NewAiCoder, reporter of #3517 and #3336) is rate-limited today; same person, not automation.

Follow-up from running this in production for a week: one seam that bit twice overnight and is fixed in the fork.

fm_idle_compact_declared_paused required the status log's latest line to EQUAL the phrase paused: awaiting compaction before validation. The same ship brief asks the worker to note its measured lane size, so the line that actually lands carries trailing detail ("... (commit abc, 1292 changed lines, over-cap accepted)"). The equality test misses it, the sweep runs the ORDINARY save-then-compact path, which never sets declared=1 and has no ring, and the episode lands at phase=done with the worker waiting 35 to 60 minutes until a human rings it. Secondary seam: even on the declared path the ring was gated behind the live-typing safety gate, which a durable inbox record does not need, so a busy pane deferred it indefinitely.

Fix: match the declared phrase as a word-boundary PREFIX of the status line, send the ring as a durable inbox record without the live-typing gate, and log the ring backstop to a size-capped .idle-compact.log. Reference: https://github.com/NewAiCoder/firstmate/pull/15

[kunchenguid]

Speaking as Kun's firstmate:

Restamp after newer activity (NewAiCoder-bot 2026-09-07T14:34:25Z — production seam on the reference fork: declared-pause phrase must match as a word-boundary prefix, and the ring should be a durable inbox record rather than gated on the live-typing safety gate. Not an upstream PR and not a contract change. Fork note: https://github.com/NewAiCoder/firstmate/pull/15 — that is not an open PR on this repo.)

Still opt-in as previously stamped: absent-means-off config/idle-compact; Claude-only verified /compact; parked/done/blocked/paused + live idle/empty-composer gate; one compaction per idle episode; composes with #2341 notes. The fork seam is a refinement of that same opt-in owner, not a default-on path.

VISION.md (each rule)

• One captain, one interface — aligns. Housekeeping stays below deck; captain sees cheaper revivals, not new noise.
• Authority is explicit and never inferred — aligns. Absent gitignored config means no behavior; enable is an explicit grant.
• Scripts own the mechanics, agents own the judgment — aligns. Shared classifier script with existing daemon callers; token efficiency is first-class. The prefix/ring seam is still exact script logic.
• A restart is a non-event — aligns. Durable per-task marker and data/<id>/precompact-notes.md survive teardown. A durable inbox ring is the same idea.
• Delegation with a spine — aligns. No new task shape; composes with crew-state / busy classify / Standardize durable pre-compaction and cross-harness task notes #2341.
• The fleet outlives any vendor — aligns. Scoped to Claude's verified /compact today; other harnesses untouched until verified. The Codex cache-miss comment earlier stays out of this issue's contract.
• Scope — aligns. Command-layer housekeeping, not workshop merge policy.

Contract-class: opt-in.

Still absent on latest main 72bfdd00a9757a2c43264e0caa9570ef9853f9a9 (bin/fm-idle-compact.sh 404; no idle-compact tree hits). No covering open PR on this repo. Leave ready-for-pr; do not open a competing triage PR. Not a merge vote. Captain-flag: no.

[NewAiCoder-bot]

Opened #3988

[kunchenguid]

Speaking as Kun's firstmate:

Restamp after newer activity (NewAiCoder-bot 2026-09-08T10:58:12Z — opened #3988). why=newer-activity.

Still opt-in as previously stamped: absent-means-off config/idle-compact; Claude-only verified /compact; parked/done/blocked/paused + live idle/empty-composer gate; one compaction per idle episode; composes with #2341 notes. Fork seam notes (prefix match / durable inbox ring) remain refinements of that same opt-in owner.

VISION.md (each rule)

• One captain, one interface — aligns. Housekeeping below deck; cheaper revivals, not new captain noise.
• Authority is explicit — aligns. Absent gitignored config means no behavior; enable is an explicit grant.
• Scripts own the mechanics — aligns. Shared bin/fm-idle-compact.sh with existing daemon callers; token efficiency first-class.
• A restart is a non-event — aligns. Durable per-task marker and data/<id>/precompact-notes.md survive teardown.
• Delegation with a spine — aligns. No new task shape; composes with crew-state / busy classify / Standardize durable pre-compaction and cross-harness task notes #2341.
• The fleet outlives any vendor — aligns. Scoped to Claude's verified /compact today; other harnesses untouched until verified.
• Scope — aligns. Command-layer housekeeping, not workshop merge policy.

Contract-class: opt-in.

Still absent on tip main b84e0e362fac (bin/fm-idle-compact.sh 404). Covering open PR: #3988 (NewAiCoder-bot / same reporter). Brief CI note only (not triaging that PR here): Lint FAIL + Greptile fail; behavior shards largely pass; NM raise check pass. Stamp existing-pr → #3988; remove ready-for-pr (no longer unhelped). Do not open a competing triage PR. Captain-flag: no. Security FYI: none.

[devin-ai-integration]