session-orchestrator 5.3.0 → 5.4.0

package/scripts/lib/owner-yaml.mjs

@@ -36,6 +36,16 @@
  *   dispatcher:             (optional; host-local cross-repo dispatcher autonomy override — #679)
  *     autonomy: string      ('' = no override; resolver enum off | advisory | autonomous-gated;
  *                            precedence env SO_DISPATCHER_AUTONOMY > this > committed > off)
+ *   vault-integration:      (optional; host-local switch for the vault-integration gate — SO#1448)
+ *     enabled: boolean      (false = off on this host; true is ignored — the host may not enable)
+ *     mode: 'off' | 'warn' | 'strict'  (applied only when weaker than the committed mode;
+ *                            precedence env SO_VAULT_INTEGRATION > this > committed.
+ *                            An invalid value drops ONLY this section, see loadOwnerConfig)
+ *   vault-dirs:             (optional list; per-directory vault-dir — agents/vault#319)
+ *     - path: string                       (the vault directory)
+ *       match: { path-prefix: string }     (required; cwd directory prefix, first match wins)
+ *       name: string                       (optional label, defaults to path)
+ *                            precedence env SO_VAULT_DIR > this > paths.vault-dir > committed
  *
  * ── Exports ───────────────────────────────────────────────────────────────────
  *
@@ -44,7 +54,8 @@
  *   validateOwnerSections(obj) — pure validation, no I/O; bucketed per section (#820)
  *   validateOwnerConfig(obj)   — pure validation, no I/O; thin wrapper over validateOwnerSections
  *   loadOwnerConfig({path?})   — reads file; per-section tolerance for OPTIONAL
- *                                sections (paths/dispatcher/vaults/baselines) — #820
+ *                                sections (paths/dispatcher/vault-integration/vaults/
+ *                                baselines/vault-dirs) — #820
  *   writeOwnerConfig(config, {path?}) — validates, writes YAML, creates dir
  *   getDefaults()              — returns sensible default config object
  *
@@ -202,9 +213,12 @@ const REQUIRED_SECTIONS = /** @type {const} */ (['owner', 'tone', 'efficiency',
  * sections — currently `scripts/lib/owner-config-banner.mjs`, which derived the
  * #1244 "survived a whole-file discard" set from a hand-mirrored local copy.
  * Frozen so a consumer cannot mutate the shared array.
+ *
+ * `vault-integration` has no `getDefaults()` entry: absent means "no host
+ * override", so a dropped section simply leaves the committed gate in force.
  */
 export const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (
-  Object.freeze(['paths', 'dispatcher'])
+  Object.freeze(['paths', 'dispatcher', 'vault-integration'])
 );
 
 /**
@@ -213,7 +227,10 @@ export const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (
  * `parseNamedVaults`/`parseBaselines` — that already drops bad entries with
  * its own WARN). Surfaced here only via `sectionWarnings`, never dropped.
  */
-const OPTIONAL_LIST_SECTIONS = /** @type {const} */ (['vaults', 'baselines']);
+const OPTIONAL_LIST_SECTIONS = /** @type {const} */ (['vaults', 'baselines', 'vault-dirs']);
+
+/** Host-settable vault-integration modes (mirrors VAULT_MODE_VALUES in config-schema.mjs). */
+const VALID_VAULT_INTEGRATION_MODES = ['off', 'warn', 'strict'];
 
 /** Canonical validation-order — MUST match the pre-#820 inline validation order. */
 const SECTION_ORDER = /** @type {const} */ ([
@@ -421,6 +438,35 @@ export function validateOwnerSections(obj) {
     sections.dispatcher = { valid: errors.length === 0, errors };
   }
 
+  // ── vault-integration (optional; host-local gate switch — SO#1448) ──────────
+  // STRICT enum validation, unlike `dispatcher`: a typo like `mode: of` must not
+  // fall through to the committed `strict` silently while the operator believes
+  // the host is off. An invalid section is dropped (and reported) on its own —
+  // `paths` and every other section survive (#820 per-section tolerance).
+  {
+    const errors = [];
+    const vi = obj['vault-integration'];
+    if (vi !== undefined && vi !== null) {
+      if (!isPlainObject(vi)) {
+        errors.push('vault-integration must be an object when present');
+      } else {
+        if (vi.enabled !== undefined && vi.enabled !== null && typeof vi.enabled !== 'boolean') {
+          errors.push(`vault-integration.enabled must be a boolean, got: ${typeof vi.enabled}`);
+        }
+        if (
+          vi.mode !== undefined &&
+          vi.mode !== null &&
+          !VALID_VAULT_INTEGRATION_MODES.includes(vi.mode)
+        ) {
+          errors.push(
+            `vault-integration.mode must be one of ${VALID_VAULT_INTEGRATION_MODES.join(', ')}, got: ${JSON.stringify(vi.mode)}`,
+          );
+        }
+      }
+    }
+    sections['vault-integration'] = { valid: errors.length === 0, errors };
+  }
+
   // ── vaults (optional; N named vaults for walk-up resolution — #700) ──────────
   // Drop-and-WARN on malformed entries is handled by parseNamedVaults() in
   // named-vault-resolver.mjs. Here we only validate the container shape to
@@ -512,6 +558,47 @@ export function validateOwnerSections(obj) {
     sections.baselines = { valid: errors.length === 0, errors };
   }
 
+  // ── vault-dirs (optional; per-directory vault-dir — agents/vault#319) ────────
+  // Same entry shape as baselines: (and parsed by the same parseBaselines() with
+  // section 'vault-dirs'), except `name` is optional. List section: surfaced via
+  // sectionWarnings, never dropped — the resolver drops bad entries itself.
+  {
+    const errors = [];
+    const vaultDirs = obj['vault-dirs'];
+    if (vaultDirs !== undefined && vaultDirs !== null) {
+      if (!Array.isArray(vaultDirs)) {
+        errors.push('vault-dirs must be an array when present');
+      } else {
+        for (let i = 0; i < vaultDirs.length; i++) {
+          const entry = vaultDirs[i];
+          if (!isPlainObject(entry)) {
+            errors.push(`vault-dirs[${i}] must be an object`);
+            continue;
+          }
+          if (typeof entry.path !== 'string' || entry.path.trim() === '') {
+            errors.push(`vault-dirs[${i}].path must be a non-empty string`);
+          }
+          if (
+            entry.name !== undefined &&
+            entry.name !== null &&
+            (typeof entry.name !== 'string' || entry.name.trim() === '')
+          ) {
+            errors.push(`vault-dirs[${i}].name must be a non-empty string when present`);
+          }
+          if (!isPlainObject(entry.match)) {
+            errors.push(`vault-dirs[${i}].match must be an object`);
+          } else if (
+            typeof entry.match['path-prefix'] !== 'string' ||
+            entry.match['path-prefix'].trim() === ''
+          ) {
+            errors.push(`vault-dirs[${i}].match.path-prefix must be a non-empty string`);
+          }
+        }
+      }
+    }
+    sections['vault-dirs'] = { valid: errors.length === 0, errors };
+  }
+
   const errors = SECTION_ORDER.flatMap((name) => sections[name].errors);
   return { sections, errors };
 }
@@ -540,10 +627,10 @@ export function validateOwnerConfig(obj) {
  * Per-section tolerance (#820): an invalid REQUIRED section (owner, tone,
  * efficiency, hardware-sharing) still discards the whole file (legacy
  * behaviour, unchanged). An invalid OPTIONAL object section (paths,
- * dispatcher) is instead replaced by its default value — the rest of the
+ * dispatcher, vault-integration) is instead replaced by its default value — the rest of the
  * file survives, `source` becomes `'partial'`, and the drop is reported via
  * `droppedSections` + a stderr WARN. OPTIONAL list sections (vaults,
- * baselines) are passed through UNTOUCHED even when strict-invalid — their
+ * baselines, vault-dirs) are passed through UNTOUCHED even when strict-invalid — their
  * consumers already run a lenient parse-at-point-of-use pass — and are
  * surfaced only via `sectionWarnings` (never dropped, never counted towards
  * `'partial'`).
@@ -658,6 +745,14 @@ export function loadOwnerConfig(opts = {}) {
         discardDropped.push({ section: name, errors: sec.errors });
       }
     }
+    // `vault-dirs:` (agents/vault#319) survives the discard too, raw — exactly as
+    // on the required-valid branch below; parseBaselines() drops bad entries at
+    // point-of-use. Dropping it would hand a repo under a declared prefix the
+    // host-wide `paths.vault-dir` (which DOES survive above): the silent vault
+    // override #319 exists to prevent, triggered by an unrelated `tone:` typo.
+    if (parsed['vault-dirs'] !== undefined && parsed['vault-dirs'] !== null) {
+      discardConfig['vault-dirs'] = parsed['vault-dirs'];
+    }
     const discardResult = { config: discardConfig, source: 'defaults', errors: allErrors };
     if (discardDropped.length > 0) discardResult.droppedSections = discardDropped;
     return discardResult;
@@ -673,7 +768,10 @@ export function loadOwnerConfig(opts = {}) {
   for (const name of OPTIONAL_OBJECT_SECTIONS) {
     const sec = sections[name];
     if (sec && !sec.valid) {
-      config[name] = defaults[name];
+      // A section without a default (vault-integration) is removed, not set to
+      // `undefined`: js-yaml's dump rejects undefined values on a write-back.
+      if (defaults[name] === undefined) delete config[name];
+      else config[name] = defaults[name];
       droppedSections.push({ section: name, errors: sec.errors });
       const firstError = sec.errors[0] ?? 'invalid section';
       console.warn(

package/scripts/lib/persona-panel/catalog-loader.mjs

@@ -261,7 +261,7 @@ export function validatePersonaSpec(rawSpec, sourcePath) {
       pushError(
         'model',
         'enum',
-        `model must be one of ${[...ALLOWED_MODEL_ALIASES].join('|')} or a full model ID like "claude-opus-4-7" (got ${JSON.stringify(m)})`,
+        `model must be one of ${[...ALLOWED_MODEL_ALIASES].join('|')} or a full model ID like "claude-opus-5-5" (got ${JSON.stringify(m)})`,
       );
     }
   }

package/scripts/lib/process-group.mjs

@@ -27,20 +27,32 @@ import { createHash } from 'node:crypto';
 import {
   appendFileSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   readFileSync,
+  renameSync,
+  unlinkSync,
   writeFileSync,
 } from 'node:fs';
 import path from 'node:path';
 
-import { DEFAULT_KILL_GRACE_MS } from './wave-executor/dispatch-common.mjs';
-
 /**
- * Re-exported, never re-defined: the SIGTERM→SIGKILL grace is a repo
- * convention with its own named ceiling in `dispatch-common.mjs`. A second
- * literal here would drift from it silently.
+ * Grace period between SIGTERM and SIGKILL, in ms — the repo's one definition,
+ * used by the gate's group ladder here and by `wave-executor/foreign-dispatch.mjs`
+ * and `remote-dispatch.mjs` through `runChild` (`dispatch-common.mjs`).
+ *
+ * `child.kill('SIGTERM')` is a REQUEST: a child that installs a handler and
+ * ignores it never emits `close`, and `runChild`'s only resolve paths are
+ * `close` and `error` — so without escalation a wedged `cursor-agent` hangs
+ * `dispatchForeign` forever and takes the whole wave with it. SIGKILL is not
+ * catchable, so the escalation always terminates.
+ *
+ * Named ceiling (BV-004): 10 s is enough for a cooperative child to flush its
+ * stream-json tail and exit. Revisit if a well-behaved `cursor-agent` is ever
+ * measured needing longer than that to shut down — raise the constant, never
+ * drop the escalation.
  */
-export { DEFAULT_KILL_GRACE_MS };
+export const DEFAULT_KILL_GRACE_MS = 10_000;
 
 /** Append-only ledger of every gate process THIS repo's orchestrator started.
  * Gitignored via `.gitignore:125` (`.orchestrator/runtime/`), verified with
@@ -572,7 +584,42 @@ export function readGateProcessLedger(repoRoot, {
 }
 
 /**
- * Drop expired and unusable lines from the ledger, rewriting it in place.
+ * Replace a regular file's contents atomically: write `<target>.tmp-<pid>` in
+ * the same directory, then rename it over the target. Throws instead of
+ * writing when the target is a symlink or not a regular file — the caller turns
+ * that into its one WARN line.
+ *
+ * Why not `writeFileSync(target)`: that truncates first, so a kill between the
+ * truncate and the write leaves the file empty, and it FOLLOWS a symlink — a
+ * ledger linked to `events.jsonl` emptied the link's target (CWE-59, reproduced
+ * 2026-10-01). `rename` replaces the directory entry itself, never a link's
+ * target, and the `wx` flag refuses a pre-planted file or link at the tmp name.
+ * Kept local, not imported, because this module deliberately has no local
+ * imports; `orphan-reaper/reaper-audit.mjs` carries the same few lines.
+ *
+ * @param {string} target
+ * @param {string} body
+ * @param {{lstatSync: Function, writeFileSync: Function, renameSync: Function, unlinkSync: Function}} io
+ */
+function replaceRegularFile(target, body, io) {
+  if (!io.lstatSync(target).isFile()) {
+    throw new Error('not a regular file (a symlink is never written through) — left untouched');
+  }
+  const tmp = `${target}.tmp-${process.pid}`;
+  try {
+    io.writeFileSync(tmp, body, { encoding: 'utf8', flag: 'wx' });
+    io.renameSync(tmp, target);
+  } catch (err) {
+    // EEXIST: the tmp name belongs to someone else — never remove it.
+    if (err?.code !== 'EEXIST') {
+      try { io.unlinkSync(tmp); } catch { /* nothing was created */ }
+    }
+    throw err;
+  }
+}
+
+/**
+ * Drop expired and unusable lines from the ledger, rewriting it atomically.
  * "Unusable" is {@link isValidLedgerRecord}'s verdict — the same one
  * {@link readGateProcessLedger} applies, so nothing the reader skips survives
  * the pruner.
@@ -583,6 +630,8 @@ export function readGateProcessLedger(repoRoot, {
  *
  * In-process fs only — never a shell `rm`/`mv` (PSA-003, and
  * `.orchestrator/metrics/**` deletions are a blocked-command rule for a reason).
+ * The rewrite goes through {@link replaceRegularFile}: a symlinked or
+ * non-regular ledger is refused with one WARN and left untouched.
  *
  * Named ceiling (BV-004): read-filter-write is not atomic against a concurrent
  * append, so a line appended between the read and the write is lost. Acceptable
@@ -595,16 +644,18 @@ export function readGateProcessLedger(repoRoot, {
  * @param {object} [opts]
  * @param {number} [opts.nowMs]
  * @param {number} [opts.maxAgeMs]
- * @param {{existsSync: Function, readFileSync: Function, writeFileSync: Function}} [opts.fs]  fs seam.
+ * @param {{existsSync: Function, readFileSync: Function, writeFileSync: Function,
+ *   lstatSync: Function, renameSync: Function, unlinkSync: Function}} [opts.fs]  fs seam;
+ *   replaces `node:fs` wholesale, so a partial seam fails closed (WARN, 0).
  * @returns {number} Number of lines removed (expired + malformed). 0 when the
- *   ledger is absent, empty, or unreadable.
+ *   ledger is absent, empty, unreadable, or not a regular file.
  */
 export function pruneGateProcessLedger(repoRoot, {
   nowMs = Date.now(),
   maxAgeMs = DEFAULT_LEDGER_MAX_AGE_MS,
   fs: fsSeam,
 } = {}) {
-  const io = fsSeam ?? { existsSync, readFileSync, writeFileSync };
+  const io = fsSeam ?? { existsSync, readFileSync, writeFileSync, lstatSync, renameSync, unlinkSync };
   const target = ledgerPathFor(repoRoot);
   let raw;
   try {
@@ -634,7 +685,7 @@ export function pruneGateProcessLedger(repoRoot, {
 
   if (removed === 0) return 0;
   try {
-    io.writeFileSync(target, kept.length > 0 ? `${kept.join('\n')}\n` : '', 'utf8');
+    replaceRegularFile(target, kept.length > 0 ? `${kept.join('\n')}\n` : '', io);
   } catch (err) {
     process.stderr.write(
       `process-group: could not prune ${GATE_PROCESS_LEDGER_RELPATH}: ${err?.message ?? String(err)}\n`,

package/scripts/lib/project-hygiene.mjs

@@ -462,7 +462,9 @@ export function checkStaleArtifacts(repoRoot, ageDays = DEFAULT_ARTIFACT_AGE_DAY
  * H4 — CI configuration hygiene.
  *
  * Measured 5/6. Checks locally declared executable commands without evaluating
- * pipeline conditions or external includes. The dependency-audit gap is the load-bearing one: three
+ * pipeline conditions or external includes; when no local audit step is found
+ * but `.gitlab-ci.yml` declares `include:`, the finding is downgraded to an
+ * unverifiable, non-fixable one. The dependency-audit gap is the load-bearing one: three
  * of the tested repos carried known-vulnerable dependencies that no pipeline
  * would ever surface.
  *
@@ -506,6 +508,24 @@ export function checkCiConfig(repoRoot) {
   }
 
   if (ciConfigs.some(({ text }) => text) && !ciConfigs.some(hasAuditStep)) {
+    // Jobs supplied via include: (component/local/project/remote/template) are
+    // never resolved, so an audit may exist there — report it as unverifiable.
+    let includes = 0;
+    try {
+      const gitlabText = hasGitlab ? ciConfigs[0].text : '';
+      const include = yaml.loadAll(gitlabText, undefined, { schema: GITLAB_SCHEMA }).filter(isConfigMap).at(-1)?.include;
+      includes = Array.isArray(include) ? include.length : include ? 1 : 0;
+    } catch {
+      /* unparseable config — keep the plain missing-audit finding */
+    }
+    if (includes > 0) {
+      findings.push({
+        check: 'ci-audit-job',
+        fixable: false,
+        message: `CI dependency-audit step could not be verified: ${includes} include(s) not evaluated (.gitlab-ci.yml include:)`,
+      });
+      return findings;
+    }
     findings.push({
       check: 'ci-audit-job',
       fixable: true,

package/scripts/lib/quality-gate.mjs

@@ -63,7 +63,7 @@
 
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { emitEvent, sessionAttribution } from './events.mjs';
@@ -120,7 +120,8 @@ const GATE_TIMEOUT_MS = DEFAULT_GATE_TIMEOUT_MS;
  * @returns {string}
  */
 function resolveRepoRoot(explicit) {
-  if (typeof explicit === 'string' && explicit.trim()) return explicit;
+  // Absolute on purpose: emitEvent refuses a relative root (#1468).
+  if (typeof explicit === 'string' && explicit.trim()) return resolve(explicit);
   return process.cwd();
 }
 
@@ -773,13 +774,44 @@ function coerceMaxRetries(n) {
 // Public API
 // ---------------------------------------------------------------------------
 
+/**
+ * The kill-ladder fields of a `quality_gate.passed/.failed` record (#1439).
+ *
+ * ONE builder for BOTH emitters — this library's {@link emitGateEvent} and the
+ * `scripts/run-quality-gate.mjs` CLI — so the two can never publish different
+ * shapes under the same keys. From THIS builder all three keys are always
+ * present: `timed_out` `false`, `survivors` `0` and `kill_signals` `[]` are
+ * measurements ("not killed"), unlike `counts`, whose absence means "not
+ * measured". The CLI then passes the result through `joinGateKillFields()`
+ * (`scripts/lib/gates/gate-helpers.mjs`, #1457), which OR-joins the inner
+ * per-command ladders and MAY omit the three keys when that inner side was
+ * not measured and the outer ladder did not fire.
+ *
+ * - `timed_out` — the run hit its wall-clock ceiling and was killed (exit 124).
+ * - `survivors` — how many pids were still alive after the SIGKILL step; the
+ *   pids themselves stay in the gate output / diagnostics bundle.
+ * - `kill_signals` — the signals actually sent, in order (`SIGTERM`, `SIGKILL`).
+ *   Copied, because `spawnInGroup` records them at send time into a live array.
+ *
+ * @param {{timedOut?: boolean, killSignals?: string[], survivors?: number[]}|null|undefined} run
+ * @returns {{timed_out: boolean, survivors: number, kill_signals: string[]}}
+ */
+export function gateKillFields(run) {
+  return {
+    timed_out: run?.timedOut === true,
+    survivors: Array.isArray(run?.survivors) ? run.survivors.length : 0,
+    kill_signals: Array.isArray(run?.killSignals) ? [...run.killSignals] : [],
+  };
+}
+
 /**
  * Emit exactly one `orchestrator.quality_gate.{passed,failed}` event per
  * `runQualityGateWithRetry` CALL (#928b).
  *
  * NO DOUBLE-COUNTING. The two gate paths never nest:
  *   - `scripts/run-quality-gate.mjs` spawns `scripts/lib/gates/gate-*.mjs`
- *     directly and does not import this module;
+ *     directly; it imports only the pure `gateKillFields` helper from this
+ *     module, never `runQualityGateWithRetry`, so it never reaches this emitter;
  *   - this module spawns the resolved gate COMMANDS (and `parse-config.mjs`)
  *     directly and does not invoke that wrapper.
  * A single run therefore passes through exactly one emitter.
@@ -846,8 +878,13 @@ function coerceMaxRetries(n) {
  * @param {number} attempts
  * @param {string|null} gate
  * @param {{passed: number, failed: number, total: number}|null} [counts]
+ * @param {{timedOut?: boolean, killSignals?: string[], survivors?: number[]}|null} [killRun]
+ *   the run that decided the verdict — the last attempt's failing gate; `null`
+ *   on the passing path, where every gate exited 0 and so none was killed
+ *   (`spawnInGroup` only starts its kill ladder on timeout or overflow, and
+ *   both force a non-zero exit code).
  */
-async function emitGateEvent(repoRoot, ok, attempts, gate, counts) {
+async function emitGateEvent(repoRoot, ok, attempts, gate, counts, killRun = null) {
   try {
     await emitEvent(
       `orchestrator.quality_gate.${ok ? 'passed' : 'failed'}`,
@@ -857,6 +894,7 @@ async function emitGateEvent(repoRoot, ok, attempts, gate, counts) {
         attempts,
         ...(gate ? { gate } : {}),
         ...(counts ? { counts } : {}),
+        ...gateKillFields(killRun),
         ...sessionAttribution(repoRoot),
       },
       { repoRoot },
@@ -985,6 +1023,8 @@ export async function runQualityGateWithRetry(opts) {
         exitCode: result.exitCode,
         output: result.output,
         timedOut: result.timedOut,
+        killSignals: result.killSignals,
+        survivors: result.survivors,
         command: cmd,
         attempt,
       };
@@ -1063,7 +1103,7 @@ export async function runQualityGateWithRetry(opts) {
     `❌ quality-gate exhausted retries (${attempt}), writing diagnostics to ${bundlePath ?? '<unwritable>'}\n`,
   );
 
-  await emitGateEvent(repoRoot, false, attempt, lastFailure?.gate ?? null, testCounts);
+  await emitGateEvent(repoRoot, false, attempt, lastFailure?.gate ?? null, testCounts, lastFailure);
 
   const out = {
     ok: false,

package/scripts/lib/resource-probe.mjs

@@ -49,7 +49,7 @@ import { ramSnapshot, cpuSnapshot, processCounts, swapUsedMb, memoryPressurePctF
 
 export { evaluate, PROCESSES_PER_SESSION, PRESSURE_HARD_PCT, PRESSURE_SOFT_PCT, PRESSURE_HEALTHY_PCT, DEFAULT_RESOURCE_THRESHOLDS } from './resource-probe/evaluate.mjs';
 export { peerSessionsCount } from './resource-probe/probe-platform.mjs';
-export { parseEtimeToMinutes, countZombieProcesses, countProcessMatches, parseSwapUsageOutput, parseMemoryPressureOutput, parseVmStatAvailableGb } from './resource-probe/parsers.mjs';
+export { parseEtimeToMinutes, parseEtimeToSeconds, countZombieProcesses, countProcessMatches, parseSwapUsageOutput, parseMemoryPressureOutput, parseVmStatAvailableGb } from './resource-probe/parsers.mjs';
 
 // ---------------------------------------------------------------------------
 // Public API — probe()