session-orchestrator 4.1.0 → 5.0.0

package/scripts/lib/session-end/tail-runner.mjs

@@ -0,0 +1,178 @@
+/**
+ * session-end/tail-runner.mjs — the APPLY half of the Phase 3.6.x tail.
+ *
+ * `phase-skip.mjs` decides WHICH tail phases should run and is side-effect-free
+ * by contract. Until now nothing was the other half for 3.6.4: the
+ * Expired-Learnings Sweep was coordinator PROSE, so the dry-run decision was
+ * computed on every close and the apply path was never mechanically reached.
+ * Census (2026-09-09, `rg -n sweepExpiredLearnings scripts/ hooks/ skills/
+ * tests/`): the only call sites were the definition itself, the `dryRun: true`
+ * probe in `phase-skip.mjs`, the standalone CLI, and tests — no session-end
+ * caller applied anything. Measured consequence across three consumer repos:
+ * 0 sweeps ever applied, 628 learnings resident in the active stores.
+ *
+ * This module closes that gap and nothing else. It is deliberately NOT a
+ * general tail executor:
+ *
+ *   - **3.6.3 Memory-Proposals** — AUQ-gated (the operator approves each
+ *     proposal before it is written); `.claude/rules/ask-via-tool.md` AUQ-004
+ *     puts the tool out of reach of anything but the coordinator thread.
+ *   - **3.6.5 Auto-Dream** and **3.6.7 Auto-Dialectic** — both NUDGES that end
+ *     in a subagent dispatch (memory-cleanup, `dialectic-deriver`); a library
+ *     function cannot dispatch an agent.
+ *   - **3.6.6 Skill-Judge** — needs a live LLM dispatch for the judgement.
+ *   - **3.6.8 Reconcile** — the write is operator-approved per proposal (AUQ),
+ *     which is the whole never-always-on firewall of Epic #693.
+ *
+ * So {@link runTailPhases} exists as the SEAM (one dispatch table, one result
+ * shape) rather than as an abstraction over six phases that will never all be
+ * mechanical. A future phase that becomes mechanical is added here; the five
+ * above stay coordinator-executed by design, not by omission.
+ *
+ * Never-throws contract, and its DIRECTION is the opposite of `phase-skip.mjs`.
+ * The planner fails OPEN (probe error → run the phase, because losing a phase
+ * silently is worse than running it needlessly). A runner that writes to disk
+ * must fail CLOSED: any error yields `{ran: false, reason: 'error'}` and the
+ * close proceeds. Session close is the one thing that must never be blocked by
+ * a best-effort maintenance sweep — a store that stays unswept for one more
+ * session costs nothing; a close that aborts loses the session record.
+ *
+ * Plain Node ESM, no external deps.
+ *
+ * @typedef {Object} SweepResult
+ * @property {boolean} ran            - true only when the store was actually rewritten.
+ * @property {string}  [reason]       - why it did not run ('plan-skip' | 'no-plan' | 'error').
+ * @property {string}  [error]        - error message, `reason === 'error'` only.
+ * @property {number}  [scanned]      - entries read from the active store (ran only).
+ * @property {number}  [archived]     - entries moved to the archive sidecar (ran only).
+ * @property {string}  [archivePath]  - the archive sidecar written to (ran only).
+ */
+
+import { sweepExpiredLearnings } from '../learnings/expiry-sweep.mjs';
+import { resolveLearningsPaths } from './phase-skip.mjs';
+
+/** Event name — a plain string literal so the events-schema census can see it. */
+const SWEEP_EVENT = 'orchestrator.learnings.sweep_applied';
+
+/** Payload marker for the producer, so the ledger separates it from the CLI. */
+const SWEEP_SOURCE = 'session-end-3.6.4';
+
+/**
+ * Pull the decision for one phase id out of a `planTailPhases()` result.
+ *
+ * Accepts three shapes so callers need no adapter: the full
+ * `{plan, skippedReport}` envelope, a bare `PhaseDecision[]`, or a single
+ * `PhaseDecision` object. Anything else → `null` (treated as "no plan").
+ *
+ * @param {object|Array|undefined} plan
+ * @param {string} phase
+ * @returns {object|null}
+ */
+function findPhaseDecision(plan, phase) {
+  if (!plan) return null;
+  const list = Array.isArray(plan) ? plan : Array.isArray(plan.plan) ? plan.plan : null;
+  if (list) return list.find((d) => d && d.phase === phase) ?? null;
+  return plan.phase === phase ? plan : null;
+}
+
+/**
+ * Emit the one sweep record. Best-effort by construction: a telemetry failure
+ * never changes the caller's return value.
+ *
+ * The shape (lazy `events.mjs` import, explicit `repoRoot`, silent catch) is
+ * copied from `_emitEvaluated` in `scripts/lib/express-path.mjs`. Both halves
+ * are load-bearing: the lazy import keeps `platform.mjs`'s load-time filesystem
+ * walk-up out of the static graph of a module the planner imports, and the
+ * refusal to emit WITHOUT an explicit `repoRoot` prevents the `SO_PROJECT_DIR`
+ * fallback from writing a synthetic record into whatever tree the ambient env
+ * happens to resolve to (#941 — that mistake once landed a test record in the
+ * operator's real fleet ledger).
+ *
+ * @param {{repoRoot: string, scanned: number, archived: number}} ctx
+ * @returns {Promise<void>}
+ */
+async function emitSweepApplied({ repoRoot, scanned, archived }) {
+  if (typeof repoRoot !== 'string' || repoRoot.trim() === '') {
+    process.stderr.write(
+      `tail-runner: skipped ${SWEEP_EVENT} — no repoRoot given; ` +
+        'refusing the ambient SO_PROJECT_DIR destination (#941).\n',
+    );
+    return;
+  }
+  try {
+    const { emitEvent, sessionAttribution } = await import('../events.mjs');
+    await emitEvent(
+      SWEEP_EVENT,
+      { scanned, archived, source: SWEEP_SOURCE, ...sessionAttribution(repoRoot) },
+      { repoRoot },
+    );
+  } catch {
+    // Best-effort telemetry — the sweep already happened and its result is
+    // authoritative whether or not the ledger accepted the record.
+  }
+}
+
+/**
+ * Phase 3.6.4 — apply the Expired-Learnings Sweep the planner decided on.
+ *
+ * Runs ONLY when the plan's 3.6.4 decision says `run === true`. Any other
+ * shape (skip decision, phase absent, no plan at all) returns without touching
+ * disk — the planner owns the decision, this function owns the write, and a
+ * runner that re-derives the decision would be free to disagree with it.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot            Absolute repo root.
+ * @param {object|Array} [args.plan]        `planTailPhases()` result, its `plan`
+ *                                          array, or the bare 3.6.4 decision.
+ * @param {Date|number} [args.now]          Injectable clock (grace-window maths).
+ * @param {number} [args.graceDays]         Override the 14-day grace window.
+ * @param {boolean} [args.emit=true]        Set false to suppress the ledger record.
+ * @returns {Promise<SweepResult>}          Never throws.
+ */
+export async function runExpiredSweep({ repoRoot, plan, now, graceDays, emit = true } = {}) {
+  try {
+    const decision = findPhaseDecision(plan, '3.6.4');
+    if (!decision) return { ran: false, reason: 'no-plan' };
+    if (decision.run !== true) {
+      return { ran: false, reason: 'plan-skip', planReason: decision.reason };
+    }
+    if (typeof repoRoot !== 'string' || repoRoot.trim() === '') {
+      return { ran: false, reason: 'error', error: 'runExpiredSweep: repoRoot is required' };
+    }
+
+    const { filePath, archivePath } = resolveLearningsPaths(repoRoot);
+    const res = await sweepExpiredLearnings({
+      filePath,
+      archivePath,
+      now,
+      dryRun: false,
+      ...(graceDays === undefined ? {} : { graceDays }),
+    });
+
+    const scanned = res?.scanned ?? 0;
+    const archived = res?.archived ?? 0;
+    if (emit) await emitSweepApplied({ repoRoot, scanned, archived });
+
+    return { ran: true, scanned, archived, archivePath: res?.archivePath ?? archivePath };
+  } catch (err) {
+    // Fail CLOSED (see the module header): a maintenance sweep must never be
+    // able to block a session close.
+    return { ran: false, reason: 'error', error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * Run every MECHANICAL phase of the session-end tail.
+ *
+ * Today that is exactly one — 3.6.4. See the module header for why 3.6.3 and
+ * 3.6.5–3.6.8 stay coordinator-executed (AUQ-gated per
+ * `.claude/rules/ask-via-tool.md` AUQ-004, or requiring a subagent dispatch a
+ * library function cannot make). The keyed return shape is the seam: a caller
+ * reads `result['3.6.4']` today and keeps compiling when a second phase lands.
+ *
+ * @param {object} args — forwarded verbatim to {@link runExpiredSweep}.
+ * @returns {Promise<Record<string, SweepResult>>} Never throws.
+ */
+export async function runTailPhases({ repoRoot, plan, now, graceDays, emit } = {}) {
+  return { '3.6.4': await runExpiredSweep({ repoRoot, plan, now, graceDays, emit }) };
+}

package/scripts/lib/session-lock.mjs

@@ -492,6 +492,11 @@ export function readLockDetailed(opts = {}) {
  *         recorded pids dead, INCLUDING the currently heartbeating session's
  *         own lock), so `stale-pid-alive` was unreachable same-host and every
  *         stale lock rendered as "confirmed dead" in the recovery AUQ.
+ *   { ok: false, reason: 'missing-session-id' }
+ *       — no usable `sessionId` given; NOTHING was written. Same reason string
+ *         and same predicate as forceAcquire() (see its docblock for why an
+ *         ownerless lock is worse than no lock). No `exclusivityClass`: the
+ *         call never reached classification.
  *   { ok: false, reason: 'fs-error', error, exclusivityClass? }
  *       — filesystem failure
  *   { ok: false, reason: 'active-incompatible-exclusive', allActiveSessions, blockingSession, exclusivityClass }
@@ -509,6 +514,28 @@ export function readLockDetailed(opts = {}) {
  * obtaining user consent.
  */
 export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoot, activeSessions, semanticSessionId, quiet = false } = {}) {
+  // -------------------------------------------------------------------------
+  // Ownerless-lock guard. Measured 2026-09-11 in a tmp repoRoot:
+  //   acquire({sessionId: undefined}) -> {ok:true}, lockfile written with NO
+  //   `session_id` key at all; acquire({sessionId: ''}) -> {ok:true}, lockfile
+  //   written with `"session_id": ""`. Both are the exact "present but owned by
+  //   nobody" state forceAcquire()'s docblock below describes: every reader
+  //   compares such a lock against its own id, finds no match, classifies it
+  //   FOREIGN — and foreign is the classification that SKIPS enforcement.
+  //   The guard lived only on forceAcquire(), the rare path (explicit
+  //   stale-lock takeover); acquire() is the primary one. The production
+  //   caller hooks/_lib/lock-bootstrap.mjs gates empty ids upstream, but the
+  //   prose path skills/session-start/references/phase-1-2-session-lock.md
+  //   calls acquire() straight from the coordinator LLM with no gate at all.
+  // Placed FIRST, before classifyMode and before any fs work: nothing is
+  // written. `exclusivityClass` is deliberately absent from this shape — the
+  // caller's class is a property of a call that got far enough to be
+  // classified, and this one did not.
+  // -------------------------------------------------------------------------
+  if (!hasUsableSessionId(sessionId)) {
+    return { ok: false, reason: 'missing-session-id' };
+  }
+
   const lockFile = lockPathFor(repoRoot);
 
   // -------------------------------------------------------------------------
@@ -671,12 +698,45 @@ export function acquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoo
  * Call only after the user has explicitly authorised stale-lock takeover.
  *
  * Returns:
- *   { ok: true, lock, replacedLock? }       — lock written (replacedLock present if one was overwritten)
- *   { ok: false, reason: 'fs-error', ... }  — filesystem failure
+ *   { ok: true, lock, replacedLock? }               — lock written (replacedLock present if one was overwritten)
+ *   { ok: false, reason: 'missing-session-id' }     — no usable `sessionId` given; NOTHING was written
+ *   { ok: false, reason: 'fs-error', ... }          — filesystem failure
+ *
+ * The `missing-session-id` guard is not cosmetic. `buildLock` assigns
+ * `session_id: sessionId` verbatim, and `JSON.stringify` DROPS an `undefined`
+ * value — so a `forceAcquire()` without a sessionId used to write a lock file
+ * carrying no `session_id` key at all. Such a lock is present but owned by
+ * nobody: every reader compares it against its own id, finds no match, and
+ * classifies it as FOREIGN — and foreign is precisely the classification that
+ * skips enforcement. The same failure class is why the wave scope manifest
+ * forbids `"session_id": ""` and requires the key be omitted instead.
+ *
+ * The result SHAPE (not a throw) is deliberate and matches the callers: the
+ * only production call site, `hooks/_lib/lock-bootstrap.mjs`, branches on
+ * `acquireResult.ok !== true` and bails non-blocking; a throw there would be
+ * swallowed by its `catch` and reported as the same `null`, i.e. it would add
+ * no information while breaking the direct `forceAcquire()` calls documented in
+ * `skills/session-start/references/phase-1-2-session-lock.md`.
  *
  * @param {{ sessionId: string, mode: string, ttlHours?: number, repoRoot?: string, semanticSessionId?: string }} args
  */
+/**
+ * A `sessionId` is usable only when it is a non-blank string. ONE predicate,
+ * shared by acquire() and forceAcquire(), so the two entry points cannot drift
+ * apart again — they did: the guard existed on forceAcquire() alone until
+ * 2026-09-11, leaving the primary path able to write an ownerless lock.
+ *
+ * @param {unknown} sessionId
+ * @returns {boolean}
+ */
+function hasUsableSessionId(sessionId) {
+  return typeof sessionId === 'string' && sessionId.trim().length > 0;
+}
+
 export function forceAcquire({ sessionId, mode, ttlHours = DEFAULT_TTL_HOURS, repoRoot, semanticSessionId } = {}) {
+  if (!hasUsableSessionId(sessionId)) {
+    return { ok: false, reason: 'missing-session-id' };
+  }
   try {
     const replacedLock = readLock({ repoRoot });
     const lock = buildLock({ sessionId, mode, ttlHours, semanticSessionId });

package/scripts/lib/session-record-repair.mjs

@@ -42,6 +42,14 @@
  * had defaulted, which is what lets a downstream consumer tell a measured zero
  * apart from a repaired-to-zero.
  *
+ * It also never DISCARDS what it replaces: any field whose present value is
+ * overwritten by a default is first copied to a `_<field>_raw` sidecar
+ * (`preserveRaw`, same convention and same non-clobber guard as
+ * `session-schema/normalizer.mjs`'s `_express_path_detail`). Without it the
+ * repair was itself a data-loss event — 7 of 40 records in the
+ * `projects-baseline` ledger (S119, 2026-09-10) lost narrative `agent_summary`
+ * strings and `total_files_changed` path lists to `{...0}` / `0`.
+ *
  * Plain Node ESM. Named exports. DI-friendly via `deps`.
  *
  * Cross-references:
@@ -112,6 +120,70 @@ function orderIncompleteFields(fields) {
   return [...fields].sort((a, b) => rank(a) - rank(b) || (a < b ? -1 : a > b ? 1 : 0));
 }
 
+/**
+ * Preserve the pre-repair value of `key` under a `_<key>_raw` sidecar BEFORE a
+ * default overwrites it.
+ *
+ * Convention lifted from `session-schema/normalizer.mjs`
+ * (`_express_path_detail`, `if (!('_express_path_detail' in next))`) — but its
+ * non-clobber guard is keyed on WHO WROTE the sidecar, not on its mere presence.
+ * That distinction is the fix for a measured data-loss bug (2026-09-11): the
+ * presence guard read `out`, and `out = { ...record }` carries the INPUT's key
+ * space, so a record arriving with its own `_agent_summary_raw` kept that
+ * unverifiable value and dropped the real `agent_summary` the repair was about
+ * to overwrite:
+ *
+ *   in:  agent_summary: 'ECHTE NARRATIVE ZUSAMMENFASSUNG',
+ *        _agent_summary_raw: 'ANGREIFER-WERT'
+ *   out: _agent_summary_raw = 'ANGREIFER-WERT'   ← the real value was gone
+ *
+ * That is the mirror image of the promise this module's docblock makes, in the
+ * one case where the promise matters. So: `rescued` — a per-`repairRecord()`-call
+ * Set of sidecar keys THIS pass has written — replaces `sidecar in out`. A value
+ * that is provably real RIGHT NOW always outranks a sidecar of unknown origin.
+ *
+ * The multi-pass concern the old comment named is not what kept the sidecar
+ * safe, and was measured unreachable: after run 1 the field holds a VALID
+ * default, so run 2 records no defect for it and never calls preserveRaw at all
+ * (measured: `repairRecord(repairRecord(x).record).changed === false`, defects
+ * `[]`, sidecar intact). Within ONE pass the Set still gives first-write-wins,
+ * which is what the two branches per field (waves, agent_summary) rely on.
+ *
+ * NAMED CEILING (BV-004): if a record is RE-CORRUPTED with a different real
+ * value for the same key BETWEEN two repair runs, run 2's original wins and run
+ * 1's rescue is dropped. Reaching it requires corruption after a repair; the
+ * alternative — trusting an input-supplied sidecar over a value that is
+ * demonstrably real — is the bug above. Revisit if a ledger is ever repaired
+ * in a loop that can re-break the same key.
+ *
+ * Motivation is measured, not hypothetical: 7 of 40 repaired records in the
+ * `projects-baseline` ledger (S119, 2026-09-10) carried narrative strings in
+ * `agent_summary` and path lists in `total_files_changed`; both were replaced
+ * by `{...0}` / `0` and had to be restored by hand. This module's own docblock
+ * promises "nothing is invented" — discarding an unreadable original is the
+ * mirror-image violation of that promise.
+ *
+ * `undefined` and `null` are NOT preserved: an absent field has nothing to
+ * lose (the defect classes are named `*_absent` / `*_missing` for exactly that
+ * reason), and `JSON.stringify` drops an `undefined` sidecar anyway.
+ *
+ * The sidecars are schema-safe: `validateSession` has no unknown-key rejection
+ * (see `validator.mjs` — every `_validate*` helper checks named fields only),
+ * and `serializeSessionLineChecked` round-trips extra keys untouched.
+ *
+ * @param {Record<string, any>} out — the mutable repaired copy
+ * @param {string} key — the field about to be defaulted
+ * @param {any} rawValue — its ORIGINAL value (read from the untouched input)
+ * @param {Set<string>} rescued — sidecar keys already written by THIS call
+ */
+function preserveRaw(out, key, rawValue, rescued) {
+  if (rawValue === undefined || rawValue === null) return;
+  const sidecar = `_${key}_raw`;
+  if (rescued.has(sidecar)) return;
+  out[sidecar] = rawValue;
+  rescued.add(sidecar);
+}
+
 /** Compact ISO stamp for backup filenames: `20260805T091500Z`. */
 export function backupStamp(date = new Date()) {
   return date.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
@@ -143,6 +215,9 @@ export function repairRecord(record) {
   const out = { ...record };
   const defects = [];
   const incomplete = new Set();
+  // Sidecar keys written by THIS pass — the provenance the non-clobber guard
+  // needs. `out`'s own key space cannot serve: it is the INPUT's. See preserveRaw.
+  const rescued = new Set();
 
   // -- waves ----------------------------------------------------------------
   // A NUMBER here is not garbage: it IS the wave count, written by an older
@@ -158,6 +233,7 @@ export function repairRecord(record) {
     } else {
       defects.push('waves_not_array');
     }
+    preserveRaw(out, 'waves', record.waves, rescued);
     out.waves = [];
     incomplete.add('waves');
   }
@@ -173,6 +249,11 @@ export function repairRecord(record) {
   if (out.waves.length > 0 && out.waves.every(isPlainObject)) {
     const needsRenumber = out.waves.some((w) => !isCount(w.wave) || w.wave < 1);
     if (needsRenumber) {
+      // The ORIGINAL ordinals are not recoverable from the renumbered output
+      // (the input may mix valid, absent and 0-based `wave` values), so the
+      // pre-renumber array is preserved whole — same sidecar as the
+      // not-an-array branch above, which cannot have fired on this path.
+      preserveRaw(out, 'waves', record.waves, rescued);
       out.waves = out.waves.map((w, i) => ({ ...w, wave: i + 1 }));
       defects.push('wave_index_invalid');
       incomplete.add('waves[].wave');
@@ -181,6 +262,7 @@ export function repairRecord(record) {
 
   // -- total_waves ----------------------------------------------------------
   if (!isCount(out.total_waves)) {
+    preserveRaw(out, 'total_waves', record.total_waves, rescued);
     out.total_waves = wavesNumber !== null ? wavesNumber : out.waves.length;
     defects.push('total_waves_missing');
     incomplete.add('total_waves');
@@ -188,12 +270,18 @@ export function repairRecord(record) {
 
   // -- agent_summary --------------------------------------------------------
   if (!isPlainObject(out.agent_summary)) {
+    preserveRaw(out, 'agent_summary', record.agent_summary, rescued);
     out.agent_summary = { complete: 0, partial: 0, failed: 0, spiral: 0 };
     defects.push('agent_summary_absent');
     incomplete.add('agent_summary');
   } else {
     const missing = AGENT_SUMMARY_FIELDS.filter((f) => !isCount(out.agent_summary[f]));
     if (missing.length > 0) {
+      // Preserve the WHOLE original summary object rather than one sidecar per
+      // defaulted counter: it carries every original field value at once and
+      // keeps the sidecar namespace flat (`_agent_summary.spiral_raw` would be
+      // a second, uglier convention for the same job).
+      preserveRaw(out, 'agent_summary', record.agent_summary, rescued);
       out.agent_summary = { ...out.agent_summary };
       for (const f of missing) {
         out.agent_summary[f] = 0;
@@ -209,6 +297,7 @@ export function repairRecord(record) {
 
   // -- total_agents ---------------------------------------------------------
   if (!isCount(out.total_agents)) {
+    preserveRaw(out, 'total_agents', record.total_agents, rescued);
     // Prefer the record's own evidence: an agent_summary PRESENT in the
     // original sums to the real agent count (live line 71 sums to 30 where
     // waves.length is 5 — W2/A4 review finding). Fall back to waves.length
@@ -226,6 +315,7 @@ export function repairRecord(record) {
 
   // -- total_files_changed --------------------------------------------------
   if (!isCount(out.total_files_changed)) {
+    preserveRaw(out, 'total_files_changed', record.total_files_changed, rescued);
     out.total_files_changed = 0;
     defects.push('total_files_changed_missing');
     incomplete.add('total_files_changed');
@@ -239,6 +329,7 @@ export function repairRecord(record) {
   // i.e. "unknown", and flagged as such. NEVER the next record's timestamp:
   // the ledger is not chronologically ordered (see the module docblock).
   if (typeof out.completed_at !== 'string' && typeof out.started_at === 'string') {
+    preserveRaw(out, 'completed_at', record.completed_at, rescued);
     const endedMs = typeof out.ended_at === 'string' ? Date.parse(out.ended_at) : NaN;
     const startedMs = Date.parse(out.started_at);
     out.completed_at =

package/scripts/lib/session-schema/constants.mjs

@@ -161,6 +161,12 @@ export const OPTIONAL_FIELDS = Object.freeze([
   'total_token_input',
   'total_token_output',
   'subagents_with_tokens',
+  // #1244 — cache buckets + cost estimate (additive, optional).
+  'total_token_input_uncached',
+  'total_token_cache_read',
+  'total_token_cache_creation',
+  'total_cost_usd',
+  '_token_schema',
   // Epic #724 C1 — SessionEnd close-through backfill provenance fields.
   // `status` distinguishes normally-closed ('completed') from hook-backfilled
   // ('abandoned') records. The `_backfill_*` markers record how a stub was

package/scripts/lib/session-schema/filters.mjs

@@ -33,7 +33,8 @@
  * schema migrations and dedup checks all legitimately need the phantoms. Use
  * these helpers only where the window is meant to represent REAL WORK.
  *
- * Exports: isRealSession, filterRealSessions, tailRealSessions
+ * Exports: isRealSession, filterRealSessions, tailRealSessions,
+ *          isCoordinatorDirectHousekeeping
  */
 
 // ---------------------------------------------------------------------------
@@ -86,3 +87,27 @@ export function tailRealSessions(records, n) {
   if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0) return [];
   return real.slice(-Math.floor(n));
 }
+
+/**
+ * True when a record's waves are ALL coordinator-direct `Housekeeping` waves —
+ * the shape the session-end writer rule (#1321) records for a session that ran
+ * no dispatched waves. The single definition of that shape: consumers treat such
+ * a record as "no waves ran" (eval gate-health) and exclude its 0-agent waves
+ * from agents-per-wave ratios.
+ *
+ * Keys on the wave SHAPE only, never on `session_type`: a housekeeping session
+ * that ran real waves is not this shape. Nor on `coordinator_direct` alone —
+ * whole multi-wave feature sessions carry it too.
+ *
+ * @param {unknown} record — a parsed sessions.jsonl entry
+ * @returns {boolean} — false for empty/absent `waves`
+ */
+export function isCoordinatorDirectHousekeeping(record) {
+  if (record === null || typeof record !== 'object' || Array.isArray(record)) return false;
+  const { waves } = record;
+  return (
+    Array.isArray(waves) &&
+    waves.length > 0 &&
+    waves.every((w) => w?.role === 'Housekeeping' && w?.coordinator_direct === true)
+  );
+}

package/scripts/lib/session-schema/validator.mjs

@@ -384,6 +384,26 @@ function _validateOptionalFields(entry) {
       );
     }
   }
+  // #1244 — cache buckets, cost estimate and the token-contract marker.
+  // Same non-negative-finite-or-null contract as the two totals above;
+  // total_cost_usd is fractional and null means "unknown model", never 0.
+  for (const field of [
+    'total_token_input_uncached',
+    'total_token_cache_read',
+    'total_token_cache_creation',
+    'total_cost_usd',
+    '_token_schema',
+  ]) {
+    const value = entry[field];
+    if (value !== undefined && value !== null) {
+      if (!Number.isFinite(value) || value < 0) {
+        throw new ValidationError(
+          `${field} must be a non-negative finite number or null, got: ${value}`
+        );
+      }
+    }
+  }
+
   // subagents_with_tokens: non-negative integer (never null — it is always a count, defaulting to 0).
   if (entry.subagents_with_tokens !== undefined && entry.subagents_with_tokens !== null) {
     if (