session-orchestrator 5.4.0 → 5.5.0

package/scripts/lib/scope-gate.mjs

@@ -16,6 +16,9 @@ import path from 'node:path';
 
 import { tokenizeCommand, splitChainSegments, resolveSegmentVerb } from './command-blocker.mjs';
 
+/** The harness state dirs a `wave-scope.json` may live in, highest precedence first. */
+const SCOPE_FILE_DIRS = Object.freeze(['.pi', '.cursor', '.codex', '.claude']);
+
 /**
  * Find the wave-scope.json file for the given project root.
  *
@@ -28,11 +31,12 @@ import { tokenizeCommand, splitChainSegments, resolveSegmentVerb } from './comma
  * Returns the absolute path string, or null if none exist.
  * Sync (uses fs.existsSync).
  *
+ * @deprecated Use findOwnScopeFile because first-file selection ignores manifest ownership and can select a peer session's manifest.
  * @param {string} projectRoot — absolute path to project root
  * @returns {string|null}
  */
 export function findScopeFile(projectRoot) {
-  for (const dir of ['.pi', '.cursor', '.codex', '.claude']) {
+  for (const dir of SCOPE_FILE_DIRS) {
     const candidate = path.join(projectRoot, dir, 'wave-scope.json');
     if (existsSync(candidate)) {
       return candidate;
@@ -41,6 +45,67 @@ export function findScopeFile(projectRoot) {
   return null;
 }
 
+/**
+ * The manifest that governs THIS session: walk the {@link findScopeFile}
+ * precedence (`.pi` > `.cursor` > `.codex` > `.claude`) and return the first
+ * candidate that is NOT provably bound to another session (#1504 point 6).
+ *
+ * `findScopeFile` stops at the first file that EXISTS. When that file is a
+ * peer's — another harness session's manifest in the same working copy — every
+ * guard that stands down on a foreign manifest stood down, and this session's
+ * own `.claude/wave-scope.json` one rung lower was never read: a peer's
+ * manifest switched this session's scope gates off.
+ *
+ * Disposition per candidate, decided INSIDE the loop (an identity check after
+ * the loop makes the first readable candidate the veto-holder —
+ * `.claude/rules/identity-and-locks.md`):
+ *   - `'own'` or `'unknown'` → return it. `'unknown'` covers an unbound/legacy
+ *     manifest, a corrupt or unreadable one (judged as `{}`), and an empty
+ *     `ownIds` (a harness that supplies no session id). Each means ENFORCE
+ *     under the binding contract, so each stays the decider exactly as under
+ *     `findScopeFile` — a truncated manifest cannot skip itself.
+ *   - `'foreign'` → remember the first one and `continue`.
+ *
+ * When EVERY existing candidate is foreign, `path` is null and `foreignPath`
+ * names the first of them, so the caller reaches its existing foreign
+ * disposition (allow + `orchestrator.scope.foreign_session_ignored`) unchanged.
+ *
+ * `classify` is injected, not imported: importing the identity module here
+ * would add it to the import closure of every hook that reaches this file
+ * through the `hardening.mjs` barrel, while only the guards that stand down on
+ * a foreign manifest need it — and each of them already binds it. Pass
+ * `classifyManifestSession` from `session-identity/own-session.mjs`.
+ *
+ * COST: identical to `findScopeFile` when no manifest exists (≤4 `existsSync`).
+ * With one, one extra sync read + parse of that small file. The caller still
+ * reads the returned file itself and classifies THAT read, so a rebind between
+ * the two reads is judged at the same decision point as before.
+ *
+ * Sync. Never throws (unless `classify` does).
+ *
+ * @param {string} projectRoot absolute path to the project root
+ * @param {Set<string>} ownIds process-local own ids (`readProcessLocalSessionIds`)
+ * @param {(scope: object, ownIds: Set<string>) => { verdict: string }} classify
+ * @returns {{ path: string|null, foreignPath: string|null }}
+ */
+export function findOwnScopeFile(projectRoot, ownIds, classify) {
+  let foreignPath = null;
+  for (const dir of SCOPE_FILE_DIRS) {
+    const candidate = path.join(projectRoot, dir, 'wave-scope.json');
+    if (!existsSync(candidate)) continue;
+    let scope = {};
+    try {
+      const parsed = JSON.parse(readFileSync(candidate, 'utf8'));
+      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) scope = parsed;
+    } catch {
+      // unreadable / corrupt → `{}` → no binding → 'unknown' → this candidate decides
+    }
+    if (classify(scope, ownIds).verdict !== 'foreign') return { path: candidate, foreignPath };
+    foreignPath ??= candidate;
+  }
+  return { path: null, foreignPath };
+}
+
 /**
  * Read the enforcement level from a scope file.
  * Defaults to "strict" (fail-closed) on parse error or missing field.
@@ -190,7 +255,8 @@ function literalScopePrefix(entry) {
  * verbatim presence + literal-prefix coverage; it does not prove that e.g.
  * `src/**\/*.ts` ⊆ `src/**\/*.js` is false. The concrete-path branch above is
  * exact and carries the incident-relevant load (the union the coordinator
- * actually writes is verbatim, deduplicated agent scopes). Erring toward
+ * actually writes is the deduplicated agent scopes in canonical spelling, see
+ * {@link unionFileScopes}). Erring toward
  * over-approximating coverage keeps a legitimate union from being rejected on a
  * glob technicality rather than pretending to a precision this matcher lacks.
  *
@@ -211,16 +277,21 @@ export function assertFileScopeSubset(fileScope, allowedPaths) {
   const missing = [];
   for (const entry of fileScope) {
     if (typeof entry !== 'string' || entry.length === 0) continue;
+    // The AGENT side is compared in canonical spelling — the spelling the union
+    // emits and the write path Gate 7 matches. `allowedPaths` stays as written:
+    // a hand-written `./x` there is a pattern Gate 7 cannot match, and spelling
+    // it away here would report coverage the hook then denies.
+    const spelled = scopeEntrySpelling(entry);
     let covered;
-    if (isGlobScopeEntry(entry)) {
+    if (isGlobScopeEntry(spelled)) {
       // GLOB entry: verbatim presence OR literal-prefix coverage.
-      const prefix = literalScopePrefix(entry);
-      covered = allowedPaths.some((p) => p === entry || pathMatchesPattern(prefix, p));
+      const prefix = literalScopePrefix(spelled);
+      covered = allowedPaths.some((p) => p === spelled || pathMatchesPattern(prefix, p));
     } else {
       // CONCRETE entry: must match ≥1 allowedPaths pattern.
-      covered = allowedPaths.some((p) => pathMatchesPattern(entry, p));
+      covered = allowedPaths.some((p) => pathMatchesPattern(spelled, p));
     }
-    if (!covered) missing.push(entry);
+    if (!covered) missing.push(entry); // as declared, so the plan entry is findable
   }
   return { ok: missing.length === 0, missing };
 }
@@ -329,13 +400,16 @@ export function testSiblingExpansionApplies(opts = {}) {
  *
  * ## Why a GLOB and not a computed path
  * The emitted sibling is `tests/**\/{basename}*.test.mjs`, never a concrete
- * path. Measured over all 430 tracked production `.mjs` in this repo:
- * a naive 1:1 mirror (`scripts/lib/X.mjs → tests/lib/X.test.mjs`) is right
- * 301/430 = 70.0% (`hooks/_lib` 0/5, `scripts/ci/` 0/1); a same-basename test
- * ANYWHERE under `tests/` is right 368/430 = 85.6%. The glob takes the 85.6%
- * form, and its failure mode is HARMLESS — it grants write access to files that
- * may not exist. A computed concrete path is wrong 30% of the time AND still
- * denies the real test, which is the original bug wearing a new face.
+ * path: a same-basename test ANYWHERE under `tests/` resolves for far more
+ * production files than a naive 1:1 mirror (`scripts/lib/X.mjs →
+ * tests/lib/X.test.mjs`). The DATED figures — population, both ratios, the
+ * measuring command and the SHA — live in ONE place:
+ * skills/wave-executor/references/wave-loop-scope-manifest.md § Test-Sibling
+ * Expansion (#970). Cite and re-measure them there, never restate them here: an
+ * undated copy drifted to a second, contradicting set of numbers (#1026.5,
+ * PSA-006 item 4). The glob's failure mode is HARMLESS — it grants write access
+ * to files that may not exist. A computed concrete path is wrong more often AND
+ * still denies the real test, which is the original bug wearing a new face.
  *
  * ## Required behaviours (each is a nameable regression)
  *  1. `[]` → `[]` STRUCTURALLY. Discovery waves use an empty scope as a
@@ -403,8 +477,11 @@ export function testSiblingsFor(entries, opts = {}) {
     : DEFAULT_TEST_PATH_PATTERNS;
   const out = [];
   const seen = new Set();
-  for (const entry of Array.isArray(entries) ? entries : []) {
-    if (typeof entry !== 'string' || entry.length === 0) continue;
+  for (const declared of Array.isArray(entries) ? entries : []) {
+    if (typeof declared !== 'string' || declared.length === 0) continue;
+    // Canonical spelling, as the union carries it: a verbatim `./tests/x.mjs`
+    // misses `tests/**` and would be mirrored as if it were production code.
+    const entry = scopeEntrySpelling(declared);
     if (path.isAbsolute(entry)) continue; // behaviour 3
     if (isGlobScopeEntry(entry)) continue; // no single basename to mirror
     if (isTestPathEntry(entry, testPatterns)) continue; // behaviours 2 + 4
@@ -940,6 +1017,53 @@ export function isPeerRecordId(id) {
   return typeof id === 'string' && id.startsWith(PEER_RECORD_PREFIX);
 }
 
+/**
+ * Record id of the COORDINATOR's own planned direct edits (#1020): one
+ * `{id: 'coordinator', files}` record in a wave's aggregate sidecar, and
+ * `<state-dir>/filescopes/wave-<N>/coordinator.json` in the per-agent shape.
+ * Exactly lowercase — `materialize-wave-scope.mjs` rejects any other casing.
+ *
+ * The coordinator is a declarant but never a DISPATCH: no `FILE-SCOPE` block is
+ * injected for it, no digest is echoed back, no agent is counted for it. Every
+ * consumer that joins scope files against dispatches must skip it, or it reports
+ * the coordinator's own scope as an omitted injection (#1493.2). SSOT beside
+ * {@link PEER_RECORD_PREFIX} for the same reason that one lives here.
+ */
+export const COORDINATOR_RECORD_ID = 'coordinator';
+
+/**
+ * Is this record id the coordinator's (see {@link COORDINATOR_RECORD_ID})?
+ * Exact match; a non-string id is not the coordinator.
+ *
+ * @param {unknown} id
+ * @returns {boolean}
+ */
+export function isCoordinatorRecordId(id) {
+  return id === COORDINATOR_RECORD_ID;
+}
+
+/**
+ * Is this repo-relative path inside a wave's per-agent scope declarations,
+ * `<state-dir>/filescopes/` (shape (a) and the aggregate sidecar, #1020)?
+ *
+ * Those files are coordinator CONTROL STATE like `wave-scope.json` itself,
+ * written by `materialize-wave-scope.mjs` once per wave — never a wave
+ * territory, so a write there is not a scope violation (#1027 Pkt 5). The
+ * caller passes the manifest's own repo-relative path, so the state dir is the
+ * one THIS manifest lives in, never a guessed `.claude/`.
+ *
+ * @param {string} relPath repo-relative, forward slashes
+ * @param {string} scopeRelPath repo-relative path of the active `wave-scope.json`
+ * @returns {boolean}
+ */
+export function isScopeDeclarationPath(relPath, scopeRelPath) {
+  if (typeof relPath !== 'string' || typeof scopeRelPath !== 'string') return false;
+  const scopeRel = scopeRelPath.replace(/\\/g, '/');
+  const cut = scopeRel.lastIndexOf('/');
+  if (cut <= 0) return false;
+  return relPath.startsWith(`${scopeRel.slice(0, cut)}/filescopes/`);
+}
+
 /**
  * Merge many agents' declared file scopes into ONE deduplicated, order-stable
  * list — the mechanical form of "allowedPaths is the UNION of all agent file
@@ -965,6 +1089,14 @@ export function isPeerRecordId(id) {
  * non-array / non-object members and non-string, empty entries are skipped.
  * Pure, sync, no I/O — hook-safe per the module header.
  *
+ * ENTRIES ARE EMITTED IN CANONICAL SPELLING ({@link scopeEntrySpelling}) and
+ * deduplicated on it. Gate 7 matches the repo-relative WRITE path against each
+ * entry, so a verbatim `./scripts/lib/foo.mjs` was a pattern no write could
+ * ever match — the declaring agent's own write was denied — and kept a second
+ * spelling of `scripts/lib/foo.mjs` beside it. The agent-side checks
+ * ({@link assertFileScopeSubset}, {@link testSiblingsFor}) compare the same
+ * spelling, so a per-agent file that keeps the plan's `./x` still passes.
+ *
  * PEER RECORDS ARE EXCLUDED (#1195 follow-through). A record whose id starts
  * with `peer-session-` declares a territory NO agent of this wave may write —
  * it exists so a peer's paths take part in the DISJOINTNESS check and so
@@ -995,9 +1127,10 @@ export function unionFileScopes(scopes) {
     if (files === null) continue;
     for (const entry of files) {
       if (typeof entry !== 'string' || entry.length === 0) continue;
-      if (seen.has(entry)) continue;
-      seen.add(entry);
-      out.push(entry);
+      const spelled = scopeEntrySpelling(entry);
+      if (seen.has(spelled)) continue;
+      seen.add(spelled);
+      out.push(spelled);
     }
   }
   return out;
@@ -1122,8 +1255,11 @@ function globsDisagreeOnLiteralSegment(x, y) {
  * NEGATIVE — the whole point of this function is that an unreviewed scope is
  * exactly the one that collides.
  *
+ * `files` holds each entry's comparison SPELLING ({@link scopeEntrySpelling});
+ * `declared` holds the entry as written, index-aligned, for the evidence report.
+ *
  * @param {Array<{id?: string, files?: string[]}>} agentScopes
- * @returns {Array<{id: string, declaredId: string|null, files: string[]}>}
+ * @returns {Array<{id: string, declaredId: string|null, files: string[], declared: string[]}>}
  */
 function normalizeAgentScopes(agentScopes) {
   const out = [];
@@ -1131,14 +1267,43 @@ function normalizeAgentScopes(agentScopes) {
     const raw = agentScopes[i];
     if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) continue;
     const declaredId = typeof raw.id === 'string' && raw.id.length > 0 ? raw.id : null;
-    const files = Array.isArray(raw.files)
+    const declared = Array.isArray(raw.files)
       ? raw.files.filter((f) => typeof f === 'string' && f.length > 0)
       : [];
-    out.push({ id: declaredId ?? `<unnamed#${i}>`, declaredId, files });
+    const files = declared.map(scopeEntrySpelling);
+    out.push({ id: declaredId ?? `<unnamed#${i}>`, declaredId, files, declared });
   }
   return out;
 }
 
+/**
+ * One scope entry's canonical SPELLING — THE spelling rule of this module.
+ * Used by the collision comparison (#1026.3), by {@link unionFileScopes} (whose
+ * output IS `allowedPaths`, so Gate 7 sees this spelling), and on the agent side
+ * of {@link assertFileScopeSubset} / {@link testSiblingsFor}, so a per-agent file
+ * that keeps the plan's declaration verbatim still agrees with the union.
+ * Equal-meaning spellings compared unequal before: `./scripts/lib/foo.mjs` vs
+ * `scripts/lib/foo.mjs` was reported disjoint (measured 2026-10-03 @ 8292050e).
+ * It changes no grant's MEANING — only how one is spelled.
+ *
+ * Collapses runs of `/` and drops `.` segments (`./a`, `a/./b`). A leading `/`
+ * (absolute entry) and a trailing `/` survive: the trailing slash is meaning,
+ * not spelling — `scripts/lib/` is a prefix grant, while `scripts/lib` grants
+ * only the literal path `scripts/lib` (`pathMatchesPattern('scripts/lib/foo.mjs',
+ * 'scripts/lib') === false`), so those two stay disjoint.
+ *
+ * NAMED CEILING: `..` segments are left alone — `a/../b` is not provably `b`
+ * when `a` is a glob segment. Revisit if a plan ever declares a `..` entry.
+ *
+ * @param {string} entry - a non-empty scope entry
+ * @returns {string}
+ */
+function scopeEntrySpelling(entry) {
+  const spelled = entry.replace(/\/{2,}/g, '/').replace(/(^|\/)(?:\.\/)+/g, '$1');
+  // `./` alone would spell as '' — keep the entry rather than invent a meaning.
+  return spelled.length > 0 ? spelled : entry;
+}
+
 /**
  * Classify a SINGLE cross-agent entry pair, in the binding three-stage order.
  * Returns the collision `kind`, or `null` when the two entries are disjoint.
@@ -1316,17 +1481,19 @@ export function findScopeCollisions(agentScopes, opts = {}) {
       const b = agents[j];
       if (a.id === b.id) continue; // duplicate-id record: reported separately
       const buckets = new Map();
-      for (const x of a.files) {
-        for (const y of b.files) {
-          const kind = classifyEntryCollision(x, y, expand);
+      // Classify on the comparison spelling; report the entry AS DECLARED, so
+      // the operator can find it in the plan (#1026.3).
+      for (let xi = 0; xi < a.files.length; xi++) {
+        for (let yi = 0; yi < b.files.length; yi++) {
+          const kind = classifyEntryCollision(a.files[xi], b.files[yi], expand);
           if (kind === null) continue;
           let evidence = buckets.get(kind);
           if (evidence === undefined) {
             evidence = new Set();
             buckets.set(kind, evidence);
           }
-          evidence.add(x);
-          evidence.add(y);
+          evidence.add(a.declared[xi]);
+          evidence.add(b.declared[yi]);
         }
       }
       for (const kind of KIND_ORDER) {

package/scripts/lib/session-close-backfill.mjs

@@ -64,6 +64,9 @@ import { serializeSessionLineChecked as defaultSerialize } from './session-schem
 import { resolveStateMdPath as defaultResolveStateMdPath } from './state-md/frontmatter-mutators.mjs';
 import { parseStateMd as defaultParseStateMd } from './state-md/yaml-parser.mjs';
 import { canonicalizeSessions } from './sessions-canonical.mjs';
+// Already in the hook import set (`emitEvent` lives there): the rotation-aware
+// reader adds no new file to the SessionStart/SessionEnd hook graph.
+import { scanEventsBackwards } from './events.mjs';
 // Leaf constants module (no imports of its own) and ALREADY in the hook import
 // set via session-schema/validator.mjs — importing it here adds no new file to
 // the SessionStart/SessionEnd hook graph. The profile enum must not be
@@ -326,6 +329,117 @@ function collectSessionEvents(events, { sessionId, semanticSessionId }) {
   };
 }
 
+/**
+ * Events-ledger window for the #1401 census (`events-retention-banner.mjs`):
+ * `null` — {@link gatherSessionEvents} reads back as far as a candidate's own
+ * `session.started`, however old, so no day count bounds it. A cut history
+ * leaves the candidate's oldest events unread: its record then lists
+ * `started_at` among `_backfill_incomplete_fields` — the same answer as before
+ * this reader existed, never a guessed time.
+ */
+export const REQUIRED_EVENTS_WINDOW_DAYS = null;
+
+/**
+ * Every record of the ledger — rotated archives included — whose raw line
+ * contains `id`, oldest first. A backward scan in the existing rotation-aware
+ * reader (`scanEventsBackwards`), reversed: one scan's order is global, so the
+ * file order {@link collectSessionEvents} depends on survives.
+ *
+ * @param {string} eventsPath
+ * @param {string} id
+ * @param {number|null} deadlineMs — epoch ms the scan must end by; `null` = unbounded
+ * @returns {Array<object>|null} `null` when the deadline had passed before the
+ *   scan or cut it short — a partial history is never handed on as a whole one.
+ */
+function recordsMentioning(eventsPath, id, deadlineMs) {
+  let budgetMs;
+  if (deadlineMs !== null) {
+    budgetMs = deadlineMs - Date.now();
+    if (!(budgetMs > 0)) return null;
+  }
+  const newestFirst = [];
+  const { truncated, unreadable } = scanEventsBackwards({
+    filePath: eventsPath,
+    filter: id,
+    budgetMs,
+    onRecord: (record) => {
+      newestFirst.push(record);
+      return false;
+    },
+  });
+  // #1505.5b: a source the walk could not read cut the history exactly like a
+  // deadline does — its records are simply absent — so it defers the candidate
+  // the same way. Ceiling (BV-004): a PERMANENTLY unreadable archive defers its
+  // candidates on every run (`skipped-history-unread`, visible, never a record
+  // dated NOW). `gaps` (pruned/unindexed archives) are deliberately NOT treated
+  // so: the walk reports every gap of the whole ledger, mostly far older than
+  // the candidate, and deferring on any of them would skip the candidate
+  // forever — telling a gap inside the session's window apart needs its
+  // first_ts/last_ts against the session's range, a follow-up.
+  const cut = truncated || (Array.isArray(unreadable) && unreadable.length > 0);
+  return cut ? null : newestFirst.reverse();
+}
+
+/**
+ * {@link collectSessionEvents} over the ACTIVE events.jsonl, and — when that
+ * holds no `session.started` for the candidate — over the whole rotated ledger.
+ *
+ * #1498: `planSessions` reads every archive since #1414, but this core read only
+ * the active file, so a candidate whose events had rotated away gathered
+ * nothing: no `lastEventMs`, hence never dead-by-age and skipped behind a live
+ * foreign lock on every run — or, without a lock, written with `started_at` and
+ * `completed_at` set to NOW. The active read stays first and cheap; the scan
+ * runs only for such a candidate, and once its record is written the CLI's
+ * sessions.jsonl pre-filter skips it on every later run.
+ *
+ * Cost (#1498 review): ≈0.55-0.8 ms per MB of ledger per such candidate —
+ * measured 2026-10-02: 25 candidates over a synthetic 58 MB ledger of six
+ * sources took 1.17-1.20 s, active reads included, at load average ~20; the
+ * review measured +0.80-0.87 s for the scans alone at 60 MB and load ~7. That
+ * does not fit the 5 s SessionStart hook unbounded, so a caller may pass
+ * `deadlineMs`: ONE epoch-ms deadline shared by every candidate of a run. A
+ * scan the deadline skipped or cut returns `historyUnread: true` instead of a
+ * partial answer, and the caller defers the candidate — never the active-file
+ * answer, which for such a candidate is a record dated NOW (see above) that the
+ * dedupe would then keep forever.
+ *
+ * One filtered scan keeps the order exact: a native UUID appears on every event
+ * of its session. Without one, the semantic label is scanned for the UUID
+ * bridge, then that UUID's events. Named ceiling (BV-004): a label bridging to
+ * SEVERAL UUIDs would need several scans merged without a shared order, so it
+ * keeps the active-file answer — revisit if a backfill record shows
+ * `started_at` among its incomplete fields while the archive holds it.
+ *
+ * @param {Function} readFileSync
+ * @param {string} eventsPath
+ * @param {{ sessionId: string|null, semanticSessionId: string|null }} ids
+ * @param {number|null} [deadlineMs=null] — shared scan deadline (epoch ms); `null` = unbounded
+ * @returns {ReturnType<typeof collectSessionEvents> & { historyUnread?: true }}
+ */
+function gatherSessionEvents(readFileSync, eventsPath, ids, deadlineMs = null) {
+  const gathered = collectSessionEvents(readJsonlSafe(readFileSync, eventsPath), ids);
+  if (gathered.startedAt !== null) return gathered;
+  try {
+    let uuid = isUuid(ids.sessionId) ? ids.sessionId : null;
+    if (uuid === null) {
+      const label = ids.semanticSessionId || ids.sessionId;
+      if (!label) return gathered;
+      const bridge = recordsMentioning(eventsPath, label, deadlineMs);
+      if (bridge === null) return { ...gathered, historyUnread: true };
+      const bridged = collectSessionEvents(bridge, ids).uuids;
+      if (bridged.size !== 1) return gathered;
+      [uuid] = bridged;
+    }
+    const history = recordsMentioning(eventsPath, uuid, deadlineMs);
+    if (history === null) return { ...gathered, historyUnread: true };
+    // Empty only when the scan found no source at all — e.g. a reader seam the
+    // filesystem does not back; the active answer stands.
+    return history.length > 0 ? collectSessionEvents(history, ids) : gathered;
+  } catch {
+    return gathered;
+  }
+}
+
 /**
  * Determine whether a candidate should be treated as dead-by-age DESPITE a
  * live FOREIGN session.lock (#731 — the historical migration CLI blocks
@@ -724,6 +838,11 @@ function checkAlreadyRecorded(readFileSync, sessionsPath, { recordId, sessionId
  *   `lastEventMs` strictly predates this value bypasses a foreign live lock
  *   regardless of `relaxDeadByAge`. Corresponds to the CLI's
  *   `--assume-dead-before <ISO>` flag.
+ * @param {number|null} [args.archiveScanDeadlineMs=null]
+ *   #1498 — epoch ms by which a scan of the ROTATED ledger must end; one value
+ *   shared by every candidate of a run (see `gatherSessionEvents`). A candidate
+ *   whose history the deadline left unread returns `skipped-history-unread`
+ *   and is retried by the next run. `null` (CLI, SessionEnd) = unbounded.
  * @param {object}  [args.deps]                   DI overrides (fs, appendJsonl, readLock, …)
  * @returns {Promise<object>}
  */
@@ -736,6 +855,7 @@ export async function backfillAbandonedSession({
   relaxDeadByAge = false,
   ownSessionIsEnding = false,
   assumeDeadBeforeMs = null,
+  archiveScanDeadlineMs = null,
   deps = {},
 } = {}) {
   const {
@@ -795,8 +915,14 @@ export async function backfillAbandonedSession({
       }
 
       // -- Read events (needed to synthesize, and to bridge UUID→semantic) ----
-      const events = readJsonlSafe(readFileSync, eventsPath);
-      const gathered = collectSessionEvents(events, { sessionId, semanticSessionId });
+      const gathered = gatherSessionEvents(
+        readFileSync, eventsPath, { sessionId, semanticSessionId }, archiveScanDeadlineMs,
+      );
+      // Deferred, never answered from the active file alone: for this candidate
+      // that answer is a record dated NOW, which the dedupe keeps forever.
+      if (gathered.historyUnread) {
+        return { action: 'skipped-history-unread', sessionId: recordId ?? sessionId };
+      }
 
       // -- Resolve a deferred id from the lock bridge or a synthetic mint ------
       if (recordId === null) {
@@ -1153,8 +1279,7 @@ export async function backfillCompletedFromStateMd({
 
       // -- Derive whatever is derivable from events.jsonl (never STATE.md body) -
       const eventsPath = path.join(repoRoot, ...EVENTS_REL);
-      const events = readJsonlSafe(readFileSync, eventsPath);
-      const gathered = collectSessionEvents(events, { sessionId: nativeId, semanticSessionId });
+      const gathered = gatherSessionEvents(readFileSync, eventsPath, { sessionId: nativeId, semanticSessionId });
 
       // -- Synthesize + validate (round-trip gate) BEFORE any disk mutation ----
       const record = synthesizeRecord({

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

@@ -45,6 +45,8 @@
  * @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 {number}  [malformed]    - unparseable store lines kept verbatim, never
+ *                                      archived (ran only; a measured `0` when none).
  * @property {string}  [archivePath]  - the archive sidecar written to (ran only).
  */
 
@@ -88,10 +90,10 @@ function findPhaseDecision(plan, phase) {
  * 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
+ * @param {{repoRoot: string, scanned: number, archived: number, malformed: number}} ctx
  * @returns {Promise<void>}
  */
-async function emitSweepApplied({ repoRoot, scanned, archived }) {
+async function emitSweepApplied({ repoRoot, scanned, archived, malformed }) {
   if (typeof repoRoot !== 'string' || repoRoot.trim() === '') {
     process.stderr.write(
       `tail-runner: skipped ${SWEEP_EVENT} — no repoRoot given; ` +
@@ -103,7 +105,7 @@ async function emitSweepApplied({ repoRoot, scanned, archived }) {
     const { emitEvent, sessionAttribution } = await import('../events.mjs');
     await emitEvent(
       SWEEP_EVENT,
-      { scanned, archived, source: SWEEP_SOURCE, ...sessionAttribution(repoRoot) },
+      { scanned, archived, malformed, source: SWEEP_SOURCE, ...sessionAttribution(repoRoot) },
       { repoRoot },
     );
   } catch {
@@ -151,9 +153,12 @@ export async function runExpiredSweep({ repoRoot, plan, now, graceDays, emit = t
 
     const scanned = res?.scanned ?? 0;
     const archived = res?.archived ?? 0;
-    if (emit) await emitSweepApplied({ repoRoot, scanned, archived });
+    // The sweep result omits `malformed` when the read found none, so absent IS
+    // a measured 0 here — carried as a number like its two siblings (HR-105).
+    const malformed = res?.malformed ?? 0;
+    if (emit) await emitSweepApplied({ repoRoot, scanned, archived, malformed });
 
-    return { ran: true, scanned, archived, archivePath: res?.archivePath ?? archivePath };
+    return { ran: true, scanned, archived, malformed, archivePath: res?.archivePath ?? archivePath };
   } catch (err) {
     // Fail CLOSED (see the module header): a maintenance sweep must never be
     // able to block a session close.

package/scripts/lib/session-lock-shape.mjs

@@ -25,9 +25,12 @@
  * @param {unknown} obj — a value already parsed from JSON.
  * @returns {boolean} true when `obj` carries all six required lock fields with
  *   the right primitive types. `semantic_session_id` and `last_heartbeat` are
- *   deliberately NOT required — both are optional by schema (v1 locks predate
- *   `last_heartbeat`, and `semantic_session_id` is absent on harnesses that
- *   resolve no semantic id).
+ *   deliberately NOT required. `semantic_session_id` is absent on harnesses
+ *   that resolve no semantic id. A lock without `last_heartbeat` must stay
+ *   shape-valid so it remains VISIBLE: since the #595 sunset (2026-10-02)
+ *   `isLockLive()` calls it not live and `acquire()` classifies it
+ *   `stale-heartbeat`, so the bootstrap reclaims it. Requiring the field here
+ *   would hide it from every `readLock()` caller instead.
  */
 export function isLockShape(obj) {
   return (