session-orchestrator 3.16.0

package/scripts/lib/autopilot/recent-runs.mjs

@@ -0,0 +1,106 @@
+/**
+ * autopilot/recent-runs.mjs — pure, no-throw reader for the per-repo
+ * autopilot.jsonl run history (Epic #673 P3, issue #682 verdict-gated launch).
+ *
+ * `readRecentAutopilotRuns({ repoRoot, limit })` reads
+ * `<repoRoot>/.orchestrator/metrics/autopilot.jsonl`, parses each JSONL line
+ * (tolerating corrupt/partial lines), and returns the most-recent `limit`
+ * records. The ONLY consumer is the dispatcher launch-gate (#682): it feeds the
+ * returned array into `computeSuitabilityVerdict({ recentRuns })`
+ * (scripts/lib/autonomy/suitability.mjs) whose G2 kill-switch gate counts the
+ * records and reads each record's `kill_switch` field.
+ *
+ * CONTRACT (mirrors the never-throws + tolerant-parse idioms in
+ * scripts/lib/autopilot/telemetry.mjs and the trailing-line skip in
+ * scripts/lib/dispatcher/rank.mjs `defaultStaleDaysFor`):
+ *   - PURE READ, NEVER throws — a missing file, an unreadable file, or a
+ *     wholly-unparseable file all return `[]`. Telemetry/launch-gate failures
+ *     must never crash the dispatcher.
+ *   - TRUE COUNT preserved: when ≥ `KILL_SWITCH_MIN_RUNS` (5) valid records
+ *     exist on disk, the reader returns the true tail count — it does NOT
+ *     pre-truncate below 5. (NICE-a: pre-truncating would falsely trigger the
+ *     engine's <5-run omission branch and skip the kill-switch gate.) The
+ *     `limit` argument is an UPPER BOUND for very large files (default 50) — it
+ *     caps the tail to keep parse work bounded, it is never a floor. Callers
+ *     MUST NOT pass `limit < 5` for the launch-gate read: a `limit` below the
+ *     engine's 5-run floor would silently mask a real ≥5-run history and force
+ *     the G2 kill-switch gate into its omission branch — exactly the NICE-a
+ *     failure mode. The default 50 is comfortably above the floor; leave it
+ *     alone for the verdict path. (A `limit < 5` is still honoured as a literal
+ *     cap — the reader does not clamp it upward — so the discipline is on the
+ *     caller, documented here so it is not "fixed" by silently raising it.)
+ *   - INTEGRITY (NICE-a): `autopilot.jsonl` is NOT subject to size-based
+ *     events-rotation. `scripts/lib/events-rotation.mjs` (`maybeRotate`) targets
+ *     `events.jsonl` ONLY — the session-start hook passes that single `logPath`;
+ *     the rotation module contains zero references to `autopilot.jsonl`. So the
+ *     autopilot run history this reader sees is never truncated/shifted out from
+ *     under the launch gate by rotation: the on-disk tail IS the true history
+ *     (only `autopilot.mjs` itself appends to it; see `skills/autopilot/SKILL.md`
+ *     / `AGENTS.md` § Telemetry — sole-writer rule).
+ *   - Ordering is NEWEST-LAST (chronological / file order): the returned array
+ *     is a tail slice of the file, preserving on-disk append order. The engine
+ *     only COUNTS records and reads `kill_switch`; order does not affect G2.
+ *   - Corrupt lines are SKIPPED (not fatal): one malformed JSON line does not
+ *     discard the rest of the history.
+ *
+ * No imports beyond node builtins. ESM. eslint-clean (eqeqeq, no-throw).
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/** Canonical per-repo autopilot telemetry path (relative to repoRoot). */
+const AUTOPILOT_JSONL_RELPATH = path.join('.orchestrator', 'metrics', 'autopilot.jsonl');
+
+/** Default tail window — generous; the engine's G2 floor is only 5 runs. */
+const DEFAULT_LIMIT = 50;
+
+/**
+ * Read the most-recent autopilot run records for a repo. Never throws.
+ *
+ * @param {{ repoRoot?: string, limit?: number }} [opts]
+ * @param {string} [opts.repoRoot]  Repo whose `.orchestrator/metrics/autopilot.jsonl`
+ *                                  to read. Falsy/non-string ⇒ `[]`.
+ * @param {number} [opts.limit=50]  UPPER BOUND on records returned (the newest
+ *                                  `limit`). Non-finite / ≤ 0 ⇒ falls back to the
+ *                                  default 50. NICE-a discipline: never pass
+ *                                  `limit < 5` on the launch-gate read — a value
+ *                                  below the engine's 5-run kill-switch floor
+ *                                  masks a real ≥5-run history and forces G2's
+ *                                  omission branch. The reader honours a small
+ *                                  `limit` literally (it does NOT clamp upward);
+ *                                  keeping it ≥ 5 (default 50) is the caller's job.
+ * @returns {Array<{ kill_switch?: string|null, [k: string]: unknown }>}
+ *          Tail slice of parsed records, NEWEST-LAST. `[]` on any failure.
+ */
+export function readRecentAutopilotRuns({ repoRoot, limit = DEFAULT_LIMIT } = {}) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return [];
+
+  const cap = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : DEFAULT_LIMIT;
+
+  let raw;
+  try {
+    raw = readFileSync(path.join(repoRoot, AUTOPILOT_JSONL_RELPATH), 'utf8');
+  } catch {
+    // Missing / unreadable file ⇒ no history ⇒ [] (G2 gate omitted with a warning).
+    return [];
+  }
+
+  const records = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      // Only keep object records; primitives/arrays are not run records.
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        records.push(parsed);
+      }
+    } catch {
+      // Skip a corrupt/partial line — one bad line never discards the history.
+    }
+  }
+
+  // Return the newest `cap` records, preserving on-disk (newest-last) order.
+  return records.length > cap ? records.slice(records.length - cap) : records;
+}

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

@@ -0,0 +1,97 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Exports:
+ *   SAMPLE_CADENCE_MS — shared constant (30_000) defining the "fresh" window
+ *   sampleProgress(opts) — returns progress descriptor; never throws
+ */
+
+import { statSync } from 'node:fs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Window (ms) within which a marker is considered "fresh". If the autopilot.jsonl
+ * mtime is within the last SAMPLE_CADENCE_MS, the sampler reports progressed=true.
+ * Exported so the kill-switch caller and tests share the same value.
+ */
+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_MISSING = 'missing';
+const MARKER_INVALID = 'invalid';
+
+// ---------------------------------------------------------------------------
+// Progress sampler
+// ---------------------------------------------------------------------------
+
+/**
+ * Sample autopilot progress by reading `autopilot.jsonl` mtime.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.autopilotJsonlPath] — path to autopilot.jsonl (default
+ *   '.orchestrator/metrics/autopilot.jsonl').
+ * @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).
+ *   DI seam for deterministic tests.
+ * @returns {{
+ *   progressed: boolean,
+ *   lastMarker: number | null,
+ *   stallSeconds: number,
+ *   marker: string,
+ * }}
+ */
+export function sampleProgress(opts = {}) {
+  const autopilotJsonlPath = opts.autopilotJsonlPath ?? DEFAULT_AUTOPILOT_JSONL;
+  // stallTimeoutSeconds is currently informational — the caller decides if
+  // stallSeconds exceeds threshold. We read it (with default) so the signature
+  // stays stable when (future) clamp logic moves here. Underscore prefix marks
+  // intentional non-use per the project ESLint config.
+  const _stallTimeoutSeconds = opts.stallTimeoutSeconds ?? DEFAULT_STALL_TIMEOUT_SECONDS;
+  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,
+    };
+  }
+
+  const now = nowMs();
+  const deltaMs = now - mtimeMs;
+  // 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
+  // future-mtime case where deltaMs < SAMPLE_CADENCE_MS).
+  const progressed = deltaMs < SAMPLE_CADENCE_MS;
+
+  return {
+    progressed,
+    lastMarker: mtimeMs,
+    stallSeconds,
+    marker: MARKER_SUCCESS,
+  };
+}

package/scripts/lib/autopilot/telemetry.mjs

@@ -0,0 +1,224 @@
+/**
+ * autopilot/telemetry.mjs — Telemetry helpers for the autopilot loop.
+ *
+ * Relocated from scripts/lib/autopilot-telemetry.mjs as part of the W1A6
+ * decomposition. The original path is kept as a thin backward-compat re-export.
+ *
+ * Leaf module: imports node built-ins only — no circular dependencies.
+ *
+ * Exports:
+ *   SCHEMA_VERSION
+ *   appendJsonlAtomic(record, jsonlPath)               — shared atomic tmp+rename helper
+ *   writeAutopilotJsonl(state, jsonlPath)              — atomic tmp+rename JSONL writer
+ *   defaultRunId(branch, nowMs)                        — autopilot_run_id builder
+ *   readHostClass(hostJsonPath)                        — reads host.json host_class field
+ *   finalizeState(state, nowMs)                        — stamps completed_at + duration_seconds
+ *   writeMultiStoryCoordinatorEntry(entry, jsonlPath)  — Phase D coordinator summary entry
+ *   linkChildLoopToCoordinator(childRunId, parentRunId)— Phase D linkage documentation helper
+ */
+
+import { writeFileSync, renameSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Schema version
+// ---------------------------------------------------------------------------
+
+export const SCHEMA_VERSION = 1;
+
+// ---------------------------------------------------------------------------
+// Shared atomic JSONL append helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Atomically append a record as a JSONL line to `jsonlPath`.
+ * Strategy: read existing file content → append new line in memory →
+ * write to a tmp file in the same directory → rename tmp → final path.
+ * Crash-safe: a partial tmpfile is never visible at the destination path.
+ * POSIX rename(2) is atomic within the same filesystem.
+ *
+ * The directory must already exist (callers are responsible for mkdirSync).
+ *
+ * @param {object} record    — the record to serialize as a JSONL line
+ * @param {string} jsonlPath — destination JSONL path
+ */
+export function appendJsonlAtomic(record, jsonlPath) {
+  let existing;
+  try {
+    existing = readFileSync(jsonlPath, 'utf8');
+  } catch {
+    existing = '';
+  }
+  if (existing.length > 0 && !existing.endsWith('\n')) existing += '\n';
+
+  const line = JSON.stringify(record) + '\n';
+  const tmp = `${jsonlPath}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  writeFileSync(tmp, existing + line, 'utf8');
+  renameSync(tmp, jsonlPath);
+}
+
+// ---------------------------------------------------------------------------
+// JSONL writer (atomic tmp + rename)
+// ---------------------------------------------------------------------------
+
+/**
+ * Append-once writer for `autopilot.jsonl`. Writes ONE record per /autopilot
+ * invocation atomically: stage to a tmpfile in the same directory, then
+ * rename. Existing file contents are preserved (read → append → atomic
+ * rewrite). Crash-safe: a partial tmpfile is never visible at the destination.
+ *
+ * @param {object} state — fully-formed autopilot state record
+ * @param {string} jsonlPath — destination JSONL path
+ */
+export function writeAutopilotJsonl(state, jsonlPath) {
+  if (!state || typeof state !== 'object') {
+    throw new TypeError('writeAutopilotJsonl: state must be an object');
+  }
+  if (typeof jsonlPath !== 'string' || jsonlPath.length === 0) {
+    throw new TypeError('writeAutopilotJsonl: jsonlPath must be a non-empty string');
+  }
+
+  const dir = path.dirname(jsonlPath);
+  mkdirSync(dir, { recursive: true });
+
+  appendJsonlAtomic(state, jsonlPath);
+}
+
+// ---------------------------------------------------------------------------
+// Run-id + host class helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a default autopilot_run_id from the current branch name and timestamp.
+ *
+ * @param {string|null|undefined} branch — git branch name
+ * @param {number} nowMs — wall-clock milliseconds (Date.now())
+ * @returns {string}
+ */
+export function defaultRunId(branch, nowMs) {
+  const d = new Date(nowMs);
+  const pad = (n) => String(n).padStart(2, '0');
+  const ymd = `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
+  const hhmm = `${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}`;
+  const safeBranch = (branch ?? 'unknown').replace(/[^A-Za-z0-9._-]+/g, '-');
+  return `${safeBranch}-${ymd}-${hhmm}-autopilot`;
+}
+
+/**
+ * Read the `host_class` field from `.orchestrator/host.json`. Returns `null`
+ * on any parse or I/O error.
+ *
+ * @param {string} hostJsonPath — absolute or relative path to host.json
+ * @returns {string|null}
+ */
+export function readHostClass(hostJsonPath) {
+  try {
+    const obj = JSON.parse(readFileSync(hostJsonPath, 'utf8'));
+    return typeof obj?.host_class === 'string' ? obj.host_class : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// State finalizer
+// ---------------------------------------------------------------------------
+
+/**
+ * Stamp `completed_at` and `duration_seconds` onto the autopilot state record
+ * in-place. Called once at the end of `runLoop` (and in dry-run) before writing
+ * the JSONL record.
+ *
+ * @param {object} state — mutable autopilot state record
+ * @param {() => number} nowMs — wall-clock supplier
+ */
+export function finalizeState(state, nowMs) {
+  const completedMs = nowMs();
+  const startedMs = Date.parse(state.started_at);
+  state.completed_at = new Date(completedMs).toISOString();
+  state.duration_seconds = Number.isFinite(startedMs)
+    ? Math.max(0, Math.round((completedMs - startedMs) / 1000))
+    : 0;
+}
+
+// ---------------------------------------------------------------------------
+// Phase D — multi-story coordinator helpers
+// ---------------------------------------------------------------------------
+
+const DEFAULT_AUTOPILOT_JSONL = '.orchestrator/metrics/autopilot.jsonl';
+
+/**
+ * Write a per-orchestrator-run coordinator entry to autopilot.jsonl.
+ * Used by autopilot-multi.mjs to log the multi-story run summary distinct
+ * from individual story-loop entries (which are written by runLoop itself).
+ *
+ * Schema additions (additive, no version bump):
+ *   - parent_run_id: null (the coordinator IS the parent — its id is the
+ *     parent_run_id used by children)
+ *   - kind: 'multi-story-coordinator' (vs 'single-loop' implied for legacy entries)
+ *   - child_run_ids: string[] of loopIds that this coordinator spawned
+ *   - cohort_aborted: boolean
+ *
+ * Fault-tolerant: errors are logged but never thrown — telemetry failures
+ * must not crash the orchestrator.
+ *
+ * @param {object}   entry
+ * @param {string}   entry.run_id           - the coordinator's parent_run_id
+ * @param {string}   entry.started_at       - ISO 8601
+ * @param {string}   entry.ended_at         - ISO 8601
+ * @param {string}   entry.stop_reason      - 'first-kill-switch'|'backlog-empty'|'inactivity-timeout'|'max-hours'|'cohort-abort'
+ * @param {number}   entry.loop_count
+ * @param {number}   entry.completed_count
+ * @param {number}   entry.failed_count
+ * @param {string[]} entry.child_run_ids
+ * @param {boolean}  entry.cohort_aborted
+ * @param {object}   [entry.kill_detail]    - optional kill-switch detail when stop_reason is fatal
+ * @param {string}   [jsonlPath]            - defaults to .orchestrator/metrics/autopilot.jsonl
+ * @returns {void}
+ */
+export function writeMultiStoryCoordinatorEntry(entry, jsonlPath = DEFAULT_AUTOPILOT_JSONL) {
+  // Defensive: ensure metrics directory exists
+  const dir = path.dirname(jsonlPath);
+  try { mkdirSync(dir, { recursive: true }); } catch { /* idempotent — directory may already exist */ }
+
+  // Compose canonical record with required field defaults
+  const record = {
+    schema_version: 1,            // additive — coordinator entries are still v1
+    run_id: entry.run_id,
+    started_at: entry.started_at,
+    ended_at: entry.ended_at,
+    kind: 'multi-story-coordinator',
+    parent_run_id: null,          // coordinator is at top of the tree
+    child_run_ids: Array.isArray(entry.child_run_ids) ? entry.child_run_ids : [],
+    stop_reason: entry.stop_reason,
+    loop_count: entry.loop_count ?? 0,
+    completed_count: entry.completed_count ?? 0,
+    failed_count: entry.failed_count ?? 0,
+    cohort_aborted: entry.cohort_aborted ?? false,
+    kill_detail: entry.kill_detail ?? null,
+  };
+
+  try {
+    appendJsonlAtomic(record, jsonlPath);
+  } catch (err) {
+    console.error(`[telemetry] writeMultiStoryCoordinatorEntry failed: ${err.message}`);
+    // Do NOT throw — telemetry failures must not crash the orchestrator
+  }
+}
+
+/**
+ * Documentation-only helper. The linkage between child loops and the
+ * coordinator is established via `state.parent_run_id` set by autopilot-multi
+ * before calling runLoop. Children's autopilot.jsonl entries inherit the
+ * parent_run_id automatically via the existing writeAutopilotJsonl path.
+ *
+ * This function exists so call-sites can self-document the contract.
+ *
+ * @param {string} childRunId  - the child's run_id
+ * @param {string} parentRunId - the coordinator's run_id
+ * @returns {{linked: true, child: string, parent: string}}
+ */
+export function linkChildLoopToCoordinator(childRunId, parentRunId) {
+  return { linked: true, child: childRunId, parent: parentRunId };
+}