session-orchestrator 5.3.0 → 5.4.0

package/scripts/lib/config.mjs

@@ -78,8 +78,57 @@ import { _parseRemoteHosts } from './config/remote-hosts.mjs';
 import { _parseEvolve, _parseEvolveDecay } from './config/evolve.mjs';
 import { _parseSkillEvolution } from './config/skill-evolution.mjs';
 import { _parseDispatcherAutonomy, resolveDispatcherAutonomy } from './config/dispatcher-autonomy.mjs';
-import { loadHostPaths, resolveHostPath } from './config/host-paths.mjs';
+import { loadHostPaths, resolveHostPath, resolveVaultIntegrationHost } from './config/host-paths.mjs';
 import { resolveNamedBaseline } from './named-baseline-resolver.mjs';
+import { expandTilde } from './common.mjs';
+
+/**
+ * Resolve `vault-dir` and report which tier produced it (agents/vault#319).
+ *
+ * Precedence (highest first): SO_VAULT_DIR env > owner.yaml `vault-dirs:`
+ * path-prefix match against the cwd > owner.yaml `paths.vault-dir` > committed.
+ * The env tier stays on top because tests/setup/vault-guard.mjs relies on it to
+ * shadow every host-local vault for the whole suite.
+ *
+ * Lives here, not in config/host-paths.mjs: host-paths.mjs is a direct CP11
+ * helper of check-owner-leakage.mjs, whose standalone vendored copy carries only
+ * its three direct helpers. The named-baseline-resolver import edge would make
+ * CP11 fail closed there (tests/husky/pre-commit-owner-leakage.test.mjs).
+ *
+ * The two owner.yaml tiers (`match`, `owner`) come back tilde-expanded: owner.yaml
+ * is host-local and `~/…` is the natural way to write a path there, but consumers
+ * such as vault-mirror.mjs `existsSync(resolve(vaultDir))` would read a literal
+ * `~` as `<cwd>/~/…`. The `env` and `committed` tiers keep their pass-through;
+ * vault-mirror.mjs expands its `--vault-dir` at entry for every tier anyway.
+ *
+ * `cwd` in the ctx is a test-only DI seam; production reads `process.cwd()`.
+ *
+ * @param {string|null|undefined} committed — value the committed Session Config produced
+ * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object, cwd?: string }} [ctx] — from loadHostPaths()
+ * @returns {{ value: string|null|undefined, source: 'env'|'match'|'owner'|'committed' }}
+ */
+function resolveVaultDir(committed, { env = process.env, ownerConfig, cwd } = {}) {
+  const isNonBlank = (v) => typeof v === 'string' && v.trim() !== '';
+
+  const envVal = env?.SO_VAULT_DIR;
+  if (isNonBlank(envVal)) return { value: envVal, source: 'env' };
+
+  const matched = resolveNamedBaseline({
+    cwd: cwd ?? process.cwd(),
+    ownerConfig,
+    env,
+    section: 'vault-dirs',
+    envKey: 'SO_VAULT_DIR',
+  });
+  if (matched.source === 'match' && isNonBlank(matched.path)) {
+    return { value: expandTilde(matched.path), source: 'match' };
+  }
+
+  const ownerVal = ownerConfig?.paths?.['vault-dir'];
+  if (isNonBlank(ownerVal)) return { value: expandTilde(ownerVal), source: 'owner' };
+
+  return { value: committed, source: 'committed' };
+}
 // express-path lives one level UP from config/ (see its module header for why):
 // the parser is a sibling of config/state-md-lock.mjs in every respect except
 // its directory. Only the pure parser is imported here — `evaluateExpressPath`
@@ -114,8 +163,9 @@ export { readConfigFile } from './config/io.mjs';
  *   hermetic ctx (e.g. `{ env: {}, ownerConfig: undefined }`) when asserting COMMITTED values:
  *   the default reads the real `owner.yaml`, so a host-local `paths:` override would otherwise
  *   bleed into fixture assertions (incident: 2026-07-03 Full-Gate red after the operator set
- *   `paths.baseline-path` host-locally). `cwd` feeds the `baselines:` match tier (#819) — a
- *   test-only DI seam; production always resolves it from `process.cwd()`.
+ *   `paths.baseline-path` host-locally). `cwd` feeds the `baselines:` (#819) and
+ *   `vault-dirs:` (agents/vault#319) match tiers — a test-only DI seam; production
+ *   always resolves it from `process.cwd()`.
  * @returns {object} config object with EXACT same shape as parse-config.sh stdout
  * @throws if any enum value is invalid
  */
@@ -230,6 +280,9 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // heavy-repo / worktree-cleanup: HR-003 preflight fields (templates/shared/.claude/rules/heavy-repo.md),
   // documented but previously unwired — silently dropped by the parser (baseline issue #60).
   const heavyRepo = _coerceBoolean(kv, 'heavy-repo', false);
+  // offload-first (#1465): route offloadable wave roles to a ready remote host
+  // even on a `proceed` resource verdict (consumed by wave-resource-gate.mjs).
+  const offloadFirst = _coerceBoolean(kv, 'offload-first', false);
 
   // List fields
   const crossRepos = _coerceList(kv, 'cross-repos', undefined);
@@ -331,18 +384,25 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // vault-integration: parsed from full content (block-scoped, avoids the
   // pre-#593 KV-name collision where `enabled:` was shared with 15+ other
   // blocks like docs-orchestrator/vault-staleness/slopcheck).
-  const vaultIntegration = _parseVaultIntegration(mdContent);
-  // Host-local override (issue #653) — applied here, NOT inside _parseVaultIntegration,
-  // so claude-md-drift-check (which calls the parser directly) keeps seeing raw values.
-  vaultIntegration['vault-dir'] = resolveHostPath('vault-dir', vaultIntegration['vault-dir'], hostCtx);
+  // Host-local overrides — applied here, NOT inside _parseVaultIntegration, so
+  // claude-md-drift-check (which calls the parser directly) keeps seeing raw values.
+  //   - the enabled/mode switch (SO#1448): env SO_VAULT_INTEGRATION > owner.yaml
+  //     `vault-integration:` > committed, LOWER-ONLY; `host-override` names the tier.
+  //   - vault-dir (#653, agents/vault#319): env > owner.yaml `vault-dirs:` cwd match >
+  //     owner.yaml paths.vault-dir > committed; `vault-dir-source` names the tier.
+  const vaultIntegration = resolveVaultIntegrationHost(_parseVaultIntegration(mdContent), hostCtx);
+  const vaultIntegrationDir = resolveVaultDir(vaultIntegration['vault-dir'], hostCtx);
+  vaultIntegration['vault-dir'] = vaultIntegrationDir.value;
+  vaultIntegration['vault-dir-source'] = vaultIntegrationDir.source;
 
   // resource-thresholds sub-keys (v3.1.0 env-aware — issue #166)
   const resourceThresholds = _parseResourceThresholds(kv);
 
   // vault-sync: parsed from full content (can live outside Session Config)
   const vaultSync = _parseVaultSync(mdContent);
-  // Host-local override (issue #653) — same host source as vault-integration above.
-  vaultSync['vault-dir'] = resolveHostPath('vault-dir', vaultSync['vault-dir'], hostCtx);
+  // Host-local override (issue #653) — same resolver as vault-integration above, so the
+  // two blocks cannot disagree about which vault this repo writes to (agents/vault#319).
+  vaultSync['vault-dir'] = resolveVaultDir(vaultSync['vault-dir'], hostCtx).value;
 
   // drift-check: parsed from full content (standalone top-level block)
   const driftCheck = _parseDriftCheck(mdContent);
@@ -408,7 +468,7 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // dispatcher-autonomy: opt-in cross-repo dispatcher autonomy block (Epic #673 / issue #679).
   // Parser stays pure (raw committed value) for claude-md-drift-check raw-value parity;
   // the host-local override (env > owner.yaml > committed > off) is overlaid onto the
-  // FINAL object only — mirroring the vault-dir resolveHostPath pattern above. Reuses the
+  // FINAL object only — mirroring the vault-dir host-override pattern above. Reuses the
   // already-loaded hostCtx.ownerConfig so owner.yaml is not read twice.
   const dispatcherAutonomy = _parseDispatcherAutonomy(mdContent);
   dispatcherAutonomy.autonomy = resolveDispatcherAutonomy({
@@ -552,6 +612,7 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     'resource-awareness': resourceAwareness,
     'enable-host-banner': enableHostBanner,
     'heavy-repo': heavyRepo,
+    'offload-first': offloadFirst,
     'worktree-cleanup': worktreeCleanup,
     'resource-thresholds': resourceThresholds,
     'worktree-exclude': worktreeExclude,

package/scripts/lib/events.mjs

@@ -388,7 +388,11 @@ function waveForRecord(root, attribution) {
  *   metrics/events.jsonl` instead of the module-level `SO_PROJECT_DIR` default
  *   (#941). Ignored when `opts.filePath` is given (explicit path wins). This is
  *   the clean interface replacing the hand-built `join(repoRoot, …)` recipes that
- *   used to open-code this destination at each call-site.
+ *   used to open-code this destination at each call-site. A relative or empty
+ *   `repoRoot` is refused with one stderr WARN and nothing is written (no line,
+ *   no directory, no webhook): joining it would land relative to the working
+ *   directory — the incident class where an unset env var produced
+ *   `undefined/…/.orchestrator/metrics/events.jsonl` under the cwd.
  * @returns {Promise<void>}
  */
 export async function emitEvent(type, payload = {}, opts = {}) {
@@ -434,11 +438,26 @@ export async function emitEvent(type, payload = {}, opts = {}) {
 
   // Ensure the destination directory exists before appending. Resolution order:
   //   1. explicit opts.filePath (a pre-resolved path — #611)
-  //   2. opts.repoRoot → <repoRoot>/.orchestrator/metrics/events.jsonl (#941)
+  //   2. opts.repoRoot → <repoRoot>/.orchestrator/metrics/events.jsonl (#941),
+  //      or refused when relative/empty (WARN, no write — see below)
   //   3. the SO_PROJECT_DIR default (unchanged for 2-arg callers)
   // eventsFilePath(undefined) falls through to its SO_PROJECT_DIR default, so a
   // caller passing neither behaves EXACTLY as before (additive) — except under
   // the test-only EVENTS_LEDGER_SANDBOX_ENV seam, which only 3. honours.
+  // An explicit filePath is never second-guessed. A defined repoRoot that is not
+  // absolute would be joined relative to the cwd, so it is refused: WARN and
+  // return (hooks must never throw). The value itself is not printed — it may
+  // carry a host-local path.
+  if (
+    opts.filePath === undefined &&
+    opts.repoRoot !== undefined &&
+    (typeof opts.repoRoot !== 'string' || !path.isAbsolute(opts.repoRoot))
+  ) {
+    process.stderr.write(
+      `[events] ${String(type)} not emitted: opts.repoRoot is not an absolute path; refusing to write relative to the working directory.\n`,
+    );
+    return;
+  }
   const filePath = opts.filePath ?? eventsFilePath(opts.repoRoot);
   await fs.mkdir(path.dirname(filePath), { recursive: true });
   await fs.appendFile(filePath, line, 'utf8');

package/scripts/lib/fleet-protocol.mjs

@@ -0,0 +1,270 @@
+/**
+ * fleet-protocol.mjs — Fleet protocol v1: file-based navigator lease + session
+ * check-ins under `~/.config/navigator/` (#1462, PRD !53 § 3).
+ *
+ * The protocol state lives in plain files so every platform (Claude Code, Codex,
+ * a headless run) can read and write it without a server:
+ *
+ *   <navigatorDir>/leases/navigator.json        — the navigator lease
+ *   <navigatorDir>/checkin/<session_id>.json    — one check-in per session
+ *   <navigatorDir>/auflagen/<session_id>.json   — conditions issued to a session
+ *
+ * `<navigatorDir>` is `NAVIGATOR_CONFIG_DIR` (trimmed; empty/whitespace counts as
+ * unset) or `<home>/.config/navigator`. Files are 0600, directories 0700,
+ * timestamps `date -u +%FT%TZ` (`YYYY-MM-DDTHH:MM:SSZ`).
+ *
+ * "A navigator is active" means exactly one thing: a readable, well-formed lease
+ * whose `laeuft_ab` lies in the future. Everything else is fail-closed — an
+ * expired lease is `none`, a lease that cannot be read or validated is
+ * `unreadable`, and neither is ever `active`.
+ *
+ * Session ids become file names, so {@link isSafeSessionId} is the security
+ * boundary between check-in input and the filesystem: every path builder that
+ * takes a session id refuses an unsafe one with a TypeError.
+ */
+
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Env var that overrides the navigator directory. */
+export const NAVIGATOR_CONFIG_DIR_ENV = 'NAVIGATOR_CONFIG_DIR';
+
+/** Minutes a session waits for a navigator before it falls back (PRD !53 § 3). */
+export const CHECKIN_FALLBACK_MIN = 10;
+
+const SESSION_ID_RE = /^[A-Za-z0-9._-]+$/;
+const SESSION_ID_MAX = 128;
+const UTC_SECONDS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+
+/** Lease timestamps: UTC with `Z`, seconds or milliseconds — never a local-time reading. */
+const LEASE_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+
+const PLATTFORMEN = ['claude', 'codex', 'kopflos'];
+const MODI = ['housekeeping', 'feature', 'deep', 'operations'];
+
+/**
+ * Resolve the navigator directory.
+ * @param {{ env?: Record<string, string|undefined>, home?: string }} [opts]
+ * @returns {string} absolute path
+ */
+export function navigatorDir({ env = process.env, home = os.homedir() } = {}) {
+  const raw = env[NAVIGATOR_CONFIG_DIR_ENV];
+  const override = typeof raw === 'string' ? raw.trim() : '';
+  if (override) return path.resolve(override);
+  return path.join(home, '.config', 'navigator');
+}
+
+/**
+ * Path of the navigator lease file.
+ * @param {{ env?: Record<string, string|undefined>, home?: string }} [opts]
+ * @returns {string}
+ */
+export function leasePath(opts) {
+  return path.join(navigatorDir(opts), 'leases', 'navigator.json');
+}
+
+/**
+ * True when `id` is safe to use as a single file-name component: only
+ * `[A-Za-z0-9._-]`, 1..128 chars, and not `.` / `..`. This excludes `/`, `\`,
+ * NUL and every other separator by construction.
+ * @param {unknown} id
+ * @returns {boolean}
+ */
+export function isSafeSessionId(id) {
+  return (
+    typeof id === 'string' &&
+    id.length > 0 &&
+    id.length <= SESSION_ID_MAX &&
+    id !== '.' &&
+    id !== '..' &&
+    SESSION_ID_RE.test(id)
+  );
+}
+
+/** @param {unknown} sessionId */
+function assertSafeSessionId(sessionId) {
+  if (!isSafeSessionId(sessionId)) {
+    throw new TypeError(`unsafe session id: ${JSON.stringify(String(sessionId)).slice(0, 80)}`);
+  }
+}
+
+/**
+ * Path of a session's check-in file.
+ * @param {string} sessionId
+ * @param {{ env?: Record<string, string|undefined>, home?: string }} [opts]
+ * @returns {string}
+ * @throws {TypeError} when `sessionId` fails {@link isSafeSessionId}
+ */
+export function checkinPath(sessionId, opts) {
+  assertSafeSessionId(sessionId);
+  return path.join(navigatorDir(opts), 'checkin', `${sessionId}.json`);
+}
+
+/**
+ * Path of a session's conditions ("Auflagen") file.
+ * @param {string} sessionId
+ * @param {{ env?: Record<string, string|undefined>, home?: string }} [opts]
+ * @returns {string}
+ * @throws {TypeError} when `sessionId` fails {@link isSafeSessionId}
+ */
+export function auflagenPath(sessionId, opts) {
+  assertSafeSessionId(sessionId);
+  return path.join(navigatorDir(opts), 'auflagen', `${sessionId}.json`);
+}
+
+/**
+ * Format a date as `YYYY-MM-DDTHH:MM:SSZ` (the output of `date -u +%FT%TZ`).
+ * @param {Date} [date]
+ * @returns {string}
+ */
+export function utcSecondsTimestamp(date = new Date()) {
+  return date.toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+/** @param {unknown} v */
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** @param {unknown} v */
+function isNonEmptyString(v) {
+  return typeof v === 'string' && v.length > 0;
+}
+
+/** @param {unknown} v */
+function isIsoTimestamp(v) {
+  return typeof v === 'string' && !Number.isNaN(Date.parse(v));
+}
+
+function isLeaseTimestamp(v) {
+  return typeof v === 'string' && LEASE_TS_RE.test(v) && isIsoTimestamp(v);
+}
+
+const REQUIRED_CHECKIN_FIELDS = [
+  'session', 'plattform', 'repo', 'modus', 'auftrag_ref',
+  'kandidaten', 'schreibbereich', 'rueckfall', 'zeit',
+];
+
+/** Repo name shape accepted in a check-in: `name` or `group/name`, no path parts. */
+const REPO_NAME_RE = /^[A-Za-z0-9._-]{1,100}(?:\/[A-Za-z0-9._-]{1,100})?$/;
+
+/** Lease `adresse` shape (a ListAgents peer name): no whitespace, no control bytes. */
+const ADRESSE_RE = /^[A-Za-z0-9._:@-]{1,128}$/;
+
+/** True for an issue reference: a non-negative integer or a `#123` / `123` string. */
+function isIssueRef(v) {
+  if (typeof v === 'number') return Number.isInteger(v) && v >= 0;
+  return typeof v === 'string' && /^#?\d{1,9}$/.test(v);
+}
+
+/**
+ * Per-field type checks. Each returns an error message or null. Applied to every
+ * PRESENT field; presence of the required ones is checked separately.
+ * @type {Record<string, (v: unknown) => string|null>}
+ */
+const CHECKIN_FIELD_CHECKS = {
+  session: (v) =>
+    isSafeSessionId(v) ? null : 'session must be a safe id: [A-Za-z0-9._-], 1..128 chars, not . or ..',
+  plattform: (v) => (PLATTFORMEN.includes(/** @type {string} */ (v)) ? null : `plattform must be one of ${PLATTFORMEN.join('|')}`),
+  // A repo NAME (optionally `group/name`), never a filesystem path: the value
+  // travels in `orchestrator.fleet.checkin`, which may leave the host over the
+  // optional events webhook (docs/events-schema.md: "never the absolute root").
+  repo: (v) => (typeof v === 'string' && REPO_NAME_RE.test(v) ? null : 'repo must be a repo name [A-Za-z0-9._-] (optionally group/name), not a path'),
+  repo_id: (v) => (v === null || typeof v === 'string' ? null : 'repo_id must be a string or null'),
+  worktree: (v) => (typeof v === 'boolean' ? null : 'worktree must be a boolean'),
+  modus: (v) => (MODI.includes(/** @type {string} */ (v)) ? null : `modus must be one of ${MODI.join('|')}`),
+  auftrag_ref: (v) => (isNonEmptyString(v) ? null : 'auftrag_ref must be a non-empty string'),
+  konto_slot: (v) =>
+    v === null || typeof v === 'string' || (typeof v === 'number' && Number.isFinite(v))
+      ? null
+      : 'konto_slot must be a number, a string or null',
+  quota: (v) => (typeof v === 'string' ? null : 'quota must be a string'),
+  stand: (v) => (isPlainObject(v) ? null : 'stand must be an object'),
+  // Issue numbers only (42 or "#42"), at most 64 — same webhook reasoning as `repo`.
+  kandidaten: (v) =>
+    Array.isArray(v) && v.length <= 64 && v.every(isIssueRef)
+      ? null
+      : 'kandidaten must be an array of at most 64 issue numbers (42 or "#42")',
+  schreibbereich: (v) =>
+    Array.isArray(v) && v.every((e) => typeof e === 'string') ? null : 'schreibbereich must be an array of strings',
+  bedarf: (v) => (isPlainObject(v) ? null : 'bedarf must be an object'),
+  vorab_geschrieben: (v) => (Array.isArray(v) ? null : 'vorab_geschrieben must be an array'),
+  rueckfall: (v) => (isNonEmptyString(v) ? null : 'rueckfall must be a non-empty string'),
+  zeit: (v) =>
+    typeof v === 'string' && UTC_SECONDS_RE.test(v) && isIsoTimestamp(v)
+      ? null
+      : 'zeit must be a UTC timestamp YYYY-MM-DDTHH:MM:SSZ',
+};
+
+/**
+ * Validate a check-in record (PRD !53 table 3.2).
+ * @param {unknown} obj
+ * @returns {string[]} error messages; empty means valid
+ */
+export function validateCheckin(obj) {
+  if (!isPlainObject(obj)) return ['check-in must be a JSON object'];
+  const rec = /** @type {Record<string, unknown>} */ (obj);
+  const errors = [];
+  for (const field of REQUIRED_CHECKIN_FIELDS) {
+    if (rec[field] === undefined) errors.push(`missing required field: ${field}`);
+  }
+  for (const [field, check] of Object.entries(CHECKIN_FIELD_CHECKS)) {
+    if (rec[field] === undefined) continue;
+    const err = check(rec[field]);
+    if (err) errors.push(err);
+  }
+  return errors;
+}
+
+/**
+ * Validate a parsed lease; returns the first problem or null.
+ * @param {unknown} lease
+ * @returns {string|null}
+ */
+function leaseProblem(lease) {
+  if (!isPlainObject(lease)) return 'lease is not a JSON object';
+  const l = /** @type {Record<string, unknown>} */ (lease);
+  // Shape-checked at the source ("escaped at generation"): both values can reach
+  // the operator's session-start banner, so control bytes are refused here.
+  if (!isSafeSessionId(l.session_id)) return 'lease.session_id missing or not a safe id';
+  if (!PLATTFORMEN.includes(/** @type {string} */ (l.plattform))) return `lease.plattform must be one of ${PLATTFORMEN.join('|')}`;
+  if (l.adresse !== undefined && l.adresse !== null && !(typeof l.adresse === 'string' && ADRESSE_RE.test(l.adresse))) {
+    return 'lease.adresse must be null or a peer name [A-Za-z0-9._:@-] (1..128 chars)';
+  }
+  if (l.uebergabe_an !== undefined && l.uebergabe_an !== null && typeof l.uebergabe_an !== 'string') {
+    return 'lease.uebergabe_an must be a string or null';
+  }
+  // Strict UTC form: a `Z`-less value would be read in the host's local time and
+  // could EXTEND the lease west of UTC — a fail-open reading, hence unreadable.
+  if (!isLeaseTimestamp(l.seit)) return 'lease.seit missing or not a UTC timestamp (…Z)';
+  if (!isLeaseTimestamp(l.laeuft_ab)) return 'lease.laeuft_ab missing or not a UTC timestamp (…Z)';
+  return null;
+}
+
+/**
+ * Read the navigator lease. Never throws; fail-closed.
+ *
+ * @param {{ now?: number, env?: Record<string, string|undefined>, home?: string }} [opts]
+ * @returns {Promise<{ state: 'active', lease: object } | { state: 'none' } | { state: 'unreadable', reason: string }>}
+ */
+export async function readNavigatorLease({ now = Date.now(), env, home } = {}) {
+  let raw;
+  try {
+    raw = await fs.readFile(leasePath({ env, home }), 'utf8');
+  } catch (err) {
+    if (err && /** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return { state: 'none' };
+    const code = err && /** @type {NodeJS.ErrnoException} */ (err).code;
+    return { state: 'unreadable', reason: `read failed: ${code || 'unknown error'}` };
+  }
+  let lease;
+  try {
+    lease = JSON.parse(raw);
+  } catch {
+    return { state: 'unreadable', reason: 'lease is not valid JSON' };
+  }
+  const problem = leaseProblem(lease);
+  if (problem) return { state: 'unreadable', reason: problem };
+  if (Date.parse(lease.laeuft_ab) <= now) return { state: 'none' };
+  return { state: 'active', lease };
+}

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

@@ -5,7 +5,7 @@
 // Required env: TYPECHECK_CMD, TEST_CMD
 // Each may equal "skip" or empty string → treated as skip.
 
-import { runCheck } from './gate-helpers.mjs';
+import { runCheck, commandKillFields } from './gate-helpers.mjs';
 
 const typecheckCmd = process.env.TYPECHECK_CMD;
 const testCmd = process.env.TEST_CMD;
@@ -57,8 +57,18 @@ if (testCmd !== 'skip') {
 
 const result = {
   variant: 'baseline',
-  typecheck: tcResult.status,
-  test: testResult.status,
+  // 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 } : {}),
+  },
   typecheck_output: tcResult.output,
   test_output: testResult.output,
 };

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

@@ -11,6 +11,7 @@ import {
   extractTestCounts,
   extractFailedTestFiles,
   collectDebugArtifacts,
+  commandKillFields,
 } from './gate-helpers.mjs';
 
 const typecheckCmd = process.env.TYPECHECK_CMD;
@@ -145,7 +146,10 @@ if (lintResult.stubbed) stubbed.lint = lintResult.stubbed;
 const output = {
   variant: 'full-gate',
   duration_seconds: durationSeconds,
-  typecheck: { status: tcResult.status, error_count: tcErrorCount },
+  // 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, error_count: tcErrorCount, ...commandKillFields(tcResult) },
   // `failed` is published explicitly (#967 item 1) rather than left to be
   // re-derived as `total - passed` downstream: the derivation and the parse can
   // disagree, and only an explicit third number lets a consumer check
@@ -161,8 +165,9 @@ const output = {
     // read just passed/failed/total, so the stdout JSON contract stays one
     // document and the test-case triple keeps `total === passed + failed`.
     ...fileFields,
+    ...commandKillFields(testResult),
   },
-  lint: { status: lintResult.status, warnings: lintWarnings },
+  lint: { status: lintResult.status, warnings: lintWarnings, ...commandKillFields(lintResult) },
   debug_artifacts: debugArtifacts,
   stubbed,
 };

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

@@ -123,6 +123,95 @@ export function gateTimeoutEnvelope({ variant, timeoutMs, run }) {
   };
 }
 
+/**
+ * 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.
@@ -614,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