session-orchestrator 5.2.0 → 5.3.0

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

package/scripts/lib/instruction-budget-guard.mjs

@@ -78,6 +78,7 @@
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
+import { scanEventsBackwards } from './events.mjs';
 import { loadApplicableRules, parseGlobsFrontmatter } from './rule-loader.mjs';
 
 /** Default directive ceiling (operator-chosen growth ratchet just above the ~457 baseline). */
@@ -443,6 +444,35 @@ export const DEFAULT_GENERATED_BYTE_CEILING = 95000;
  */
 export const DEFAULT_PATH_SCOPED_BYTE_CEILING = 124000;
 
+/**
+ * Share of {@link DEFAULT_PATH_SCOPED_BYTE_CEILING} at which the banner warns
+ * BEFORE the writer refuses (#1419).
+ *
+ * The defect #1419 records is not the ceiling but its TIMING: it becomes
+ * visible only inside `writeApprovedRules`, after the operator has already
+ * decided. Measured on that case (2026-09-20, /reconcile run): 117,973 of
+ * 124,000 B = 95.1 % — ~6 kB of headroom holding back `capped: 91`
+ * candidates, and `overPathScopedBudget` (a HARD `bytes > ceiling` test) did
+ * not fire, so nothing warned.
+ *
+ * 90 % is the distance of ~4 materialised rules: 10 % of 124,000 B = 12,400 B
+ * against the ~1.5 kB a generated rule file occupied on the #1419 tree — i.e.
+ * roughly four more accepted learnings until the hard break. A fixed fraction,
+ * deliberately not a per-repo calibration: it cannot know how large THIS
+ * repo's next rule is, and a second calibrated number would need its own
+ * falsification record.
+ *
+ * BV-004 ceiling + revisit trigger (HR-105): measure this line's firing rate
+ * after ~20 sessions from the probe records in
+ * `.orchestrator/metrics/events.jsonl`
+ * (`jq -c 'select(.event=="orchestrator.probes.completed")
+ * | .probes[] | select(.id=="instruction-budget")' …` — count `ran-warn`
+ * against the record total).
+ * Above ~10 % the instrument is RE-AIMED per HR-101 — neither lowered nor
+ * silenced; below it, leave it alone.
+ */
+export const PATH_SCOPED_NEAR_THRESHOLD = 0.9;
+
 /**
  * Read the `instruction-budget:` nested block from the `## Session Config`
  * section of CLAUDE.md (or AGENTS.md) at `repoRoot`. Synchronous + never throws.
@@ -1244,6 +1274,83 @@ export function computeInstructionBudget(opts = {}) {
   };
 }
 
+/** Ledger event the backlog number below is read from (`reconcile/engine.mjs`). */
+const RECONCILE_EVENT = 'orchestrator.reconcile.completed';
+
+/**
+ * Wall-clock budget for the backwards ledger walk. Deliberately small: this
+ * runs inside a session-start probe whose own budget is 2 s, and the number it
+ * fetches is DECORATION on a line that is already actionable without it.
+ */
+const RECONCILE_SCAN_BUDGET_MS = 150;
+
+/**
+ * `capped` from the most recent `orchestrator.reconcile.completed` record —
+ * how many rule-eligible learnings the last /reconcile run held back.
+ *
+ * Three-state on purpose (`feedback_missing_measurement_looks_like_zero`):
+ * `null` means NOT MEASURED (no ledger, no such record, unreadable source, or
+ * the walk ran out of budget), which the caller must render as ABSENCE — never
+ * as `0`, which is a measured "nothing waiting".
+ *
+ * @param {string|undefined} repoRoot
+ * @returns {number|null}
+ */
+function readLastReconcileCapped(repoRoot) {
+  if (typeof repoRoot !== 'string' || repoRoot === '') return null;
+  const filePath = join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+  let capped = null;
+  let scan;
+  try {
+    scan = scanEventsBackwards({
+      filePath,
+      budgetMs: RECONCILE_SCAN_BUDGET_MS,
+      // Cheap raw-line pre-filter before JSON.parse — same reason as
+      // `maintenance-due-banner.mjs`: parsing every line of a multi-MB ledger
+      // to answer one question is the cost this option exists to avoid.
+      filter: RECONCILE_EVENT,
+      onRecord: (rec) => {
+        if (rec?.event !== RECONCILE_EVENT) return false;
+        capped = Number.isFinite(rec.capped) ? rec.capped : null;
+        return true; // newest record wins; stop the walk
+      },
+    });
+  } catch {
+    return null; // never throw out of the banner wrapper
+  }
+  // A walk that did not finish has not proven anything about the backlog.
+  if (scan.truncated || scan.unreadable.length > 0) return null;
+  return capped;
+}
+
+/**
+ * The #1419 early-warning line: the path-scoped ceiling is close, not broken.
+ *
+ * Reports the numbers the RULE judged (HR-106) — the same `pathScoped.bytes`
+ * and ceiling `writeApprovedRules` will compare later — plus, when the ledger
+ * carries one, how many learnings the last /reconcile run already held back.
+ * The percentage is formatted locale-free so the same corpus renders the same
+ * string on every host.
+ *
+ * @param {ReturnType<typeof computeInstructionBudget>} budget
+ * @param {string|undefined} repoRoot
+ * @returns {string}
+ */
+function formatNearPathScopedLine(budget, repoRoot) {
+  const used = budget.bySurface.pathScoped.bytes;
+  const ceiling = budget.pathScopedByteCeiling;
+  const pct = ((used / ceiling) * 100).toFixed(1);
+  const capped = readLastReconcileCapped(repoRoot);
+  // Only a POSITIVE measured backlog is worth a clause; `0` and `null` both
+  // add nothing the operator can act on, and printing `0` for `null` would be
+  // the false-negative this helper's three-state contract exists to prevent.
+  const backlog = typeof capped === 'number' && capped > 0 ? ` — ${capped} Learnings warten` : '';
+  return (
+    `path-scoped Regel-Decke zu ${pct} % belegt (${used}/${ceiling} B)${backlog} — ` +
+    '/reconcile wird Learnings zurueckhalten'
+  );
+}
+
 /**
  * Banner wrapper — session-start Phase 4 convention.
  *
@@ -1268,10 +1375,15 @@ export function computeInstructionBudget(opts = {}) {
  * @param {number} [opts.byteCeiling] explicit byte-ceiling override (wins over config).
  * @param {number} [opts.pathScopedByteCeiling] explicit path-scoped-ceiling override.
  * @returns {{ severity: 'warn', message: string } | null}
- *   null when disabled / off / every axis at-or-under its ceiling OR on any
- *   read failure. Since #1316 each of the four axes — directives, bytes,
+ *   null when disabled / off / every axis comfortably under its ceiling OR on
+ *   any read failure. Since #1316 each of the four axes — directives, bytes,
  *   generated, path-scoped — raises the banner on its own (see
- *   DEFAULT_PATH_SCOPED_BYTE_CEILING).
+ *   DEFAULT_PATH_SCOPED_BYTE_CEILING). Since #1419 the path-scoped axis ALSO
+ *   raises it at {@link PATH_SCOPED_NEAR_THRESHOLD} of its ceiling, before the
+ *   breach: that band used to be silent, and the ceiling then surfaced only
+ *   inside `writeApprovedRules` — after the operator had approved rules it
+ *   refused to write. The RETURN SHAPE is unchanged (`{severity:'warn',
+ *   message}` | null), so `session-start-probes.mjs` needs no new vocabulary.
  */
 export function checkInstructionBudget(opts = {}) {
   let cfg;
@@ -1331,7 +1443,33 @@ export function checkInstructionBudget(opts = {}) {
     return null; // never throw out of the banner wrapper
   }
 
-  if (!budget || !budget.overBudget) return null;
+  if (!budget) return null;
+
+  // #1419 near-threshold stage. Strictly BELOW the hard test (a breach is
+  // reported as a breach, never twice), and computed before the early return
+  // so a corpus at 90–100 % of the path-scoped ceiling stops being silent —
+  // that silence is the defect: the ceiling used to surface only inside
+  // `writeApprovedRules`, after the operator had already approved rules.
+  const nearPathScoped =
+    !budget.overPathScopedBudget &&
+    budget.pathScopedByteCeiling > 0 &&
+    budget.bySurface.pathScoped.bytes >= budget.pathScopedByteCeiling * PATH_SCOPED_NEAR_THRESHOLD;
+
+  if (!budget.overBudget && !nearPathScoped) return null;
+
+  const nearLine = nearPathScoped ? formatNearPathScopedLine(budget, opts.repoRoot) : null;
+
+  // Near-threshold and nothing breached: a one-finding banner, carrying the
+  // same remedy as the breach clause below (consolidate — never raise).
+  if (!budget.overBudget) {
+    return {
+      severity: 'warn',
+      message: [
+        `⚠ ${nearLine}.`,
+        '  Consolidate generated rules per docs/rule-authoring.md § Consolidated rules; never raise the ceiling.',
+      ].join('\n'),
+    };
+  }
 
   // Name only the breached axes — listing a healthy axis would pad the line
   // without telling the operator anything they must act on.
@@ -1377,8 +1515,12 @@ export function checkInstructionBudget(opts = {}) {
     .map((f) => `${f.file} (${f.count} dir, ${f.bytes} B)`)
     .join(', ');
 
+  // The near-threshold line rides ALONGSIDE the breach line rather than inside
+  // `axes`: the path-scoped axis is not over, and folding a healthy-but-close
+  // axis into a sentence that says "over" would misreport which ceiling broke.
   const message = [
     `⚠ Instruction budget over — ${axes.join(' · ')} across ${budget.perFile.length} always-on rules.`,
+    ...(nearLine ? [`  ${nearLine}.`] : []),
     `  Top files: ${top}`,
     '  See the instruction-budget audit (#687; archived in the private Meta-Vault) for the prune/demote list.',
   ].join('\n');