session-orchestrator 5.1.0 → 5.3.0

package/scripts/release.mjs

@@ -356,7 +356,7 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
   'templates/python-uv/tests/test_sanity.py',
 ]);
 
-// `commands/release.md` quotes the `npm view` OUTPUT that proves the 3.18.0 gap,
+// `skills/release/SKILL.md` quotes the `npm view` OUTPUT that proves the 3.18.0 gap,
 // dated at the line. Bumping it would destroy the evidence it exists to carry —
 // the registry state on that date is the whole point of the paragraph.
 //
@@ -384,7 +384,10 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
 // September 10 campaign snapshot: inputs and receipt reproduce the dated 4.3-planned
 // render made while 4.2.0 was current. Exact files only; neighboring marketing
 // remains checked. Do not bump receipt props without a newly reviewed render.
-export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|commands\/release\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
+// `scripts/lib/locks/index.mjs` is the one-cycle deprecation shim (5.2.0 CHANGELOG, Changed): its
+// runtime warning names the version it was deprecated IN, so it legitimately carries the previous
+// release literal until its 6.0.0 removal — version history by construction, not drift.
+export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|scripts\/lib\/locks\/index\.mjs|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|skills\/release\/SKILL\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
 
 /** Pure check over packed-entry lines. Returns violations: {name, line}[]. */
 export function checkLeakage(lines) {
@@ -881,14 +884,36 @@ export function evaluateNpmAuth(whoami) {
  * never found out". Only an actual `status: 'green'` reading passes; a release
  * must never proceed on an unknown CI state.
  *
- * @param {null | {status?: string, failingJobName?: string, degraded?: string}} ci
+ * The row also carries the CAUSE the probe already knows, because the three
+ * ways this row goes red are indistinguishable without it (#1384 P5): a short
+ * `sha`, a commit the mirror has never seen, and a HEAD with no pipeline all
+ * printed `CI status unknown (query-failed)` / `status: unknown`. The probe's
+ * `detail` (degraded branch, `degradedResult`) and `details.reason` /
+ * `failingJobName` (read branch, `sanitizeApiText`) are clamped and
+ * control-byte-escaped AT THEIR GENERATION in `ci-status-banner.mjs` —
+ * appended here, never re-formatted. That escaping is load-bearing, not
+ * hygiene: the read branch interpolates a RAW API `status` value into
+ * `reason`, and until #1384 f-4 a status carrying `\r` + an ANSI sequence
+ * could repaint THIS row green while its verdict stayed `ok:false`. Do not
+ * append a further probe field here without checking it goes through one of
+ * those two. With neither present the text is byte-identical to
+ * before, so a plain green or a named failing job reads exactly as it did.
+ *
+ * @param {null | {status?: string, failingJobName?: string, degraded?: string,
+ *   detail?: string, details?: {reason?: string}}} ci
  * @returns {{ok: boolean, detail: string}}
  */
 export function evaluateCiRow(ci) {
   if (ci === null || ci === undefined) return { ok: false, detail: 'CI status unavailable' };
-  if (ci.degraded) return { ok: false, detail: `CI status unknown (${ci.degraded})` };
-  const job = ci.failingJobName ? ` (${ci.failingJobName})` : '';
-  return { ok: ci.status === 'green', detail: `status: ${ci.status}${job}` };
+  if (ci.degraded) {
+    const why = ci.detail ? `: ${ci.detail}` : '';
+    return { ok: false, detail: `CI status unknown (${ci.degraded}${why})` };
+  }
+  // A failing job NAMES the failure, so it wins over the generic reason;
+  // `reason` is what fills the gap when there is no job to name (`unknown`).
+  const reason = ci.failingJobName || ci.details?.reason || '';
+  const why = reason ? ` (${reason})` : '';
+  return { ok: ci.status === 'green', detail: `status: ${ci.status}${why}` };
 }
 
 /**
@@ -908,6 +933,11 @@ export function evaluateCiRow(ci) {
  * "we could not read the mirror" is not "the mirror is green" (the fail-closed
  * house rule at the top of this file).
  *
+ * This function only judges the `ci` reading it is handed — it is
+ * `evaluateCiPreflightRows` (the caller, see its own docblock) that fetches
+ * `ci` for the commit actually being released, rather than whichever HEAD the
+ * GitHub mirror itself reports.
+ *
  * @param {string|undefined} repoSpec — `resolveRepoSpec({vcs:'github'})`, undefined when no github remote resolves
  * @param {null | {status?: string, failingJobName?: string, degraded?: string}} ci
  * @returns {{ok: boolean, detail: string}}
@@ -969,6 +999,62 @@ function readPackageVersion(repoRoot) {
   return JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')).version;
 }
 
+/**
+ * Both CI preflight rows (`ci-green-on-head` + `ci-green-on-head-github`) for
+ * ONE commit — the commit actually about to be released — never whichever
+ * HEAD the queried platform happens to report.
+ *
+ * Before this function existed, neither `checkCiStatus` call below passed
+ * `sha`, so the GitHub branch fell back to `commits/HEAD` — the MIRROR's own
+ * default-branch head, which is the release commit only once `head-pushed-github`
+ * has ALREADY proven `github/main == local HEAD`. A release cut before that
+ * push landed asked GitHub about a commit that was never pushed and could read
+ * green for work GitHub has not seen at all (measured 2026-09-16 for
+ * `3ebf0e9d`). The GitLab branch was already correct by default (`deps.sha ??
+ * getHeadSha(repoRoot)`), so only the two call sites below needed the fix —
+ * see `checkCiStatus`'s own docblock in `ci-status-banner.mjs` for the `sha`
+ * contract (#1332).
+ *
+ * Factored out of `preflight()` as its own async, DI-testable unit:
+ * `checkCiStatus` reaches the network by default, and `preflight()`'s
+ * surrounding checks (git, npm) are not test-doubled, so this is the seam
+ * through which the `sha` wiring can be unit-tested without spinning up a
+ * full fixture release.
+ *
+ * @param {string} repoRoot
+ * @param {string} head - full hex commit id of the commit being released (the
+ *   local HEAD `preflight()` already computed for the remote-parity rows).
+ * @param {{
+ *   skipCi?: boolean,
+ *   checkCiStatus?: Function,
+ *   resolveRepoSpec?: (opts: { repoRoot: string, vcs: 'github' }) => string|undefined,
+ * }} [deps]
+ * @returns {Promise<{ gitlab: {ok: boolean, detail: string}, github: {ok: boolean, detail: string} }>}
+ */
+export async function evaluateCiPreflightRows(repoRoot, head, {
+  skipCi = false,
+  checkCiStatus: checkCiStatusDep,
+  resolveRepoSpec: resolveRepoSpecDep = resolveRepoSpec,
+} = {}) {
+  if (skipCi) {
+    const skipped = { ok: true, detail: 'SKIPPED via --skip-ci' };
+    return { gitlab: skipped, github: skipped };
+  }
+  const checkCiStatusImpl = checkCiStatusDep ?? (await import('./lib/ci-status-banner.mjs')).checkCiStatus;
+
+  const ci = await checkCiStatusImpl({ repoRoot, timeoutMs: 15000, sha: head });
+  const gitlab = evaluateCiRow(ci);
+
+  const githubSpec = resolveRepoSpecDep({ repoRoot, vcs: 'github' });
+  let githubCi = null;
+  if (githubSpec) {
+    githubCi = await checkCiStatusImpl({ repoRoot, vcs: 'github', timeoutMs: 15000, sha: head });
+  }
+  const github = evaluateGithubCiRow(githubSpec, githubCi);
+
+  return { gitlab, github };
+}
+
 async function preflight(repoRoot, target, { skipCi = false } = {}) {
   const checks = [];
   const add = (name, ok, detail = '') => checks.push({ name, ok, detail });
@@ -1098,39 +1184,23 @@ async function preflight(repoRoot, target, { skipCi = false } = {}) {
     add('npm-token-live', false, err.message);
   }
 
-  // 6. CI green on HEAD (the repo's iron session-start rule applies to
-  // releases doubly: local green is not evidence — see .claude/rules).
-  // --skip-ci is refused under --publish upstream in validateFlags(); it can
-  // only reach this branch from --check.
-  if (skipCi) {
-    add('ci-green-on-head', true, 'SKIPPED via --skip-ci');
-  } else {
-    const { checkCiStatus } = await import('./lib/ci-status-banner.mjs');
-    const ci = await checkCiStatus({ repoRoot, timeoutMs: 15000 });
-    const row = evaluateCiRow(ci);
-    add('ci-green-on-head', row.ok, row.detail);
-  }
-
-  // 6b. CI green on the GitHub mirror too. The row above asks the platform
-  // `detectVcsFamily` picks for `origin` (GitLab), whose pipeline is Linux-only;
-  // the macOS matrix leg lives exclusively in `.github/workflows/test.yml`.
-  // `vcs: 'github'` forces the probe onto the mirror without touching the
-  // detection order. The GitHub check-runs path reads `commits/HEAD`, i.e. the
-  // mirror's default-branch head — which is HEAD only because `head-pushed-github`
-  // above proves github/main == local HEAD; that row is this one's precondition,
-  // not a duplicate of it.
-  if (skipCi) {
-    add('ci-green-on-head-github', true, 'SKIPPED via --skip-ci');
-  } else {
-    const githubSpec = resolveRepoSpec({ repoRoot, vcs: 'github' });
-    let githubCi = null;
-    if (githubSpec) {
-      const { checkCiStatus } = await import('./lib/ci-status-banner.mjs');
-      githubCi = await checkCiStatus({ repoRoot, vcs: 'github', timeoutMs: 15000 });
-    }
-    const row = evaluateGithubCiRow(githubSpec, githubCi);
-    add('ci-green-on-head-github', row.ok, row.detail);
-  }
+  // 6/6b. CI green on HEAD, both platforms — judged for the commit actually
+  // being released, never whichever HEAD the queried platform reports (see
+  // evaluateCiPreflightRows's docblock for the `sha`-wiring history, #1332).
+  //
+  // GitLab: the repo's iron session-start rule applies to releases doubly —
+  // local green is not evidence — see .claude/rules. GitHub: this second row
+  // exists because `detectVcsFamily` picks `origin` (GitLab) for the row
+  // above, whose pipeline is Linux-only; the macOS matrix leg lives
+  // exclusively in `.github/workflows/test.yml`. `vcs: 'github'` forces the
+  // probe onto the mirror without touching the detection order.
+  // SELF-DISABLING: a checkout with no `github` remote has no mirror to be
+  // red, so `evaluateGithubCiRow` reports `skipped` rather than red — see its
+  // own docblock. --skip-ci is refused under --publish upstream in
+  // validateFlags(); it can only reach this branch from --check.
+  const ciRows = await evaluateCiPreflightRows(repoRoot, head, { skipCi });
+  add('ci-green-on-head', ciRows.gitlab.ok, ciRows.gitlab.detail);
+  add('ci-green-on-head-github', ciRows.github.ok, ciRows.github.detail);
 
   // 7. Leakage gate over the actual pack file list.
   // `npm_config_loglevel` is INHERITED, and `npm pack --dry-run` writes its whole

package/scripts/relocate-vault-corpus.mjs

@@ -40,7 +40,6 @@
 
 import { promises as fs, existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
 import path from 'node:path';
 import {
   loadVaultRelocationRules,
@@ -55,6 +54,7 @@ import {
 } from './lib/vault-relocation-rules.mjs';
 import { buildBackfillIndex, parseSessionId } from './lib/vault-repo-backfill.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -1158,8 +1158,7 @@ async function main() {
 // Entry guard (run only when invoked directly)
 // ---------------------------------------------------------------------------
 
-const invokedDirectly =
-  process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly =isMainModule(import.meta.url);
 
 if (invokedDirectly) {
   main().catch((err) => {

package/scripts/repair-invalid-sessions.mjs

@@ -37,10 +37,10 @@
 import fs from 'node:fs';
 import { parseArgs } from 'node:util';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 import { repairLedger, CANONICAL_LEDGER_REL } from './lib/session-record-repair.mjs';
 import { getProjectDir } from './lib/platform.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const USAGE =
   'Usage: node scripts/repair-invalid-sessions.mjs [--dry-run|--apply] [--json]\n' +
@@ -200,7 +200,7 @@ async function main() {
   process.exit(summary.ok === false ? 3 : 0);
 }
 
-const isDirectRun = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+const isDirectRun =isMainModule(import.meta.url);
 if (isDirectRun) {
   main().catch((err) => {
     process.stderr.write(`repair-invalid-sessions: unexpected error: ${err?.stack ?? err}\n`);

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/session-shape.mjs

@@ -42,10 +42,10 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
-import { fileURLToPath } from 'node:url';
 import { resolveInstructionFile } from './lib/common.mjs';
 import { parseSessionConfig } from './lib/config.mjs';
 import { resolveAndRecordSessionShape } from './lib/session-shape.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const USAGE = [
   'Usage: node scripts/session-shape.mjs --repo-root <path> --session-type <housekeeping|feature|deep>',
@@ -258,7 +258,7 @@ async function main() {
 }
 
 // Entrypoint guard — importing this file must not run it (check-unwired-features S3).
-if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+if (isMainModule(import.meta.url)) {
   main().catch((err) => {
     process.stderr.write(`session-shape: unexpected error: ${err?.stack ?? err}\n`);
     process.exit(EXIT_CONFIG_IO);

package/scripts/site-numbers.mjs

@@ -101,10 +101,11 @@
 import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join, resolve, relative } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
 
 import { writeStdoutLineSync, writeJsonAtomicSync } from './lib/io.mjs';
 import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+import { slashCommandNames } from './lib/user-invocable-skills.mjs';
 
 /** Machine-readable schema tag for the --json envelope. */
 export const SCHEMA = 'site-numbers/1';
@@ -169,11 +170,37 @@ export function countSkills(root) {
   return n;
 }
 
-/** `ls commands/*.md | wc -l` — same basis as checker.mjs `command-count`. */
+/**
+ * The product's "slash commands" number: `commands/*.md` ∪ skills carrying an
+ * EXPLICIT `user-invocable: true`, deduplicated by name.
+ *
+ * NOT `ls commands/*.md | wc -l` any more, and the change is not cosmetic. After
+ * the 2026-09-16 fold (#1370) `commands/` holds two files — `session` and
+ * `templates-ack`, the only two names a skill cannot carry — while 26 operator-
+ * facing slash commands exist. A command file only ever resolved because a
+ * same-named skill existed, and the twin additionally listed the entry twice in
+ * the `/` picker; the skill frontmatter flag is what makes a slash command a
+ * slash command now. Counting the directory would have reported 2.
+ *
+ * Dedup by name is load-bearing: a name present on BOTH sides is the picker-
+ * duplicate defect (`tests/commands/headless-bare-command-availability.test.mjs`
+ * fails on it), so it must count once here rather than inflate the tile.
+ *
+ * null (→ the tile renders as unmeasured) only when NEITHER `commands/` nor
+ * `skills/` exists — i.e. this is not a plugin tree at all. A tree with one of
+ * the two counts what it has; a missing `commands/` is now the NORMAL state, not
+ * a missing measurement.
+ *
+ * NO divergence from `skills/claude-md-drift-check/checker.mjs` `command-count`:
+ * that checker unions the same user-invocable skills (`checker.mjs:435-446`,
+ * measured 2026-09-17), and both routes reach the same verdict through the same
+ * SSOT — `isUserInvocableValue` in `scripts/lib/user-invocable-skills.mjs`. The
+ * checker stays GENERIC over consumer repos only in the sense that a repo
+ * without `skills/` sees the union collapse to the directory count on its own.
+ */
 export function countCommands(root) {
-  const dir = join(root, 'commands');
-  if (!isDir(dir)) return null;
-  return readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('.')).length;
+  if (!isDir(join(root, 'commands')) && !isDir(join(root, 'skills'))) return null;
+  return slashCommandNames(root).length;
 }
 
 /**
@@ -400,7 +427,8 @@ export const METRIC_DEFS = Object.freeze([
   {
     id: 'commands',
     provenance: false,
-    source: 'ls commands/*.md | wc -l',
+    source:
+      'ls commands/*.md | wc -l  +  grep -l "^user-invocable: true" skills/*/SKILL.md | wc -l   (union by name — see countCommands)',
     compute: (root) => fmtCount(countCommands(root)),
   },
   {
@@ -1398,11 +1426,7 @@ export function main(argv = process.argv.slice(2), env = {}) {
   return exitCode;
 }
 
-const isMain =
-  typeof process !== 'undefined' &&
-  process.argv[1] !== null &&
-  process.argv[1] !== undefined &&
-  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+const isMain =isMainModule(import.meta.url);
 
 if (isMain) {
   const argv = process.argv.slice(2);