session-orchestrator 3.22.0 → 3.24.0

package/scripts/archive-closed-prds.mjs

@@ -16,11 +16,16 @@
  *   2. Enumerate tracked .md files under --prd-dir (git ls-files), excluding
  *      *.original-uncommitted.md. A missing/empty --prd-dir yields [] → clean
  *      report, exit 0 (no crash) — see listTrackedPrds.
- *   3. For each doc: parse the FIRST `#NNN` Epic/Issue reference in the header
- *      region (first ~20 lines, up to the first `## ` section). No ref → skip (WARN).
- *   4. `glab issue view <iid> --output json` → state. Only `closed` refs archive;
+ *   3. For each doc: parse an Epic/Issue DECLARATION out of the header region
+ *      (first ~20 lines, up to the first `## ` section) — frontmatter key, label
+ *      line, or H1 title suffix. A bare `#NNN` in prose is a CITATION and never
+ *      counts (`citation-only`); no `#NNN` at all → `no-epic-ref`. Both skip.
+ *   4. Session ownership: a doc with uncommitted changes (`uncommitted`) or one
+ *      committed at/after this session's `started_at` (`foreign-session`) is
+ *      skipped — it belongs to a parallel session, not to us (#1123).
+ *   5. `glab issue view <iid> --output json` → state. Only `closed` refs archive;
  *      `opened` and unknown/error states skip (never guess).
- *   5. Closed → archiveFileToVault(...) into <vault>/<--vault-subdir>/. Under
+ *   6. Closed → archiveFileToVault(...) into <vault>/<--vault-subdir>/. Under
  *      --apply the source doc is removed with `git rm`; --dry-run (default) writes
  *      NOTHING (not even to the vault).
  *
@@ -29,8 +34,9 @@
  *
  * Exit codes: 0 success · 1 input/config error · 2 system error.
  *
- * Exports (for tests): main, parseEpicRef, readHeaderRegion, listTrackedPrds,
- *   epicState, defaultGlabRepo.
+ * Exports (for tests): main, parseEpicDeclaration, parseEpicRef, readHeaderRegion,
+ *   listTrackedPrds, epicState, classifyOwnership, readSessionStartedAt,
+ *   defaultGlabRepo.
  */
 
 import { readFileSync } from 'node:fs';
@@ -43,6 +49,9 @@ import { parseSessionConfig } from './lib/config.mjs';
 import { glabRun as defaultGlabRun } from './lib/vault-backfill/glab.mjs';
 import { archiveFileToVault, titleFromMarkdown } from './lib/vault-archive.mjs';
 import { defaultGlabRepo } from './lib/vcs-repo-spec.mjs';
+import { readLock } from './lib/session-lock.mjs';
+import { resolveStateMdPath } from './lib/state-md/frontmatter-mutators.mjs';
+import { parseStateMd } from './lib/state-md/yaml-parser.mjs';
 
 const DEFAULT_PRD_DIR = 'docs/prd';
 const DEFAULT_VAULT_SUBDIR = '01-projects/session-orchestrator/prd';
@@ -74,14 +83,184 @@ export { defaultGlabRepo };
 // Pure helpers
 // ---------------------------------------------------------------------------
 
+// A DECLARATION line names the doc's own tracking Epic/Issue. Three accepted
+// spellings, all anchored at line start so prose can never reach them:
+//   (a) `**Epic:** #1113`   — colon INSIDE the bold (the shape 2 of 4 live PRDs use)
+//   (b) `**Epic**: #1113`   — colon outside the bold
+//   (c) `Source: docs/prd/x.md (#786)` — unbolded (the plan-header shape,
+//       skills/write-executable-plan/SKILL.md:193)
+// The optional leading `-`/`*` covers list items (`- **Issue:** #366`).
+const LABEL_WORD = String.raw`(?:parent[ \t]+)?(?:epic|issues?|source)`;
+const LABEL_LINE_RE = new RegExp(
+  String.raw`^[-*]?[ \t]*(?:` +
+    String.raw`\*\*[ \t]*${LABEL_WORD}[ \t]*:[ \t]*\*\*` +
+    String.raw`|\*\*[ \t]*${LABEL_WORD}[ \t]*\*\*[ \t]*:` +
+    String.raw`|${LABEL_WORD}[ \t]*:` +
+    String.raw`)[ \t]*(\S.*)$`,
+  'i',
+);
+const FRONTMATTER_LINE_RE = /^(?:epic|issues?)[ \t]*:[ \t]*\[?[ \t]*['"]?#?(\d+)/i;
+const TITLE_SUFFIX_RE = /^#[ \t]+.*\(#(\d+)\)[ \t]*$/;
+const ANY_IID_RE = /#(\d+)/;
+
+/**
+ * Parse the doc's DECLARED Epic/Issue out of its header region.
+ *
+ * Precedence (first hit wins): frontmatter key → label line → H1 title suffix.
+ * A bare `#NNN` in prose is a CITATION and NEVER counts — that conflation is
+ * what deleted a live PRD on 2026-08-22 (#1112): a quoted, long-closed `#214`
+ * inside a blockquote read as the doc's own Epic, so the doc looked finished.
+ * The rule therefore prefers, by construction, documents that carry LESS
+ * context — hence the anchored line shapes below.
+ *
+ * @param {string} headerText — output of readHeaderRegion().
+ * @returns {{ iid: string, via: 'frontmatter'|'label'|'title' }|null}
+ */
+export function parseEpicDeclaration(headerText) {
+  const lines = String(headerText).split(/\r?\n/);
+
+  // (1) Frontmatter — only inside the LEADING `---` block, never a stray
+  // `epic:` line further down the header.
+  //
+  // A leading `---` alone does NOT make a frontmatter block: in Markdown it is
+  // also a thematic break, and a doc that opens with one would otherwise have
+  // its BODY read as frontmatter (a body line `epic: 1113` — or any `issue:`
+  // note — would then win over the real declaration below). Require a CLOSING
+  // `---` inside the header region; without it, fall through to label/title.
+  if (lines[0]?.trim() === '---') {
+    const close = lines.findIndex((line, i) => i > 0 && line.trim() === '---');
+    if (close !== -1) {
+      for (let i = 1; i < close; i++) {
+        const m = FRONTMATTER_LINE_RE.exec(lines[i]);
+        if (m) return { iid: m[1], via: 'frontmatter' };
+      }
+    }
+  }
+
+  // (2) Label line — the first `#NNN` on a recognised label line. Taking the
+  // first is correct for `**Epic:** #1048 · **Sub-Issues:** #1049 …`: the
+  // primary declaration leads, the sub-issues trail.
+  for (const line of lines) {
+    const label = LABEL_LINE_RE.exec(line);
+    if (!label) continue;
+    const iid = ANY_IID_RE.exec(label[1]);
+    if (iid) return { iid: iid[1], via: 'label' };
+  }
+
+  // (3) H1 title suffix — `# Feature: Foo (#1113)`.
+  for (const line of lines) {
+    const m = TITLE_SUFFIX_RE.exec(line);
+    if (m) return { iid: m[1], via: 'title' };
+  }
+
+  return null;
+}
+
 /**
- * Parse the FIRST `#NNN` issue reference out of a PRD header region.
+ * @deprecated Use {@link parseEpicDeclaration} — it also reports HOW the iid was
+ * declared, which the caller needs to tell `citation-only` from `no-epic-ref`.
+ * Retained as a thin shim for existing importers.
  * @param {string} headerText
- * @returns {string|null} the numeric iid as a string, or null when absent.
+ * @returns {string|null} the declared iid as a string, or null when absent.
  */
 export function parseEpicRef(headerText) {
-  const m = String(headerText).match(/#(\d+)/);
-  return m ? m[1] : null;
+  return parseEpicDeclaration(headerText)?.iid ?? null;
+}
+
+/**
+ * Decide whether a doc belongs to THIS session or to a parallel one (#1123).
+ *
+ * Author IDENTITY carries no signal here — every session commits as the same
+ * human — so the discriminator is commit TIME against this session's
+ * `started_at`, taken as MAX(author date, committer date) so a rebased or
+ * cherry-picked peer commit cannot read as old.
+ * Fail-closed in every ambiguous direction: a failed git probe,
+ * an unparseable commit timestamp, or a missing `sessionStartedAt` all yield
+ * `'foreign'`, because 'foreign' is the verdict that does NOT delete.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {string} args.rel — repo-relative doc path.
+ * @param {string|null|undefined} args.sessionStartedAt — ISO-8601.
+ * @param {(args: string[]) => { ok: boolean, stdout: string, stderr: string }} args.gitRunFn
+ * @returns {'mine'|'foreign'|'uncommitted'} never throws.
+ */
+export function classifyOwnership({ repoRoot, rel, sessionStartedAt, gitRunFn }) {
+  let status;
+  try {
+    status = gitRunFn(['-C', repoRoot, 'status', '--porcelain', '--', rel]);
+  } catch {
+    return 'foreign';
+  }
+  if (!status?.ok) return 'foreign';
+  // Non-empty porcelain output = staged, unstaged or untracked (`??`) — either
+  // way there is work in the tree that a `git rm` would destroy.
+  if (String(status.stdout).trim() !== '') return 'uncommitted';
+
+  const startedMs = Date.parse(String(sessionStartedAt ?? ''));
+  if (Number.isNaN(startedMs)) return 'foreign';
+
+  let log;
+  try {
+    // BOTH timestamps, newest wins. `%aI` alone is the AUTHOR date, which
+    // survives rebase, cherry-pick and `--amend` UNCHANGED — a peer session's
+    // doc rebased onto this branch keeps its old author date and would read as
+    // 'mine', i.e. as ours to `git rm`. `%cI` (committer date) moves with every
+    // rewrite, so MAX(author, committer) is the moment the object entered THIS
+    // history — the quantity the session-ownership guard actually needs.
+    log = gitRunFn(['-C', repoRoot, 'log', '-1', '--format=%aI%n%cI', '--', rel]);
+  } catch {
+    return 'foreign';
+  }
+  if (!log?.ok) return 'foreign';
+  const stamps = String(log.stdout)
+    .split(/\r?\n/)
+    .map((s) => Date.parse(s.trim()))
+    .filter((n) => !Number.isNaN(n));
+  if (stamps.length === 0) return 'foreign';
+  const committedMs = Math.max(...stamps);
+
+  return committedMs >= startedMs ? 'foreign' : 'mine';
+}
+
+/**
+ * Resolve THIS session's `started_at` (ISO-8601): the session lock first, the
+ * STATE.md frontmatter as fallback.
+ *
+ * @param {string} repoRoot
+ * @returns {string|null} null when neither source yields a parseable timestamp.
+ */
+export function readSessionStartedAt(repoRoot) {
+  try {
+    const startedAt = readLock({ repoRoot })?.started_at;
+    if (typeof startedAt === 'string' && !Number.isNaN(Date.parse(startedAt))) return startedAt;
+  } catch {
+    // fall through to STATE.md
+  }
+  try {
+    const parsed = parseStateMd(readFileSync(resolveStateMdPath(repoRoot), 'utf8'));
+    const startedAt = parsed?.frontmatter?.started_at;
+    if (typeof startedAt === 'string' && !Number.isNaN(Date.parse(startedAt))) return startedAt;
+  } catch {
+    // no STATE.md, or unreadable → null (fail-closed at the call site)
+  }
+  return null;
+}
+
+/**
+ * Read the issue iids this session declared in STATE.md frontmatter (`issues:`).
+ * @param {string} repoRoot
+ * @returns {Set<string>} empty when STATE.md is absent or carries no list.
+ */
+function readSessionIssues(repoRoot) {
+  try {
+    const parsed = parseStateMd(readFileSync(resolveStateMdPath(repoRoot), 'utf8'));
+    const issues = parsed?.frontmatter?.issues;
+    if (Array.isArray(issues)) return new Set(issues.map((n) => String(n)));
+  } catch {
+    // absent/unreadable → empty set
+  }
+  return new Set();
 }
 
 /**
@@ -167,7 +346,8 @@ function printHelp() {
 
 USAGE
   node scripts/archive-closed-prds.mjs [--dry-run|--apply] [--json]
-    [--prd-dir DIR] [--vault-subdir DIR] [--help]
+    [--prd-dir DIR] [--vault-subdir DIR] [--glab-repo SPEC]
+    [--ignore-session-guard] [--owned-issues-only] [--help]
 
 FLAGS
   --dry-run          (default) Plan the archive; write NOTHING (not even the vault).
@@ -180,6 +360,16 @@ FLAGS
                      shell wrapper and uses the ambient GITLAB_HOST). When
                      omitted, the spec is auto-detected from the local git
                      remote (prefers 'gitlab', else 'origin').
+  --ignore-session-guard
+                     Escape hatch for a CATCH-UP SWEEP: also consider docs last
+                     committed at/after this session's start (normally skipped
+                     as 'foreign-session', because they belong to a parallel
+                     session — #1123). Docs with uncommitted changes are STILL
+                     skipped; this flag never widens that guard.
+  --owned-issues-only
+                     Opt-in: archive only docs whose declared iid appears in
+                     this session's STATE.md 'issues:' list. Everything else
+                     skips as 'epic-#NNN-not-owned'.
   -h, --help         Show this help and exit.
 
 EXIT CODES
@@ -229,6 +419,8 @@ function printHuman(archived, skipped, isDryRun, vaultDir, vaultSubdir) {
  * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object }} [opts.hostPaths]
  *   — forwarded to parseSessionConfig. Tests pass `{ env: {}, ownerConfig: undefined }`
  *   for hermetic, owner.yaml-free vault-dir resolution (issue #653 bleed guard).
+ * @param {string|null} [opts.sessionStartedAt] — ISO-8601 override for the
+ *   session-ownership guard (#1123). Omitted → readSessionStartedAt(root).
  * @returns {{ code: 0|1|2, archived: object[], skipped: object[], vaultDir?: string, dryRun?: boolean }}
  */
 export function main({
@@ -238,6 +430,7 @@ export function main({
   gitRunFn = defaultGitRun,
   now,
   hostPaths,
+  sessionStartedAt,
 } = {}) {
   // ── Parse flags ──────────────────────────────────────────────────────────
   let apply = false;
@@ -247,6 +440,8 @@ export function main({
   let prdDir = DEFAULT_PRD_DIR;
   let vaultSubdir = DEFAULT_VAULT_SUBDIR;
   let glabRepo;
+  let ignoreSessionGuard = false;
+  let ownedIssuesOnly = false;
 
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -260,6 +455,8 @@ export function main({
     else if (a.startsWith('--vault-subdir=')) vaultSubdir = a.slice('--vault-subdir='.length);
     else if (a === '--glab-repo') glabRepo = argv[++i];
     else if (a.startsWith('--glab-repo=')) glabRepo = a.slice('--glab-repo='.length);
+    else if (a === '--ignore-session-guard') ignoreSessionGuard = true;
+    else if (a === '--owned-issues-only') ownedIssuesOnly = true;
     else {
       process.stderr.write(`archive-closed-prds: unknown argument: ${a}\n`);
       process.stderr.write('Run with --help for usage.\n');
@@ -314,6 +511,16 @@ export function main({
   // the local git remote (host-agnostic; nothing host-specific committed).
   const effectiveGlabRepo = glabRepo ?? defaultGlabRepo(root, gitRunFn);
 
+  // ── Session identity (ownership guard, #1123) ────────────────────────────
+  const startedAt = sessionStartedAt !== undefined ? sessionStartedAt : readSessionStartedAt(root);
+  if (!startedAt && !ignoreSessionGuard) {
+    warn(
+      'archive-closed-prds: no session started_at (session.lock/STATE.md) — every doc is treated ' +
+        'as foreign-session. Use --ignore-session-guard for a deliberate catch-up sweep.',
+    );
+  }
+  const ownedIssues = ownedIssuesOnly ? readSessionIssues(root) : null;
+
   // ── Enumerate + classify PRDs ────────────────────────────────────────────
   const prds = listTrackedPrds(root, prdDir, gitRunFn);
   const archived = [];
@@ -331,20 +538,51 @@ export function main({
       continue;
     }
 
-    const iid = parseEpicRef(header);
-    if (!iid) {
-      skipped.push({ source: rel, reason: 'no-epic-ref' });
-      warn(`archive-closed-prds: no Epic reference in header of ${rel} — skipped (never guess).`);
+    const decl = parseEpicDeclaration(header);
+    if (!decl) {
+      // Distinguish "nothing to go on" from "only a CITATION to go on" — the
+      // latter is the #1112 shape and the more dangerous of the two, because a
+      // quoted closed issue reads exactly like a declared one.
+      const citationOnly = ANY_IID_RE.test(header);
+      skipped.push({ source: rel, reason: citationOnly ? 'citation-only' : 'no-epic-ref' });
+      warn(
+        citationOnly
+          ? `archive-closed-prds: ${rel} header has #NNN only as a citation, not a declaration — skipped (#1112).`
+          : `archive-closed-prds: no Epic reference in header of ${rel} — skipped (never guess).`,
+      );
+      continue;
+    }
+    const { iid, via } = decl;
+
+    // Session ownership BEFORE any glab call: a doc a parallel session just
+    // committed is not ours to archive, whatever its Epic's state (#1123).
+    const ownership = classifyOwnership({ repoRoot: root, rel, sessionStartedAt: startedAt, gitRunFn });
+    if (ownership === 'uncommitted') {
+      skipped.push({ source: rel, reason: 'uncommitted', iid, via, ownership });
+      warn(`archive-closed-prds: ${rel} has uncommitted changes — skipped (never 'git rm' live work).`);
+      continue;
+    }
+    if (ownership === 'foreign' && !ignoreSessionGuard) {
+      skipped.push({ source: rel, reason: 'foreign-session', iid, via, ownership });
+      warn(
+        `archive-closed-prds: ${rel} was last committed at/after this session's start — skipped ` +
+          '(belongs to a parallel session; --ignore-session-guard overrides).',
+      );
+      continue;
+    }
+
+    if (ownedIssues && !ownedIssues.has(String(iid))) {
+      skipped.push({ source: rel, reason: `epic-#${iid}-not-owned`, iid, via, ownership });
       continue;
     }
 
     const state = epicState(iid, glabRunFn, effectiveGlabRepo);
     if (state === 'opened') {
-      skipped.push({ source: rel, reason: `epic-#${iid}-open`, iid });
+      skipped.push({ source: rel, reason: `epic-#${iid}-open`, iid, via, ownership });
       continue;
     }
     if (state === 'unknown') {
-      skipped.push({ source: rel, reason: `epic-#${iid}-state-unknown`, iid });
+      skipped.push({ source: rel, reason: `epic-#${iid}-state-unknown`, iid, via, ownership });
       warn(`archive-closed-prds: could not resolve state of Epic #${iid} for ${rel} — skipped.`);
       continue;
     }
@@ -364,11 +602,13 @@ export function main({
         title: titleFromMarkdown(header),
       });
     } catch (err) {
-      skipped.push({ source: rel, reason: `archive-failed: ${err.message}`, iid });
+      skipped.push({ source: rel, reason: `archive-failed: ${err.message}`, iid, via, ownership });
       warn(`archive-closed-prds: failed to archive ${rel}: ${err.message}`);
       continue;
     }
     entry.iid = iid;
+    entry.via = via;
+    entry.ownership = ownership;
 
     if (!isDryRun) {
       const rm = gitRunFn(['-C', root, 'rm', '--', rel]);

package/scripts/autopilot.mjs

@@ -47,6 +47,7 @@ import { selectMode } from './lib/mode-selector.mjs';
 import { probe, evaluate, DEFAULT_RESOURCE_THRESHOLDS } from './lib/resource-probe.mjs';
 import { detectPeers } from './lib/session-registry.mjs';
 import { normalizeSession } from './lib/session-schema.mjs';
+import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
 
 // ---------------------------------------------------------------------------
 // CLI-level flag extraction
@@ -174,17 +175,29 @@ const branch = detectBranch();
 const SESSIONS_JSONL_PATH = resolve('.orchestrator/metrics/sessions.jsonl');
 
 /**
- * Count the number of non-empty lines in sessions.jsonl. Returns 0 if missing.
- * @returns {number}
+ * Set of the DISTINCT session identities currently recorded in sessions.jsonl.
+ * Empty set when the file is missing or unreadable.
+ *
+ * Identities, not lines (#1167): the ledger is append-only, so one physical
+ * session can occupy two lines (an abandoned stub plus the authoritative
+ * record that supersedes it, or the systemic double-stub pair). The
+ * pre/post comparison below asks "did the session I just spawned record
+ * itself?", and a raw line count answers that question wrong in BOTH
+ * directions — a duplicate pair looks like two sessions, while a supersede
+ * append (+1 line, −1 stub) leaves a canonical COUNT unchanged. Comparing the
+ * id SETS is immune to both.
+ *
+ * @returns {Set<string>}
  */
-function countSessionLines() {
-  if (!existsSync(SESSIONS_JSONL_PATH)) return 0;
-  try {
-    const raw = readFileSync(SESSIONS_JSONL_PATH, 'utf8');
-    return raw.split('\n').filter((l) => l.trim().length > 0).length;
-  } catch {
-    return 0;
+function readSessionIds() {
+  if (!existsSync(SESSIONS_JSONL_PATH)) return new Set();
+  const ids = new Set();
+  for (const rec of readCanonicalSessions({ filePath: SESSIONS_JSONL_PATH })) {
+    if (typeof rec.session_id === 'string' && rec.session_id.length > 0) {
+      ids.add(rec.session_id);
+    }
   }
+  return ids;
 }
 
 /**
@@ -230,7 +243,12 @@ async function modeSelector() {
   // `backlogLimit` is intentionally NOT passed: the window default lives once,
   // in backlog-scan.mjs (`DEFAULT_BACKLOG_LIMIT`). The hand-written 50 that
   // stood here under-read this repo's own backlog and hid its critical issues.
+  // `repoRoot` is passed EXPLICITLY (#1071) rather than left to the helper's
+  // cwd default: this driver already reads learnings.jsonl and sessions.jsonl
+  // relative to the invocation directory, and an implicit default is the seam
+  // where those two roots silently drift apart.
   const signals = await buildLiveSignals({
+    repoRoot: process.cwd(),
     learnings: surfacedLearnings,
   });
   return selectMode(signals);
@@ -244,7 +262,7 @@ async function modeSelector() {
  * @returns {Promise<{session_id: string, agent_summary?: object, effectiveness?: object}>}
  */
 async function sessionRunner({ mode, autopilotRunId }) {
-  const preCount = countSessionLines();
+  const preIds = readSessionIds();
 
   await new Promise((res, rej) => {
     const childStdio = hasVerbose
@@ -276,8 +294,9 @@ async function sessionRunner({ mode, autopilotRunId }) {
     });
   });
 
-  const postCount = countSessionLines();
-  if (postCount === preCount) {
+  const postIds = readSessionIds();
+  const appeared = [...postIds].some((id) => !preIds.has(id));
+  if (!appeared) {
     throw new Error('no session record appended');
   }
 

package/scripts/backfill-abandoned-sessions.mjs

@@ -42,10 +42,12 @@ import { parseArgs } from 'node:util';
 import { fileURLToPath } from 'node:url';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
+import { emitEvent } from './lib/events.mjs';
 import { SO_PROJECT_DIR } from './lib/platform.mjs';
 
 const LOCK_ACQUIRED = 'orchestrator.session.lock.acquired';
 const SESSION_STARTED = 'orchestrator.session.started';
+const SESSION_ENDED = 'orchestrator.session.ended';
 
 /**
  * Default cap on how many candidates may reach the (expensive) shared core in a
@@ -54,12 +56,31 @@ const SESSION_STARTED = 'orchestrator.session.started';
  */
 export const SESSION_START_LIMIT = 25;
 
-/** Read a JSONL file into parsed objects; missing → []; malformed lines skipped. */
+/**
+ * Read a JSONL file into parsed objects; MISSING (ENOENT) → `[]` silently,
+ * UNREADABLE (EACCES/EISDIR/…) → `[]` with a stderr WARN (#1188); malformed
+ * lines skipped.
+ */
 function readJsonl(filePath) {
   let raw;
   try {
     raw = fs.readFileSync(filePath, 'utf8');
-  } catch {
+  } catch (err) {
+    // #1188 — ENOENT and EACCES/EISDIR are different facts: a missing ledger is
+    // the ordinary fresh-repo case; an UNREADABLE one previously read as "no
+    // records" and made every downstream count silently wrong. Same split as
+    // readLockDetailed (session-lock.mjs § absent vs unreadable).
+    if (!err || err.code !== 'ENOENT') {
+      process.stderr.write(
+        `⚠ backfill-abandoned-sessions: cannot read ${filePath} ` +
+          `(${err?.code ?? '?'}: ${err?.message ?? String(err)}) — ` +
+          'treating as EMPTY, counts below are floors\n',
+      );
+    }
+    // CEILING (BV-004): still [] rather than throw — this runs on the
+    // SessionStart path (SESSION_START_LIMIT), where a permissions fault must
+    // not crash the session start. REVISIT if the warn rate in events.jsonl
+    // shows masked corruption.
     return [];
   }
   const out = [];
@@ -86,16 +107,22 @@ function readJsonl(filePath) {
 export function planSessions({ repoRoot }) {
   const events = readJsonl(path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl'));
 
-  const semanticByUuid = new Map();
+  // Two independent UUID -> semantic bridges (#1167). `lock.acquired` is the
+  // original one, but a session that LOST the lock-acquire race never emits it;
+  // its `session.ended` event carries `semantic_session_id` all the same (since
+  // #1068 AC1) and was never read here. Without that second bridge the
+  // candidate resolved semantic=null and the shared core minted a SYNTHETIC id,
+  // writing a duplicate stub beside the record the SessionEnd hook had already
+  // written under the real semantic id (measured 2026-09-02 @ c3ab480: 8 pairs).
+  // lock.acquired keeps precedence — it is the older, mode-carrying attestation.
+  const semanticFromLock = new Map();
+  const semanticFromEnded = new Map();
   for (const ev of events) {
-    if (
-      ev.event === LOCK_ACQUIRED &&
-      typeof ev.session_id === 'string' &&
-      typeof ev.semantic_session_id === 'string'
-    ) {
-      semanticByUuid.set(ev.session_id, ev.semantic_session_id);
-    }
+    if (typeof ev.session_id !== 'string' || typeof ev.semantic_session_id !== 'string') continue;
+    if (ev.event === LOCK_ACQUIRED) semanticFromLock.set(ev.session_id, ev.semantic_session_id);
+    else if (ev.event === SESSION_ENDED) semanticFromEnded.set(ev.session_id, ev.semantic_session_id);
   }
+  const semanticByUuid = new Map([...semanticFromEnded, ...semanticFromLock]);
 
   const seen = new Set();
   const plan = [];
@@ -133,7 +160,14 @@ function readRecordedIds(repoRoot) {
   const records = readJsonl(path.join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl'));
   const ids = new Set();
   for (const r of records) {
-    if (r && typeof r.session_id === 'string') ids.add(r.session_id);
+    if (!r) continue;
+    if (typeof r.session_id === 'string') ids.add(r.session_id);
+    // #1167 — a backfilled record now stamps the harness UUID it was
+    // reconstructed from. Indexing it lets a bare-UUID candidate be recognised
+    // as already-recorded even though the record itself is keyed semantically —
+    // the join that was structurally impossible while the field was absent
+    // (0 of 286 records carried it, measured 2026-09-02 @ c3ab480).
+    if (typeof r.raw_session_id === 'string') ids.add(r.raw_session_id);
   }
   return ids;
 }
@@ -238,6 +272,7 @@ export async function runMigration({
       case 'backfilled':
         summary.backfilled += 1;
         if (res.deadByAge) summary.dead_by_age += 1;
+        await emitBackfillCompleted(repoRoot, item, res);
         // Keep the pre-filter snapshot in step with what we just wrote, so a
         // second candidate bridging to the SAME semantic id is skipped cheaply
         // instead of re-entering the core (which would reach the same verdict).
@@ -263,6 +298,40 @@ export async function runMigration({
   return summary;
 }
 
+/**
+ * Emit `orchestrator.session.backfill_completed` for a record THIS path wrote
+ * (#1167). Mirrors the payload of `hooks/on-session-end.mjs::emitBackfillOutcome`
+ * so both writers are queryable with one filter.
+ *
+ * Until now the startup/CLI path wrote records SILENTLY: only the SessionEnd
+ * hook emitted the event, so nothing in the event stream distinguished "the
+ * backfill never ran" from "the backfill ran here". Best-effort by contract —
+ * observability must never fail a migration run.
+ *
+ * @param {string} repoRoot
+ * @param {{sessionId: string, semanticSessionId: string|null}} item
+ * @param {{action: string, sessionId?: string, supersedes?: string, error?: string}} res
+ */
+async function emitBackfillCompleted(repoRoot, item, res) {
+  try {
+    await emitEvent(
+      'orchestrator.session.backfill_completed',
+      {
+        kind: 'abandoned',
+        action: typeof res?.action === 'string' ? res.action : 'unknown',
+        ...(typeof item?.sessionId === 'string' ? { session_id: item.sessionId } : {}),
+        ...(typeof item?.semanticSessionId === 'string'
+          ? { semantic_session_id: item.semanticSessionId }
+          : {}),
+        ...(typeof res?.sessionId === 'string' ? { record_id: res.sessionId } : {}),
+        ...(typeof res?.supersedes === 'string' ? { supersedes: res.supersedes } : {}),
+        ...(typeof res?.error === 'string' ? { reason: res.error } : {}),
+      },
+      { repoRoot },
+    );
+  } catch { /* observability is best-effort */ }
+}
+
 /**
  * SessionStart entry point (#926) — decouple the backfill from the /close path.
  *