session-orchestrator 5.2.0 → 5.4.0

package/scripts/lib/autopilot/stall-sampler.mjs

@@ -2,21 +2,39 @@
  * autopilot/stall-sampler.mjs — Stateless progress sampler for STALL_TIMEOUT
  * kill-switch (ADR-364, issue #371).
  *
- * The sampler reads `autopilot.jsonl` mtime as the progress marker: the
- * autopilot loop writes one record per session atomically (tmp+rename), so the
- * file mtime advances exactly when the loop makes progress. No false-positive
- * churn from in-place writes, no need to parse JSON, microsecond precision.
+ * PROGRESS MARKER PRECEDENCE (HR-102: a better signal REPLACES a worse one).
  *
- * Stateless — single statSync call per invocation, no side effects, no async.
- * Wire-up to the kill-switch + loop is deferred (see #371 follow-up); this
- * module ships in isolation under the ADR-364 thin-slice MVP.
+ *   1. `session.lock` `last_heartbeat` (schema v2) — advances DURING a run:
+ *      `hooks/on-stop.mjs` refreshes it at every turn-end and
+ *      `hooks/post-tool-batch-wave-signal.mjs` at every tool batch.
+ *   2. `autopilot.jsonl` mtime — the legacy marker, used only when no lock path
+ *      is supplied or the lock is absent/corrupt/timestamp-less.
+ *
+ * The header of this module used to claim `autopilot.jsonl` carries "one record
+ * per session". It does not: `telemetry.mjs` writes ONE record per /autopilot
+ * INVOCATION, and `loop.mjs` calls it exactly twice — once for the dry-run
+ * preview and once AFTER the `for(;;)` loop. So during a real run the mtime the
+ * sampler read belonged to the PREVIOUS autopilot run, typically hours or days
+ * old, and the post-session check fired STALL_TIMEOUT after iteration 1 every
+ * time. The append-once contract is correct and stays; the marker was wrong.
+ *
+ * CEILING (BV-004). The heartbeat only advances while some live session owns the
+ * lock: `updateHeartbeat()` refuses on a session_id mismatch, and a child
+ * `claude -p` spawned while a parent session already holds the lock never
+ * acquires one (`hooks/_lib/lock-bootstrap.mjs` bails on `reason: 'active'`).
+ * In that one invocation shape — the headless driver started FROM a chat
+ * session rather than from a bare shell — the heartbeat freezes and the check
+ * degrades to today's behaviour. Revisit if STALL_TIMEOUT is ever observed
+ * firing on a run whose child session did real work.
+ *
+ * Stateless — at most two sync reads per invocation, no side effects, no async.
  *
  * Exports:
  *   SAMPLE_CADENCE_MS — shared constant (30_000) defining the "fresh" window
  *   sampleProgress(opts) — returns progress descriptor; never throws
  */
 
-import { statSync } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -32,9 +50,40 @@ export const SAMPLE_CADENCE_MS = 30_000;
 const DEFAULT_AUTOPILOT_JSONL = '.orchestrator/metrics/autopilot.jsonl';
 const DEFAULT_STALL_TIMEOUT_SECONDS = 600;
 const MARKER_SUCCESS = 'autopilot.jsonl:mtime';
+const MARKER_HEARTBEAT = 'session.lock:last_heartbeat';
 const MARKER_MISSING = 'missing';
 const MARKER_INVALID = 'invalid';
 
+/**
+ * Read the live heartbeat timestamp (ms) out of `session.lock`.
+ *
+ * Returns `null` — meaning "fall back to the mtime marker" — for every failure
+ * mode: no path supplied, file absent, unreadable, not JSON, or carrying no
+ * parsable timestamp. A missing measurement is NOT a zero here; conflating the
+ * two would report a stall of `now` seconds the moment the lock is unreadable.
+ *
+ * @param {string} [sessionLockPath]
+ * @returns {number | null}
+ */
+function readHeartbeatMs(sessionLockPath) {
+  if (typeof sessionLockPath !== 'string' || sessionLockPath.length === 0) return null;
+  let lock;
+  try {
+    lock = JSON.parse(readFileSync(sessionLockPath, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (typeof lock !== 'object' || lock === null) return null;
+  // Same precedence `session-lock.mjs` uses on read: a v1 lock has no
+  // `last_heartbeat`, and its `started_at` is the best available stand-in.
+  const raw = typeof lock.last_heartbeat === 'string' && lock.last_heartbeat.length > 0
+    ? lock.last_heartbeat
+    : lock.started_at;
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  const ms = Date.parse(raw);
+  return Number.isFinite(ms) ? ms : null;
+}
+
 // ---------------------------------------------------------------------------
 // Progress sampler
 // ---------------------------------------------------------------------------
@@ -45,6 +94,10 @@ const MARKER_INVALID = 'invalid';
  * @param {object} [opts]
  * @param {string} [opts.autopilotJsonlPath] — path to autopilot.jsonl (default
  *   '.orchestrator/metrics/autopilot.jsonl').
+ * @param {string} [opts.sessionLockPath] — path to `session.lock`. When supplied
+ *   and readable, its `last_heartbeat` (falling back to `started_at`, the schema
+ *   v1 normalisation `session-lock.mjs` applies on read) REPLACES the mtime
+ *   marker. Omitted → mtime only, which is what every pre-existing caller gets.
  * @param {number} [opts.stallTimeoutSeconds] — kill-switch threshold (default
  *   600). NOT range-clamped here; caller is responsible for bounds.
  * @param {() => number} [opts.nowMs] — wall-clock supplier (default Date.now).
@@ -66,22 +119,26 @@ export function sampleProgress(opts = {}) {
   void _stallTimeoutSeconds;
   const nowMs = typeof opts.nowMs === 'function' ? opts.nowMs : Date.now;
 
-  let mtimeMs;
-  try {
-    const st = statSync(autopilotJsonlPath);
-    mtimeMs = st.mtimeMs;
-  } catch (err) {
-    const marker = err && err.code === 'ENOENT' ? MARKER_MISSING : MARKER_INVALID;
-    return {
-      progressed: false,
-      lastMarker: null,
-      stallSeconds: 0,
-      marker,
-    };
+  let markerMs = readHeartbeatMs(opts.sessionLockPath);
+  let markerName = MARKER_HEARTBEAT;
+
+  if (markerMs === null) {
+    markerName = MARKER_SUCCESS;
+    try {
+      markerMs = statSync(autopilotJsonlPath).mtimeMs;
+    } catch (err) {
+      const marker = err && err.code === 'ENOENT' ? MARKER_MISSING : MARKER_INVALID;
+      return {
+        progressed: false,
+        lastMarker: null,
+        stallSeconds: 0,
+        marker,
+      };
+    }
   }
 
   const now = nowMs();
-  const deltaMs = now - mtimeMs;
+  const deltaMs = now - markerMs;
   // Clamp negative deltas (clock skew, file mtime in the future) to 0.
   const stallSeconds = Math.max(0, Math.round(deltaMs / 1000));
   // Fresh if within the sample cadence window (also covers the clock-skew
@@ -90,8 +147,8 @@ export function sampleProgress(opts = {}) {
 
   return {
     progressed,
-    lastMarker: mtimeMs,
+    lastMarker: markerMs,
     stallSeconds,
-    marker: MARKER_SUCCESS,
+    marker: markerName,
   };
 }

package/scripts/lib/baseline-archetypes.mjs

@@ -19,10 +19,11 @@ const BASENAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*\.md$/;
 const unique = (items) => [...new Set(items)].sort();
 const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 
+/** `message` must never interpolate a baseline root or any other host path. */
 export class BaselineContractError extends Error {
-  constructor(reason) { super(`Baseline archetype lookup failed (${reason}).`); this.name = 'BaselineContractError'; this.reason = reason; }
+  constructor(reason, message = `Baseline archetype lookup failed (${reason}).`) { super(message); this.name = 'BaselineContractError'; this.reason = reason; }
 }
-function fail(reason = 'invalid-contract') { throw new BaselineContractError(reason); }
+function fail(reason = 'invalid-contract', message) { throw new BaselineContractError(reason, message); }
 function check(condition) { if (!condition) fail(); }
 function shape(value, required, optional = []) {
   check(object(value) && required.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => [...required, ...optional].includes(key)));
@@ -122,24 +123,38 @@ process.stdout.write(JSON.stringify(resolveConfiguredBaselinePath(JSON.parse(rea
   return realpathSync(root);
 }
 
-/** Resolve a canonical relative source and reject symlinks at every component. */
-export function baselineSourcePath(root, source, directory = false) {
+/** Resolve a canonical relative source and reject symlinks at every component.
+ * Only an ENOENT thrown by the per-component `lstatSync` itself maps to
+ * `missingReason`; every other failure is `unsafe-source`. Existence is never
+ * probed with a link-following call (existsSync/statSync/accessSync/realpathSync):
+ * a dangling symlink would then read as "missing" instead of `unsafe-source`.
+ */
+export function baselineSourcePath(root, source, directory = false, { missingReason = 'unsafe-source' } = {}) {
   relative(source);
+  // Resolved first: a vanished root is unsafe, never a missing source.
+  let realRoot;
+  try { realRoot = realpathSync(root); } catch { fail('unsafe-source'); }
   let current = root;
-  try {
-    for (const component of source.split('/')) {
-      current = path.join(current, component);
-      if (lstatSync(current).isSymbolicLink()) fail('unsafe-source');
-    }
-    const stat = lstatSync(current);
-    if (directory ? !stat.isDirectory() : !stat.isFile()) fail('unsafe-source');
-    if (!realpathSync(current).startsWith(`${realpathSync(root)}${path.sep}`)) fail('unsafe-source');
-    return current;
-  } catch { fail('unsafe-source'); }
+  let stat;
+  for (const component of source.split('/')) {
+    current = path.join(current, component);
+    try { stat = lstatSync(current); } catch (error) { fail(error?.code === 'ENOENT' ? missingReason : 'unsafe-source'); }
+    if (stat.isSymbolicLink()) fail('unsafe-source');
+  }
+  if (directory ? !stat.isDirectory() : !stat.isFile()) fail('unsafe-source');
+  let real;
+  try { real = realpathSync(current); } catch { fail('unsafe-source'); }
+  if (!real.startsWith(`${realRoot}${path.sep}`)) fail('unsafe-source');
+  return current;
 }
 
+const PRODUCER = 'scripts/archetype-manifest.mjs';
 function projection(root, args, { timeoutMs = 5000, maxBuffer = MAX_BYTES } = {}) {
-  const script = baselineSourcePath(root, 'scripts/archetype-manifest.mjs');
+  let script;
+  try { script = baselineSourcePath(root, PRODUCER, false, { missingReason: 'producer-missing' }); } catch (error) {
+    if (error?.reason !== 'producer-missing') throw error;
+    fail('producer-missing', `Baseline archetype lookup failed (producer-missing): the configured baseline has no ${PRODUCER} exporter — see docs/baseline.md § How bootstrap finds it.`);
+  }
   const result = spawnSync(process.execPath, [script, ...args], {
     cwd: root, encoding: 'utf8', timeout: Math.min(timeoutMs, 5000), maxBuffer: Math.min(maxBuffer, MAX_BYTES),
     shell: false, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'pipe'],
@@ -195,7 +210,8 @@ export async function loadBaselineArchetypes(options = {}) {
     let manifest;
     try { manifest = validateBaselineContract(JSON.parse(projection(root, ['export'], options))); }
     catch (error) { if (error instanceof BaselineContractError) throw error; fail(); }
-    for (const item of manifest.archetypes) baselineSourcePath(root, item.templatePath, true);
+    // An absent declared source is an incomplete baseline, not a security refusal (#1447 3a).
+    for (const item of manifest.archetypes) baselineSourcePath(root, item.templatePath, true, { missingReason: 'invalid-contract' });
     const facts = collectFacts(repoRoot);
     const ordered = [...manifest.archetypes].sort((a, b) => a.order - b.order);
     const archetypes = ordered.map(({ id, order, runtimes, packageManagers, ui, api, deploy }) => ({ id, order, runtimes, packageManagers, ui, api, deploy }));
@@ -220,7 +236,7 @@ export async function loadBaselineArchetypes(options = {}) {
       if (!ruleTargets.includes(name) || seen.has(name)) fail('invalid-rule-projection');
       seen.add(name);
       if (owned.includes(name)) continue;
-      baselineSourcePath(root, source);
+      baselineSourcePath(root, source, false, { missingReason: 'invalid-rule-projection' });
       baselineRules.push({ source, target: `.claude/rules/${name}` });
     }
     if (ruleTargets.some((name) => !seen.has(name))) fail('invalid-rule-projection');
@@ -230,7 +246,9 @@ export async function loadBaselineArchetypes(options = {}) {
       pluginRuleTargets: ruleTargets.filter((name) => owned.includes(name)), baselineRules,
     } };
   } catch (error) {
-    return { status: 'error', reason: error instanceof BaselineContractError ? error.reason : 'lookup-failed', archetypes: [], selected: null };
+    // Only a BaselineContractError message is path-free by construction; others stay opaque.
+    const contract = error instanceof BaselineContractError;
+    return { status: 'error', reason: contract ? error.reason : 'lookup-failed', ...(contract && { message: error.message }), archetypes: [], selected: null };
   }
 }
 
@@ -290,11 +308,12 @@ function applyCopies(plan) {
   return { status: 'applied', created, preserved };
 }
 function applyFailure(error) {
-  return { status: 'error', reason: error instanceof BaselineContractError ? error.reason : 'apply-failed', created: [], preserved: [] };
+  const contract = error instanceof BaselineContractError;
+  return { status: 'error', reason: contract ? error.reason : 'apply-failed', ...(contract && { message: error.message }), created: [], preserved: [] };
 }
 async function selectedContext(options) {
   const result = await loadBaselineArchetypes(options);
-  if (result.status !== 'private' || !result.selected) fail(result.reason);
+  if (result.status !== 'private' || !result.selected) fail(result.reason, result.message);
   const root = await resolveBaselineLocation(options);
   if (!root) fail('baseline-unavailable');
   return { root, selected: result.selected };
@@ -340,7 +359,7 @@ export async function scaffoldBaselineArchetype(options = {}) {
     const { repoRoot = process.cwd(), projectName } = options;
     if (typeof projectName !== 'string' || !ID.test(projectName)) fail('invalid-project-name');
     const { root, selected } = await selectedContext(options);
-    const template = baselineSourcePath(root, selected.templatePath, true);
+    const template = baselineSourcePath(root, selected.templatePath, true, { missingReason: 'invalid-contract' });
     sourceFiles(template);
     const shared = baselineSourcePath(root, 'templates/shared', true);
     sourceFiles(shared);
@@ -401,7 +420,7 @@ export async function syncBootstrapRules(options = {}) {
     // ordinary plugin rules, just as its minimal scaffold does.
     const contract = options.minimal ? { status: 'public', selected: null }
       : await loadBaselineArchetypes({ ...options, repoRoot, pluginRoot, archetype });
-    if (contract.status === 'error') fail(contract.reason);
+    if (contract.status === 'error') fail(contract.reason, contract.message);
     if (contract.status === 'private' && !contract.selected && !hasUnselectedFastLock(repoRoot)) fail(contract.reason);
     const before = new Set();
     for (const name of pluginRuleTargets(pluginRoot)) {