fix: preserve fleet state in truncated session-start digests

[kunchenguid]

Intent

Promote a digest-composition investigation's recommendations (its sections 5.1-5.3) into one coherent ship in bin/fm-session-start.sh, the firstmate session-start digest. Captain authorized. This is firstmate shared, tracked material, so firstmate-coding-guidelines applies: one-owner rule for contracts, colocated tests in tests/ that exercise behavior through the executable interface rather than implementation source text, one sentence per line in Markdown, plain dash never em dash, no agent co-author, and shellcheck-clean via bin/fm-lint.sh.

Motivating evidence from the investigation: the digest is delivered through a harness that truncates an oversized payload from the TAIL. A measured 70KB digest was really delivered as lines 1-435 of 578, cutting off eight lines before the live-task inventory, so that session took the helm without ever seeing which tasks were live or where their endpoints were. The CONTEXT block (five curated memory files) was 50.4% of the digest and sat in front of the recovery-critical fleet state.

Three required changes:

1. REORDER (highest value; a safety change, zero bytes saved). Emit the FLEET STATE section BEFORE the bulky CONTEXT memory files, so tail truncation drops recoverable curated memory instead of recovery-critical live fleet identity (live-task inventory, window/worktree/backend/endpoint-liveness). Use the existing SESSION_START_STAGES ordering contract. Explicitly do NOT reorder the LOCK/BOOTSTRAP/WAKE-QUEUE safety preamble. Move or duplicate the NEXT STEP read-once contract near the top so it too survives truncation.

2. CAP STATUS-TAIL LINE LENGTH. print_status_tail had no per-line bound; an observed status line ran 865 characters. Cap each tail line at 220 reusing the OPEN DECISIONS cap shape already in bin/fm-wake-drain.sh (a ' [truncated]' marker). This is safe because the section already prints each task's full status log path for targeted follow-up, and AGENTS.md section 8 already treats a status line as a wake event rather than current state (bin/fm-crew-state.sh owns current state).

3. BACKLOG LISTING. Drop done rows at startup (tasks-axi supports --state; retained completion history is a reporting surface, not a recovery input). ALWAYS keep every in_flight and held row with its hold_kind/hold_reason. Bound the plain queued listing, preferring the ready set plus all held/blocked rows in full plus an accurate '(N more queued)' remainder counter. Never silently truncate blocked or held items.

Scope boundaries the captain set: this is complementary to, and must NOT duplicate, a separate already-merged full-read safety-net change. It does NOT touch AGENTS.md. It must not change the startup memory budget scope or its estimator (separately deferred).

Required tests: colocated tests for the reorder ordering (FLEET STATE precedes CONTEXT, safety preamble unchanged), the status-tail per-line cap, and the backlog-state filtering (done dropped, in_flight/held always kept in full, queued bounded with an accurate '(N more)' counter), exercising real script output rather than source text.

Decisions and tradeoffs I made while implementing, which a reviewer reading only the diff would not know:

• I chose the section order LOCK, BOOTSTRAP, WAKE QUEUE, SUPERVISION, READ-ONCE CONTRACT, FLEET STATE, CONTEXT, NEXT STEP. Supervision stays between the wake queue and context exactly as AGENTS.md section 3 already states in prose.
• I MOVED the read-once contract rather than duplicating it, because the one-owner rule forbids two copies of the same contract. Because it now precedes the payload it governs, I added the condition that voids it: a STARTUP TRUNCATED banner naming a stage that never ran. The closing NEXT STEP reminder now points back at it instead of restating it.
• I added a new stage name 'read-once' to SESSION_START_STAGES so the truncation banner still names exactly which stages never ran; the existing banner test was updated for the new order.
• I did NOT reorder content WITHIN the FLEET STATE section (backlog listing still precedes the work-under-way inventory). AGENTS.md section 3 item 5 enumerates that internal order and AGENTS.md is out of scope; change 3 shrinks the backlog listing enough that the intra-section risk is much reduced. This was a deliberate scope decision, not an oversight.
• For the 220 cap I extracted the cut and its marker into a new shared owner, bin/fm-line-cap-lib.sh, and refactored bin/fm-wake-drain.sh's OPEN DECISIONS section onto it, rather than copying the logic into a second place. fm-wake-drain.sh keeps its own composite policy (the 4000-byte global cap and its 'N more omitted' disclosure); the lib owns only the per-line cut. The drain passes a per-item allowance one short of the cap because its global budget also charges for the trailing newline, preserving its existing byte math exactly. The lib exposes an assigning form (fm_cap_line_var) and a printing form (fm_cap_line) built on it, one rule with two call shapes, so the drain - which runs at the top of every wake-handling turn - pays no command substitution per item.
• The cap counts characters rather than bytes. Status lines are plain ASCII in practice so the two coincide, and character semantics can never cut a multibyte character in half into an invalid sequence. This matches the existing OPEN DECISIONS shape it reuses.
• I added a regression test for the OPEN DECISIONS per-item cap, which previously had none, since I refactored that code path.
• For the backlog I composed four tasks-axi group filters (--state in_flight, --state held, --state queued --blocked, and tasks-axi ready) rather than post-processing one listing, so this script never reimplements task state. The groups can overlap: an in-flight item that is also held appears in both, which I disclose in the group label. Only the ready group is bounded, so the remainder counter is exact.
• I renamed FM_SESSION_START_BACKLOG_LIMIT to FM_SESSION_START_QUEUED_LIMIT and changed its default from 80 to 20. This is deliberate: the knob's meaning genuinely changed (it no longer bounds the whole listing, and bounding the whole listing was unsafe because it could drop a held or blocked row), so keeping the old name would have been misleading. The old name is referenced nowhere else in the repo. docs/configuration.md's env inventory records the new knob.
• The manual (non-tasks-axi) backend path got the same rules: done rows dropped, every in-flight title line kept, every queued title line whose own text carries a hold or blocked-by marker kept, the rest bounded with an exact remainder. Its keep-pattern uses bracket expressions rather than backslashes because awk's -v applies escape processing before the regex is compiled.
• I dropped tasks-axi's per-group help block from each of the four composed listings. Keeping them would have repeated the same two pointers four times, each carrying this home's full backlog path, giving back much of the saving; the section already prints one equivalent pointer of its own.
• I tightened one pre-existing assertion that checked for the bare string 'STARTUP TRUNCATED', because the read-once contract now legitimately names that banner as the condition that voids it; the test now pins the actual banner line.

Verification performed: bin/fm-lint.sh clean, bin/fm-doc-audience-check.sh clean, bin/fm-test-run.sh --check-coverage clean, and bin/fm-test-run.sh --changed ran 63 test scripts with zero failures. I also ran the real digest end to end against a throwaway home with the real tasks-axi installed to inspect the rendered output.

What Changed

• Move the read-once contract and FLEET STATE ahead of bulky CONTEXT content while preserving the lock, bootstrap, and wake-queue safety preamble.
• Add a shared 220-character line cap with a [truncated] marker for session status tails and wake-drain open decisions.
• Omit completed backlog rows, retain all in-flight, held, and blocked rows, and bound ready queued rows with an exact remainder count and documented configuration.

Risk Assessment

✅ Low: The change is well-bounded, conforms to the stated digest ordering and truncation requirements, preserves existing wake-drain byte accounting, and adds behavioral coverage through executable output.

Testing

The author-reported baseline had already covered lint, documentation checks, coverage registration, and 63 changed test scripts; this phase reran the focused session-start and shared OPEN DECISIONS behavior suites and captured an actual CLI digest proving the safety preamble remains first, FLEET STATE precedes CONTEXT, the long status event is capped at 220 characters with its recovery path retained, done work is absent, held/blocked/in-flight work remains visible, and seven ready items bounded to three disclose an exact four-item remainder.

Evidence: End-to-end session-start digest

Actual CLI digest shows LOCK -> BOOTSTRAP -> WAKE QUEUE -> SUPERVISION -> READ-ONCE CONTRACT -> FLEET STATE -> CONTEXT -> NEXT STEP. It retains in-flight, held, and blocked rows, shows 3 of 7 ready rows with “(4 more queued)”, omits done rows, and caps the long status line at exactly 220 characters with “ [truncated]”.

================================================================================
SESSION START - /var/folders/0k/bf8mwt2n5qddzk24r20gfk0c0000gn/T//fm-session-start-tests.gz4N0P/reviewer-evidence/home
================================================================================

LOCK
--------------------------------------------------------------------------------
lock acquired: harness pid 66699

BOOTSTRAP
--------------------------------------------------------------------------------
MISSING: quota-axi (install: npm install -g quota-axi)

WAKE QUEUE
--------------------------------------------------------------------------------
OPEN DECISIONS (still open, folded from the durable status logs - not just the latest line):
evidence-task needs-decision: [key=visual-proof] a very long status event padding padding padding padding padding padding padding padding padding padding padding padding padding padding padding padding paddi [truncated]
●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
●  WATCHER DOWN - SUPERVISION IS OFF
●  1 task(s) in flight, but no watcher has a fresh beacon (last beat: never, grace 300s).
●  Trust the emitted supervision protocol for this harness; do not use shell & for watcher repair.
●  This is a supervision warning only; the guarded operation WILL still run.
●  watcher supervision needs Stop-owned automatic recovery; inspect the hook registration and startup status before ending the turn.
●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
================================================================================
SUPERVISION OPERATING INSTRUCTIONS - primary harness: claude
================================================================================
Current state:
- Lock: held by this session; this session owns normal supervision unless away mode says otherwise.
- Away mode: inactive.
- X mode: inactive; use the default watcher cadence.
- Ordinary wake: the Stop-owned auto-arm (bin/fm-claude-stop-autoarm.sh) already owns watcher continuity; drain and handle the wake, and do not arm another cycle yourself.

Mode: Claude Stop-hook-owned supervision.

When this session owns supervision and away mode is not active:
1. Drain first with `bin/fm-wake-drain.sh`.
2. Routine watcher arm and re-arm are owned by the Stop `asyncRewake` hook (`bin/fm-claude-stop-autoarm.sh`), never by you.
   Every turn end while supervision is needed launches or attaches one home-scoped watcher cycle with no model command and no model tokens.
   An actionable close wakes you through the hook's exit-2 rewake, delivered as a `Stop hook feedback` message.
3. On a `Stop hook feedback` wake (`signal:`, `stale:`, `check:`, or `heartbeat`), run `bin/fm-wake-drain.sh` first and handle the wake.
   Do not run `bin/fm-watch-arm.sh` after an ordinary wake; the next turn end re-arms automatically when supervision is still needed.
   Do not invent a wake from an attach-status line alone; drain and act only on real wake records, the drain's `OPEN DECISIONS` entries, or a real watcher reason line.
4. On the one `Stop hook feedback` automatic-mechanism failure notice (`firstmate watcher auto-arm FAILED ...`), drain, inspect the automatic mechanism failure, and do not turn the notice into a repeating manual-arm loop.
5. If the Stop hook does not claim the home or reports an exhausted failure, inspect its registration and watcher startup path before ending blind.
   Keep the Stop-owned automatic mechanism as the only Claude arm owner.
6. Treat `watcher: started ...` and `watcher: attached ...` inside automatic arm output as proof that one live cycle exists.
   On attach, the arm follows verified identity-matched successors instead of exiting when the first cycle ends.
7. The durable wake queue preserves actionable events between a rewake and the next Stop-launched arm, while the bounded turn-end guard prevents a blind Stop when recovery did not start.
   No PreToolUse hook denies fleet commands based on watcher status.
   [`watcher-continuity.md`](../watcher-continuity.md) owns the exact session-lock recovery boundary.
8. The turn-end guard (`bin/fm-turnend-guard.sh --claude`) remains the final backstop.
   It requires the PID-strict live-watcher and fresh-beacon predicate at the Stop boundary, while the mid-turn pull guard accepts a fresh beacon without a live process under Claude's between-turns auto-arm model.
   It allows the stop when a watcher is healthy or the role-verified auto-arm owns recovery, while fresh failure epochs advance the bounded one-time attended fail-open progression described in [`turnend-guard.md`](../turnend-guard.md).
9. Waiting on the hook-owned cycle is silent: do not send idle progress while the watcher is parked.

The watcher itself remains `bin/fm-watch.sh`, and `bin/fm-watch-arm.sh` remains the verified arm wrapper that the Stop hook foregrounds.
Re-arm attaches to an existing healthy cycle when one is already present and follows its verified successor chain.
See [`watcher-continuity.md`](../watcher-continuity.md) for the arm-layer successor and clean-close failure contract and the Claude ownership model.


================================================================================
READ-ONCE CONTRACT
================================================================================
Everything below is printed in full for this session start: every state/*.meta,
a compact data/backlog.md listing, a bounded tail of every state/*.status,
data/projects.md, data/secondmates.md, data/captain.md, data/captain-shared.md,
and data/learnings.md.
Do NOT re-read any of them after reading this digest, and do NOT bulk-read
data/backlog.md or state/*.status: re-reading everything defeats the entire
point of this command.

Go to a source directly only when:
  - this digest flagged it ABSENT (then rebuild or create it per AGENTS.md),
  - its contents looked unparseable or corrupt,
  - an individual full status log is needed for older wake-event history, or a
    status line was capped and its tail matters (each task's full log path is
    printed with its tail),
  - a full task body is needed (tasks-axi show <id> --full, or data/backlog.md),
  - the backlog listing disclosed omitted queued items and this turn needs them,
  - or a STARTUP TRUNCATED banner named the stage that would have printed it, in
    which case that stage's sources were never emitted and must be reconciled.

================================================================================
FLEET STATE
================================================================================

data/backlog.md
--------------------------------------------------------------------------------
compact backlog listing (tasks-axi; done rows omitted; every in-flight, held, and blocked row shown in full; ready queued bounded to 3; task bodies omitted)

in flight:
count: 1
tasks[1]{id,state,kind,repo,title,blocked_by,hold_kind,hold_reason}:
  compact-startup,in_flight,ship,firstmate,Compact startup digest,none,captain,captain choice pending

held (captain- or time-gated; an in-flight item that is also held appears in both groups):
count: 1
tasks[1]{id,state,kind,repo,title,blocked_by,hold_kind,hold_reason}:
  held-queued,queued,ship,firstmate,Held queued work,none,captain,captain choice pending

blocked queued:
count: 1
tasks[1]{id,state,kind,repo,title,blocked_by,hold_kind,hold_reason}:
  blocked-followup,queued,scout,firstmate,Follow compact startup,compact-startup,"-","-"

ready queued (dispatchable now):
count: 7
ready[7]{id,state,kind,repo,title}:
  ready-1,queued,ship,firstmate,Ready item 1
  ready-2,queued,ship,firstmate,Ready item 2
  ready-3,queued,ship,firstmate,Ready item 3
ready_public_followups: 0 delivery-ready obligations
(shown 3 of 7 ready queued item(s))
(4 more queued - tasks-axi ready --file /var/folders/0k/bf8mwt2n5qddzk24r20gfk0c0000gn/T//fm-session-start-tests.gz4N0P/reviewer-evidence/home/data/backlog.md)
Full task bodies remain available on demand: tasks-axi show <id> --full when compatible tasks-axi is available, or data/backlog.md.

Work under way (state/*.meta)
--------------------------------------------------------------------------------

--- evidence-task ---
window=fm-evidence:live
worktree=/var/folders/0k/bf8mwt2n5qddzk24r20gfk0c0000gn/T//fm-session-start-tests.gz4N0P/reviewer-evidence/root
backend=codex
kind=ship
endpoint: dead (backend=codex window=fm-evidence:live)
status tail (last 5 line(s), each capped at 220 characters, wake-EVENT history, not current state; full log: /var/folders/0k/bf8mwt2n5qddzk24r20gfk0c0000gn/T//fm-session-start-tests.gz4N0P/reviewer-evidence/home/state/evidence-task.status):
needs-decision: [key=visual-proof] a very long status event padding padding padding padding padding padding padding padding padding padding padding padding padding padding padding padding padding padding padd [truncated]
working: short status event remains whole

Orphan status logs (state/*.status without matching .meta)
--------------------------------------------------------------------------------
(none)

AFK
--------------------------------------------------------------------------------
absent

================================================================================
CONTEXT
================================================================================

data/projects.md
--------------------------------------------------------------------------------
ABSENT

data/secondmates.md
--------------------------------------------------------------------------------
ABSENT

data/captain.md
--------------------------------------------------------------------------------
ABSENT

data/captain-shared.md (shared, main-authoritative, read-only in secondmate homes)
--------------------------------------------------------------------------------
ABSENT

data/learnings.md
--------------------------------------------------------------------------------
ABSENT

================================================================================
NEXT STEP
================================================================================
Follow the supervision operating instructions block above for harness 'claude'.
This script never starts supervision itself.

The digest above is complete for this session start. The READ-ONCE CONTRACT
section near the top of it governs what may still be read from disk.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-session-start.test.sh
• bash tests/fm-wake-drain-open-decisions.test.sh
• Ran bin/fm-session-start.sh end-to-end through the test fixture with FM_SESSION_START_QUEUED_LIMIT=3, seven ready tasks, held/blocked/in-flight tasks, a done task, and an overlong status line; captured the complete emitted digest.
• Inspected the captured section positions and backlog rows with rg; verified the emitted capped status line length with awk and confirmed the working tree remained clean.

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.