session-orchestrator 5.2.0 → 5.4.0

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

@@ -8,10 +8,265 @@
 
 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 ?? [],
+  };
+}
+
+/**
+ * The INNER kill ladder of one gate command, in the gate envelope's own
+ * snake_case shape (#1457 point 1).
+ *
+ * `runCheck` knows, per command, whether its per-command ceiling fired, which
+ * signals it sent and which pids survived the SIGKILL step. Until this helper
+ * that knowledge died inside the gate sub-script, so a command killed by the
+ * INNER ceiling reached `orchestrator.quality_gate.failed` as
+ * `timed_out: false`. Spread it into the command's envelope object.
+ *
+ * Absent is not zero: a result that spawned nothing (skip, stub) carries no
+ * `timedOut` boolean, and gets NO keys — never `false` / `[]`.
+ *
+ * @param {{timedOut?: boolean, killSignals?: string[], survivors?: number[]}} result
+ *   A {@link runCheck} result.
+ * @returns {{timed_out: boolean, kill_signals: string[], survivors: number[]}|{}}
+ *   `survivors` are the pids, same as {@link gateTimeoutEnvelope}.
+ */
+export function commandKillFields(result) {
+  if (typeof result?.timedOut !== 'boolean') return {};
+  return {
+    timed_out: result.timedOut,
+    kill_signals: Array.isArray(result.killSignals) ? [...result.killSignals] : [],
+    survivors: Array.isArray(result.survivors) ? [...result.survivors] : [],
+  };
+}
+
+/** Envelope keys, in execution order, that may carry {@link commandKillFields}. */
+const KILL_FIELD_COMMANDS = ['typecheck', 'test', 'lint'];
+
+/**
+ * Join the OUTER kill ladder (the gate sub-script as a whole) with the INNER
+ * per-command ladders its JSON envelope publishes (#1457 point 1), into the
+ * `timed_out` / `survivors` / `kill_signals` keys of
+ * `orchestrator.quality_gate.{passed,failed}`.
+ *
+ * - inner measured (the envelope parses and EVERY command object either carries
+ *   a boolean `timed_out` or provably spawned nothing — `status: 'skip'` or
+ *   listed in `stubbed`): `timed_out` = outer OR any inner; `kill_signals` =
+ *   outer followed by each command's, in execution order; `survivors` = outer
+ *   count plus every inner pid count.
+ * - inner NOT measured (a variant whose envelope does not publish it, an
+ *   unparseable envelope, or the outer ceiling killed the sub-script before it
+ *   wrote one): the outer ladder alone when it fired — a kill is a kill — and
+ *   otherwise NO keys, because `false` / `0` / `[]` would claim that no
+ *   command was killed when nobody looked.
+ *
+ * Never throws.
+ *
+ * @param {object} args
+ * @param {{timed_out: boolean, survivors: number, kill_signals: string[]}} args.outer
+ *   `gateKillFields()` of the sub-script's `spawnInGroup` result.
+ * @param {string} args.gateStdout  The sub-script's stdout envelope (`''` on an outer kill).
+ * @returns {{timed_out: boolean, survivors: number, kill_signals: string[]}|{}}
+ */
+export function joinGateKillFields({ outer, gateStdout }) {
+  let parsed = null;
+  if (typeof gateStdout === 'string' && gateStdout.trim()) {
+    try {
+      parsed = JSON.parse(gateStdout);
+    } catch {
+      parsed = null;
+    }
+  }
+  const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  const names = isObj(parsed) ? KILL_FIELD_COMMANDS.filter((name) => isObj(parsed[name])) : [];
+  const stubbed = isObj(parsed?.stubbed) ? parsed.stubbed : {};
+  // A command either published its ladder, or provably spawned nothing (skip /
+  // stub) — nothing killed is then a measurement too. Any OTHER command (a
+  // variant that ran it but does not publish the ladder) makes the inner side
+  // unknown as a whole.
+  const inner = names.map((name) => parsed[name]).filter((c) => typeof c.timed_out === 'boolean');
+  const innerKnown = names.length > 0 && names.every((name) => typeof parsed[name].timed_out === 'boolean'
+    || parsed[name].status === 'skip'
+    || Boolean(stubbed[name]));
+
+  if (!innerKnown) return outer?.timed_out === true ? { ...outer } : {};
+
+  return {
+    timed_out: outer?.timed_out === true || inner.some((c) => c.timed_out),
+    survivors: (outer?.survivors ?? 0)
+      + inner.reduce((n, c) => n + (Array.isArray(c.survivors) ? c.survivors.length : 0), 0),
+    kill_signals: [
+      ...(outer?.kill_signals ?? []),
+      ...inner.flatMap((c) => (Array.isArray(c.kill_signals) ? c.kill_signals : [])),
+    ],
+  };
+}
+
+/**
+ * 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 +294,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 +308,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 +358,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,
+  };
 }
 
 /**
@@ -392,8 +703,10 @@ export function extractFailedTestFiles(output, cwd = process.cwd()) {
  *
  * This function sees a candidate triple and nothing else. It performs no I/O and
  * reads no files. The following are per-caller INPUT ADAPTERS and must not
- * migrate here: JSON-envelope parsing; the `test`-object-vs-status-string
- * variant discrimination (non-full-gate variants emit a bare status string);
+ * migrate here: JSON-envelope parsing; the `test`-must-be-an-object check
+ * (every variant emits an object since #1457 pkt 12; only full-gate's carries
+ * counts, so the others fall through to this function's own finite-number
+ * refusal);
  * `test.status ∈ {pass, fail}`; the `parsed.stubbed?.test` short-circuit; the
  * raw-text tail parse ({@link extractTestCounts}); and the positional evidence
  * that the test gate ran at all — which each caller expresses by handing over

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

@@ -6,13 +6,38 @@
 // Required env: TYPECHECK_CMD, TEST_CMD
 // Optional env: FILES (comma-separated), SESSION_START_REF
 
-import { runCheck, resolveTestFiles, extractErrorLinesJson } from './gate-helpers.mjs';
+import { runCheck, resolveTestFiles, extractErrorLinesJson, commandKillFields } from './gate-helpers.mjs';
 
 const typecheckCmd = process.env.TYPECHECK_CMD;
 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);
@@ -24,41 +49,32 @@ if (!testCmd) {
 
 const start = Date.now();
 
-let testStatus;
+// A skipped test run spawned nothing: `{ status: 'skip' }`, no kill keys.
+let testResult = { status: 'skip' };
 let errors = [];
 
 // --- typecheck (always runs unless cmd is "skip") ---
-const tcResult = await runCheck(typecheckCmd);
-const tcStatus = tcResult.status;
-if (tcStatus === 'fail') {
+const tcResult = await runCheck(typecheckCmd, CHECK_OPTS);
+if (tcResult.status === 'fail') {
   errors = errors.concat(extractErrorLinesJson(tcResult.output, /error TS\d+/));
 }
 
 // --- test (scoped to changed/specified files) ---
-if (testCmd === 'skip') {
-  testStatus = 'skip';
-} else {
+if (testCmd !== 'skip') {
   const testFiles = await resolveTestFiles(files, sessionStartRef);
   if (testFiles.length > 0) {
     const fileArgs = testFiles.join(' ');
-    const testResult = await runCheck(`${testCmd} -- ${fileArgs}`);
-    testStatus = testResult.status;
-    if (testStatus === 'fail') {
-      const testErrors = extractErrorLinesJson(testResult.output, /(fail|error|FAIL)/i);
-      errors = errors.concat(testErrors);
-    }
+    testResult = await runCheck(`${testCmd} -- ${fileArgs}`, CHECK_OPTS);
   } else if (!files && !sessionStartRef) {
     // No FILES or SESSION_START_REF supplied: run the full test suite
-    const testResult = await runCheck(testCmd);
-    testStatus = testResult.status;
-    if (testStatus === 'fail') {
-      const testErrors = extractErrorLinesJson(testResult.output, /(fail|error|FAIL)/i);
-      errors = errors.concat(testErrors);
-    }
+    testResult = await runCheck(testCmd, CHECK_OPTS);
   } else {
     // Files/ref supplied but no test files found — skip
     process.stderr.write('warn: No test files found for incremental run; skipping tests\n');
-    testStatus = 'skip';
+  }
+  if (testResult.status === 'fail') {
+    const testErrors = extractErrorLinesJson(testResult.output, /(fail|error|FAIL)/i);
+    errors = errors.concat(testErrors);
   }
 }
 
@@ -67,8 +83,18 @@ const duration_seconds = Math.round((Date.now() - start) / 1000);
 const result = {
   variant: 'incremental',
   duration_seconds,
-  typecheck: tcStatus,
-  test: testStatus,
+  // Each command object also carries its INNER kill ladder (`timed_out`,
+  // `kill_signals`, `survivors` pids) when `runCheck` spawned it — omitted for
+  // skip/stub (#1457). `run-quality-gate.mjs` joins them into its event.
+  typecheck: { status: tcResult.status, ...commandKillFields(tcResult) },
+  test: { status: testResult.status, ...commandKillFields(testResult) },
+  // Stub map, same shape as gate-full: a command `runCheck` recognised as a
+  // stub (`echo …`/`true`) spawned nothing, so `joinGateKillFields` may count
+  // it as measured instead of declaring the whole inner ladder unknown.
+  stubbed: {
+    ...(tcResult.stubbed ? { typecheck: tcResult.stubbed } : {}),
+    ...(testResult.stubbed ? { test: testResult.stubbed } : {}),
+  },
   errors,
 };
 

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

@@ -9,11 +9,36 @@
  * Part of v3.2 shell-helper port migration (issue #218 / #317).
  */
 
-import { runCheck, csvToJsonArray } from './gate-helpers.mjs';
+import { runCheck, csvToJsonArray, commandKillFields } 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,21 +58,30 @@ if (files.length === 0) {
 }
 
 // Typecheck runs on the whole project, not per-file
-const tcResult = runCheck(typecheckCmd);
-const tcStatus = tcResult.status;
+const tcResult = await runCheck(typecheckCmd, CHECK_OPTS);
 
-let testStatus = 'skip';
+// A skipped test run spawned nothing: `{ status: 'skip' }`, no kill keys.
+let testResult = { status: 'skip' };
 
 if (testCmd !== 'skip' && files.length > 0) {
   const fileArgs = files.join(' ');
-  const testResult = runCheck(`${testCmd} -- ${fileArgs}`);
-  testStatus = testResult.status;
+  testResult = await runCheck(`${testCmd} -- ${fileArgs}`, CHECK_OPTS);
 }
 
 const result = {
   variant: 'per-file',
-  typecheck: tcStatus,
-  test: testStatus,
+  // Each command object also carries its INNER kill ladder (`timed_out`,
+  // `kill_signals`, `survivors` pids) when `runCheck` spawned it — omitted for
+  // skip/stub (#1457). `run-quality-gate.mjs` joins them into its event.
+  typecheck: { status: tcResult.status, ...commandKillFields(tcResult) },
+  test: { status: testResult.status, ...commandKillFields(testResult) },
+  // Stub map, same shape as gate-full: a command `runCheck` recognised as a
+  // stub (`echo …`/`true`) spawned nothing, so `joinGateKillFields` may count
+  // it as measured instead of declaring the whole inner ladder unknown.
+  stubbed: {
+    ...(tcResult.stubbed ? { typecheck: tcResult.stubbed } : {}),
+    ...(testResult.stubbed ? { test: testResult.stubbed } : {}),
+  },
   files,
 };
 

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('---');