session-orchestrator 5.11.0 → 5.13.0

package/scripts/lib/tmux-layout/layouts.mjs

@@ -25,6 +25,8 @@
 
 import path from 'node:path';
 import { resolveStateDir } from '../platform.mjs';
+import { resolveOwnLockRootFor } from '../own-lock-root.mjs';
+import { readProcessLocalSessionIds } from '../session-identity/own-session.mjs';
 import { shellQuote } from '../sh-quote.mjs';
 import { detectVcsCommand } from './vcs-detector.mjs';
 import { isSessionCollision } from './tmux-shell.mjs';
@@ -70,6 +72,11 @@ const STATUS_PANE_POLL_SECONDS = 2;
  *
  * Exported so a consumer test can run the render ONCE instead of the poll loop.
  *
+ * `repoRoot` (#1730): the agent-status writer (`hooks/subagent-telemetry.mjs`)
+ * writes beside the session's OWN lock, which is not always the checkout the
+ * second terminal sits in. A given root is written into the command as a
+ * literal; without one the pane reads its own `process.cwd()`, as before.
+ *
  * Shell-shape notes (both load-bearing):
  *   - the `-e` script is wrapped in SINGLE quotes, so the JS below uses only
  *     double-quoted strings: inside single quotes no `$`, backtick or interactive
@@ -77,15 +84,21 @@ const STATUS_PANE_POLL_SECONDS = 2;
  *   - the module path is resolved from THIS file's own URL (never a hardcoded home
  *     path), exactly as the sibling pane commands stay relative-to-cwd.
  *
+ * @param {{ repoRoot?: string|null }} [opts]
  * @returns {string} a single shell command; prints the pane body once and exits.
  */
-export function buildStatusPaneRenderCommand() {
+export function buildStatusPaneRenderCommand({ repoRoot = null } = {}) {
   // `%27` guard: a single quote in the repo path would otherwise end the shell
   // single-quoted `-e` argument.
   const moduleHref = new URL('../agent-status.mjs', import.meta.url).href.replace(/'/g, '%27');
+  // Same guard for the root literal: a quote in the path is written as its
+  // JSON unicode escape, which the double-quoted JS string reads as the quote.
+  const rootExpr = typeof repoRoot === 'string' && repoRoot !== ''
+    ? JSON.stringify(repoRoot).replace(/'/g, '\\u0027')
+    : 'process.cwd()';
   const js = [
     `import {readCurrentStatus} from ${JSON.stringify(moduleHref)};`,
-    'const v=readCurrentStatus({repoRoot:process.cwd()});',
+    `const v=readCurrentStatus({repoRoot:${rootExpr}});`,
     'const ids=Object.keys(v.entries).sort();',
     // An EMPTY channel (no ledger yet, no cache yet) is the normal fresh-repo
     // state, not a degradation — marking it would fire the warning on every
@@ -141,7 +154,11 @@ async function _renderDefaultLayoutInner({ sessionName, force, projectRoot, vcsC
   // file — so the pane can never present a stale `running` as live. The renderer
   // prints its own "no agent-status yet" line when the channel is empty, and is
   // exported (buildStatusPaneRenderCommand) so a test can run it once.
-  const pane5Cmd = `while true; do clear; ${buildStatusPaneRenderCommand()}; sleep ${STATUS_PANE_POLL_SECONDS}; done`;
+  // #1730: the root is the one holding this session's own lock, resolved once here; none found → the pane's cwd.
+  const own = withStatusPane
+    ? resolveOwnLockRootFor({ sessionId: readProcessLocalSessionIds()[0] ?? null, cwd: projectRoot })
+    : null;
+  const pane5Cmd = `while true; do clear; ${buildStatusPaneRenderCommand({ repoRoot: own && own.source !== 'none' ? own.root : null })}; sleep ${STATUS_PANE_POLL_SECONDS}; done`;
 
   // 4. Session-collision check
   const collision = isSessionCollision(sessionName);

package/scripts/lib/ux-grill/paths.mjs

@@ -26,6 +26,7 @@ import path from 'node:path';
 import { randomBytes } from 'node:crypto';
 
 import { digestSha256Short } from '../crypto-digest-utils.mjs';
+import { resolveLedgerPath } from '../ledger-path.mjs';
 import { RUN_ID_PATTERN, assertRunId } from '../test-runner/artifact-paths.mjs';
 
 // Re-exported so existing `ux-grill/paths.mjs` importers keep working; the
@@ -106,6 +107,7 @@ function assertRepoRoot(repoRoot) {
  * @throws {TypeError} on an invalid repoRoot or runId (path-traversal guard)
  */
 export function runDirPath(repoRoot, runId) {
+  // ledger-root: per-run artifact dir of this working tree, kept local
   return path.resolve(assertRepoRoot(repoRoot), UX_GRILL_METRICS_DIR, assertRunId(runId));
 }
 
@@ -156,7 +158,9 @@ export function findingsPath(repoRoot, runId) {
  * @returns {string}
  */
 export function runRecordPath(repoRoot) {
-  return path.resolve(assertRepoRoot(repoRoot), UX_GRILL_LEDGER);
+  // #1722: an ignored ledger in a linked worktree maps to the main checkout;
+  // a target repo that commits it keeps its own copy.
+  return resolveLedgerPath(UX_GRILL_LEDGER, path.resolve(assertRepoRoot(repoRoot)));
 }
 
 /**

package/scripts/lib/validate/check-agents.mjs

@@ -6,9 +6,9 @@
 
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import yaml from 'js-yaml';
-import { ALLOWED_MODEL_ALIASES, MODEL_ID_RE } from '../agent-frontmatter.mjs';
+import { ALLOWED_MODEL_ALIASES, MODEL_ID_RE, checkAgentEffort } from '../agent-frontmatter.mjs';
 import { extractInitialFrontmatter } from './frontmatter-block.mjs';
 import { parseFrontmatterDescription } from '../description-surface.mjs';
 
@@ -18,7 +18,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 let _tierModule = null;
 async function getTierModule() {
   if (!_tierModule) {
-    _tierModule = await import(join(__dirname, 'tier-inference.mjs'));
+    _tierModule = await import(pathToFileURL(join(__dirname, 'tier-inference.mjs')).href);
   }
   return _tierModule;
 }
@@ -103,13 +103,28 @@ function parseFrontmatterYaml(yamlText) {
 
 /**
  * Get a scalar field value from frontmatter text.
- * Returns null if field not present.
+ * Returns null if field not present or its value is empty. `[ \t]*` instead of
+ * `\s*`: an empty `key:` must not read the NEXT line as its value.
  */
 function getField(fm, name) {
-  const m = fm.match(new RegExp(`^${name}:\\s*(.+)$`, 'm'));
+  const m = fm.match(new RegExp(`^${name}:[ \t]*(.+)$`, 'm'));
   return m ? m[1].trim() : null;
 }
 
+/**
+ * Like getField, but for plain enum-like scalars (`model`, `effort`): strips one
+ * pair of surrounding quotes and a trailing YAML comment, so `effort: "medium"`
+ * and `effort: medium # reason` read as `medium`. Not for free text such as
+ * `description`, where ` #` may be content.
+ */
+function getScalarField(fm, name) {
+  const raw = getField(fm, name);
+  if (raw === null) return null;
+  const quoted = raw.match(/^(["'])(.*)\1(?:\s+#.*)?$/);
+  if (quoted) return quoted[2];
+  return raw.replace(/(^|\s+)#.*$/, '').trim();
+}
+
 /**
  * Check whether a field key is present in frontmatter (even with empty/block value).
  */
@@ -323,7 +338,7 @@ if (mdFiles.length === 0) {
     // do not re-declare the alias set or the model-ID regex here.
     // Per https://code.claude.com/docs/en/sub-agents — the canonical doc accepts both.
     if (hasField(frontmatter, 'model')) {
-      const modelVal = getField(frontmatter, 'model');
+      const modelVal = getScalarField(frontmatter, 'model');
       if (modelVal === null || (!ALLOWED_MODEL_ALIASES.has(modelVal) && !MODEL_ID_RE.test(modelVal))) {
         const got = modelVal ?? '';
         const aliasList = [...ALLOWED_MODEL_ALIASES].join('|');
@@ -331,6 +346,22 @@ if (mdFiles.length === 0) {
       }
     }
 
+    // effort: required when model ≠ inherit, enum low|medium|high|xhigh|max (#1614).
+    // Rule lives in agent-frontmatter.mjs (checkAgentEffort) — do not re-declare it here.
+    const effortError = checkAgentEffort(
+      hasField(frontmatter, 'model') ? (getScalarField(frontmatter, 'model') ?? '') : undefined,
+      hasField(frontmatter, 'effort') ? (getScalarField(frontmatter, 'effort') ?? '') : undefined,
+    );
+    if (effortError) fail(`${agentName}: ${effortError.message}`);
+
+    // omitClaudeMd: optional boolean (#1616) — a typo such as `yes` would be ignored silently.
+    if (hasField(frontmatter, 'omitClaudeMd')) {
+      const omitVal = getField(frontmatter, 'omitClaudeMd');
+      if (omitVal !== 'true' && omitVal !== 'false') {
+        fail(`${agentName}: omitClaudeMd must be true or false (got: '${omitVal ?? ''}')`);
+      }
+    }
+
     // color: canonical Anthropic palette (red|blue|green|yellow|purple|orange|pink|cyan) plus magenta from plugin-dev SKILL.md.
     // Source: https://code.claude.com/docs/en/sub-agents § Supported frontmatter fields.
     if (hasField(frontmatter, 'color')) {

package/scripts/lib/validate/check-component-paths.mjs

@@ -72,7 +72,22 @@ function stripLeadingDotSlash(p) {
  * @param {boolean} optional    - If true, missing conventional path is a PASS
  */
 function checkComponentPath(field, conventional, optional = false) {
-  const relPath = json[field] || '';
+  const value = json[field];
+  // hooks/mcpServers also accept inline config objects (plugins-reference §
+  // Component path forms). An inline object carries no path to resolve; arrays
+  // may mix paths and objects, so each string entry is checked as a path.
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      if (typeof entry === 'string') checkExplicitPath(field, entry);
+      else pass(`${field} inline config entry (no path to resolve)`);
+    }
+    return;
+  }
+  if (value && typeof value === 'object') {
+    pass(`${field} is an inline config object (no path to resolve)`);
+    return;
+  }
+  const relPath = value || '';
 
   if (!relPath) {
     // No explicit value — try conventional auto-discovery
@@ -87,6 +102,15 @@ function checkComponentPath(field, conventional, optional = false) {
     return;
   }
 
+  checkExplicitPath(field, relPath);
+}
+
+/**
+ * Check one explicit component path: must start with "./" and exist.
+ * @param {string} field
+ * @param {string} relPath
+ */
+function checkExplicitPath(field, relPath) {
   // Explicit value — must start with "./"
   if (!relPath.startsWith('./')) {
     fail(`${field} path does not start with ./: ${relPath}`);

package/scripts/lib/validate/check-guard-requires-parity.mjs

@@ -889,7 +889,7 @@ function loadModuleVersions(pluginRoot, modulePath, cache) {
 
   const workingSource = readFileSync(modulePath, 'utf8');
   const working = parseModule(workingSource, modulePath);
-  const gitPath = relative.split(path.sep).join('/');
+  const gitPath = relative.replace(/\\/g, '/');
   const env = {};
   for (const key of GIT_ENV_ALLOWLIST) {
     if (process.env[key] !== undefined) env[key] = process.env[key];
@@ -1027,8 +1027,8 @@ export function inspectGuardRequiresParity(pluginRoot) {
         result.summary.requires += requires.requires.length;
 
         const modulePath = path.resolve(pluginRoot, MODULE_RELATIVE_PREFIX, ...specifier.segments);
-        const moduleRelative = path.relative(pluginRoot, modulePath);
-        if (moduleRelative.startsWith('..') || path.isAbsolute(moduleRelative) || !moduleRelative.startsWith(`${MODULE_RELATIVE_PREFIX}${path.sep}`)) {
+        const moduleRelative = path.relative(pluginRoot, modulePath).replace(/\\/g, '/');
+        if (moduleRelative.startsWith('..') || path.isAbsolute(moduleRelative) || !moduleRelative.startsWith(`${MODULE_RELATIVE_PREFIX}/`)) {
           report('dynamic-contract', `${namespace}: specifier resolves outside ${MODULE_RELATIVE_PREFIX}`, specifierValue);
           continue;
         }

package/scripts/lib/validate/check-hooks-symmetry.mjs

@@ -10,7 +10,7 @@
 // Stdout: '  PASS: ...' / '  FAIL: ...' lines + 'Results: N passed, M failed'
 
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 
 // The pi and cursor projections are IMPORTED, not copied: the runtime bridges
 // rewrite `hook_event_name` for every native event, so they are the source of
@@ -83,16 +83,48 @@ const DOCUMENTED_ASYMMETRIES = {
       // shape ("PreToolUse hook returned permissionDecision:deny without a
       // non-empty permissionDecisionReason").
       //
-      // THE ACTUAL BLOCKER is the tool-name VOCABULARY, not the payload shape.
-      // Codex ships no `Bash`, `Edit`, `Write` or `MultiEdit` tool — it has
-      // `shell` / `exec_command` / `unified_exec` / `apply_patch`
-      // (`strings -a <codex> | grep -c '"Bash"'` -> 0). Every handler below
-      // opens with an equality gate on a Claude tool name and returns
-      // `emitAllow()` otherwise, so wiring one produces a hook that runs,
-      // matches nothing and allows everything: FALSE enforcement, which is
-      // strictly worse than the registered gap (#919-P2 class). The repair is
-      // a tool-name map (see CODEX_TOOL_NAMES in scripts/lib/codex/
-      // plugin-contract.mjs), not a manifest entry.
+      // 2026-09-06 (0.144.4) this block named the tool-name VOCABULARY as the
+      // blocker: Codex's model-facing tools are `shell` / `exec_command` /
+      // `unified_exec` / `apply_patch`, so a guard gating on
+      // `tool_name === 'Bash'` would run, match nothing and allow everything
+      // (#919-P2 class). For the SHELL tool that premise is refuted below; for
+      // the Edit/Write/MultiEdit gates (apply_patch) it is still unmeasured.
+      //
+      // REFUTED AGAIN for the shell tool (#1669), measured 2026-10-20 on
+      // codex-cli 0.160.1 with a logging PreToolUse hook under `codex exec`:
+      // a shell call arrives as `"tool_name":"Bash"` with
+      // `"tool_input":{"command":"<string>"}`, and `matcher: "Bash"` fires.
+      // The 2026-09-06 evidence (`strings -a <codex> | grep -c '"Bash"'` -> 0)
+      // counted a JSON-quoted literal Rust never stores.
+      //
+      // DENY IS HONOURED (#1691), measured 2026-10-20 on codex-cli 0.160.1:
+      // `codex exec` with pre-bash-destructive-guard as the only PreToolUse hook
+      // and the prompt `printf x > CLAUDE.md` logged `Command blocked by
+      // PreToolUse hook: Destructive command blocked: '> CLAUDE.md' (rule:
+      // redirect-truncate-protected)` and left the file unchanged (the rule
+      // protects CLAUDE.md and its Codex alias AGENTS.md alike); the control
+      // run with `hooks.PreToolUse=[]` executed it and the file became `x`.
+      // Measured payload: `session_id`, `turn_id`, `cwd` (= the session workdir,
+      // also the hook's process cwd), `hook_event_name`, `model`,
+      // `permission_mode`, `tool_name:"Bash"`, `tool_input.command`,
+      // `tool_use_id`, `transcript_path: null`; PostToolUse adds
+      // `tool_response: ""`. A real Codex session exports NO CLAUDE_* env.
+      //
+      // Every Bash hook was then fed that payload by hand under a clean env
+      // (PATH + HOME only, SO_PLATFORM=codex, mkdtemp git repo) and wired only
+      // where it enforces on it (2026-10-20): destructive-guard (deny on
+      // `> CLAUDE.md`), sessions-ledger-guard (deny on `>>
+      // .orchestrator/metrics/sessions.jsonl`), issue-budget (cap 1, second
+      // create denied and parked), enforce-commands (`.codex/wave-scope.json`
+      // `blockedCommands` → deny), memory-propose-audit (event appended,
+      // observe-only by design), post-bash-write-verify (warn on an out-of-scope
+      // write). They read `tool_input.command`, `cwd` and `session_id`; issue-budget also `tool_use_id`.
+      // Wiring contract: tests/hooks/codex-bash-guards-wiring.test.mjs.
+      //
+      // post-bash-issue-budget-refund is no gap on this list: it runs on
+      // PostToolUseFailure, an event hooks-codex.json does not carry, so a
+      // failed create on Codex keeps its slot (over-count, the fail-closed
+      // direction). Revisit when Codex gains a failure event.
       PreToolUse: [
         // pre-task-scope-disjoint (#1020): NOT ported by construction. The hook
         // matches the `Agent` dispatch tool, which this platform does not have —
@@ -118,27 +150,17 @@ const DOCUMENTED_ASYMMETRIES = {
         // `apply_patch`, a name this hook never matches. Wired, it would run and allow
         // everything: a silent no-op, not enforcement. Gap registered, not faked.
         'pre-edit-sessions-ledger-guard.mjs',
-        'pre-bash-destructive-guard.mjs',
-        'pre-bash-staging-fence.mjs',
-        'pre-bash-memory-propose-audit.mjs',
-        // pre-bash-sessions-ledger-guard (#958): same tool-name-vocabulary
-        // dependency as the guards above — it gates on tool_name === 'Bash',
-        // and Codex names its shell tools `shell` / `exec_command` /
-        // `unified_exec`. The fields it reads ARE delivered; the value it
-        // compares against never occurs. A manifest entry would be a silent
-        // no-op, not enforcement — #919-P2 class. Gap registered, not faked.
-        'pre-bash-sessions-ledger-guard.mjs',
+        // pre-bash-templates-first (#1691): runs on the Codex payload but can
+        // only DENY. Both allow routes are unreachable there: the template-Read
+        // evidence needs `transcript_path` (hooks/pre-bash-templates-first.mjs:
+        // 404-410), which Codex sends as `null` (codex-cli 0.160.1, 2026-10-20),
+        // and `/templates-ack` writes an acknowledgement only under a `claude`
+        // ancestor process (commands/templates-ack.md:18-23). Fed the Codex
+        // payload with `.gitlab/issue_templates/bug.md` present, `glab issue
+        // create` was denied with no way to satisfy it. A guard nobody can pass
+        // is a blocker, not enforcement; gap registered, not faked.
         'pre-bash-templates-first.mjs',
-        'pre-bash-issue-budget.mjs',
-        'enforce-commands.mjs',
       ],
-      // post-bash-write-verify (#942): gates on tool_name === 'Bash', a value
-      // Codex never emits (its shell tools are `shell` / `exec_command` /
-      // `unified_exec`). Documented exception until a tool-name map exists —
-      // a manifest entry today would be a silent no-op, not enforcement. Same
-      // #919-P2 class as the PreToolUse block. `post-tool-use.command.input`
-      // at 0.144.4 does require `tool_name`, `tool_input` AND `tool_response`,
-      // so the port is a rename map, not a payload bridge.
       PostToolUse: [
         'post-edit-validate.mjs',
         'post-tooluse-frontend-slop.mjs',
@@ -147,7 +169,6 @@ const DOCUMENTED_ASYMMETRIES = {
         // tool_input.file_path, neither of which any Codex bridge delivers.
         // A manifest entry would be a silent no-op, not enforcement.
         'post-edit-import-probe.mjs',
-        'post-bash-write-verify.mjs',
       ],
       SubagentStart: ['subagent-telemetry.mjs'],
       SubagentStop: ['subagent-telemetry.mjs', 'post-subagent-discovery-validator.mjs'],
@@ -247,7 +268,7 @@ function loadJson(filePath, required = true) {
   try {
     return JSON.parse(readFileSync(filePath, 'utf8'));
   } catch (e) {
-    fail(`${filePath.split('/').pop()}: ${e.message}`);
+    fail(`${basename(filePath)}: ${e.message}`);
     process.exit(1);
   }
 }

package/scripts/lib/validate/check-json-files.mjs

@@ -85,7 +85,9 @@ if (hooksPath && hooksPath.endsWith('.json')) {
 console.log('');
 console.log('--- Check 5b: mcpServers JSON validity ---');
 
-const mcpPath = pluginData.mcpServers ?? '';
+// mcpServers may also be an inline object or an array (plugins-reference §
+// Component path forms); only a .json path string is a file to parse here.
+const mcpPath = typeof pluginData.mcpServers === 'string' ? pluginData.mcpServers : '';
 if (mcpPath && mcpPath.endsWith('.json')) {
   const mcpAbs = join(pluginRoot, mcpPath.replace(/^\.\//, ''));
   if (existsSync(mcpAbs)) {

package/scripts/lib/validate/check-learning-provenance.mjs

@@ -134,6 +134,7 @@ import { readLearnings } from '../learnings/io.mjs';
 // the emitter's formula.
 import { learningKeyOf } from '../learnings/kebab.mjs';
 import { isMainModule } from '../is-main-module.mjs';
+import { resolveLedgerPath } from '../ledger-path.mjs';
 
 /** Directory holding the rule corpus, relative to the plugin root. */
 const RULES_REL = path.join('.claude', 'rules');
@@ -272,8 +273,8 @@ async function indexStore(absolutePath) {
 export async function inspectLearningProvenance(pluginRoot, opts = {}) {
   /** @type {Finding[]} */
   const findings = [];
-  const livePath = opts.livePath ?? path.join(pluginRoot, LIVE_STORE_REL);
-  const archivePath = opts.archivePath ?? path.join(pluginRoot, ARCHIVE_STORE_REL);
+  const livePath = opts.livePath ?? resolveLedgerPath(LIVE_STORE_REL, pluginRoot);
+  const archivePath = opts.archivePath ?? resolveLedgerPath(ARCHIVE_STORE_REL, pluginRoot);
 
   /** @type {Inspection} */
   const result = {

package/scripts/lib/validate/check-learnings-shell-writes.mjs

@@ -61,10 +61,16 @@ export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', 'docs',
 /** Lines on either side of an R2 operator searched for an anchor. */
 const WINDOW = 3;
 
-const MENTION_RE = /learnings\.jsonl/;
-const ANCHOR_RE = /learnings\.jsonl|\b(?:the|learnings) store\b|\bresult back\b|\batomic rewrite\b/i;
-const SHELL_REDIRECT_RE = /(?:^|[\s|;&(])(>{1,2})[ \t]*["'`]?[^\s"'`<>]*learnings\.jsonl\b/dg;
-const TEE_RE = /\btee\b(?:[ \t]+-{1,2}[\w-]+)*[ \t]+["'`]?[^\s"'`|]*learnings\.jsonl\b/g;
+/**
+ * The protected store filenames: the live store plus the #1516 inbox and its
+ * receipts — append-only stores written only through `learnings/io.mjs`.
+ */
+const STORE = String.raw`learnings(?:-inbox(?:-ingested)?)?\.jsonl`;
+
+const MENTION_RE = new RegExp(STORE);
+const ANCHOR_RE = new RegExp(String.raw`${STORE}|\b(?:the|learnings) store\b|\bresult back\b|\batomic rewrite\b`, 'i');
+const SHELL_REDIRECT_RE = new RegExp(String.raw`(?:^|[\s|;&(])(>{1,2})[ \t]*["'\`]?[^\s"'\`<>]*${STORE}\b`, 'dg');
+const TEE_RE = new RegExp(String.raw`\btee\b(?:[ \t]+-{1,2}[\w-]+)*[ \t]+["'\`]?[^\s"'\`|]*${STORE}\b`, 'g');
 const PROSE_OPERATOR_RE = /`>{1,2}`/g;
 const ANY_OPERATOR_RE = /`>{1,2}`|(?:^|[\s|;&(])>{1,2}|\btee\b/;
 const PROHIBITION_RE = /\b(NEVER|[Nn]ever|DO NOT|[Dd]o not|[Dd]on't|FORBIDDEN|forbidden|verboten)\b/;

package/scripts/lib/validate/check-metrics-ledger-root.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+/**
+ * Check: every line under `scripts/`, `hooks/` and `skills/` that builds a path
+ * into `.orchestrator/metrics` routes it through a ledger resolver (GitLab
+ * #1722). BLOCKING.
+ *
+ * ## Why
+ *
+ * The ledgers under `.orchestrator/metrics/` are gitignored in this repo
+ * (`.gitignore:57`). A writer that joins the path to the cwd, `getProjectDir()`
+ * or an unmapped repo root writes, from a linked worktree, a copy that is lost
+ * with the worktree, and a reader built the same way sees an empty ledger.
+ * Measured 2026-10-22 before #1722: 43 of 62 sites in 54 unrouted modules,
+ * two stranded ledgers in live worktrees (`eval.jsonl`, `skill-invocations.jsonl`).
+ * A first, per-FILE version of this check passed while five readers in
+ * resolver-calling modules still read the worktree copy (review of the same
+ * day) — hence the per-LINE rule below.
+ *
+ * The resolvers that answer correctly:
+ *   - `resolveLedgerPath()` / `resolveLedgerRoot()` (`scripts/lib/ledger-path.mjs`)
+ *     for every ledger except events and sessions — main checkout only when
+ *     the ledger is gitignored in the worktree, so repos that version it keep
+ *     it on the branch;
+ *   - `resolveEventsLedgerRoot()` / `explainEventsLedgerRoot()` /
+ *     `eventsFilePath()` (`scripts/lib/platform.mjs`, `scripts/lib/events.mjs`)
+ *     for `events.jsonl` and `sessions.jsonl` (#1514, #1584);
+ *   - helpers built on them (`resolveLearningsPaths`, `defaultSkillInvocationsPath`).
+ *
+ * ## Rule
+ *
+ * A HIT is a non-comment line with a `.orchestrator/metrics` string literal or
+ * the segment pair `'.orchestrator', 'metrics'` (also split over two lines,
+ * reported on the `'.orchestrator',` line). It passes when
+ *   (a) a resolver is called on that line or on one of the {@link LOOKBACK}
+ *       lines above it that belong to the same statement (a multi-line
+ *       `path.join(` whose root argument comes first),
+ *   (b) it declares an UPPER_CASE relative constant (string, `path.join(…)` or
+ *       array of segments) — the join site of the constant is checked by (2), or
+ *   (c) it, or the line above, carries the marker `ledger-root: <reason>` —
+ *       for a line that is no ledger access or whose root is already resolved.
+ * (2) A line that passes such a constant to `join(`/`resolve(` follows the same
+ *     (a)/(c) rule.
+ * A file on {@link ALLOWLIST} is skipped whole; an allowlisted file without a
+ * HIT fails, so the list cannot rot.
+ *
+ * Ceiling: (2) sees constants declared in the same file only, and (a) trusts
+ * any resolver within the lookback window. Revisit if a stranded ledger is
+ * traced to an imported constant or to a line the window wrongly covered.
+ *
+ * @module scripts/lib/validate/check-metrics-ledger-root
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { enumerateRepoFiles } from './enumerate-repo-files.mjs';
+import { isMainModule } from '../is-main-module.mjs';
+
+export const SCAN_DIRS = Object.freeze(['scripts', 'hooks', 'skills']);
+
+/** Lines above a HIT in which a resolver call still counts (multi-line joins). */
+export const LOOKBACK = 3;
+
+/** A string literal starting with the metrics dir, or the two-segment join. */
+const METRICS_PATH_RE = /['"`]\.orchestrator\/metrics|['"]\.orchestrator['"]\s*,\s*['"]metrics['"]/;
+
+/** The two-segment join split over two lines: `'.orchestrator',` ⏎ `'metrics'`. */
+const SPLIT_HEAD_RE = /['"]\.orchestrator['"]\s*,\s*$/;
+const SPLIT_TAIL_RE = /^\s*['"]metrics['"]/;
+
+function isHit(lines, i) {
+  return METRICS_PATH_RE.test(lines[i]) || (SPLIT_HEAD_RE.test(lines[i]) && SPLIT_TAIL_RE.test(lines[i + 1] ?? ''));
+}
+
+const RESOLVER_CALL_RE =
+  /\b(?:resolveLedgerPath|resolveLedgerRoot|resolveEventsLedgerRoot|explainEventsLedgerRoot|eventsFilePath|resolveLearningsPaths|defaultSkillInvocationsPath)\s*\(/;
+
+const MARKER_RE = /ledger-root:/;
+
+/** `const NAME = '…'`, `= path.join('…'`, `= join('…'`, `= ['…'`, optionally inside Object.freeze( */
+const CONST_DECL_RE =
+  /^\s*(?:export\s+)?const\s+([A-Z][A-Z0-9_]*)\s*=\s*(?:Object\.freeze\(\s*)?(?:(?:path\.)?join\(\s*|\[\s*)?['"`]\.orchestrator/;
+
+const PATH_FN_RE = /\b(?:join|resolve)\s*\(/;
+
+/**
+ * Files that build a metrics path on purpose without a resolver. Each reason
+ * is the census verdict (2026-10-22): INTENDED-LOCAL (the data belongs to this
+ * working tree), NOT-A-SINK (the string is no ledger path being opened) or
+ * ROUTED-DOWNSTREAM (the path is handed to a callee that resolves each ledger).
+ * Prefer the line marker `ledger-root: <reason>` for a single line in a file
+ * that otherwise reads ledgers.
+ */
+export const ALLOWLIST = Object.freeze({
+  'hooks/on-session-end.mjs':
+    'ROUTED-DOWNSTREAM: hands the launch dir\'s metrics dir to the telemetry flush; buildBatch resolves each ledger in it (scripts/lib/telemetry/sync.mjs)',
+  'hooks/pre-bash-sessions-ledger-guard.mjs':
+    'NOT-A-SINK/INTENDED-LOCAL: matches command text, and probes the exact --repo-root the repair CLI is given',
+  'scripts/lib/autopilot/flags.mjs': 'constant only: the relative DEFAULT_JSONL_PATH; the loop resolves it',
+  'scripts/lib/convergence-monitor.mjs': 'NOT-A-SINK: a label and help text; the read goes through the events ledger root',
+  'scripts/lib/playwright-driver/runner.mjs':
+    'INTENDED-LOCAL: guards the per-run artifact dir, which the artifact builder roots in this tree',
+  'scripts/lib/project-hygiene.mjs': 'NOT-A-SINK: a git ls-files pathspec over this tree\'s own index',
+  'scripts/lib/quality-gate.mjs':
+    'INTENDED-LOCAL: verification-failure bundles of this tree\'s gate run, which can carry secrets',
+  'scripts/lib/quality-gates-cache.mjs':
+    'INTENDED-LOCAL: cache keyed to this tree\'s session start ref and dependency hash',
+  'scripts/lib/scope-baseline.mjs': 'NOT-A-SINK: an exclusion glob for drift counting',
+  'scripts/lib/ux-grill/manifest.mjs': 'NOT-A-SINK: a .gitignore line for the run-artifact dir',
+  'scripts/lib/vault-mirror/retention.mjs': 'NOT-A-SINK: text inside a generated note body',
+  'scripts/lib/wave-transcript-tail.mjs': 'NOT-A-SINK: help text',
+  'scripts/relocate-vault-corpus.mjs':
+    'INTENDED-LOCAL: reads each child of --repos-root as named; mapping a worktree child would count its main twice',
+  'scripts/run-migrate-v2-cross-repo.mjs': 'INTENDED-LOCAL: migrates the repos the operator names, as named',
+});
+
+function isCommentLine(line) {
+  const t = line.trim();
+  return t.startsWith('//') || t.startsWith('*') || t.startsWith('/*');
+}
+
+/**
+ * Line `i` plus up to {@link LOOKBACK} lines above it that belong to the SAME
+ * statement — the walk stops at a line ending in `;`, `{` or `}`, or at a blank
+ * line, so a resolver call in the previous statement does not cover this one.
+ */
+function statementWindow(lines, i) {
+  const window = [lines[i]];
+  for (let j = i - 1; j >= 0 && window.length <= LOOKBACK; j -= 1) {
+    const prev = lines[j];
+    if (prev.trim() === '' || /[;{}]\s*$/.test(prev)) break;
+    window.unshift(prev);
+  }
+  return window.join('\n');
+}
+
+/** (a) or (c) for line `i`. */
+function covered(lines, i) {
+  if (RESOLVER_CALL_RE.test(statementWindow(lines, i))) return true;
+  return MARKER_RE.test(lines[i]) || (i > 0 && MARKER_RE.test(lines[i - 1]));
+}
+
+/**
+ * @param {{ pluginRoot: string, dirs?: readonly string[], allowlist?: Record<string, string> }} opts
+ * @returns {{ ok: boolean, findings: Array<{ file: string, line: number, kind: 'unrouted'|'unrouted-constant'|'stale-allowlist', text?: string }>, summary: { filesScanned: number, hits: number, resolved: number, constants: number, marked: number, allowlisted: number } }}
+ */
+export function scanMetricsLedgerRoot({ pluginRoot, dirs = SCAN_DIRS, allowlist = ALLOWLIST }) {
+  const files = enumerateRepoFiles({ repoRoot: pluginRoot, dirs: [...dirs], exts: ['.mjs'] });
+  const findings = [];
+  const seenAllowlisted = new Set();
+  const summary = { filesScanned: files.length, hits: 0, resolved: 0, constants: 0, marked: 0, allowlisted: 0 };
+  for (const abs of files) {
+    const rel = path.relative(pluginRoot, abs).split(path.sep).join('/');
+    if (/\.(test|spec)\.mjs$/.test(rel)) continue;
+    const lines = readFileSync(abs, 'utf8').split('\n');
+    const constNames = [];
+    const fileFindings = [];
+    let fileHits = 0;
+    lines.forEach((line, i) => {
+      if (isCommentLine(line) || !isHit(lines, i)) return;
+      fileHits += 1;
+      const decl = CONST_DECL_RE.exec(line);
+      if (decl) {
+        constNames.push(decl[1]);
+        summary.constants += 1;
+      } else if (covered(lines, i)) {
+        summary[RESOLVER_CALL_RE.test(statementWindow(lines, i)) ? 'resolved' : 'marked'] += 1;
+      } else {
+        fileFindings.push({ file: rel, line: i + 1, kind: 'unrouted', text: line.trim().slice(0, 160) });
+      }
+    });
+    if (constNames.length > 0) {
+      const uses = new RegExp(`\\b(?:${constNames.join('|')})\\b`);
+      lines.forEach((line, i) => {
+        if (isCommentLine(line) || CONST_DECL_RE.test(line)) return;
+        if (!uses.test(line) || !PATH_FN_RE.test(line) || covered(lines, i)) return;
+        fileFindings.push({ file: rel, line: i + 1, kind: 'unrouted-constant', text: line.trim().slice(0, 160) });
+      });
+    }
+    if (fileHits === 0) continue;
+    summary.hits += fileHits;
+    if (Object.hasOwn(allowlist, rel)) {
+      seenAllowlisted.add(rel);
+      continue;
+    }
+    findings.push(...fileFindings);
+  }
+  for (const rel of Object.keys(allowlist)) {
+    if (!seenAllowlisted.has(rel)) findings.push({ file: rel, line: 0, kind: 'stale-allowlist' });
+  }
+  summary.allowlisted = seenAllowlisted.size;
+  return { ok: findings.length === 0, findings, summary };
+}
+
+/**
+ * @param {string} pluginRoot absolute plugin root
+ * @returns {number} 0 = clean, 1 = findings
+ */
+export function runCheckMetricsLedgerRoot(pluginRoot) {
+  console.log('--- Check: .orchestrator/metrics paths go through a ledger resolver (#1722) ---');
+  const inspection = scanMetricsLedgerRoot({ pluginRoot });
+  for (const f of inspection.findings) {
+    if (f.kind === 'stale-allowlist') {
+      console.log(`  FAIL: ${f.file} is on the ALLOWLIST but builds no .orchestrator/metrics path any more — drop the entry`);
+    } else {
+      console.log(
+        `  FAIL: ${f.file}:${f.line} builds a .orchestrator/metrics path without resolveLedgerPath() ` +
+          '(events/sessions: resolveEventsLedgerRoot()) — from a linked worktree it reads or writes a copy ' +
+          `lost with the worktree; route it, or mark a non-ledger line with \`// ledger-root: <reason>\`: ${f.text}`,
+      );
+    }
+  }
+  const s = inspection.summary;
+  if (inspection.ok) {
+    console.log(
+      `  PASS: ${s.hits} metrics path line(s) in ${s.filesScanned} module(s): ${s.resolved} resolved, ` +
+        `${s.constants} relative constant(s), ${s.marked} marked, ${s.allowlisted} allowlisted module(s)`,
+    );
+  }
+  console.log('');
+  console.log(`Results: ${inspection.ok ? 1 : 0} passed, ${inspection.findings.length} failed`);
+  return inspection.ok ? 0 : 1;
+}
+
+if (isMainModule(import.meta.url)) {
+  const args = process.argv.slice(2).filter((arg) => arg !== '--json');
+  const root = path.resolve(args[0] || process.cwd());
+  if (process.argv.includes('--json')) {
+    const inspection = scanMetricsLedgerRoot({ pluginRoot: root });
+    process.stdout.write(`${JSON.stringify(inspection, null, 2)}\n`);
+    process.exitCode = inspection.ok ? 0 : 1;
+  } else {
+    process.exitCode = runCheckMetricsLedgerRoot(root);
+  }
+}