session-orchestrator 5.2.0 → 5.3.0

package/scripts/resolve-session-invocation.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/** Stdin-only boundary for commands/session.md; never executes task context. */
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { resolveSessionInvocation } from './lib/session-invocation.mjs';
+
+const HELP = `Usage: node scripts/resolve-session-invocation.mjs [--json] < arguments.txt
+
+Read the complete /session argument text from UTF-8 stdin.
+Resolve the leading housekeeping, feature, deep or ultradeep token; preserve
+the rest as task context. Empty input defaults to deep. An invalid mode emits
+a warning and resolves to deep, as the session command has always specified.
+
+  --json     Emit one JSON object instead of a human-readable summary
+  --help     Show this help
+  --version  Show the plugin version
+
+Example: node scripts/resolve-session-invocation.mjs --json < arguments.txt
+Write arguments.txt with a file tool; do not interpolate user text into a shell.
+Exit codes: 0 resolved (including fallback), 1 bad CLI arguments, 2 stdin I/O error
+`;
+
+let options;
+try {
+  options = parseArgs({
+    options: { json: { type: 'boolean' }, help: { type: 'boolean' }, version: { type: 'boolean' } },
+    allowPositionals: false,
+  }).values;
+} catch (error) {
+  process.stderr.write(`session-invocation: ${error.message}\n`);
+  process.exit(1);
+}
+
+if (options.help) {
+  process.stdout.write(HELP);
+} else if (options.version) {
+  process.stdout.write(
+    `${JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version}\n`,
+  );
+} else {
+  let input;
+  try {
+    input = readFileSync(0, 'utf8');
+  } catch {
+    process.stderr.write('session-invocation: could not read UTF-8 stdin\n');
+    process.exit(2);
+  }
+  const resolved = resolveSessionInvocation(input);
+  if (resolved.invalidMode !== undefined) {
+    process.stderr.write(
+      `Invalid session type '${resolved.invalidMode}'. Valid types: housekeeping, feature, deep (alias: ultradeep). Falling back to deep.\n`,
+    );
+  }
+  process.stdout.write(
+    options.json
+      ? `${JSON.stringify(resolved)}\n`
+      : `Session type: ${resolved.sessionType}${resolved.profile ? ` (profile: ${resolved.profile})` : ''}\nTask context: ${resolved.context}\n`,
+  );
+}

package/scripts/run-quality-gate.mjs

@@ -23,9 +23,15 @@
  *   0 — pass (or informational; non-blocking variants always exit 0)
  *   1 — script error (bad arguments, missing dependencies)
  *   2 — gate failed (full-gate only: typecheck/test/lint errors)
+ * 124 — the gate sub-script exceeded the wall-clock ceiling and its whole
+ *       process GROUP was killed (SIGTERM→SIGKILL). Same value coreutils
+ *       `timeout(1)` uses. Applies to EVERY variant, including the otherwise
+ *       non-blocking ones: a killed gate measured nothing, so reporting it as
+ *       0 would be a false green (Epic #1425 A3).
  *
  * The gate sub-scripts in scripts/lib/gates/ are NOT reimplemented here; they are
- * invoked via child_process.spawn('bash', [path, ...]) with the required env vars.
+ * invoked via spawnInGroup() — a detached, process-group-leading shell — with the
+ * required env vars.
  *
  * References:
  *   scripts/run-quality-gate.sh                  — original shell orchestrator
@@ -37,12 +43,18 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 
 import { die, warn } from './lib/common.mjs';
 import { loadQualityGatesPolicy, resolveCommand } from './lib/quality-gates-policy.mjs';
 import { emitEvent, sessionAttribution } from './lib/events.mjs';
-import { admitSuiteCounts } from './lib/gates/gate-helpers.mjs';
+import {
+  admitSuiteCounts,
+  publishGateOutcome,
+  resolveGateTimeoutMs,
+} from './lib/gates/gate-helpers.mjs';
+import { buildCommandSignature, spawnInGroup } from './lib/process-group.mjs';
+import { readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
 import { findScopeFile } from './lib/scope-gate.mjs';
 
 // ---------------------------------------------------------------------------
@@ -62,6 +74,24 @@ const VALID_VARIANTS = ['baseline', 'incremental', 'full-gate', 'per-file'];
  */
 const GATE_STDOUT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
 
+/**
+ * Head-room between the ceiling the gate's OWN commands run under
+ * (`resolveGateTimeoutMs()`, applied per command inside `runCheck`) and the one
+ * this wrapper applies to the gate sub-script as a whole.
+ *
+ * The inner cap must fire FIRST: it kills exactly the wedged command and still
+ * lets the gate print its JSON envelope, name the failing check on stderr and
+ * exit 2. This outer cap is the backstop for the case the inner one cannot
+ * reach — a gate wedged outside `runCheck`, or a kill ladder that left a
+ * survivor holding the pipe open.
+ *
+ * Named ceiling (BV-004): 60 s. It only has to cover one full SIGTERM→grace→
+ * SIGKILL→verify ladder (`DEFAULT_KILL_GRACE_MS` 10 s + 0.5 s verify + 1 s
+ * deadline slack ≈ 11.5 s) plus the gate's own JSON write. Revisit if the grace
+ * period is ever raised past ~45 s.
+ */
+const GATE_OUTER_TIMEOUT_RESERVE_MS = 60_000;
+
 const DEFAULT_TEST_CMD = 'npm test';
 const DEFAULT_TYPECHECK_CMD = 'npm run typecheck';
 const DEFAULT_LINT_CMD = 'npm run lint';
@@ -88,7 +118,8 @@ if (argv.includes('-h') || argv.includes('--help')) {
     'Exit codes:\n' +
     '  0 — pass (non-blocking variants always exit 0)\n' +
     '  1 — script error (bad arguments, missing dependencies)\n' +
-    '  2 — gate failed (full-gate only)\n',
+    '  2 — gate failed (full-gate only)\n' +
+    '  124 — gate timed out; its process group was killed (SIGTERM→SIGKILL)\n',
   );
   process.exit(0);
 }
@@ -355,6 +386,11 @@ if (!existsSync(gatePath)) {
   die(`Gate script not found: ${gatePath}`);
 }
 
+// Resolved BEFORE the spawn (it used to sit beside the telemetry block below):
+// the gate-process ledger the spawn writes is pinned to the same root as the
+// event, for the same reason — see the spawn's `repoRoot` comment.
+const ledgerRoot = resolveLedgerRoot(ledgerRootArg);
+
 // `npm_config_loglevel` is INHERITED by every descendant, and the pre-push hook
 // invokes this script as `npm run --silent quality-gate` — which sets it to
 // `silent`. That level then reached the gate's own children: `npm pack
@@ -368,37 +404,141 @@ if (!existsSync(gatePath)) {
 // independent of how the gate itself was invoked. `--silent` still does its real
 // job — keeping THIS process's stdout to the single JSON envelope — because the
 // children's output is captured by `runCheck`, never streamed.
+/**
+ * Per-command wall-clock ceiling for PATH B (#1425 A3 / #1432).
+ *
+ * Precedence, highest first:
+ *   1. `SO_GATE_TIMEOUT_MS` — the OPERATOR override. It is inherited by every
+ *      descendant, so a gate child that re-derives the ceiling gets the same
+ *      answer; `resolveGateTimeoutMs()` already reads it.
+ *   2. Session Config `gate.timeout-path-b-ms` — the COMMITTED default.
+ *   3. `DEFAULT_GATE_TIMEOUT_MS` (900 000), via `resolveGateTimeoutMs()`.
+ *
+ * Published to the gate sub-script as `GATE_TIMEOUT_MS` — a DIFFERENT name from
+ * the operator override on purpose: writing the resolved value back into
+ * `SO_GATE_TIMEOUT_MS` would make a committed default indistinguishable from an
+ * operator decision for every process further down the tree.
+ */
+const configuredGateTimeoutMs = (() => {
+  const block = configJson !== null && typeof configJson === 'object' ? configJson.gate : null;
+  const raw = block && typeof block === 'object' ? block['timeout-path-b-ms'] : undefined;
+  return Number.isFinite(raw) && raw > 0 ? raw : null;
+})();
+const operatorTimeoutOverride = (process.env.SO_GATE_TIMEOUT_MS || '').trim() !== '';
+const commandTimeoutMs = operatorTimeoutOverride || configuredGateTimeoutMs === null
+  ? resolveGateTimeoutMs()
+  : configuredGateTimeoutMs;
+
+// Gate-process REGISTER root — the same precedence the telemetry destination
+// uses below (`--ledger-root` > project-dir env > cwd), so a sandboxed test that
+// only sets CLAUDE_PROJECT_DIR never writes register lines into the checkout.
+const gateLedgerRoot =
+  ledgerRoot ?? process.env.CLAUDE_PROJECT_DIR ?? process.env.CODEX_PROJECT_DIR ?? repoRoot;
+
 const env = {
   ...process.env,
   npm_config_loglevel: 'notice',
   TYPECHECK_CMD,
   TEST_CMD,
   LINT_CMD,
+  GATE_TIMEOUT_MS: String(commandTimeoutMs),
+  // Same resolution the wrapper uses for its OWN spawn (`--ledger-root` > repo
+  // root): the gate sub-scripts pass it to runCheck() so every register line of
+  // one gate run lands in ONE ledger (#1425 A4, W5 fix-pass).
+  GATE_LEDGER_ROOT: gateLedgerRoot,
   FILES: files,
   SESSION_START_REF: sessionStartRef,
 };
 
+/**
+ * POSIX single-quote one argument for the shell `spawnInGroup` runs the command
+ * through. The gate path is derived from `import.meta.url`, so it carries
+ * whatever the checkout path carries — a space in it must not split the command.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+// The gate sub-script runs as the LEADER OF ITS OWN PROCESS GROUP under a
+// wall-clock ceiling (Epic #1425 A3). Before this, `spawnSync('node', [gatePath])`
+// had NO timeout at all and no group semantics: a wedged `tsgo` or vitest worker
+// two levels down was reparented to PPID 1 and kept its memory (2026-09-20: four
+// such orphans, up to 8.0 GB RSS each, host at 13 % free).
+//
 // stdout is PIPED (not inherited) so the suite counts the gate already computed
 // can be lifted straight off its JSON envelope into telemetry (#954) instead of
 // travelling as prose through the STATE.md header. The envelope is re-emitted
 // verbatim below, so the stdout contract is unchanged — a gate sub-script writes
 // exactly one JSON line at the very end (its own child commands are captured by
-// `runCheck`), so nothing streamed before and nothing streams now. stderr stays
-// inherited, keeping warnings live.
-const result = spawnSync('node', [gatePath], {
+// `runCheck`), so nothing streamed before and nothing streams now.
+//
+// stderr stays INHERITED, and that is why `spawnFn` is overridden here rather
+// than left at its default: `spawnInGroup` merges stdout and stderr into one
+// capture, which would interleave the gate's failure disclosure (hundreds of
+// lines, #1149) into the single JSON document every consumer parses off stdout.
+// Handing it a child with `stderr: 'inherit'` leaves `child.stderr` null, the
+// module's own `child.stderr?.on(…)` a no-op, and the gate's warnings live on
+// the operator's terminal exactly as before.
+const gateCommand = `node ${shellQuote(gatePath)}`;
+// Derived from the SAME resolved per-command ceiling published as
+// `GATE_TIMEOUT_MS` above — not from `resolveGateTimeoutMs()` a second time.
+// The outer cap must stay strictly ABOVE the inner one so the inner kill fires
+// first and the gate can still print its envelope; re-deriving here would leave
+// the outer cap at the 900 000 default while a committed
+// `gate.timeout-path-b-ms` above it made the inner cap the later of the two.
+const gateTimeoutMs = commandTimeoutMs + GATE_OUTER_TIMEOUT_RESERVE_MS;
+const result = await spawnInGroup(gateCommand, {
+  cwd: repoRoot,
   env,
-  stdio: ['inherit', 'pipe', 'inherit'],
-  encoding: 'utf8',
-  maxBuffer: GATE_STDOUT_MAX_BUFFER_BYTES,
+  timeoutMs: gateTimeoutMs,
+  maxOutputBytes: GATE_STDOUT_MAX_BUFFER_BYTES,
+  // The ledger is what the orphan reaper (#1425 B) reads to tell its OWN gate
+  // processes from every other `node` on the host, so it is pinned to the same
+  // root the telemetry is — under the pre-push hook the tree the gate runs in
+  // is deleted seconds later, and the record with it.
+  repoRoot: gateLedgerRoot,
+  commandSignature: buildCommandSignature(gateCommand),
+  // The OWNER the ledger records, from the PROCESS-LOCAL witness only — the same
+  // rule `scripts/lib/quality-gate.mjs` follows for the gate commands it spawns
+  // (`.claude/rules/identity-and-locks.md`: rank witnesses, never union them).
+  // `.orchestrator/session.lock` is deliberately NOT consulted: it is a
+  // repo-GLOBAL artefact any session in this working copy may hold, so reading
+  // it would stamp a PEER's id onto our own gate process and point the orphan
+  // reaper (#1425 B) at the wrong owner. No witness → `null`, which the ledger
+  // records as "owner unknown" — the state every record carried before this.
+  sessionId: [...readProcessLocalSessionIds({ env: process.env, hookInput: null })][0] ?? null,
+  // stdin is IGNORED, not inherited. A gate sub-script reads no stdin, but a
+  // DETACHED child is in its own process group and is therefore not the
+  // terminal's foreground group: the first read from an inherited TTY earns it
+  // SIGTTIN, which stops the whole group until the outer ceiling kills it. An
+  // ignored stdin turns that hang into an immediate EOF.
+  spawnFn: (command, options) => spawn(command, { ...options, stdio: ['ignore', 'pipe', 'inherit'] }),
 });
 
-const gateStdout = typeof result.stdout === 'string' ? result.stdout : '';
-if (gateStdout) process.stdout.write(gateStdout);
-
-if (result.error && typeof result.status !== 'number') {
-  die(`Failed to run gate script: ${result.error.message}`);
+// `pid: -1` is `spawnInGroup`'s spawn-failure channel (it never rejects).
+if (result.pid === -1) {
+  die(`Failed to run gate script: ${result.fullOutput.trim()}`);
 }
 
+// On timeout the child was KILLED before it could write its envelope, so its
+// capture is at best a partial JSON document. Publishing that would hand every
+// stdout consumer a parse error where a named failure belongs; publishing the
+// partial text AND an envelope would break the one-document contract. So the
+// capture goes to stderr, where the operator can still read it, and stdout
+// carries a complete `gate-timeout` envelope instead.
+//
+// The DECISION lives in `publishGateOutcome` (gate-helpers.mjs) and only the
+// WRITES live here: this branch needs a real 16-minute gate to reach, so while
+// the decision was inline it was pinned by nothing.
+const outcome = publishGateOutcome({ result, variant, timeoutMs: gateTimeoutMs });
+const gateStdout = result.timedOut ? '' : result.fullOutput;
+if (outcome.stderr) process.stderr.write(outcome.stderr);
+if (outcome.stdout) process.stdout.write(outcome.stdout);
+for (const line of outcome.warnings) warn(line);
+
 // Quality-gate telemetry — one canonical event per gate run via emitEvent
 // (single emission path). `sessionAttribution` is the shared helper in
 // events.mjs (#941); this CLI wrapper runs against the CWD `repoRoot`, so the
@@ -433,8 +573,7 @@ if (result.error && typeof result.status !== 'number') {
 //
 // Best-effort: a telemetry failure must NEVER alter the gate's authoritative
 // exit code — which is why the counts parse also lives inside this try.
-const exitCode = result.status ?? 1;
-const ledgerRoot = resolveLedgerRoot(ledgerRootArg);
+const exitCode = outcome.exitCode;
 try {
   const counts = suiteCountsFromGateStdout(gateStdout);
   // The names behind `counts.failed`. Absent, never `[]` — see

package/scripts/sweep-expired-rules.mjs

@@ -115,15 +115,25 @@ export function parseArgs(argv) {
   return args;
 }
 
-/** Roll the plan up into the summary both output modes render. */
-function summarize(plan, args, applied) {
+/**
+ * Roll the plan up into the summary both output modes render.
+ *
+ * `header_raises` is additive (#1388 P7): a header-raise is an
+ * `action: 'rewrite'` plan carrying `reason: 'header-raise'`, so it was counted
+ * inside `rewrites` and invisible on the human stdout line although `--json`
+ * always carried `plans[].reason`. It is a SUBSET of `rewrites`, never a
+ * sibling category — the two are deliberately not disjoint.
+ */
+export function summarize(plan, args, applied) {
   const counts = { rewrite: 0, delete: 0, keep: 0 };
   for (const p of plan.plans) counts[p.action] = (counts[p.action] ?? 0) + 1;
+  const headerRaises = plan.plans.filter((p) => p.reason === 'header-raise').length;
   return {
     dry_run: args.dryRun,
     grace_days: args.graceDays,
     files_scanned: plan.plans.length,
     rewrites: counts.rewrite,
+    header_raises: headerRaises,
     deletes: counts.delete,
     keeps: counts.keep,
     expired_entries: plan.plans.reduce((n, p) => n + p.expiredPairIds.length, 0),
@@ -163,7 +173,8 @@ async function main(argv) {
   else {
     process.stdout.write(
       `sweep-expired-rules: ${args.dryRun ? 'dry-run' : 'applied'} — ` +
-        `${summary.files_scanned} generated rule file(s), ${summary.rewrites} rewrite(s), ` +
+        `${summary.files_scanned} generated rule file(s), ${summary.rewrites} rewrite(s) ` +
+        `(${summary.header_raises} header-raise(s)), ` +
         `${summary.deletes} delete(s), ${summary.expired_entries} expired entr(ies), ` +
         `${summary.unresolved_pairs} unresolved pair(s), ${summary.skipped.length} skipped, ` +
         `${summary.malformed_lines} malformed learnings line(s)\n`,

package/scripts/validate-plugin.mjs

@@ -433,6 +433,18 @@ if (runCheck('check-dead-bridge.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-entry-guard.mjs') !== 0) checkFailed = 1;
 
+// BLOCKING (#1422), the complement of the check above: `check-entry-guard`
+// judges the FORM of a guard that already exists, so a registered hook with NO
+// guard at all passes it trivially — the #1393 regression class exactly. This
+// one asks the other half of the question over the union of the four platform
+// manifests: does every registered hook run its entry only under
+// `isMainModule(import.meta.url)` / `invokedAsScript()`, and does no profile
+// gate sit at module top level where its `process.exit(0)` kills a mere
+// importer. Blocking honestly: 27/27 registered hooks were guarded at the
+// moment it landed, because #1393 drained the backlog first.
+process.stdout.write('\n');
+if (runCheck('check-hook-entry-guards.mjs') !== 0) checkFailed = 1;
+
 // FAIL-capable, unlike the WARN-only censuses below: R2+R4 were measured at
 // 1 hit / 1 TP / 0 FP each against the full test corpus, so this check cannot be
 // red on arrival for anything but a real instance of the class. The alternatives

package/scripts/validate-wave-scope.mjs

@@ -69,7 +69,6 @@
  *   2 — I/O error (file not found, unreadable stdin, unreadable sidecar file)
  */
 
-import path from 'node:path';
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { warn } from './lib/common.mjs';
@@ -86,6 +85,17 @@ import {
   // which roles are allowed to grant zero paths.
   isReadOnlyWaveRole,
   READ_ONLY_WAVE_ROLES,
+  // #1398 cond. 4 / #1405 / #1406 — THE grading predicate for an absolute Gate 5b
+  // grant. Lives in scope-gate.mjs so this CLI and `hooks/enforce-scope.mjs`
+  // grade one and the same way (BV-003): before the move, only this CLI could
+  // grade at all, so the hook honoured grants the CLI would have refused and a
+  // manifest that skipped the CLI was never graded.
+  gradeScopeEntry,
+  // #1398 cond. 4 — the `resolve` injection the predicate above takes. Moved
+  // into scope-gate.mjs (from a private copy here) once the hot-path cost was
+  // measured rather than assumed, so this CLI and `hooks/enforce-scope.mjs` pass
+  // the SAME resolver and can no longer reach different verdicts for one grant.
+  canonicalizeGrantPrefix,
   // Aliased: `expandTestSiblings` is ALSO the name of the pre-existing
   // boolean parameter threaded through validate()/assertSubsetOrDie for the
   // #970 flag. Aliasing the import avoids shadowing that parameter rather than
@@ -338,79 +348,6 @@ function validateSessionBinding(obj, errors, warnings) {
   }
 }
 
-/**
- * Literal filesystem-root forms — POSIX "/" and the Windows equivalents "\"
- * and a bare drive root ("C:\", "C:\\", ...). Checked independently of
- * `path.isAbsolute()` because that primitive is platform-native: on a POSIX
- * host (this repo's dev/CI hosts) it never reports `C:\` as absolute, so a
- * Windows-literal-root entry would otherwise slip past every check below.
- * @type {ReadonlySet<string>}
- */
-const FILESYSTEM_ROOT_LITERALS = new Set(['/', '\\']);
-const WINDOWS_DRIVE_ROOT_RE = /^[A-Za-z]:\\+$/;
-
-/**
- * @param {string} entry
- * @returns {boolean}
- */
-function isFilesystemRootLiteral(entry) {
-  return FILESYSTEM_ROOT_LITERALS.has(entry) || WINDOWS_DRIVE_ROOT_RE.test(entry);
-}
-
-/**
- * Well-known top-level system/home directories. A FIXED DENYLIST (not a
- * segment-count threshold): the #792 legitimate grant
- * (`/private/tmp/<session>/scratchpad/**`) is itself a single-segment-deep
- * grant under an unusual root ("private"), so any segment-count heuristic
- * tight enough to catch `/etc/**` risks catching that too, or must be tuned
- * loosely enough to leave a gap. A fixed list of the directories a
- * hallucinated/mis-copied wave-scope entry could plausibly land on is
- * predictable, auditable in a one-line diff, and does not touch legitimate
- * deep grants under any other root.
- * @type {ReadonlySet<string>}
- */
-const DENIED_ABSOLUTE_TOP_SEGMENTS = new Set([
-  'etc',
-  'Users',
-  'home',
-  'root',
-  'bin',
-  'sbin',
-  'usr',
-  'System',
-  'var',
-  'boot',
-  'dev',
-  'proc',
-  'sys',
-  'Library',
-  'Applications',
-  'Windows',
-]);
-
-/**
- * The top-level path segment of an absolute POSIX-style entry (the segment
- * immediately after the leading "/"), if it is on the denylist above.
- * @param {string} entry
- * @returns {string|null}
- */
-function deniedTopSegment(entry) {
-  const first = entry.split('/').filter(Boolean)[0];
-  return first && DENIED_ABSOLUTE_TOP_SEGMENTS.has(first) ? first : null;
-}
-
-/**
- * Does this entry contain a glob wildcard? Mirrors this codebase's own glob
- * convention (`isGlobScopeEntry` in scripts/lib/scope-gate.mjs / #796): `*`
- * is the sole wildcard metachar used in allowedPaths/fileScope entries
- * throughout this repo (no `?`/`[]`/`{}` glob syntax is supported or tested
- * anywhere else in scope-gate.mjs or enforce-scope.mjs).
- * @param {string} entry
- * @returns {boolean}
- */
-function hasWildcard(entry) {
-  return entry.includes('*');
-}
 
 /**
  * Validate allowedPaths array: must exist, be an array of non-empty strings,
@@ -463,37 +400,27 @@ function validateAllowedPaths(obj, errors, warnings) {
       errors.push('allowedPaths contains empty string');
       continue;
     }
-    // #870: an explicit absolute entry is a SANCTIONED out-of-repo grant — mirrors
-    // hooks/enforce-scope.mjs Gate 5b (matchesAbsoluteAllowlist), which honours ANY
-    // syntactically-absolute allowedPaths entry (path.isAbsolute) against the
-    // realpath-resolved write candidate. Using `path.isAbsolute` (not a hand-rolled
-    // `startsWith('/')`) keeps the same platform-native semantics Gate 5b uses.
-    // WARN, not reject — the validator must not contradict the hook it validates
-    // for (#792 / #870) — EXCEPT for the narrow catastrophic subclass below
-    // (#870-followup), which hard-rejects regardless of what Gate 5b would do
-    // with it: pre-flight validation exists precisely to catch a grant this bad
-    // before the hook is ever consulted.
-    if (path.isAbsolute(entry) || isFilesystemRootLiteral(entry)) {
-      if (isFilesystemRootLiteral(entry)) {
-        errors.push(
-          `allowedPaths grants the entire filesystem root: ${entry} — refused unconditionally, this can never be a valid wave scope`,
-        );
-      } else {
-        const denied = deniedTopSegment(entry);
-        if (denied) {
-          errors.push(
-            `allowedPaths contains a well-known system/home directory grant: ${entry} (top-level segment "${denied}" is denylisted) — refused, scope a narrower path instead`,
-          );
-        } else if (!hasWildcard(entry)) {
-          errors.push(
-            `allowedPaths contains a bare absolute file grant with no wildcard: ${entry} — a single concrete out-of-repo file has no established legitimate use in this codebase; scope a glob instead`,
-          );
-        } else {
-          warnings.push(
-            `allowedPaths contains an absolute (out-of-repo) path: ${entry} — honoured by hooks/enforce-scope.mjs Gate 5b; verify this grant is intentional`,
-          );
-        }
-      }
+    // #870 / #1398 / #1405 / #1406 — grade the entry as a Gate 5b grant through
+    // the SHARED predicate (`scripts/lib/scope-gate.mjs` gradeScopeEntry), the
+    // same one `hooks/enforce-scope.mjs` Gate 5b calls. Most absolute entries are
+    // a SANCTIONED out-of-repo grant and only WARN — the validator must not
+    // contradict the hook it validates for (#792/#870) — while the catastrophic
+    // subclasses (filesystem root, denylisted system directory in either its
+    // literal or its canonical spelling, a home grant at or above the user level
+    // or into a credential directory, a tilde that nothing expands, and a
+    // non-canonical prefix Gate 5b can never match) hard-reject here, BEFORE the
+    // hook is ever consulted. `null` = an ordinary relative entry, nothing to say.
+    //
+    // SAME PREDICATE, SAME RESOLVER (#1398 cond. 4). The resolver used to live
+    // here, which made the two callers' ARGUMENT shapes differ and let one grant
+    // reach two verdicts (`/tmp/x/**`: hook `warn`, this CLI `error`). Since the
+    // hot-path cost was measured (+0.067 ms per Gate 5b hit — see
+    // {@link canonicalizeGrantPrefix}) both callers pass this exact function, so
+    // the only remaining asymmetry is the CONSEQUENCE: exit-1 refusal here,
+    // allow-with-notice there.
+    const grade = gradeScopeEntry(entry, { resolve: canonicalizeGrantPrefix });
+    if (grade !== null) {
+      (grade.verdict === 'error' ? errors : warnings).push(`allowedPaths ${grade.message}`);
     }
     // Reject path traversal: any `../` segment. INDEPENDENT of the absolute checks
     // above — an absolute entry that ALSO contains `../` must still be rejected

package/scripts/vault-mirror.mjs

@@ -485,6 +485,10 @@ async function main() {
     kind,
     force,
     vaultName,
+    // #1389: the repo whose `.vault.yaml` declares the namespace slug. This CLI
+    // has no repo-root flag, so it is the invocation cwd — bound ONCE here and
+    // shared by every processor call and the auto-commit below.
+    repoRoot: process.cwd(),
     qualityMinNarrativeChars,
     qualityMinConfidence,
   };
@@ -693,7 +697,11 @@ async function main() {
   // Opt-in: triggers only when --session-id is provided. Callers (session-end, evolve)
   // pass it explicitly; bare invocations stay quiet to preserve legacy behaviour.
   if (!dryRun && !noCommit && sessionIdArg) {
-    autoCommitVaultMirror(resolve(vaultDir), sessionIdArg, resolveRepoNamespace({ vaultName }));
+    autoCommitVaultMirror(
+      resolve(vaultDir),
+      sessionIdArg,
+      resolveRepoNamespace({ vaultName, repoRoot: ctx.repoRoot }),
+    );
   }
 }
 

package/skills/_shared/platform-tools.md

@@ -8,15 +8,17 @@ The current platform is determined by the `scripts/lib/platform.mjs` library:
 - `$SO_PLATFORM` = `claude` | `codex` | `cursor` | `pi`
 - Environment: `$CLAUDE_PLUGIN_ROOT` (Claude Code), `$CODEX_PLUGIN_ROOT` (Codex CLI), `$CURSOR_RULES_DIR` (Cursor IDE), or `$PI_PLUGIN_ROOT` (Pi)
 
-## Identical Tools (no mapping needed)
-
-These tools have the same name and behavior on all platforms. Cursor IDE uses equivalent built-in tools for file operations and terminal commands.
-- **Read** — read file contents
-- **Write** — create/overwrite files
-- **Edit** — string replacement in files
-- **Bash** — execute shell commands
-- **Glob** — file pattern matching
-- **Grep** — content search (ripgrep)
+## File and Shell Tool Adaptation
+
+Skill bodies use Claude Code names as operations, not as a requirement that every
+harness expose those exact tools. Use the current runtime's available tools.
+Measured in Codex Desktop 0.153.4 on 2026-09-19: `exec_command` runs shell
+commands (`cat`, `rg`, `rg --files` for Read/Grep/Glob); `apply_patch` performs
+file edits. These may be exposed through a `functions.exec` tools namespace.
+Never call an unavailable `Read`, `Bash`, or `Skill` tool by name. An instruction
+to invoke `session-orchestrator:<name>` means read and follow the canonical
+`skills/<name>/SKILL.md` relative to the plugin root when no Skill tool exists.
+Keep the user's project as the working directory for project operations.
 
 ## Platform-Specific Tool Mapping
 
@@ -24,7 +26,7 @@ These tools have the same name and behavior on all platforms. Cursor IDE uses eq
 
 | Function | Claude Code | Codex CLI | Cursor IDE | Pi |
 |----------|------------|-----------|------------|----|
-| Present choices to user | `AskUserQuestion` tool with structured options | Numbered Markdown list as plain text, wait for user reply | Numbered Markdown list (same as Codex) | Numbered Markdown list v1; native UI adapter planned |
+| Present choices to user | `AskUserQuestion` tool with structured options | Available native user-input tool, respecting its mode restrictions; plain-text fallback when unavailable | Available native choice tool or numbered Markdown list | Numbered Markdown list v1; native UI adapter planned |
 | Dispatch subagent | `Agent({ description, prompt, subagent_type })` | Native multi-agent collaboration namespace: `spawn_agent`, `list_agents`, `wait_agent`, `send_message`, `followup_task`, `interrupt_agent`, `close_agent`. Measured 2026-08-25 on `codex-cli 0.141.0` — `codex features list` → `multi_agent  stable  true`. | No native in-session Agent tool. Coordinator-side foreign dispatch via the headless `cursor-agent` CLI exists (`scripts/lib/wave-executor/foreign-dispatch.mjs`, #1150) — measured 2026-08-25 on `cursor-agent 2026.08.11-e8db854`. | Sequential execution v1. Do not assume native subagents until the Pi SDK dispatcher exists. |
 | Track tasks | `TaskCreate` / `TaskUpdate` / `TaskList` | Plain-text checklist in response context | Plain-text checklist (same as Codex) | Plain-text checklist (same as Codex) |
 | Enter plan mode | `EnterPlanMode` / `ExitPlanMode` tools | `/plan` slash command (prompt-level, not tool-based) | Instruction-based: "Focus on analysis and planning. Do not modify files until the user approves." | `/plan` prompt template; use instruction-based planning when tool mode is unavailable |
@@ -37,7 +39,13 @@ When a skill instructs "Use the AskUserQuestion tool", apply this pattern:
 
 **On Claude Code:** Use the AskUserQuestion tool with structured options as documented.
 
-**On Codex CLI / Cursor IDE / Pi:** Present the same choices as a numbered Markdown list and ask the user to respond:
+**On Codex:** Prefer the available native user-input tool. In the measured Desktop
+0.153.4 runtime (2026-09-19), `request_user_input_async` allows a question while
+independent work continues; `request_user_input` has mode restrictions. Follow
+the live tool contract. Existing user authorization remains valid; do not ask
+again merely because a workflow names `AskUserQuestion`.
+
+**When no suitable native tool is available (including Cursor IDE / Pi):** Present the same choices as a numbered Markdown list and ask the user to respond:
 ```
 Choose one:
 1. Option A — description
@@ -85,6 +93,10 @@ No Session Orchestrator Pi subagent dispatcher exists in v1. Execute wave tasks
 
 Skills use `model-preference` (Claude), `model-preference-codex` (Codex), `model-preference-cursor` (Cursor), and active-model fallback on Pi in YAML frontmatter.
 
+These are preferences, not authority to replace a user's selected model,
+reasoning effort, or service tier. Preserve the current settings unless the user
+requests a change; inherit them for native subagents.
+
 ## State Directory
 
 - **Claude Code:** `.claude/` (STATE.md, wave-scope.json)