session-orchestrator 3.17.0 → 3.20.0

package/scripts/lib/session-token-rollup.mjs

@@ -3,7 +3,9 @@
  *
  * Reads `.orchestrator/metrics/subagents.jsonl` (or a caller-supplied path),
  * filters to a given `parent_session_id`, and sums `token_input` /
- * `token_output` across all matched records, skipping null/undefined values.
+ * `token_output` across the records whose token fields are TRUSTWORTHY — see
+ * § Token provenance below, which is the whole reason this module is not a
+ * two-line sum.
  *
  * Design notes:
  * - Pure function — no top-level side effects, no writes.
@@ -12,7 +14,44 @@
  *   "session was genuinely free / cost $0".
  * - Malformed JSONL lines are silently skipped (resilience over strictness).
  * - `subagents_with_tokens` counts distinct agent_ids that have at least one
- *   record with a non-null token_input or token_output value (coverage metric).
+ *   TOKEN-BEARING record (coverage metric).
+ *
+ * ## Token provenance — why a bare Σ over token_input is wrong (#949)
+ *
+ * Two record classes in this ledger carry a `token_input` that must NEVER be
+ * summed, and both look identical to a naive reader:
+ *
+ * 1. **Pre-#949 records** (written before 2026-07-31). The producer read the
+ *    PARENT session transcript instead of the subagent's own, so every stop
+ *    record carries the parent's running totals. Summing them counts the parent
+ *    once per subagent. `hooks/subagent-telemetry.mjs` § TOKEN-DATA PROVENANCE
+ *    states the consumer obligation outright: "Consumers MUST discard token_* on
+ *    every stop record written before this fix landed."
+ * 2. **Phantom stops** (#939). The harness fires `SubagentStop` for an ephemeral
+ *    agent class that never fires `SubagentStart` and for which no subagent ever
+ *    existed. These carry null tokens today — harmless to sum, but they inflate
+ *    any coverage ratio computed against `matched_records`.
+ *
+ * `subagent_transcript_found === true` settles both at once and is the flag the
+ * producer writes for exactly this purpose. It is a sufficient cutoff on its own:
+ * the field did not exist before the #949 fix, so `=== true` excludes every
+ * pre-fix record without needing a date comparison.
+ *
+ * Measured over this repo's ledger on 2026-08-11 (3,981 records / 116 sessions):
+ * 73 sessions summed to 96,148,781 tokens that no agent ever spent — every one of
+ * them a pre-#949 parent total. Under this filter those sessions correctly report
+ * null ("no token data") instead.
+ *
+ *   jq -r 'select(.event=="stop" and .subagent_transcript_found==true and .token_input==null)' \
+ *     .orchestrator/metrics/subagents.jsonl | wc -l     # → 0
+ *
+ * i.e. the flag never excludes a record that genuinely had tokens.
+ *
+ * FORWARD-ONLY. Session totals already written into `sessions.jsonl` by the
+ * unfiltered recipe are NOT recomputed — that ledger is append-only and the
+ * transcripts that produced the oldest records have aged out, so a rewrite would
+ * be reconstruction, not correction. Consumers comparing token totals across the
+ * 2026-08-11 boundary must treat it as a series break.
  *
  * @module session-token-rollup
  */
@@ -30,12 +69,28 @@ const DEFAULT_SUBAGENTS_PATH = '.orchestrator/metrics/subagents.jsonl';
 // Public API
 // ---------------------------------------------------------------------------
 
+/**
+ * Is this record's token data trustworthy enough to sum? (#949)
+ *
+ * The producer sets `subagent_transcript_found: true` only when it located and
+ * read the subagent's OWN transcript. Every other shape — a phantom stop, a
+ * start record, or any record written before the flag existed — is excluded.
+ * See the module header § Token provenance for why this single flag is a
+ * sufficient cutoff and what it costs to omit it.
+ *
+ * @param {object} record — a parsed subagents.jsonl record
+ * @returns {boolean}
+ */
+function isTokenBearing(record) {
+  return record?.subagent_transcript_found === true;
+}
+
 /**
  * @typedef {Object} TokenRollupResult
- * @property {number|null} total_token_input  - Sum of token_input across matched records; null when no record had a non-null value.
- * @property {number|null} total_token_output - Sum of token_output across matched records; null when no record had a non-null value.
- * @property {number}      subagents_with_tokens - Count of distinct agent_ids that had at least one non-null token value.
- * @property {number}      matched_records    - Total count of JSONL records matched by parentSessionId (includes null-token records).
+ * @property {number|null} total_token_input  - Sum of token_input across TOKEN-BEARING matched records; null when none had a non-null value.
+ * @property {number|null} total_token_output - Sum of token_output across TOKEN-BEARING matched records; null when none had a non-null value.
+ * @property {number}      subagents_with_tokens - Count of distinct agent_ids with at least one token-bearing record. This is the numerator of the honest coverage ratio.
+ * @property {number}      matched_records    - Total count of JSONL records matched by parentSessionId. Counts start records, phantom stops and pre-#949 records alike, so it is NOT the denominator for a token-coverage ratio — dividing by it is what made healthy sessions read as 12% covered.
  */
 
 /**
@@ -107,6 +162,13 @@ export function rollupSessionTokens({
   const agentsWithTokens = new Set();
 
   for (const record of matched) {
+    // Provenance gate (#949) — a record whose tokens describe the PARENT
+    // transcript, or no transcript at all, contributes nothing. Skipping it
+    // entirely (rather than treating its values as 0) preserves the null
+    // sentinel: a session of only untrustworthy records reports "no data",
+    // which is true, instead of a fabricated 0.
+    if (!isTokenBearing(record)) continue;
+
     const inp = record.token_input;
     const out = record.token_output;
 

package/scripts/lib/sessions-integrity-banner.mjs

@@ -0,0 +1,294 @@
+/**
+ * sessions-integrity-banner.mjs — GitLab #958 finding 3 (visibility half).
+ *
+ * Deterministic session-start nudge for the "silently invalid ledger record"
+ * gap: `.orchestrator/metrics/sessions.jsonl` accumulates records that fail
+ * the repo's OWN `validateSession()`, and nobody is told.
+ *
+ * Why the loss is silent (W1/D4, 2026-07-31, HEAD 1f7b449): the ledger record
+ * is composed by the coordinator from a Markdown template
+ * (`skills/session-end/metrics-collection.md`) and appended directly,
+ * bypassing `scripts/emit-session.mjs` — which validates and would have
+ * exited 1. Downstream, `scripts/vault-mirror.mjs` logs the casualty as
+ * `{"action":"skipped-invalid"}` on stdout and still exits 0, so the affected
+ * sessions simply have no vault note. A prose prohibition already exists in
+ * `skills/session-end/session-metrics-write.md` and did not stop it; this
+ * banner is the instrument that makes the residue visible at session-start.
+ *
+ * Mirrors the contract used by the sibling Phase 4 banners
+ * (`scripts/lib/sessions-staleness-banner.mjs`,
+ * `scripts/lib/reconcile-nudge-banner.mjs`,
+ * `scripts/lib/vault-staleness-banner.mjs`): a single `checkXxx({repoRoot})`
+ * entry point that is COMPLETELY try/catch-wrapped (never throws) and returns
+ * either `null` (silent no-op) or `{severity:'warn'|'alert', message, ...extra}`.
+ *
+ * TWO VALIDATORS OVER ONE STORE — why this banner reports both populations.
+ * The repo has two independent notions of "a valid session record", and
+ * neither one contains the other:
+ *
+ *   - `validateSession()` (`scripts/lib/session-schema/validator.mjs`) — the
+ *     canonical write-path schema, enforced by `scripts/emit-session.mjs`.
+ *     It treats `effectiveness` as OPTIONAL/nullable — since #964 declared
+ *     explicitly in `OPTIONAL_FIELDS` (`session-schema/constants.mjs`) rather
+ *     than inferable only from an `if` — so a record vault-mirror refuses to
+ *     render can pass it cleanly.
+ *   - vault-mirror's render path — its own, differently-shaped requirement
+ *     set (`RENDERABLE_SESSION_FIELDS_V1` / `_V2` / `_V3`, exported from
+ *     `scripts/lib/vault-mirror/render-sessions.mjs` and consumed by the
+ *     matching `generateSessionNote*` generator, routed by
+ *     `detectSessionSchema`), which REQUIRES `effectiveness` to be present.
+ *     A record can therefore be schema-valid and still get no vault note.
+ *     Since #964 those lists are module-scope and pinned to the write-path
+ *     schema by a mechanical superset test (v1 ⊇ `REQUIRED_FIELDS`, with
+ *     measured carve-outs for the write-unreachable v2/v3) — so "renderable"
+ *     is now a stated strengthening of "schema-valid" rather than an
+ *     undeclared second opinion. That relationship is exactly why BOTH
+ *     populations still have to be reported: a superset can still exclude.
+ *
+ * Reporting one population would hide the other, so the banner names both and
+ * attributes each to its own consequence.
+ *
+ * Live ledger at HEAD 730ee9d (measured 2026-08-03; 205 parseable records,
+ * 146 of them `status: 'abandoned'`, all 205 routing to the v1 generator):
+ * `validateSession` fails 0, vault-mirror render fails 10 — and all 10 of
+ * those are abandoned, i.e. discarded by the #909 filter BEFORE the render
+ * path (see `mirrorSkipReason` below), so the banner is correctly silent
+ * here. The counts move as the ledger grows; treat them as a dated
+ * measurement, never as an invariant — re-run the probe before quoting them.
+ *
+ * The vault-mirror population is measured by CALLING THE REAL RENDER PATH in
+ * a try/catch — never by re-deriving its required-field list here. A third
+ * copy of that list would reproduce the very defect this banner reports
+ * (`.claude/rules/testing.md` § Unfaithful Double: ask the production code
+ * what it would do, do not model it). The same rule is why the #909 abandoned
+ * filter is imported from `session-schema/filters.mjs` and not re-typed.
+ *
+ * Severity is grounded in consequence, not in an arbitrary count threshold:
+ *   - `warn`  — records are schema-invalid, but every one of them still
+ *               mirrors: the ledger is corrupt, nothing is lost yet.
+ *   - `alert` — at least one record is DROPPED by vault-mirror: those
+ *               sessions have no vault note right now.
+ *
+ * Deliberately un-gated (no Session Config key, like `project-hygiene`) — a
+ * check nobody enables finds nothing.
+ *
+ * Plain-JS — no Zod dependency. Never throws. Never mutates input. No
+ * `console.*` calls (repo ESLint `no-console` rule).
+ *
+ * Cross-references:
+ *  - `scripts/lib/session-schema/validator.mjs` — `validateSession`.
+ *  - `scripts/lib/session-schema/filters.mjs` — `isRealSession` (#909).
+ *  - `scripts/lib/vault-mirror/process.mjs` — the routing this probe mirrors.
+ *  - `scripts/lib/vault-mirror/render-sessions.mjs` — the real render path,
+ *    and the `RENDERABLE_SESSION_FIELDS_V{1,2,3}` lists it gates on (#964).
+ *  - `scripts/lib/session-schema/constants.mjs` — `REQUIRED_FIELDS` /
+ *    `OPTIONAL_FIELDS`, the write-path half of the superset relationship.
+ *  - `scripts/emit-session.mjs` — the validating writer this banner points at.
+ *  - `hooks/pre-bash-sessions-ledger-guard.mjs` — the write-guard half of #958.
+ *  - `skills/session-start/SKILL.md` Phase 4 — banner render site.
+ *  - `.claude/rules/verification-before-completion.md` — evidence-before-claims.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { isRealSession } from './session-schema/filters.mjs';
+import { validateSession } from './session-schema/validator.mjs';
+import {
+  detectSessionSchema,
+  normalizeSessionEntry,
+  generateSessionNote,
+  generateSessionNoteV2,
+  generateSessionNoteV3,
+} from './vault-mirror/render-sessions.mjs';
+
+/** Repo-relative path to the session ledger (one record per closed session). */
+const SESSIONS_PATH = '.orchestrator/metrics/sessions.jsonl';
+
+/** Max session_ids listed inline before the message collapses to "+N more". */
+export const MAX_LISTED_IDS = 5;
+
+/**
+ * Read the ledger's non-empty lines. Returns `null` when the file is absent
+ * or unreadable, `[]` when it exists but has no non-empty lines. Never throws.
+ *
+ * @param {string} filePath
+ * @returns {string[]|null}
+ */
+function readJsonlLines(filePath) {
+  if (!existsSync(filePath)) return null;
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  return raw.split('\n').filter((line) => line.length > 0);
+}
+
+/**
+ * Ask the REAL vault-mirror render path whether it would skip this entry AS
+ * `skipped-invalid`. Reproduces `scripts/lib/vault-mirror/process.mjs`
+ * `processSession()` routing in its production ORDER: normalize aliases (#635)
+ * → detect schema → select that schema's generator → **#909 abandoned filter**
+ * → invoke the generator. A throw from the generator is precisely what
+ * `scripts/vault-mirror.mjs` catches and reports as
+ * `{"action":"skipped-invalid"}`.
+ *
+ * The abandoned filter is load-bearing, not decoration. `process.mjs:485`
+ * returns `skipped-abandoned` for `!isRealSession(entry)` BEFORE the generator
+ * is ever called, so an abandoned record can never reach the render path and
+ * can never become `skipped-invalid`. Omitting it made this probe measure a
+ * population production never reaches: on this repo's ledger (measured
+ * 2026-08-03, HEAD 730ee9d, 205 records) **all 10** reported "dropped" records
+ * were `status: 'abandoned'` — a 100 %-false 🚨 on every session start, with a
+ * prescribed remedy (re-emit) that produces no vault note for such a record.
+ * The predicate is IMPORTED from `session-schema/filters.mjs` rather than
+ * re-derived: that rule already has exactly two homes (the filter module and
+ * `process.mjs`'s call site), and a hand-copied `status !== 'abandoned'` here
+ * would make a third — the divergence class this banner exists to report.
+ *
+ * The generator is invoked with one argument where production passes
+ * `generator(entry, { repoNs })` (`process.mjs:516` — the SESSION render whose
+ * throw becomes `skipped-invalid`; the 3-argument `generator(entry, slug,
+ * generatorOpts)` calls elsewhere in that file belong to the separate
+ * LEARNINGS path and are not this probe's population). All three generators
+ * declare `options = {}` and use `repoNs` only for a frontmatter field, never
+ * to decide whether to throw — so the omission cannot change the render/skip
+ * verdict this probe reads. Resolving a real `repoNs` here would cost a git
+ * subprocess per record for a value the verdict ignores.
+ *
+ * @param {object} record
+ * @returns {string|null} the skip reason, or `null` when production would
+ *   either render it or discard it for a reason OTHER than invalidity.
+ */
+function mirrorSkipReason(record) {
+  try {
+    const entry = normalizeSessionEntry(record);
+    const schema = detectSessionSchema(entry);
+    const generator =
+      schema === 'v3' ? generateSessionNoteV3 : schema === 'v2' ? generateSessionNoteV2 : generateSessionNote;
+    // #909 filter — production returns `skipped-abandoned` here and never
+    // reaches the generator. Not a render failure; not this banner's signal.
+    if (!isRealSession(entry)) return null;
+    generator(entry);
+    return null;
+  } catch (err) {
+    return err && typeof err.message === 'string' ? err.message : 'unknown render failure';
+  }
+}
+
+/**
+ * Render `<id>, <id>, … (+N more)` for a bounded id list.
+ *
+ * @param {{sessionId: string}[]} rows
+ * @returns {string}
+ */
+function formatIds(rows) {
+  const ids = rows.map((r) => r.sessionId);
+  const shown = ids.slice(0, MAX_LISTED_IDS).join(', ');
+  const rest = ids.length - MAX_LISTED_IDS;
+  return rest > 0 ? `${shown} (+${rest} more)` : shown;
+}
+
+/**
+ * Check sessions-ledger schema integrity and produce a session-start banner.
+ *
+ * Silent (`null`) when: `sessions.jsonl` is missing, empty, unreadable, holds
+ * no parseable JSON line at all, or every parseable record satisfies BOTH
+ * `validateSession()` and the vault-mirror render path. An `abandoned` record
+ * satisfies the render half vacuously — production discards it as
+ * `skipped-abandoned` before rendering, so it can never be `skipped-invalid`
+ * and is never counted in `mirrorSkipped`. Unparseable lines are
+ * SKIPPED, not reported — this probe judges schema integrity, not file
+ * corruption (matching the sibling banners' malformed-line handling). Never
+ * throws.
+ *
+ * @param {{repoRoot: string}} opts
+ *   - `repoRoot`: REQUIRED absolute path to the repo root.
+ * @returns {null | {
+ *   severity: 'warn'|'alert',
+ *   message: string,
+ *   total: number,
+ *   schemaInvalid: {line: number, sessionId: string, error: string}[],
+ *   mirrorSkipped: {line: number, sessionId: string, error: string}[],
+ * }}
+ */
+export function checkSessionsIntegrity({ repoRoot } = {}) {
+  try {
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    const lines = readJsonlLines(path.join(repoRoot, SESSIONS_PATH));
+    if (lines === null || lines.length === 0) return null;
+
+    /** @type {{line: number, sessionId: string, error: string}[]} */
+    const schemaInvalid = [];
+    /** @type {{line: number, sessionId: string, error: string}[]} */
+    const mirrorSkipped = [];
+    let total = 0;
+
+    for (let i = 0; i < lines.length; i++) {
+      let record;
+      try {
+        record = JSON.parse(lines[i]);
+      } catch {
+        continue; // unparseable line — not this probe's concern
+      }
+      if (!record || typeof record !== 'object' || Array.isArray(record)) continue;
+      total += 1;
+
+      const sessionId =
+        typeof record.session_id === 'string' && record.session_id.length > 0
+          ? record.session_id
+          : '<no session_id>';
+
+      try {
+        validateSession(record);
+      } catch (err) {
+        schemaInvalid.push({
+          line: i + 1,
+          sessionId,
+          error: err && typeof err.message === 'string' ? err.message : 'unknown validation failure',
+        });
+      }
+
+      const skipReason = mirrorSkipReason(record);
+      if (skipReason !== null) {
+        mirrorSkipped.push({ line: i + 1, sessionId, error: skipReason });
+      }
+    }
+
+    if (total === 0) return null;
+    if (schemaInvalid.length === 0 && mirrorSkipped.length === 0) return null;
+
+    // alert only when records are ACTUALLY being dropped by vault-mirror —
+    // those sessions have no vault note right now. A schema-invalid record
+    // that still mirrors is corruption without loss: warn.
+    const severity = mirrorSkipped.length > 0 ? 'alert' : 'warn';
+
+    const parts = [];
+    if (schemaInvalid.length > 0) {
+      parts.push(
+        `${schemaInvalid.length} of ${total} records fail validateSession (${formatIds(schemaInvalid)})`
+      );
+    }
+    if (mirrorSkipped.length > 0) {
+      parts.push(
+        `${mirrorSkipped.length} are dropped by vault-mirror as skipped-invalid — those sessions have NO vault note (${formatIds(mirrorSkipped)})`
+      );
+    }
+
+    const base =
+      `sessions-integrity: ${parts.join('; ')} — records were appended without passing ` +
+      `scripts/emit-session.mjs (which validates and would have refused). ` +
+      `Inspect: node -e with validateSession from scripts/lib/session-schema/validator.mjs; ` +
+      `re-emit affected records via scripts/emit-session.mjs`;
+
+    const message = severity === 'alert' ? `🚨 ${base}.` : `⚠ ${base}.`;
+
+    return { severity, message, total, schemaInvalid, mirrorSkipped };
+  } catch {
+    // Defensive catch-all — banner must never throw.
+    return null;
+  }
+}

package/scripts/lib/sessions-staleness-banner.mjs

@@ -20,9 +20,11 @@
  * by the time this probe fires. Gating on "no live lock" would make the
  * banner structurally silent forever. Instead:
  *
- *   - `lastLedgerAt`      = `completed_at` of the last PARSEABLE
- *                           `sessions.jsonl` record (scanned from EOF
- *                           backward, skipping malformed lines).
+ *   - `lastLedgerAt`      = `completed_at` of the last PARSEABLE, GENUINE
+ *                           (non-backfill-stub) `sessions.jsonl` record
+ *                           (scanned from EOF backward, skipping malformed
+ *                           lines) — see "Backfill-stub self-erasure fix"
+ *                           below for the stub-skip logic and its fallback.
  *   - `cutoff`            = the CURRENT session's `session.lock`
  *                           `started_at` (via `readLock()`); when no lock is
  *                           readable, `cutoff = now` (all events count).
@@ -36,6 +38,45 @@
  *                           meaningful when > 0 (foreign activity happened
  *                           AFTER the last ledger entry).
  *
+ * Backfill-stub self-erasure fix — the anchor axis: a backfill-produced
+ * `sessions.jsonl` record (`_backfill_source` / `status: 'abandoned'`, see
+ * `session-close-backfill.mjs` `synthesizeRecord()`) sets `completed_at =
+ * max(started_at, lastTerminalMs ?? nowMs)`. When the abandoned session
+ * never emitted a STOPPED/ENDED event — the COMMON case, since that is
+ * *why* it is "abandoned" — `completed_at` silently becomes the BACKFILL
+ * RUN's own wall-clock instant, not a measurement of when the session
+ * actually ended. Anchoring `lastLedgerEntry()` on that value means a
+ * backfill run can retroactively erase a multi-day staleness gap just by
+ * writing a stub today (observed: a 92.5h gap to the last GENUINE record
+ * collapsed to 0.6h the moment a backfill stub landed).
+ *
+ * Two axes were available to fix this: (a) skip stub records when scanning
+ * for the ledger anchor, keeping `completed_at` as the anchor field; or (b)
+ * blanket-switch the anchor field to `started_at` for every record. (b) was
+ * rejected — for a GENUINE multi-hour session, `started_at` sits hours
+ * before `completed_at`, so switching the anchor field universally would
+ * inflate `deltaHours` for perfectly healthy, promptly-closed sessions
+ * (a session's own mid-session events would newly count as "after" the
+ * anchor), reintroducing false positives on the opposite side. (a) is
+ * chosen: `lastLedgerEntry()` skips any record `isBackfillStub()` flags and
+ * keeps searching backward for a GENUINE `completed_at`. Stub recognition
+ * uses EITHER marker (OR, not AND) deliberately — both are set by the same
+ * producer today, but requiring both would silently stop matching the day a
+ * future backfill variant drops one of them while keeping the other; OR
+ * degrades gracefully (still catches it), AND does not.
+ *
+ * All-stub fallback (deliberately NOT null): when NO genuine record exists
+ * anywhere in the file — every record is a backfill stub — this is a
+ * STRONGER signal of the close-through gap than an ordinary stale ledger,
+ * not a weaker one: no session has EVER genuinely closed. The module's
+ * usual fail-quiet convention (null on missing/empty/ambiguous input) does
+ * not extend to "we have data but all of it is synthetic" — that state IS
+ * the failure this banner exists to catch, so `lastLedgerEntry()` instead
+ * anchors on the newest stub's `started_at` (grounded in the real
+ * `orchestrator.session.started` event in the common case — see
+ * `synthesizeRecord()` — unlike that same stub's fabricated `completed_at`)
+ * and flags the result `stubFallback: true` for callers that want to say so.
+ *
  * Severity: warn above `2 × DEFAULT_TTL_HOURS` (8h, imported from
  * `session-lock.mjs` rather than duplicated), alert above 24h.
  *
@@ -60,6 +101,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { readLock, DEFAULT_TTL_HOURS } from './session-lock.mjs';
+import { isRealSession } from './session-schema/filters.mjs';
 
 /** Repo-relative path to the session ledger (one record per closed session). */
 const SESSIONS_PATH = '.orchestrator/metrics/sessions.jsonl';
@@ -93,15 +135,51 @@ function readJsonlLines(filePath) {
 }
 
 /**
- * Scan `sessions.jsonl` lines from EOF backward and return the `completed_at`
- * of the last PARSEABLE record that carries a valid ISO timestamp. Malformed
- * or non-conforming lines (bad JSON, missing/invalid `completed_at`) are
- * skipped, not treated as fatal.
+ * True when a `sessions.jsonl` record's `completed_at` was SYNTHESIZED by
+ * the backfill engine (`scripts/lib/session-close-backfill.mjs`
+ * `synthesizeRecord()`) rather than measured at real session-close time —
+ * see the module-header "Backfill-stub self-erasure fix" section above for
+ * the full reasoning behind the OR (not AND) combination of the two markers.
+ *
+ * Reuses `isRealSession()` from `./session-schema/filters.mjs` — its own doc
+ * names `status: 'abandoned'` "the canonical marker" for exactly this phantom
+ * class, so this is the SAME predicate every other real/phantom-aware
+ * consumer in this repo already relies on, not a hand-rolled duplicate of it.
+ * `_backfill_source` is layered on top as the second, independent signal.
+ * Caller guarantees `record` is already a non-null object (see
+ * `lastLedgerEntry()`'s guard above the call site).
+ *
+ * @param {object} record
+ * @returns {boolean}
+ */
+function isBackfillStub(record) {
+  if (!isRealSession(record)) return true;
+  return typeof record._backfill_source === 'string' && record._backfill_source.length > 0;
+}
+
+/**
+ * Scan `sessions.jsonl` lines from EOF backward and return the anchor
+ * instant to measure ledger staleness against. Malformed or non-conforming
+ * lines (bad JSON, non-object) are skipped, not treated as fatal.
+ *
+ * Two passes, in priority order:
+ *   1. GENUINE — the last (by position) record that is NOT `isBackfillStub()`
+ *      and carries a valid `completed_at`. This is the trustworthy case:
+ *      `completed_at` was written by the real session-end path.
+ *   2. STUB-FALLBACK — only reached when the loop above finds no genuine
+ *      record at all (every record is a stub, or the file has none). Anchors
+ *      on the newest-by-position stub's `started_at` instead of its
+ *      `completed_at` — see the module-header design note for why. Flags
+ *      `stubFallback: true` on the returned object; omitted (`undefined`) on
+ *      the genuine path so existing callers checking `ledger.ms`/`ledger.iso`
+ *      see no behavioural change.
  *
  * @param {string[]} lines
- * @returns {{iso: string, ms: number}|null}
+ * @returns {{iso: string, ms: number, stubFallback?: true}|null}
  */
 function lastLedgerEntry(lines) {
+  let newestStub = null; // newest-by-position stub with a parseable started_at
+
   for (let i = lines.length - 1; i >= 0; i--) {
     let record;
     try {
@@ -109,12 +187,28 @@ function lastLedgerEntry(lines) {
     } catch {
       continue;
     }
-    if (!record || typeof record !== 'object' || typeof record.completed_at !== 'string') continue;
+    if (!record || typeof record !== 'object') continue;
+
+    if (isBackfillStub(record)) {
+      // Never anchor on a stub's completed_at (it may be the backfill run's
+      // own wall-clock) — remember it only as a fallback candidate, and only
+      // the first (nearest-EOF, i.e. newest-by-position) one seen.
+      if (newestStub === null && typeof record.started_at === 'string') {
+        const startedMs = Date.parse(record.started_at);
+        if (Number.isFinite(startedMs)) newestStub = { iso: record.started_at, ms: startedMs };
+      }
+      continue;
+    }
+
+    if (typeof record.completed_at !== 'string') continue;
     const ms = Date.parse(record.completed_at);
     if (!Number.isFinite(ms)) continue;
     return { iso: record.completed_at, ms };
   }
-  return null;
+
+  // No genuine record anywhere — see module-header "All-stub fallback" note:
+  // this is a stronger alarm signal than null, not a null-worthy absence.
+  return newestStub ? { iso: newestStub.iso, ms: newestStub.ms, stubFallback: true } : null;
 }
 
 /**
@@ -182,10 +276,16 @@ function resolveCutoffMs(repoRoot, nowMs) {
  * Check sessions-ledger staleness and produce a session-start banner.
  *
  * Silent (`null`) when: `sessions.jsonl` is missing/empty/entirely
- * unparseable, `events.jsonl` is missing/empty, no foreign (pre-cutoff)
+ * unparseable-or-anchor-less (see `lastLedgerEntry()` — this now also
+ * covers "every record is a backfill stub with no parseable `started_at`
+ * anywhere"), `events.jsonl` is missing/empty, no foreign (pre-cutoff)
  * event exists, the foreign event is not after the last ledger entry, or the
  * resulting gap is under the warn threshold. Never throws.
  *
+ * When the anchor comes from the all-stub fallback (`ledger.stubFallback`),
+ * `lastLedgerAt` is a STUB's `started_at`, not a genuine `completed_at` — the
+ * message says so explicitly rather than implying a real close was measured.
+ *
  * @param {{repoRoot: string, now?: number}} opts
  *   - `repoRoot`: REQUIRED absolute path to the repo root.
  *   - `now`: optional injectable clock (epoch ms); defaults to `Date.now()`.
@@ -196,6 +296,7 @@ function resolveCutoffMs(repoRoot, nowMs) {
  *   lastLedgerAt: string,
  *   lastForeignEventAt: string,
  *   deltaHours: number,
+ *   stubFallback?: true,
  * }}
  */
 export function checkSessionsStaleness({ repoRoot, now = Date.now() } = {}) {
@@ -226,8 +327,15 @@ export function checkSessionsStaleness({ repoRoot, now = Date.now() } = {}) {
 
     const severity = deltaHours > ALERT_THRESHOLD_HOURS ? 'alert' : 'warn';
 
+    // stubFallback (see lastLedgerEntry()): every sessions.jsonl record is a
+    // backfill stub — ledger.iso is a STUB's started_at, not a measured
+    // completed_at. Say so explicitly rather than implying a real close.
+    const ledgerDescription = ledger.stubFallback
+      ? `last sessions.jsonl entry is backfill-stub-only — newest stub started_at ${ledger.iso}`
+      : `last sessions.jsonl entry ${ledger.iso}`;
+
     const base =
-      `sessions-staleness: last sessions.jsonl entry ${ledger.iso} is ${deltaHours}h behind ` +
+      `sessions-staleness: ${ledgerDescription} is ${deltaHours}h behind ` +
       `pre-session events.jsonl activity ${foreign.iso} — possible close-through gap ` +
       `(sessions ended without a ledger record; run node scripts/backfill-abandoned-sessions.mjs --dry-run)`;
 
@@ -239,6 +347,7 @@ export function checkSessionsStaleness({ repoRoot, now = Date.now() } = {}) {
       lastLedgerAt: ledger.iso,
       lastForeignEventAt: foreign.iso,
       deltaHours,
+      ...(ledger.stubFallback ? { stubFallback: true } : {}),
     };
   } catch {
     // Defensive catch-all — banner must never throw.