session-orchestrator 5.3.0 → 5.5.0

package/scripts/lib/fleet-protocol.mjs

@@ -0,0 +1,288 @@
+/**
+ * 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.
+ * Check-in and lease timestamps are UTC with `Z`, in a form per file: the
+ * check-in's `zeit` is seconds, `date -u +%FT%TZ` (`YYYY-MM-DDTHH:MM:SSZ`,
+ * stamped by the CLI); the lease's `seit` / `laeuft_ab` are seconds or
+ * milliseconds (`LEASE_TS_RE`); the auflagen content belongs to the navigator.
+ *
+ * "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');
+}
+
+/**
+ * When the Standard-Auflagen apply to a check-in written at `zeit` if no
+ * `auflagen/<session_id>.json` has appeared: {@link CHECKIN_FALLBACK_MIN} later
+ * while a navigator is active (it may still write one), and at `zeit` itself
+ * otherwise — with no active navigator nobody will, so the fallback is due at
+ * once (#1501 item 8: this deadline lived only as prose in session-start).
+ * @param {string} zeit the check-in's `zeit`, as {@link utcSecondsTimestamp} writes it
+ * @param {'active'|'none'|'unreadable'} navigatorState from {@link readNavigatorLease}
+ * @returns {string} same form as `zeit`
+ */
+export function fallbackDueAt(zeit, navigatorState) {
+  if (navigatorState !== 'active') return zeit;
+  return utcSecondsTimestamp(new Date(Date.parse(zeit) + CHECKIN_FALLBACK_MIN * 60_000));
+}
+
+/** @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

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

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

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

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

package/scripts/lib/hardening.mjs

@@ -34,6 +34,7 @@ export { assertNodeVersion, assertDepInstalled, checkEnvironment } from './env-c
 
 // B) Scope / pattern primitives
 export {
+  /** @deprecated Use findOwnScopeFile from scope-gate.mjs because first-file selection ignores manifest ownership and can select a peer session's manifest. */
   findScopeFile,
   getEnforcementLevel,
   gateEnabled,

package/scripts/lib/harness-audit/categories/category4.mjs

@@ -27,8 +27,11 @@ export const DEFAULT_LOCK_TTL_HOURS = 4;
 /**
  * Heartbeat-based liveness for a parsed session.lock — a self-contained mirror
  * of session-lock.mjs `isLockLive` (which is the SSOT for the semantics). A lock
- * is live when (now - last_heartbeat) < ttl_hours; falls back to started_at for
- * v1 locks. Returns false for malformed input (→ treated as an orphaned lease).
+ * is live when (now - last_heartbeat) < ttl_hours. A lock without
+ * `last_heartbeat` is not live — no `started_at` fallback since the #595 sunset
+ * (2026-10-02), same as the SSOT. Nor is one stamped more than 5 minutes in the
+ * future (#1494 — the SSOT's FUTURE_HEARTBEAT_TOLERANCE_MS). Returns false for
+ * malformed input (→ treated as an orphaned lease).
  *
  * Exported (additive-only) so tests/lib/lock-ttl-parity.test.mjs can drive both
  * this mirror and the SSOT with identical fixtures and assert identical verdicts.
@@ -39,11 +42,10 @@ export const DEFAULT_LOCK_TTL_HOURS = 4;
  */
 export function lockIsLive(lock, nowMs) {
   if (!lock || typeof lock !== 'object') return false;
-  const hb = (typeof lock.last_heartbeat === 'string' && lock.last_heartbeat.length > 0)
-    ? lock.last_heartbeat
-    : lock.started_at;
-  const ms = Date.parse(hb);
+  if (typeof lock.last_heartbeat !== 'string' || lock.last_heartbeat.length === 0) return false;
+  const ms = Date.parse(lock.last_heartbeat);
   if (Number.isNaN(ms)) return false;
+  if (ms > nowMs + 5 * 60 * 1000) return false;
   const ttlHours = typeof lock.ttl_hours === 'number' ? lock.ttl_hours : DEFAULT_LOCK_TTL_HOURS;
   return (nowMs - ms) < ttlHours * 3600 * 1000;
 }