session-orchestrator 5.12.0 → 5.13.0

package/scripts/close-precheck.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * close-precheck.mjs — classify `<state-dir>/STATE.md` before `/close` hands
+ * off to session-end (#1661). Logic: `lib/session-end/close-precheck.mjs`.
+ *
+ * Usage:
+ *   node scripts/close-precheck.mjs [--repo-root <dir>] [--state-dir <dir>] [--confirm-own <token>]
+ *
+ * `--confirm-own` takes the 16-hex `confirmToken` of an `ownership-unproven`
+ * result and confirms that STATE.md as this session's while unchanged (#1718).
+ *
+ * Prints one JSON object: `verdict`, `runsSessionEnd`, `ownership`, `status`,
+ * `stateSessionId`, `ownSessionIds`, `statePath`, optional `reason`; with
+ * `ownership-unproven` also `wouldRun`, `confirmToken`, `session`, `startedAt`.
+ * Exit 0 for every verdict (a stop is an answer, not an error; Claude Code
+ * marks every non-zero exit as a tool failure) · 2 usage error.
+ */
+
+import { classifyCloseState, RUNS_SESSION_END } from './lib/session-end/close-precheck.mjs';
+
+function parseArgs(argv) {
+  const out = { repoRoot: process.cwd(), stateDir: undefined, confirmToken: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--repo-root' || a === '--state-dir') {
+      const v = argv[++i];
+      if (!v) throw new Error(`${a} needs a value`);
+      if (a === '--repo-root') out.repoRoot = v; else out.stateDir = v;
+    } else if (a === '--confirm-own') {
+      const v = argv[++i];
+      if (!v || !/^[0-9a-f]{16}$/.test(v)) throw new Error('--confirm-own needs a 16-hex token');
+      out.confirmToken = v;
+    } else if (a === '--help' || a === '-h') {
+      out.help = true;
+    } else {
+      throw new Error(`unknown argument: ${a}`);
+    }
+  }
+  return out;
+}
+
+let args;
+try {
+  args = parseArgs(process.argv.slice(2));
+} catch (err) {
+  process.stderr.write(`close-precheck: ${err.message}\n`);
+  process.exit(2);
+}
+if (args.help) {
+  process.stdout.write('Usage: node scripts/close-precheck.mjs [--repo-root <dir>] [--state-dir <dir>] [--confirm-own <token>]\n');
+  process.exit(0);
+}
+
+const result = classifyCloseState({ repoRoot: args.repoRoot, stateDir: args.stateDir, confirmToken: args.confirmToken });
+process.stdout.write(`${JSON.stringify({ ...result, runsSessionEnd: RUNS_SESSION_END.has(result.verdict) })}\n`);

package/scripts/dialectic-deriver.mjs

@@ -46,10 +46,11 @@ import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 
 import { readPeerCards } from './lib/peer-cards/reader.mjs';
-import { filterRealSessions } from './lib/session-schema/filters.mjs';
-import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
+import { readCanonicalSessions, isMeasuredSession } from './lib/sessions-canonical.mjs';
 import { recordDialecticRun } from './lib/learnings/evolve-telemetry.mjs';
 import { DEFAULT_BUDGET_TOKENS } from './lib/config/dialectic.mjs';
+import { withVisibleInboxText } from './lib/learnings/surface.mjs';
+import { resolveLedgerPath } from './lib/ledger-path.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -400,17 +401,24 @@ function parseTargetFromInfo(info) {
  * Best-effort read of a JSONL file: line-by-line JSON.parse with malformed-
  * line skip. Returns [] when the file is missing or empty.
  *
+ * For the canonical `learnings.jsonl` the visible records of a sibling
+ * `learnings-inbox.jsonl` are appended (#1516, #1685) via the shared
+ * visibility rule in `withVisibleInboxText` — also when the live file is
+ * absent (inbox host). An unreadable inbox never costs the live read.
+ *
  * @param {string} absPath
  * @returns {Promise<Array<object>>}
  */
 async function readJsonlBestEffort(absPath) {
-  if (!existsSync(absPath)) return [];
-  let raw;
-  try {
-    raw = await readFile(absPath, 'utf8');
-  } catch {
-    return [];
+  let raw = '';
+  if (existsSync(absPath)) {
+    try {
+      raw = await readFile(absPath, 'utf8');
+    } catch {
+      return [];
+    }
   }
+  raw = await withVisibleInboxText(absPath, raw);
   /** @type {Array<object>} */
   const out = [];
   for (const line of raw.split('\n')) {
@@ -435,7 +443,7 @@ async function readJsonlBestEffort(absPath) {
  * @returns {Promise<Array<object>>}
  */
 async function readTopLearnings(repoRoot, topN) {
-  const path = join(repoRoot, '.orchestrator', 'metrics', 'learnings.jsonl');
+  const path = resolveLedgerPath('.orchestrator/metrics/learnings.jsonl', repoRoot); // #1722
   const entries = await readJsonlBestEffort(path);
   entries.sort((a, b) => {
     const ca = typeof a?.confidence === 'number' ? a.confidence : 0;
@@ -451,8 +459,8 @@ async function readTopLearnings(repoRoot, topN) {
 /**
  * Read and rank sessions: collapse ledger duplicates (#1209 — the ledger is
  * append-only and can carry more than one raw line per physical session, see
- * `scripts/lib/sessions-canonical.mjs` header), filter out phantom
- * `status: 'abandoned'` stubs (#834, session-close-backfill), sort by
+ * `scripts/lib/sessions-canonical.mjs` header), retain measured work
+ * via isMeasuredSession (#1584), excluding synthetic completed stubs, sort by
  * `completed_at` DESC, take last K.
  *
  * Without the dedup, a duplicate ledger line for the SAME session can occupy
@@ -467,7 +475,7 @@ async function readTopLearnings(repoRoot, topN) {
  * @returns {Array<object>}
  */
 function readLastSessions(repoRoot, lastK) {
-  const entries = filterRealSessions(readCanonicalSessions({ repoRoot }));
+  const entries = readCanonicalSessions({ repoRoot }).filter(isMeasuredSession);
   entries.sort((a, b) => {
     const ta = typeof a?.completed_at === 'string' ? a.completed_at : '';
     const tb = typeof b?.completed_at === 'string' ? b.completed_at : '';

package/scripts/emit-event.mjs

@@ -31,7 +31,7 @@
 
 import { parseArgs } from 'node:util';
 import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -141,7 +141,7 @@ if (payloadRaw !== undefined) {
 
 let emitEvent;
 try {
-  ({ emitEvent } = await import(join(__dirname, 'lib', 'events.mjs')));
+  ({ emitEvent } = await import(pathToFileURL(join(__dirname, 'lib', 'events.mjs')).href));
 } catch (err) {
   fail(`failed to load events.mjs: ${err.message}`, 2, jsonMode);
 }

package/scripts/emit-session.mjs

@@ -27,17 +27,21 @@
  *   {"action":"appended","path":"<file>","session_id":"<id>","schema_version":2}
  */
 
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { resolveEventsLedgerRoot } from './lib/platform.mjs';
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { explainEventsLedgerRoot, resolveEventsLedgerRoot } from './lib/platform.mjs';
 import { appendJsonl } from './lib/common.mjs';
+import { resolveLedgerPath } from './lib/ledger-path.mjs';
 import {
   MEMORY_CLEANUP_EVENT,
   deriveMemoryCleanupSignal,
   stampMemoryCleanup,
 } from './lib/memory-cleanup-stamp.mjs';
-import { parseStateMd, readSessionProfile, resolveStateMdPath } from './lib/state-md.mjs';
+import { parseStateMd, readSessionProfile } from './lib/state-md.mjs';
+import { resolveStateMdWriteTarget, warnForeignStateMd } from './lib/state-md/frontmatter-mutators.mjs';
 import { readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
+import { readSessionWorkTrees } from './lib/session-work-trees.mjs';
 import { rollupSessionTokens } from './lib/session-token-rollup.mjs';
 import { COST_BASIS, PRICING_TABLE_DATE } from './lib/telemetry/pricing.mjs';
 import { serializeSessionLineChecked } from './lib/session-schema/serializer.mjs';
@@ -50,6 +54,7 @@ import {
   normalizeWaveKeys,
 } from './lib/session-schema.mjs';
 import { stableHostname } from './lib/host-identity.mjs';
+import { activeDir } from './lib/session-registry.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 
 /**
@@ -181,18 +186,23 @@ function resolveOwnSessionUuid({ override, recordSessionId }) {
  * Whole-file read, like deriveMemoryCleanupSignal() on the same file — fine at
  * today's events.jsonl size; revisit if the file outgrows a single read.
  *
+ * `behind` (#1668) is that same event's count of upstream commits the checkout
+ * lacked at start: a non-negative integer when measured, null when the event
+ * carries none (no upstream, or a pre-#1668 writer) — never read as 0.
+ *
  * Never throws.
  *
  * @param {string} eventsFile
  * @param {string} uuid
- * @returns {string|null}
+ * @returns {{ headSha: string|null, behind: number|null }}
  */
 function readOwnStartHeadSha(eventsFile, uuid) {
+  const none = { headSha: null, behind: null };
   let raw;
   try {
     raw = readFileSync(eventsFile, 'utf8');
   } catch {
-    return null;
+    return none;
   }
   for (const line of raw.split('\n')) {
     if (!line.includes(uuid)) continue;
@@ -203,14 +213,115 @@ function readOwnStartHeadSha(eventsFile, uuid) {
       continue;
     }
     if (ev?.event !== 'orchestrator.session.started' || ev.session_id !== uuid) continue;
-    if (ev.native_source === 'compact' || ev.native_source === 'resume') return null;
-    return typeof ev.head_sha === 'string' && FULL_SHA_RE.test(ev.head_sha) ? ev.head_sha : null;
+    if (ev.native_source === 'compact' || ev.native_source === 'resume') return none;
+    return {
+      headSha: typeof ev.head_sha === 'string' && FULL_SHA_RE.test(ev.head_sha) ? ev.head_sha : null,
+      behind: Number.isInteger(ev.behind) && ev.behind >= 0 ? ev.behind : null,
+    };
+  }
+  return none;
+}
+
+/**
+ * True when THIS session's registry entry proves it works in a different tree
+ * than the one it started in (#1652): `work_root` (refreshed at every turn end,
+ * #1605) differs from `session_root` (the SessionStart project root, the tree
+ * `head_sha` was measured in). Then the start event's `head_sha` names the
+ * wrong tree — a `<head_sha>..HEAD` range would attribute that tree's history,
+ * not the session's commits — so the fallback must not adopt it.
+ *
+ * Absent entry, absent roots or an unreadable file → false (no proof of a
+ * divergence; the pre-#1652 behaviour). Ceiling: `work_root` follows the
+ * harness cwd, so a coordinator that commits in a worktree through absolute
+ * paths without changing its cwd is not detected — the primary source is the
+ * STATE.md `session-start-ref` (HEAD of the session's own checkout — repoRoot,
+ * the tree STATE.md lives in; commits in additional worktrees: #1659).
+ *
+ * Never throws.
+ *
+ * @param {string} uuid
+ * @returns {boolean}
+ */
+function startTreeDiverged(uuid) {
+  if (!/^[A-Za-z0-9._-]+$/.test(uuid) || uuid.startsWith('.')) return false;
+  try {
+    const entry = JSON.parse(readFileSync(join(activeDir(), `${uuid}.json`), 'utf8'));
+    const { session_root: sessionRoot, work_root: workRoot } = entry ?? {};
+    return typeof sessionRoot === 'string' && typeof workRoot === 'string' && sessionRoot !== workRoot;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Realpath, or the resolved path when it does not exist (any more).
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+function realOrResolved(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+/**
+ * Keep only well-formed `session_work_trees` entries (#1659): an absolute
+ * `tree` and a FULL hex `start_ref` — the shape the work_tree reader accepts.
+ * Invalid entries are dropped, never the record.
+ *
+ * @param {unknown} value
+ * @returns {{ entries: Array<{ tree: string, start_ref: string }>, dropped: number } | null}
+ *   null when `value` is not an array at all.
+ */
+function sanitizeWorkTrees(value) {
+  if (!Array.isArray(value)) return null;
+  const entries = [];
+  for (const item of value) {
+    if (item && typeof item.tree === 'string' && isAbsolute(item.tree)
+      && typeof item.start_ref === 'string' && FULL_SHA_RE.test(item.start_ref)) {
+      entries.push({ tree: item.tree, start_ref: item.start_ref });
+    }
+  }
+  return { entries, dropped: value.length - entries.length };
+}
+
+/**
+ * The own checkout's top level — the tree emit-session runs in (process.cwd(),
+ * where it also reads STATE.md and current-session.json). null outside a git
+ * repo. Never throws.
+ *
+ * @returns {string|null}
+ */
+function ownCheckoutTop() {
+  try {
+    const top = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      timeout: 10_000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return top ? realOrResolved(top) : null;
+  } catch {
+    return null;
   }
-  return null;
 }
 
 function parseArgs(argv) {
-  const args = { file: '.orchestrator/metrics/sessions.jsonl', entry: null, sessionUuid: null };
+  // The default shares the events ledger's main-checkout root (#1584).
+  // Explicit --file paths below remain verbatim, including relative paths.
+  // #1659: a linked worktree whose common dir is not named `.git`
+  // (`--separate-git-dir`, bare repo) has no main checkout to map to, and the
+  // resolver falls back to the WORKTREE — a second, per-worktree ledger. The
+  // default is therefore resolved after parsing and refused when unmapped.
+  const args = {
+    file: null,
+    // true when --file was not given and the default sessions ledger is used
+    fileDefaulted: false,
+    entry: null,
+    sessionUuid: null,
+  };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--file') args.file = argv[++i];
@@ -219,7 +330,7 @@ function parseArgs(argv) {
     else if (a === '--help' || a === '-h') {
       process.stdout.write(
         'Usage: node scripts/emit-session.mjs [--file PATH] [--entry JSON]\n' +
-          '  --file   target JSONL file (default: .orchestrator/metrics/sessions.jsonl)\n' +
+          '  --file   explicit target JSONL file (default: main-checkout/.orchestrator/metrics/sessions.jsonl)\n' +
           '  --entry  entry JSON (if omitted, read from stdin)\n' +
           '  --session-uuid  raw harness UUID (default: owned .orchestrator/current-session.json)\n' +
           'Exit codes: 0 append ok, 1 validation error, 2 I/O error\n'
@@ -230,6 +341,22 @@ function parseArgs(argv) {
       process.exit(2);
     }
   }
+  if (args.file === null) {
+    // The cwd is the EXPLICIT root (like the former resolveEventsLedgerRoot
+    // call and every other sessions.jsonl reader), so a launch-dir env var
+    // never redirects the default --file; an unmapped worktree is still
+    // detected (#1659).
+    const ledger = explainEventsLedgerRoot(process.cwd());
+    if (!ledger.resolved) {
+      process.stderr.write(
+        `emit-session: refusing the default --file: ${ledger.reason}; pass an explicit --file\n`
+      );
+      process.exit(2);
+    }
+    // ledger-root: ledger.root comes from explainEventsLedgerRoot (sessions rule)
+    args.file = join(ledger.root, '.orchestrator', 'metrics', 'sessions.jsonl');
+    args.fileDefaulted = true;
+  }
   return args;
 }
 
@@ -416,8 +543,15 @@ async function main() {
   if (needsProfile || needsStartRef) {
     let stateMdContents = '';
     try {
-      const stateMdPath = resolveStateMdPath(process.cwd());
-      if (existsSync(stateMdPath)) stateMdContents = readFileSync(stateMdPath, 'utf8');
+      // #1622: the write side's ownership rule — another platform's STATE.md
+      // not proven to be this process's counts as no STATE.md.
+      const { path: stateMdPath, rejected } = resolveStateMdWriteTarget(process.cwd());
+      if (rejected) {
+        warnForeignStateMd('emit-session', rejected, stateMdPath);
+        stateMdStartRefNote = "STATE.md foreign (another platform's, not this process's session-id)";
+      } else if (existsSync(stateMdPath)) {
+        stateMdContents = readFileSync(stateMdPath, 'utf8');
+      }
     } catch (err) {
       process.stderr.write(
         `emit-session: WARN could not read STATE.md for session_profile/session_start_ref ` +
@@ -483,10 +617,28 @@ async function main() {
   // with a WARN whether or not an own UUID was available (#1457 point 2) —
   // without one the fallback cannot run, which is exactly when silence hid it.
   if (!hasOwn('session_start_ref')) {
-    const headSha = ownUuid !== null
+    const { headSha, behind } = ownUuid !== null
       ? readOwnStartHeadSha(siblingEventsFile(args.file), ownUuid)
-      : null;
-    if (headSha !== null) {
+      : { headSha: null, behind: null };
+    if (headSha !== null && behind !== null && behind > 0) {
+      // #1668 — the checkout was provably behind its upstream at start. A pull
+      // during the session makes `<head_sha>..HEAD` span the upstream commits it
+      // pulled in; no sha known at start fixes that (merge-base(head_sha,
+      // upstream) IS head_sha when merely behind, and upstream_sha is wrong when
+      // nothing was pulled), so the ref is dropped rather than overstated.
+      // behind 0 or not measured (absent) keep the pre-#1668 adoption below.
+      process.stderr.write(
+        `emit-session: WARN no session_start_ref — ${stateMdStartRefNote}, and the own ` +
+          `session.started head_sha=${headSha} was ${behind} commit(s) behind its upstream; ` +
+          'a range from it can include pulled-in upstream commits (#1668)\n'
+      );
+    } else if (headSha !== null && startTreeDiverged(ownUuid)) {
+      process.stderr.write(
+        `emit-session: WARN no session_start_ref — ${stateMdStartRefNote}, and the own ` +
+          `session.started head_sha=${headSha} was measured in session_root, not the work_root ` +
+          'this session works in (#1652)\n'
+      );
+    } else if (headSha !== null) {
       repaired = { ...repaired, session_start_ref: headSha };
       process.stderr.write(
         `emit-session: derived session_start_ref=${headSha} from the own orchestrator.session.started event\n`
@@ -503,6 +655,61 @@ async function main() {
     repaired = { ...repaired, raw_session_id: ownUuid };
   }
 
+  // `session_work_trees` (#1659) — the (tree, start_ref) pairs the staging
+  // fence recorded before each of THIS session's commits
+  // (`orchestrator.session.work_tree`, joined on the own raw id — never on a
+  // repo-global file). `session_start_ref` names one sha in the own checkout,
+  // so the field is written ONLY when it adds something: ≥2 trees, or one tree
+  // that is not the own checkout. An explicit key on the record wins, but its
+  // malformed entries are dropped with a WARN (like session_start_ref above —
+  // enforced here, not in validateSession()). Best-effort: any failure omits
+  // the field with a WARN; it never fails the emit.
+  if (hasOwn('session_work_trees')) {
+    const clean = sanitizeWorkTrees(repaired.session_work_trees);
+    if (clean === null) {
+      process.stderr.write('emit-session: WARN session_work_trees is not an array; dropping it\n');
+      const { session_work_trees: _dropped, ...rest } = repaired;
+      repaired = rest;
+    } else if (clean.dropped > 0) {
+      process.stderr.write(
+        `emit-session: WARN session_work_trees: dropping ${clean.dropped} malformed entry/entries\n`
+      );
+      repaired = { ...repaired, session_work_trees: clean.entries };
+    }
+  } else if (ownUuid !== null) {
+    try {
+      const read = readSessionWorkTrees({ sessionId: ownUuid, eventsFile: siblingEventsFile(args.file) });
+      if (read.error) {
+        process.stderr.write(
+          `emit-session: WARN could not read work_tree events (${read.error}); omitting session_work_trees\n`
+        );
+      } else if (read.malformed > 0) {
+        // Unreadable lines may hide own work_tree events — warn even when no
+        // tree was read, since then the omission itself may be the gap (#1659).
+        process.stderr.write(
+          `emit-session: WARN ${read.malformed} unreadable events ledger line(s); session_work_trees may be incomplete\n`
+        );
+      }
+      if (!read.error && read.trees.length > 0) {
+        if (read.invalid > 0) {
+          process.stderr.write(
+            `emit-session: WARN ignored ${read.invalid} own work_tree event(s) without a valid tree/start_ref\n`
+          );
+        }
+        // A single tree is only worth recording when it provably differs from
+        // the own checkout; outside a git repo that is unprovable → omitted.
+        const ownTop = read.trees.length >= 2 ? null : ownCheckoutTop();
+        const addsInfo = read.trees.length >= 2
+          || (ownTop !== null && realOrResolved(read.trees[0].tree) !== ownTop);
+        if (addsInfo) repaired = { ...repaired, session_work_trees: read.trees };
+      }
+    } catch (err) {
+      process.stderr.write(
+        `emit-session: WARN session_work_trees derivation failed (${err?.message ?? err}); omitting it\n`
+      );
+    }
+  }
+
   // Token rollup (#1436) — mechanical, replacing the session-metrics-write.md
   // prose step that had no production caller. Joins the sibling subagents.jsonl
   // on the own raw UUID and fills ONLY keys the entry does not carry; an
@@ -518,10 +725,22 @@ async function main() {
   if (ownUuid !== null && !hasOwn('total_tokens')) {
     let rollup = null;
     try {
-      rollup = rollupSessionTokens({
-        parentSessionId: ownUuid,
-        subagentsPath: join(dirname(args.file), 'subagents.jsonl'),
-      });
+      // A defaulted --file reads the subagents ledger where the hook writer
+      // (hooks/subagent-telemetry.mjs) puts it: resolved from the cwd first, then
+      // from the ledger root — the hook resolves from the LAUNCH dir, which is
+      // the main checkout when the session entered this worktree later and the
+      // repo versions the ledger. First copy with a record of this session wins,
+      // so nothing is counted twice. An explicit --file keeps its sibling.
+      const candidates = args.fileDefaulted
+        ? [...new Set([
+          resolveLedgerPath('.orchestrator/metrics/subagents.jsonl', process.cwd()),
+          resolveLedgerPath('.orchestrator/metrics/subagents.jsonl', resolveEventsLedgerRoot(process.cwd())),
+        ])]
+        : [join(dirname(args.file), 'subagents.jsonl')];
+      for (const subagentsPath of candidates) {
+        rollup = rollupSessionTokens({ parentSessionId: ownUuid, subagentsPath });
+        if (rollup.matched_records > 0) break;
+      }
     } catch (err) {
       process.stderr.write(
         `emit-session: WARN token rollup failed (${err?.message ?? err}); omitting token fields\n`

package/scripts/eval-session.mjs

@@ -74,6 +74,7 @@ import { appendEvalRecord, readEvalRecords } from './lib/eval/sink.mjs';
 import { writeStdoutLineSync } from './lib/io.mjs';
 import { VALID_MODEL_SOURCES } from './lib/eval/schema.mjs';
 import { SessionResolutionError } from './lib/eval/session-resolve.mjs';
+import { resolveLedgerPath } from './lib/ledger-path.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -103,7 +104,8 @@ OPTIONS
   --session <id>          session_id to evaluate (default: last completed session)
   --json                  emit the record (or verify result) as JSON on stdout
   --no-write              evaluate without appending to the eval journal
-  --metrics-dir <path>    metrics directory (default: .orchestrator/metrics)
+  --metrics-dir <path>    metrics directory (default: .orchestrator/metrics of this repo;
+                          in a linked worktree the main checkout's when it is gitignored)
   --rubric <path>         rubric file to hash for provenance (default: ${DEFAULT_RUBRIC_PATH})
   --model-id <id>         evaluated model id (default: $ANTHROPIC_MODEL or "unknown")
   --model-source <src>    ${VALID_MODEL_SOURCES.join(' | ')} (default: self-report)
@@ -159,8 +161,20 @@ function renderHuman(record, summary, writeResult) {
   return lines.join('\n');
 }
 
+/**
+ * The metrics directory: `--metrics-dir` as given, else this repo's
+ * `.orchestrator/metrics` — from a linked worktree the main checkout's when
+ * `eval.jsonl` is gitignored there, so the record survives the worktree (#1722).
+ * The engine reads `sessions.jsonl` beside it through the same main-checkout
+ * mapping (engine.mjs, #1592).
+ */
+function resolveMetricsDir(flag) {
+  if (flag) return path.resolve(flag);
+  return path.dirname(resolveLedgerPath('.orchestrator/metrics/eval.jsonl', process.cwd()));
+}
+
 function runEvaluate(values) {
-  const metricsDir = values['metrics-dir'] || '.orchestrator/metrics';
+  const metricsDir = resolveMetricsDir(values['metrics-dir']);
   const rubricPath = values.rubric || DEFAULT_RUBRIC_PATH;
   const modelSource = values['model-source'] || 'self-report';
   if (!VALID_MODEL_SOURCES.includes(modelSource)) {
@@ -219,7 +233,7 @@ function runEvaluate(values) {
 }
 
 function runVerify(runId, values) {
-  const metricsDir = values['metrics-dir'] || '.orchestrator/metrics';
+  const metricsDir = resolveMetricsDir(values['metrics-dir']);
   const rubricPath = values.rubric || DEFAULT_RUBRIC_PATH;
 
   const records = readEvalRecords(path.join(metricsDir, 'eval.jsonl'));

package/scripts/export-hw-learnings.mjs

@@ -60,12 +60,14 @@ import {
   CURRENT_ANONYMIZATION_VERSION,
 } from './lib/learnings.mjs';
 import { withLearningsLock } from './lib/learnings/io.mjs';
+import { assertStoreRoleUsable, isCanonicalStore, resolveStoreRole } from './lib/learnings/store-role.mjs';
 import { findProjectRoot, resolveInstructionFile, expandTilde, redactHomeDir } from './lib/common.mjs';
 import { parseSessionConfig } from './lib/config.mjs';
 import { createSecretValueMasker } from './lib/secret-masker.mjs';
 import { stableHostname, readHostAliases } from './lib/host-identity.mjs';
 import { emitEvent, sessionAttribution } from './lib/events.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { resolveLedgerPath } from './lib/ledger-path.mjs';
 
 // Vault-relative default write target (Epic #774 — docs Public-Split removed
 // the prior in-repo generated telemetry doc in favor of the private Meta-Vault).
@@ -572,6 +574,7 @@ function parseArgs(argv) {
   const out = {
     dryRun: false,
     promote: false,
+    // ledger-root: parse default, routed after parsing unless --input is explicit
     input: '.orchestrator/metrics/learnings.jsonl',
     output: undefined, // resolved lazily below (default = vault-dir target)
     generatedAt: new Date().toISOString(),
@@ -581,11 +584,12 @@ function parseArgs(argv) {
     // themselves (see their opts.repoRoot doc for why).
     repoRoot: findProjectRoot(),
   };
+  let inputExplicit = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--dry-run') out.dryRun = true;
     else if (a === '--promote') out.promote = true;
-    else if (a === '--input') out.input = argv[++i];
+    else if (a === '--input') { out.input = argv[++i]; inputExplicit = true; }
     else if (a === '--output') out.output = argv[++i];
     else if (a === '--generated-at') out.generatedAt = argv[++i];
     else if (a === '--help' || a === '-h') {
@@ -598,7 +602,12 @@ function parseArgs(argv) {
         '                   (backup created first). Use with --dry-run to preview.\n' +
         '  --dry-run        Print markdown to stdout; do not write any files.\n' +
         '  --output FILE    Override the default write target. Default: resolved from\n' +
-        '                   vault-integration.vault-dir (see script header doc).\n'
+        '                   vault-integration.vault-dir (see script header doc).\n' +
+        '\n' +
+        'Exit codes: 0 success, 1 export failed (incl. --promote without --dry-run on a\n' +
+        '            host whose learnings-store role is inbox or invalid, #1516:\n' +
+        '            nothing written),\n' +
+        '            2 unknown argument.\n'
       );
       process.exit(0);
     } else {
@@ -619,6 +628,13 @@ function parseArgs(argv) {
     }
     out.output = resolved;
   }
+  // #1722: the DEFAULT input routes through the ledger resolver (main checkout
+  // when cwd is a linked worktree that gitignores it); outside one the relative
+  // default is kept verbatim. An explicit --input stays as given.
+  if (!inputExplicit) {
+    const routed = resolveLedgerPath(out.input, process.cwd());
+    if (routed !== path.resolve(out.input)) out.input = routed;
+  }
   return out;
 }
 
@@ -650,6 +666,17 @@ export async function promoteHwLearnings(opts) {
   // nothing and takes no lock. A lock not acquired throws LearningsLockError
   // (nothing written), which the CLI reports as `export failed: …`, exit 1.
   if (opts.dryRun) return promoteHwLearningsUnlocked(opts);
+  // #1516 fail-closed: an invalid store role throws LearningsStoreRoleError
+  // (CLI: `export failed: …`, exit 1) before anything is read, locked or emitted.
+  assertStoreRoleUsable(opts.input);
+  // #1516: on an inbox-role host the live store is never rewritten, and a
+  // promoted twin keeps its private original's id, so the inbox rewrite would
+  // drop it silently. Refuse before anything is read, locked or emitted.
+  if (isCanonicalStore(opts.input) && resolveStoreRole().role === 'inbox') {
+    throw new Error(
+      'store-role inbox: --promote rewrites learnings.jsonl, which this host never does — run it on the writer host'
+    );
+  }
   return withLearningsLock(opts.input, () => promoteHwLearningsUnlocked(opts));
 }
 

package/scripts/fleet-checkin-audit.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 /** Read-only CLI for explicitly supplied, stable snapshot copies (#1462). */
-import { constants, promises as fs } from 'node:fs';
+import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { TextDecoder } from 'node:util';
 import { auditCheckins } from './lib/fleet-checkin-audit.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { openNoFollow } from './lib/no-follow-open.mjs';
 
 const HELP = `Usage: fleet-checkin-audit --input-root DIR --registry FILE --checkins FILE --repo KEY [--repo KEY] --at UTC [--json]
 All five input flags are required. --repo may repeat with distinct explicit keys.
@@ -80,10 +81,13 @@ async function readSnapshot({ target, stat }) {
   // The parent check above and this open are not atomic: a same-user process can swap a parent
   // directory in between. Fine while the operator names the snapshot files and the result grants
   // nothing; revisit (#1549) once paths come from a foreign owner or the result gates a decision.
-  if (typeof constants.O_NOFOLLOW !== 'number' || typeof constants.O_NONBLOCK !== 'number') {
-    throw failure('unsupported-safe-open', 2);
+  let handle;
+  try { handle = await openNoFollow(target); }
+  catch (error) {
+    // inspect() already proved a regular non-symlink file: any of these means it changed since.
+    if (['ERR_FILE_CHANGED', 'ELOOP', 'ERR_NOT_REGULAR_FILE'].includes(error?.code)) throw failure('changed-input-file', 1);
+    throw error;
   }
-  const handle = await fs.open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
   let bytes;
   try {
     const actual = await handle.stat();