session-orchestrator 5.6.0 → 5.8.0

package/scripts/lib/eval/engine.mjs

@@ -1,7 +1,7 @@
 /**
  * eval/engine.mjs — deterministic session-eval engine for the aiat-llm-eval
  * standard (Epic #803, S3). Scores ONE completed orchestrator session against
- * the rubric-v2 dimensions using ONLY local metrics files
+ * the rubric-v3 dimensions using ONLY local metrics files
  * (sessions.jsonl + events.jsonl AND its rotated `_archive/`, #1407 — the
  * scored window is a PAST one and may predate the last rotation). Missing
  * source data ⇒ `cannot-determine`
@@ -18,7 +18,14 @@
  * `--verify` path checks. provenance.engine_commit / harness.hostname_hash may
  * vary across machines/commits but are EXCLUDED from the per-dimension diff.
  *
- * ── rubric-v2 DIMENSIONS (pre-registered verbatim in skills/eval/rubric-v2.md) ─
+ * ── rubric-v3 DIMENSIONS (pre-registered verbatim in skills/eval/rubric-v3.md) ─
+ *
+ * rubric-v3 (#1487) changes ONE rule against v2: a quality_gate event is
+ * FAILED when `exit_code !== 0`, `timed_out === true`, or the event is
+ * `orchestrator.quality_gate.failed` (`isFailedGateEvent`). v2 read the exit
+ * code only, so a killed reporting-variant run (exit 0 by design, #1459)
+ * scored `pass`. Stored v2 records are never re-scored: `--verify` reports
+ * VERSION-MISMATCH across versions.
  *
  *   verification-evidence  quality_gate events in the (clean) window all green
  *   plan-fidelity          effectiveness.completion_rate vs the v1 threshold
@@ -50,6 +57,7 @@ import { execFileSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { resolveEventsLedgerRoot } from '../platform.mjs';
 
 import { resolvePluginRoot } from '../common.mjs';
 import { readEventsWithRotations } from '../events.mjs';
@@ -59,10 +67,10 @@ import { buildRunId, CURRENT_STANDARD_VERSION, VALID_MODEL_SOURCES } from './sch
 import { resolveSession, computeWindow, findPeerOverlap } from './session-resolve.mjs';
 
 /** The rubric version this engine scores against. */
-export const RUBRIC_VERSION = 'rubric-v2';
+export const RUBRIC_VERSION = 'rubric-v3';
 
 /** Rubric location relative to the plugin root. */
-export const RUBRIC_RELATIVE_PATH = 'skills/eval/rubric-v2.md';
+export const RUBRIC_RELATIVE_PATH = 'skills/eval/rubric-v3.md';
 
 /**
  * Default rubric location, resolved against the PLUGIN root rather than the
@@ -89,7 +97,7 @@ export const DEFAULT_RUBRIC_PATH = (() => {
   }
 })();
 
-/** Ordered rubric-v2 dimension ids — the canonical scoring order. */
+/** Ordered rubric-v3 dimension ids — the canonical scoring order. */
 export const RUBRIC_DIMENSION_IDS = Object.freeze([
   'verification-evidence',
   'plan-fidelity',
@@ -124,6 +132,22 @@ const QUALITY_GATE_EVENTS = new Set([
   'orchestrator.quality_gate.failed',
 ]);
 
+/**
+ * rubric-v3 § 1 "Failed gate event" (#1487): a quality_gate event is failed
+ * when its exit code is non-zero, when its timeout ladder killed it
+ * (`timed_out: true`), or when the gate itself recorded the run as
+ * `orchestrator.quality_gate.failed`. The reporting variants of
+ * `scripts/run-quality-gate.mjs` keep `exit_code: 0` on a killed run (#1459),
+ * so the exit code alone scored that run green. Both gate dimensions use this
+ * one predicate so they can never disagree about the same event.
+ *
+ * @param {{event?: string, exit_code?: unknown, timed_out?: unknown}} e
+ * @returns {boolean}
+ */
+export function isFailedGateEvent(e) {
+  return e.exit_code !== 0 || e.timed_out === true || e.event === 'orchestrator.quality_gate.failed';
+}
+
 function isNonEmptyString(v) {
   return typeof v === 'string' && v.trim().length > 0;
 }
@@ -223,12 +247,12 @@ function countAttributedEvents(ctx, eventName) {
 // ---------------------------------------------------------------------------
 
 /**
- * verification-evidence: ≥1 quality_gate event in the clean window ∧ all
- * exit_code==0 → pass; any exit_code≠0 → fail; 0 events ∧ total_files_changed==0
+ * verification-evidence: ≥1 quality_gate event in the clean window ∧ none
+ * failed (`isFailedGateEvent`) → pass; any failed → fail; 0 events ∧ total_files_changed==0
  * → not-applicable; 0 events otherwise / peer-contaminated window → cannot-determine.
  *
  * Exported ONLY so `tests/eval/rubric-parity.test.mjs` can drive it row-by-row
- * against the pre-registered table in `skills/eval/rubric-v2.md`. NOT a public
+ * against the pre-registered table in `skills/eval/rubric-v3.md`. NOT a public
  * contract: signature, arguments and return shape may change with the rubric.
  */
 export function scoreVerificationEvidence(ctx) {
@@ -266,20 +290,20 @@ export function scoreVerificationEvidence(ctx) {
     };
   }
 
-  const failing = gates.filter((g) => g.exit_code !== 0);
+  const failing = gates.filter(isFailedGateEvent);
   if (failing.length === 0) {
     return {
       id,
       method,
       status: 'pass',
-      evidence: `attribution: time-window. ${gates.length} quality_gate event(s) in window, all exit_code=0.`,
+      evidence: `attribution: time-window. ${gates.length} quality_gate event(s) in window, all exit_code=0, none timed_out or recorded failed.`,
     };
   }
   return {
     id,
     method,
     status: 'fail',
-    evidence: `attribution: time-window. ${gates.length} quality_gate event(s) in window; ${failing.length} with non-zero exit_code.`,
+    evidence: `attribution: time-window. ${gates.length} quality_gate event(s) in window; ${failing.length} failed (non-zero exit_code, timed_out or quality_gate.failed).`,
   };
 }
 
@@ -290,7 +314,7 @@ export function scoreVerificationEvidence(ctx) {
  * work → cannot-determine. score = completion_rate (informative).
  *
  * Exported ONLY so `tests/eval/rubric-parity.test.mjs` can drive it row-by-row
- * against the pre-registered table in `skills/eval/rubric-v2.md`. NOT a public
+ * against the pre-registered table in `skills/eval/rubric-v3.md`. NOT a public
  * contract: signature, arguments and return shape may change with the rubric.
  */
 export function scorePlanFidelity(ctx) {
@@ -334,12 +358,13 @@ export function scorePlanFidelity(ctx) {
 
 /**
  * gate-health: like verification-evidence but ONLY variant=='full-gate' events;
- * pass = the LAST full-gate in the clean window has exit_code==0, else fail.
+ * pass = the LAST full-gate in the clean window is not a failed gate event
+ * (`isFailedGateEvent`, rubric-v3), else fail.
  * 0 full-gate events → not-applicable when no waves ran (housekeeping), else
  * cannot-determine. Peer-contaminated window → cannot-determine.
  *
  * Exported ONLY so `tests/eval/rubric-parity.test.mjs` can drive it row-by-row
- * against the pre-registered table in `skills/eval/rubric-v2.md`. NOT a public
+ * against the pre-registered table in `skills/eval/rubric-v3.md`. NOT a public
  * contract: signature, arguments and return shape may change with the rubric.
  */
 export function scoreGateHealth(ctx) {
@@ -390,12 +415,15 @@ export function scoreGateHealth(ctx) {
   const last = fullGates.reduce((a, b) =>
     Date.parse(a.timestamp) >= Date.parse(b.timestamp) ? a : b,
   );
-  const status = last.exit_code === 0 ? 'pass' : 'fail';
+  const lastFailed = isFailedGateEvent(last);
+  // A failed run that still exited 0 (killed, or recorded `.failed`) carries a
+  // marker, so the judge's `last_full_gate_exit=0` is not read as a green finish.
+  const flag = lastFailed && last.exit_code === 0 ? ', last failed-flag=true' : '';
   return {
     id,
     method,
-    status,
-    evidence: `attribution: time-window. ${fullGates.length} full-gate event(s) in window; last exit_code=${last.exit_code}.`,
+    status: lastFailed ? 'fail' : 'pass',
+    evidence: `attribution: time-window. ${fullGates.length} full-gate event(s) in window; last exit_code=${last.exit_code}${flag}.`,
   };
 }
 
@@ -420,7 +448,7 @@ export function scoreGateHealth(ctx) {
  * those only `spiral` is emitted at all, which the evidence discloses.
  *
  * Exported ONLY so `tests/eval/rubric-parity.test.mjs` can drive it row-by-row
- * against the pre-registered table in `skills/eval/rubric-v2.md`. NOT a public
+ * against the pre-registered table in `skills/eval/rubric-v3.md`. NOT a public
  * contract: signature, arguments and return shape may change with the rubric.
  */
 export function scoreProcessSafety(ctx) {
@@ -465,7 +493,7 @@ export function scoreProcessSafety(ctx) {
  * window — see `countAttributedEvents`.
  *
  * Exported ONLY so `tests/eval/rubric-parity.test.mjs` can drive it row-by-row
- * against the pre-registered table in `skills/eval/rubric-v2.md`. NOT a public
+ * against the pre-registered table in `skills/eval/rubric-v3.md`. NOT a public
  * contract: signature, arguments and return shape may change with the rubric.
  */
 export function scoreGuardFriction(ctx) {
@@ -509,7 +537,7 @@ export function scoreGuardFriction(ctx) {
  * Missing values are null ("don't fake perfect"), never guessed.
  *
  * Exported ONLY so `tests/eval/rubric-parity.test.mjs` can drive it row-by-row
- * against the pre-registered table in `skills/eval/rubric-v2.md`. NOT a public
+ * against the pre-registered table in `skills/eval/rubric-v3.md`. NOT a public
  * contract: signature, arguments and return shape may change with the rubric.
  */
 export function scoreEfficiencyKpis(kpis) {
@@ -528,7 +556,7 @@ export function scoreEfficiencyKpis(kpis) {
  * Dimension id → its scorer, in the canonical `RUBRIC_DIMENSION_IDS` order.
  *
  * Exists so the rubric parity test resolves a scorer from the dimension ANCHOR
- * it parsed out of `skills/eval/rubric-v2.md` instead of retyping six function
+ * it parsed out of `skills/eval/rubric-v3.md` instead of retyping six function
  * names — a hand-typed list under a census title is a green tick with no cover
  * (`.claude/rules/measurement-discipline.md`). NOT a public contract; the
  * callable values are the same test-only exports as above.
@@ -579,7 +607,7 @@ const EVENT_DERIVED_DIMENSIONS = new Set([
  * turns a partial result into a clean verdict.
  *
  * NOT A RUBRIC CHANGE — and deliberately so. This appends to `evidence` and
- * touches no `status`: no pre-registered formula in `skills/eval/rubric-v2.md`
+ * touches no `status`: no pre-registered formula in `skills/eval/rubric-v3.md`
  * reads it, and no dimension can flip verdict because of it. Measured
  * 2026-09-20 over the 40 records in `.orchestrator/metrics/eval.jsonl`: the
  * live ledger reads `complete: true`, `gaps: []`, `malformed_lines: 0`
@@ -652,8 +680,11 @@ export const EVIDENCE_PATTERNS = Object.freeze({
     gateRunsTotal: /(\d+) quality_gate event\(s\) in window/,
     /** ≥1-gate, all-green branch. */
     gateAllGreen: /quality_gate event\(s\) in window, all exit_code=0/,
-    /** ≥1-gate, some-red branch ("…; N with non-zero exit_code."). */
-    gateRunsFailed: /(\d+) with non-zero exit_code/,
+    /**
+     * ≥1-gate, some-red branch — rubric-v3 "…; N failed (non-zero exit_code, …)."
+     * and, for stored rubric-v2 records, "…; N with non-zero exit_code.".
+     */
+    gateRunsFailed: /(\d+) (?:failed \(non-zero exit_code|with non-zero exit_code)/,
     /** 0-gate, nothing changed → not-applicable branch. */
     noChangeToVerify: /0 quality_gate events in window and total_files_changed=0/,
     /** 0-gate, files changed → cannot-determine branch. */
@@ -673,6 +704,8 @@ export const EVIDENCE_PATTERNS = Object.freeze({
     /** ≥1-full-gate branch ("N full-gate event(s) in window; last exit_code=X."). */
     fullGateRuns: /(\d+) full-gate event\(s\) in window/,
     lastFullGateExit: /last exit_code=(-?\d+)/,
+    /** rubric-v3: the last full-gate failed although it exited 0 (killed / recorded `.failed`). */
+    lastFullGateFailedFlag: /last failed-flag=true/,
     /** 0-full-gate branches (not-applicable / cannot-determine). */
     fullGateZero: /0 full-gate events (?:in window|and no waves ran)/,
   }),
@@ -690,7 +723,7 @@ export const EVIDENCE_PATTERNS = Object.freeze({
     // `RecordFacts` field and no rubric-v2 decision rule names them, so a
     // pattern for them would be a reader with zero consumers (BV-001.1). They
     // were exactly that until 2026-09-19. Adding one back means adding the
-    // fact to the pre-registered list in `skills/eval/rubric-v2.md` first.
+    // fact to the pre-registered list in `skills/eval/rubric-v3.md` first.
     /** attribution marker: session-id (preferred) vs the time-window fallback. */
     attributionSessionId: /attribution: session-id/,
     attributionTimeWindow: /attribution: time-window/,
@@ -854,7 +887,7 @@ function resolveModel(model, env, resolveModelFromEnv) {
 export const REQUIRED_EVENTS_WINDOW_DAYS = null;
 
 /**
- * Evaluate one completed session against the rubric-v2 dimensions.
+ * Evaluate one completed session against the rubric-v3 dimensions.
  *
  * @param {object} opts
  * @param {string} [opts.sessionId] — explicit session_id; default is the cascade.
@@ -899,7 +932,8 @@ export function evaluateSession(opts = {}) {
   }
 
   const sessionsPath = path.join(metricsDir, 'sessions.jsonl');
-  const eventsPath = path.join(metricsDir, 'events.jsonl');
+  // #1514 point 1 — the repo's ONE ledger (main checkout for a linked worktree).
+  const eventsPath = path.join(resolveEventsLedgerRoot(metricsDir), 'events.jsonl');
   // #1209: sessions.jsonl is APPEND-ONLY (the same physical session can carry
   // more than one line — crash-recovery re-appends, #1068 stub/supersede
   // pairs), so a raw readJsonlFile() left resolveSession()/findPeerOverlap()

package/scripts/lib/eval/judge.mjs

@@ -2,7 +2,7 @@
  * eval/judge.mjs — opt-in advisory LLM-judge overlay for the aiat-llm-eval
  * standard (Epic #803, S7 / issue #810).
  *
- * Overlays the ONE pre-registered judge dimension from `skills/eval/rubric-v2.md`
+ * Overlays the ONE pre-registered judge dimension from `skills/eval/rubric-v3.md`
  * § "Judge Dimensions" — `instruction-adherence` — onto a deterministic
  * session-eval record produced by `scripts/lib/eval/engine.mjs`.
  * Default OFF (`eval.judge: off` in Session Config); when disabled, zero code in
@@ -64,7 +64,7 @@ export const DEFAULT_BUDGET = Object.freeze({ input: 8000, output: 4000 });
 const CHARS_PER_TOKEN = 4;
 
 /**
- * The pre-registered judge dimension ids (rubric-v2.md § "Judge Dimensions").
+ * The pre-registered judge dimension ids (rubric-v3.md § "Judge Dimensions").
  * Fixed set — the judge may never invent a second dimension. `report-quality`
  * was retired in v2 (#1381; see the module docblock for the two measurements).
  */
@@ -82,11 +82,11 @@ export const JUDGE_DIMENSION_IDS = Object.freeze(['instruction-adherence']);
  * signal that is allowed to speak at all. Numerator AND denominator are quoted
  * here because the bare percentage disagreed with its own rubric copy: this
  * docblock read 5.1% (= 2/39) against the rubric's 5.0% for the same
- * measurement. Pre-registered in `skills/eval/rubric-v2.md`.
+ * measurement. Pre-registered in `skills/eval/rubric-v3.md`.
  */
 export const GUARD_BLOCKED_CONSPICUOUS_THRESHOLD = 20;
 
-/** The judge question text per dimension, pre-registered verbatim in rubric-v2.md. */
+/** The judge question text per dimension, pre-registered verbatim in rubric-v3.md. */
 export const JUDGE_QUESTIONS = Object.freeze({
   'instruction-adherence':
     "Reading the session-eval record's dimension evidence, kpis, session_id and the pre-computed facts below, did the coordinator follow the operator's stated instructions and the repo's always-on rules (verification-before-completion, ask-via-tool, parallel-session safety, scope discipline) — or is a concrete deviation visible in the record?",
@@ -94,7 +94,7 @@ export const JUDGE_QUESTIONS = Object.freeze({
 
 /**
  * The ordered decision rules for `instruction-adherence`, pre-registered
- * verbatim in `skills/eval/rubric-v2.md` § "Judge Dimensions". Applied IN THIS
+ * verbatim in `skills/eval/rubric-v3.md` § "Judge Dimensions". Applied IN THIS
  * ORDER; the first rule that applies decides.
  *
  * They exist because the v1 wording was under-specified: it named "isolated
@@ -213,7 +213,7 @@ const LEGACY_V1_SPIRAL = /(?:^|[\s(])(\d+) spiral\b/;
 /**
  * @typedef {Object} RecordFacts
  * @property {number|null} gate_runs_total        quality_gate events attributed to the session
- * @property {number|null} gate_runs_failed       of those, how many exited non-zero
+ * @property {number|null} gate_runs_failed       of those, how many failed (rubric-v3: non-zero exit, timed_out, or `.failed`)
  * @property {number|null} full_gate_runs         full-gate events attributed to the session
  * @property {number|null} last_full_gate_exit    exit code of the LAST full gate
  * @property {boolean|null} red_runs_then_green_finish  red intermediate runs, green finish
@@ -356,6 +356,10 @@ export function computeRecordFacts(dimensions) {
   const ghEv = ev('gate-health');
   let full_gate_runs = null;
   let last_full_gate_exit = null;
+  // rubric-v3 (#1487): the last full-gate can be red while it exited 0 (killed
+  // reporting run). Not a fact of its own — it only keeps the exit code from
+  // being read as a green finish below.
+  let last_full_gate_flagged_failed = false;
   if (ghEv !== null) {
     if (GH.windowContaminated.test(ghEv)) {
       // Same construction as above — unattributable, no number to read.
@@ -365,6 +369,7 @@ export function computeRecordFacts(dimensions) {
     } else if (GH.fullGateRuns.test(ghEv)) {
       full_gate_runs = num(ghEv, GH.fullGateRuns);
       last_full_gate_exit = num(ghEv, GH.lastFullGateExit);
+      last_full_gate_flagged_failed = GH.lastFullGateFailedFlag.test(ghEv);
       if (last_full_gate_exit === null) {
         miss('last_full_gate_exit', 'gate-health', 'the ≥1-full-gate branch matched but carried no exit code');
       }
@@ -454,10 +459,11 @@ export function computeRecordFacts(dimensions) {
   const carryover = planCarryover ?? kpiCarryover;
 
   // --- derived + contradictions -------------------------------------------
+  const lastFullGateGreen = last_full_gate_exit === 0 && !last_full_gate_flagged_failed;
   const red_runs_then_green_finish =
     gate_runs_failed === null || last_full_gate_exit === null
       ? null
-      : gate_runs_failed > 0 && last_full_gate_exit === 0;
+      : gate_runs_failed > 0 && lastFullGateGreen;
 
   let window_contaminated = null;
   const contaminationSources = [
@@ -484,7 +490,7 @@ export function computeRecordFacts(dimensions) {
   if (st('gate-health') === 'pass' && last_full_gate_exit !== null && last_full_gate_exit !== 0) {
     contradictions.push(`gate-health status=pass but last_full_gate_exit=${last_full_gate_exit}`);
   }
-  if (st('gate-health') === 'fail' && last_full_gate_exit === 0) {
+  if (st('gate-health') === 'fail' && lastFullGateGreen) {
     contradictions.push('gate-health status=fail but last_full_gate_exit=0');
   }
   if (planCarryover !== null && kpiCarryover !== null && planCarryover !== kpiCarryover) {

package/scripts/lib/eval/session-resolve.mjs

@@ -10,8 +10,13 @@
  *      order) that is either status:'completed' or non-abandoned with completed
  *      work. Abandoned records are ALWAYS skipped.
  *
- *   2. WHOSE events? — quality_gate events in events.jsonl carry NO session_id,
- *      so they are attributed to a session by its wall-clock window
+ *   2. WHOSE events? — quality_gate events in events.jsonl do not RELIABLY
+ *      carry a session_id (measured 2026-10-05, this repo's events.jsonl:
+ *      17 of 82 `orchestrator.quality_gate.*` records without one, 65 with —
+ *      `grep '"orchestrator.quality_gate' <file> | grep -c '"session_id"'`;
+ *      the id-less ones are interleaved through the file, not just the oldest),
+ *      so this module attributes them to a
+ *      session by its wall-clock window
  *      [started_at, completed_at] (Decision #1: attribution = time-window).
  *      findPeerOverlap() detects when that window overlaps ANY other session's
  *      window — a contaminated window means gate-attribution is unsafe and the

package/scripts/lib/events-retention-banner.mjs

@@ -88,6 +88,7 @@
 import { closeSync, existsSync, openSync, readSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 
+import { eventsFilePath } from './events.mjs';
 import { ARCHIVE_DIR_NAME, ARCHIVE_NAME_RE, LEGACY_RING_MAX, ROTATION_EVENT } from './events-schema.mjs';
 
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -268,9 +269,11 @@ async function maxRequiredWindow(readers) {
  */
 export async function checkEventsRetention({ repoRoot, config, now = Date.now() } = {}) {
   if (!repoRoot || typeof repoRoot !== 'string') return null;
-  const metricsDir = path.join(repoRoot, '.orchestrator', 'metrics');
+  // #1514 point 1 — the repo's ONE ledger; its archive dir sits beside the SAME
+  // resolved file rotation writes (`events-rotation.mjs`: `<dirname(log)>/_archive`).
+  const activePath = eventsFilePath(repoRoot);
+  const metricsDir = path.dirname(activePath);
   const archiveDir = path.join(metricsDir, ARCHIVE_DIR_NAME);
-  const activePath = path.join(metricsDir, 'events.jsonl');
   const nowMs = typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
 
   let names;

package/scripts/lib/events.mjs

@@ -52,7 +52,7 @@ import {
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { getProjectDir, SO_SHARED_DIR } from './platform.mjs';
+import { getProjectDir, resolveEventsLedgerRoot, SO_SHARED_DIR } from './platform.mjs';
 import { readLock } from './session-lock.mjs';
 import { resolveStateMdPath } from './state-md/frontmatter-mutators.mjs';
 import {
@@ -139,8 +139,12 @@ function sandboxedDefault(defaultPath) {
 /**
  * Returns the absolute path to `.orchestrator/metrics/events.jsonl` under `repoRoot`.
  *
- * `repoRoot` defaults to the module-level `SO_PROJECT_DIR` constant, so the
- * zero-arg call is unchanged for every existing caller (#941). Pass an explicit
+ * `repoRoot` defaults to the ONE events-ledger root, `resolveEventsLedgerRoot()`
+ * (`platform.mjs`, #1514 point 1): the launch dir from env, else the main
+ * checkout when the cwd is a linked git worktree, else `getProjectDir()` — the
+ * pre-#1514 default, unchanged everywhere a worktree is not involved (#941). An
+ * explicit absolute `repoRoot` inside a linked worktree is mapped to its main
+ * checkout the same way. Pass an explicit
  * `repoRoot` when the destination must be pinned to a tree other than the
  * CWD/env-resolved project — e.g. a unit test running the gate against a tmp
  * repo, which must NOT append synthetic records to the real fleet telemetry.
@@ -154,8 +158,18 @@ function sandboxedDefault(defaultPath) {
  * @returns {string}
  */
 export function eventsFilePath(repoRoot) {
-  if (repoRoot !== undefined) return path.join(repoRoot, SO_SHARED_DIR, 'metrics', 'events.jsonl');
-  return sandboxedDefault(path.join(getProjectDir(), SO_SHARED_DIR, 'metrics', 'events.jsonl'));
+  if (repoRoot !== undefined) {
+    // #1514 point 1 — an absolute root inside a LINKED git worktree maps to the
+    // same spot in its main checkout: one ledger per repo, never one per
+    // worktree. Identity for every other root (a plain repo, a tmp fixture, a
+    // non-git dir), and a relative/empty value is joined exactly as before —
+    // `emitEvent()` refuses it upstream.
+    const root = typeof repoRoot === 'string' && path.isAbsolute(repoRoot)
+      ? resolveEventsLedgerRoot(repoRoot)
+      : repoRoot;
+    return path.join(root, SO_SHARED_DIR, 'metrics', 'events.jsonl');
+  }
+  return sandboxedDefault(path.join(resolveEventsLedgerRoot(), SO_SHARED_DIR, 'metrics', 'events.jsonl'));
 }
 
 /**
@@ -578,6 +592,60 @@ function discoverArchives(logPath) {
   return { archives, legacy: present.map((i) => `${logPath}.${i}`), ringHoles, unindexed };
 }
 
+/**
+ * The one tombstone-to-archive match (#1505 5c) — shared by
+ * {@link readEventsWithRotations} rule 1, {@link scanEventsBackwards}, and
+ * `planWithGaps` in `scripts/backfill-abandoned-sessions.mjs`, which used to
+ * carry three hand-kept copies of it.
+ *
+ * #1411 — the tombstone resolves against THIS ledger's own `_archive/`, by
+ * BASENAME, never against the absolute value it stores. The writer keeps
+ * `archived_as` absolute (`events-rotation.mjs` joins the repo root) and that
+ * value stays in the record as PROVENANCE. It is not a lookup key: a moved
+ * checkout, a clone, or a sibling git worktree — routine here — makes every
+ * tombstone name a path that does not exist in THIS tree, so an exact
+ * comparison reported a phantom `missing-archive` for an archive sitting right
+ * beside the active file. Basename, not `realpath`: realpath cannot resolve a
+ * path that no longer exists, which IS the failure mode.
+ *
+ * ORDER (why the absolute value has no second chance): the sibling answer is
+ * consulted first, and an absolute hit would only be trustworthy while it
+ * pointed INSIDE this ledger's own archive dir — but any such path resolves to
+ * exactly the sibling path already tested, so once the sibling misses, an
+ * absolute hit can ONLY be a still-present OLD checkout. Honouring it would
+ * validate THIS ledger against a FOREIGN repo's archive: a silent false
+ * negative, worse than the phantom gap.
+ *
+ * #1423 — THREE outcomes, not two: read (`null`), present-but-unread
+ * (`unindexed-archive`), gone (`missing-archive`). The middle one used to be
+ * folded into the first by `existsSync`, so a tombstone whose archive had been
+ * RENAMED out of `ARCHIVE_NAME_RE` reported `complete: true` while its records
+ * were absent.
+ *
+ * @param {unknown} record  a parsed ledger line
+ * @param {string} ownArchiveDir  this ledger's `_archive/`, built exactly as
+ *   `discoverArchives` builds it so a read archive matches `readSet` by string
+ * @param {Set<string>} readSet  the paths this read actually took as sources
+ * @returns {{kind: 'unindexed-archive'|'missing-archive', path: string,
+ *            archived_as: string, first_ts: string|null, last_ts: string|null}|null}
+ *   `null` when `record` is not a rotation tombstone, names no archive, or its
+ *   archive was read.
+ */
+export function tombstoneGap(record, ownArchiveDir, readSet) {
+  if (record?.event !== ROTATION_EVENT) return null;
+  const target = record.archived_as;
+  if (typeof target !== 'string' || target.length === 0) return null;
+  const sibling = path.join(ownArchiveDir, path.basename(target));
+  if (readSet.has(sibling)) return null;
+  return {
+    kind: existsSync(sibling) ? 'unindexed-archive' : 'missing-archive',
+    path: sibling,
+    archived_as: target,
+    first_ts: record.first_ts ?? null,
+    last_ts: record.last_ts ?? null,
+  };
+}
+
 /**
  * Read the events ledger ACROSS rotation boundaries — active file plus every
  * archive still on disk — in time order, reporting what is missing instead of
@@ -660,44 +728,14 @@ export function readEventsWithRotations(repoRoot, opts = {}) {
   // `onDisk` still match by string.
   const ownArchiveDir = path.join(path.dirname(activePath), ARCHIVE_DIR_NAME);
 
-  // Rule 1 — every rotation tombstone must still point at a file.
+  // Rule 1 — every rotation tombstone must still point at a file (resolution
+  // and the three outcomes: {@link tombstoneGap}).
   for (const source of sources) {
     for (const record of source.records) {
-      if (record?.event !== ROTATION_EVENT) continue;
-      const target = record.archived_as;
-      if (typeof target !== 'string' || target.length === 0) continue;
-      // #1411 — resolve the tombstone against THIS ledger's own `_archive/`,
-      // by BASENAME, and never against the absolute value it stores.
-      //
-      // The writer keeps `archived_as` absolute (`events-rotation.mjs` joins
-      // the repo root) and that value stays in the record as PROVENANCE. It is
-      // not a lookup key: a moved checkout, a clone, or a sibling git worktree
-      // — routine here — makes every tombstone name a path that does not exist
-      // in THIS tree, so the old exact comparison reported a phantom
-      // `missing-archive` for an archive sitting right beside the active file.
-      // Basename, not `realpath`: realpath cannot resolve a path that no longer
-      // exists, which IS the failure mode.
-      //
-      // ORDER (why the absolute value has no second chance): the sibling answer
-      // is consulted first, and an absolute hit would only be trustworthy while
-      // it pointed INSIDE this ledger's own archive dir — but any such path
-      // resolves to exactly the sibling path already tested, so once the
-      // sibling misses, an absolute hit can ONLY be a still-present OLD
-      // checkout. Honouring it would validate THIS ledger against a FOREIGN
-      // repo's archive: a silent false negative, worse than the phantom gap.
-      const sibling = path.join(ownArchiveDir, path.basename(target));
-      if (onDisk.has(sibling)) continue;
+      const gap = tombstoneGap(record, ownArchiveDir, onDisk);
+      if (gap === null) continue;
       gaps.push({
-        // #1423 — THREE outcomes, not two: read (above), present-but-unread
-        // (here), gone (below). The middle one used to be silently folded into
-        // the first by `existsSync`, so a tombstone whose archive had been
-        // RENAMED out of `ARCHIVE_NAME_RE` reported `complete: true` while its
-        // records were absent from `events`.
-        kind: existsSync(sibling) ? 'unindexed-archive' : 'missing-archive',
-        path: sibling,
-        archived_as: target,
-        first_ts: record.first_ts ?? null,
-        last_ts: record.last_ts ?? null,
+        ...gap,
         lines: record.lines ?? null,
         size_before: record.size_before ?? null,
         reported_by: source.path,
@@ -866,8 +904,7 @@ export function scanEventsBackwards(opts = {}) {
    * LOW-2): `maybeRotate` renames, prunes, THEN appends the tombstone, from an
    * async SessionStart hook, so a concurrent append can land first and push it
    * to line 2. Called BEFORE the caller's `filter`, which names another event
-   * and would otherwise hide the cut. Resolved by basename against this
-   * ledger's own `_archive/`, never by the absolute provenance value (#1411).
+   * and would otherwise hide the cut. Matched by {@link tombstoneGap}.
    */
   const noteCut = (line, source) => {
     if (!line.includes(ROTATION_EVENT)) return;
@@ -877,18 +914,8 @@ export function scanEventsBackwards(opts = {}) {
     } catch {
       return; // counted by `consume` like every other malformed line
     }
-    const target = record?.event === ROTATION_EVENT ? record.archived_as : null;
-    if (typeof target !== 'string' || target.length === 0) return;
-    const sibling = path.join(ownArchiveDir, path.basename(target));
-    if (listed.has(sibling)) return;
-    gaps.push({
-      kind: existsSync(sibling) ? 'unindexed-archive' : 'missing-archive',
-      path: sibling,
-      archived_as: target,
-      first_ts: record.first_ts ?? null,
-      last_ts: record.last_ts ?? null,
-      reported_by: source.path,
-    });
+    const gap = tombstoneGap(record, ownArchiveDir, listed);
+    if (gap !== null) gaps.push({ ...gap, reported_by: source.path });
   };
 
   /** @returns {boolean} true ⇒ the caller accepted a record; stop everything. */