session-orchestrator 5.11.0 → 5.13.0

package/scripts/lib/scope-baseline.mjs

@@ -85,7 +85,7 @@
  * a size-ceiling check and a frontmatter-round-trip-safety check (both
  * documented at frontmatter-mutators.mjs:307-328) — a breach of either
  * REFUSES the write (leaves STATE.md untouched) and surfaces as
- * `{ written: false, reason: 'size-ceiling' | 'frontmatter-unsafe' }`
+ * `{ written: false, reason: 'size-ceiling' | 'frontmatter-unsafe' | 'foreign-state-md' }`
  * instead of silently bypassing the guard the way the old private
  * `writeStateMdAtomic()` helper did.
  *
@@ -119,12 +119,16 @@
  * No I/O at import time. Node 20+ stdlib only.
  */
 
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
+import path from 'node:path';
 
-import { parseStateMd, serializeStateMd, resolveStateMdPath, writeStateMd } from './state-md.mjs';
+import { parseStateMd, serializeStateMd, writeStateMd } from './state-md.mjs';
+import { resolveStateMdWriteTarget } from './state-md/frontmatter-mutators.mjs';
 import { pathMatchesPattern } from './scope-gate.mjs';
 import { resolveBaselineRange, isQueryFailure } from './vcs-repo-spec.mjs';
+import { readProcessLocalSessionIds } from './session-identity/own-session.mjs';
+import { readSessionWorkTrees, sessionCommitFiles } from './session-work-trees.mjs';
 
 // ---------------------------------------------------------------------------
 // DRIFT_EXCLUDE_PATTERNS — the SINGLE filter source for both the denominator
@@ -271,6 +275,78 @@ function outputPaths(stdout) {
 // throws like any other failure and lands in the same skip.
 const DRIFT_GIT_TIMEOUT_MS = 10_000;
 
+/** realpath, or the resolved spelling when the path cannot be resolved. */
+function realOrResolved(p) {
+  try { return realpathSync(p); } catch { return path.resolve(p); }
+}
+
+/**
+ * Committed files from the session's OTHER own work trees (#1659).
+ *
+ * `session-start-ref` names one sha in the coordinator's own checkout; commits
+ * the same session made in its other worktrees are recorded as
+ * `orchestrator.session.work_tree` events (hooks/pre-bash-staging-fence.mjs).
+ * This reads them for the PROCESS-LOCAL raw session id
+ * (`readProcessLocalSessionIds`, never a repo-global file) and diffs each tree
+ * inside itself (`sessionCommitFiles`) — never across trees.
+ *
+ * Excluded before diffing: the own tree (realpath-equal to `ownTop`; the
+ * STATE.md ref stays authoritative there) and trees of a DIFFERENT repository
+ * (other `--git-common-dir`; their paths live in another path space). A tree
+ * whose common dir cannot be queried is passed through, so
+ * `sessionCommitFiles` names why it is unusable (`tree-missing`, …).
+ *
+ * Never throws: any failure yields `null` (no other-tree data), so the
+ * existing own-tree measurement is never turned into a skip by this source.
+ * That includes the own-tree identity queries (`--show-toplevel`,
+ * `--path-format=absolute` needs git >= 2.31): they run HERE, only once a
+ * session id exists, never inside computeDrift()'s numerator `try`.
+ *
+ * @param {{ repoRoot: string|undefined, gitOpts: object, env: object,
+ *           eventsFile?: string }} args
+ * @returns {{ files: string[], counted: number, skipped: number, otherRepo: number,
+ *             malformed: number, invalid: number } | null}
+ *   `null` when no other own tree is recorded. `malformed` / `invalid` carry
+ *   the reader's unreadable lines and own events without a usable tree/ref.
+ */
+function otherWorkTreeFiles({ repoRoot, gitOpts, env, eventsFile }) {
+  try {
+    const [sessionId] = readProcessLocalSessionIds({ env });
+    if (!sessionId) return null;
+    const read = readSessionWorkTrees({ sessionId, repoRoot, eventsFile });
+    if (read.trees.length === 0) return null;
+    const ownTop = realOrResolved(execFileSync('git', ['rev-parse', '--show-toplevel'], gitOpts).trim());
+    const ownCommonDir = realOrResolved(
+      execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], gitOpts).trim(),
+    );
+    const others = read.trees.filter((t) => realOrResolved(t.tree) !== ownTop);
+    if (others.length === 0) return null;
+    const sameRepo = [];
+    let otherRepo = 0;
+    for (const t of others) {
+      let common = null;
+      try {
+        common = execFileSync('git', ['-C', t.tree, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+          encoding: 'utf8', timeout: DRIFT_GIT_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+      } catch { /* unusable tree: sessionCommitFiles reports the reason */ }
+      if (common !== null && realOrResolved(common) !== ownCommonDir) { otherRepo += 1; continue; }
+      sameRepo.push(t);
+    }
+    const res = sessionCommitFiles({ trees: sameRepo });
+    return {
+      files: res.union,
+      counted: res.perTree.length,
+      skipped: res.skipped.length,
+      otherRepo,
+      malformed: read.malformed,
+      invalid: read.invalid,
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Internal: read + parse STATE.md's frontmatter exactly once. Shared by
  * `readBaseline()` and `computeDrift()` so a single `computeDrift()` call
@@ -280,7 +356,12 @@ const DRIFT_GIT_TIMEOUT_MS = 10_000;
  * @returns {{ ok: true, fm: object } | { ok: false, reason: 'no-state-md'|'unreadable-state-md' }}
  */
 function readFrontmatterOrReason(repoRoot) {
-  const statePath = resolveStateMdPath(repoRoot);
+  // #1636: the write side's ownership rule — another platform's STATE.md not
+  // proven to be this process's would lend its baseline and session-start-ref
+  // to THIS session's drift tripwire. It counts as absent (`no-state-md`,
+  // silent like every skip here; writeBaseline() already refuses it).
+  const { path: statePath, rejected } = resolveStateMdWriteTarget(repoRoot);
+  if (rejected) return { ok: false, reason: 'no-state-md' };
   let raw;
   try {
     raw = readFileSync(statePath, 'utf8');
@@ -418,7 +499,7 @@ export function readBaseline(repoRoot) {
  *   `filterExcluded()` pass at all). Anything that is not an array is
  *   rejected UP FRONT — before STATE.md is read or the lock is taken —
  *   as `{ written: false, reason: 'invalid-planned-files' }`.
- * @returns {Promise<{ written: boolean, reason?: 'invalid-planned-files'|'already-frozen'|'no-state-md'|'unreadable-state-md'|'lock-timeout'|'lock-fs-error'|'unexpected-error'|'size-ceiling'|'frontmatter-unsafe' }>}
+ * @returns {Promise<{ written: boolean, reason?: 'invalid-planned-files'|'already-frozen'|'no-state-md'|'unreadable-state-md'|'lock-timeout'|'lock-fs-error'|'unexpected-error'|'size-ceiling'|'frontmatter-unsafe'|'foreign-state-md' }>}
  */
 export async function writeBaseline({ repoRoot, intent, ownerBoundary, plannedFiles } = {}) {
   if (!Array.isArray(plannedFiles)) {
@@ -488,7 +569,8 @@ export async function writeBaseline({ repoRoot, intent, ownerBoundary, plannedFi
     // frontmatter-unsafe breach) — surface that reason rather than falling
     // back to the transformer's closure-captured reason, which was never
     // set on this path.
-    if (result.reason === 'size-ceiling' || result.reason === 'frontmatter-unsafe') {
+    // `foreign-state-md` (#1640): the target belongs to another session.
+    if (result.reason === 'size-ceiling' || result.reason === 'frontmatter-unsafe' || result.reason === 'foreign-state-md') {
       return { written: false, reason: result.reason };
     }
     return { written: false, reason: skipReason ?? 'unreadable-state-md' };
@@ -600,14 +682,29 @@ export async function writeBaseline({ repoRoot, intent, ownerBoundary, plannedFi
  * @param {string|undefined} args.repoRoot
  * @param {number} [args.threshold] — breach threshold, `>=` counts as
  *   breached (default `2.0`).
+ * @param {object} [args.env=process.env] — source of the PROCESS-LOCAL raw
+ *   session id whose other work trees are added (#1659); injectable for tests.
+ * @param {string} [args.eventsFile] — explicit events ledger for the
+ *   work-tree records (default: the repoRoot's ledger).
  * @returns {{ ok: true, skipped: true, reason: 'no-state-md'|'unreadable-state-md'|'no-baseline'|'stale-baseline'|'no-baseline-ref'|'unresolvable-ref' }
  *   | { ok: true, skipped: false, filesRatio: number, plannedFiles: number,
- *       actualFiles: number, breached: boolean, threshold: number, refUsed: string }}
+ *       actualFiles: number, breached: boolean, threshold: number, refUsed: string,
+ *       otherWorkTrees?: { counted: number, skipped: number, otherRepo: number,
+ *                          malformed: number, invalid: number } }}
  *   Additive since #1039: `no-baseline-ref` is a NEW member of the skip-reason
  *   union. No existing member was renamed or removed, and the measured-result
  *   shape (all eight keys) is byte-identical to the pre-#1039 contract.
+ *   Additive since #1659: the committed source also unions the files the
+ *   session (process-local raw id) committed in its OTHER own work trees of
+ *   the same repository, each diffed inside itself against its own recorded
+ *   start ref (`orchestrator.session.work_tree`). `otherWorkTrees` appears
+ *   only when such a tree is recorded: `counted` trees measured, `skipped`
+ *   trees unusable (gone, ref unresolvable — they never fail the drift),
+ *   `otherRepo` trees of a different repository (not comparable, ignored),
+ *   `malformed` unreadable ledger lines and `invalid` own events without a
+ *   usable tree/start_ref (a partial read, never a clean verdict).
  */
-export function computeDrift({ repoRoot, threshold = 2.0 } = {}) {
+export function computeDrift({ repoRoot, threshold = 2.0, env = process.env, eventsFile } = {}) {
   const parsedFm = readFrontmatterOrReason(repoRoot);
   if (!parsedFm.ok) {
     return { ok: true, skipped: true, reason: parsedFm.reason };
@@ -683,6 +780,11 @@ export function computeDrift({ repoRoot, threshold = 2.0 } = {}) {
     return { ok: true, skipped: true, reason: 'unresolvable-ref' };
   }
 
+  // #1659: add what the session committed in its OTHER own work trees. The
+  // own tree is excluded inside (its STATE.md ref above stays authoritative).
+  const otherTrees = otherWorkTreeFiles({ repoRoot, gitOpts, env, eventsFile });
+  if (otherTrees !== null) for (const file of otherTrees.files) changedFiles.add(file);
+
   // Same `filterExcluded()` primitive `writeBaseline()`'s denominator
   // (`countPlannedFiles()`) calls (#894 review finding F1), so the pattern
   // filter on both sides of the ratio is one function. The untracked
@@ -710,5 +812,18 @@ export function computeDrift({ repoRoot, threshold = 2.0 } = {}) {
     breached,
     threshold,
     refUsed,
+    // Additive (#1659), present ONLY when another own work tree is recorded,
+    // so the eight-key shape above is unchanged for single-tree sessions.
+    ...(otherTrees !== null
+      ? {
+        otherWorkTrees: {
+          counted: otherTrees.counted,
+          skipped: otherTrees.skipped,
+          otherRepo: otherTrees.otherRepo,
+          malformed: otherTrees.malformed,
+          invalid: otherTrees.invalid,
+        },
+      }
+      : {}),
   };
 }

package/scripts/lib/scope-echo.mjs

@@ -52,6 +52,7 @@ import { join, resolve } from 'node:path';
 import { digestSha256Short } from './crypto-digest-utils.mjs';
 import { isMainModule } from './is-main-module.mjs';
 import { isCoordinatorRecordId } from './scope-gate.mjs';
+import { resolveEventsLedgerRoot } from './platform.mjs';
 
 /** Marker the agent must emit. Case-sensitive by design — a lowercase lookalike is not an echo. */
 export const SCOPE_ECHO_MARKER = 'SCOPE-DIGEST:';
@@ -420,7 +421,8 @@ export function digestScopeFiles(stateDir, wave, { readDir = readdirSync, readFi
  * @param {number} params.wave
  * @param {string} params.stateDir
  * @param {string} [params.session]    semantic (or raw) session id to filter on
- * @param {string} [params.eventsPath] defaults to the cwd-relative `.orchestrator/metrics/events.jsonl`;
+ * @param {string} [params.eventsPath] defaults to `.orchestrator/metrics/events.jsonl` under
+ *   `resolveEventsLedgerRoot(cwd)`;
  *   the CLI passes `eventsFilePath(<state-dir>/..)` (the repo's one ledger, #1514)
  * @param {typeof readFileSync} [params.readFile]
  * @param {typeof readdirSync} [params.readDir]
@@ -437,7 +439,8 @@ export function verifyWaveScope({
   readFile = readFileSync,
   readDir = readdirSync,
 }) {
-  const ledgerPath = eventsPath || join('.orchestrator', 'metrics', 'events.jsonl');
+  // #1514/#1722: the default maps a linked worktree to the main checkout's one ledger.
+  const ledgerPath = eventsPath || join(resolveEventsLedgerRoot(process.cwd()), '.orchestrator', 'metrics', 'events.jsonl');
   let records = [];
   let malformedLines = 0;
   try {

package/scripts/lib/scope-gate.mjs

@@ -704,10 +704,12 @@ export function assertTestSiblingCoverage(fileScope, allowedPaths, opts = {}) {
  * module importing the barrel WOULD cycle).
  *
  * Two deltas the shared token stream does not carry, handled locally below:
- *   - `(`/`)`: `tokenizeCommand` keeps them inside word text (they are not
- *     control operators for its purpose). {@link peelSubshellParens} splits them
- *     back out as separators so `(echo x > y)` still yields `y` and
- *     `> >(cat)` still yields nothing.
+ *   - `(`/`)`: since #1667 `tokenizeCommand` already emits a subshell's parens
+ *     as `;` separators and hoists `$( … )` / backtick bodies as their own
+ *     commands. What still reaches this pass glued is word text the lexer keeps
+ *     on purpose — a process substitution word (`>(cat)`), `f()`, `arr=(…)`,
+ *     case patterns. {@link peelSubshellParens} splits those so `> >(cat)`
+ *     still yields nothing (the peeled `cat` lands in command-head position).
  *   - here-doc BODY tokens arrive as ordinary quoted words. They are DATA, and a
  *     body is multi-line, so the whitespace skip rule in
  *     {@link shouldSkipWriteTarget} drops them. (The delimiter word itself now
@@ -906,13 +908,13 @@ const INPUT_REDIRECT_OP_RE = /^\d*(?:<<<|<)$/;
  * Split leading `(` / trailing `)` off an UNQUOTED word token into standalone
  * separator tokens.
  *
- * `tokenizeCommand` does not treat parentheses as control operators (it does not
- * need to), so `(echo x > y)` arrives as words `(echo` … `y)`. Without this the
- * subshell's redirect target would read as the literal `y)` and be dropped by the
- * paren skip rule in {@link shouldSkipWriteTarget} — a silent DETECTION LOSS
- * versus the pre-#970 lexer. Peeling restores it, and process substitution
- * `> >(cat)` still yields nothing because the peeled `cat` lands in command-head
- * position rather than redirect-target position.
+ * Since #1667 `tokenizeCommand` splits a word-start subshell `(` / `)` itself,
+ * so `(echo x > y)` arrives as `;` `echo` `x` `>` `y` `;`. What still arrives
+ * glued is paren text the lexer deliberately keeps inside a word — a process
+ * substitution word (`>(cat)`), `f()`, `arr=(…)`, case patterns, and openers
+ * past its nesting cap. Peeling keeps those from reading as a literal `y)`
+ * target, and `> >(cat)` still yields nothing because the peeled `cat` lands in
+ * command-head position rather than redirect-target position.
  *
  * Quoted tokens are never peeled: `echo '(' x` must keep its literal paren.
  *
@@ -2021,6 +2023,11 @@ const DENIED_ABSOLUTE_TOP_SEGMENTS = Object.freeze([
   'Library',
   'Applications',
   'Windows',
+  // Windows machine-wide program and data roots (#1612, Opus review M3): the
+  // drive-less spelling of C:/ProgramData/** and C:/Program Files/** lands here.
+  'ProgramData',
+  'Program Files',
+  'Program Files (x86)',
 ]);
 
 /**
@@ -2151,7 +2158,10 @@ const CACHE_CARVEOUT_MIN_LITERAL_SEGMENTS = 4;
  * @returns {boolean}
  */
 function isSensitiveHomeSegment(segment) {
-  return segment.startsWith('.') || foldPath(segment) === 'library';
+  // AppData is Windows' counterpart of ~/Library: gh/glab tokens, browser
+  // profiles, credential caches (#1612, Opus review M3).
+  const folded = foldPath(segment);
+  return segment.startsWith('.') || folded === 'library' || folded === 'appdata';
 }
 
 /**
@@ -2267,14 +2277,24 @@ function classifyHomeGrant(normalizedEntry) {
   const cacheCarveout =
     foldPath(firstBelowHome) === CACHE_CARVEOUT_SEGMENT &&
     literal.length >= CACHE_CARVEOUT_MIN_LITERAL_SEGMENTS;
-  if (!cacheCarveout && isSensitiveHomeSegment(firstBelowHome)) {
+  // #1612 — Windows' os.tmpdir() is ~/AppData/Local/Temp, where worktrees and
+  // fixtures live. Same DEPTH rule as ~/.cache: the Temp root stays refused,
+  // a named directory below it is honoured.
+  const below = HOME_MIN_LITERAL_SEGMENTS - 1;
+  const windowsTempCarveout =
+    foldPath(firstBelowHome) === 'appdata' &&
+    literal.length >= below + 4 &&
+    foldPath(literal[below + 1]) === 'local' &&
+    foldPath(literal[below + 2]) === 'temp';
+  if (!cacheCarveout && !windowsTempCarveout && isSensitiveHomeSegment(firstBelowHome)) {
     return {
       verdict: 'error',
       reason:
-        `grants a sensitive home subdirectory ("${firstBelowHome}") — dot-directories and Library ` +
+        `grants a sensitive home subdirectory ("${firstBelowHome}") — dot-directories, Library and AppData ` +
         `hold credentials, tokens, owner.yaml and the agent guards themselves; scope a project ` +
-        `directory instead (the sole exception is ~/.cache/<project>/…, which must name at least ` +
-        `${CACHE_CARVEOUT_MIN_LITERAL_SEGMENTS} literal segments — #1406)`,
+        `directory instead (the exceptions are ~/.cache/<project>/…, which must name at least ` +
+        `${CACHE_CARVEOUT_MIN_LITERAL_SEGMENTS} literal segments — #1406, and a named directory ` +
+        `below Windows' temp root ~/AppData/Local/Temp — #1612)`,
     };
   }
 
@@ -2396,6 +2416,13 @@ export function canonicalizeGrantPrefix(absPath) {
  */
 export function gradeScopeEntry(entry, opts = {}) {
   if (typeof entry !== 'string' || entry.length === 0) return null;
+  // Windows drive-absolute grants (#1612): every check below speaks POSIX
+  // separators and Gate 5b matches the realpath candidate in its forward-slash
+  // form ("C:/Users/..."). Graded verbatim, `C:\a\b\**` had no "/" prefix at
+  // all ("/" resolves to "C:/") and a clean grant was reported non-canonical,
+  // so scripts/validate-wave-scope.mjs refused it (measured on Windows 11).
+  const windowsDrive = /^[A-Za-z]:[\\/]/.test(entry);
+  if (windowsDrive) entry = entry.replace(/\\/g, '/');
   const bag = opts !== null && typeof opts === 'object' ? opts : {};
   const resolver = typeof bag.resolve === 'function' ? bag.resolve : null;
   /** @param {string} p @returns {string} */
@@ -2431,7 +2458,7 @@ export function gradeScopeEntry(entry, opts = {}) {
     };
   }
 
-  if (!path.isAbsolute(entry)) return null;
+  if (!windowsDrive && !path.isAbsolute(entry)) return null;
 
   // `.` segments are collapsed BEFORE any classification (#1398): without it,
   // `/Users/./alice/.ssh/**` has a literal prefix whose third element is
@@ -2440,8 +2467,12 @@ export function gradeScopeEntry(entry, opts = {}) {
   // any entry containing `../`, whatever else it is.
   const normalized = path.posix.normalize(entry);
   const literalPrefix = literalGrantPrefix(normalized);
+  // The system-directory and home-root rules are written for POSIX roots; a
+  // drive-less spelling makes `C:/Users/<name>/**` as strict as `/Users/<name>/**`
+  // (before #1612 a Windows home grant was never classified at all).
+  const rootless = windowsDrive ? normalized.replace(/^[A-Za-z]:/, '') : normalized;
 
-  const deniedLiteral = deniedRootFor(literalPrefix, (p) => p);
+  const deniedLiteral = deniedRootFor(literalGrantPrefix(rootless), (p) => p);
   if (deniedLiteral !== null) {
     return {
       verdict: 'error',
@@ -2452,7 +2483,7 @@ export function gradeScopeEntry(entry, opts = {}) {
     };
   }
 
-  const home = classifyHomeGrant(normalized);
+  const home = classifyHomeGrant(rootless);
   if (home !== null) {
     return home.verdict === 'error'
       ? { verdict: 'error', code: 'home-grant', message: `${home.reason}: ${entry}` }
@@ -2481,7 +2512,11 @@ export function gradeScopeEntry(entry, opts = {}) {
     };
   }
 
-  if (canonicalPrefix !== literalPrefix) {
+  // Windows: realpath answers in forward slashes with an upper-case drive letter.
+  const comparable = (p) => (windowsDrive
+    ? p.replace(/\\/g, '/').replace(/^([a-z]):/, (_, d) => `${d.toUpperCase()}:`)
+    : p);
+  if (comparable(canonicalPrefix) !== comparable(literalPrefix)) {
     return {
       verdict: 'error',
       code: 'non-canonical',

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

@@ -64,6 +64,7 @@ import { serializeSessionLineChecked as defaultSerialize } from './session-schem
 import { resolveStateMdPath as defaultResolveStateMdPath } from './state-md/frontmatter-mutators.mjs';
 import { parseStateMd as defaultParseStateMd } from './state-md/yaml-parser.mjs';
 import { canonicalizeSessions } from './sessions-canonical.mjs';
+import { explainEventsLedgerRoot, resolveEventsLedgerRoot } from './platform.mjs';
 // Already in the hook import set (`emitEvent` lives there): the rotation-aware
 // reader adds no new file to the SessionStart/SessionEnd hook graph.
 import { eventsFilePath, scanEventsBackwards } from './events.mjs'; // eventsFilePath: #1514, the repo's one ledger
@@ -137,6 +138,25 @@ export function isLoggedBackfillAction(action) {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * A skip outcome when `repoRoot` sits in a LINKED worktree with no main
+ * checkout to map the ledger to (`git init --separate-git-dir`, a bare repo's
+ * worktree, stale worktree metadata): the resolver falls back to the worktree
+ * itself, and this writer would append into ITS `sessions.jsonl` again — the
+ * #1660 incident class. Says so on stderr in one line (#1666). `undefined`
+ * otherwise: write as before. The skip is a `skipped-*` action, so the
+ * breadcrumb log stays out of the worktree too.
+ *
+ * @param {string} repoRoot
+ * @returns {{ action: string, reason: string } | undefined}
+ */
+function unresolvedLedgerSkip(repoRoot) {
+  const { resolved, reason } = explainEventsLedgerRoot(repoRoot);
+  if (resolved) return undefined;
+  process.stderr.write(`session-close-backfill: skipped, sessions ledger not written into the worktree: ${reason}\n`);
+  return { action: 'skipped-ledger-root-unresolved', reason };
+}
+
 /**
  * True when `s` is an RFC 9562 UUID session id (any version 1-8, variant `10xx`).
  *
@@ -161,6 +181,19 @@ function markerName(id) {
   return `.backfilled-${cleaned}.marker`;
 }
 
+/**
+ * Give a TOCTOU marker back after the ledger append failed (#1609): a marker
+ * without its record would keep the candidate from ever being backfilled.
+ * Best-effort — a failed unlink leaves the old behaviour, never throws.
+ */
+function releaseMarker(markerPath) {
+  try {
+    fs.unlinkSync(markerPath);
+  } catch {
+    /* best-effort */
+  }
+}
+
 /**
  * Read a JSONL file into an array of parsed objects. Missing file (ENOENT) →
  * [] silently; an unreadable one (EACCES/EISDIR/…) → [] with a stderr WARN
@@ -971,9 +1004,11 @@ export async function backfillAbandonedSession({
       if (!sessionId && !semanticSessionId) {
         return { action: 'skipped-no-identifier' };
       }
+      const unresolved = unresolvedLedgerSkip(repoRoot);
+      if (unresolved) return unresolved;
 
       const eventsPath = eventsFilePath(repoRoot);
-      const sessionsPath = path.join(repoRoot, ...SESSIONS_REL);
+      const sessionsPath = path.join(resolveEventsLedgerRoot(repoRoot), ...SESSIONS_REL);
 
       // -- Resolve the SEMANTIC record id (sessions.jsonl key) ----------------
       // Two-phase so the common SessionEnd path stays cheap: when the id is
@@ -1145,8 +1180,29 @@ export async function backfillAbandonedSession({
         };
       }
 
-      // -- TOCTOU marker — atomic create-or-fail keyed by the final id --------
-      const markerPath = path.join(repoRoot, '.orchestrator', 'metrics', markerName(recordId));
+      // -- TOCTOU marker — atomic create-or-fail keyed by the CANDIDATE -------
+      // #1592: the marker guards the ledger it sits beside — the MAIN
+      // checkout's, shared by every worktree. A linked worktree has no
+      // `.orchestrator/metrics/` since #1584, hence the mkdir.
+      // #1609: keyed by the raw UUID when known, never by `recordId`: which id a
+      // run records under (semantic, or the UUID when the semantic key is
+      // occupied) depends on the ledger it read, so two racing runs of one
+      // candidate claimed different markers and both appended. A legacy marker
+      // (keyed by the record id) still counts as a lost claim, but only without a
+      // key switch: once the semantic key is occupied and we record under our own
+      // UUID, the semantic marker belongs to the session occupying that key.
+      const markerDir = path.dirname(sessionsPath);
+      const markerKey = isUuid(sessionId) ? sessionId : semanticRecordId;
+      const markerPath = path.join(markerDir, markerName(markerKey));
+      try {
+        fs.mkdirSync(markerDir, { recursive: true });
+      } catch {
+        /* the openSync below reports the real failure */
+      }
+      if (recordId === semanticRecordId && recordId !== markerKey
+        && fs.existsSync(path.join(markerDir, markerName(recordId)))) {
+        return { action: 'skipped-marker-exists', sessionId: recordId };
+      }
       try {
         const fd = openSync(markerPath, 'wx');
         closeSync(fd);
@@ -1162,6 +1218,7 @@ export async function backfillAbandonedSession({
       try {
         await appendJsonl(sessionsPath, validated);
       } catch (err) {
+        releaseMarker(markerPath);
         return { action: 'error', error: `append: ${err?.message ?? String(err)}`, sessionId: recordId };
       }
       return {
@@ -1185,7 +1242,8 @@ export async function backfillAbandonedSession({
       }
       if (typeof repoRoot !== 'string' || repoRoot.length === 0) return;
       if (!isLoggedBackfillAction(res.action)) return;
-      const logPath = path.join(repoRoot, ...BACKFILL_LOG_REL);
+      // #1592: one breadcrumb log beside the one ledger, not one per worktree.
+      const logPath = path.join(resolveEventsLedgerRoot(repoRoot), ...BACKFILL_LOG_REL);
       fs.mkdirSync(path.dirname(logPath), { recursive: true });
       fs.appendFileSync(
         logPath,
@@ -1298,6 +1356,8 @@ export async function backfillCompletedFromStateMd({
       if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
         return { action: 'error', error: 'repoRoot must be a non-empty string' };
       }
+      const unresolved = unresolvedLedgerSkip(repoRoot);
+      if (unresolved) return unresolved;
 
       // -- Read + parse STATE.md ------------------------------------------------
       const stateMdPath = resolveStateMdPath(repoRoot);
@@ -1334,7 +1394,7 @@ export async function backfillCompletedFromStateMd({
       // 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 sessionsPath = path.join(resolveEventsLedgerRoot(repoRoot), ...SESSIONS_REL);
       const existing = classifyExisting(readFileSync, sessionsPath, {
         recordId,
         sessionId: nativeId,
@@ -1407,7 +1467,13 @@ export async function backfillCompletedFromStateMd({
 
       // -- 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}`));
+      // #1592: beside the shared ledger it guards (see backfillAbandonedSession).
+      const markerPath = path.join(path.dirname(sessionsPath), markerName(`completed-${recordId}`));
+      try {
+        fs.mkdirSync(path.dirname(markerPath), { recursive: true });
+      } catch {
+        /* the openSync below reports the real failure */
+      }
       try {
         const fd = openSync(markerPath, 'wx');
         closeSync(fd);
@@ -1422,6 +1488,7 @@ export async function backfillCompletedFromStateMd({
       try {
         await appendJsonl(sessionsPath, validated);
       } catch (err) {
+        releaseMarker(markerPath);
         return { action: 'error', error: `append: ${err?.message ?? String(err)}`, sessionId: recordId };
       }
       return {
@@ -1449,7 +1516,8 @@ export async function backfillCompletedFromStateMd({
       }
       if (typeof repoRoot !== 'string' || repoRoot.length === 0) return;
       if (!isLoggedBackfillAction(res.action)) return;
-      const logPath = path.join(repoRoot, ...BACKFILL_LOG_REL);
+      // #1592: one breadcrumb log beside the one ledger, not one per worktree.
+      const logPath = path.join(resolveEventsLedgerRoot(repoRoot), ...BACKFILL_LOG_REL);
       fs.mkdirSync(path.dirname(logPath), { recursive: true });
       fs.appendFileSync(
         logPath,