create-agent-rig 0.5.0 → 0.6.0

package/templates/agent-os/universal/.claude/scripts/queue/plan-md.mjs

@@ -12,7 +12,8 @@
 // has real dependencies, move to an adapter whose tracker can express them
 // (`github-issues`). Ordering the list by hand is not a dependency graph.
 import { readFileSync, writeFileSync } from 'node:fs';
-import { duplicateOf, fingerprintOf, validateProposal } from './core.mjs';
+import { duplicateOf, fingerprintOf, validateProposal, lifecycleOf } from './core.mjs';
+import { withAsOf } from './as-of.mjs';
 import { recordEscalation } from '../run-state.mjs';
 
 export const name = 'plan-md';
@@ -60,6 +61,17 @@ const MARKERS = {
   triage: /\[triage\]/i,
   triggerAuto: /\[trigger-auto\]/i,
   triggerHuman: /\[trigger-human\]/i,
+  // `[owner:<name>]` — the repository the item belongs to (AR-132), the same
+  // fact the tracker adapters read out of an `owner-<name>` label. Case-exact,
+  // because the name is compared exactly to `options.owner`.
+  owner: /\[owner:([^\]\s]+)\]/,
+  // AR-144: the lifecycle vocabulary and the scheduling flag, the same words the
+  // tracker adapters read as labels. Case-insensitive, as the tier and trigger
+  // markers are (the owner marker is case-exact, because it is compared to a name).
+  keepCore: /\[keep-core\]/i,
+  reScope: /\[re-scope\]/i,
+  obsolete: /\[obsolete\]/i,
+  parked: /\[parked\]/i,
 };
 
 /**
@@ -91,7 +103,10 @@ export const parsePlan = (plan) => {
     if (!match) continue;
     const raw = match[1];
     const title = raw
-      .replace(/\[(elevated|triage|trigger-auto|trigger-human)\]/gi, '')
+      .replace(
+        /\[(elevated|triage|trigger-auto|trigger-human|keep-core|re-scope|obsolete|parked|owner:[^\]\s]+)\]/gi,
+        '',
+      )
       .replace(/\s+/g, ' ')
       .trim();
     items.push({
@@ -114,12 +129,29 @@ export const parsePlan = (plan) => {
       blocks: [],
       priority: items.length,
       createdAt: null,
+      // A flat list carries no marker at all, so revalidation at SELECT records
+      // `changed: null` for it — a blind spot, never an "unchanged".
+      updatedAt: null,
       triage: MARKERS.triage.test(raw),
       trigger: MARKERS.triggerAuto.test(raw)
         ? 'auto'
         : MARKERS.triggerHuman.test(raw)
           ? 'human'
           : null,
+      owner: MARKERS.owner.exec(raw)?.[1] ?? null,
+      // The markers present, handed to the one precedence rule (`core.mjs` ›
+      // lifecycleOf) rather than re-deriving it here. Hygiene cannot report a
+      // contradiction on this adapter: a flat list carries no labels for it to read.
+      ...lifecycleOf(
+        [
+          ['keep-core', MARKERS.keepCore],
+          ['re-scope', MARKERS.reScope],
+          ['obsolete', MARKERS.obsolete],
+          ['parked', MARKERS.parked],
+        ]
+          .filter(([, marker]) => marker.test(raw))
+          .map(([label]) => label),
+      ),
     });
   }
   return items;
@@ -190,10 +222,20 @@ export const claim = (ticket) => ({
     'its own worktree and say so in the journal.',
 });
 
+/** One item by position; a flat list has no closed state, so an absent line is `null`. */
+export const find = (id, options = {}) =>
+  parsePlan(readPlan(options)).find((ticket) => ticket.id === String(id)) ?? null;
+
 export const close = (ticket, { prUrl = null, planPath: p } = {}) => {
   const file = p ?? 'PLAN.md';
-  writeFileSync(file, closeInPlan(readFileSync(file, 'utf8'), ticket.id));
-  return { ok: true, prUrl };
+  const before = readFileSync(file, 'utf8');
+  const present = parsePlan(before).some((item) => item.id === String(ticket.id));
+  writeFileSync(file, closeInPlan(before, ticket.id));
+  // `transitioned` means the line was there and is now gone — an id the plan
+  // never carried closed nothing, and saying otherwise would publish a close
+  // that changed no state (AR-135).
+  const gone = !parsePlan(readFileSync(file, 'utf8')).some((item) => item.id === String(ticket.id));
+  return { ok: true, prUrl, transitioned: present && gone };
 };
 
 /** A flat list has no comment thread; the journal is where this lands. */
@@ -242,8 +284,10 @@ export const triageItemFor = (proposal) => {
       `- **part to change** — ${proposal.part}`,
       `- **proposed change** — ${proposal.change}`,
       `- **how the next run proves it** — ${proposal.proof}`,
+      ...(proposal.measured ? [`- **measured** — ${proposal.measured}`, `- **inferred** — ${proposal.inferred}`] : []),
       '',
       `fingerprint: ${fingerprint}`,
+      ...(proposal.asOf ? [`asOf: ${proposal.asOf}`] : []),
       '',
       'The loop proposes; the owner patches. Self-applying a change to its own',
       'rulebook is how an unattended run drifts irreversibly.',
@@ -316,8 +360,26 @@ export const oneLine = (text) => String(text ?? '').replace(/\s+/g, ' ').trim();
 const bulletFor = (item, proposal, seen) =>
   `- **${oneLine(item.title)}** — finding: ${oneLine(proposal.finding)} · ` +
   `part: ${oneLine(proposal.part)} · proof: ${oneLine(proposal.proof)} · ` +
+  `${proposal.measured ? `measured: ${oneLine(proposal.measured)} · inferred: ${oneLine(proposal.inferred)} · ` : ''}` +
+  `${proposal.asOf ? `asOf: ${proposal.asOf} · ` : ''}` +
   `fingerprint: \`${item.fingerprint}\` · seen ×${seen}`;
 
+/**
+ * The proposals on file, as `{ id, body }` — every Operator-queue line carrying
+ * this adapter's trailing field shape, the whole line as the body so `asOfOf`
+ * and `citedPathsOf` can read it. An absent Operator queue lists nothing.
+ */
+export const listProposals = ({ planPath: p } = {}) => {
+  const plan = readFileSync(p ?? 'PLAN.md', 'utf8');
+  const { found, lines, start, end } = sectionRange(plan, OPERATOR_QUEUE);
+  if (!found) return [];
+  const proposals = [];
+  for (let i = start; i < end; i += 1) {
+    if (TAIL.test(lines[i])) proposals.push({ id: String(i), body: lines[i] });
+  }
+  return proposals;
+};
+
 /**
  * File a proposal into the **Operator queue** — never the Agent queue.
  *
@@ -387,7 +449,8 @@ const bulletFor = (item, proposal, seen) =>
  *   the bullet stays unselectable — but a reader sees it under the wrong
  *   heading.
  */
-export const proposeTriage = (proposal, { planPath: p } = {}) => {
+export const proposeTriage = (rawProposal, { planPath: p } = {}) => {
+  const proposal = withAsOf(rawProposal);
   const item = triageItemFor(proposal);
   const file = p ?? 'PLAN.md';
   const plan = readFileSync(file, 'utf8');

package/templates/agent-os/universal/.claude/scripts/revalidate.mjs

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+/**
+ * Revalidation at BEFORE_PR — is the branch about to ship still the branch the
+ * run took up?
+ *
+ *   node .claude/scripts/revalidate.mjs --point BEFORE_PR --ticket <id> [--base origin/master] [--config <queue.json>] [--json]
+ *
+ * Two sources, compared and named separately, because a hold that cannot say
+ * WHAT moved sends the run to re-read everything:
+ *
+ * - `task:updatedAt` — the item's marker now, read through the queue adapter,
+ *   against the take-up snapshot `queue/index.mjs next` recorded in the run's
+ *   `state.json` (`takeUps`, AR-133). No snapshot, no marker or no run → that
+ *   source is `null`: not looked, never "unchanged".
+ * - `main:<path>` — what the default branch changed since this branch forked
+ *   (`git merge-base <base> HEAD` … `<base>`), intersected with the CITED
+ *   paths. Cited is a labelled assumption, not a recorded fact: the paths the
+ *   branch itself touches, plus every `blockers[].file` of a `check-premises`
+ *   record in this run's journal — the files the run said its premises rest
+ *   on. An unrelated change on the default branch does not hold.
+ *
+ * At BEFORE_CLOSE (AR-135) there is no git and no main: the sources are
+ * `task:updatedAt` against the LAST VALIDATION — the `task.to` of this run's
+ * latest `revalidation` event for the item, falling back to the take-up
+ * snapshot — and `task:state`, which is expected `in-progress` at close and
+ * is a change when someone closed the item or moved it back. The item comes
+ * from the adapter's `find`, which sees closed items where `listEligible`
+ * drops them; one the tracker no longer offers at all reads `missing`, and
+ * either holds on `task:state` (revalidate.test.ts › "holds on task:state when
+ * someone already closed the item", › "holds on task:state when the tracker no
+ * longer offers the item"). The result lists the item's dependants (`blocks`)
+ * and re-reads each one's state through the same `find` (revalidate.test.ts ›
+ * "re-reads each dependant's state, and names one the tracker no longer
+ * offers") for the loop's write-back.
+ *
+ * The aggregates are `queue/core.mjs` › beforePrRevalidationOf and
+ * beforeCloseRevalidationOf; this file is the I/O around them.
+ *
+ * `outcome --point <P> --ticket <id> --action-changed true|false [--note …]`
+ * (AR-136) is the second half of the evidence: after the re-read, it appends a
+ * `revalidation-outcome` record whose `answers` is the seq of the latest
+ * `revalidation` for that ticket and point in this run — the join a report
+ * needs, made by the writer rather than guessed by the reader. It refuses
+ * without a run, without a matching revalidation, and with any word but
+ * `true`/`false`, and writes nothing then. Exit 2 on `hold`, 0 on `continue` and `unverifiable`, 1 when
+ * the arguments cannot be acted on (unknown point, no ticket, a base that is
+ * not a revision) — and then nothing is journalled, because a refusal is not
+ * an answer.
+ *
+ * ⚠ It reads `<base>` as it is in this checkout and never updates the remote
+ * ref itself; `pr-ship` step 1 does that before calling this. A stale ref
+ * makes this compare against yesterday's main and report `continue` — see
+ * revalidate.test.ts › "reads the ref as it is: a stale origin/master reports
+ * continue".
+ */
+
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { withoutGitLocation } from './git-env.mjs';
+import { readRun, recordEvent } from './run-journal.mjs';
+import { readState } from './run-state.mjs';
+import { POINTS as ALL_POINTS, REVALIDATES } from './lib/revalidation-points.mjs';
+import { beforeCloseRevalidationOf, beforePrRevalidationOf, revalidationOf } from './queue/core.mjs';
+import { loadConfig, optionsWithPlanPath, resolveAdapter } from './queue/index.mjs';
+
+// Derived from the one source, never restated here (AR-137).
+export const POINTS = REVALIDATES;
+
+const revisionOrNull = (value) =>
+  typeof value === 'string' && value !== '' && !value.startsWith('-') ? value : null;
+
+const parseArgs = (argv) => {
+  const args = {
+    outcome: false,
+    point: null,
+    ticket: null,
+    base: 'origin/master',
+    config: null,
+    json: false,
+    actionChanged: null,
+    note: null,
+    bad: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (i === 0 && arg === 'outcome') args.outcome = true;
+    else if (arg === '--json') args.json = true;
+    else if (arg === '--action-changed') args.actionChanged = argv[++i] ?? null;
+    else if (arg === '--note') args.note = argv[++i] ?? null;
+    else if (arg === '--point') args.point = argv[++i] ?? null;
+    else if (arg === '--ticket') {
+      // The id reaches git-free paths only, but on github-issues it becomes a
+      // `gh` argv element: a value starting with `-` would be read as an option.
+      const value = revisionOrNull(argv[++i]);
+      if (value === null) args.bad = arg;
+      else args.ticket = value;
+    }
+    else if (arg === '--config') args.config = argv[++i] ?? null;
+    else if (arg === '--base') {
+      const value = revisionOrNull(argv[++i]);
+      if (value === null) args.bad = arg;
+      else args.base = value;
+    } else if (args.bad === null) args.bad = arg;
+  }
+  return args;
+};
+
+const git = (args) =>
+  execFileSync('git', args, {
+    encoding: 'utf8',
+    env: withoutGitLocation(),
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+const pathsOf = (raw) => raw.split('\0').filter(Boolean);
+
+/**
+ * The paths a `check-premises` record in this run named. Only that gate: a
+ * reviewer blocker names where a finding is, not what the task rests on.
+ */
+const citedByPremises = (runDir) => {
+  if (!runDir) return [];
+  const { decisions } = readRun({ runDir });
+  return decisions
+    .filter((record) => record.gate === 'check-premises')
+    .flatMap((record) => (Array.isArray(record.blockers) ? record.blockers : []))
+    .map((blocker) => blocker?.file)
+    .filter((file) => typeof file === 'string' && file !== '');
+};
+
+/** The last validation's marker for this item: the latest revalidation event, any point. */
+const lastValidationOf = (runDir, id) => {
+  if (!runDir) return null;
+  const { events } = readRun({ runDir });
+  const last = [...events]
+    .reverse()
+    .find((e) => e.kind === 'revalidation' && String(e.data?.ticket) === String(id));
+  const to = last?.data?.task?.to;
+  return typeof to === 'string' ? to : null;
+};
+
+const invokedDirectly = () => {
+  if (!process.argv[1]) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
+};
+
+const refuse = (message) => {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+};
+
+if (invokedDirectly()) {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.bad !== null) refuse(`unrecognised or unusable argument: ${args.bad}`);
+  // An outcome may answer any point, SELECT included — that one is written by
+  // `queue/index.mjs next`, so it is not in POINTS, which names what THIS
+  // script can revalidate.
+  const known = args.outcome ? ALL_POINTS : POINTS;
+  if (!known.includes(args.point)) {
+    refuse(`unknown point: ${args.point ?? '(none)'}. This script knows ${known.join(', ')}.`);
+  }
+  if (!args.ticket) refuse('--ticket is required: the item whose take-up this branch is.');
+
+  const runDir = process.env.RIG_RUN_DIR || null;
+
+  if (args.outcome) {
+    if (!runDir) refuse('outcome needs RIG_RUN_DIR: an outcome answers a revalidation in a run, and there is none.');
+    if (args.actionChanged !== 'true' && args.actionChanged !== 'false') {
+      refuse(`--action-changed must be true or false, got ${args.actionChanged ?? '(none)'}.`);
+    }
+    const { events } = readRun({ runDir });
+    const target = [...events]
+      .reverse()
+      .find(
+        (e) =>
+          e.kind === 'revalidation' &&
+          String(e.data?.ticket) === String(args.ticket) &&
+          e.data?.point === args.point,
+      );
+    if (!target) {
+      refuse(`no revalidation of ${args.ticket} at ${args.point} in ${runDir} for this outcome to answer.`);
+    }
+    const record = recordEvent({
+      runDir,
+      kind: 'revalidation-outcome',
+      data: {
+        ticket: args.ticket,
+        point: args.point,
+        actionChanged: args.actionChanged === 'true',
+        note: args.note,
+        answers: target.seq,
+      },
+      now: new Date().toISOString(),
+    });
+    process.stdout.write(
+      args.json
+        ? `${JSON.stringify(record, null, 2)}\n`
+        : `revalidation-outcome: ${args.ticket} at ${args.point} answers seq ${target.seq} — actionChanged ${args.actionChanged}\n`,
+    );
+    process.exit(0);
+  }
+
+  const projectRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const configPath = args.config ?? join(projectRoot, '.claude', 'queue.json');
+  const config = loadConfig(configPath);
+  const adapter = await resolveAdapter(config.adapter ?? 'plan-md');
+  const options = optionsWithPlanPath(config.options, configPath);
+
+  if (args.point === 'BEFORE_CLOSE') {
+    const ticket = await adapter.find(args.ticket, options);
+    const takeUp = runDir ? (readState(runDir).takeUps?.[args.ticket] ?? null) : null;
+    // The NEWER of the two, not the last validation first (AR-140): an adapter
+    // re-records the take-up after each write of its own, and a comment posted
+    // after BEFORE_PR would otherwise hold this close on the run's own move.
+    // ISO strings compare as text; a missing side yields to the other.
+    const lastValidation = lastValidationOf(runDir, args.ticket);
+    const baseline =
+      lastValidation !== null && takeUp !== null
+        ? takeUp > lastValidation
+          ? takeUp
+          : lastValidation
+        : (lastValidation ?? takeUp);
+    const task =
+      ticket && baseline !== null
+        ? revalidationOf({ ticket, snapshot: baseline })
+        : { changed: null, task: { from: baseline, to: ticket?.updatedAt ?? null } };
+    // Not found is not "in progress": the tracker no longer offers the item.
+    const actual = ticket ? ticket.state : 'missing';
+    // The dependants' state is RE-READ, not copied off the item: what this close
+    // releases is only what is still waiting, and a dependant somebody closed
+    // ahead of its blocker is reported as such for the write-back.
+    const dependants = Array.isArray(ticket?.blocks) ? ticket.blocks : [];
+    const dependantState = {};
+    for (const dependant of dependants) {
+      dependantState[dependant] = (await adapter.find(dependant, options))?.state ?? 'missing';
+    }
+    const aggregate = beforeCloseRevalidationOf({ ticket: args.ticket, task, state: actual });
+    const result = {
+      ...aggregate,
+      task: { changed: task.changed, from: task.task.from, to: task.task.to },
+      state: { expected: 'in-progress', actual },
+      dependants,
+      dependantState,
+    };
+    if (runDir) {
+      recordEvent({ runDir, kind: 'revalidation', data: result, now: new Date().toISOString() });
+    }
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    } else {
+      const detail = result.source.length > 0 ? ` — ${result.source.join(', ')}` : '';
+      process.stdout.write(`revalidate BEFORE_CLOSE: ${args.ticket} ${result.action}${detail}\n`);
+      if (result.action === 'hold') {
+        process.stdout.write('  re-read the item before closing it; a late change is not published as Done.\n');
+      }
+    }
+    process.exit(result.action === 'hold' ? 2 : 0);
+  }
+
+  let mergeBase;
+  try {
+    mergeBase = git(['merge-base', args.base, 'HEAD']).trim();
+  } catch (error) {
+    refuse(`--base ${args.base} is not a revision this checkout can compare against: ${error.message}`);
+  }
+
+  const tickets = await adapter.listEligible(options);
+  const ticket = tickets.find((candidate) => String(candidate.id) === String(args.ticket)) ?? null;
+
+  const snapshot = runDir ? (readState(runDir).takeUps?.[args.ticket] ?? null) : null;
+  // At SELECT a missing snapshot is a first sight only when no earlier run
+  // took the item up either — `queue/index.mjs` asks `previousTakeUp` (AR-138);
+  // here the question is this run's own take-up, which SELECT wrote — and it
+  // becomes the baseline;
+  // here it is a comparison that cannot be made — the run never recorded a
+  // take-up for this item, so `null`, not the SELECT point's `false`.
+  const unverifiable = { changed: null, task: { from: snapshot, to: ticket?.updatedAt ?? null } };
+  const task = ticket && snapshot !== null ? revalidationOf({ ticket, snapshot }) : unverifiable;
+
+  const branchPaths = pathsOf(git(['diff', '--name-only', '-z', mergeBase, 'HEAD']));
+  const mainPaths = pathsOf(git(['diff', '--name-only', '-z', mergeBase, args.base]));
+  const cited = [...new Set([...branchPaths, ...citedByPremises(runDir)])];
+  const mainChanged = mainPaths.filter((path) => cited.includes(path));
+
+  const aggregate = beforePrRevalidationOf({ ticket: args.ticket, task, mainChanged });
+  const result = {
+    ...aggregate,
+    task: { changed: task.changed, from: task.task.from, to: task.task.to },
+    main: { base: args.base, mergeBase, cited, changed: mainChanged },
+  };
+
+  if (runDir) {
+    recordEvent({ runDir, kind: 'revalidation', data: result, now: new Date().toISOString() });
+  }
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    const detail = result.source.length > 0 ? ` — ${result.source.join(', ')}` : '';
+    process.stdout.write(`revalidate BEFORE_PR: ${args.ticket} ${result.action}${detail}\n`);
+    if (result.action === 'hold') {
+      process.stdout.write('  re-read the item and the default branch before opening or updating the PR.\n');
+    }
+  }
+  process.exit(result.action === 'hold' ? 2 : 0);
+}

package/templates/agent-os/universal/.claude/scripts/revalidation-report.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * The Revalidation Experiment's report — what the evidence log says, over the
+ * run directories of this rig since a date (AR-136).
+ *
+ *   node .claude/scripts/revalidation-report.mjs --since <ISO date> [--runs <dir>] [--json]
+ *
+ * It reads `<runs>/<run-id>/` — `--runs <dir>`, or by default `.claude/runs/`
+ * under the MAIN checkout, resolved through `queue/checkout.mjs` so a report
+ * run from a linked worktree reads the runs the loop actually declared
+ * (revalidation-evidence.test.ts › "reads the main checkout's runs by default,
+ * even from a linked worktree") — through `run-journal.mjs` › readRun, the same
+ * reader every gate uses, with the same refusal: a journal whose sequence is
+ * broken is not read. Such a run is COUNTED under `skipped`, with the reason,
+ * never dropped silently; a report that quietly narrowed its own base would be
+ * the kind of number the journal README says will be believed.
+ *
+ * Per point (SELECT, BEFORE_PR, BEFORE_CLOSE), over `revalidation` events at
+ * or after `since`:
+ *   opportunities — every event; catches — `changed: true`;
+ *   unverifiable — `changed: null`;
+ *   actionChanged — catches whose `revalidation-outcome` says true;
+ *   falseHolds — catches whose outcome says false;
+ *   unresolved — catches with no outcome at all (the run skipped the re-read).
+ * An outcome answers the revalidation whose seq its `answers` names, in the
+ * SAME run — an outcome cannot reach across runs. `noise` counts the sources
+ * behind the false holds, which is where the mechanism's cost is.
+ *
+ * The primary metric is `actionChanged`, not `opportunities` or `catches`: a
+ * hold that changed nothing is noise, and the report says so by name.
+ */
+
+import { readdirSync, realpathSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mainCheckoutRoot } from './queue/checkout.mjs';
+import { readRun } from './run-journal.mjs';
+import { POINTS } from './lib/revalidation-points.mjs';
+
+export { POINTS };
+
+const emptyCounts = () => ({
+  opportunities: 0,
+  catches: 0,
+  unverifiable: 0,
+  actionChanged: 0,
+  falseHolds: 0,
+  unresolved: 0,
+});
+
+/** The report over already-read runs — pure, so the counting is testable alone. */
+export const reportOf = ({ runs, since }) => {
+  const sinceMs = Date.parse(since);
+  const points = Object.fromEntries(POINTS.map((point) => [point, emptyCounts()]));
+  const noise = {};
+  const read = [];
+  const skipped = [];
+  for (const { run, events, error } of runs) {
+    if (error) {
+      skipped.push({ run, why: error });
+      continue;
+    }
+    read.push(run);
+    const outcomes = new Map();
+    for (const event of events) {
+      if (event.kind === 'revalidation-outcome' && Number.isInteger(event.data?.answers)) {
+        outcomes.set(event.data.answers, event.data);
+      }
+    }
+    for (const event of events) {
+      if (event.kind !== 'revalidation') continue;
+      // Written as "inside the window", so an `at` that does not parse falls
+      // OUT — the NaN comparison would otherwise count it in.
+      if (!(Date.parse(event.at) >= sinceMs)) continue;
+      const bucket = points[event.data?.point];
+      if (!bucket) continue;
+      bucket.opportunities += 1;
+      if (event.data.changed === null) bucket.unverifiable += 1;
+      if (event.data.changed !== true) continue;
+      bucket.catches += 1;
+      const outcome = outcomes.get(event.seq);
+      if (!outcome) bucket.unresolved += 1;
+      else if (outcome.actionChanged === true) bucket.actionChanged += 1;
+      else {
+        bucket.falseHolds += 1;
+        for (const source of Array.isArray(event.data.source) ? event.data.source : []) {
+          noise[source] = (noise[source] ?? 0) + 1;
+        }
+      }
+    }
+  }
+  const totals = emptyCounts();
+  for (const counts of Object.values(points)) {
+    for (const key of Object.keys(totals)) totals[key] += counts[key];
+  }
+  return { since, points, noise, totals, runs: { read: read.length, skipped } };
+};
+
+/** Every run directory under `runsDir`, read or refused — never both, never neither. */
+export const readRuns = (runsDir) => {
+  let names;
+  try {
+    names = readdirSync(runsDir).filter((name) => statSync(join(runsDir, name)).isDirectory());
+  } catch (error) {
+    throw new Error(`cannot list runs in ${runsDir}: ${error.message}`, { cause: error });
+  }
+  return names.sort().map((run) => {
+    try {
+      const { events } = readRun({ runDir: join(runsDir, run) });
+      return { run, events };
+    } catch (error) {
+      return { run, error: String(error?.message ?? error) };
+    }
+  });
+};
+
+export const render = (report) => {
+  const line = (name, c) =>
+    `${name}: ${c.opportunities} opportunities, ${c.catches} catches, ${c.actionChanged} actionChanged, ` +
+    `${c.falseHolds} falseHolds, ${c.unresolved} unresolved, ${c.unverifiable} unverifiable`;
+  const lines = [`revalidation since ${report.since}`];
+  for (const point of POINTS) lines.push(line(point, report.points[point]));
+  lines.push(line('totals', report.totals));
+  const noise = Object.entries(report.noise);
+  lines.push(
+    noise.length === 0
+      ? 'noise: none'
+      : `noise: ${noise.map(([source, count]) => `${source} ×${count}`).join(', ')}`,
+  );
+  lines.push(`runs: ${report.runs.read} read, ${report.runs.skipped.length} skipped`);
+  for (const { run, why } of report.runs.skipped) lines.push(`  skipped ${run} — ${why}`);
+  return `${lines.join('\n')}\n`;
+};
+
+const parseArgs = (argv) => {
+  const args = { since: null, runs: null, json: false, bad: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') args.json = true;
+    else if (arg === '--since') args.since = argv[++i] ?? null;
+    else if (arg === '--runs') args.runs = argv[++i] ?? null;
+    else if (args.bad === null) args.bad = arg;
+  }
+  return args;
+};
+
+const invokedDirectly = () => {
+  if (!process.argv[1]) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
+};
+
+if (invokedDirectly()) {
+  const args = parseArgs(process.argv.slice(2));
+  const refuse = (message) => {
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+  };
+  if (args.bad !== null) refuse(`unrecognised argument: ${args.bad}`);
+  if (!args.since || Number.isNaN(Date.parse(args.since))) {
+    refuse(`--since needs an ISO date (got ${args.since ?? '(none)'}); a report with no window reports nothing honest.`);
+  }
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const runsDir =
+    args.runs ?? join(mainCheckoutRoot(join(scriptsDir, '..', '..')), '.claude', 'runs');
+  let runs;
+  try {
+    runs = readRuns(runsDir);
+  } catch (error) {
+    refuse(error.message);
+  }
+  const report = reportOf({ runs, since: new Date(args.since).toISOString() });
+  process.stdout.write(args.json ? `${JSON.stringify(report, null, 2)}\n` : render(report));
+}