session-orchestrator 5.2.0 → 5.3.0

package/scripts/lib/auq/schema.mjs

@@ -233,50 +233,16 @@ export const CRITERION_IDS = Object.freeze(Object.keys(CRITERIA));
  */
 export const TOTAL_WEIGHT = CRITERION_IDS.reduce((sum, id) => sum + CRITERIA[id].weight, 0);
 
-// ---------------------------------------------------------------------------
-// Die zwei harten Hürden
-// ---------------------------------------------------------------------------
-
-/**
- * Hürden sind KEINE gewichteten Kriterien. Eine gerissene Hürde ergibt Note F,
- * unabhängig von der Punktzahl — deshalb stehen sie getrennt und werden in
- * `AuqScore.hurdlesBroken` geführt, nicht in `points` verrechnet.
- *
- * @type {Readonly<Record<'H1'|'H2', Readonly<{id:string,title:string,rule:string,criterion:string,evidence:string}>>>}
- */
-export const HURDLES = Object.freeze({
-  H1: Object.freeze({
-    id: 'H1',
-    title: 'Kopfzeile höchstens 12 Zeichen',
-    rule: 'codepointLength(header) <= 12',
-    criterion: 'K5',
-    evidence:
-      'Gemessen 2026-08-22: 26 von 42 Kopfzeilen-Literalen reißen diese Grenze (62 %), ' +
-      'Spitzenwert 54 Zeichen. Die 12 ist die Stilangabe der Tool-Beschreibung ' +
-      '(`max 12 chars`), KEINE erzwungene Grenze: im Bundle 2.1.268 steht die Zahl nur ' +
-      'in ebendieser Beschreibung, es gibt kein `.max(12)` im Zod-Schema und keinen ' +
-      'Render-Pfad, der sie liest — 125 längere Kopfzeilen wurden vom Tool angenommen ' +
-      'und beantwortet (gemessen 2026-09-11). Deshalb gilt H1 nur für VORLAGEN, wo ein ' +
-      'Autor kostenlos kürzen kann; zur Laufzeit meldet der Hook sie und blockt nicht ' +
-      '(siehe BLOCKING_HURDLES in hooks/pre-auq-clarity.mjs).',
-  }),
-  H2: Object.freeze({
-    id: 'H2',
-    title: '2–4 Optionen je Frage, genau eine Empfehlung auf Platz 1',
-    rule: 'options.length zwischen 2 und 4 JE FRAGE, und isRecommended nur bei index 0',
-    criterion: 'K6',
-    evidence:
-      'Pro Block gezählt meldet skills/plan/SKILL.md:137 fälschlich 14 Optionen — ' +
-      'es ist ein legaler Vierfragen-Block. Der Zähler zählt je Frage.',
-  }),
-});
-
-/** Stabile Reihenfolge. */
-export const HURDLE_IDS = Object.freeze(Object.keys(HURDLES));
-
 // ---------------------------------------------------------------------------
 // Schwellen — die einzige Stelle, an der eine Zahl steht
 // ---------------------------------------------------------------------------
+//
+// DEFINITIONSREIHENFOLGE IST TRAGEND: `HURDLES` weiter unten baut seine
+// operator-sichtbaren Sätze per Template-Literal aus `THRESHOLDS`, und ein
+// Template-Literal wird beim Laden des Moduls ausgewertet. Steht `THRESHOLDS`
+// wieder unter `HURDLES`, wirft der Import mit `ReferenceError` — auf einem
+// Modul, das `hooks/pre-auq-clarity.mjs` in JEDER Session lädt, ist das eine
+// host-weite Sperre, kein Testfehler.
 
 /**
  * Alle Schwellen, nach Kriterium gruppiert. clarity.mjs liest ausschließlich
@@ -356,6 +322,55 @@ export const THRESHOLDS = Object.freeze({
   }),
 });
 
+// ---------------------------------------------------------------------------
+// Die zwei harten Hürden
+// ---------------------------------------------------------------------------
+
+/**
+ * Hürden sind KEINE gewichteten Kriterien. Eine gerissene Hürde ergibt Note F,
+ * unabhängig von der Punktzahl — deshalb stehen sie getrennt und werden in
+ * `AuqScore.hurdlesBroken` geführt, nicht in `points` verrechnet.
+ *
+ * `title` und `rule` werden dem Operator GEDRUCKT (check-auq-clarity.mjs,
+ * auq-audit.mjs, der Deny-Text von hooks/pre-auq-clarity.mjs). Deshalb steht
+ * keine Zahl darin, sondern die Schwelle selbst: eine verschobene Schwelle mit
+ * einem stehengebliebenen Satz daneben ist eine Zeile, die den Operator belügt.
+ *
+ * @type {Readonly<Record<'H1'|'H2', Readonly<{id:string,title:string,rule:string,criterion:string,evidence:string}>>>}
+ */
+export const HURDLES = Object.freeze({
+  H1: Object.freeze({
+    id: 'H1',
+    title: `Kopfzeile höchstens ${THRESHOLDS.K5.headerCharsFail} Zeichen`,
+    rule: `codepointLength(header) <= ${THRESHOLDS.K5.headerCharsFail}`,
+    criterion: 'K5',
+    // `evidence` zitiert die Tool-Beschreibung des Bundles wörtlich
+    // (`max 12 chars`, `.max(12)`). Diese 12 ist die Zahl DES BUNDLES, nicht
+    // unsere Schwelle — sie bleibt ein Literal, auch wenn K5 sich bewegt.
+    evidence:
+      'Gemessen 2026-08-22: 26 von 42 Kopfzeilen-Literalen reißen diese Grenze (62 %), ' +
+      'Spitzenwert 54 Zeichen. Die 12 ist die Stilangabe der Tool-Beschreibung ' +
+      '(`max 12 chars`), KEINE erzwungene Grenze: im Bundle 2.1.268 steht die Zahl nur ' +
+      'in ebendieser Beschreibung, es gibt kein `.max(12)` im Zod-Schema und keinen ' +
+      'Render-Pfad, der sie liest — 125 längere Kopfzeilen wurden vom Tool angenommen ' +
+      'und beantwortet (gemessen 2026-09-11). Deshalb gilt H1 nur für VORLAGEN, wo ein ' +
+      'Autor kostenlos kürzen kann; zur Laufzeit meldet der Hook sie und blockt nicht ' +
+      '(siehe BLOCKING_HURDLES in hooks/pre-auq-clarity.mjs).',
+  }),
+  H2: Object.freeze({
+    id: 'H2',
+    title: `${THRESHOLDS.K6.optionsMin}–${THRESHOLDS.K6.optionsMax} Optionen je Frage, genau eine Empfehlung auf Platz 1`,
+    rule: `options.length zwischen ${THRESHOLDS.K6.optionsMin} und ${THRESHOLDS.K6.optionsMax} JE FRAGE, und isRecommended nur bei index 0`,
+    criterion: 'K6',
+    evidence:
+      'Pro Block gezählt meldet skills/plan/SKILL.md:137 fälschlich 14 Optionen — ' +
+      'es ist ein legaler Vierfragen-Block. Der Zähler zählt je Frage.',
+  }),
+});
+
+/** Stabile Reihenfolge. */
+export const HURDLE_IDS = Object.freeze(Object.keys(HURDLES));
+
 /** Höchstlänge eines Zitats in einem Befund (Codepoints). */
 export const EXCERPT_MAX_CHARS = 80;
 

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