@event4u/agent-config 14.1.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/skill_catalogue_series.ts

@@ -409,3 +409,94 @@ export function formatPointableBare(
     }
     return lines.join('\n');
 }
+
+/* ------------------------------------------------------------------ *
+ * The delivery filter — what the runtime router must not name.
+ * ------------------------------------------------------------------ */
+
+/**
+ * The bare names one host is KNOWN to have delivered, or `null` when nothing
+ * about that host's per-entry delivery was ever enumerated.
+ *
+ * `joinPointableBare` above answers "how large is the D-4 divergence" for an
+ * operator report. This answers the runtime question the same log can settle:
+ * given this host, which skill names must a pointer line not name? It is the
+ * reducer `skill_route_hook` consumes, and it lives here rather than in that
+ * hook for one reason — every guard below is already argued in this module's
+ * prose, and a second reducer over the same log is how two readers start
+ * breaking the same tie in opposite directions (`_supersedes`, in the parent
+ * module, exists because that happened once and printed two drop counts for one
+ * host on one day).
+ *
+ * THE THREE-WAY DISTINCTION IS THE WHOLE POINT, and collapsing any two of them
+ * is the failure:
+ *
+ *   - **`null` — nothing was enumerated.** No record for this host, or none of
+ *     its records is a `per-entry` observation, or the latest one carries no
+ *     `bare_names` array. The consumer must fail OPEN: filtering on this would
+ *     be a zero inferred from silence, and a filter that quietly narrows on
+ *     missing data is worse than the divergence it treats.
+ *   - **An EMPTY set — enumerated, and nothing was bare.** A legitimate answer,
+ *     and behaviourally identical to `null` at today's only consumer. It is
+ *     still returned distinctly, because "measured clean" and "never measured"
+ *     are different facts and this module refuses to let them look alike.
+ *   - **A NON-EMPTY set — these names went dark.** The pointer must not name
+ *     them.
+ *
+ * A `budget-strip-and-drop` host is therefore always `null` here, never an
+ * empty set: it publishes no per-entry list at all, so its empty `bare_names`
+ * records that nothing was counted. That is the same skip `joinPointableBare`
+ * makes, for the same reason, and it is why a codex install gets no filtering
+ * rather than a filter that believes nothing was degraded.
+ *
+ * LATEST WINS, per host, by `observed_at` — the `latestPointableBarePerHost`
+ * tie-break rather than a union across the series. A union would let a
+ * superseded observation keep suppressing a skill the host now delivers fine,
+ * which is a filter that only ever narrows; the whole series is available to an
+ * operator report, and a runtime filter wants the current reading.
+ *
+ * `bare_names` is guarded with `Array.isArray`, and `observed_at` with a
+ * `typeof` check, because `readObservationLog` produces records by an unchecked
+ * `JSON.parse … as` over an append-only log with more than one producer — the
+ * same guard, for the same recorded reason, that `joinPointableBare` and
+ * `knownHostLimits` carry. Both guards resolve to `null`, never to an older
+ * reading: a malformed LATEST record means the current state is unknown, and
+ * falling back to a superseded one would be the stale-suppression failure this
+ * function's own tie-break exists to prevent.
+ */
+export function knownBareNames(
+    records: readonly ObservationRecord[],
+    host: string,
+): Set<string> | null {
+    // The latest record for the host decides, and the mode is read OFF that
+    // record rather than used to select it. R2 finding 2: filtering `per-entry`
+    // first meant a NEWER `budget-strip-and-drop` record could never supersede
+    // an older `per-entry` one, so a host that changed truncation mode kept
+    // being filtered against a bare set from before the change — the precise
+    // failure the LATEST-WINS paragraph above claims to prevent.
+    //
+    // `headlineRecordPerHost` rather than a fourth inline tie-break (R2 finding
+    // 7): this module already imports it, already defines
+    // `latestPointableBarePerHost`, and its own comment cites `_supersedes` as
+    // the reason duplicate reducers are dangerous. Restating the rule here would
+    // have meant the runtime filter silently not inheriting any precedence the
+    // parent adds later.
+    //
+    // The `observed_at` pre-filter is R2 finding 6, and it is a pre-filter
+    // rather than a change to `_supersedes` because that reducer is shared.
+    // `_supersedes` compares dates with `!==` then `>`, and BOTH
+    // `undefined > "2026-08-12"` and `"2026-08-12" > undefined` are false — so a
+    // record with a missing or non-string date, once it becomes the incumbent,
+    // can never be displaced by a well-formed later one. One malformed line in
+    // an append-only log with two producers would pin the filter to it forever.
+    // Feeding the shared reducer only well-dated records avoids that without
+    // changing behaviour for its other callers.
+    const dated = records.filter(
+        (record) => record.host === host && typeof record.observed_at === 'string',
+    );
+    const latest = headlineRecordPerHost(dated).get(host);
+    if (latest === undefined) return null;
+    if (truncationModeOf(latest) !== 'per-entry') return null;
+    if (!Array.isArray(latest.bare_names)) return null;
+    return new Set(latest.bare_names.filter((name): name is string => typeof name === 'string'));
+}