session-orchestrator 5.11.0 → 5.13.0

package/scripts/lib/common.mjs

@@ -141,11 +141,12 @@ export async function writeJson(filePath, obj) {
  * PIPE_BUF (4 KiB).
  * @param {string} filePath
  * @param {unknown} obj
+ * @param {{ mode?: number }} [opts] — file mode on creation (e.g. 0o600 for host-private logs, #1632)
  * @returns {Promise<void>}
  */
-export async function appendJsonl(filePath, obj) {
+export async function appendJsonl(filePath, obj, { mode } = {}) {
   await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.appendFile(filePath, JSON.stringify(obj) + '\n', 'utf8');
+  await fs.appendFile(filePath, JSON.stringify(obj) + '\n', mode === undefined ? 'utf8' : { encoding: 'utf8', mode });
 }
 
 // ---------------------------------------------------------------------------

package/scripts/lib/config/cross-repo.mjs

@@ -16,21 +16,88 @@
 // here). We deliberately do NOT import `parseSessionConfig` — calling it from
 // `getCrossRepoProjects` would re-run `_parseCrossRepo` (double-parse). By calling
 // `_parseCrossRepo` directly on the raw content we parse exactly once. (issue #664)
+import { statSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
+import { expandTilde } from '../common.mjs';
 import { readConfigFile } from './io.mjs';
+import { loadHostPaths, resolveHostPath } from './host-paths.mjs';
 import { matchBlockHeader } from './block-header.mjs';
 import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
- * Resolve the cross-repo confinement root. Defaults to ~/Projects.
- * Override via CROSS_REPO_CONFINEMENT_ROOT env (test-only — never set in production).
+ * Expand a leading `~` / `~/` to the home directory and accept the result only
+ * when it is absolute. A relative value would otherwise resolve against the
+ * process cwd — a different root per caller — so it is rejected instead.
+ * An existing non-directory (a file) is rejected too (#1567): every sweep under
+ * it would find nothing. A path that does not exist yet is accepted, like the
+ * ~/Projects default — callers guard with existsSync, and falling back from an
+ * unmounted volume to ~/Projects would widen the confinement root.
  *
- * @returns {string} absolute path
+ * @param {string} raw — non-blank value from one precedence tier
+ * @param {string} source — tier name for the WARN (`env SO_PROJECTS_ROOT` / `owner.yaml paths.projects-root`)
+ * @returns {string|null} absolute path, or null when rejected
  */
-export function getConfinementRoot() {
-  const v = process.env.CROSS_REPO_CONFINEMENT_ROOT;
-  return (v && v.trim()) ? v : join(homedir(), 'Projects');
+function expandProjectsRoot(raw, source) {
+  const expanded = expandTilde(raw.trim());
+  if (!isAbsolute(expanded)) {
+    process.stderr.write(
+      `cross-repo: ignoring ${source}=${JSON.stringify(raw)} — not an absolute path after ~ expansion; falling back\n`,
+    );
+    return null;
+  }
+  let stat;
+  try {
+    stat = statSync(expanded, { throwIfNoEntry: false });
+  } catch {
+    stat = undefined; // unreadable (EACCES/ENOTDIR): treated like a missing path — never throw here
+  }
+  if (stat && !stat.isDirectory()) {
+    process.stderr.write(
+      `cross-repo: ignoring ${source}=${JSON.stringify(raw)} — exists but is not a directory; falling back\n`,
+    );
+    return null;
+  }
+  return expanded;
+}
+
+/**
+ * Resolve the cross-repo confinement root — the directory host-wide sweeps scan
+ * and outside which `cross-repo.projects` entries are dropped (#1562).
+ *
+ * Precedence (highest first):
+ *   1. env CROSS_REPO_CONFINEMENT_ROOT — test-only, never set in production;
+ *      returned verbatim when non-blank (no ~ expansion, no absolute check).
+ *   2. env SO_PROJECTS_ROOT            — host-local, via resolveHostPath.
+ *   3. owner.yaml paths.projects-root  — host-local, via resolveHostPath.
+ *   4. ~/Projects                      — default.
+ * Tiers 2 and 3 expand a leading `~`; a value that is still not absolute is
+ * ignored with one stderr WARN and the next tier is tried. owner.yaml is read
+ * only when tiers 1 and 2 yield nothing usable.
+ *
+ * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object }} [ctx]
+ *   injection seam for tests, mirroring resolveHostPath; `ownerConfig` omitted →
+ *   owner.yaml is loaded from disk via loadHostPaths()
+ * @returns {string} confinement root
+ */
+export function getConfinementRoot({ env = process.env, ownerConfig } = {}) {
+  const v = env.CROSS_REPO_CONFINEMENT_ROOT;
+  if (v && v.trim()) return v;
+
+  const fromEnv = resolveHostPath('projects-root', undefined, { env, ownerConfig: undefined });
+  if (typeof fromEnv === 'string') {
+    const root = expandProjectsRoot(fromEnv, 'env SO_PROJECTS_ROOT');
+    if (root) return root;
+  }
+
+  const owner = ownerConfig ?? loadHostPaths({ env }).ownerConfig;
+  const fromOwner = resolveHostPath('projects-root', undefined, { env: {}, ownerConfig: owner });
+  if (typeof fromOwner === 'string') {
+    const root = expandProjectsRoot(fromOwner, 'owner.yaml paths.projects-root');
+    if (root) return root;
+  }
+
+  return join(homedir(), 'Projects');
 }
 
 // Allowlist: only characters that are safe in shell contexts and file paths.

package/scripts/lib/config/host-paths.mjs

@@ -8,7 +8,8 @@
  * committed default act as a fallback for unconfigured hosts.
  *
  * Precedence (highest first):
- *   1. env-var               (SO_VAULT_DIR / SO_BASELINE_PATH)
+ *   1. env-var               (SO_VAULT_DIR / SO_BASELINE_PATH / SO_NAMESPACE_MAP /
+ *                             SO_CONFIDENTIAL_NAMES_FILE / SO_PROJECTS_ROOT — see ENV_KEYS)
  *   2. owner.yaml paths[key]  (host-local, never committed — ~/.config/session-orchestrator/owner.yaml)
  *   3. committed Session Config default (the value the committed CLAUDE.md —
  *      AGENTS.md on Codex CLI — produced)
@@ -40,6 +41,9 @@ const ENV_KEYS = /** @type {const} */ ({
   'namespace-map-path': 'SO_NAMESPACE_MAP',
   // #728a — host-local confidential customer/repo name list for CP11 leak scanning.
   'confidential-names-file': 'SO_CONFIDENTIAL_NAMES_FILE',
+  // #1562 — host-local cross-repo confinement / scan root (default ~/Projects);
+  // consumed by getConfinementRoot() in config/cross-repo.mjs.
+  'projects-root': 'SO_PROJECTS_ROOT',
 });
 
 /**
@@ -86,7 +90,7 @@ export function loadHostPaths({ env = process.env, ownerLoader = loadOwnerConfig
  * (fall through to the next tier). When no override is set, `committedDefault`
  * passes through unchanged — including `null`/`undefined`, preserving back-compat.
  *
- * @param {'vault-dir'|'baseline-path'|'namespace-map-path'|'confidential-names-file'} key — logical path key
+ * @param {'vault-dir'|'baseline-path'|'namespace-map-path'|'confidential-names-file'|'projects-root'} key — logical path key
  * @param {string|null|undefined} committedDefault — value the committed Session Config produced
  * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object }} [ctx] — from loadHostPaths()
  * @returns {string|null|undefined} resolved value

package/scripts/lib/config/remote-hosts.mjs

@@ -18,7 +18,7 @@ import { preprocessBlockLinesNoDash } from './block-preprocess.mjs';
  *
  * Block shape:
  *   remote-hosts:
- *     - alias: m5                        # required; becomes `-H <alias>` argv
+ *     - alias: build-host                # required; becomes `-H <alias>` argv
  *       roles-allowed: [test, ui, perf]  # subset of ALLOWED_REMOTE_ROLES
  *       repo-path: ~/Projects/Alice   # optional
  *       claude-path: ~/.local/bin/claude # optional
@@ -54,7 +54,7 @@ export const ALLOWED_REMOTE_ROLES = Object.freeze(['test', 'ui', 'perf']);
 // The first character is anchored separately from the rest because a charset
 // cannot express a POSITION: an alias of `-H` passes any hyphen-inclusive
 // allowlist and then reaches argv as an OPTION token, where the CLI swallows the
-// operand behind it. Interior hyphens (`m5-box`) stay legal.
+// operand behind it. Interior hyphens (`build-host`) stay legal.
 const SAFE_NAME_RE = /^[A-Za-z0-9._][A-Za-z0-9._-]*$/;
 
 // `repo-path` / `claude-path` are filesystem paths handed to a remote shell —

package/scripts/lib/config/section-extractor.mjs

@@ -345,8 +345,11 @@ export function _parseKV(lines) {
  * and at any indent. Deliberately NOT imported from block-header.mjs: that
  * matcher answers "does this line open the block for THIS key" for a known key,
  * while here the key is unknown by construction.
+ *
+ * Group 1 captures the key, for `collectTopLevelKeyLines` below; `.test()`
+ * callers are unaffected by the group.
  */
-const NESTED_BLOCK_HEADER_RE = /^\s*(?:-\s+)?(?:\*\*)?[a-zA-Z][a-zA-Z0-9_.-]*:(?:\*\*)?\s*$/;
+const NESTED_BLOCK_HEADER_RE = /^\s*(?:-\s+)?(?:\*\*)?([a-zA-Z][a-zA-Z0-9_.-]*):(?:\*\*)?\s*$/;
 
 /** A YAML sequence element that is not a `key: value` pair (`  - some-value`). */
 const LIST_ITEM_RE = /^\s*-\s+\S/;
@@ -391,8 +394,67 @@ const COMMENT_RE = /^\s*(?:#|<!--|>)/;
 export function collectUnparsableLines(content) {
   if (typeof content !== 'string' || content === '') return [];
 
-  const lines = content.split(/\r?\n/);
   const unparsable = [];
+  for (const { lineNo, line } of liveBlockLines(content)) {
+    if (_matchKVLine(line)) continue;
+    if (NESTED_BLOCK_HEADER_RE.test(line)) continue;
+    if (LIST_ITEM_RE.test(line)) continue;
+
+    unparsable.push({ line: lineNo, text: sanitizeReportText(line.trim()) });
+  }
+
+  return unparsable;
+}
+
+/**
+ * Collect the TOP-LEVEL keys the runtime reads from `## Session Config` — the
+ * local half of the unknown-key report in `scripts/parse-config.mjs` (#1562).
+ *
+ * Same block, same walk, same line acceptance as `collectUnparsableLines`
+ * (both iterate `liveBlockLines`), so a key inside a multi-line `<!-- -->`
+ * comment, a fence, or a `#` line is never collected. A line counts as a
+ * top-level key when it starts at column 0 and is either a key/value pair the
+ * reader accepts (`_matchKVLine`, both spellings) or a nested-block header
+ * (`vault-integration:`); indented lines are children of a nested block.
+ *
+ * Ceiling (deliberate): a compact YAML sequence written at column 0 under a
+ * nested header (`custom-phases:` then `- name: x` unindented) yields `name`
+ * here. `extractTopLevelKeys` in `template-keys.mjs` reads that line the
+ * same way, so drift-check Check 6 and this collector agree on it. Revisit if
+ * a fleet CLAUDE.md is ever measured writing that form.
+ *
+ * @param {string} content — full markdown document
+ * @returns {Array<{ line: number, key: string }>} 1-based document line numbers
+ *   in document order (a repeated key appears once per line); empty when the
+ *   block is absent or the content is not a string. Keys are passed through
+ *   `sanitizeReportText` because the bold spelling admits any character but
+ *   `*` and `:`, and the one consumer prints them on a terminal.
+ */
+export function collectTopLevelKeyLines(content) {
+  if (typeof content !== 'string' || content === '') return [];
+
+  const keys = [];
+  for (const { lineNo, line } of liveBlockLines(content)) {
+    if (/^\s/.test(line)) continue;
+    const kv = _matchKVLine(line);
+    const key = kv ? kv.key : NESTED_BLOCK_HEADER_RE.exec(line)?.[1];
+    if (key) keys.push({ line: lineNo, key: sanitizeReportText(key) });
+  }
+  return keys;
+}
+
+/**
+ * The lines of the FIRST `## Session Config` block that can carry meaning:
+ * everything except blank lines, fences, `#`/`<!--`/`>` documentation lines and
+ * the inside of a multi-line HTML comment. The one walk both classifiers share,
+ * in the order `_extractConfigSection` applies the same skips — the shared
+ * `htmlCommentSkipper` call is what keeps the accept-sets identical.
+ *
+ * @param {string} content
+ * @returns {Generator<{ lineNo: number, line: string }>} 1-based line numbers
+ */
+function* liveBlockLines(content) {
+  const lines = content.split(/\r?\n/);
   let inSection = false;
   const skipHtmlComment = htmlCommentSkipper();
 
@@ -406,20 +468,12 @@ export function collectUnparsableLines(content) {
     if (!inSection) continue;
     if (/^## /.test(line)) break;
 
-    // A multi-line HTML comment: everything up to `-->` is documentation.
-    // Same call, same order, as `_extractConfigSection` — that shared call is
-    // what makes the two accept-sets identical rather than merely similar.
     if (skipHtmlComment(line)) continue;
 
     if (!line.trim()) continue;
     if (isCodeFence(line)) continue;
     if (COMMENT_RE.test(line)) continue;
-    if (_matchKVLine(line)) continue;
-    if (NESTED_BLOCK_HEADER_RE.test(line)) continue;
-    if (LIST_ITEM_RE.test(line)) continue;
 
-    unparsable.push({ line: i + 1, text: sanitizeReportText(line.trim()) });
+    yield { lineNo: i + 1, line };
   }
-
-  return unparsable;
 }

package/scripts/lib/config/template-keys.mjs

@@ -0,0 +1,153 @@
+/**
+ * template-keys.mjs — the KNOWN top-level Session Config keys, read from
+ * `docs/session-config-template.md`.
+ *
+ * Two consumers read the same population and must not drift apart:
+ *   - `skills/claude-md-drift-check/checker.mjs` Check 6 (session-config-parity)
+ *     diffs a repo's local block against the template's blocks;
+ *   - `scripts/parse-config.mjs` reports a local top-level key the template
+ *     never documents — a typo'd key is otherwise absent from the KV map and
+ *     every consumer silently applies its default (#1562).
+ *
+ * The template carries TWO literal `## Session Config` lines, both inside fenced
+ * ```yaml examples: the FIRST is the starter / minimal baseline (the mandatory
+ * keys), the LAST is the opt-in baseline (the full key catalog). Check 6
+ * classifies mandatory vs opt-in by exactly that order.
+ */
+
+import { isSessionConfigHeading, collectTopLevelKeyLines } from './section-extractor.mjs';
+
+/**
+ * Extract the YAML block under a `## Session Config` heading from a Markdown
+ * document. Tries fenced YAML first (```yaml ... ```) *within the matched
+ * heading's own body slice*, then falls back to the raw body up to the next
+ * `^## ` heading or EOF.
+ *
+ * `docs/session-config-template.md` carries TWO literal `## Session Config`
+ * lines — both live INSIDE fenced ```yaml example blocks: the starter / "Full
+ * minimal baseline" (7 mandatory keys) and the "Full opt-in baseline" (the
+ * complete key catalog, a strict superset of the minimal block). By default
+ * this function matches the FIRST occurrence (correct for a local CLAUDE.md /
+ * AGENTS.md instruction file, which has exactly one real heading). Pass
+ * `{ occurrence: 'last' }` to match the LAST occurrence instead — the template
+ * call site uses this to reach the opt-in baseline's full key set rather than
+ * silently stopping at the 7-key minimal block (issue #785).
+ *
+ * Returns { body: string, headingLine: number } or null when no heading found.
+ *
+ * @param {string} content
+ * @param {{ occurrence?: 'first'|'last' }} [options]
+ * @returns {{ body: string, headingLine: number } | null}
+ */
+export function extractSessionConfigBlock(content, { occurrence = 'first' } = {}) {
+  const lines = content.split('\n');
+  const headingIdxs = [];
+  for (let i = 0; i < lines.length; i++) {
+    // SSOT predicate (#968). The previous local `/^##\s+Session Config\b/`
+    // was the loosest JS comparator in the repo: no end anchor and `\s+`
+    // instead of a single space, so it accepted `##  Session Config` (two
+    // spaces) and `## Session Config Convention` — both of which the runtime
+    // parser rejects. The drift-check's whole job is to report on the block
+    // the runtime reads, so matching a heading the runtime cannot see made it
+    // audit a section that does not exist.
+    if (isSessionConfigHeading(lines[i])) headingIdxs.push(i);
+  }
+  if (headingIdxs.length === 0) return null;
+
+  const targetIdx = occurrence === 'last' ? headingIdxs[headingIdxs.length - 1] : headingIdxs[0];
+  const headingLine = targetIdx + 1; // 1-based line number for error reporting
+
+  // Raw body: from the line after the heading up to the next `## ` heading or EOF.
+  let endIdx = lines.length;
+  for (let i = targetIdx + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) { endIdx = i; break; }
+  }
+  const rawBody = lines.slice(targetIdx + 1, endIdx).join('\n');
+
+  // Prefer a fenced YAML block found anywhere within the raw body slice
+  // (tolerates a blank line between the heading and the fence); fall back to
+  // the raw body itself when no fence is present.
+  const fenced = rawBody.match(/```ya?ml\r?\n([\s\S]*?)\r?\n```/);
+  const body = fenced ? fenced[1] : rawBody;
+
+  return { body, headingLine };
+}
+
+/**
+ * Extract top-level YAML keys from a YAML body. Only column-0 keys are
+ * collected (indented keys are children and ignored).
+ *
+ * Accepts four equivalent forms consumer CLAUDE.md files write a Session
+ * Config key in: bare `key:`, Markdown bullet `- key:`, bold `**key:**`
+ * (closing bold before the colon), and the bold-bullet consumer shape
+ * `- **key:** value` (bold wraps the key AND colon together, closing bold
+ * AFTER the colon). Baseline issue #60: the original bare-only regex
+ * extracted zero keys from bullet-form local files, so session-config-parity
+ * (drift-check Check 6) either false-positived on every mandatory key (local
+ * side reads as empty) or, when the TEMPLATE side also used bullet form,
+ * passed vacuously (both sides empty, so the diff was always empty). Sibling
+ * precedent: `scripts/lib/config/block-header.mjs` recognizes only header
+ * lines, not individual key-value pairs — this function is the per-key
+ * counterpart.
+ *
+ * @param {string} body
+ * @returns {string[]} keys in document order (duplicates kept)
+ */
+export function extractTopLevelKeys(body) {
+  const keys = [];
+  const re = /^(?:-\s+)?(?:\*\*)?([A-Za-z][\w-]*)(?:\*\*)?:/gm;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    keys.push(m[1]);
+  }
+  return keys;
+}
+
+/**
+ * The known-key union of a Session Config template: every top-level key of its
+ * FIRST `## Session Config` block (starter / mandatory) and its LAST one
+ * (opt-in catalog).
+ *
+ * Returns null — "not measurable", never "no keys" — when the template does not
+ * carry two DISTINCT blocks. A single block is not a key catalog (the same
+ * guard drift-check Check 6 applies before it warns on local keys): diffing a
+ * repo against the seven starter keys alone would report every legitimately
+ * adopted opt-in key as unknown.
+ *
+ * @param {string} content - full template document
+ * @returns {Set<string> | null}
+ */
+export function knownTemplateKeys(content) {
+  if (typeof content !== 'string') return null;
+  const first = extractSessionConfigBlock(content, { occurrence: 'first' });
+  const last = extractSessionConfigBlock(content, { occurrence: 'last' });
+  if (!first || !last || first.headingLine === last.headingLine) return null;
+  return new Set([...extractTopLevelKeys(first.body), ...extractTopLevelKeys(last.body)]);
+}
+
+/**
+ * The template's starter (mandatory) keys a local instruction file does NOT
+ * carry in its `## Session Config` block — the input of `/bootstrap
+ * --retroactive` step 6 (#1567).
+ *
+ * Why not the validator: `parseSessionConfig()` fills every mandatory field
+ * with its default, so `validate-config` never sees an ABSENT key; in a pnpm
+ * repo without `test-command` the run silently uses `npm test`. Presence is a
+ * property of the FILE, so it is read from the file: local keys come from
+ * `collectTopLevelKeyLines()` (the lines the runtime reads, all spellings),
+ * the mandatory population from the template's FIRST block — the same
+ * population drift-check Check 6 calls mandatory.
+ *
+ * @param {string} localContent - the repo's CLAUDE.md / AGENTS.md
+ * @param {string} templateContent - `docs/session-config-template.md`
+ * @returns {string[] | null} missing keys in template order; null when the
+ *   template has no `## Session Config` block ("not measurable", never "none
+ *   missing")
+ */
+export function missingStarterKeys(localContent, templateContent) {
+  if (typeof templateContent !== 'string') return null;
+  const starter = extractSessionConfigBlock(templateContent, { occurrence: 'first' });
+  if (!starter) return null;
+  const present = new Set(collectTopLevelKeyLines(localContent).map(({ key }) => key));
+  return [...new Set(extractTopLevelKeys(starter.body))].filter((key) => !present.has(key));
+}

package/scripts/lib/config/vault-integration.mjs

@@ -347,6 +347,7 @@ export function _parseResourceThresholds(kv) {
     // Unchanged at 5 — but now compared against LIVE PEER SESSIONS rather than
     // the Claude process count. Same number, different denominator: measured
     // firing rate drops from 93.6% to 4.2% (median processes:sessions = 6.0).
+    // That 4.2% did not hold: 67.4% M4 / 25.7% M5 re-measured 2026-10-17 (#1650).
     'concurrent-sessions-warn': _coerceInteger(kv, 'concurrent-sessions-warn', 5),
     'ssh-no-docker': _coerceBoolean(kv, 'ssh-no-docker', true),
   };

package/scripts/lib/config.mjs

@@ -327,7 +327,7 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     // dispatched natively, exactly as before.
     //   impl: code-implementer      → native Agent dispatch (unchanged)
     //   impl: cursor:composer-2.5   → foreign model over the Cursor channel
-    //   test: ssh:m5                → same Claude, another host (#1160)
+    //   test: ssh:build-host        → same Claude, another host (#1160)
     // An unknown prefix is a typo or a channel this build cannot route, and
     // must fail loudly: silently accepting it would dispatch to an agent that
     // does not exist, which surfaces only as an empty wave much later.
@@ -433,8 +433,8 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   const eventsRotation = _parseEventsRotation(mdContent);
 
   // express-path: parsed from full content (standalone top-level block, #214/#1119).
-  // Documented in docs/session-config-template.md:585 and
-  // docs/session-config-reference.md:1519 since #214, but never in the key schema —
+  // Documented in docs/session-config-template.md § Express Path and
+  // docs/session-config-reference.md § Express Path (#214) since #214, but never in the key schema —
   // measured 2026-08-23, a probe carrying `express-path:\n  enabled: false` produced
   // 88 keys and none of them was `express-path`. The key was dropped even when it
   // stood in the file, so the documented default was prose rather than a value.

package/scripts/lib/coordinator-snapshot.mjs

@@ -20,7 +20,7 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 
-import { $, nothrow } from 'zx';
+import { $, nothrow } from './zx.mjs';
 
 // Do not spam stdout/stderr with git command echoes.
 $.verbose = false;

package/scripts/lib/discovery/triage-state.mjs

@@ -19,6 +19,7 @@ import { appendFile, readFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { findProjectRoot } from '../common.mjs';
+import { resolveLedgerPath } from '../ledger-path.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -56,7 +57,7 @@ export const DEFAULT_STATE_FILE = '.orchestrator/metrics/discovery-triage.jsonl'
 function resolveStatePath(stateFilePath) {
   const p = stateFilePath ?? DEFAULT_STATE_FILE;
   if (path.isAbsolute(p)) return p;
-  return path.join(findProjectRoot(), p);
+  return resolveLedgerPath(p, findProjectRoot());
 }
 
 /**

package/scripts/lib/dispatcher/rank.mjs

@@ -29,13 +29,10 @@
  * @typedef {{ repoRoot: string, repoName: string, free: boolean, status: 'frei'|'in-progress'|'force-closed', heartbeat: string|null, sessionId: string|null }} Candidate
  */
 
-import path from 'node:path';
-
 import { scanBacklog } from '../backlog-scan.mjs';
 import { checkCiStatus as realCheckCiStatus } from '../ci-status-banner.mjs';
 import { probe as realProbe, evaluate as realEvaluate, DEFAULT_RESOURCE_THRESHOLDS as CANONICAL_RESOURCE_THRESHOLDS } from '../resource-probe.mjs';
-import { readCanonicalSessions } from '../sessions-canonical.mjs';
-import { isRealSession } from '../session-schema/filters.mjs';
+import { isMeasuredSession, readCanonicalSessions } from '../sessions-canonical.mjs';
 
 /** Staleness cap (days). Beyond this, additional age does not raise the score. */
 export const STALENESS_CAP_DAYS = 90;
@@ -184,13 +181,14 @@ async function defaultFetchPriority(repoRoot, nowMs) {
  */
 async function defaultStaleDaysFor(repoRoot, nowMs) {
   try {
-    const file = path.join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl');
-    const records = readCanonicalSessions({ filePath: file });
+    const records = readCanonicalSessions({ repoRoot });
     if (records.length === 0) return STALENESS_CAP_DAYS;
 
     let latestMs = null;
     for (const rec of records) {
-      if (!isRealSession(rec)) continue;
+      // Audit E1: a synthetic backfill stub (even a `status: 'completed'` one)
+      // must not make a neglected repo look freshly touched.
+      if (!isMeasuredSession(rec)) continue;
       const iso = rec.completed_at || rec.started_at || null;
       if (!iso || typeof iso !== 'string') continue;
       const t = Date.parse(iso);

package/scripts/lib/ecosystem-health.mjs

@@ -38,8 +38,8 @@
  */
 
 import { existsSync, statSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
 import { getProjectDir } from './platform.mjs';
+import { resolveLedgerPath } from './ledger-path.mjs';
 
 // Ceiling (BV-004): one process per session that invoked session-start
 // (monitors/monitors.json `when: on-skill-invoke:session-start`), alive until
@@ -132,7 +132,7 @@ function fingerprint(absPath) {
 async function watchLoop(intervalS) {
   // #1517: the PROJECT root, never CLAUDE_PLUGIN_ROOT (the installed plugin
   // directory, whose metrics are not this repo's).
-  const absPath = join(getProjectDir(), STATE_FILE_REL);
+  const absPath = resolveLedgerPath(STATE_FILE_REL, getProjectDir());
 
   // Startup event — confirms the watcher is alive even when nothing has
   // happened yet. Without this, a "no events" stream is indistinguishable

package/scripts/lib/eval/engine.mjs

@@ -931,8 +931,9 @@ export function evaluateSession(opts = {}) {
     throw new Error('evaluateSession: model.id is required');
   }
 
-  const sessionsPath = path.join(metricsDir, 'sessions.jsonl');
-  // #1514 point 1 — the repo's ONE ledger (main checkout for a linked worktree).
+  // #1514 point 1 / #1592 — the repo's ONE ledger pair (main checkout for a
+  // linked worktree); resolving only events left the session unresolvable.
+  const sessionsPath = path.join(resolveEventsLedgerRoot(metricsDir), 'sessions.jsonl');
   const eventsPath = path.join(resolveEventsLedgerRoot(metricsDir), 'events.jsonl');
   // #1209: sessions.jsonl is APPEND-ONLY (the same physical session can carry
   // more than one line — crash-recovery re-appends, #1068 stub/supersede

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

@@ -8,7 +8,8 @@
  *   1. WHICH session? — resolveSession() implements the operator-approved
  *      cascade (Decision #2, revised #822): explicit id > newest record (source
  *      order) that is either status:'completed' or non-abandoned with completed
- *      work. Abandoned records are ALWAYS skipped.
+ *      work. The cascade uses only measured records and requires completion
+ *      evidence; abandoned records remain ineligible for a completed-session eval.
  *
  *   2. WHOSE events? — quality_gate events in events.jsonl do not RELIABLY
  *      carry a session_id (measured 2026-10-05, this repo's events.jsonl:
@@ -26,6 +27,8 @@
  * arrays. Determinism is load-bearing for the CLI `--verify` re-evaluation path.
  */
 
+import { isMeasuredSession } from '../sessions-canonical.mjs';
+
 /** Thrown by resolveSession when no eligible session can be selected. */
 export class SessionResolutionError extends Error {
   constructor(message) {
@@ -81,6 +84,7 @@ export function resolveSession(records, sessionId) {
   for (let i = records.length - 1; i >= 0; i--) {
     const r = records[i];
     if (!isPlainObject(r)) continue;
+    if (!isMeasuredSession(r)) continue;
     if (r.status === 'abandoned') continue;
     if (r.status === 'completed') {
       return { record: r, resolvedVia: 'cascade-completed' };
@@ -96,7 +100,7 @@ export function resolveSession(records, sessionId) {
   }
 
   throw new SessionResolutionError(
-    'no completed session found (all records abandoned or without evidence of completed work)',
+    'no completed session found (all records unmeasured or without evidence of completed work)',
   );
 }
 

package/scripts/lib/eval/sink.mjs

@@ -19,6 +19,7 @@ import { mkdirSync, appendFileSync } from 'node:fs';
 import path from 'node:path';
 import { validateEvalRecord, normalizeEvalRecord } from './schema.mjs';
 import { readJsonlFile } from '../io.mjs';
+import { resolveLedgerPath } from '../ledger-path.mjs';
 
 /** Default repo-relative path for the eval journal. */
 export const DEFAULT_EVAL_JSONL_PATH = '.orchestrator/metrics/eval.jsonl';
@@ -36,11 +37,11 @@ export const DEFAULT_EVAL_JSONL_PATH = '.orchestrator/metrics/eval.jsonl';
  *
  * @param {object} record — candidate session-eval record.
  * @param {{ path?: string }} [opts] — target path (absolute preferred); defaults
- *        to DEFAULT_EVAL_JSONL_PATH (repo-relative).
+ *        to `resolveLedgerPath(DEFAULT_EVAL_JSONL_PATH)` (#1722).
  * @returns {{ ok: true, record: object, path: string }
  *          | { ok: false, reason: 'validation'|'fs-error', error: string }}
  */
-export function appendEvalRecord(record, { path: filePath = DEFAULT_EVAL_JSONL_PATH } = {}) {
+export function appendEvalRecord(record, { path: filePath = resolveLedgerPath(DEFAULT_EVAL_JSONL_PATH) } = {}) {
   let validated;
   try {
     validated = validateEvalRecord(record);
@@ -71,7 +72,7 @@ export function appendEvalRecord(record, { path: filePath = DEFAULT_EVAL_JSONL_P
  * @param {string} [filePath] — absolute path to the eval journal.
  * @returns {object[]} normalized session-eval records, in source order.
  */
-export function readEvalRecords(filePath = DEFAULT_EVAL_JSONL_PATH) {
+export function readEvalRecords(filePath = resolveLedgerPath(DEFAULT_EVAL_JSONL_PATH)) {
   const rows = readJsonlFile(filePath, { skipInvalid: true });
   return rows.map((r) => normalizeEvalRecord(r));
 }

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

@@ -109,8 +109,8 @@ const HEAD_BYTES = 64 * 1024;
  * `rg -n "readEventsWithRotations\(|scanEventsBackwards\(|listEventSourcesNewestFirst\(" --glob '!tests/**' scripts hooks skills`
  * → 6 call sites beside the definitions in `events.mjs` (and its internal
  * `listEventSourcesNewestFirst` call); the seventh, `session-close-backfill`,
- * joined with #1498. A test re-runs that census, so an eighth reader cannot
- * join unlisted.
+ * joined with #1498, the eighth, `session-work-trees`, with #1659. A test
+ * re-runs that census, so a ninth reader cannot join unlisted.
  */
 export const EVENTS_WINDOW_READERS = Object.freeze([
   { label: 'eval/engine', spec: './eval/engine.mjs' },
@@ -120,6 +120,7 @@ export const EVENTS_WINDOW_READERS = Object.freeze([
   { label: 'instruction-budget-guard', spec: './instruction-budget-guard.mjs' },
   { label: 'backfill-abandoned-sessions', spec: '../backfill-abandoned-sessions.mjs' },
   { label: 'session-close-backfill', spec: './session-close-backfill.mjs' },
+  { label: 'session-work-trees', spec: './session-work-trees.mjs' },
 ]);
 
 /**

package/scripts/lib/events-schema.mjs

@@ -99,6 +99,16 @@ export const ARCHIVE_NAME_RE =
 /** Upper bound of the legacy `.1`..`.N` ring (`max-backups` is capped at 20). */
 export const LEGACY_RING_MAX = 20;
 
+/**
+ * Per-session work-tree record (#1659): written by hooks/pre-bash-staging-fence.mjs
+ * BEFORE a `git commit` runs, payload `{ session_id, tree, start_ref }` — the raw
+ * session id, the realpath of the committing tree's toplevel, and that tree's
+ * full `HEAD` sha before the commit. Read by scripts/lib/session-work-trees.mjs
+ * (first record per tree wins). Lives in this zero-import module so the hook
+ * and the reader share the name without either importing the other.
+ */
+export const SESSION_WORK_TREE_EVENT = 'orchestrator.session.work_tree';
+
 /** Prefix marking an orchestrator-owned event. */
 export const ORCHESTRATOR_PREFIX = 'orchestrator.';