opencode-longrun-harness 1.2.22

package/harness/test/v128-compaction.test.mjs

@@ -0,0 +1,156 @@
+import { reviewProjectFixture } from "./helper.mjs";
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import * as C from '../src/controller.js';
+import { F } from './helper.mjs';
+process.env.LONGRUN_CONTROLLER_FILE = path.resolve(import.meta.dirname, '../src/controller.js');
+async function setup({ delay = 0 } = {}) {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'lr128-'));
+  const dir = path.join(base, 'project'); fs.mkdirSync(dir); fs.writeFileSync(path.join(dir, 'source.txt'), 'real fixture');
+  process.env.LONGRUN_STATE_DIR = path.join(base, 'state');
+  const hooks = await F('../plugin/longrun.js', { client: null });
+  const first = { sessionID: 'old-host', directory: dir, worktree: dir }, second = { ...first, sessionID: 'new-host' };
+  const run = JSON.parse(await hooks.tool.longrun.execute({ action: 'start', request: 'Compaction control fixture', criteria: [{ id: 'c', evidenceClass: 'STATIC', checks: ['check'] }], checkCatalogue: { check: { command: [process.execPath, '-e', `setTimeout(()=>require('node:assert/strict').equal(1+1,2),${delay})`], kind: 'cmd' } } }, first));
+  const store = new C.Store(process.env.LONGRUN_STATE_DIR), key = C.stateKey(C.projectIdentity(dir), run.runId);
+  const call = (action, ctx = second) => hooks.tool.longrun.execute({ action, runId: run.runId }, ctx);
+  await call('resume');
+  return { hooks, first, second, store, key, call, runId: run.runId };
+}
+
+test('compaction cannot auto-continue an old session after another session pauses or cancels the same run', async () => {
+  for (const action of ['pause', 'cancel']) {
+    const s = await setup(); await s.call(action);
+    const before = fs.readFileSync(s.store._file(s.key, 'run.json'));
+    const output = { enabled: true };
+    await s.hooks['experimental.compaction.autocontinue']({ sessionID: s.first.sessionID }, output);
+    assert.equal(output.enabled, false, `${action} must use canonical run, not stale session flags`);
+    assert.deepEqual(fs.readFileSync(s.store._file(s.key, 'run.json')), before);
+  }
+});
+
+test('compaction auto-continuation refuses missing runs and exhausted execution budgets without resets', async () => {
+  for (const situation of ['missing', 'deadline', 'attempts', 'legacy']) {
+    const s = await setup();
+    if (situation === 'missing') fs.rmSync(s.store._file(s.key, 'run.json'));
+    else s.store.mutate(s.key, r => { if (situation === 'legacy') delete r.compactionSessionID; else if (situation === 'deadline') r.createdAt -= 86400000; else r.execution.commandAttempts = r.budget.toolActionCap; return { ok: true }; });
+    const output = { enabled: true };
+    await s.hooks['experimental.compaction.autocontinue']({ sessionID: s.second.sessionID }, output);
+    assert.equal(output.enabled, false, situation);
+  }
+});
+
+test('a short concurrent writer cannot silently discard the real compacted state transition', async () => {
+  const s = await setup();
+  s.store.tryLock(s.key, 'checkpoint-writer');
+  const release = setTimeout(() => s.store.releaseLock(s.key), 60);
+  try {
+    await s.hooks.event({ event: { type: 'session.compacted', properties: { sessionID: s.second.sessionID } } });
+    await new Promise(resolve => setTimeout(resolve, 80));
+    assert.equal(s.store.readJSON(s.key, 'run.json').status, 'RECOVERY_REQUIRED');
+  } finally { clearTimeout(release); s.store.releaseLock(s.key); }
+});
+
+test('an older session cannot interrupt or continue the newly rebound active session', async () => {
+  const s = await setup(), before = s.store.readJSON(s.key, 'run.json');
+  await s.hooks.event({ event: { type: 'session.compacted', properties: { sessionID: s.first.sessionID } } });
+  const output = { enabled: true };
+  await s.hooks['experimental.compaction.autocontinue']({ sessionID: s.first.sessionID }, output);
+  assert.equal(output.enabled, false); assert.deepEqual(s.store.readJSON(s.key, 'run.json'), before);
+});
+
+test('current-session compaction preserves context and requires recovery once, without enabling the scheduler', async () => {
+  const s = await setup();
+  const ctx = { nextAction: 'inspect the preserved independent oracle', decisions: ['preserve acceptance'] };
+  await s.hooks.tool.longrun.execute({ action: 'checkpoint', runId: s.runId, progress: ctx }, s.second);
+  const before = s.store.readJSON(s.key, 'run.json');
+  const compact = { context: ['host context'] };
+  await s.hooks['experimental.session.compacting']({ sessionID: s.second.sessionID }, compact);
+  assert.equal(compact.context[0], 'host context'); assert.match(compact.context[1], /inspect the preserved independent oracle/);
+  await s.hooks.event({ event: { type: 'session.compacted', properties: { sessionID: s.second.sessionID } } });
+  const enabled = { enabled: true };
+  await s.hooks['experimental.compaction.autocontinue']({ sessionID: s.second.sessionID }, enabled);
+  assert.equal(enabled.enabled, true); // Continue the active host turn, not automatic Longrun scheduling.
+  const after = s.store.readJSON(s.key, 'run.json');
+  assert.equal(after.status, 'RECOVERY_REQUIRED'); assert.equal(after.controlGeneration, before.controlGeneration + 1);
+  assert.equal(after.autoEnabled, false);
+  for (const field of ['contract', 'contractHash', 'budget', 'receipts', 'agentProgress']) assert.deepEqual(after[field], before[field]);
+  const veto = { enabled: false };
+  await s.hooks['experimental.compaction.autocontinue']({ sessionID: s.second.sessionID }, veto);
+  assert.equal(veto.enabled, false); assert.equal(s.store.readJSON(s.key, 'run.json').controlGeneration, after.controlGeneration);
+});
+
+test('persistent writer contention vetoes compaction continuation and permits later recovery without state fabrication', async () => {
+  const s = await setup(), before = fs.readFileSync(s.store._file(s.key, 'run.json'));
+  s.store.tryLock(s.key, 'long-writer');
+  try {
+    const output = { enabled: true };
+    await s.hooks['experimental.compaction.autocontinue']({ sessionID: s.second.sessionID }, output);
+    assert.equal(output.enabled, false); assert.deepEqual(fs.readFileSync(s.store._file(s.key, 'run.json')), before);
+  } finally { s.store.releaseLock(s.key); }
+  await s.hooks.event({ event: { type: 'session.compacted', properties: { sessionID: s.second.sessionID } } });
+  assert.equal(s.store.readJSON(s.key, 'run.json').status, 'RECOVERY_REQUIRED');
+  assert.equal(s.store.readJSON(s.key, 'run.json').receipts.length, 0);
+});
+
+test('completed runs stay terminal and untracked sessions remain outside Longrun control', async () => {
+  const s = await setup();
+  const checked = JSON.parse(await s.hooks.tool.longrun_verify.execute({ runId: s.runId, checkId: 'check', evidenceClass: 'STATIC' }, s.second));
+  assert.equal(checked.status, 'PASS'); reviewProjectFixture(s.second.directory, s.runId); assert.equal(JSON.parse(await s.call('complete')).complete, true);
+  const before = s.store.readJSON(s.key, 'run.json');
+  const output = { enabled: true };
+  await s.hooks['experimental.compaction.autocontinue']({ sessionID: s.second.sessionID }, output);
+  assert.equal(output.enabled, false); assert.deepEqual(s.store.readJSON(s.key, 'run.json'), before);
+  const unrelated = { enabled: true };
+  await s.hooks['experimental.compaction.autocontinue']({ sessionID: 'untracked' }, unrelated);
+  assert.equal(unrelated.enabled, true); assert.deepEqual(s.store.readJSON(s.key, 'run.json'), before);
+});
+
+test('compaction while an owned check is running cancels it honestly and refuses another host turn', async () => {
+  const s = await setup({ delay: 5000 });
+  const pending = s.hooks.tool.longrun_verify.execute({ runId: s.runId, checkId: 'check', evidenceClass: 'STATIC' }, s.second);
+  for (let i = 0; i < 100 && !s.store.readJSON(s.key, 'run.json').execution.inFlight?.childPid; i++) await new Promise(r => setTimeout(r, 10));
+  assert.ok(s.store.readJSON(s.key, 'run.json').execution.inFlight?.childPid);
+  const output = { enabled: true };
+  await s.hooks['experimental.compaction.autocontinue']({ sessionID: s.second.sessionID }, output);
+  assert.equal(output.enabled, false);
+  const result = JSON.parse(await pending); assert.equal(result.status, 'ERROR');
+  const run = s.store.readJSON(s.key, 'run.json');
+  assert.equal(run.status, 'RECOVERY_REQUIRED'); assert.equal(run.receipts[0].terminationReason, 'recovery_required');
+  assert.equal(run.execution.inFlight, null); assert.equal(run.receipts.length, 1);
+});
+
+test('a corrupt recorded binding cannot masquerade as an untracked session', async () => {
+  const s = await setup();
+  fs.writeFileSync(path.join(process.env.LONGRUN_STATE_DIR, 'runs.json'), JSON.stringify({ [s.second.sessionID]: { runId: s.runId } }));
+  const output = { enabled: true };
+  await s.hooks['experimental.compaction.autocontinue']({ sessionID: s.second.sessionID }, output);
+  assert.equal(output.enabled, false); assert.equal(s.store.readJSON(s.key, 'run.json').receipts.length, 0);
+});
+
+test('post-compaction execution and edits require native recovery while reads stay available', async () => {
+  const s = await setup();
+  await s.hooks.event({ event: { type: 'session.compacted', properties: { sessionID: s.second.sessionID } } });
+  const guard = s.hooks['tool.execute.before'];
+  assert.equal(typeof guard, 'function', 'host execution requires a recovery guard, not prose alone');
+  for (const tool of ['bash', 'edit', 'write', 'apply_patch', 'task', 'batch']) {
+    await assert.rejects(() => guard({ tool, sessionID: s.second.sessionID }, { args: {} }), /LONGRUN_RECOVERY_REQUIRED.*resume-context/);
+  }
+  for (const tool of ['read', 'glob', 'grep', 'list', 'skill', 'longrun', 'longrun_verify']) {
+    await guard({ tool, sessionID: s.second.sessionID }, { args: {} });
+  }
+  const resumed = JSON.parse(await s.call('resume')); assert.equal(resumed.resumed, true);
+  await guard({ tool: 'edit', sessionID: s.second.sessionID }, { args: {} });
+  await guard({ tool: 'bash', sessionID: 'untracked' }, { args: {} });
+});
+
+test('compaction context distinguishes a pre-event snapshot from the mandatory post-event recovery', async () => {
+  const s = await setup(); const output = { context: ['host prompt'] };
+  await s.hooks['experimental.session.compacting']({ sessionID: s.second.sessionID }, output);
+  assert.equal(output.context[0], 'host prompt');
+  assert.match(output.context[1], /PRE-COMPACTION SNAPSHOT/);
+  assert.match(output.context[1], /resume-context/); assert.match(output.context[1], new RegExp(s.runId));
+  assert.match(output.context[1], /do not infer.*IMPLEMENTING/i);
+});

package/harness/test/v129-routing.test.mjs

@@ -0,0 +1,165 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { F } from './helper.mjs';
+import * as C from '../src/controller.js';
+process.env.LONGRUN_CONTROLLER_FILE = path.resolve(import.meta.dirname, '../src/controller.js');
+const request = { action: 'start', request: 'Routing integrity fixture', criteria: [{ id: 'c', checks: ['check'], evidenceClass: 'STATIC' }], checkCatalogue: { check: { command: [process.execPath, '-e', 'require("node:assert/strict").equal(2+2,4)'], kind: 'cmd' } } };
+function base() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lr129-'));
+  for (const d of ['A', 'B', 'state']) fs.mkdirSync(path.join(root, d));
+  for (const d of ['A', 'B']) fs.writeFileSync(path.join(root, d, 'source.txt'), d);
+  return root;
+}
+async function setup() {
+  const root = base(), state = path.join(root, 'state'), dir = path.join(root, 'A');
+  process.env.LONGRUN_STATE_DIR = state;
+  const hooks = await F('../plugin/longrun.js', { client: null });
+  const ctx = { sessionID: 'A', directory: dir, worktree: dir };
+  const call = async (args, context = ctx) => JSON.parse(await hooks.tool.longrun.execute(args, context));
+  return { root, state, dir, hooks, ctx, call };
+}
+async function race(root, mode) {
+  const children = [];
+  function start(label) {
+    let output = '', error = '';
+    const child = spawn(process.execPath, [path.join(import.meta.dirname, 'fixtures/routing-worker.mjs'), root, label, mode], { env: { ...process.env, LONGRUN_TEST: '1' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    children.push(child);
+    const done = new Promise((resolve, reject) => {
+      child.on('error', reject);
+      child.on('close', code => code === 0 ? resolve(output.trim().split('\n').map(JSON.parse).find(x => x.result).result) : reject(new Error(error || `child exit ${code}`)));
+    });
+    const critical = new Promise(resolve => child.stdout.on('data', d => { output += d; if (output.includes('"critical":true')) resolve(); }));
+    child.stderr.on('data', d => error += d);
+    return { done, critical };
+  }
+  let timeout;
+  try {
+    return await Promise.race([(async () => {
+      const a = start('A');
+      await Promise.race([a.critical, a.done.then(() => { throw new Error('race boundary not reached'); })]);
+      const b = start('B');
+      return await Promise.all([a.done, b.done]);
+    })(), new Promise((_, reject) => { timeout = setTimeout(() => reject(new Error('routing race timed out')), 15000); })]);
+  } finally {
+    clearTimeout(timeout);
+    for (const child of children) if (child.exitCode === null) child.kill('SIGTERM');
+  }
+}
+function canonicalRuns(root) {
+  const dir = path.join(root, 'state/state');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).flatMap(k => { try { return [JSON.parse(fs.readFileSync(path.join(dir, k, 'run.json')))]; } catch { return []; } });
+}
+
+test('concurrent hosts starting different projects preserve both session bindings', async () => {
+  const root = base();
+  try {
+    const results = await race(root, 'different-projects');
+    assert.ok(results.every(r => r.runId), JSON.stringify(results));
+    const bindings = JSON.parse(fs.readFileSync(path.join(root, 'state/runs.json')));
+    assert.deepEqual(Object.keys(bindings).sort(), ['A', 'B']);
+    assert.equal(canonicalRuns(root).length, 2);
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+});
+
+test('concurrent start admission cannot create two active runs for one project', async () => {
+  const root = base();
+  try {
+    const results = await race(root, 'same-project');
+    assert.equal(results.filter(r => !r.error && r.runId).length, 1, JSON.stringify(results));
+    assert.equal(results.filter(r => r.error === 'EXISTING_RUN').length, 1);
+    assert.equal(canonicalRuns(root).length, 1);
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+});
+
+test('corrupt routing indices fail explicitly without being replaced by an empty map', async () => {
+  for (const filename of ['runs.json', 'projects.json']) {
+    const s = await setup(), file = path.join(s.state, filename);
+    try {
+      fs.writeFileSync(file, '{ preserved corrupt bytes');
+      const result = await s.call(request);
+      assert.equal(result.error, 'ROUTING_STORE_ERROR');
+      assert.equal(fs.readFileSync(file, 'utf8'), '{ preserved corrupt bytes');
+      assert.equal(canonicalRuns(s.root).length, 0);
+      await assert.rejects(s.hooks['tool.execute.before']({ sessionID: 'A', tool: 'bash' }), /ROUTING_STORE_ERROR/);
+    } finally { fs.rmSync(s.root, { recursive: true, force: true }); }
+  }
+});
+
+test('canonical run survives missing routing indices and an authorized resume repairs the binding', async () => {
+  const s = await setup();
+  try {
+    const started = await s.call(request), runId = started.runId;
+    const before = canonicalRuns(s.root)[0];
+    fs.unlinkSync(path.join(s.state, 'runs.json')); fs.unlinkSync(path.join(s.state, 'projects.json'));
+    const fresh = { ...s.ctx, sessionID: 'fresh' };
+    const found = await s.call({ action: 'status', runId }, fresh);
+    assert.equal(found.state, 'IMPLEMENTING'); assert.equal(found.runId, runId);
+    assert.equal((await s.call(request, fresh)).error, 'EXISTING_RUN');
+    assert.equal((await s.call({ action: 'resume', runId }, fresh)).resumed, true);
+    const after = canonicalRuns(s.root)[0];
+    for (const key of ['runId', 'contract', 'contractHash', 'budget', 'receipts', 'createdAt']) assert.deepEqual(after[key], before[key]);
+    assert.equal(JSON.parse(fs.readFileSync(path.join(s.state, 'runs.json'))).fresh.runId, runId);
+    assert.equal(canonicalRuns(s.root).length, 1);
+  } finally { fs.rmSync(s.root, { recursive: true, force: true }); }
+});
+
+test('a session binding cannot authorize a lifecycle mutation from a foreign project', async () => {
+  const s = await setup();
+  try {
+    const started = await s.call(request), before = canonicalRuns(s.root)[0];
+    const foreign = { ...s.ctx, directory: path.join(s.root, 'B'), worktree: path.join(s.root, 'B') };
+    assert.equal((await s.call({ action: 'cancel', runId: started.runId }, foreign)).state, 'NO_RUN');
+    assert.deepEqual(canonicalRuns(s.root)[0], before);
+  } finally { fs.rmSync(s.root, { recursive: true, force: true }); }
+});
+
+test('an interrupted index write reports failure and does not lose the canonical run on retry', async () => {
+  const s = await setup(), original = fs.renameSync;
+  try {
+    fs.renameSync = function(from, to, ...rest) {
+      if (String(to) === path.join(s.state, 'projects.json')) throw Object.assign(new Error('isolated index failure'), { code: 'EACCES' });
+      return original.call(this, from, to, ...rest);
+    };
+    const first = await s.call(request);
+    assert.equal(first.error, 'ROUTING_STORE_ERROR');
+    fs.renameSync = original;
+    const runId = canonicalRuns(s.root)[0].runId;
+    const fresh = { ...s.ctx, sessionID: 'fresh' };
+    assert.equal((await s.call(request, fresh)).error, 'EXISTING_RUN');
+    assert.equal((await s.call({ action: 'resume', runId }, fresh)).resumed, true);
+    assert.equal(canonicalRuns(s.root).length, 1);
+  } finally { fs.renameSync = original; fs.rmSync(s.root, { recursive: true, force: true }); }
+});
+
+test('a corrupt canonical record is not treated as absence and replaced by a new run', async () => {
+  const s = await setup();
+  try {
+    const started = await s.call(request);
+    const file = path.join(s.state, 'state', C.stateKey(C.projectIdentity(s.dir), started.runId), 'run.json');
+    fs.writeFileSync(file, '{ preserved canonical corruption');
+    const result = await s.call(request, { ...s.ctx, sessionID: 'fresh' });
+    assert.equal(result.error, 'ROUTING_STORE_ERROR');
+    assert.equal(fs.readFileSync(file, 'utf8'), '{ preserved canonical corruption');
+    assert.equal(fs.readdirSync(path.join(s.state, 'state')).length, 1);
+  } finally { fs.rmSync(s.root, { recursive: true, force: true }); }
+});
+
+test('an existing routing lock is preserved on bounded contention and an exact retry succeeds after release', async () => {
+  const s = await setup();
+  const lock = path.join(s.state, 'ROUTING.lock'), bytes = JSON.stringify({ pid: process.pid, token: 'other-owner' });
+  try {
+    fs.writeFileSync(lock, bytes);
+    const result = await s.call(request);
+    assert.equal(result.error, 'ROUTING_BUSY');
+    assert.equal(fs.readFileSync(lock, 'utf8'), bytes);
+    assert.equal(canonicalRuns(s.root).length, 0);
+    fs.unlinkSync(lock); // fixture owner releases its own lock, never a guessed production PID
+    assert.ok((await s.call(request)).runId);
+    assert.equal(fs.existsSync(lock), false);
+  } finally { fs.rmSync(s.root, { recursive: true, force: true }); }
+});

package/harness/tools/audit-receipts.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// Independent receipt auditor for a tracked run. The supervisor must not trust "PASS" at face value,
+// but must also not cry wolf: this run's receipts span two schema eras, so the auditor is explicitly
+// schema-aware. Fields that simply did not exist in older receipts are reported as era notes, never
+// as fabrication findings.
+//
+// Checks that can prove a receipt was produced by a real declared-check execution:
+//   - command matches the declared check command in checkCatalogue (no substituted command)
+//   - contractHash matches the run contract
+//   - PASS implies exitCode 0, no termination reason and no execution error
+//   - timestamps are ordered and inside the run's lifetime
+//   - sourceFingerprint present (freshness is judged against the current fingerprint separately)
+// Checks that only apply when the receipt schema has the field:
+//   - receiptId uniqueness, executionToken presence
+//
+// usage: node audit-receipts.mjs [--state-dir DIR] [--run RUN_ID] [--baseline N] [--json]
+// exit: 0 clean/review, 1 suspect (a HIGH finding)
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+const argv = process.argv.slice(2);
+const flag = (n, d) => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : d; };
+const STATE_DIR = flag("--state-dir", path.join(process.env.HOME, ".local/state/opencode-longrun/v1"));
+const RUN_ID = flag("--run", "");
+if (!RUN_ID) { console.error("usage: audit-receipts.mjs --run RUN_ID [--state-dir DIR] [--baseline N] [--json]"); process.exit(2); }
+const BASELINE = Number(flag("--baseline", 0));
+
+function findRun(stateDir, runId) {
+  const root = path.join(stateDir, "state");
+  for (const name of fs.readdirSync(root)) {
+    if (!/^[a-f0-9]{32}$/.test(name)) continue;
+    const file = path.join(root, name, "run.json");
+    try { const run = JSON.parse(fs.readFileSync(file, "utf8")); if (run.runId === runId) return { run, file }; } catch {}
+  }
+  return null;
+}
+
+const found = findRun(STATE_DIR, RUN_ID);
+if (!found) { console.error("run not found"); process.exit(2); }
+const { run, file } = found;
+const catalogue = run.checkCatalogue || {};
+const receipts = run.receipts || [];
+const fresh = receipts.slice(BASELINE);
+
+const findings = [];
+const add = (severity, checkId, receiptId, message, extra = {}) =>
+  findings.push({ severity, checkId: checkId ?? null, receiptId: receiptId ?? null, message, ...extra });
+
+// ---- schema era detection (once) -----------------------------------------------------------------
+const hasIds = receipts.some(r => r && (r.receiptId || r.id));
+const hasTokens = receipts.some(r => r && r.executionToken);
+const eras = [];
+if (!hasIds) eras.push("no receiptId in any receipt: legacy schema, identity is positional");
+if (!hasTokens) eras.push("no executionToken in any receipt: legacy schema, process provenance is not recorded");
+if (eras.length) add("INFO", null, null, `legacy receipt schema (${eras.length} era notes)`, { eras });
+
+// ---- structural integrity -----------------------------------------------------------------------
+const seen = new Map();
+for (const [i, r] of receipts.entries()) {
+  if (!r || typeof r !== "object") { add("HIGH", null, null, `receipt #${i} is not an object`); continue; }
+  const id = r.receiptId || r.id || null;
+  if (id) { if (seen.has(id)) add("HIGH", r.checkId, id, `duplicate receiptId (also receipt #${seen.get(id)})`); else seen.set(id, i); }
+  if (Number(r.finishedAt) < Number(r.startedAt)) add("HIGH", r.checkId, id, `finishedAt precedes startedAt (#${i})`);
+  if (r.startedAt && run.createdAt && Number(r.startedAt) < Number(run.createdAt))
+    add("HIGH", r.checkId, id, `receipt #${i} predates the run's creation (backdated)`);
+}
+
+// ---- per-receipt authenticity -------------------------------------------------------------------
+for (const [i, r] of fresh.entries()) {
+  const idx = BASELINE + i;
+  const id = r.receiptId || r.id || `#${idx}`;
+  const declared = catalogue[r.checkId];
+  if (!declared) { add("HIGH", r.checkId, id, "receipt for a check absent from the declared catalogue"); continue; }
+  const declaredCmd = (Array.isArray(declared.command) ? declared.command.join(" ") : String(declared.command)).trim();
+  const receiptCmd = (Array.isArray(r.argv) ? r.argv.join(" ") : String(r.command ?? "")).trim();
+  if (receiptCmd && declaredCmd && receiptCmd !== declaredCmd)
+    add("HIGH", r.checkId, id, "receipt command differs from the declared check command (substituted command?)", { declaredCmd, receiptCmd });
+  if (r.contractHash && run.contractHash && r.contractHash !== run.contractHash)
+    add("HIGH", r.checkId, id, "receipt contractHash differs from the run contract");
+  if (r.status === "PASS" && Number(r.exitCode) !== 0) add("HIGH", r.checkId, id, "PASS with a non-zero exit code", { exitCode: r.exitCode });
+  if (r.status === "PASS" && r.terminationReason) add("HIGH", r.checkId, id, "PASS with a termination reason", { terminationReason: r.terminationReason });
+  if (r.status === "PASS" && r.executionError) add("HIGH", r.checkId, id, "PASS with an execution error", { executionError: r.executionError });
+  if (!r.sourceFingerprint) add("MEDIUM", r.checkId, id, "no sourceFingerprint recorded");
+  if (r.status === "NOT_RUN" && Number(r.exitCode) === 0)
+    add("LOW", r.checkId, id, "NOT_RUN with exit 0: the summary was not recognised, so this does NOT satisfy the criterion");
+  if (r.status === "FAIL") add("LOW", r.checkId, id, "historical FAIL receipt retained in the canonical history", { exitCode: r.exitCode });
+}
+
+// ---- freshness ----------------------------------------------------------------------------------
+const fps = new Map();
+for (const r of fresh) fps.set(r.sourceFingerprint, (fps.get(r.sourceFingerprint) || 0) + 1);
+
+const summary = {
+  runId: RUN_ID, runFile: file,
+  runHash: createHash("sha256").update(fs.readFileSync(file)).digest("hex"),
+  status: run.status, totalReceipts: receipts.length, auditedFrom: BASELINE, auditedReceipts: fresh.length,
+  schemaEra: { receiptIds: hasIds, executionTokens: hasTokens },
+  distinctFingerprints: [...fps.entries()].map(([fingerprint, count]) => ({ fingerprint, count })),
+  counts: { PASS: fresh.filter(r => r.status === "PASS").length, FAIL: fresh.filter(r => r.status === "FAIL").length, NOT_RUN: fresh.filter(r => r.status === "NOT_RUN").length },
+  findings,
+  high: findings.filter(f => f.severity === "HIGH").length,
+  medium: findings.filter(f => f.severity === "MEDIUM").length,
+  low: findings.filter(f => f.severity === "LOW").length,
+  verdict: findings.some(f => f.severity === "HIGH") ? "SUSPECT" : findings.some(f => f.severity === "MEDIUM") ? "REVIEW" : "CLEAN",
+};
+
+if (argv.includes("--json")) process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+else {
+  console.log(`run ${summary.runId}  status ${summary.status}  receipts ${summary.totalReceipts} (audited from ${BASELINE})`);
+  console.log(`schema era: receiptIds=${hasIds} executionTokens=${hasTokens}`);
+  console.log(`audited: PASS ${summary.counts.PASS}  FAIL ${summary.counts.FAIL}  NOT_RUN ${summary.counts.NOT_RUN}`);
+  console.log(`verdict: ${summary.verdict}  high=${summary.high} medium=${summary.medium} low=${summary.low}`);
+  console.log("fingerprints in audited receipts:");
+  for (const d of summary.distinctFingerprints) console.log(`  ${String(d.fingerprint).slice(0, 16)}… ×${d.count}`);
+  for (const f of findings) {
+    if (f.severity === "INFO") { console.log(`  [INFO] ${f.message}`); for (const e of f.eras || []) console.log(`         - ${e}`); continue; }
+    console.log(`  [${f.severity}] ${f.checkId || "-"} ${f.receiptId || "-"}: ${f.message}`);
+  }
+}
+process.exit(summary.verdict === "SUSPECT" ? 1 : 0);