session-orchestrator 5.3.0 → 5.5.0

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

@@ -12,9 +12,12 @@
  * - File-absent or all-null-token sessions return a sentinel shape with null
  *   totals (not 0) so callers can distinguish "session had no token data" from
  *   "session was genuinely free / cost $0".
+ * - `match_status` and `ledger_records` distinguish why totals are absent
+ *   without interpreting the session key's shape (#1027 Nachtrag 7).
  * - Malformed JSONL lines are silently skipped (resilience over strictness).
  * - `subagents_with_tokens` counts distinct agent_ids that have at least one
- *   TOKEN-BEARING record (coverage metric).
+ *   TOKEN-BEARING record (coverage metric); every total counts each agent once
+ *   (§ One record per agent).
  *
  * ## Token provenance — why a bare Σ over token_input is wrong (#949)
  *
@@ -64,10 +67,54 @@
  * `total_token_*` and reports the excluded ones as `legacy_v1_records`: the
  * boundary is DECLARED, never silent.
  *
- * `total_cost_usd` is computed per record via `costUsd()` and is null when ANY
- * priced record carries a model the price table does not know — a partial cost
- * is worse than no cost, because it reads as a complete one. `cost_records_priced`
- * / `cost_records_total` say how much of the session the estimate covers.
+ * ## One record per agent — a stop record carries a RUNNING total
+ *
+ * `hooks/subagent-telemetry.mjs` re-reads the agent's WHOLE transcript at every
+ * stop, so an agent that stops twice (resumed via SendMessage, for one) writes
+ * its running total twice, and summing both counts the first part again. Every
+ * total below therefore takes ONE v2 record per `agent_id`: its tokens come from
+ * the agent's last stop that found its transcript and carried tokens, its cost
+ * candidacy from its last stop that found its transcript ("last" = latest
+ * `timestamp`, ties and unparseable timestamps by file order). Those two differ
+ * only when the last read yielded no tokens — an oversized transcript: the
+ * earlier running total is then a lower bound for the tokens and the cost is
+ * unknown. Measured 2026-10-01 over the 31 local fleet ledgers (1,002 distinct
+ * session/agent pairs with two or more found stops, 407 sessions): no v2 token
+ * bucket ever decreased from one found stop to the next, so the last record is
+ * also the largest; 2 pairs end in a token-less stop, both transcripts now past
+ * the hook's 50 MiB read limit. FORWARD-ONLY like the #949 cut: totals already
+ * in `sessions.jsonl` are not recomputed.
+ *
+ * `total_cost_usd` is computed per agent via `costUsd()` and is null whenever
+ * `cost_records_priced < cost_records_total` (#1475) — a partial cost is worse
+ * than no cost, because it reads as a complete one. An agent is unpriced when the
+ * model of its last found record is unknown to the price table, when it has no model (a token-bearing turn
+ * named none), when it has no tokens at all (transcript found but oversized,
+ * without usage turns, or unreadable, #1474), or when the agent has a start
+ * record but its stop found no transcript of its own and no other record of the
+ * same agent did (`start_record_found: true`, `subagent_transcript_found: false`
+ * — mostly `workflow-subagent`), or when its only own-transcript records are
+ * schema_version 1 (#1487 Pkt 1 — v1 has no priceable buckets). A phantom stop
+ * (#939, no start record) is no agent and no candidate. A record whose four token buckets
+ * are all 0 is priced at $0 whatever its model, and never turns a null total into
+ * a number on its own. A record whose turns span several models carries
+ * `models_usage` (#1470) and is priced part by part. `cost_records_priced` /
+ * `cost_records_total` say how much of the session the estimate covers; with
+ * nothing to price (total 0) the cost is null as well.
+ *
+ * Blind spots the ledger cannot close: an agent whose start record lies outside
+ * the hook's tail window reads `start_record_found: false` and is
+ * indistinguishable from a phantom, and an agent that left neither a start nor a
+ * stop record is invisible. "Never a partial sum" holds over the agents the
+ * ledger can see. Until #1487 Pkt 1 (2026-10-02) a session spanning the
+ * 2026-09-09 schema boundary was priced over its v2 records only — its v1
+ * agents were never cost candidates, so the v2 half's sum read as the whole
+ * bill (4 distinct fleet sessions, 31 ledgers, 2026-10-01). A v1 agent is now an
+ * unpriced candidate: such a session reports `total_cost_usd: null` with
+ * `cost_records_priced < cost_records_total`. Re-measured 2026-10-02 (28
+ * ledgers, 1,887 ledger/session pairs): the same 4 sessions turn null, and 498
+ * pure-v1 pairs change only `cost_records_total` (0/0 → 0/N, cost null before
+ * and after). FORWARD-ONLY like the #949 cut.
  *
  * @module session-token-rollup
  */
@@ -102,6 +149,26 @@ function isTokenBearing(record) {
   return record?.subagent_transcript_found === true;
 }
 
+/**
+ * Did a REAL agent run whose transcript the hook could not find? (#1475 follow-up)
+ *
+ * A stop record with a start record (`start_record_found: true`) but no own
+ * transcript (`subagent_transcript_found: false`) is not a phantom: the agent
+ * existed, it just left nothing to price — 813 of the 877 such records in the
+ * 33 fleet ledgers are `workflow-subagent` (2026-10-01). Its cost is unknown, so it must reach
+ * `cost_records_total`. A phantom stop (#939) has `start_record_found` false and
+ * stays out; a record written before either flag existed matches neither.
+ * @param {object} record
+ * @returns {boolean}
+ */
+function isStartedWithoutTranscript(record) {
+  return (
+    record?.event === 'stop' &&
+    record.start_record_found === true &&
+    record.subagent_transcript_found === false
+  );
+}
+
 /**
  * Is this record inside the schema_version 2 token contract? (#1244)
  * @param {object} record
@@ -111,19 +178,76 @@ function isV2(record) {
   return typeof record?.schema_version === 'number' && record.schema_version >= 2;
 }
 
+/**
+ * Does this record carry a token count on either side?
+ * @param {object} record
+ * @returns {boolean}
+ */
+function hasTokens(record) {
+  const { token_input: inp, token_output: out } = record;
+  return (typeof inp === 'number' && inp >= 0) || (typeof out === 'number' && out >= 0);
+}
+
+/**
+ * Was `candidate` written at a later stop than `current`? Ordered by
+ * `timestamp`; a tie or an unparseable timestamp falls back to file order, and
+ * the caller reads in file order, so the candidate then wins.
+ * @param {object} candidate — read after `current` in the ledger
+ * @param {object} current
+ * @returns {boolean}
+ */
+function isLaterStop(candidate, current) {
+  const a = Date.parse(candidate.timestamp);
+  const b = Date.parse(current.timestamp);
+  if (Number.isNaN(a) || Number.isNaN(b) || a === b) return true;
+  return a > b;
+}
+
+/**
+ * USD cost of one v2 record, or null when it cannot be priced. A record whose
+ * token-bearing turns span several models carries `models_usage` (#1470): each
+ * part is priced at its own model's rates, and one unknown part leaves the whole
+ * record unpriced. Without that field the record's single `model` prices all
+ * four buckets.
+ * @param {object} record
+ * @returns {number|null}
+ */
+function recordCostUsd(record) {
+  const parts =
+    Array.isArray(record.models_usage) && record.models_usage.length > 0
+      ? record.models_usage
+      : [record];
+  let total = 0;
+  for (const part of parts) {
+    const cost = costUsd({
+      model: part?.model,
+      tokenInputUncached: part?.token_input_uncached,
+      tokenCacheRead: part?.token_cache_read,
+      tokenCacheCreation: part?.token_cache_creation,
+      tokenOutput: part?.token_output,
+    });
+    if (cost === null) return null;
+    total += cost;
+  }
+  return total;
+}
+
 /**
  * @typedef {Object} TokenRollupResult
- * @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 {'invalid-key'|'ledger-absent'|'ledger-empty'|'unmatched'|'matched'} match_status - Distinguishes absent telemetry from an unmatched key (#1027 Nachtrag 7).
+ * @property {number|null} ledger_records - Count of parsed non-null, non-array objects; null when the ledger was not read (#1027 Nachtrag 7).
+ * @property {number|null} total_token_input  - Sum of token_input over one v2 token-bearing record per agent (its last stop that carried tokens — § One record per agent); null when none had a non-null value.
+ * @property {number|null} total_token_output - Sum of token_output over the same one record per agent; null when none had a non-null value.
+ * @property {number|null} total_tokens       - total_token_input + total_token_output (#1436); a null side counts as absent, null only when BOTH are null.
  * @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.
- * @property {number|null}  total_token_input_uncached - Sum of token_input_uncached across v2 token-bearing records.
- * @property {number|null}  total_token_cache_read     - Sum of token_cache_read across v2 token-bearing records.
- * @property {number|null}  total_token_cache_creation - Sum of token_cache_creation across v2 token-bearing records.
- * @property {number|null}  total_cost_usd     - Σ costUsd() over v2 token-bearing records; null when ANY of them carries an unknown model (never 0 — see telemetry/pricing.mjs).
- * @property {number}       cost_records_priced - How many token-bearing records the price table could price.
- * @property {number}       cost_records_total  - How many token-bearing records were candidates for pricing.
- * @property {number}       legacy_v1_records  - Token-bearing records EXCLUDED from every total above because their schema_version < 2 (their token_input is a different quantity).
+ * @property {number|null}  total_token_input_uncached - Sum of token_input_uncached over the same one record per agent.
+ * @property {number|null}  total_token_cache_read     - Sum of token_cache_read over the same one record per agent.
+ * @property {number|null}  total_token_cache_creation - Sum of token_cache_creation over the same one record per agent.
+ * @property {number|null}  total_cost_usd     - Σ cost over the agents counted in cost_records_priced; null when cost_records_priced < cost_records_total (#1475 — any unpriced candidate: unknown model, no model, no tokens, a started agent without a transcript, or a v1 agent, #1487 Pkt 1), null when there is nothing to price (cost_records_total 0), and null when no record with a non-zero bucket was priced (all-zero records alone never yield a fabricated $0). Never 0 for unknown — see telemetry/pricing.mjs.
+ * @property {number}       cost_records_priced - How many agents of cost_records_total carry a known cost on their last found v2 record: priced by the table (per model part when the record carries models_usage, #1470), or all four token buckets 0 (priced at $0 whatever the model, #1474).
+ * @property {number}       cost_records_total  - How many agents were candidates for pricing, each counted once however often it stopped: every agent with a v2 record whose own transcript was found — priced on its LAST such record, so one whose last read yielded no tokens (transcript oversized, without usage turns, or unreadable, #1474) is unpriced — plus every started agent whose stops found no transcript of its own (`start_record_found: true`, `subagent_transcript_found: false`), plus every agent with a schema_version 1 own-transcript record (#1487 Pkt 1) — each of these two only when the agent has no v2 own-transcript record in the session. All three latter kinds have an unknown cost. Phantom stops (no start record, #939) are never candidates. priced < total nulls total_cost_usd.
+ * @property {number}       legacy_v1_records  - Token-bearing records EXCLUDED from every token total above because their schema_version < 2 (their token_input is a different quantity). Their agents are unpriced cost candidates (cost_records_total, #1487 Pkt 1).
  * @property {2}            _token_schema      - The token contract these totals were computed under.
  */
 
@@ -142,8 +266,11 @@ export function rollupSessionTokens({
 }) {
   /** @type {TokenRollupResult} */
   const ZERO = {
+    match_status: 'invalid-key',
+    ledger_records: null,
     total_token_input: null,
     total_token_output: null,
+    total_tokens: null,
     subagents_with_tokens: 0,
     matched_records: 0,
     total_token_input_uncached: null,
@@ -169,7 +296,7 @@ export function rollupSessionTokens({
     raw = readFileSync(resolvedPath, 'utf8');
   } catch (err) {
     if (err.code === 'ENOENT') {
-      return { ...ZERO };
+      return { ...ZERO, match_status: 'ledger-absent' };
     }
     throw err;
   }
@@ -177,6 +304,7 @@ export function rollupSessionTokens({
   // Parse JSONL — skip malformed lines, filter to parentSessionId.
   const lines = raw.split('\n');
   const matched = [];
+  let ledgerRecords = 0;
   for (const line of lines) {
     const trimmed = line.trim();
     if (!trimmed) continue;
@@ -187,13 +315,19 @@ export function rollupSessionTokens({
       // Malformed line — skip silently.
       continue;
     }
-    if (record && record.parent_session_id === parentSessionId) {
+    if (record === null || typeof record !== 'object' || Array.isArray(record)) continue;
+    ledgerRecords += 1;
+    if (record.parent_session_id === parentSessionId) {
       matched.push(record);
     }
   }
 
   if (matched.length === 0) {
-    return { ...ZERO };
+    return {
+      ...ZERO,
+      match_status: ledgerRecords === 0 ? 'ledger-empty' : 'unmatched',
+      ledger_records: ledgerRecords,
+    };
   }
 
   // Aggregate — skip null/undefined token values.
@@ -205,7 +339,6 @@ export function rollupSessionTokens({
   let sumCost = null;
   let costPriced = 0;
   let costTotal = 0;
-  let costUnknownModel = false;
   let legacyV1 = 0;
 
   // Track distinct agent_ids that contributed at least one non-null token.
@@ -214,68 +347,133 @@ export function rollupSessionTokens({
   const addNonNegative = (acc, value) =>
     typeof value === 'number' && value >= 0 ? (acc ?? 0) + value : acc;
 
+  // Real agents that may have no v2 record of their own transcript — each an
+  // unpriced candidate, counted once: a started agent whose stop found no
+  // transcript (#1475), and an agent seen in a v1 record (#1487 Pkt 1 — v1
+  // carries no priceable buckets). Resolved against `agents` only AFTER the
+  // pass: a later v2 stop of the same agent that found its transcript prices it
+  // (measured 2026-10-01: 4 agents in one fleet session, `workflow-subagent`
+  // found:false first, then found:true) and must not null a known cost. A record
+  // without an agent_id cannot be joined to another and stands alone.
+  const maybeUnpriced = new Set();
+  let unkeyedUnpriced = 0;
+  const addMaybeUnpriced = (record) => {
+    if (record.agent_id === undefined || record.agent_id === null) unkeyedUnpriced += 1;
+    else maybeUnpriced.add(record.agent_id);
+  };
+
+  // One agent, one count (see module header § One record per agent). Per agent:
+  // `last` is its last stop that found its transcript — the cost candidate —
+  // and `lastWithTokens` its last such stop that carried tokens — the token
+  // contribution. They differ only when the last read yielded no tokens (an
+  // oversized transcript): the earlier running total is then a known lower bound
+  // for the tokens, while the cost stays unknown. A record without an agent_id
+  // cannot be joined to another and stands alone.
+  /** @type {Map<unknown, {last: object, lastWithTokens: object|null}>} */
+  const agents = new Map();
+
   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
+    // transcript, or no transcript at all, contributes no TOKENS. 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;
+    if (!isTokenBearing(record)) {
+      // …but an agent that really ran without a readable transcript has an
+      // unknown cost: an unpriced candidate (total, not priced), so priced <
+      // total nulls `total_cost_usd` (#1475). Phantoms never reach this branch.
+      if (isStartedWithoutTranscript(record)) addMaybeUnpriced(record);
+      continue;
+    }
 
     // Schema gate (#1244) — a v1 record's token_input is raw uncached input,
     // a different quantity from a v2 record's billable prompt volume. Count it
-    // so the boundary is visible, never sum it.
+    // so the boundary is visible, never sum it. Its agent ran, though, and v1
+    // cannot be priced: it is an unpriced cost candidate (#1487 Pkt 1), so a
+    // session spanning the 2026-09-09 boundary reports a null cost instead of
+    // the v2 half's partial sum.
     if (!isV2(record)) {
       legacyV1 += 1;
+      addMaybeUnpriced(record);
       continue;
     }
 
-    const inp = record.token_input;
-    const out = record.token_output;
-
-    sumInput = addNonNegative(sumInput, inp);
-    sumOutput = addNonNegative(sumOutput, out);
-    sumUncached = addNonNegative(sumUncached, record.token_input_uncached);
-    sumCacheRead = addNonNegative(sumCacheRead, record.token_cache_read);
-    sumCacheCreation = addNonNegative(sumCacheCreation, record.token_cache_creation);
+    const withTokens = hasTokens(record) ? record : null;
+    const key = record.agent_id ?? Symbol('unkeyed');
+    const seen = agents.get(key);
+    if (!seen) {
+      agents.set(key, { last: record, lastWithTokens: withTokens });
+      continue;
+    }
+    // A token-bearing `last` is always `lastWithTokens` too — set together, so
+    // an unparseable timestamp (no transitive order) cannot split them.
+    if (isLaterStop(record, seen.last)) {
+      seen.last = record;
+      if (withTokens) seen.lastWithTokens = withTokens;
+    } else if (withTokens && (!seen.lastWithTokens || isLaterStop(withTokens, seen.lastWithTokens))) {
+      seen.lastWithTokens = withTokens;
+    }
+  }
 
-    // Count this agent as having tokens if either field is a non-null number.
-    const hasTokens =
-      (typeof inp === 'number' && inp >= 0) || (typeof out === 'number' && out >= 0);
-    if (hasTokens) {
-      if (record.agent_id !== undefined && record.agent_id !== null) {
-        agentsWithTokens.add(record.agent_id);
-      }
+  for (const [key, { last, lastWithTokens }] of agents) {
+    if (lastWithTokens) {
+      sumInput = addNonNegative(sumInput, lastWithTokens.token_input);
+      sumOutput = addNonNegative(sumOutput, lastWithTokens.token_output);
+      sumUncached = addNonNegative(sumUncached, lastWithTokens.token_input_uncached);
+      sumCacheRead = addNonNegative(sumCacheRead, lastWithTokens.token_cache_read);
+      sumCacheCreation = addNonNegative(sumCacheCreation, lastWithTokens.token_cache_creation);
+      if (typeof key !== 'symbol') agentsWithTokens.add(key);
+    }
 
-      // Cost: every token-bearing v2 record is a pricing candidate. One unknown
-      // model poisons the SESSION total — a cost covering some of the agents
-      // reads as covering all of them.
-      costTotal += 1;
-      const cost = costUsd({
-        model: record.model,
-        tokenInputUncached: record.token_input_uncached,
-        tokenCacheRead: record.token_cache_read,
-        tokenCacheCreation: record.token_cache_creation,
-        tokenOutput: record.token_output,
-      });
-      if (cost === null) {
-        costUnknownModel = true;
-      } else {
-        costPriced += 1;
-        sumCost = (sumCost ?? 0) + cost;
-      }
+    // Cost: every agent with a found transcript is ONE pricing candidate. One
+    // unpriced agent poisons the SESSION total — a cost covering some of the
+    // agents reads as covering all of them.
+    costTotal += 1;
+    if (last !== lastWithTokens) {
+      // #1474 — the agent's last read of its own transcript yielded no tokens:
+      // it exceeded the hook's MAX_TRANSCRIPT_BYTES and was not read, it held no
+      // usage turns, or it was unreadable. Either way the agent ran and its cost
+      // is unknown, so it counts as an unpriced candidate (total, not priced),
+      // and priced < total nulls `total_cost_usd` (#1475).
+      continue;
+    }
+    // #1474 — all four buckets 0 costs $0 whatever the model says. The hook
+    // names such a record by its last turn, typically `<synthetic>`, which
+    // the price table does not know; pricing it would null the session total
+    // for a record that added nothing to it.
+    const allZero = [
+      last.token_input_uncached,
+      last.token_cache_read,
+      last.token_cache_creation,
+      last.token_output,
+    ].every((v) => v === 0);
+    const cost = allZero ? 0 : recordCostUsd(last);
+    if (cost !== null) {
+      costPriced += 1;
+      // An all-zero record adds nothing, so it must not be what turns
+      // `sumCost` from null into a number: next to a token-less record it
+      // would persist a fabricated $0 for a session whose real cost is unknown.
+      if (!allZero) sumCost = (sumCost ?? 0) + cost;
     }
   }
+  for (const id of maybeUnpriced) if (!agents.has(id)) costTotal += 1;
+  costTotal += unkeyedUnpriced;
 
   return {
+    match_status: 'matched',
+    ledger_records: ledgerRecords,
     total_token_input: sumInput,
     total_token_output: sumOutput,
+    // #1436 — the one figure a session-level budget compares against. Null only
+    // when neither side has data; never a fabricated 0.
+    total_tokens: sumInput === null && sumOutput === null ? null : (sumInput ?? 0) + (sumOutput ?? 0),
     subagents_with_tokens: agentsWithTokens.size,
     matched_records: matched.length,
     total_token_input_uncached: sumUncached,
     total_token_cache_read: sumCacheRead,
     total_token_cache_creation: sumCacheCreation,
-    total_cost_usd: costUnknownModel ? null : sumCost,
+    // #1475 — a cost that leaves out any candidate record is not persisted.
+    total_cost_usd: costPriced < costTotal ? null : sumCost,
     cost_records_priced: costPriced,
     cost_records_total: costTotal,
     legacy_v1_records: legacyV1,

package/scripts/lib/sessions-canonical.mjs

@@ -20,6 +20,18 @@
  *     (2026-05-10) carries a byte-identical duplicate LINE — an older
  *     collision class than (3), and rule (1) alone resolves it.
  *
+ *     EXCEPT: a backfill stub never shadows a record that is not one (#1443).
+ *     A stub (a synthesised `_backfill_source` — repair provenance is not one,
+ *     see `isBackfillStub()` — and no wave, agent or changed file, whatever the
+ *     `status` or `_repair_source`) appended AFTER the real record for the
+ *     same id hid that record from every reader — the writers were closed by
+ *     #1368 and the key-occupancy guard, this reader was the remaining gap.
+ *     Among non-stubs, and among stubs, the newest still wins. The same guard
+ *     joins ACROSS ids: a stub sharing a non-empty `raw_session_id` with a
+ *     non-stub under a DIFFERENT `session_id` is dropped for the non-stub. That
+ *     join runs LAST, so it can neither orphan a synthetic twin of (2) nor
+ *     change what (3) reports.
+ *
  * (2) NARROW COLLAPSE OF THE SYSTEMIC DOUBLE-STUB CLASS.
  *     Two `abandoned` records with an EXACT `started_at` + `completed_at`
  *     tuple match are one physical session recorded twice by the two backfill
@@ -70,8 +82,8 @@
  *         refused marker keeps both records and is reported (never logged)
  *         via `canonicalizeSessionsDetailed().ignoredSupersedes`.
  *
- * RULE ORDER: (1) → (2) → (3). The double-stub collapse must run BEFORE
- * supersede removal: with the reverse order a `supersedes` append deleted the
+ * RULE ORDER: (1) → (2) → (3) → (1)'s raw-id join. The double-stub collapse
+ * must run BEFORE supersede removal: with the reverse order a `supersedes` append deleted the
  * authentic stub first, shrank the tuple group to a single member, and the
  * synthetic phantom then survived the very session that refuted it.
  *
@@ -158,6 +170,80 @@ function supersedeRejectReason(superseder, target) {
   return 'no-shared-join-key';
 }
 
+/**
+ * `_backfill_source` prefix that `session-record-repair.mjs` stamps
+ * (`REPAIR_SOURCE`, `'repair-invalid-sessions/1004'`) on a record it repaired
+ * in place that had NO origin of its own — i.e. a REAL record. A record that
+ * already carried a synthesised origin keeps it, and the repair goes to the
+ * separate `_repair_source` field, which this module deliberately ignores
+ * (#1443 F2). Kept as a literal so this module stays a stdlib-only leaf.
+ */
+const REPAIR_PROVENANCE_PREFIX = 'repair-invalid-sessions/';
+
+/**
+ * True when a record is a BACKFILL STUB for rule (1)'s #1443 guard: it carries
+ * SYNTHESISED provenance (`_backfill_source`, but not repair provenance) AND
+ * measured no work (0 waves, agents and files) — whatever its `status`. A
+ * missing `status` is the norm on real records, so status cannot decide it.
+ *
+ * Repair provenance (`repair-invalid-sessions/…`) in `_backfill_source` is
+ * never a stub: the repair tool puts it there only on a record without an
+ * origin, i.e. a real record it fixed in place, not one it invented (#1443 F1 —
+ * a repaired 4-wave record lost to an older 2-wave one). A repaired STUB keeps
+ * its synthesised `_backfill_source` (`state-md-completed`, `events-jsonl`,
+ * `abandoned`) and is judged on that and on its work, whatever its
+ * `_repair_source` says (#1443 F2 — a repaired 0-wave stub shadowed a 4-wave
+ * record once the repair overwrote its origin). Legacy records repaired before
+ * F2 lost that origin irrecoverably and read as real.
+ *
+ * Exported for `scripts/autopilot.mjs`, which must not read a stub as a
+ * healthy 0-token iteration (#1457 F2). Not shared with
+ * `session-close-backfill.mjs::isSupersedableStub()` on purpose: that asks a
+ * narrower WRITER question ("may this be overwritten?" — `abandoned` only), and
+ * that module imports this one, so reusing it here would be a cycle.
+ *
+ * @param {object} rec
+ * @returns {boolean}
+ */
+export function isBackfillStub(rec) {
+  if (!isNonEmptyString(rec._backfill_source)) return false;
+  if (rec._backfill_source.startsWith(REPAIR_PROVENANCE_PREFIX)) return false;
+  const hasWork = (Array.isArray(rec.waves) && rec.waves.length > 0)
+    || rec.total_waves > 0 || rec.total_agents > 0 || rec.total_files_changed > 0;
+  return !hasWork;
+}
+
+/**
+ * Rule (1), cross-id half (#1443) — drop every backfill stub that shares a
+ * non-empty `raw_session_id` with at least one non-stub. A group of stubs only
+ * (or of non-stubs only) is left intact: with no non-stub to prefer there is no
+ * evidence which record is the artefact. Mutates `byId`.
+ *
+ * LIMIT (#1457 point 9): the join assumes one raw_session_id = one physical
+ * session. A raw id can also span a CLOSED session and a later, separate
+ * abandoned tail (measured: a stub starting 4 minutes after its partner's
+ * `completed_at`, LeadPipeDACH `main-2026-09-03-session-11`) — that stub is
+ * dropped too, so the tail is invisible to every reader. No time-window check
+ * guards against it; adding one is a separate decision.
+ * @param {Map<string, object>} byId
+ * @returns {void}
+ */
+function collapseStubsByRawSessionId(byId) {
+  const byRaw = new Map();
+  for (const rec of byId.values()) {
+    if (!isNonEmptyString(rec.raw_session_id)) continue;
+    const group = byRaw.get(rec.raw_session_id);
+    if (group) group.push(rec);
+    else byRaw.set(rec.raw_session_id, [rec]);
+  }
+  for (const group of byRaw.values()) {
+    if (group.length < 2 || group.every(isBackfillStub)) continue;
+    for (const rec of group) {
+      if (isBackfillStub(rec)) byId.delete(rec.session_id);
+    }
+  }
+}
+
 /**
  * Rule (3) — collapse the systemic two-writer double stub. Mutates `byId` by
  * deleting the synthetic twin of each qualifying pair.
@@ -285,10 +371,13 @@ function resolveSupersedes(byId, ignored) {
  *
  * Rules, applied in this order (see the module header for the measured
  * justification of each):
- *   1. newest-wins per `session_id` (file order is chronological);
+ *   1. newest-wins per `session_id` (file order is chronological), except
+ *      that a later backfill stub never shadows an earlier non-stub (#1443);
  *   2. two `abandoned` records with an exact, both-present
  *      `started_at` + `completed_at` tuple collapse to the non-synthetic one;
- *   3. a surviving record's ATTESTABLE `supersedes: X` removes record `X`.
+ *   3. a surviving record's ATTESTABLE `supersedes: X` removes record `X`;
+ *   4. a backfill stub sharing a non-empty `raw_session_id` with a surviving
+ *      non-stub under another `session_id` is dropped (#1443).
  *
  * The double-stub collapse runs BEFORE supersede removal so that a stub which
  * is itself about to be superseded still shadows its synthetic twin — with the
@@ -325,6 +414,9 @@ export function canonicalizeSessionsDetailed(records, { keepUnidentified = false
       if (keepUnidentified) unidentified.push(rec);
       continue;
     }
+    // #1443 — a later backfill stub never shadows an earlier non-stub.
+    const prev = byId.get(rec.session_id);
+    if (prev && isBackfillStub(rec) && !isBackfillStub(prev)) continue;
     byId.set(rec.session_id, rec);
   }
 
@@ -335,6 +427,9 @@ export function canonicalizeSessionsDetailed(records, { keepUnidentified = false
   const ignoredSupersedes = [];
   resolveSupersedes(byId, ignoredSupersedes);
 
+  // -- (1b) stub vs non-stub across ids, joined by raw_session_id (#1443) ----
+  collapseStubsByRawSessionId(byId);
+
   return { records: [...byId.values(), ...unidentified], ignoredSupersedes };
 }
 
@@ -399,7 +494,7 @@ export function countSessionsInJsonl(raw) {
  * is skipped rather than aborting the whole read (same posture as the readers
  * in `session-close-backfill.mjs` and `backfill-abandoned-sessions.mjs`).
  *
- * NOT EVERY RAW READ OF `sessions.jsonl` IS A GAP TO CLOSE (#1221 P2). Five
+ * NOT EVERY RAW READ OF `sessions.jsonl` IS A GAP TO CLOSE (#1221 P2). Four
  * more readers bypass this module's collapse on purpose — verified via
  * `rg -n "sessions.jsonl|SESSIONS"` against each file — and none of them
  * should be "migrated" to `readCanonicalSessions`:
@@ -417,10 +512,6 @@ export function countSessionsInJsonl(raw) {
  *     window; a canonical read could drop a duplicate/superseded stub that
  *     still names a worktree, making a live worktree look unreferenced and
  *     eligible for garbage collection.
- *   - `readTailSession()` in `scripts/autopilot.mjs` parses only the LAST raw
- *     line to project the record this run's own session just appended,
- *     verbatim; canonicalizing could return a different record than the tail
- *     line if a collapse rule folded it away.
  *
  * @param {object} [args]
  * @param {string} [args.repoRoot] project root; the ledger is resolved as

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

@@ -192,7 +192,9 @@ const CLOSING_DIAGNOSTIC_EVENTS = new Map([
   // scripts/lib/autopilot/worktree-pipeline.mjs (release_failed/released only).
   ['orchestrator.session.lock.released', null],
   ['orchestrator.session.lock.release_failed', null],
-  // Only emitter: hooks/on-session-end.mjs — reading the lock during teardown.
+  // hooks/on-session-end.mjs — reading the lock during teardown. Since #1494 also
+  // hooks/_lib/lock-bootstrap.mjs at SessionStart (`unreadable` only); skipping that
+  // one too loses nothing, because the same start emits orchestrator.session.started.
   ['orchestrator.session.lock.read_anomaly', null],
   // Wave lifecycle: hooks/post-tool-batch-wave-signal.mjs emits wave.completed MID-session
   // (real activity, still counted); only the SessionEnd final-wave stamp is a closing

package/scripts/lib/sh-quote.mjs

@@ -0,0 +1,29 @@
+/**
+ * sh-quote.mjs — the one POSIX shell-quoting helper (#1438).
+ *
+ * Four byte-identical private copies (cursor-install, tmux-layout/layouts,
+ * tmux-layout/tmux-shell, run-quality-gate) and one inline copy
+ * (vault-integration-watcher) were folded into this module.
+ */
+
+/**
+ * Quote one value as a single POSIX shell word.
+ *
+ * Wraps the value in single quotes, inside which POSIX `sh` treats EVERY byte
+ * literally — no `$` expansion, no backtick substitution, no word splitting, a
+ * newline included. The one byte that cannot appear inside single quotes is
+ * the single quote itself, and it cannot be backslash-escaped there either
+ * (`\'` inside quotes is a literal backslash that then ENDS the string); so
+ * each `'` closes the quoted run, emits an escaped `\'` outside it, and
+ * reopens: `'` → `'\''`.
+ *
+ * The value is coerced with `String(value)`, as all four former copies did —
+ * their call sites pass paths, command strings and pane commands, and a
+ * number or other primitive must quote to its string form rather than throw.
+ *
+ * @param {unknown} value  The value to quote; coerced via `String()`.
+ * @returns {string}  e.g. `'it'\''s'` for `it's`, `''` for the empty string.
+ */
+export function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}