session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/auto-dialectic.mjs

@@ -1,11 +1,24 @@
 /**
- * auto-dialectic.mjs — Cadence helper for session-end Phase 3.6.7 (#506, F2.5).
+ * auto-dialectic.mjs — Cadence helper for the dialectic derivation (#506, F2.5).
  *
- * Mirrors the auto-dream.mjs API shape exactly. Decides whether the post-session
- * dialectic derivation should fire, writes the proposed peer-card diff to
+ * Mirrors the auto-dream.mjs API shape exactly. Decides whether a dialectic
+ * derivation is DUE, writes the proposed peer-card diff to
  * `.orchestrator/dialectic-pending.md` atomically, and tracks the last-run
- * timestamp at `.orchestrator/dialectic-last-run` so the next session can
- * compute cadence delta.
+ * timestamp at `.orchestrator/dialectic-last-run`.
+ *
+ * Who calls what (the session-end Phase 3.6.7 auto-trigger is GONE — #1288):
+ *   - `shouldDispatchAutoDialectic` — read by the session-start `maintenance-due`
+ *     probe (`scripts/lib/maintenance-due-banner.mjs`) to report the `dialectic`
+ *     signal. Side-effect-free by contract: a variant advancing the last-run stamp
+ *     would consume the signal it reports.
+ *   - `writeDialecticPending` / `consumeDialecticPending` / `writeDialecticLastRun` —
+ *     called by `/evolve dialectic` (Step 6.4 in
+ *     `skills/evolve/references/evolve-dialectic-mode.md`), the only trigger today.
+ *   - `renderPendingBody` / `comparePendingBody` (#1386) — the same Step 6.4 builds
+ *     the sidecar body with the former on the dry-run path and, on `--apply`,
+ *     compares the freshly derived body against the reviewed sidecar with the
+ *     latter before writing any peer card.
+ *   - Both sidecars are READ by the same `maintenance-due` probe.
  *
  * Decision inputs (PRD F2.5 acceptance criteria):
  *   - dialectic.cadence (default 5) — sessions since last dialectic run
@@ -17,7 +30,7 @@
  * separate helpers. No external deps — Node 20+ stdlib only.
  */
 
-import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, rename, unlink, mkdir, readdir, stat, lstat } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
@@ -37,6 +50,20 @@ export const DIALECTIC_LAST_RUN_PATH = '.orchestrator/dialectic-last-run';
 /** Repo-relative path to the pending dialectic proposal sidecar. */
 export const DIALECTIC_PENDING_PATH = '.orchestrator/dialectic-pending.md';
 
+/** Repo-relative directory the consumed sidecars are archived into (#1388 P9). */
+export const DIALECTIC_CONSUMED_DIR = '.orchestrator/consumed';
+
+/**
+ * Retention ceiling for `.orchestrator/consumed/` — newest N archived sidecars
+ * survive a consume, older ones are pruned.
+ *
+ * Ceiling + revisit trigger (BV-004): newest 10; revisit if `checkStaleArtifacts`
+ * (`scripts/lib/project-hygiene.mjs`) ever reports a `consumed/` file. That probe
+ * counts every untracked `.orchestrator/**` file older than 30 days, so an
+ * unbounded archive would become a standing hygiene finding.
+ */
+export const DIALECTIC_CONSUMED_RETENTION = 10;
+
 // ---------------------------------------------------------------------------
 // Path helpers
 // ---------------------------------------------------------------------------
@@ -49,6 +76,10 @@ function pendingPath(repoRoot) {
   return path.join(repoRoot, DIALECTIC_PENDING_PATH);
 }
 
+function consumedDirPath(repoRoot) {
+  return path.join(repoRoot, DIALECTIC_CONSUMED_DIR);
+}
+
 function sessionsJsonlPath(repoRoot) {
   return path.join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl');
 }
@@ -180,15 +211,16 @@ export async function readDialecticSignals({ repoRoot } = {}) {
 // ---------------------------------------------------------------------------
 
 /**
- * Decide whether session-end Phase 3.6.7 should dispatch
- * `/evolve --dialectic --dry-run`.
+ * Decide whether a dialectic derivation is DUE — i.e. whether the operator should
+ * run `/evolve dialectic` (dry-run first). Read by the session-start
+ * `maintenance-due` probe; no auto-trigger consumes this any more (#1288).
  *
  * Rules (PRD F2.5):
  *   - cadence === 0 → never trigger (kill-switch).
  *   - AC4 precondition: sessionsSinceLast === 0 AND learningsSinceLast === 0 →
  *     no new input since last run → skip with reason
- *     `no-new-input-since-last-run` (this skip MUST surface in the Final
- *     Report verbatim as `dialectic: skipped (no new input since last run)`).
+ *     `no-new-input-since-last-run` (the reason string is part of the contract —
+ *     the `maintenance-due` probe reports it verbatim).
  *   - sessionsSinceLast >= cadence → trigger (cadence threshold met).
  *   - Otherwise → skip with reason `under-threshold (sessions=N/M)`.
  *
@@ -257,8 +289,12 @@ export async function shouldDispatchAutoDialectic({
  * never a half-written intermediate (mirrors auto-dream.mjs:248-251).
  *
  * Defensive: returns `{ok: false, error}` on filesystem failure rather than
- * throwing — callers (session-end Phase 3.6.7 step 7) should log the error
- * and continue rather than aborting the close.
+ * throwing — the caller logs the error and continues.
+ *
+ * Caller: `/evolve dialectic` Step 6.4 (`skills/evolve/references/evolve-dialectic-mode.md`),
+ * after a successful `--apply` AND after the operator explicitly discards a
+ * proposal. Without this write the maintenance-due `dialectic` signal never
+ * resets (#1380). The session-end auto-trigger that used to call it is gone.
  *
  * @param {object} args
  * @param {string} args.repoRoot
@@ -293,11 +329,17 @@ export async function writeDialecticLastRun({ repoRoot, isoTimestamp } = {}) {
  * Write the proposed dialectic diff to `.orchestrator/dialectic-pending.md`
  * atomically.
  *
+ * Caller: `/evolve dialectic` Step 6.4's dry-run branch
+ * (`skills/evolve/references/evolve-dialectic-mode.md`) — `runDialecticDeriver()`
+ * returns the diff and the caller persists it here. There is no session-end
+ * auto-trigger any more (#1288).
+ *
  * Caller supplies the body (a Markdown document containing the peer-card
  * diff and any narrative). This helper prepends a minimal hand-rolled YAML
- * frontmatter block carrying the metadata session-end's Final Report and
- * the next session's --apply step both rely on. The frontmatter is hand
- * rolled (no js-yaml dep) — auto-dream pattern.
+ * frontmatter block carrying the metadata the operator's review and the later
+ * `--apply` step rely on; the session-start `maintenance-due` probe reads the
+ * resulting file's presence + age for its `pending-sidecar` signal. The
+ * frontmatter is hand rolled (no js-yaml dep) — auto-dream pattern.
  *
  * Atomicity: tmp+rename (mirrors auto-dream.mjs:248-251).
  *
@@ -366,6 +408,146 @@ export async function writeDialecticPending({
   return { path: target, bytes: Buffer.byteLength(content, 'utf8') };
 }
 
+/**
+ * Archive file name for a consumed sidecar: `<ISO-stamp>-<8 hex>-dialectic-pending.md`.
+ * The stamp is `toISOString()` with `:` and `.` replaced by `-` — both are
+ * illegal or awkward on several filesystems, and the form still sorts
+ * lexicographically. The random suffix separates two consumes landing in the
+ * SAME millisecond — without it the second rename would overwrite the first
+ * archive silently.
+ *
+ * @returns {string}
+ */
+function archiveFileName() {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return `${stamp}-${randomUUID().slice(0, 8)}-dialectic-pending.md`;
+}
+
+/**
+ * Exactly the names {@link archiveFileName} produces. The prune touches nothing
+ * else in the directory (#1390 P6): a loose suffix match would still delete an
+ * unrelated `operator-dialectic-pending.md`.
+ */
+const ARCHIVE_NAME_RE =
+  /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-[0-9a-f]{8}-dialectic-pending\.md$/;
+
+/**
+ * Prune `.orchestrator/consumed/` to the newest `DIALECTIC_CONSUMED_RETENTION`
+ * archives. Only regular files whose name matches {@link ARCHIVE_NAME_RE} are
+ * counted or removed — anything else in the directory is not this module's to
+ * delete. Best-effort: every failure degrades to "pruned nothing" — an archive
+ * that grew one file too long is never worth failing a consume over.
+ *
+ * "Newest" is mtime DESC with the filename as tiebreaker: the archive names
+ * carry an ISO timestamp, which sorts lexicographically, so the two orderings
+ * agree except inside one millisecond.
+ *
+ * @param {string} dir Absolute path to the consumed archive directory.
+ * @returns {Promise<number>} Number of files removed.
+ */
+async function pruneConsumedArchive(dir) {
+  let removed = 0;
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = entries
+      .filter((e) => e.isFile() && ARCHIVE_NAME_RE.test(e.name))
+      .map((e) => e.name);
+    if (files.length <= DIALECTIC_CONSUMED_RETENTION) return 0;
+
+    const dated = [];
+    for (const name of files) {
+      let mtimeMs = 0;
+      try {
+        mtimeMs = (await stat(path.join(dir, name))).mtimeMs;
+      } catch {
+        mtimeMs = 0; // unreadable → oldest, pruned first
+      }
+      dated.push({ name, mtimeMs });
+    }
+    dated.sort((a, b) => b.mtimeMs - a.mtimeMs || (a.name < b.name ? 1 : -1));
+
+    for (const { name } of dated.slice(DIALECTIC_CONSUMED_RETENTION)) {
+      try {
+        await unlink(path.join(dir, name));
+        removed += 1;
+      } catch {
+        /* best-effort */
+      }
+    }
+  } catch {
+    /* best-effort — a prune failure never fails the consume */
+  }
+  return removed;
+}
+
+/**
+ * Consume `.orchestrator/dialectic-pending.md` once its proposal has been
+ * applied or explicitly discarded: the file is MOVED into
+ * `.orchestrator/consumed/<ISO-timestamp>-dialectic-pending.md` rather than
+ * unlinked (#1388 P9 — the sidecar was the only copy of what the operator
+ * reviewed, and an unlink destroyed it). The maintenance-due probe reads an
+ * explicit two-path list (`PENDING_SIDECARS`,
+ * `scripts/lib/maintenance-due-banner.mjs`), so an archived file does not
+ * re-raise `pending-sidecar` (#1380 stays fixed).
+ *
+ * The archive is pruned to `DIALECTIC_CONSUMED_RETENTION` entries on every
+ * consume — see that constant for the ceiling and its revisit trigger.
+ *
+ * ENOENT is tolerated (`consumed: false`) — "already gone" is the desired end
+ * state. Any other filesystem error returns `{ok: false, error}` rather than
+ * throwing, matching `writeDialecticLastRun`.
+ *
+ * Symlink (#1390 P6, measured 2026-09-19): a pre-existing `.orchestrator/consumed`
+ * symlink used to be followed — `mkdir` was a no-op on it, `rename` moved the
+ * sidecar into its target, and the retention prune unlinked that target's
+ * regular files beyond the newest 10 (a tmp repro deleted 3 of 12). The consume
+ * now `lstat`s the directory first and REFUSES a symlink: it returns
+ * `{ok: false, error}`, moves nothing and prunes nothing, so the pending
+ * sidecar stays where it is for the caller to report. The prune additionally
+ * only ever removes names this module writes (see `ARCHIVE_NAME_RE`). Ceiling:
+ * the `lstat` → `rename` window is not atomic — a process swapping in a symlink
+ * inside it wins; revisit if the consumed directory ever becomes writable by a
+ * less-trusted uid than the operator's.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @returns {Promise<{ok:boolean, consumed?:boolean, error?:string, path?:string, archivedTo?:string, pruned?:number}>}
+ */
+export async function consumeDialecticPending({ repoRoot } = {}) {
+  if (!repoRoot) {
+    return { ok: false, error: 'consumeDialecticPending: repoRoot is required' };
+  }
+  const target = pendingPath(repoRoot);
+  if (!existsSync(target)) return { ok: true, consumed: false, path: target };
+
+  const dir = consumedDirPath(repoRoot);
+  const archivedTo = path.join(dir, archiveFileName());
+
+  try {
+    let dirStat = null;
+    try {
+      dirStat = await lstat(dir);
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw err;
+    }
+    if (dirStat?.isSymbolicLink()) {
+      return {
+        ok: false,
+        path: target,
+        error: `consumeDialecticPending: ${DIALECTIC_CONSUMED_DIR} is a symlink — refusing to archive or prune through it`,
+      };
+    }
+    await mkdir(dir, { recursive: true });
+    await rename(target, archivedTo);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { ok: true, consumed: false, path: target };
+    return { ok: false, error: err.message };
+  }
+
+  const pruned = await pruneConsumedArchive(dir);
+  return { ok: true, consumed: true, path: target, archivedTo, pruned };
+}
+
 /**
  * Read `.orchestrator/dialectic-pending.md` if present. Returns the raw file
  * body (including frontmatter) so callers can decide how to parse it.
@@ -389,3 +571,110 @@ export async function readDialecticPending({ repoRoot } = {}) {
     return null;
   }
 }
+
+// ---------------------------------------------------------------------------
+// pending body — serializer + drift comparison (#1386, variant b)
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize a deriver diff OBJECT (`result.diff = {user?, agent?}`) into the
+ * Markdown body `writeDialecticPending` persists.
+ *
+ * This lived as a JS snippet in `skills/evolve/references/evolve-dialectic-mode.md`
+ * Step 6.4 and is moved here VERBATIM so the dry-run write and the apply-time
+ * comparison build the body from the same code — two hand-copied serializers
+ * would report drift that is only formatting (#1386).
+ *
+ * Pure: no I/O, no throw. A non-object argument, or one with neither target as
+ * a string, yields `''` — the caller's "nothing to review, write no sidecar"
+ * branch.
+ *
+ * @param {{user?: string, agent?: string}} diff
+ * @returns {string} Fenced Markdown body, or `''` when nothing was proposed.
+ */
+export function renderPendingBody(diff) {
+  if (!diff || typeof diff !== 'object') return '';
+  const FENCE = '`'.repeat(3);
+  return ['user', 'agent']
+    .filter((t) => typeof diff[t] === 'string')
+    .map((t) => [`${FENCE}diff`, `# target: ${t}`, diff[t].trimEnd(), FENCE].join('\n'))
+    .join('\n\n');
+}
+
+/**
+ * Strip EXACTLY the leading frontmatter block `writeDialecticPending` wrote.
+ *
+ * The delimiters sit at fixed positions — line 0 and the next `---` LINE — so
+ * this splits on the first two delimiter LINES only. A naive `split('---')`
+ * breaks on a body containing a `---` line, and diff bodies do.
+ *
+ * @param {string} content
+ * @returns {string} The body, or the whole input when no frontmatter is present.
+ */
+function stripPendingFrontmatter(content) {
+  const lines = content.split('\n');
+  if (lines[0] !== '---') return content;
+  const end = lines.indexOf('---', 1);
+  if (end === -1) return content; // unterminated → nothing to strip
+  return lines.slice(end + 1).join('\n');
+}
+
+/**
+ * Whitespace normalisation for the drift comparison: exactly ONE trailing
+ * newline is removed from each side.
+ *
+ * `writeDialecticPending` appends a newline when the body lacks one, so the
+ * persisted body is the rendered body plus `\n` — without this normalisation a
+ * clean round-trip would always report drift. Nothing else is normalised (no
+ * trim, no line-ending or indentation folding): anything more would hide real
+ * drift in a diff body, where trailing whitespace is content.
+ */
+function normalizeTrailingNewline(text) {
+  return text.endsWith('\n') ? text.slice(0, -1) : text;
+}
+
+/**
+ * Compare a freshly derived pending body against the sidecar the operator
+ * reviewed (#1386, variant b).
+ *
+ * `/evolve dialectic --apply` re-derives from the model, so what gets applied
+ * is not necessarily what was approved in `.orchestrator/dialectic-pending.md`.
+ * This makes that divergence VISIBLE at apply time; it does not make apply
+ * deterministic.
+ *
+ * Never throws — every failure degrades to a result object, matching this
+ * module's other readers.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {string} args.body Fresh body, typically from `renderPendingBody()`.
+ * @returns {Promise<{ok:boolean, drifted:boolean, sidecarAbsent:boolean, sidecarBody?:string, freshBody?:string, error?:string}>}
+ */
+export async function comparePendingBody({ repoRoot, body } = {}) {
+  if (!repoRoot) {
+    return {
+      ok: false,
+      drifted: false,
+      sidecarAbsent: false,
+      error: 'comparePendingBody: repoRoot is required',
+    };
+  }
+  if (typeof body !== 'string') {
+    return {
+      ok: false,
+      drifted: false,
+      sidecarAbsent: false,
+      error: 'comparePendingBody: body must be a string',
+    };
+  }
+
+  const raw = await readDialecticPending({ repoRoot });
+  // Applying without a sidecar is legitimate (the operator may never have run
+  // the dry-run) — that is NOT drift.
+  if (raw === null) return { ok: true, drifted: false, sidecarAbsent: true };
+
+  const sidecarBody = stripPendingFrontmatter(raw);
+  const drifted = normalizeTrailingNewline(sidecarBody) !== normalizeTrailingNewline(body);
+
+  return { ok: true, drifted, sidecarAbsent: false, sidecarBody, freshBody: body };
+}

package/scripts/lib/autopilot/flags.mjs

@@ -58,7 +58,7 @@ function parseNumeric(raw) {
  * silently to bounds. Unknown flags are ignored. `--dry-run` is a boolean flag.
  *
  * @param {string[]} argv — argument tokens (e.g. ['--max-sessions=3', '--dry-run'])
- * @returns {{maxSessions: number, maxHours: number, confidenceThreshold: number, dryRun: boolean}}
+ * @returns {{maxSessions: number, maxHours: number, confidenceThreshold: number, maxTokens: number, dryRun: boolean}}
  */
 export function parseFlags(argv) {
   const tokens = Array.isArray(argv) ? argv : [];
@@ -66,6 +66,7 @@ export function parseFlags(argv) {
   let rawSessions = null;
   let rawHours = null;
   let rawConfidence = null;
+  let rawTokens = null;
   let dryRun = false;
 
   for (const tok of tokens) {
@@ -81,6 +82,7 @@ export function parseFlags(argv) {
     if (key === '--max-sessions') rawSessions = parseNumeric(val);
     else if (key === '--max-hours') rawHours = parseNumeric(val);
     else if (key === '--confidence-threshold') rawConfidence = parseNumeric(val);
+    else if (key === '--max-tokens') rawTokens = parseNumeric(val);
   }
 
   return {
@@ -99,6 +101,15 @@ export function parseFlags(argv) {
       max: FLAG_BOUNDS.confidenceThreshold.max,
       fallback: FLAG_BOUNDS.confidenceThreshold.default,
     }),
+    // Integer token count — the TOKEN_BUDGET_EXCEEDED switch compares it against
+    // a summed `usage.output_tokens`, which is never fractional. `0` disables the
+    // switch (`kill-switches.mjs` guards on `maxTokens > 0`), so the lower bound
+    // stays 0 rather than 1.
+    maxTokens: Math.floor(clampNumber(rawTokens, {
+      min: FLAG_BOUNDS.maxTokens.min,
+      max: FLAG_BOUNDS.maxTokens.max,
+      fallback: FLAG_BOUNDS.maxTokens.default,
+    })),
     dryRun,
   };
 }

package/scripts/lib/autopilot/kill-switches.mjs

@@ -110,7 +110,8 @@ export function preIterationKillSwitch(args) {
  * @param {object | null | undefined} sessionResult
  * @param {object} opts
  * @param {number} opts.carryoverThreshold
- * @param {string} [opts.autopilotJsonlPath] — STALL_TIMEOUT sampler input
+ * @param {string} [opts.autopilotJsonlPath] — STALL_TIMEOUT sampler fallback marker
+ * @param {string} [opts.sessionLockPath] — STALL_TIMEOUT sampler primary marker
  * @param {number} [opts.stallTimeoutSeconds] — STALL_TIMEOUT threshold (default 600)
  * @param {() => number} [opts.nowMs] — wall-clock supplier (DI seam for tests)
  * @returns {{kill: string, detail: string} | null}
@@ -120,12 +121,14 @@ export function postSessionKillSwitch(sessionResult, opts) {
   const { carryoverThreshold } = opts;
 
   // STALL_TIMEOUT (ADR-364 §3, issue #371) — one-strike v1.
-  // Sampler reads autopilot.jsonl mtime; missing file → stallSeconds=0 → no kill
-  // (documented contract: missing file is NOT a kill condition).
+  // Sampler prefers the session.lock heartbeat and falls back to autopilot.jsonl
+  // mtime; missing marker → stallSeconds=0 → no kill (documented contract:
+  // a missing file is NOT a kill condition).
   // Events route to autopilot.jsonl, NOT failures.jsonl (ADR-364 cross-connections rule 4).
   const stallTimeoutSeconds = opts.stallTimeoutSeconds ?? 600;
   const stallSample = sampleProgress({
     autopilotJsonlPath: opts.autopilotJsonlPath,
+    sessionLockPath: opts.sessionLockPath,
     stallTimeoutSeconds,
     nowMs: opts.nowMs,
   });

package/scripts/lib/autopilot/loop.mjs

@@ -59,7 +59,11 @@ function clampNumber(value, { min, max, fallback }) {
  * @param {string} [opts.jsonlPath] @param {string} [opts.runId] @param {string} [opts.branch]
  * @param {string} [opts.hostJsonPath] @param {number} [opts.peerAbortThreshold]
  * @param {number} [opts.carryoverThreshold] @param {number} [opts.maxTokens]
- * @param {string} [opts.autopilotJsonlPath] — STALL_TIMEOUT sampler input (defaults to jsonlPath)
+ * @param {string} [opts.autopilotJsonlPath] — STALL_TIMEOUT sampler fallback marker (defaults to jsonlPath)
+ * @param {string} [opts.sessionLockPath] — STALL_TIMEOUT sampler PRIMARY marker (`session.lock`
+ *   `last_heartbeat`). Deliberately undefaulted: the default would be cwd-relative, which in a
+ *   test run resolves to the LIVE repo lock and would silently decide the sampler's branch. The
+ *   CLI driver (`scripts/autopilot.mjs`) supplies it; omitting it keeps the legacy mtime marker.
  * @param {number} [opts.stallTimeoutSeconds] — STALL_TIMEOUT threshold seconds (default 600)
  * @param {string} [opts.worktreePath] @param {string} [opts.parentRunId]
  * @param {number} [opts.blockedByIssue] — Phase D (#341) forward-compat: issue number this loop is waiting on (OPEN-4 commit-deps); callers may omit, defaults to null
@@ -125,6 +129,14 @@ export async function runLoop(opts = {}) {
     max_sessions: maxSessions,
     max_hours: maxHours,
     confidence_threshold: confidenceThreshold,
+    // Persisted for the same reason as the three above (HR-105): a switch whose
+    // input is never recorded cannot be falsified afterwards. `0` = disabled.
+    // CEILING: reaching a NON-zero value here does not make TOKEN_BUDGET_EXCEEDED
+    // live under the headless driver — `readTailSession()` in scripts/autopilot.mjs
+    // returns no `usage`, and sessions.jsonl carries no token field to build one
+    // from, so `total_tokens_used` stays 0. Revisit when a session record gains
+    // token counts.
+    max_tokens: opts.maxTokens ?? 0,
     iterations_completed: 0,
     kill_switch: null,
     kill_switch_detail: null,
@@ -275,6 +287,7 @@ export async function runLoop(opts = {}) {
     const postCheck = postSessionKillSwitch(sessionResult, {
       carryoverThreshold,
       autopilotJsonlPath: opts.autopilotJsonlPath ?? jsonlPath,
+      sessionLockPath: opts.sessionLockPath,
       stallTimeoutSeconds: opts.stallTimeoutSeconds ?? 600,
       nowMs: opts.nowMs,
     });

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,
   };
 }