session-orchestrator 3.22.0 → 3.23.0

package/scripts/lib/session-transition.mjs

@@ -0,0 +1,277 @@
+/**
+ * session-transition.mjs — the PROCESS-BOUNDARY teardown of a source repo root.
+ *
+ * Issue #1069 ("EnterWorktree/CwdChanged als eindeutigen Ein-Root-Übergang
+ * modellieren"), operator decision 2026-08-28: **Prozessgrenze**, not live
+ * migration. The source session ENDS regularly in the old root; a NEW session
+ * with its own identity starts in the destination worktree. Nothing is
+ * transferred — no lock hand-off, no registry rewrite, no proof migration.
+ *
+ * The gap this closes: session-start Phase 0.5 Worktree-Promotion calls
+ * `enterWorktree()` and then "exits Phase 0 immediately". It released nothing
+ * on the OLD root (measured 2026-08-28: zero `deregisterSelf` / `release(`
+ * call sites across `skills/session-start/SKILL.md` and
+ * `skills/_shared/parallel-aware-auq.md`). The abandoned registry entry keeps
+ * reading FRESH to `detectPeers()` for `freshnessMin=15` minutes and is only
+ * removed by `sweepZombies()` after `thresholdMin=60` — so the promoted-away
+ * root advertises a PHANTOM peer for up to an hour, and the abandoned
+ * `session.lock` blocks/skews every exclusivity decision in that root until
+ * its TTL lapses.
+ *
+ * Ownership rules are NOT re-derived here. The lock half is the same shape
+ * `hooks/on-session-end.mjs` uses: `readLockDetailed()` to distinguish an
+ * absent lock from an unparseable one, an exact raw `lock.session_id ===
+ * sessionId` compare BEFORE any proof is loaded, then `loadOwnerProof()`
+ * handed to `release()` as the second identity factor (#987/#989).
+ *
+ * ## Deliberate deltas vs `hooks/on-session-end.mjs` (its release block)
+ *
+ * The two teardowns share the ownership gate and now the
+ * `orchestrator.session.lock.released` breadcrumb, and diverge in four places
+ * ON PURPOSE. Each divergence is a narrower authority, never an oversight:
+ *
+ *  1. **No reconciliation on a raw-ID mismatch.** SessionEnd calls
+ *     `attemptLockReconciliation()`, which may reap a provably-dead foreign
+ *     lease. A worktree promotion is not a lifecycle end for the foreign
+ *     session and carries no mandate over its lease: this function returns
+ *     `lock-session-mismatch:<owner>` and touches nothing.
+ *  2. **No owner-proof unlink after a successful release.** SessionEnd removes
+ *     the genesis proof as hygiene because the session is ending. Here the
+ *     session continues in the DESTINATION root; the source proof is
+ *     self-invalidating (its millisecond `started_at` can never match a future
+ *     lock) and deleting it would be a write outside the teardown's remit.
+ *  3. **No `orchestrator.session.lock.read_anomaly` breadcrumb.** An
+ *     unparseable lock aborts this teardown outright and is reported in the
+ *     RETURN value (`ok: false`, `reason: 'lock-unreadable'|'lock-corrupt'`),
+ *     which the caller must surface as a WARN. SessionEnd has no return channel
+ *     to its caller, so there the event is the only place the anomaly can land.
+ *  4. **No `orchestrator.session.lock.release_failed` breadcrumb.** Same
+ *     reason as (3): a failed release surfaces as `ok: false` plus
+ *     `reason: 'lock-<release-reason>'` to a caller that is required to WARN on
+ *     it, so the stream is not the only witness.
+ *
+ * @module scripts/lib/session-transition
+ */
+
+import path from 'node:path';
+
+import { deregisterSelf, readRegistry, repoPathHash } from './session-registry.mjs';
+import { readLockDetailed, loadOwnerProof, release } from './session-lock.mjs';
+import { emitEvent } from './events.mjs';
+
+/** Event name emitted once per completed source-root departure. */
+export const ROOT_LEFT_EVENT = 'orchestrator.session.root_left';
+
+/** Shared lock-release breadcrumb — same event the other two `release()` call sites emit. */
+export const LOCK_RELEASED_EVENT = 'orchestrator.session.lock.released';
+
+/**
+ * Release this session's claim on `repoRoot` because the session is leaving it
+ * for good. Ordering is load-bearing and fixed:
+ *
+ *   1. `readLockDetailed()` — OWNERSHIP IS ESTABLISHED BEFORE ANYTHING IS
+ *      REMOVED. A lock this session does not own, or one that cannot be parsed,
+ *      aborts the teardown with `ok: false` and zero side effects. (This used to
+ *      run second, after the registry entry had already been deleted: a caller
+ *      passing the wrong `sessionId` destroyed a live registry entry and was
+ *      told `ok: true` — the registry half of the very phantom-peer state the
+ *      function exists to prevent.)
+ *   2. `deregisterSelf(sessionId)` — the host-wide registry entry. The registry
+ *      is one file per harness session id, so this removes the session's ONLY
+ *      entry; the destination worktree's own SessionStart registers itself
+ *      afresh under its own identity (that is what "process boundary" means).
+ *      Gated a second time on the entry's `repo_path_hash`: an entry that
+ *      describes a DIFFERENT root is not this root's claim, and deleting it
+ *      would silently unregister a session living somewhere else.
+ *   3. `release()` of the old root's `session.lock`, gated exactly as
+ *      `hooks/on-session-end.mjs` gates it, followed by the shared
+ *      `orchestrator.session.lock.released` breadcrumb (`caller:
+ *      'session-transition'`) so this third `release()` call site is visible on
+ *      the same stream as the other two.
+ *   4. `emitEvent(ROOT_LEFT_EVENT)` into the OLD root's events.jsonl — the
+ *      breadcrumb that says which root was left and why. Emitted even when a
+ *      step above found nothing: "nothing to release" is itself a fact worth
+ *      recording, and a departure that left no trace is exactly the
+ *      indistinguishable-from-a-crash state #1069 was filed about. NOT emitted
+ *      on an aborted teardown (foreign lock, unparseable lock, invalid args):
+ *      the event asserts that a root was LEFT, and on those branches nothing
+ *      was — writing it would put a fiction in a stream that, unlike the
+ *      registry, may belong to the session that actually owns this root.
+ *
+ * The caller must invoke this BEFORE the destination worktree's own Phase 1.2
+ * `acquire()` runs — never both roots owning a live lock/registry entry at
+ * once, which is the double-live-UUID state the issue's acceptance criteria
+ * forbid.
+ *
+ * NEVER THROWS. Every failure is reported in the returned structure, because
+ * the sole caller is a promotion path that has already created the destination
+ * worktree: a thrown error there would abort the transition halfway, leaving
+ * precisely the two-live-roots state this function exists to prevent.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot — absolute path of the root being LEFT.
+ * @param {string} args.sessionId — the raw (physical) session id that owns the
+ *   registry entry and the lock in `repoRoot`. NOT the semantic id.
+ * @param {string|null} [args.semanticSessionId] — semantic id, when known.
+ *   Omitted from the event payload when null/absent rather than emitted as
+ *   `null` (same honest-encoding rule as `sessionAttribution()` in events.mjs).
+ * @param {string} [args.reason='unspecified'] — why the root is being left,
+ *   e.g. `'worktree-promotion'`. Recorded verbatim in the event payload.
+ *   Defaults to `'unspecified'` rather than guessing `'worktree-promotion'`:
+ *   a mislabelled reason is worse than an admittedly unknown one.
+ * @param {object} [deps] — test seams (same shape as `foreign-dispatch.mjs`).
+ * @param {Function} [deps.emitFn] — event-emitter seam; defaults to `emitEvent`.
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   steps: { deregistered: boolean, released: boolean, emitted: boolean },
+ *   reason?: string
+ * }>}
+ *   `steps` are literal outcomes: `deregistered` = a registry file was removed,
+ *   `released` = the lock file was deleted, `emitted` = the `root_left` event
+ *   was appended.
+ *
+ *   `ok: false` means the departure is NOT provably complete — invalid input, a
+ *   lock owned by someone else, an unparseable lock, a registry entry pinned to
+ *   a different root, a registry unlink that failed, a contradictory owner
+ *   proof, or a filesystem error. Callers WARN on it and continue; see the
+ *   `parallel-aware: leaveSourceRoot: <reason>` contract in
+ *   `skills/_shared/parallel-aware-auq.md`.
+ *
+ *   `reason` is present whenever something other than a full clean teardown
+ *   happened; `'already-gone'` is the idempotent-rerun case (nothing left to
+ *   remove), which is `ok: true`.
+ */
+export async function leaveSourceRoot({
+  repoRoot,
+  sessionId,
+  semanticSessionId = null,
+  reason = 'unspecified',
+} = {}, deps = {}) {
+  const emit = deps.emitFn ?? emitEvent;
+  const steps = { deregistered: false, released: false, emitted: false };
+
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0
+    || typeof sessionId !== 'string' || sessionId.length === 0) {
+    // Nothing is attempted on unusable input — in particular no event, since
+    // an event without a resolvable root has nowhere honest to be written.
+    return { ok: false, steps, reason: 'invalid-args' };
+  }
+
+  // -- Step 1: ownership, BEFORE any removal --------------------------------
+  // Mirrors hooks/on-session-end.mjs's release block: discriminate the read
+  // first, compare the RAW session_id before touching the proof, and only then
+  // hand the proof to release() as a second factor. An 'absent' lock is the
+  // idempotent-rerun / never-acquired case and does NOT block the teardown.
+  const lockDetail = readLockDetailed({ repoRoot });
+
+  if (lockDetail.status === 'unreadable' || lockDetail.status === 'corrupt') {
+    // Fail-closed and VISIBLE (issue #1069 AC: "fehlende oder widersprüchliche
+    // Proofs degradieren sichtbar und fail-closed"). A lock we cannot parse is
+    // neither released nor proven foreign — ownership stays indeterminate, so
+    // nothing is removed and nothing is claimed.
+    return { ok: false, steps, reason: `lock-${lockDetail.status}` };
+  }
+
+  if (lockDetail.status === 'ok' && lockDetail.lock.session_id !== sessionId) {
+    // A different session owns this root's lock, so this root is not ours to
+    // tear down — not the lock, and not the registry entry either. Aborting
+    // with `ok: false` (rather than the pre-#1069-review `ok: true`) is the
+    // point: a caller that passed the wrong id has NOT departed anything, and
+    // reporting success let that mistake through silently.
+    return { ok: false, steps, reason: `lock-session-mismatch:${lockDetail.lock.session_id}` };
+  }
+
+  let ok = true;
+  let outcome = null;
+
+  // -- Step 2: registry (host-wide) -----------------------------------------
+  // Second ownership factor, on the registry's own terms: the entry records the
+  // root it belongs to as a hash. When it names a DIFFERENT root, the entry is
+  // some other checkout's live claim and unlinking it would unregister a
+  // session that is still running there. Legacy v1 entries carry no hash — the
+  // gate is skipped rather than fail-closed, because rejecting them would make
+  // this teardown a no-op against exactly the old entries most likely to be
+  // stale (same back-compat rule as `_validEntry`'s optional `mode`).
+  let registryGateOk = true;
+  try {
+    const entry = (await readRegistry()).find((e) => e.session_id === sessionId);
+    if (entry && typeof entry.repo_path_hash === 'string' && entry.repo_path_hash.length > 0
+      && entry.repo_path_hash !== repoPathHash(repoRoot)) {
+      registryGateOk = false;
+      ok = false;
+      outcome ??= 'registry-root-mismatch';
+    }
+  } catch { /* an unreadable registry is handled by deregisterSelf below */ }
+
+  if (registryGateOk) {
+    try {
+      steps.deregistered = await deregisterSelf(sessionId);
+    } catch (err) {
+      ok = false;
+      outcome ??= `deregister-failed:${err?.message ?? 'unknown'}`;
+    }
+  }
+
+  // -- Step 3: lock (this root only) ----------------------------------------
+  if (lockDetail.status === 'ok') {
+    const proof = loadOwnerProof({ repoRoot });
+    // `proof` is null whenever ownership cannot be proven; release() treats
+    // null as absent (#989) and degrades to the session_id-only path, so it
+    // is passed through unguarded — the spread-guard call sites needed
+    // before that fix are exactly what the API contract removed.
+    const result = release({ sessionId, repoRoot, proof });
+    steps.released = result.ok === true && result.deleted === true;
+    // 'no-lock' = the lock vanished between the read above and the release —
+    // benign (idempotent rerun / concurrent SessionEnd), and forensically the
+    // interesting half: someone else removed a lock we still held.
+    const alreadyGone = result.ok === true && result.reason === 'no-lock';
+    if (!steps.released) {
+      if (!alreadyGone) ok = false;
+      outcome ??= `lock-${result.reason ?? 'not-deleted'}`;
+    }
+    if (steps.released || alreadyGone) {
+      // ARCH-MED-1 — this is the THIRD `release()` call site in the repo and
+      // was the only one silent on `orchestrator.session.lock.*`. Emitted at
+      // the call site, never inside release(): session-lock.mjs carries no
+      // dependency on events.mjs, and release() is synchronous.
+      try {
+        await emit(LOCK_RELEASED_EVENT, {
+          session_id: sessionId,
+          ...(semanticSessionId ? { semantic_session_id: semanticSessionId } : {}),
+          caller: 'session-transition',
+          outcome: steps.released ? 'deleted' : 'already-gone',
+          verified: result.verified === true,
+        }, { repoRoot });
+      } catch { /* observability is best-effort — the return value still tells */ }
+    }
+  }
+
+  if (outcome === null && !steps.deregistered && !steps.released) {
+    outcome = 'already-gone';
+  }
+
+  // -- Step 4: breadcrumb ----------------------------------------------------
+  try {
+    await emit(ROOT_LEFT_EVENT, {
+      session_id: sessionId,
+      ...(semanticSessionId ? { semantic_session_id: semanticSessionId } : {}),
+      // NEVER the absolute path. emitEvent forwards the whole payload to the
+      // optional Clank webhook with no redaction, and an absolute repo root on
+      // this host is `/Users/<operator>/…`. The hash is the SAME function the
+      // session registry keys its entries by (`repo_path_hash`), so a consumer
+      // can still join a departure to the registry entry it removed; the
+      // basename matches the registry's `repo_name`. Same rule as the
+      // `board_written` / `mirror_completed` payloads and
+      // `relativeWorktreePath` in worktree-pipeline.mjs.
+      from_root_hash: repoPathHash(repoRoot),
+      from_root_basename: path.basename(path.resolve(repoRoot)),
+      reason,
+    }, { repoRoot });
+    steps.emitted = true;
+  } catch (err) {
+    ok = false;
+    outcome ??= `emit-failed:${err?.message ?? 'unknown'}`;
+  }
+
+  return outcome === null ? { ok, steps } : { ok, steps, reason: outcome };
+}

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

@@ -20,11 +20,15 @@
  * 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, 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.
+ *   - `lastLedgerAt`      = the NEWEST instant any PARSEABLE `sessions.jsonl`
+ *                           record proves the ledger was alive at — a genuine
+ *                           record contributes its `completed_at` (or, absent
+ *                           one, its `started_at`), a backfill stub
+ *                           contributes ONLY its `started_at`. See
+ *                           "Backfill-stub self-erasure fix" below for why the
+ *                           stub's `completed_at` is excluded, and "#1125 —
+ *                           newest-across-all, not genuine-first" for why the
+ *                           two kinds are maxed rather than ranked.
  *   - `cutoff`            = the CURRENT session's `session.lock`
  *                           `started_at` (via `readLock()`); when no lock is
  *                           readable, `cutoff = now` (all events count).
@@ -58,24 +62,50 @@
  * 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
+ * chosen: a stub's `completed_at` is NEVER an anchor candidate. 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.
+ * #1125 — newest-across-ALL records, not genuine-first: excluding the stub's
+ * `completed_at` (above) is correct; excluding the whole STUB from the anchor
+ * search was not. The original implementation scanned from EOF backward and
+ * returned the first GENUINE record it met, reaching the stub `started_at`
+ * fallback only when no genuine record existed ANYWHERE. That is a PRIORITY
+ * ORDER, and it lets an OLD genuine record outrank a NEWER stub: whenever the
+ * most recent ledger activity is a stub, the anchor fell back to a stale
+ * genuine `completed_at` and the reported gap ballooned by the difference.
+ * Measured in the vault repo 2026-08-22 (issue #1125): a 173h `alert` — the
+ * probe's TOP severity — against a ledger whose newest records were from the
+ * same day, contradicted by three independent counter-measurements (231 of 233
+ * records carrying `completed_at`, newest `2026-08-22T16:23Z`;
+ * `backfill-abandoned-sessions.mjs --dry-run` finding 0 to backfill; all 15
+ * sessions since 2026-08-15 closed). A permanent top-severity false alarm
+ * trains exactly the looking-away this probe exists to prevent, so it is a
+ * defect of the same class as a missed gap, not a cosmetic one.
+ *
+ * The anchor is therefore the MAXIMUM over every record's own contribution:
+ *   - GENUINE record → its `completed_at`; or, when that field is absent or
+ *     unparseable, its `started_at` as a floor.
+ *   - BACKFILL STUB  → its `started_at` ONLY (never the fabricated
+ *     `completed_at` — that is the axis-(a) rule above).
+ * A stub written for an abandoned session still PROVES the ledger was alive at
+ * that instant: that session IS recorded (as abandoned), so activity around it
+ * is not evidence of an unrecorded close-through. Taking a MAX can only move
+ * the anchor FORWARD relative to the genuine-only anchor, so it never
+ * re-introduces axis (b)'s inflation of `deltaHours`.
+ *
+ * Stub-anchored reporting (deliberately NOT null): when the winning anchor is a
+ * stub's `started_at` — either because every record is a stub (no session has
+ * EVER genuinely closed, a STRONGER close-through signal than an ordinary stale
+ * ledger) or merely because the newest ledger activity happens to be a stub —
+ * the result carries `stubFallback: true` so the message can say the anchor is
+ * a stub `started_at` (grounded in the real `orchestrator.session.started`
+ * event in the common case — see `synthesizeRecord()`) rather than imply a
+ * measured close. 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.
  *
  * Severity: warn above `2 × DEFAULT_TTL_HOURS` (8h, imported from
  * `session-lock.mjs` rather than duplicated), alert above 24h.
@@ -158,57 +188,92 @@ function isBackfillStub(record) {
 }
 
 /**
- * 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.
+ * Parse one record field into an anchor candidate. Returns `null` when the
+ * field is absent, not a string, or not a parseable timestamp.
  *
- * 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 {unknown} value
+ * @returns {{iso: string, ms: number}|null}
+ */
+function tsCandidate(value) {
+  if (typeof value !== 'string') return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? { iso: value, ms } : null;
+}
+
+/**
+ * Keep whichever of the two candidates is newer. A `null` candidate never
+ * displaces a real one. On an exact tie the LATER-seen candidate wins, which
+ * (with the forward scan in `lastLedgerEntry()`) preserves the previous
+ * "nearest-EOF record wins" tie-break.
+ *
+ * @param {{iso: string, ms: number}|null} current
+ * @param {{iso: string, ms: number}|null} candidate
+ * @returns {{iso: string, ms: number}|null}
+ */
+function keepNewer(current, candidate) {
+  if (candidate === null) return current;
+  if (current === null) return candidate;
+  return candidate.ms >= current.ms ? candidate : current;
+}
+
+/**
+ * Scan all `sessions.jsonl` lines and return the anchor instant to measure
+ * ledger staleness against: the NEWEST instant any record proves the ledger
+ * was alive at. Malformed or non-conforming lines (bad JSON, non-object) are
+ * skipped, not treated as fatal.
+ *
+ * Which timestamp each record kind contributes, and why (full reasoning in the
+ * module header, "#1125 — newest-across-ALL records"):
+ *   - GENUINE (`!isBackfillStub()`) → `completed_at`, written by the real
+ *     session-end path; falling back to `started_at` when `completed_at` is
+ *     absent or unparseable, so a truncated/in-flight record still contributes
+ *     the coverage it does prove. Taking the newer of the two can only move the
+ *     anchor forward, never backward, so it does not inflate `deltaHours`.
+ *   - BACKFILL STUB → `started_at` ONLY. Its `completed_at` may be the backfill
+ *     RUN's own wall-clock rather than a measurement of when the session ended
+ *     (see `synthesizeRecord()`), and anchoring on that would let a backfill run
+ *     retroactively erase a real multi-day gap.
+ *
+ * The two kinds are MAXED, not ranked: an older genuine record must not outrank
+ * a newer stub (that priority order was the #1125 false-alert defect). When the
+ * winning candidate is a stub's `started_at`, `stubFallback: true` is set on the
+ * result so the caller can say the anchor is a stub start, not a measured close;
+ * the key is omitted (`undefined`) on the genuine path.
  *
  * @param {string[]} lines
  * @returns {{iso: string, ms: number, stubFallback?: true}|null}
  */
 function lastLedgerEntry(lines) {
-  let newestStub = null; // newest-by-position stub with a parseable started_at
+  let newestGenuine = null; // newest genuine completed_at (or started_at floor)
+  let newestStub = null; // newest stub started_at
 
-  for (let i = lines.length - 1; i >= 0; i--) {
+  for (const line of lines) {
     let record;
     try {
-      record = JSON.parse(lines[i]);
+      record = JSON.parse(line);
     } catch {
       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 };
-      }
+      newestStub = keepNewer(newestStub, tsCandidate(record.started_at));
       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 };
+    let own = tsCandidate(record.completed_at);
+    const started = tsCandidate(record.started_at);
+    // `completed_at` is the normal anchor and wins ties; `started_at` only
+    // takes over when it is genuinely newer or `completed_at` is unusable.
+    if (started !== null && (own === null || started.ms > own.ms)) own = started;
+    newestGenuine = keepNewer(newestGenuine, own);
   }
 
-  // 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;
+  if (newestGenuine === null && newestStub === null) return null;
+
+  const stubWins = newestGenuine === null || (newestStub !== null && newestStub.ms > newestGenuine.ms);
+  if (stubWins) return { iso: newestStub.iso, ms: newestStub.ms, stubFallback: true };
+  return { iso: newestGenuine.iso, ms: newestGenuine.ms };
 }
 
 /**
@@ -282,7 +347,7 @@ function resolveCutoffMs(repoRoot, nowMs) {
  * 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`),
+ * When the newest anchor is a backfill stub (`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.
  *
@@ -327,11 +392,13 @@ 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.
+    // stubFallback (see lastLedgerEntry()): the newest anchor in sessions.jsonl
+    // is a backfill stub — ledger.iso is that STUB's started_at, not a measured
+    // completed_at. Say so explicitly rather than implying a real close. (The
+    // wording deliberately does NOT claim "stub-only": since #1125 a stub can
+    // win the anchor while older genuine records exist.)
     const ledgerDescription = ledger.stubFallback
-      ? `last sessions.jsonl entry is backfill-stub-only — newest stub started_at ${ledger.iso}`
+      ? `newest sessions.jsonl entry is a backfill stub — its started_at ${ledger.iso}`
       : `last sessions.jsonl entry ${ledger.iso}`;
 
     const base =