@event4u/agent-config 14.2.0 → 14.4.0

package/src/scripts/_lib/roadmap_checkboxes.ts

@@ -0,0 +1,88 @@
+/**
+ * The checkbox vocabulary and the phase-span rule, in one place.
+ *
+ * R2 review, findings 11 and 15. Two scanners on the autonomous-run path —
+ * `run_checkpoint.countRoadmap` and `run_continuation_hook.scanOpenSteps` —
+ * each carried their own narrower regex and each scanned the WHOLE file, while
+ * both docblocks claimed the dashboard's vocabulary. Two consequences, and
+ * they pull in opposite directions:
+ *
+ *   - NARROWER VOCABULARY under-counts. Only `-` bullets and a lowercase `x`
+ *     matched, so a roadmap authored with `*` bullets or `[X]` read
+ *     `open === 0` and `run_supervise.classify` reported disposition
+ *     `complete` — "the run finished, the session just never said so" — for a
+ *     run with real open work. That is the exact confusion the watcher exists
+ *     to remove.
+ *   - WHOLE-FILE SCANNING over-counts. The dashboard attributes checkboxes to
+ *     `## Phase` spans; these did not. On the very roadmap under review every
+ *     phase step is closed and the only `- [ ]` sits under `## Acceptance criteria`, so
+ *     the continuation would have named "A killed session resumes via the
+ *     watcher…" as the next step — an observation of a live multi-day run, not
+ *     an executable step, and by construction with no `verify:` line. Steps
+ *     under `## Blockers` and `## Risk Register` are the same shape.
+ *
+ * The vocabulary is deliberately the dashboard's, character for character:
+ * where an autonomous run and the dashboard disagree about whether a roadmap
+ * is finished, the disagreement is the defect.
+ */
+
+/** Bullet `-` or `*`, mark ` `, `x`, `X`, `~` or `-`; body captured. */
+export const CHECKBOX_LINE = /^[ \t]*[-*][ \t]+\[([ xX~-])\][ \t]+(.*)$/;
+
+/** H2/H3 heading, its text captured. */
+const HEADING = /^(#{2,3})[ \t]+(.*?)[ \t]*$/;
+
+/** An H2/H3 that opens a phase span, matching the dashboard's PHASE_RE shape. */
+const PHASE_HEADING = /^Phase[ \t]+(?:\d+(?:\.\d+)*[a-z]?|[IVX]+|[A-Z](?:\d+)?)\b/;
+
+/**
+ * The lines of `text` that sit inside a `## Phase …` span.
+ *
+ * A phase span runs from its heading to the next heading AT ITS OWN LEVEL OR
+ * SHALLOWER. A DEEPER heading does not close it — an `### Measurement A`
+ * inside a `## Phase 1` is part of that phase, not the end of it.
+ *
+ * R2 round 6, critical finding 2, and it was live in this tree rather than
+ * hypothetical. The first version closed the span at ANY H2/H3, so on
+ * `road-to-ui-track-integrity-followup.md` — whose `## Phase 1` is immediately
+ * followed by three `###` sub-headings — `countRoadmap` returned `open: 0`
+ * against ten real open checkboxes. `ladder` then answers `complete` and
+ * `run_supervise` reports "the run finished, the session just never said so".
+ * That is the exact false-completion this module was written to prevent,
+ * produced by the module itself.
+ *
+ * `## Blockers`, `## Acceptance criteria` and `## Risk Register` still close a
+ * `## Phase` because they are H2s — the level rule gives that for free, and it
+ * is why the rule is a level comparison rather than a list of section names
+ * nobody would keep current.
+ *
+ * A roadmap with NO phase heading at all yields every line. That is the
+ * deliberate choice and it is the safe direction: an unphased roadmap is a
+ * legitimate shape, and returning nothing for it would make every such run
+ * read as `complete`, which is the more dangerous of the two errors.
+ */
+export function phaseLines(text: string): string[] {
+    const lines = text.split('\n');
+    const out: string[] = [];
+    // The heading level of the phase currently open, or 0 when none is.
+    let phaseLevel = 0;
+    let sawPhase = false;
+    for (const line of lines) {
+        const h = HEADING.exec(line);
+        if (h !== null) {
+            const level = (h[1] as string).length;
+            const isPhase = PHASE_HEADING.test(h[2] ?? '');
+            if (isPhase) {
+                phaseLevel = level;
+                sawPhase = true;
+            } else if (phaseLevel !== 0 && level <= phaseLevel) {
+                // A sibling or shallower section ends the phase.
+                phaseLevel = 0;
+            }
+            // A DEEPER non-phase heading leaves the span open.
+            continue;
+        }
+        if (phaseLevel !== 0) out.push(line);
+    }
+    return sawPhase ? out : lines;
+}

package/src/scripts/_lib/run_checkpoint.ts

@@ -0,0 +1,409 @@
+/**
+ * run_checkpoint — the deterministic checkpoint a dying run leaves behind,
+ * and the re-verification a resumed run owes before trusting it.
+ *
+ * road-to-long-horizon-execution Phase 3.0 / 3.2 (sequencing UOTL Phase 6.1).
+ *
+ * ## Why "deterministic" is the load-bearing word
+ *
+ * A handoff summary is authored — a model writes prose about where the work
+ * stands, and prose can be wrong in ways nothing catches. A checkpoint is
+ * DERIVED: every field here is recomputed from files on disk, so writing one
+ * costs no judgement and reading one back can be checked against the tree
+ * that produced it. The two are complements, not alternatives: the summary
+ * says what the run was thinking, this says what the run had actually done.
+ *
+ * ## Why a resumed run re-verifies rather than trusts
+ *
+ * The reference design this borrows from resumes by BOOKKEEPING — the daemon
+ * believes its own record of where a session was. That is fine while nothing
+ * else touches the tree, and wrong the moment something does: a human
+ * committing, a sibling worktree, a partially-applied edit the dying session
+ * never finished. So `verifyCheckpoint` recomputes the same fields and reports
+ * a per-field agreement rather than a boolean — a resumed run should be able
+ * to say WHICH claim went stale, not merely that something did.
+ *
+ * A disagreement is explicitly NOT an error here. Work landing between the
+ * checkpoint and the resume is the normal case, and a verifier that treats
+ * progress as corruption would refuse every healthy resume.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { CHECKBOX_LINE, phaseLines } from './roadmap_checkboxes.js';
+
+export const CHECKPOINT_DIR_REL = path.join('agents', 'runtime', 'state', 'checkpoints');
+
+/**
+ * A run's derived state at the moment its session ended.
+ *
+ * Every field is recomputed, never remembered — that is what makes
+ * `verifyCheckpoint` possible at all.
+ */
+export interface RunCheckpoint {
+    readonly schema_version: 1;
+    /** The session-derived run id this checkpoint belongs to. */
+    readonly run_id: string;
+    /** Roadmap slug from the session's `sessions:claim` file. */
+    readonly roadmap: string;
+    /** Steps still `[ ]` at checkpoint time. */
+    readonly open_steps: number;
+    /** Steps already `[x]` at checkpoint time. */
+    readonly done_steps: number;
+    /** `[~]` deferred plus `[-]` cancelled — neither is open work. */
+    readonly parked_steps: number;
+    /** The next `[ ]` step's text, trimmed, or `null` when none remains. */
+    readonly next_step: string | null;
+    /** Commit the tree was on. A resume onto a different commit is normal, and visible. */
+    readonly head: string | null;
+    readonly written_at: string;
+}
+
+/** Counts derived from a roadmap body — the same vocabulary the loop uses. */
+export interface RoadmapCounts {
+    open: number;
+    done: number;
+    parked: number;
+    next: string | null;
+}
+
+/**
+ * Count checkboxes in a roadmap body.
+ *
+ * `[~]` (deferred) and `[-]` (cancelled) are PARKED, not open: a resumed run
+ * that treated them as work to do would re-engage into the exact items a human
+ * decided not to do, which is the anti-stall mechanism manufacturing a stall.
+ */
+export function countRoadmap(text: string): RoadmapCounts {
+    const counts: RoadmapCounts = { open: 0, done: 0, parked: 0, next: null };
+    // Phase spans only, and the dashboard's own vocabulary — see
+    // `_lib/roadmap_checkboxes.ts` for what each half was getting wrong.
+    for (const raw of phaseLines(text)) {
+        const m = CHECKBOX_LINE.exec(raw);
+        if (m === null) continue;
+        const mark = m[1];
+        if (mark === 'x' || mark === 'X') {
+            counts.done += 1;
+        } else if (mark === '~' || mark === '-') {
+            counts.parked += 1;
+        } else {
+            counts.open += 1;
+            if (counts.next === null) {
+                counts.next = (m[2] ?? '').trim() || null;
+            }
+        }
+    }
+    return counts;
+}
+
+export function checkpointFile(repoRoot: string, runId: string): string {
+    return path.join(repoRoot, CHECKPOINT_DIR_REL, `${runId.replace(/[^A-Za-z0-9_-]/g, '_')}.json`);
+}
+
+export function roadmapPath(repoRoot: string, slug: string): string {
+    return path.join(repoRoot, 'agents', 'roadmaps', `${slug}.md`);
+}
+
+export interface BuildOptions {
+    /** Injected so a test does not depend on the ambient git state. */
+    readonly head?: string | null;
+    readonly now?: () => Date;
+}
+
+/**
+ * The current commit, read straight off `.git` — no subprocess.
+ *
+ * R2 round 2, finding 5. `head` was populated only from `opts.head`, and the
+ * ONE production caller (`session_eol_hook`) never passed it, so the field was
+ * always `null` while the checkpoint's own docblock, the loop contract and the
+ * roadmap all describe it as carrying the commit the tree was on. Only the
+ * test injected a value, which is why nothing noticed.
+ *
+ * No `git rev-parse`: this runs on the Stop path, where a spawn is a cost paid
+ * on every reply. Two files answer it — and a WORKTREE is the case a naive
+ * reader gets wrong, because there `.git` is a FILE holding `gitdir: <path>`
+ * rather than a directory. This package is developed in worktrees, so the naive
+ * version would have returned null exactly where it was being exercised.
+ *
+ * Returns `null` on anything unexpected. A checkpoint without a commit is
+ * still useful; a Stop path that throws is not.
+ */
+export function readHead(repoRoot: string): string | null {
+    try {
+        let gitDir = path.join(repoRoot, '.git');
+        if (fs.statSync(gitDir).isFile()) {
+            const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(gitDir, 'utf-8').trim());
+            if (m === null) return null;
+            gitDir = path.resolve(repoRoot, m[1] as string);
+        }
+        // HEAD is per-worktree; REFS are not. A linked worktree's gitdir holds
+        // its own HEAD and a `commondir` pointer, and `refs/` + `packed-refs`
+        // live at that commondir — never beside HEAD.
+        //
+        // R2 round 3, finding 1, and the round-2 version of this function got
+        // it exactly half right: it handled `.git`-as-a-file and then resolved
+        // refs against the worktree gitdir, so `head` was null in every linked
+        // worktree — including the one this package is developed in. Its test
+        // passed because the fixture wrote refs beside HEAD, a layout git never
+        // produces. A fixture that agrees with the code instead of with reality
+        // reads as coverage and is worse than no test at all.
+        let refRoot = gitDir;
+        try {
+            const common = fs.readFileSync(path.join(gitDir, 'commondir'), 'utf-8').trim();
+            if (common !== '') refRoot = path.resolve(gitDir, common);
+        } catch {
+            // No commondir — a plain repository, where gitDir already is it.
+        }
+        const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf-8').trim();
+        // A detached HEAD is the sha itself.
+        if (/^[0-9a-f]{40}$/.test(head)) return head;
+        const ref = /^ref:\s*(.+)$/.exec(head);
+        if (ref === null) return null;
+        const refName = ref[1] as string;
+        try {
+            return fs.readFileSync(path.join(refRoot, refName), 'utf-8').trim() || null;
+        } catch {
+            // Packed refs: a loose file does not exist for every branch.
+            const packed = fs.readFileSync(path.join(refRoot, 'packed-refs'), 'utf-8');
+            for (const line of packed.split('\n')) {
+                const pm = /^([0-9a-f]{40})\s+(.+)$/.exec(line.trim());
+                if (pm !== null && pm[2] === refName) return pm[1] as string;
+            }
+            return null;
+        }
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Derive a checkpoint from the tree. Returns `null` when the roadmap is
+ * unreadable — a checkpoint that guesses is worse than none, because the whole
+ * contract of this file is that its fields were computed rather than recalled.
+ */
+export function buildCheckpoint(
+    repoRoot: string,
+    runId: string,
+    slug: string,
+    opts: BuildOptions = {},
+): RunCheckpoint | null {
+    let text: string;
+    try {
+        text = fs.readFileSync(roadmapPath(repoRoot, slug), 'utf-8');
+    } catch {
+        return null;
+    }
+    const counts = countRoadmap(text);
+    return {
+        schema_version: 1,
+        run_id: runId,
+        roadmap: slug,
+        open_steps: counts.open,
+        done_steps: counts.done,
+        parked_steps: counts.parked,
+        next_step: counts.next,
+        head: opts.head ?? readHead(repoRoot),
+        written_at: (opts.now ?? ((): Date => new Date()))().toISOString(),
+    };
+}
+
+/** Write a checkpoint. Best-effort: a failed write must never break a Stop. */
+export function writeCheckpoint(repoRoot: string, cp: RunCheckpoint): string | null {
+    const file = checkpointFile(repoRoot, cp.run_id);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, `${JSON.stringify(cp, null, 2)}\n`, 'utf-8');
+        return file;
+    } catch {
+        return null;
+    }
+}
+
+export function readCheckpoint(repoRoot: string, runId: string): RunCheckpoint | null {
+    try {
+        const parsed: unknown = JSON.parse(fs.readFileSync(checkpointFile(repoRoot, runId), 'utf-8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+        const o = parsed as Record<string, unknown>;
+        if (typeof o['run_id'] !== 'string' || typeof o['roadmap'] !== 'string') return null;
+        if (typeof o['open_steps'] !== 'number' || typeof o['done_steps'] !== 'number') return null;
+        return parsed as RunCheckpoint;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The most recent checkpoint for a ROADMAP, across every run id.
+ *
+ * R2 review, finding 7. `readCheckpoint` keys on the run id, which is derived
+ * from the session id of the session that DIED — so a relaunched session, which
+ * by definition has a new id and no index from slug to old id, could not reach
+ * its own checkpoint through any path in the tree. `verifyCheckpoint` and
+ * `renderVerification` had zero production call sites, and the loop contract
+ * nonetheless instructed a resumed run that "the first act is verifyCheckpoint".
+ * The mitigation Risk 5 names was unreachable as shipped.
+ *
+ * The roadmap slug is the one key a relaunched run genuinely holds: it claims
+ * the same roadmap, which is what makes it a resume rather than a new run.
+ *
+ * Ties are broken by `written_at` descending, then by filename, so the result
+ * is deterministic when two checkpoints share a timestamp. A malformed or
+ * unreadable file is skipped rather than failing the lookup — a resume that
+ * refuses to start because one stale JSON file is corrupt is worse than a
+ * resume that verifies against the newest readable one.
+ */
+export function latestCheckpointFor(repoRoot: string, roadmap: string): RunCheckpoint | null {
+    const dir = path.join(repoRoot, CHECKPOINT_DIR_REL);
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
+    } catch {
+        return null;
+    }
+    const found: RunCheckpoint[] = [];
+    for (const name of names.sort()) {
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf-8'));
+        } catch {
+            continue;
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) continue;
+        const o = parsed as Record<string, unknown>;
+        if (o['roadmap'] !== roadmap) continue;
+        if (typeof o['run_id'] !== 'string') continue;
+        if (typeof o['open_steps'] !== 'number' || typeof o['done_steps'] !== 'number') continue;
+        found.push(parsed as RunCheckpoint);
+    }
+    if (found.length === 0) return null;
+    found.sort((a, b) => {
+        const at = String(a.written_at ?? '');
+        const bt = String(b.written_at ?? '');
+        if (at !== bt) return at < bt ? 1 : -1;
+        return a.run_id < b.run_id ? 1 : -1;
+    });
+    return found[0] ?? null;
+}
+
+/** One claim's verdict — the field, what was claimed, what is true now. */
+export interface FieldVerdict {
+    readonly field: string;
+    readonly claimed: string | number | null;
+    readonly actual: string | number | null;
+    readonly agrees: boolean;
+}
+
+export interface VerifyResult {
+    /** `false` when the roadmap named by the checkpoint no longer reads. */
+    readonly readable: boolean;
+    readonly fields: readonly FieldVerdict[];
+    /** Every field agreed. NOT a precondition for resuming — see the header. */
+    readonly agrees: boolean;
+}
+
+/**
+ * Recompute the checkpoint's claims against the tree as it is NOW.
+ *
+ * Reports per-field rather than a boolean on purpose: "the checkpoint is
+ * stale" tells a resumed run nothing it can act on, while "open_steps claimed
+ * 4, actual 3" tells it a step landed after the checkpoint was written and
+ * which count to trust.
+ */
+export function verifyCheckpoint(repoRoot: string, cp: RunCheckpoint): VerifyResult {
+    let text: string;
+    try {
+        text = fs.readFileSync(roadmapPath(repoRoot, cp.roadmap), 'utf-8');
+    } catch {
+        return { readable: false, fields: [], agrees: false };
+    }
+    const counts = countRoadmap(text);
+    // Read ONCE, so the recorded `actual` and the verdict about it are one
+    // expression rather than two that happen to agree.
+    const head = readHead(repoRoot);
+    const fields: FieldVerdict[] = [
+        { field: 'open_steps', claimed: cp.open_steps, actual: counts.open, agrees: cp.open_steps === counts.open },
+        { field: 'done_steps', claimed: cp.done_steps, actual: counts.done, agrees: cp.done_steps === counts.done },
+        { field: 'parked_steps', claimed: cp.parked_steps, actual: counts.parked, agrees: cp.parked_steps === counts.parked },
+        { field: 'next_step', claimed: cp.next_step, actual: counts.next, agrees: cp.next_step === counts.next },
+        // `head` is recomputed like every other field. R2 round 3, finding 2:
+        // round 2 fixed only the WRITE half of finding 5, so the loop
+        // contract's "every field is recomputed" was false for exactly the
+        // field that says whether the tree moved under the run — which is the
+        // one a resume most needs to see. A disagreement here is the NORMAL
+        // case (a human committed, a sibling worktree moved) and is reported,
+        // never treated as corruption.
+        {
+            field: 'head',
+            claimed: cp.head,
+            actual: head,
+            // A `null` on EITHER side is "not known", never "different".
+            //
+            // R2 round 4, finding 2. `readHead` is explicitly designed to
+            // return null on any failure — no git, an unreadable ref, a
+            // packed-refs miss — so a strict `===` turned "I could not read
+            // the commit" into "the tree moved since the checkpoint", on a
+            // resume at the SAME commit with every other field agreeing. That
+            // is a false alarm on the one field whose whole job is to tell a
+            // human whether anything moved, and a false alarm there costs more
+            // than a missing one: it trains the reader to skip the line.
+            agrees: cp.head === null || head === null || cp.head === head,
+        },
+    ];
+    return { readable: true, fields, agrees: fields.every((f) => f.agrees) };
+}
+
+/** A one-line-per-field report a resumed run can put in front of a human. */
+export function renderVerification(cp: RunCheckpoint, res: VerifyResult): string {
+    if (!res.readable) {
+        return (
+            `checkpoint ${cp.run_id}: roadmap '${cp.roadmap}' no longer reads — ` +
+            `the claimed state cannot be re-verified, so none of it may be assumed.`
+        );
+    }
+    const lines = [`checkpoint ${cp.run_id} · roadmap ${cp.roadmap} · written ${cp.written_at}`];
+    // Three states, not two. R2 round 5, finding 3: the null-head tolerance
+    // added in round 4 is correct as a VERDICT — an unknown commit is not a
+    // moved one — but rendering it as `ok head: null` alongside "the tree
+    // still matches the checkpoint" tells the reader something was checked
+    // when nothing could be. UNKNOWN is a third word because the reader's next
+    // action differs: `ok` needs nothing, `CHANGED` names what moved, and
+    // UNKNOWN says this axis carries no information and the other four are
+    // what the verdict rests on.
+    // ONLY `head` can be unknown. R2 round 6, finding 6: the predicate was
+    // written for `head` — where `null` means "could not read" — and applied
+    // to all five fields, but for `next_step` a `null` is a documented VALUE
+    // ("or `null` when none remains"). A finished roadmap therefore rendered
+    // `UNKNOWN next_step: not readable` and claimed a field had not been
+    // compared when it had been, on the exact state a resume most wants to
+    // see. The field name is the discriminator because the meaning of `null`
+    // is a property of the field, not of the value.
+    const UNKNOWNABLE: ReadonlySet<string> = new Set(['head']);
+    let unknown = 0;
+    for (const f of res.fields) {
+        if (UNKNOWNABLE.has(f.field) && (f.claimed === null || f.actual === null)) {
+            unknown += 1;
+            lines.push(
+                `  UNKNOWN  ${f.field}: not readable ` +
+                    `(claimed ${String(f.claimed)}, actual ${String(f.actual)}) — not compared`,
+            );
+            continue;
+        }
+        lines.push(
+            f.agrees
+                ? `  ok       ${f.field}: ${String(f.actual)}`
+                : `  CHANGED  ${f.field}: claimed ${String(f.claimed)} → actual ${String(f.actual)}`,
+        );
+    }
+    if (!res.agrees) {
+        lines.push('  the tree moved since the checkpoint — the ACTUAL column is what to resume from.');
+    } else if (unknown > 0) {
+        lines.push(
+            `  the ${res.fields.length - unknown} comparable field(s) match; ` +
+                `${unknown} could not be read and were not compared.`,
+        );
+    } else {
+        lines.push('  the tree still matches the checkpoint.');
+    }
+    return lines.join('\n');
+}

package/src/scripts/_lib/session_register.ts

@@ -321,10 +321,37 @@ export function delete_record(dir: string, session_id: string): boolean {
 export interface ReadLiveOptions {
     /** Unlink expired records as they are encountered. Default `false`. */
     prune?: boolean;
+    /**
+     * How long an EXPIRED record survives the prune. Default 24 h.
+     *
+     * R2 round 4, finding 5. The register has two consumers with opposite
+     * needs and only one of them knew: `sessions:list` and the session-start
+     * hook both read with `prune: true`, while `run:supervise` exists
+     * ENTIRELY to classify expired records — the runs whose session died. So
+     * the watcher's whole input was deleted by two routine read paths, the
+     * hook one of them, which fires on every session start. The digest could
+     * then report nothing, and round 3's `clearCompleted` release could never
+     * fire because no completed candidate ever reached it.
+     *
+     * The 24 h is derived, not picked: `digest` is documented as the MORNING
+     * report, so a once-a-day reader must be able to see a full day of deaths.
+     * A shorter grace loses runs that died overnight, which is precisely the
+     * population the watcher was built for.
+     *
+     * `0` restores the old delete-on-sight behaviour for a caller that really
+     * wants it. Nothing in the tree passes it today.
+     */
+    prune_grace_ms?: number;
     /** Clock injection for tests. */
     now?: Date;
 }
 
+/**
+ * How long an expired record outlives its expiry before a prune may remove it.
+ * See {@link ReadLiveOptions.prune_grace_ms} for why this is a day.
+ */
+export const PRUNE_GRACE_MS = 24 * 60 * 60 * 1000;
+
 /**
  * Every live record in the register, optionally pruning expired ones as it goes.
  *
@@ -339,6 +366,7 @@ export interface ReadLiveOptions {
 export function read_live_records(dir: string, options: ReadLiveOptions = {}): SessionRecord[] {
     const now = options.now ?? new Date();
     const prune = options.prune === true;
+    const grace = options.prune_grace_ms ?? PRUNE_GRACE_MS;
     let names: string[];
     try {
         names = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
@@ -356,7 +384,10 @@ export function read_live_records(dir: string, options: ReadLiveOptions = {}): S
             rec = null;
         }
         if (rec === null || is_expired(rec, now)) {
-            if (prune) {
+            // A record is dropped from the LIVE set the moment it expires, and
+            // deleted from disk only after the grace window — the watcher
+            // reads the register directly and needs the expired ones.
+            if (prune && (rec === null || is_expired(rec, new Date(now.getTime() - grace)))) {
                 try {
                     fs.unlinkSync(full);
                 } catch {

package/src/scripts/_lib/stdin.ts

@@ -41,6 +41,31 @@ function _sleepSync(ms: number): void {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
+/** Options for {@link readStdinText}. */
+export interface ReadStdinOptions {
+    /**
+     * Give up and return `''` when the FIRST byte has not arrived within this
+     * many milliseconds. Undefined (the default) keeps the historical behaviour:
+     * the full {@link MAX_RETRIES} budget applies from the first read, which is
+     * what a `gh pr diff` pipe needs — its first byte can legitimately take a
+     * while, and reporting that as empty input is the defect this module exists
+     * to prevent.
+     *
+     * A HOOK is the opposite case, and it cost a CI hang to learn the difference.
+     * The host writes the payload synchronously on spawn, so a byte that has not
+     * arrived promptly is not a slow writer — it is an fd 0 nobody will ever
+     * write to, which is what a child inherits when a test spawns it without
+     * piping stdin. With no cap the dispatcher then span the full ~10 s budget on
+     * EVERY such invocation and returned "" anyway; measured 12.4 s per call
+     * against an immediate return before the retry loop existed. Hundreds of
+     * those hung three Node-Tests shards for over an hour.
+     *
+     * Once ANY byte has arrived the cap no longer applies: a writer demonstrably
+     * exists, so the full budget is right and the large-payload fix is intact.
+     */
+    firstByteTimeoutMs?: number;
+}
+
 /**
  * Read all of fd 0 as UTF-8.
  *
@@ -48,10 +73,13 @@ function _sleepSync(ms: number): void {
  *         {@link MAX_RETRIES} consecutive EAGAINs — a caller must not be able to
  *         mistake a failed read for empty input.
  */
-export function readStdinText(fd = 0): string {
+export function readStdinText(fd = 0, opts: ReadStdinOptions = {}): string {
     const chunks: Buffer[] = [];
     const buf = Buffer.alloc(CHUNK);
     let retries = 0;
+    let got_any = false;
+    const first_byte_deadline =
+        opts.firstByteTimeoutMs === undefined ? null : Date.now() + opts.firstByteTimeoutMs;
     for (;;) {
         let read: number;
         try {
@@ -60,6 +88,11 @@ export function readStdinText(fd = 0): string {
         } catch (exc) {
             const code = (exc as NodeJS.ErrnoException).code;
             if (code === 'EAGAIN') {
+                // An idle fd 0 is "no input", not a slow writer — but only
+                // before the first byte. See ReadStdinOptions.firstByteTimeoutMs.
+                if (!got_any && first_byte_deadline !== null && Date.now() >= first_byte_deadline) {
+                    return '';
+                }
                 retries += 1;
                 if (retries > MAX_RETRIES) {
                     throw new Error(
@@ -76,6 +109,7 @@ export function readStdinText(fd = 0): string {
             throw exc;
         }
         if (read === 0) break;
+        got_any = true;
         chunks.push(Buffer.from(buf.subarray(0, read)));
     }
     return Buffer.concat(chunks).toString('utf-8');

package/src/scripts/_lib/turn_end_refusals.ts

@@ -45,10 +45,18 @@ import { read_lockfile } from './installed_lock.js';
  *
  * The roadmap's § 0 names three (A promissory, B language, C verification).
  * That was true of the draft and is not true of the tree: detector D
- * (`completion`) landed under round 7 § Phase 1 and is in the same
- * unconditional list as the other three. Counting three would silently drop a
- * detector's refusals, so the set is read off `DetectorId` in the gate rather
- * than off the prose.
+ * (`completion`) landed under round 7 § Phase 1 and runs in the same detector
+ * list as the other three. Counting three would silently drop a detector's
+ * refusals, so the set is read off `DetectorId` in the gate rather than off the
+ * prose.
+ *
+ * This said "the same UNCONDITIONAL list" until 2026-08-18, which was wrong and
+ * is worth naming rather than quietly rewording: `main()` runs A and D only when
+ * no subagent dispatch is open. It does not change this set — every detector
+ * that CAN fire needs a counter — but it does change what a reader may conclude
+ * from a zero here: A's and D's counts are censored by that third allow path,
+ * and `docs/contracts/turn-end-detector-demotion.md` is where that consequence
+ * is carried.
  */
 export const DETECTOR_IDS = [
     'promissory',