session-orchestrator 3.22.0 → 3.24.0

package/scripts/lib/express-path.mjs

@@ -0,0 +1,327 @@
+/**
+ * express-path.mjs — the Express Path activation DECISION plus its record (#214, #1119).
+ *
+ * ## Why this module exists at all
+ *
+ * The Express Path (session-start Phase 8.5) was built as prose and nothing else.
+ * Two measurements on 2026-08-23 pinned what that cost:
+ *
+ *   grep -c "express" scripts/lib/config.mjs                       → 0   (506 lines)
+ *   grep -c "express" .orchestrator/metrics/events.jsonl           → 0   (whole history)
+ *
+ * The second number is the real defect. `express-path.enabled` had no parser, so
+ * the documented default was prose rather than a value — but even a wired key only
+ * answers "what was configured". Nothing anywhere answered "did it fire?", and
+ * 22 of the last 30 sessions ran wave-less housekeeping without a single record
+ * saying whether the path applied to any of them.
+ *
+ * So the decision lives HERE, in code, and records itself as it is made. The prose
+ * in `skills/session-start/phase-8-5-express-path.md` points at this function; it
+ * does not re-implement the rule and it does not emit the event. A telemetry
+ * emitter that fires only when a coordinator reads the right paragraph is not
+ * wired — that is the same class of defect wave 2 of this session repaired for 18
+ * discovery probes.
+ *
+ * ## Where the rule comes from
+ *
+ * The three activation conditions are quoted verbatim from
+ * `skills/session-start/phase-8-5-express-path.md:9-11` and cross-checked against
+ * `docs/session-config-reference.md:1532-1536`. Both sources agree. The condition
+ * matrix in the same two files (spec `:47-53`, reference `:1557-1563`) supplies the
+ * fourth input, `parallelAgentsRequired`, which condition 3 carries as its second
+ * clause ("AND no parallel agents are required").
+ *
+ * ## Module placement — a deviation, and its cause
+ *
+ * Every other top-level Session Config block parser lives at
+ * `scripts/lib/config/<key>.mjs` (42 files). `_parseExpressPath` sits here instead
+ * because this agent's declared file scope for #1119 named `scripts/lib/express-path.mjs`
+ * and did not include `scripts/lib/config/`. The parser is otherwise a byte-for-byte
+ * sibling of `config/state-md-lock.mjs` — same block walk, same `matchBlockHeader`
+ * adoption (#830), same tolerant fallbacks. It imports only `./config/block-header.mjs`,
+ * which has zero imports by design, so no cycle is possible in either direction.
+ * Revisit trigger: if a later session is free to touch `scripts/lib/config/`, move
+ * `_parseExpressPath` to `scripts/lib/config/express-path.mjs` and leave only
+ * `evaluateExpressPath` here.
+ */
+
+import { matchBlockHeader } from './config/block-header.mjs';
+
+/**
+ * The one event name this module emits. Named, not inlined, so a consumer that
+ * queries the ledger and the producer that writes it cannot drift apart.
+ * Matches `ORCHESTRATOR_EVENT_RE` in `events-schema.mjs`.
+ */
+export const EXPRESS_PATH_EVENT = 'orchestrator.express_path.evaluated';
+
+/**
+ * Condition 3, first clause: "Agreed issue scope is ≤ 3 issues"
+ * (`skills/session-start/phase-8-5-express-path.md:11`).
+ */
+export const EXPRESS_PATH_MAX_TASKS = 3;
+
+// ---------------------------------------------------------------------------
+// Config parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the top-level `express-path:` YAML block from markdown content.
+ * Independent of the `## Session Config` section boundary, exactly like the
+ * sibling block parsers under `scripts/lib/config/`.
+ *
+ * Defaults:
+ *   enabled: true   (documented in docs/session-config-reference.md:1528 —
+ *                   "opt-in by default, opt-out via express-path.enabled: false")
+ *
+ * Because the default is `true`, only a literal `false` flips it — mirroring
+ * `config/state-md-lock.mjs`, whose `enabled` default is also `true`. (The
+ * `=== 'true'` form used by `config/discovery-validator.mjs` is the opposite
+ * convention and belongs to a default-`false` key.)
+ *
+ * Tolerant parser: malformed values silently fall back to the default.
+ *
+ * @param {string} content — full file contents
+ * @returns {{ enabled: boolean }}
+ */
+export function _parseExpressPath(content) {
+  const defaults = {
+    enabled: true,
+  };
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'express-path')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let epEnabled = true;
+
+  for (const rawLine of blockLines) {
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].trim();
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+    else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+
+    switch (k) {
+      case 'enabled':
+        // Default is true → only flip to false on explicit "false"
+        epEnabled = v.toLowerCase() !== 'false';
+        break;
+    }
+  }
+
+  return {
+    enabled: epEnabled,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The decision
+// ---------------------------------------------------------------------------
+
+/**
+ * Read `express-path.enabled` out of a `parseSessionConfig()` result.
+ *
+ * Returns `undefined` — NOT `true` — when the flag was never measured, so the
+ * caller can distinguish "the operator set true" from "nobody looked". The
+ * documented default is applied to the DECISION; the absent measurement is kept
+ * out of the RECORD.
+ *
+ * @param {unknown} config — a `parseSessionConfig()` result, or anything else
+ * @returns {boolean|undefined}
+ */
+function _readEnabledFlag(config) {
+  if (config === null || typeof config !== 'object') return undefined;
+  const block = /** @type {Record<string, unknown>} */ (config)['express-path'];
+  if (block === null || typeof block !== 'object') return undefined;
+  const value = /** @type {Record<string, unknown>} */ (block).enabled;
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+/**
+ * Build the event payload. Every optional field is spread conditionally:
+ * a value that was not measured is OMITTED, never encoded as `0`/`false`.
+ * An absent key is the only honest encoding of "not measured" — the same
+ * contract `sessionAttribution()` in `events.mjs` follows for session ids.
+ *
+ * @param {object} ctx
+ * @returns {Record<string, unknown>}
+ */
+function _buildPayload(ctx) {
+  const { activated, reasons, enabledMeasured, sessionType, taskCount, parallelAgentsRequired } = ctx;
+  const sessionTypeMeasured = typeof sessionType === 'string' && sessionType.trim() !== '';
+  const taskCountMeasured = Number.isInteger(taskCount) && taskCount >= 0;
+
+  return {
+    activated,
+    reasons,
+    ...(enabledMeasured === undefined ? {} : { enabled: enabledMeasured }),
+    ...(sessionTypeMeasured ? { session_type: sessionType.trim() } : {}),
+    ...(taskCountMeasured ? { task_count: taskCount } : {}),
+    ...(typeof parallelAgentsRequired === 'boolean'
+      ? { parallel_agents_required: parallelAgentsRequired }
+      : {}),
+  };
+}
+
+/**
+ * Append the evaluation record. Best-effort in the strict sense: it can never
+ * change, delay past its own await, or throw into the verdict.
+ *
+ * `events.mjs` is imported LAZILY on purpose, and the reason is measured rather
+ * than stylistic. `scripts/lib/config.mjs` imports this module for its parser,
+ * and its static import graph is 48 files today with no telemetry or platform
+ * modules in it. A static `import './events.mjs'` would add `platform.mjs`,
+ * which runs filesystem walk-ups at MODULE LOAD (`SO_PROJECT_DIR =
+ * resolveProjectDir(...)`) — paid by every hook and script that merely reads
+ * config. The lazy form also puts the telemetry module's own load inside the
+ * try/catch, so a broken events stack cannot stop the decision from being made.
+ *
+ * @param {object} ctx — see `_buildPayload`, plus `repoRoot`
+ * @returns {Promise<void>}
+ */
+async function _emitEvaluated(ctx) {
+  const { repoRoot } = ctx;
+
+  // Refuse the SO_PROJECT_DIR fallback rather than guess a destination. Without
+  // an explicit repoRoot, `emitEvent` writes to whatever tree the ambient env
+  // resolves to — which in wave 1 of this session put a synthetic record into
+  // the operator's real fleet ledger. A skipped record is recoverable; a record
+  // in the wrong ledger is not. Diagnostics on stderr, never stdout.
+  if (typeof repoRoot !== 'string' || repoRoot.trim() === '') {
+    process.stderr.write(
+      `express-path: skipped ${EXPRESS_PATH_EVENT} — no repoRoot given; ` +
+        'refusing the ambient SO_PROJECT_DIR destination (#941).\n',
+    );
+    return;
+  }
+
+  try {
+    const { emitEvent, sessionAttribution } = await import('./events.mjs');
+    await emitEvent(
+      EXPRESS_PATH_EVENT,
+      { ..._buildPayload(ctx), ...sessionAttribution(repoRoot) },
+      { repoRoot },
+    );
+  } catch {
+    // Best-effort telemetry — the verdict below is authoritative and is
+    // returned whether or not the ledger accepted the record.
+  }
+}
+
+/**
+ * @typedef {object} ExpressPathVerdict
+ * @property {boolean} activated — true only when every condition below holds.
+ * @property {string[]} reasons — when NOT activated, the blocking condition
+ *   codes and nothing else: the answer to "why didn't it fire". When activated,
+ *   the satisfied codes, since all of them decided jointly. Stable, greppable
+ *   slugs — they are the query key for the ledger.
+ */
+
+/**
+ * Evaluate the Express Path activation conditions and record the evaluation.
+ *
+ * The three conditions, quoted from `skills/session-start/phase-8-5-express-path.md:9-11`:
+ *
+ *   1. "`express-path.enabled` is `true` in Session Config (default: `true` —
+ *      opt-in by default, opt-out via `express-path.enabled: false`)."
+ *   2. "Session type is `housekeeping` (the user confirmed `housekeeping` in Phase 8)."
+ *   3. "Agreed issue scope is ≤ 3 issues AND no parallel agents are required
+ *      (i.e., tasks are sequential, no wave decomposition needed)."
+ *
+ * Every condition is evaluated — none short-circuits — because a run blocked by
+ * two conditions is a different fact from one blocked by a single condition, and
+ * the ledger is the only place that difference can ever be read.
+ *
+ * Fail-closed on an unmeasured input: an unknown session type or an unknown task
+ * count BLOCKS activation (`session-type-unknown` / `task-count-unknown`) rather
+ * than defaulting into a fast path that skips every quality gate. `enabled` is
+ * the one exception — its documented default is `true`, so an absent config
+ * applies that default to the decision while omitting `enabled` from the record.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot] — repo whose `.orchestrator/metrics/events.jsonl`
+ *   receives the record. REQUIRED for the record to be written; when absent the
+ *   verdict is still returned and a WARN goes to stderr (see `_emitEvaluated`).
+ * @param {object} [opts.config] — a `parseSessionConfig()` result. Read for
+ *   `config['express-path'].enabled` only.
+ * @param {string} [opts.sessionType] — the session type confirmed in Phase 8.
+ * @param {number} [opts.taskCount] — agreed issue/task scope (non-negative integer).
+ * @param {boolean} [opts.parallelAgentsRequired] — whether the agreed tasks need
+ *   parallel agents. Omitting it asserts nothing: the condition is treated as
+ *   satisfied (`parallel-agents-not-asserted`) and the field is left out of the
+ *   record, because "nobody said parallel agents are needed" is not the same
+ *   claim as "it was measured that none are needed".
+ * @returns {Promise<ExpressPathVerdict>}
+ */
+export async function evaluateExpressPath(opts = {}) {
+  const { repoRoot, config, sessionType, taskCount, parallelAgentsRequired } = opts;
+
+  const enabledMeasured = _readEnabledFlag(config);
+  const enabled = enabledMeasured === undefined ? true : enabledMeasured;
+
+  /** @type {string[]} */ const satisfied = [];
+  /** @type {string[]} */ const blocking = [];
+
+  // Condition 1 — express-path.enabled
+  if (enabled) satisfied.push('enabled');
+  else blocking.push('disabled-by-config');
+
+  // Condition 2 — session type is housekeeping
+  if (typeof sessionType !== 'string' || sessionType.trim() === '') {
+    blocking.push('session-type-unknown');
+  } else if (sessionType.trim() === 'housekeeping') {
+    satisfied.push('session-type-housekeeping');
+  } else {
+    blocking.push('session-type-not-housekeeping');
+  }
+
+  // Condition 3a — scope ≤ EXPRESS_PATH_MAX_TASKS issues
+  if (!Number.isInteger(taskCount) || taskCount < 0) {
+    blocking.push('task-count-unknown');
+  } else if (taskCount > EXPRESS_PATH_MAX_TASKS) {
+    blocking.push('scope-exceeds-limit');
+  } else {
+    satisfied.push('scope-within-limit');
+  }
+
+  // Condition 3b — no parallel agents required
+  if (parallelAgentsRequired === true) {
+    blocking.push('parallel-agents-required');
+  } else if (parallelAgentsRequired === false) {
+    satisfied.push('no-parallel-agents');
+  } else {
+    satisfied.push('parallel-agents-not-asserted');
+  }
+
+  const activated = blocking.length === 0;
+  const reasons = activated ? satisfied : blocking;
+
+  await _emitEvaluated({
+    repoRoot,
+    activated,
+    reasons,
+    enabledMeasured,
+    sessionType,
+    taskCount,
+    parallelAgentsRequired,
+  });
+
+  return { activated, reasons };
+}

package/scripts/lib/file-lock.mjs

@@ -12,8 +12,10 @@
  *   4. live holder OR cross-host → poll until a deadline;
  *   5. owner-guarded release.
  *
- * This module is the single home for that skeleton. It is a PURE primitive:
- * it imports ONLY scripts/lib/io.mjs (for writeJsonAtomicSync) and Node stdlib.
+ * This module is the single home for that skeleton. It is a near-PURE primitive:
+ * it imports ONLY scripts/lib/io.mjs (for writeJsonAtomicSync), the two host
+ * identity helpers from scripts/lib/host-identity.mjs (#1072 — `os.hostname()`
+ * is not stable on a single machine), and Node stdlib.
  * It does NOT import session-lock.mjs — instead `isPidAliveOnHost` is MOVED here
  * and re-exported from session-lock.mjs, so the dependency edge points
  * file-lock → io, never the reverse (no import cycle).
@@ -35,6 +37,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 
 import { writeJsonAtomicSync } from './io.mjs';
+import { hostnamesMatch, lockHostCandidate, stableHostname } from './host-identity.mjs';
 
 // ---------------------------------------------------------------------------
 // PID liveness (moved here from session-lock.mjs in #630)
@@ -139,7 +142,17 @@ function parseBody(raw) {
  * @returns {{ stale: boolean, reason: string }}
  */
 function isExistingStale(existing, staleCheck, staleMs, lockPath) {
-  const sameHost = existing.host === os.hostname();
+  // #1072: compare on the normalised/alias-aware identity, never on a raw
+  // `os.hostname()` string. A raw comparison reports `cross-host` for THIS
+  // machine's own lock whenever the hostname has flipped spelling since it was
+  // written, and `cross-host` disables stale detection entirely (below) — the
+  // lock then survives its holder for the full timeout. `host_id` is preferred
+  // when present because it is already normalised; `host` is the pre-#1072
+  // fallback, so old lock files need no migration. `lockHostCandidate` owns
+  // that choice for all six lock-family call sites — and falls back on an
+  // EMPTY `host_id` too, which a bare `??` would have short-circuited into a
+  // false `cross-host` verdict against this machine's own lock.
+  const sameHost = hostnamesMatch(lockHostCandidate(existing), os.hostname());
   if (!sameHost) return { stale: false, reason: 'cross-host' };
 
   if (staleCheck === 'none') return { stale: false, reason: 'live' };
@@ -294,7 +307,10 @@ export function tryAcquireFileLock(lockPath, opts = {}) {
 
   const body = {
     pid: process.pid,
+    // `host` stays the RAW hostname (on-the-wire field other readers pin);
+    // `host_id` is the additive normalised twin the comparisons above use.
     host: os.hostname(),
+    host_id: stableHostname(),
     acquiredAt: new Date().toISOString(),
     ...(meta && typeof meta === 'object' ? meta : {}),
   };
@@ -407,7 +423,9 @@ export function releaseFileLock(lockPath, opts = {}) {
   const expectedHolder = typeof holder === 'string' && holder.length > 0 ? holder : null;
   const ownerMatch = expectedHolder !== null
     ? lock.holder === expectedHolder
-    : lock.pid === process.pid && lock.host === os.hostname();
+    // #1072: a raw hostname comparison here makes a process unable to release
+    // its OWN lock after the hostname flips spelling mid-session.
+    : lock.pid === process.pid && hostnamesMatch(lockHostCandidate(lock), os.hostname());
 
   if (!ownerMatch) return { ok: false, reason: 'not-owner' };
 

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

@@ -40,14 +40,42 @@ const tcErrorCount =
     : 0;
 
 // --- Test ---
-// NOTE: `testFailed`, 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.
+// 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 { passed: testPassed, failed: testFailed, total: testTotal } =
+const testCounts =
   testResult.status !== 'skip'
     ? extractTestCounts(testResult.fullOutput ?? testResult.output)
-    : { passed: 0, failed: 0, total: 0 };
+    : { passed: 0, failed: 0, total: 0, files: null };
+
+// A suite that dies at import time (a bad import, a syntax error in a test
+// file) is counted on vitest's `Test Files` line, not its `Tests` line —
+// vitest omits `N failed` from `Tests` when zero individual test CASES ran.
+// That leaves `status: 'fail'` sitting beside `failed: 0`, which reads as "no
+// failures" even though the gate is about to block. `suite_died` names the
+// contradiction explicitly, in the JSON itself, rather than leaving it
+// inferable only by cross-referencing three separate fields (#1149).
+//
+// All FOUR of these fields are file-measurement-derived, so all four are
+// published together or not at all. Only vitest prints a `Test Files` line; a
+// non-vitest runner or a terse reporter prints none, and the previous
+// zero-filled `files_*: 0` was an UNMEASURED zero the envelope could not tell
+// from a measured one — with `suite_died: false` derived from it, stating a
+// verdict nobody had checked. Absent, not zero: the same contract this
+// envelope's `counts` field already keeps (`admitSuiteCounts`).
+const fileFields = testCounts.files
+  ? {
+      files_total: testCounts.files.total,
+      files_passed: testCounts.files.passed,
+      files_failed: testCounts.files.failed,
+      // Self-diagnosing: true exactly when `status: 'fail'` sits beside a
+      // test-case `failed: 0` that a file-level failure explains. Greppable —
+      // a consumer no longer has to recompute the contradiction by hand.
+      suite_died:
+        testResult.status === 'fail' && testCounts.failed === 0 && testCounts.files.failed > 0,
+    }
+  : {};
 
 // --- Lint ---
 const lintResult = runCheck(lintCmd);
@@ -79,9 +107,15 @@ const output = {
   // `passed + failed === total` as a real producer/consumer drift guard.
   test: {
     status: testResult.status,
-    total: testTotal,
-    passed: testPassed,
-    failed: testFailed,
+    total: testCounts.total,
+    passed: testCounts.passed,
+    failed: testCounts.failed,
+    // File-level counts + `suite_died` (#1149) — present only when a
+    // `Test Files` line was actually parsed; see `fileFields` above.
+    // Additive keys only: `admitSuiteCounts` / `suiteCountsFromGateStdout`
+    // read just passed/failed/total, so the stdout JSON contract stays one
+    // document and the test-case triple keeps `total === passed + failed`.
+    ...fileFields,
   },
   lint: { status: lintResult.status, warnings: lintWarnings },
   debug_artifacts: debugArtifacts,
@@ -94,4 +128,43 @@ process.stdout.write(JSON.stringify(output) + '\n');
 const failed = [tcResult, testResult, lintResult].some(
   (r) => r.status === 'fail',
 );
+
+// --- Failure disclosure ---
+// A gate that BLOCKS and says nothing is not concise, it is unusable. Measured
+// 2026-08-23: a pre-push run emitted exactly
+//   {"test":{"status":"fail","total":14671,"passed":14671,"failed":0}, …}
+// and nothing else. `failed: 0` beside `status: fail` was not a contradiction
+// in the data — it was the SHAPE of the report: `extractTestCounts` reads
+// vitest's `Tests …` summary line, and vitest OMITS the `N failed` segment
+// when no individual test case failed. A suite that dies at import time is
+// counted on the `Test Files …` line instead, which this payload had no field
+// for. So a file-level failure was, by construction, reported as zero
+// failures. The JSON envelope now carries `files_failed` and `suite_died`
+// (#1149) so that contradiction is published rather than only inferable —
+// but the envelope still does not name WHICH file died.
+//
+// Reconstructing which file died then cost a full manual re-materialisation of
+// the tracked tree. That is the cost this block removes: on failure the raw
+// output of every failing gate goes to STDERR, where the JSON contract on
+// STDOUT is untouched and every existing consumer keeps parsing one line.
+//
+// stderr, not stdout, and only on failure, for three reasons that are all
+// contract-preserving: `scripts/run-quality-gate.mjs` and the pre-push hook
+// parse stdout as ONE JSON document; a green run stays silent, so the "~2 min
+// of silence" the hook promises still holds; and the operator gets the failure
+// at the moment of the block instead of a second run to find it.
+if (failed) {
+  for (const [name, result] of [
+    ['typecheck', tcResult],
+    ['test', testResult],
+    ['lint', lintResult],
+  ]) {
+    if (result.status !== 'fail') continue;
+    const raw = result.fullOutput ?? result.output ?? '';
+    process.stderr.write(`\n──── ${name} FAILED — raw output ────\n`);
+    process.stderr.write(raw.length > 0 ? raw : '(the gate captured no output)\n');
+    process.stderr.write(`──── end ${name} ────\n`);
+  }
+}
+
 process.exit(failed ? 2 : 0);

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

@@ -154,7 +154,35 @@ export function extractCount(output, pattern) {
 const TEST_SUMMARY_LINE = /^\s*Tests\b/;
 
 /**
- * Parse test-runner output for pass/fail/total TEST-CASE counts.
+ * Matches vitest's FILE-level summary line (`Test Files  8 failed | 595 passed (603)`).
+ *
+ * Distinct from {@link TEST_SUMMARY_LINE} (the TEST-CASE line, `Tests  ...`): a
+ * suite that dies at import time is counted HERE, and the `Tests` line then
+ * carries no `N failed` segment at all (#1149) — vitest omits it whenever zero
+ * individual test cases ran. Last matching line wins (the final summary after
+ * any rerun), mirroring `TEST_SUMMARY_LINE`'s own convention.
+ */
+const TEST_FILES_SUMMARY_LINE = /^\s*Test Files\b/;
+
+/**
+ * Parse a `<N> passed` / `<N> failed` pair out of one summary line/scope.
+ * `total` is their sum (skipped excluded) — the same rule the top-level
+ * test-case triple in {@link extractTestCounts} publishes.
+ *
+ * @param {string} scope
+ * @returns {{ passed: number, failed: number, total: number }}
+ */
+function parseCountTriple(scope) {
+  const passMatch = scope.match(/(\d+)\s+passed/);
+  const failMatch = scope.match(/(\d+)\s+failed/);
+  const passed = passMatch ? parseInt(passMatch[1], 10) : 0;
+  const failed = failMatch ? parseInt(failMatch[1], 10) : 0;
+  return { passed, failed, total: passed + failed };
+}
+
+/**
+ * Parse test-runner output for pass/fail/total TEST-CASE counts, plus the
+ * vitest FILE-level triple when a `Test Files` summary line is present.
  *
  * ## Which line is parsed
  *
@@ -168,10 +196,38 @@ const TEST_SUMMARY_LINE = /^\s*Tests\b/;
  * A naive whole-output scan hits the FILE count (550) and publishes it as the
  * test count — the number then rides `gate-full.mjs`'s `test.passed` into the
  * `orchestrator.quality_gate.*` event stream looking authoritative. So: when a
- * `Tests`-anchored summary line exists, ONLY that line is parsed (the LAST one,
- * which is the final summary after any rerun). Terse or non-vitest output with
- * no such line falls back to scanning the whole string, which preserves the
- * bare `"42 passed"` / `"10 passed, 5 failed"` forms.
+ * `Tests`-anchored summary line exists, ONLY that line is parsed for the
+ * test-case triple (the LAST one, which is the final summary after any
+ * rerun). Terse or non-vitest output with no such line falls back to scanning
+ * the whole string, which preserves the bare `"42 passed"` / `"10 passed, 5
+ * failed"` forms.
+ *
+ * The `Test Files` line is parsed the same way, into a SEPARATE nested `files`
+ * triple — never folded into `failed`/`total`. `total === passed + failed` is
+ * load-bearing for the test-case triple (`admitSuiteCounts`, and historically
+ * `failed = total - passed` in `run-quality-gate.mjs`); mixing file counts in
+ * would either break that invariant or invent phantom test-case failures. A
+ * suite that dies at import is invisible on the `Tests` line (vitest omits
+ * `N failed` there when zero test cases ran) and visible only on `Test
+ * Files` — #1149, measured as
+ * `{"test":{"status":"fail","total":14671,"passed":14671,"failed":0}}`, with
+ * no field anywhere naming the 8 files that actually died.
+ * `gate-full.mjs` derives a `suite_died` boolean from `files.failed` for
+ * exactly this shape.
+ *
+ * ## `files` is NULL when no `Test Files` line was seen — never a zero triple
+ *
+ * Only vitest prints that line. A non-vitest runner, a terse reporter, or a
+ * fail-fast crash produces output with no file-level summary at all, and the
+ * function used to publish `files_total/passed/failed: 0` there — an UNMEASURED
+ * zero, byte-identical in the envelope to a measured one, from which
+ * `gate-full.mjs` then derived `suite_died: false` as if it had checked. That is
+ * the same "absent is not zero" defect `admitSuiteCounts` exists to prevent one
+ * field over, so it uses the same channel: `null` means "no file-level
+ * measurement", and the caller OMITS the keys rather than zero-filling them.
+ * The test-case triple keeps its zeros — those are the caller's fallback, not a
+ * parse result, and `total: 0` is already the "no counts" signal
+ * `admitSuiteCounts` rejects.
  *
  * ## What `total` means — passed + failed, NOT vitest's parenthesised number
  *
@@ -189,22 +245,27 @@ const TEST_SUMMARY_LINE = /^\s*Tests\b/;
  * see. Add it together with a consumer, never ahead of one.
  *
  * @param {string} output - Captured test-runner stdout/stderr (or a tail of it).
- * @returns {{ passed: number, failed: number, total: number }} `total === passed + failed`.
+ * @returns {{ passed: number, failed: number, total: number, files: {passed: number, failed: number, total: number}|null }}
+ *   Test-case `total === passed + failed`. `files` is `null` when the output
+ *   carried no `Test Files` summary line; when present,
+ *   `files.total === files.passed + files.failed`.
  */
 export function extractTestCounts(output) {
-  if (!output) return { passed: 0, failed: 0, total: 0 };
+  const EMPTY = { passed: 0, failed: 0, total: 0, files: null };
+  if (!output) return EMPTY;
 
-  const summaryLines = output.split('\n').filter((line) => TEST_SUMMARY_LINE.test(line));
+  const lines = output.split('\n');
+  const summaryLines = lines.filter((line) => TEST_SUMMARY_LINE.test(line));
   const scope = summaryLines.length > 0 ? summaryLines[summaryLines.length - 1] : output;
+  const { passed, failed, total } = parseCountTriple(scope);
 
-  const passMatch = scope.match(/(\d+)\s+passed/);
-  const failMatch = scope.match(/(\d+)\s+failed/);
+  const fileSummaryLines = lines.filter((line) => TEST_FILES_SUMMARY_LINE.test(line));
+  const fileScope = fileSummaryLines.length > 0 ? fileSummaryLines[fileSummaryLines.length - 1] : '';
+  // No `Test Files` line → NOT MEASURED. See the docstring section above: a zero
+  // triple here would be indistinguishable from a real all-passed-zero-files run.
+  const files = fileScope ? parseCountTriple(fileScope) : null;
 
-  const passed = passMatch ? parseInt(passMatch[1], 10) : 0;
-  const failed = failMatch ? parseInt(failMatch[1], 10) : 0;
-  const total = passed + failed;
-
-  return { passed, failed, total };
+  return { passed, failed, total, files };
 }
 
 /**