session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/gates/gate-baseline.mjs

@@ -10,6 +10,31 @@ import { runCheck } from './gate-helpers.mjs';
 const typecheckCmd = process.env.TYPECHECK_CMD;
 const testCmd = process.env.TEST_CMD;
 
+/**
+ * Per-command wall-clock ceiling, published by `scripts/run-quality-gate.mjs`
+ * as `GATE_TIMEOUT_MS` (#1425 A3 / #1432). It carries the ALREADY-RESOLVED
+ * value — operator override `SO_GATE_TIMEOUT_MS` > Session Config
+ * `gate.timeout-path-b-ms` > 900 000 — so this script only has to read it.
+ *
+ * Absent or non-numeric (this gate invoked directly, not through the wrapper)
+ * → the option is OMITTED, and `runCheck` falls back to `resolveGateTimeoutMs()`
+ * exactly as before. An empty object is deliberate: passing `timeoutMs:
+ * undefined` would NOT trigger that fallback in every spread order.
+ */
+const CHECK_OPTS = (() => {
+  const raw = Number((process.env.GATE_TIMEOUT_MS || '').trim());
+  const opts = Number.isFinite(raw) && raw > 0 ? { timeoutMs: raw } : {};
+  // GATE_LEDGER_ROOT (#1425 A4, W5 fix-pass): the wrapper publishes the ledger
+  // root it resolved (--ledger-root > repo root) so the gate-process register
+  // is written where the WRAPPER decided, not where this sub-script happens to
+  // run. Without it every runCheck() here defaulted to process.cwd(), and a test
+  // that spawned this script from the checkout wrote real lines into the live
+  // .orchestrator/runtime/gate-processes.jsonl — the reaper's kill population.
+  const ledgerRoot = (process.env.GATE_LEDGER_ROOT || "").trim();
+  if (ledgerRoot && ledgerRoot.startsWith("/")) opts.repoRoot = ledgerRoot;
+  return opts;
+})();
+
 if (!typecheckCmd) {
   process.stderr.write('TYPECHECK_CMD must be set\n');
   process.exit(1);
@@ -23,11 +48,11 @@ let tcResult = { status: 'skip', output: '' };
 let testResult = { status: 'skip', output: '' };
 
 if (typecheckCmd !== 'skip') {
-  tcResult = await runCheck(typecheckCmd);
+  tcResult = await runCheck(typecheckCmd, CHECK_OPTS);
 }
 
 if (testCmd !== 'skip') {
-  testResult = await runCheck(testCmd);
+  testResult = await runCheck(testCmd, CHECK_OPTS);
 }
 
 const result = {

package/scripts/lib/gates/gate-full.mjs

@@ -18,6 +18,31 @@ const testCmd = process.env.TEST_CMD;
 const lintCmd = process.env.LINT_CMD;
 const sessionStartRef = process.env.SESSION_START_REF ?? '';
 
+/**
+ * Per-command wall-clock ceiling, published by `scripts/run-quality-gate.mjs`
+ * as `GATE_TIMEOUT_MS` (#1425 A3 / #1432). It carries the ALREADY-RESOLVED
+ * value — operator override `SO_GATE_TIMEOUT_MS` > Session Config
+ * `gate.timeout-path-b-ms` > 900 000 — so this script only has to read it.
+ *
+ * Absent or non-numeric (this gate invoked directly, not through the wrapper)
+ * → the option is OMITTED, and `runCheck` falls back to `resolveGateTimeoutMs()`
+ * exactly as before. An empty object is deliberate: passing `timeoutMs:
+ * undefined` would NOT trigger that fallback in every spread order.
+ */
+const CHECK_OPTS = (() => {
+  const raw = Number((process.env.GATE_TIMEOUT_MS || '').trim());
+  const opts = Number.isFinite(raw) && raw > 0 ? { timeoutMs: raw } : {};
+  // GATE_LEDGER_ROOT (#1425 A4, W5 fix-pass): the wrapper publishes the ledger
+  // root it resolved (--ledger-root > repo root) so the gate-process register
+  // is written where the WRAPPER decided, not where this sub-script happens to
+  // run. Without it every runCheck() here defaulted to process.cwd(), and a test
+  // that spawned this script from the checkout wrote real lines into the live
+  // .orchestrator/runtime/gate-processes.jsonl — the reaper's kill population.
+  const ledgerRoot = (process.env.GATE_LEDGER_ROOT || "").trim();
+  if (ledgerRoot && ledgerRoot.startsWith("/")) opts.repoRoot = ledgerRoot;
+  return opts;
+})();
+
 if (!typecheckCmd) {
   process.stderr.write('TYPECHECK_CMD must be set\n');
   process.exit(1);
@@ -34,7 +59,7 @@ if (!lintCmd) {
 const startTime = Date.now();
 
 // --- Typecheck ---
-const tcResult = runCheck(typecheckCmd);
+const tcResult = await runCheck(typecheckCmd, CHECK_OPTS);
 const tcErrorCount =
   tcResult.status === 'fail'
     ? extractCount(tcResult.fullOutput ?? tcResult.output, /error TS\d+/)
@@ -44,7 +69,7 @@ const tcErrorCount =
 // NOTE: `testCounts`, NOT `failed` — a local `failed` is already bound near
 // the bottom of this file and drives `process.exit(failed ? 2 : 0)`.
 // Shadowing it would corrupt the gate's exit code.
-const testResult = runCheck(testCmd);
+const testResult = await runCheck(testCmd, CHECK_OPTS);
 const testCounts =
   testResult.status !== 'skip'
     ? extractTestCounts(testResult.fullOutput ?? testResult.output)
@@ -98,7 +123,7 @@ const fileFields = testCounts.files
   : {};
 
 // --- Lint ---
-const lintResult = runCheck(lintCmd);
+const lintResult = await runCheck(lintCmd, CHECK_OPTS);
 const lintWarnings =
   lintResult.status !== 'skip'
     ? extractCount(lintResult.fullOutput ?? lintResult.output, /warning/i)

package/scripts/lib/gates/gate-helpers.mjs

@@ -8,10 +8,176 @@
 
 import { execSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
+
+import {
+  DEFAULT_GATE_TIMEOUT_MS,
+  buildCommandSignature,
+  spawnInGroup,
+} from '../process-group.mjs';
 import { detectStubCommand } from './echo-stub-detect.mjs';
 
 const RUN_CHECK_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
 
+/** Lines of captured output kept in the human-facing `output` tail. */
+const OUTPUT_TAIL_LINES = 5;
+
+/**
+ * Name of the per-invocation override for the gate wall-clock ceiling.
+ *
+ * Read at CALL time, never at module load, so a test (or a caller that sets it
+ * for one child) is not defeated by import order.
+ *
+ * Named ceiling (BV-004): this is an ENV var, and an env var is inherited by
+ * every descendant — the exact shape that made `SO_GATE_LEDGER_ROOT` reach
+ * every vitest worker on 2026-09-06 (`scripts/run-quality-gate.mjs`, the
+ * `--ledger-root` block). It is acceptable here only because the value is a
+ * CEILING every descendant should honour anyway. A future Session-Config
+ * wiring of `gate.timeout-path-b-ms` should prefer the explicit `timeoutMs`
+ * option below — which reaches exactly one call — over exporting this name.
+ */
+export const GATE_TIMEOUT_ENV = 'SO_GATE_TIMEOUT_MS';
+
+/**
+ * The wall-clock ceiling one gate command is allowed, in ms.
+ *
+ * Precedence: `process.env.SO_GATE_TIMEOUT_MS` when set to a finite positive
+ * number, else {@link DEFAULT_GATE_TIMEOUT_MS} (900_000 — the PRD's
+ * `gate.timeout-path-b-ms`, deliberately the same 15 min the synchronous
+ * path A already had, so both gate paths are allowed exactly as long).
+ *
+ * A non-numeric or non-positive value is IGNORED rather than honoured: a typo
+ * that parsed as 0 would disable the cap, which is the failure this whole
+ * change exists to remove.
+ *
+ * @returns {number} positive milliseconds
+ */
+export function resolveGateTimeoutMs() {
+  const raw = (process.env[GATE_TIMEOUT_ENV] || '').trim();
+  if (!raw) return DEFAULT_GATE_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_GATE_TIMEOUT_MS;
+  return parsed;
+}
+
+/**
+ * Last {@link OUTPUT_TAIL_LINES} lines of a captured text, trimmed.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function tailOf(text) {
+  return String(text ?? '').split('\n').slice(-OUTPUT_TAIL_LINES).join('\n').trim();
+}
+
+/**
+ * The one line a timed-out gate command MUST carry.
+ *
+ * A timeout is a FAILURE with a name, never a silent `fail`: without this line
+ * a killed command is indistinguishable in the envelope from a command that
+ * exited non-zero on its own, and the operator has nothing to act on. It names
+ * the ceiling that fired, the process GROUP that was signalled, the ladder that
+ * ran, and — the part an exit code can never carry — anything that SURVIVED
+ * SIGKILL (PRD B6: a sent signal proves nothing).
+ *
+ * @param {number} timeoutMs
+ * @param {{pgid: number, killSignals: string[], survivors: number[]}} run
+ * @returns {string}
+ */
+function timeoutLine(timeoutMs, run) {
+  const ladder = (run.killSignals ?? []).join('\u2192') || 'no signal sent';
+  return `gate: TIMEOUT after ${timeoutMs} ms \u2014 process group ${run.pgid} ${ladder}, `
+    + `survivors: [${(run.survivors ?? []).join(', ')}]`;
+}
+
+/**
+ * The stdout envelope `scripts/run-quality-gate.mjs` publishes when the GATE
+ * SUB-SCRIPT itself was killed on the wall-clock ceiling.
+ *
+ * Lives here, beside the other envelope helpers, because the CLI that consumes
+ * it is a top-level script with no exports — a pure function there would be
+ * untestable without executing the CLI.
+ *
+ * Deliberately carries no `test`/`typecheck`/`lint` object: a killed gate
+ * measured nothing, and `suiteCountsFromGateStdout` must return `null` for it
+ * (absent is not zero). `error: 'gate-timeout'` is the machine-readable
+ * discriminator; the exit code is 124, the same value `spawnInGroup` reports
+ * and the same one coreutils `timeout(1)` uses.
+ *
+ * @param {object} args
+ * @param {string} args.variant  The `--variant` value the run was started with.
+ * @param {number} args.timeoutMs  Ceiling that fired.
+ * @param {{pgid: number, durationMs: number, killSignals: string[], survivors: number[]}} args.run
+ *   The {@link spawnInGroup} result.
+ * @returns {{variant: string, error: 'gate-timeout', timeout_ms: number, duration_ms: number,
+ *   pgid: number, kill_signals: string[], survivors: number[]}}
+ */
+export function gateTimeoutEnvelope({ variant, timeoutMs, run }) {
+  return {
+    variant,
+    error: 'gate-timeout',
+    timeout_ms: timeoutMs,
+    duration_ms: run?.durationMs ?? 0,
+    pgid: run?.pgid ?? -1,
+    kill_signals: run?.killSignals ?? [],
+    survivors: run?.survivors ?? [],
+  };
+}
+
+/**
+ * Decide WHAT a finished gate sub-script run publishes — stdout, stderr,
+ * exit code and operator warnings — without performing any of the writes.
+ *
+ * ## Why this is a pure function and not four `process.*.write` calls
+ *
+ * The timeout branch in `scripts/run-quality-gate.mjs` was unreachable by any
+ * test: reaching it required a REAL gate sub-script to exceed
+ * `resolveGateTimeoutMs() + GATE_OUTER_TIMEOUT_RESERVE_MS` (15 min + 60 s, a
+ * hard constant with no injection seam), so the four decisions it makes —
+ * suppress the partial capture on stdout, re-publish it on stderr, emit ONE
+ * complete `gate-timeout` envelope, warn about survivors — were pinned by
+ * nothing. The CLI now decides here and only WRITES there, so each decision is
+ * testable against a synthetic {@link spawnInGroup} result.
+ *
+ * ## The one-document contract on stdout
+ *
+ * A killed child never wrote its envelope, so its capture is at best a partial
+ * JSON document. Publishing that hands every stdout consumer a parse error
+ * where a named failure belongs; publishing BOTH the partial text and an
+ * envelope breaks the "one JSON document" contract. Hence: capture → stderr,
+ * envelope → stdout, and `stdout` carries EXACTLY the envelope line.
+ *
+ * @param {object} args
+ * @param {{fullOutput?: string, exitCode?: number, timedOut?: boolean, pgid?: number,
+ *   durationMs?: number, killSignals?: string[], survivors?: number[]}} args.result
+ *   The {@link spawnInGroup} result for the gate sub-script.
+ * @param {string} args.variant  The `--variant` value the run was started with.
+ * @param {number} args.timeoutMs  The OUTER ceiling that applied to the sub-script.
+ * @returns {{stdout: string, stderr: string, exitCode: number, warnings: string[]}}
+ *   `stdout`/`stderr` are written verbatim (empty string = write nothing);
+ *   `warnings` go through the caller's `warn()`; `exitCode` is the gate's own,
+ *   which `spawnInGroup` reports as 124 on the timeout path.
+ */
+export function publishGateOutcome({ result, variant, timeoutMs }) {
+  const capture = String(result?.fullOutput ?? '');
+  const exitCode = result?.exitCode ?? 0;
+
+  if (!result?.timedOut) {
+    return { stdout: capture, stderr: '', exitCode, warnings: [] };
+  }
+
+  const survivors = result.survivors ?? [];
+  return {
+    stdout: `${JSON.stringify(gateTimeoutEnvelope({ variant, timeoutMs, run: result }))}\n`,
+    stderr: capture.trim()
+      ? `\n\u2500\u2500\u2500\u2500 gate TIMED OUT \u2014 captured output before the kill \u2500\u2500\u2500\u2500\n${capture}\n\u2500\u2500\u2500\u2500 end \u2500\u2500\u2500\u2500\n`
+      : '',
+    exitCode,
+    warnings: survivors.length > 0
+      ? [`gate process group ${result.pgid} left survivors after SIGKILL: ${survivors.join(', ')}`]
+      : [],
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Internal pattern helpers
 // ---------------------------------------------------------------------------
@@ -39,7 +205,8 @@ function isTestFile(filePath) {
 // ---------------------------------------------------------------------------
 
 /**
- * Execute a shell command and return a structured result.
+ * Execute a shell command as the LEADER OF ITS OWN PROCESS GROUP, under a
+ * wall-clock ceiling, and return a structured result.
  *
  * `output` is a bounded TAIL for humans. `fullOutput` is the complete captured
  * text and is what every COUNT parse must read.
@@ -52,10 +219,47 @@ function isTestFile(filePath) {
  * "the runner never produced results" and hides WHICH test failed. An hour was
  * spent chasing that phantom before the real cause (one red test) was found.
  *
+ * ## Why a process group, and why a timeout (Epic #1425 A3)
+ *
+ * This used to be `execSync(cmd, { maxBuffer })` — no timeout at all, and the
+ * shell as the only signalled process. On 2026-09-20 four `tsgo --noEmit`
+ * grandchildren of gate runs outlived their parents at PPID 1 with up to 8.0 GB
+ * RSS each and took the host to 13 % free memory. {@link spawnInGroup} spawns
+ * `detached`, so `process.kill(-pgid, …)` reaches every descendant, and it runs
+ * the SIGTERM→grace→SIGKILL ladder with a read-back verification.
+ *
+ * ## What changed for callers
+ *
+ * 1. It is ASYNC. Every call site must `await`.
+ * 2. `fullOutput` now interleaves stdout AND stderr on the PASS path too
+ *    (`execSync` discarded stderr when the command succeeded). A runner that
+ *    prints its summary to stderr is therefore no longer invisible to
+ *    {@link extractTestCounts}.
+ * 3. Three fields are added — `timedOut`, `killSignals`, `survivors` — and they
+ *    are present ONLY when a process actually ran. A skipped or stubbed command
+ *    spawned nothing, so it carries no `timedOut: false`: absent is not a
+ *    measured false, the same contract `counts` and `files` already keep.
+ *
+ * A timeout is a REPORTED failure: `status: 'fail'`, `exitCode: 124`, and a
+ * `gate: TIMEOUT after …` line appended to `output`/`fullOutput` naming the
+ * ceiling, the group, the signal ladder and any survivor. It is never a silent
+ * `fail`.
+ *
  * @param {string} cmd - Shell command to run, or `"skip"` / empty to skip.
- * @returns {{ status: 'pass'|'fail'|'skip', output: string, fullOutput: string, exitCode: number, stubbed?: { kind: 'echo'|'noop' } }}
+ * @param {object} [opts] - Forwarded verbatim to {@link spawnInGroup}, and it
+ *   OVERRIDES the defaults below (`timeoutMs`, `maxOutputBytes`, `repoRoot`,
+ *   `commandSignature`). This is also the seam tests inject `spawnFn` /
+ *   `killFn` / `isAliveFn` through.
+ * @param {number|null} [opts.timeoutMs] - Wall-clock ceiling; defaults to
+ *   {@link resolveGateTimeoutMs} (`SO_GATE_TIMEOUT_MS` or 900_000). `null`
+ *   disables the clock — the byte cap still applies.
+ * @param {string} [opts.repoRoot] - Root whose gate-process ledger the spawn is
+ *   recorded in; defaults to `process.cwd()`, which is the tree under test.
+ * @returns {Promise<{ status: 'pass'|'fail'|'skip', output: string, fullOutput: string,
+ *   exitCode: number, timedOut?: boolean, killSignals?: string[], survivors?: number[],
+ *   stubbed?: { kind: 'echo'|'noop' } }>}
  */
-export function runCheck(cmd) {
+export async function runCheck(cmd, opts = {}) {
   if (!cmd || cmd === 'skip') {
     return { status: 'skip', output: '', fullOutput: '', exitCode: 0 };
   }
@@ -65,26 +269,44 @@ export function runCheck(cmd) {
     return { status: 'pass', output: `(stubbed: ${stub.kind})`, fullOutput: `(stubbed: ${stub.kind})`, exitCode: 0, stubbed: { kind: stub.kind } };
   }
 
-  try {
-    const raw = execSync(cmd, {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-      maxBuffer: RUN_CHECK_MAX_BUFFER_BYTES,
-    });
-    const output = raw.split('\n').slice(-5).join('\n').trim();
-    return { status: 'pass', output, fullOutput: raw, exitCode: 0 };
-  } catch (err) {
-    const exitCode = typeof err.status === 'number' ? err.status : 1;
-
-    // Exit code 127 means command not found — treat as skip.
-    if (exitCode === 127) {
-      return { status: 'skip', output: 'command not found', fullOutput: '', exitCode };
-    }
+  const timeoutMs = opts.timeoutMs === undefined ? resolveGateTimeoutMs() : opts.timeoutMs;
+  const run = await spawnInGroup(cmd, {
+    maxOutputBytes: RUN_CHECK_MAX_BUFFER_BYTES,
+    repoRoot: process.cwd(),
+    commandSignature: buildCommandSignature(cmd),
+    ...opts,
+    timeoutMs,
+  });
+
+  // Reported in every returned shape below, so a consumer never has to ask a
+  // second question to learn whether the group is actually gone.
+  const groupFields = { killSignals: run.killSignals, survivors: run.survivors };
+
+  if (run.timedOut) {
+    const fullOutput = `${run.fullOutput}\n${timeoutLine(timeoutMs, run)}\n`;
+    return {
+      status: 'fail',
+      output: tailOf(fullOutput),
+      fullOutput,
+      exitCode: run.exitCode,
+      timedOut: true,
+      ...groupFields,
+    };
+  }
 
-    const combined = [err.stdout ?? '', err.stderr ?? ''].join('\n');
-    const output = combined.split('\n').slice(-5).join('\n').trim();
-    return { status: 'fail', output, fullOutput: combined, exitCode };
+  // Exit code 127 means command not found — treat as skip.
+  if (run.exitCode === 127) {
+    return { status: 'skip', output: 'command not found', fullOutput: '', exitCode: 127, timedOut: false, ...groupFields };
   }
+
+  return {
+    status: run.exitCode === 0 ? 'pass' : 'fail',
+    output: tailOf(run.fullOutput),
+    fullOutput: run.fullOutput,
+    exitCode: run.exitCode,
+    timedOut: false,
+    ...groupFields,
+  };
 }
 
 /**

package/scripts/lib/gates/gate-incremental.mjs

@@ -13,6 +13,31 @@ const testCmd = process.env.TEST_CMD;
 const files = process.env.FILES ?? '';
 const sessionStartRef = process.env.SESSION_START_REF ?? '';
 
+/**
+ * Per-command wall-clock ceiling, published by `scripts/run-quality-gate.mjs`
+ * as `GATE_TIMEOUT_MS` (#1425 A3 / #1432). It carries the ALREADY-RESOLVED
+ * value — operator override `SO_GATE_TIMEOUT_MS` > Session Config
+ * `gate.timeout-path-b-ms` > 900 000 — so this script only has to read it.
+ *
+ * Absent or non-numeric (this gate invoked directly, not through the wrapper)
+ * → the option is OMITTED, and `runCheck` falls back to `resolveGateTimeoutMs()`
+ * exactly as before. An empty object is deliberate: passing `timeoutMs:
+ * undefined` would NOT trigger that fallback in every spread order.
+ */
+const CHECK_OPTS = (() => {
+  const raw = Number((process.env.GATE_TIMEOUT_MS || '').trim());
+  const opts = Number.isFinite(raw) && raw > 0 ? { timeoutMs: raw } : {};
+  // GATE_LEDGER_ROOT (#1425 A4, W5 fix-pass): the wrapper publishes the ledger
+  // root it resolved (--ledger-root > repo root) so the gate-process register
+  // is written where the WRAPPER decided, not where this sub-script happens to
+  // run. Without it every runCheck() here defaulted to process.cwd(), and a test
+  // that spawned this script from the checkout wrote real lines into the live
+  // .orchestrator/runtime/gate-processes.jsonl — the reaper's kill population.
+  const ledgerRoot = (process.env.GATE_LEDGER_ROOT || "").trim();
+  if (ledgerRoot && ledgerRoot.startsWith("/")) opts.repoRoot = ledgerRoot;
+  return opts;
+})();
+
 if (!typecheckCmd) {
   process.stderr.write('TYPECHECK_CMD must be set\n');
   process.exit(1);
@@ -28,7 +53,7 @@ let testStatus;
 let errors = [];
 
 // --- typecheck (always runs unless cmd is "skip") ---
-const tcResult = await runCheck(typecheckCmd);
+const tcResult = await runCheck(typecheckCmd, CHECK_OPTS);
 const tcStatus = tcResult.status;
 if (tcStatus === 'fail') {
   errors = errors.concat(extractErrorLinesJson(tcResult.output, /error TS\d+/));
@@ -41,7 +66,7 @@ if (testCmd === 'skip') {
   const testFiles = await resolveTestFiles(files, sessionStartRef);
   if (testFiles.length > 0) {
     const fileArgs = testFiles.join(' ');
-    const testResult = await runCheck(`${testCmd} -- ${fileArgs}`);
+    const testResult = await runCheck(`${testCmd} -- ${fileArgs}`, CHECK_OPTS);
     testStatus = testResult.status;
     if (testStatus === 'fail') {
       const testErrors = extractErrorLinesJson(testResult.output, /(fail|error|FAIL)/i);
@@ -49,7 +74,7 @@ if (testCmd === 'skip') {
     }
   } else if (!files && !sessionStartRef) {
     // No FILES or SESSION_START_REF supplied: run the full test suite
-    const testResult = await runCheck(testCmd);
+    const testResult = await runCheck(testCmd, CHECK_OPTS);
     testStatus = testResult.status;
     if (testStatus === 'fail') {
       const testErrors = extractErrorLinesJson(testResult.output, /(fail|error|FAIL)/i);

package/scripts/lib/gates/gate-per-file.mjs

@@ -14,6 +14,31 @@ import { runCheck, csvToJsonArray } from './gate-helpers.mjs';
 const typecheckCmd = process.env.TYPECHECK_CMD;
 const testCmd = process.env.TEST_CMD;
 
+/**
+ * Per-command wall-clock ceiling, published by `scripts/run-quality-gate.mjs`
+ * as `GATE_TIMEOUT_MS` (#1425 A3 / #1432). It carries the ALREADY-RESOLVED
+ * value — operator override `SO_GATE_TIMEOUT_MS` > Session Config
+ * `gate.timeout-path-b-ms` > 900 000 — so this script only has to read it.
+ *
+ * Absent or non-numeric (this gate invoked directly, not through the wrapper)
+ * → the option is OMITTED, and `runCheck` falls back to `resolveGateTimeoutMs()`
+ * exactly as before. An empty object is deliberate: passing `timeoutMs:
+ * undefined` would NOT trigger that fallback in every spread order.
+ */
+const CHECK_OPTS = (() => {
+  const raw = Number((process.env.GATE_TIMEOUT_MS || '').trim());
+  const opts = Number.isFinite(raw) && raw > 0 ? { timeoutMs: raw } : {};
+  // GATE_LEDGER_ROOT (#1425 A4, W5 fix-pass): the wrapper publishes the ledger
+  // root it resolved (--ledger-root > repo root) so the gate-process register
+  // is written where the WRAPPER decided, not where this sub-script happens to
+  // run. Without it every runCheck() here defaulted to process.cwd(), and a test
+  // that spawned this script from the checkout wrote real lines into the live
+  // .orchestrator/runtime/gate-processes.jsonl — the reaper's kill population.
+  const ledgerRoot = (process.env.GATE_LEDGER_ROOT || "").trim();
+  if (ledgerRoot && ledgerRoot.startsWith("/")) opts.repoRoot = ledgerRoot;
+  return opts;
+})();
+
 if (!typecheckCmd) {
   process.stderr.write('gate-per-file: TYPECHECK_CMD must be set\n');
   process.exit(1);
@@ -33,14 +58,14 @@ if (files.length === 0) {
 }
 
 // Typecheck runs on the whole project, not per-file
-const tcResult = runCheck(typecheckCmd);
+const tcResult = await runCheck(typecheckCmd, CHECK_OPTS);
 const tcStatus = tcResult.status;
 
 let testStatus = 'skip';
 
 if (testCmd !== 'skip' && files.length > 0) {
   const fileArgs = files.join(' ');
-  const testResult = runCheck(`${testCmd} -- ${fileArgs}`);
+  const testResult = await runCheck(`${testCmd} -- ${fileArgs}`, CHECK_OPTS);
   testStatus = testResult.status;
 }
 

package/scripts/lib/gitlab-ops/stale-mr-sweep.mjs

@@ -24,6 +24,7 @@ import { promisify } from 'node:util';
 
 import { detectVcsForRepo, discoverVaultRepos } from '../gitlab-portfolio/vcs-detect.mjs';
 import { resolveRepoSpec } from '../vcs-repo-spec.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 const realExecFile = promisify(execFileCb);
 
@@ -455,7 +456,7 @@ export async function main(argv, deps = {}) {
 
 // ── CLI guard — prevent process.exit during test-time imports ─────────────────
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main(process.argv.slice(2))
     .then((result) => {
       process.exit(result.exitCode);

package/scripts/lib/gitlab-portfolio/cli.mjs

@@ -36,6 +36,7 @@ import { expandTilde } from '../common.mjs';
 import { discoverVaultRepos } from './vcs-detect.mjs';
 import { fetchIssuesMultiRepo, summarizeRepo } from './aggregator.mjs';
 import { renderPortfolio, writePortfolio } from './markdown-writer.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -406,7 +407,7 @@ EXIT CODES
 
 // ── CLI guard — prevent process.exit during test-time imports ─────────────────
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main(process.argv.slice(2)).then((result) => {
     process.exit(result.exitCode);
   }).catch((err) => {

package/scripts/lib/gitlab-portfolio/markdown-writer.mjs

@@ -139,7 +139,12 @@ export function renderPortfolio(summaries, opts) {
   // Frontmatter
   lines.push('---');
   lines.push(`_generator: ${GENERATOR_MARKER}`);
-  lines.push(`type: dashboard`);
+  // `id` + `type` satisfy the vault frontmatter schema (skills/vault-sync/validator.mjs).
+  // `type: dashboard` was not in its enum and `id` was missing, so the generated file
+  // failed the hard gate at /close (#1144). `board` is the enum member added for
+  // generated dashboards (#738) — same shape as vault-status/board-writer.mjs.
+  lines.push('id: portfolio');
+  lines.push('type: board');
   lines.push(`created: ${createdValue}`);
   lines.push(`updated: ${updatedValue}`);
   lines.push('---');