session-orchestrator 3.22.0 → 3.24.0

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

@@ -13,6 +13,17 @@
  * from `hooks/on-session-end.mjs` and by the one-time historical migration CLI
  * `scripts/backfill-abandoned-sessions.mjs`.
  *
+ * A second, sibling export — `backfillCompletedFromStateMd` — closes a
+ * different gap (#429): `commands/close.md`'s Pre-Check treats STATE.md
+ * `status: completed` as proof the session-end writer already ran and refuses
+ * to invoke it again. When that status was set by hand (or by any path that
+ * never reached Phase 3.7), no sessions.jsonl record is EVER written — the
+ * Pre-Check keeps blocking the only thing that would normally create one.
+ * `backfillCompletedFromStateMd` reads STATE.md directly, and when its status
+ * is `completed` with no matching sessions.jsonl record, backfills one tagged
+ * `status: 'completed'` + `_backfill_source: 'state-md-completed'` (never
+ * `'abandoned'` — the session itself claims to have finished normally).
+ *
  * ── ID BRIDGE ────────────────────────────────────────────────────────────────
  *   sessions.jsonl records are keyed by SEMANTIC ids (`main-2026-05-27-session-1`).
  *   events.jsonl carries the harness UUID on `session.started` / `stop` / `ended`.
@@ -25,6 +36,11 @@
  *   - No-throw: every path returns a structured `{ action, ... }` result; the
  *     hook must never be pushed past its teardown timeout by an exception.
  *   - Dedupe: never double-write a session already present in sessions.jsonl.
+ *   - Supersede (#1068 AC3/AC4): the ONE exception to that dedupe — an
+ *     authoritative `state-md-completed` record may be appended for an identity
+ *     whose only entry is a backfilled `abandoned` STUB, carrying
+ *     `supersedes: <stub id>`. Append-only: the stub is kept verbatim and
+ *     readers take the NEWEST record for an id as the canonical one.
  *   - Liveness guard: never backfill over a FOREIGN live session.lock (PSA).
  *   - TOCTOU marker: an atomic `openSync(..., 'wx')` claim file keyed by the
  *     final id serialises concurrent backfill attempts (mirrors the
@@ -40,16 +56,17 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 
 import { appendJsonl as defaultAppendJsonl } from './common.mjs';
+import { parseSessionId } from './session-id.mjs';
 import { readLock as defaultReadLock, isLockLive as defaultIsLockLive, DEFAULT_TTL_HOURS } from './session-lock.mjs';
 import { validateSession as defaultValidateSession } from './session-schema/validator.mjs';
 import { serializeSessionLineChecked as defaultSerialize } from './session-schema.mjs';
+import { resolveStateMdPath as defaultResolveStateMdPath } from './state-md/frontmatter-mutators.mjs';
+import { parseStateMd as defaultParseStateMd } from './state-md/yaml-parser.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
 /** session_type enum accepted by the schema — lock.mode is coerced against it. */
 const VALID_SESSION_TYPES = new Set(['feature', 'deep', 'housekeeping']);
 
@@ -66,9 +83,22 @@ const BACKFILL_LOG_REL = ['.orchestrator', 'metrics', 'session-close-backfill.lo
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** True when `s` is a canonical UUID (v4-shaped). */
+/**
+ * True when `s` is an RFC 9562 UUID session id (any version 1-8, variant `10xx`).
+ *
+ * Delegates to `parseSessionId()` so the repo has exactly ONE UUID contract
+ * (`UUID_RE` in `scripts/lib/session-id.mjs`). This module previously carried a
+ * private, LOOSER copy that constrained neither the version nor the variant
+ * nibble, so a 36-char lookalike such as
+ * `xxxxxxxx-xxxx-0xxx-cxxx-xxxxxxxxxxxx` was classified as a harness UUID here
+ * while `hooks/on-session-start.mjs` — which gates on `parseSessionId()` —
+ * rejected it. The disagreement is exactly the ID-bridge this module depends
+ * on: a value the writer refused to use as a raw id was still treated here as
+ * one, sending the record down the UUID branch (lock-bridge + synthetic-id
+ * mint) instead of the semantic branch.
+ */
 export function isUuid(s) {
-  return typeof s === 'string' && UUID_RE.test(s);
+  return parseSessionId(s)?.format === 'uuid';
 }
 
 /** Filesystem-safe marker filename for an arbitrary session id. */
@@ -123,18 +153,33 @@ function collectSessionEvents(events, { sessionId, semanticSessionId }) {
 
   let mode = null;
   let semanticFromLock = null;
-
-  // First pass — lock.acquired bridges the UUID set + carries mode + semantic.
+  // #1167 — the SECOND semantic bridge. `orchestrator.session.ended` carries
+  // `semantic_session_id` alongside the raw UUID since #1068 AC1, but nothing
+  // read it: a session that LOST the lock-acquire race emits no lock.acquired,
+  // so the lock bridge above resolved null and the caller fell through to the
+  // synthetic-id mint — writing a SECOND `abandoned` stub for a session the
+  // SessionEnd hook had already recorded under its semantic id. Measured
+  // 2026-09-02 @ c3ab480: 8 such duplicate pairs in sessions.jsonl.
+  let semanticFromEvents = null;
+
+  // First pass — bridge the UUID set + carry mode + semantic id. lock.acquired
+  // is the original bridge; session.ended is the #1167 addition.
   for (const ev of events) {
-    if (ev.event !== EVENT_LOCK_ACQUIRED) continue;
+    const isLock = ev.event === EVENT_LOCK_ACQUIRED;
+    const isEnded = ev.event === EVENT_ENDED && typeof ev.semantic_session_id === 'string';
+    if (!isLock && !isEnded) continue;
     const matchesUuid = isUuid(sessionId) && ev.session_id === sessionId;
     const matchesSemantic =
       (semanticSessionId && ev.semantic_session_id === semanticSessionId) ||
       (!isUuid(sessionId) && sessionId && ev.semantic_session_id === sessionId);
     if (!matchesUuid && !matchesSemantic) continue;
     if (typeof ev.session_id === 'string') uuids.add(ev.session_id);
-    if (typeof ev.mode === 'string') mode = ev.mode;
-    if (typeof ev.semantic_session_id === 'string') semanticFromLock = ev.semantic_session_id;
+    if (isLock) {
+      if (typeof ev.mode === 'string') mode = ev.mode;
+      if (typeof ev.semantic_session_id === 'string') semanticFromLock = ev.semantic_session_id;
+    } else {
+      semanticFromEvents = ev.semantic_session_id;
+    }
   }
 
   // Second pass — started + terminal timestamps from every matched UUID.
@@ -170,7 +215,18 @@ function collectSessionEvents(events, { sessionId, semanticSessionId }) {
     }
   }
 
-  return { uuids, mode, semanticFromLock, startedAt, branch, project, lastTerminalMs, earliestMs, lastEventMs };
+  return {
+    uuids,
+    mode,
+    semanticFromLock,
+    semanticFromEvents,
+    startedAt,
+    branch,
+    project,
+    lastTerminalMs,
+    earliestMs,
+    lastEventMs,
+  };
 }
 
 /**
@@ -213,12 +269,20 @@ function isCandidateDeadByAge({ relaxDeadByAge, assumeDeadBeforeMs, lastEventMs,
 }
 
 /**
- * Build the abandoned-session stub record. Required fields with no events
- * source are defaulted to empty/zero and enumerated in
- * `_backfill_incomplete_fields`; the mode → session_type coercion sets
- * `_session_type_inferred`.
+ * Build a backfilled stub record. Required fields with no events source are
+ * defaulted to empty/zero and enumerated in `_backfill_incomplete_fields`;
+ * the mode → session_type coercion sets `_session_type_inferred`.
+ *
+ * `status` / `backfillSource` are parameterized (#429 — the STATE.md
+ * `status: completed` backfill below reuses this exact synthesis, just with
+ * a different terminal status and provenance tag). Defaults reproduce the
+ * original `backfillAbandonedSession` behaviour exactly for existing callers.
+ *
+ * `supersedes` (#1068 AC3, default `null`) stamps the id of the backfill STUB
+ * this record replaces. It is emitted only when non-null, so every existing
+ * record shape is byte-identical to before.
  */
-function synthesizeRecord({ recordId, synthetic, gathered, nowMs }) {
+function synthesizeRecord({ recordId, synthetic, gathered, nowMs, status = 'abandoned', backfillSource = 'events-jsonl', supersedes = null, rawSessionId = null }) {
   const startedIso = canonicalIso(gathered.startedAt, gathered.earliestMs ?? nowMs);
   const startedMs = Date.parse(startedIso);
   // completed_at is events-attested, never the backfill-run wall-clock (#914 R1).
@@ -271,40 +335,120 @@ function synthesizeRecord({ recordId, synthetic, gathered, nowMs }) {
     agent_summary: { complete: 0, partial: 0, failed: 0, spiral: 0 },
     total_agents: 0,
     total_files_changed: 0,
-    status: 'abandoned',
-    // Issue #773 — an abandoned session never ran Phase 1.65, so its carryover
-    // is genuinely UNKNOWN. Emit `null` (not 0) so downstream effectiveness
-    // consumers can tell "not measured" apart from "measured zero" — 0 here
-    // would resurrect the very carryover=0 blind spot #773 exists to close.
+    status,
+    // Issue #773 — a backfilled stub never ran (or cannot be proven to have
+    // run) Phase 1.65, so its carryover is genuinely UNKNOWN. Emit `null` (not
+    // 0) so downstream effectiveness consumers can tell "not measured" apart
+    // from "measured zero" — 0 here would resurrect the very carryover=0
+    // blind spot #773 exists to close.
     effectiveness: { carryover: null },
-    _backfill_source: 'events-jsonl',
+    _backfill_source: backfillSource,
     _backfill_incomplete_fields: incomplete,
   };
   if (branchFound) record.branch = gathered.branch;
   if (inferred) record._session_type_inferred = true;
   if (synthetic) record._synthetic_session_id = true;
   if (completedEstimated) record._completed_at_estimated = true;
+  // #1068 AC3/AC4 — forensic supersede marker. sessions.jsonl is append-only,
+  // so the stub itself cannot be stamped `superseded_by`; the FORWARD pointer
+  // lives on the newer record instead, and the stub survives verbatim (AC4:
+  // "historische Stub-Provenance bleibt erhalten"). Readers resolve one
+  // canonical state per id by taking the NEWEST record for that id.
+  if (typeof supersedes === 'string' && supersedes.length > 0) record.supersedes = supersedes;
+  // #1167 — the harness UUID this record was reconstructed from, when known.
+  // Additive and optional (the schema validates unknown keys pass-through, see
+  // session-schema/validator.mjs `_validateOptionalFields`): it is the ONLY key
+  // that lets a reader join a semantic record back to its raw uuid. Measured
+  // 2026-09-02 @ c3ab480: 0 of 286 existing records carry it, which is exactly
+  // why the two backfill writers could not see each other's work.
+  if (typeof rawSessionId === 'string' && rawSessionId.length > 0) record.raw_session_id = rawSessionId;
   return record;
 }
 
+/**
+ * Terminal statuses that mark a ledger record as a BACKFILLED STUB rather than
+ * an authoritative close (#1068 AC3).
+ *
+ * `abandoned` is the only member today: it is what `backfillAbandonedSession`
+ * writes when a session never reached `/close`, i.e. a reconstruction, never a
+ * self-reported outcome. `completed` is deliberately NOT a member — including
+ * the `state-md-completed` backfill, whose status IS the session's own truth
+ * claim. That exclusion is also what makes supersede idempotent: the record
+ * appended by a supersede is `completed`, so a second run classifies it as
+ * canonical and skips instead of superseding its own predecessor forever.
+ */
+const BACKFILL_STUB_STATUSES = new Set(['abandoned']);
+
+/**
+ * True when a sessions.jsonl record is a backfilled STUB — reconstructed
+ * provenance (`_backfill_source`) AND a stub status. Both are required: a
+ * hand-written `abandoned` record with no backfill provenance is somebody's
+ * deliberate statement and is never superseded on our own initiative.
+ *
+ * @param {unknown} record
+ * @returns {boolean}
+ */
+function isBackfillStub(record) {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) return false;
+  if (typeof record._backfill_source !== 'string') return false;
+  return BACKFILL_STUB_STATUSES.has(record.status);
+}
+
+/**
+ * Classify what sessions.jsonl already holds for this identity (#1068 AC3/AC4).
+ *
+ * Reads the (small) sessions.jsonl exactly once and returns one of:
+ *   { kind: 'absent' }                                — nothing recorded yet
+ *   { kind: 'canonical', matchedId }                  — an authoritative record exists
+ *   { kind: 'stub', matchedId, stubId }               — only a backfilled stub exists
+ *
+ * "Newest wins" is the reading rule: sessions.jsonl is APPEND-ONLY, so a
+ * superseding record can never rewrite the stub in place — it is appended
+ * after it, and the LAST record for an id is therefore the current one. This
+ * function reads the same way (last match, not first), so a stub that has
+ * already been superseded classifies as `canonical` and is never superseded
+ * twice.
+ *
+ * @param {Function} readFileSync
+ * @param {string} sessionsPath
+ * @param {{recordId: string, sessionId: string|null}} ids
+ */
+function classifyExisting(readFileSync, sessionsPath, { recordId, sessionId }) {
+  const sessionRecords = readJsonlSafe(readFileSync, sessionsPath);
+  // Both keys count: the semantic record id, and — defensively — a prior record
+  // keyed directly by the UUID.
+  const uuidKey = isUuid(sessionId) ? sessionId : null;
+  const byId = (id) =>
+    id === null ? [] : sessionRecords.filter((r) => r && r.session_id === id);
+  // Key preference is UNCHANGED from the pre-#1068 dedupe: the semantic
+  // recordId wins whenever any record carries it, and the UUID key is only the
+  // defensive fallback.
+  const semanticMatches = byId(recordId);
+  const matches = semanticMatches.length > 0 ? semanticMatches : byId(uuidKey);
+  if (matches.length === 0) return { kind: 'absent' };
+
+  const newest = matches[matches.length - 1];
+  if (isBackfillStub(newest)) {
+    return { kind: 'stub', matchedId: newest.session_id, stubId: newest.session_id };
+  }
+  return { kind: 'canonical', matchedId: newest.session_id };
+}
+
 /**
  * Dedupe against sessions.jsonl. Returns a `skipped-already-recorded` result
  * when `recordId` (or a UUID `sessionId` written directly as a key) is already
- * present, else `null`. Reads the (small) sessions.jsonl exactly once.
+ * present, else `null`.
+ *
+ * HARD dedupe by design — it is the guard for `backfillAbandonedSession`, whose
+ * output is itself a stub: replacing one stub with another buys nothing and
+ * would re-append on every SessionEnd. The supersede path (#1068 AC3) belongs
+ * to the AUTHORITATIVE writer only; see `classifyExisting` + its use in
+ * `backfillCompletedFromStateMd`.
  */
 function checkAlreadyRecorded(readFileSync, sessionsPath, { recordId, sessionId }) {
-  const sessionRecords = readJsonlSafe(readFileSync, sessionsPath);
-  const existingIds = new Set(
-    sessionRecords.map((r) => (r && typeof r.session_id === 'string' ? r.session_id : null)).filter(Boolean)
-  );
-  if (existingIds.has(recordId)) {
-    return { action: 'skipped-already-recorded', sessionId: recordId };
-  }
-  // Defensive: a prior record keyed directly by the UUID also counts.
-  if (isUuid(sessionId) && existingIds.has(sessionId)) {
-    return { action: 'skipped-already-recorded', sessionId };
-  }
-  return null;
+  const existing = classifyExisting(readFileSync, sessionsPath, { recordId, sessionId });
+  if (existing.kind === 'absent') return null;
+  return { action: 'skipped-already-recorded', sessionId: existing.matchedId };
 }
 
 // ---------------------------------------------------------------------------
@@ -424,8 +568,11 @@ export async function backfillAbandonedSession({
 
       // -- Resolve a deferred id from the lock bridge or a synthetic mint ------
       if (recordId === null) {
-        if (gathered.semanticFromLock) {
-          recordId = gathered.semanticFromLock;
+        // Prefer the lock bridge (it also carries `mode`), then the #1167
+        // session.ended bridge. Only when NEITHER attests a semantic id do we
+        // mint a synthetic one — that fallback was the duplicate-stub source.
+        if (gathered.semanticFromLock || gathered.semanticFromEvents) {
+          recordId = gathered.semanticFromLock || gathered.semanticFromEvents;
         } else {
           // No semantic bridge — mint a synthetic id. Both components are STABLE
           // across re-runs so dedupe/marker suppress a double write (idempotency
@@ -508,7 +655,13 @@ export async function backfillAbandonedSession({
       }
 
       // -- Synthesize + validate (round-trip gate) BEFORE any disk mutation ---
-      const record = synthesizeRecord({ recordId, synthetic, gathered, nowMs });
+      const record = synthesizeRecord({
+        recordId,
+        synthetic,
+        gathered,
+        nowMs,
+        rawSessionId: isUuid(sessionId) ? sessionId : null,
+      });
       let validated;
       try {
         validated = validateSession(record);
@@ -583,6 +736,243 @@ export async function backfillAbandonedSession({
   }
 }
 
+/**
+ * Backfill a `status: 'completed'` session record from STATE.md when STATE.md
+ * itself already carries `status: completed` but sessions.jsonl has no
+ * matching record (#429).
+ *
+ * ── THE GAP THIS CLOSES ──────────────────────────────────────────────────
+ *   `commands/close.md`'s Pre-Check treats `STATE.md status: completed` as
+ *   PROOF that the session-end skill's Phase 3.7 writer already ran, and
+ *   stops before invoking it — including when `status: completed` was set by
+ *   hand (or by any path that never reached Phase 3.7). The session then has
+ *   no record in sessions.jsonl, permanently: nothing else ever re-drives the
+ *   write, because the Pre-Check keeps refusing to invoke session-end for as
+ *   long as STATE.md says `completed`. This function is the mechanical
+ *   self-heal — every SessionEnd hook firing checks the invariant
+ *   "STATE.md completed ⇒ a record exists" and repairs it once, regardless of
+ *   which session's hook happens to run next.
+ *
+ * ── WHY `status: 'completed'`, NOT `'abandoned'` ─────────────────────────
+ *   `backfillAbandonedSession` (above) marks its stub `abandoned` because a
+ *   session that never reached `/close` is, by definition, unfinished. This
+ *   case is the opposite: STATE.md's own `status: completed` is a truth claim
+ *   the session made about itself — only the LEDGER write failed to run. The
+ *   record is tagged `_backfill_source: 'state-md-completed'` (never
+ *   `'events-jsonl'`) so a later reader can tell the two backfill classes
+ *   apart at a glance.
+ *
+ * ── DATA SOURCE ──────────────────────────────────────────────────────────
+ *   Required numeric counters (`total_waves`, `total_agents`,
+ *   `total_files_changed`, `agent_summary`) are derived ONLY from
+ *   events.jsonl via the same `collectSessionEvents` + `synthesizeRecord`
+ *   machinery `backfillAbandonedSession` uses — never from STATE.md's own
+ *   body sections (Wave History, etc.), which this module deliberately never
+ *   parses. Schema `REQUIRED_FIELDS` forbids `null` on these (non-negative
+ *   number, `session-schema/validator.mjs`), so "otherwise null" is realized
+ *   as "otherwise 0, flagged in `_backfill_incomplete_fields`" — the same
+ *   contract the abandoned path already carries and the same reason it exists.
+ *
+ *   CONSTRAINT specific to this path: STATE.md's `session` field is already
+ *   the SEMANTIC id, never the raw harness UUID — unlike
+ *   `backfillAbandonedSession` (which usually receives the UUID directly from
+ *   SessionEnd stdin), this function has no UUID to seed `collectSessionEvents`'s
+ *   `uuids` set with. Events therefore only surface here when a
+ *   `lock.acquired` breadcrumb bridges the UUID to this exact semantic id
+ *   (`ev.semantic_session_id === recordId`) — the SAME bridge condition
+ *   `backfillAbandonedSession`'s synthetic-id fallback exists to handle when
+ *   ABSENT. Without that bridge, `gathered` stays empty and the record still
+ *   validates (started_at/completed_at both fall back to `now`, flagged
+ *   incomplete) — degraded but never blocked.
+ *
+ * Never throws. Returns one of:
+ *   { action: 'backfilled', sessionId, record }              — written to disk
+ *   { action: 'superseded', sessionId, record, supersedes }   — written, replacing a stub (#1068 AC3)
+ *   { action: 'would-backfill', sessionId, record }           — dryRun only
+ *   { action: 'would-supersede', sessionId, record, supersedes } — dryRun only
+ *   { action: 'skipped-no-state-md' }                — no STATE.md at any candidate path
+ *   { action: 'skipped-unparseable-state-md' }        — frontmatter did not parse
+ *   { action: 'skipped-not-completed', status }       — STATE.md status isn't 'completed'
+ *   { action: 'skipped-no-session-id' }               — completed but no `session:` field
+ *   { action: 'skipped-already-recorded', sessionId } — sessions.jsonl already has it
+ *   { action: 'skipped-marker-exists', sessionId }    — lost the TOCTOU claim
+ *   { action: 'error', error, sessionId? }             — any failure, swallowed
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot            absolute project root
+ * @param {number|string} [args.now]        ms-since-epoch (test seam) or ISO string
+ * @param {boolean} [args.dryRun=false]      compute + validate only, no marker/write
+ * @param {object} [args.deps]               DI overrides (fs, appendJsonl, resolveStateMdPath, …)
+ * @returns {Promise<object>}
+ */
+export async function backfillCompletedFromStateMd({
+  repoRoot,
+  now = Date.now(),
+  dryRun = false,
+  deps = {},
+} = {}) {
+  const {
+    readFileSync = fs.readFileSync,
+    appendJsonl = defaultAppendJsonl,
+    openSync = fs.openSync,
+    closeSync = fs.closeSync,
+    validateSession = defaultValidateSession,
+    serializeSessionLineChecked = defaultSerialize,
+    resolveStateMdPath = defaultResolveStateMdPath,
+    parseStateMd = defaultParseStateMd,
+    log = null,
+  } = deps;
+
+  const nowMs = resolveNowMs(now);
+  const result = await run();
+  logBreadcrumb(result);
+  return result;
+
+  async function run() {
+    try {
+      if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
+        return { action: 'error', error: 'repoRoot must be a non-empty string' };
+      }
+
+      // -- Read + parse STATE.md ------------------------------------------------
+      const stateMdPath = resolveStateMdPath(repoRoot);
+      let raw;
+      try {
+        raw = readFileSync(stateMdPath, 'utf8');
+      } catch {
+        return { action: 'skipped-no-state-md' };
+      }
+      const parsed = parseStateMd(raw);
+      if (parsed === null) {
+        return { action: 'skipped-unparseable-state-md' };
+      }
+
+      const stateStatus = parsed.frontmatter?.status;
+      if (stateStatus !== 'completed') {
+        return { action: 'skipped-not-completed', status: stateStatus ?? null };
+      }
+
+      const recordId = parsed.frontmatter?.session;
+      if (typeof recordId !== 'string' || recordId.length === 0) {
+        return { action: 'skipped-no-session-id' };
+      }
+
+      // -- Dedupe, or SUPERSEDE a backfill stub (#1068 AC3) ---------------------
+      // This is the authoritative writer of the pair: STATE.md's own
+      // `status: completed` is the session's truth claim about itself, and it
+      // arrives with an identity-complete key (the semantic id). When the only
+      // thing on file for that identity is a reconstructed `abandoned` stub,
+      // the stub is a measurement this record refutes — so we append the fuller
+      // record (carrying `supersedes: <stub id>`) instead of skipping. An
+      // authoritative record already on file still short-circuits exactly as
+      // before.
+      const sessionsPath = path.join(repoRoot, ...SESSIONS_REL);
+      const existing = classifyExisting(readFileSync, sessionsPath, { recordId, sessionId: recordId });
+      if (existing.kind === 'canonical') {
+        return { action: 'skipped-already-recorded', sessionId: existing.matchedId };
+      }
+      const supersedes = existing.kind === 'stub' ? existing.stubId : null;
+
+      // -- 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: null, semanticSessionId: recordId });
+
+      // -- Synthesize + validate (round-trip gate) BEFORE any disk mutation ----
+      const record = synthesizeRecord({
+        recordId,
+        synthetic: false,
+        gathered,
+        nowMs,
+        status: 'completed',
+        backfillSource: 'state-md-completed',
+        supersedes,
+        // #1167 — the abandoned path stamps this; so must the authoritative
+        // one, or the join key exists on exactly the weaker half of the pair.
+        // `gathered.uuids` is bridged from lock.acquired / session.ended, so it
+        // normally holds EXACTLY the one uuid this semantic id ran under. Two
+        // (or zero) means the bridge is ambiguous — omit rather than guess, the
+        // same fail-quiet posture as `isUuid(sessionId) ? sessionId : null`.
+        rawSessionId: gathered.uuids?.size === 1 ? [...gathered.uuids][0] : null,
+      });
+      let validated;
+      try {
+        validated = validateSession(record);
+        serializeSessionLineChecked(record);
+      } catch (err) {
+        return { action: 'error', error: `validation: ${err?.message ?? String(err)}`, sessionId: recordId };
+      }
+
+      if (dryRun) {
+        return {
+          action: supersedes ? 'would-supersede' : 'would-backfill',
+          sessionId: recordId,
+          record: validated,
+          ...(supersedes ? { supersedes } : {}),
+        };
+      }
+
+      // -- TOCTOU marker — atomic create-or-fail, own namespace so a concurrent
+      // abandoned-path claim for the same id can never collide with this one. --
+      const markerPath = path.join(repoRoot, '.orchestrator', 'metrics', markerName(`completed-${recordId}`));
+      try {
+        const fd = openSync(markerPath, 'wx');
+        closeSync(fd);
+      } catch (err) {
+        if (err && err.code === 'EEXIST') {
+          return { action: 'skipped-marker-exists', sessionId: recordId };
+        }
+        return { action: 'error', error: `marker: ${err?.message ?? String(err)}`, sessionId: recordId };
+      }
+
+      // -- Write via the shared append path -------------------------------------
+      try {
+        await appendJsonl(sessionsPath, validated);
+      } catch (err) {
+        return { action: 'error', error: `append: ${err?.message ?? String(err)}`, sessionId: recordId };
+      }
+      return {
+        action: supersedes ? 'superseded' : 'backfilled',
+        sessionId: recordId,
+        record: validated,
+        ...(supersedes ? { supersedes } : {}),
+      };
+    } catch (err) {
+      // Absolute backstop — the hook must never see an exception from here.
+      return { action: 'error', error: err?.message ?? String(err) };
+    }
+  }
+
+  /** Best-effort JSONL breadcrumb (project-local; never cascades). Shares the
+   * same log file as backfillAbandonedSession — the two are distinguishable
+   * by `_backfill_source` on the eventual sessions.jsonl record, and by the
+   * distinct action vocabulary above (`skipped-not-completed`,
+   * `skipped-no-state-md`, …) in the breadcrumb itself. */
+  function logBreadcrumb(res) {
+    try {
+      if (typeof log === 'function') {
+        log(res);
+        return;
+      }
+      if (typeof repoRoot !== 'string' || repoRoot.length === 0) return;
+      const logPath = path.join(repoRoot, ...BACKFILL_LOG_REL);
+      fs.mkdirSync(path.dirname(logPath), { recursive: true });
+      fs.appendFileSync(
+        logPath,
+        JSON.stringify({
+          timestamp: new Date(nowMs).toISOString(),
+          action: res.action,
+          session_id: res.sessionId ?? null,
+          ...(res.error ? { error: res.error } : {}),
+        }) + '\n',
+        'utf8'
+      );
+    } catch {
+      /* never let logging cascade into the caller */
+    }
+  }
+}
+
 /** Normalise the `now` arg (number ms | ISO string | undefined) → ms. */
 function resolveNowMs(now) {
   if (typeof now === 'number' && Number.isFinite(now)) return now;