session-orchestrator 5.12.0 → 5.13.0

package/scripts/lib/telemetry/sync.mjs

@@ -23,9 +23,10 @@
  * queue (bounded, oldest-dropped) and the session closes with zero user-facing
  * error.
  *
- * Node ESM. The only network dependency is the global `fetch`.
+ * Node ESM. Networking uses the Stdlib HTTP helper.
  */
 
+import { httpRequest } from '../http-request.mjs';
 import path from 'node:path';
 import os from 'node:os';
 import fs from 'node:fs';
@@ -43,10 +44,11 @@ import { loadOwnerConfig } from '../owner-yaml.mjs';
 import { readJsonlFile } from '../io.mjs';
 import { readEventsWithRotations } from '../events.mjs';
 import { resolveEventsLedgerRoot } from '../platform.mjs';
+import { resolveLedgerPath } from '../ledger-path.mjs';
 import { readCanonicalSessions } from '../sessions-canonical.mjs';
 import { resolvePrivateConfigDir } from '../config/private-config-dir.mjs';
 import { readSessionProfile } from '../state-md.mjs';
-import { resolveStateMdPath } from '../state-md/frontmatter-mutators.mjs';
+import { resolveStateMdWriteTarget } from '../state-md/frontmatter-mutators.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -73,7 +75,7 @@ function resolveEndpoint(env) {
 
 /**
  * The default network sender: one POST carrying the whole batch array as the
- * JSON body (the server accepts arrays), with an AbortSignal timeout. Resolves
+ * JSON body (the server accepts arrays), with a wall-clock timeout. Resolves
  * on a 2xx status, rejects on anything else (which routes the caller into the
  * offline queue).
  *
@@ -85,11 +87,12 @@ function resolveEndpoint(env) {
 function defaultSender({ env, timeoutMs }) {
   const endpoint = resolveEndpoint(env);
   return async (batches) => {
-    const res = await fetch(endpoint, {
+    const res = await httpRequest(endpoint, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(batches),
-      signal: AbortSignal.timeout(timeoutMs),
+      timeoutMs,
+      maxBytes: 64 * 1024,
     });
     if (!res.ok) {
       // The status travels ON the error: `flush` needs it to tell a TRANSPORT
@@ -307,7 +310,15 @@ export function readSessionProfileForMetricsDir(metricsDir) {
     // metricsDir is `<repoRoot>/.orchestrator/metrics` by construction (every
     // caller builds it that way); two levels up is the repo root.
     const repoRoot = path.resolve(metricsDir, '..', '..');
-    return readSessionProfile(fs.readFileSync(resolveStateMdPath(repoRoot), 'utf8'));
+    // #1636: the write side's ownership rule — another platform's STATE.md not
+    // proven to be this process's is no profile source (ABSENT IS NOT EMPTY:
+    // null ⇒ the ping omits the field). Deliberately NO warnForeignStateMd line:
+    // this runs inside flush, which the hooks call in-process at SessionEnd or
+    // spawn detached with `stdio: 'ignore'` — the line would be hook noise or
+    // lost, and an omitted optional field needs no operator action.
+    const { path: stateMdPath, rejected } = resolveStateMdWriteTarget(repoRoot);
+    if (rejected) return null;
+    return readSessionProfile(fs.readFileSync(stateMdPath, 'utf8'));
   } catch {
     return null;
   }
@@ -494,6 +505,23 @@ export function deriveSessionFromEvents(metricsDir) {
   }
 }
 
+/**
+ * `skill-invocations.jsonl` for the metrics dir `metricsDir` (#1722): a
+ * `<root>/.orchestrator/metrics` dir resolves through {@link resolveLedgerPath}
+ * for `<root>` — the main checkout's ledger when `<root>` is a linked worktree
+ * that ignores it, else the dir's own — and any other dir is read as given.
+ *
+ * @param {string} metricsDir
+ * @returns {string}
+ */
+function skillInvocationsPathFor(metricsDir) {
+  const parent = path.dirname(metricsDir);
+  if (path.basename(metricsDir) === 'metrics' && path.basename(parent) === '.orchestrator') {
+    return resolveLedgerPath('.orchestrator/metrics/skill-invocations.jsonl', path.dirname(parent));
+  }
+  return path.join(metricsDir, 'skill-invocations.jsonl');
+}
+
 /**
  * Build ONE whitelist-projected usage-ping record from the local JSONL streams.
  *
@@ -537,11 +565,19 @@ export function buildBatch({
   consentState,
 } = {}) {
   try {
+    // `dir` stays the caller's metrics dir: STATE.md and the events fallback
+    // below derive their own roots from it.
+    // ledger-root: the caller's dir as given; each ledger in it resolves below
     const dir = metricsDir || path.join(process.cwd(), '.orchestrator', 'metrics');
     const nowIso = now || new Date().toISOString();
 
-    const sessions = readCanonicalSessions({ filePath: path.join(dir, 'sessions.jsonl') });
-    const invocations = readJsonlFile(path.join(dir, 'skill-invocations.jsonl'), { skipInvalid: true });
+    // #1722: each ledger resolves on its own, an explicit metricsDir included
+    // (the SessionEnd flush hands over the LAUNCH dir's, which is a linked
+    // worktree for a session started there; deriveSessionFromEvents maps the
+    // events fallback the same way) — sessions via the one-ledger root
+    // (#1514/#1584), skill-invocations via skillInvocationsPathFor().
+    const sessions = readCanonicalSessions({ filePath: path.join(resolveEventsLedgerRoot(dir), 'sessions.jsonl') });
+    const invocations = readJsonlFile(skillInvocationsPathFor(dir), { skipInvalid: true });
 
     const sessionRecord = mostRecentSession(sessions);
 
@@ -855,7 +891,7 @@ export function shouldDailyFlush({ statePath, queuePath, metricsDir, now = Date.
     //     (271 records / 292 KB in this repo, 2026-08-23) that is sub-millisecond
     //     and it only runs once the 24h gate above has already passed. Revisit
     //     with a tail-read if any repo's sessions.jsonl passes ~10 MB.
-    const dir = metricsDir || path.join(process.cwd(), '.orchestrator', 'metrics');
+    const dir = metricsDir || path.join(resolveEventsLedgerRoot(process.cwd()), '.orchestrator', 'metrics');
     const sessions = readCanonicalSessions({ filePath: path.join(dir, 'sessions.jsonl') });
     const last = mostRecentSession(sessions);
     const completedMs = Date.parse(last?.completed_at);

package/scripts/lib/test-runner/artifact-paths.mjs

@@ -17,6 +17,7 @@
  */
 
 import path from 'node:path';
+import { resolveLedgerPath } from '../ledger-path.mjs';
 
 const ROLLUP_REL = '.orchestrator/metrics/test-runs.jsonl';
 const TEST_RUNS_REL = '.orchestrator/metrics/test-runs';
@@ -62,6 +63,7 @@ export function makeRunId() {
  * @throws {TypeError} on an invalid runId (see {@link assertRunId})
  */
 export function runDirPath(runId) {
+  // ledger-root: per-run artifact dir of this working tree, kept local
   return path.join(TEST_RUNS_REL, assertRunId(runId));
 }
 
@@ -112,8 +114,14 @@ export function consoleLogPath(runId) {
 
 /**
  * Path to the shared JSONL rollup file (across all runs).
+ *
+ * Without `repoRoot` it is the repo-relative constant. With `repoRoot` it is
+ * the absolute ledger path, routed to the main checkout when `repoRoot` is a
+ * linked worktree of a repo that ignores the rollup (#1722).
+ *
+ * @param {string} [repoRoot]
  * @returns {string}
  */
-export function jsonlRollupPath() {
-  return ROLLUP_REL;
+export function jsonlRollupPath(repoRoot) {
+  return typeof repoRoot === 'string' && repoRoot !== '' ? resolveLedgerPath(ROLLUP_REL, repoRoot) : ROLLUP_REL;
 }

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/;