@rigour-labs/core 6.6.6 → 6.7.0

package/dist/review/reviewer/consensus.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How a panel agrees, as pure functions: when two judges' items are the same finding (similarity),
+ * the minimum-cost one-to-one assignment (the Hungarian algorithm), the grouping of every judge's
+ * items into findings, and the majority rule that decides a finding from every judge's call.
+ * Deterministic: inputs sorted, ties broken on file, line and id. panel.ts runs the judges around it.
+ */
+import type { OpenItem } from './verdict.js';
+export type Call = 'raised' | 'confirm' | 'refute' | 'unsure' | 'not asked';
+export type PanelStatus = 'confirmed' | 'disputed' | 'dropped';
+/** Similarity at or above which two items are the same finding. */
+export declare const MATCH_THRESHOLD = 0.5;
+export declare const order: (a: OpenItem, b: OpenItem) => number;
+/** Shared words over all words (Jaccard) of two items' issue and consequence. */
+export declare function textSimilarity(a: OpenItem, b: OpenItem): number;
+/** 0 for different files; otherwise wording, line distance and class, weighted. A far-apart pair needs close wording. */
+export declare function similarity(a: OpenItem, b: OpenItem): number;
+/** One finding as the panel sees it: the item each judge who raised it wrote, in judge order. */
+export interface Cluster {
+    members: Array<{
+        judge: string;
+        item: OpenItem;
+    }>;
+}
+/**
+ * The judges' items grouped into findings. Judges are taken in order; each judge's items are
+ * assigned one-to-one to the findings so far by the Hungarian algorithm (a finding scores as its
+ * closest member), never first-fit. An item left over that a finding already holding this judge
+ * resembles joins it (one judge split what another named once); any other leftover is a new finding.
+ */
+export declare function clusterItems(judges: string[], items: OpenItem[][]): Cluster[];
+/**
+ * Status from every judge's call. Confirmed: a strict majority raised it or confirmed it with
+ * evidence. Dropped: refutations with evidence at least match the support and no judge is unsure.
+ * Disputed otherwise. With two judges: both raised it, or the other confirmed it; refuted, dropped.
+ */
+export declare function statusOf(calls: Record<string, Call>, judges: number): PanelStatus;

package/dist/review/reviewer/consensus.js

@@ -0,0 +1,144 @@
+/** Similarity at or above which two items are the same finding. */
+export const MATCH_THRESHOLD = 0.5;
+/** Below this share of words, two items are the same finding only on the same line and in the same class. */
+const MIN_SHARED_WORDS = 0.15;
+const LINE_WINDOW = 5;
+const STOP = new Set(['the', 'and', 'for', 'that', 'this', 'with', 'from', 'when', 'into', 'are', 'not', 'but', 'its', 'has', 'have', 'every', 'each', 'one', 'can']);
+export const order = (a, b) => (a.file ?? '').localeCompare(b.file ?? '') || (a.line ?? 0) - (b.line ?? 0) || a.id.localeCompare(b.id);
+/** Shared words over all words (Jaccard) of two items' issue and consequence. */
+export function textSimilarity(a, b) {
+    const wa = words(a);
+    const wb = words(b);
+    const shared = [...wa].filter(w => wb.has(w)).length;
+    return wa.size + wb.size - shared ? shared / (wa.size + wb.size - shared) : 0;
+}
+function words(item) {
+    const text = `${item.issue} ${item.consequence ?? ''}`.toLowerCase();
+    return new Set((text.match(/[a-z_][a-z0-9_]{2,}/g) ?? []).filter(w => !STOP.has(w)));
+}
+/** 0 for different files; otherwise wording, line distance and class, weighted. A far-apart pair needs close wording. */
+export function similarity(a, b) {
+    if (!a.file || a.file !== b.file)
+        return 0;
+    const text = textSimilarity(a, b);
+    const distance = a.line !== undefined && b.line !== undefined ? Math.abs(a.line - b.line) : undefined;
+    const line = distance === undefined ? 0.5 : distance <= LINE_WINDOW ? 1 - distance / (LINE_WINDOW + 1) : 0;
+    if (line === 0 && text < 0.5)
+        return 0;
+    if (text < MIN_SHARED_WORDS && !(distance === 0 && a.class === b.class))
+        return 0;
+    return 0.4 * text + 0.35 * line + 0.25 * (a.class === b.class ? 1 : 0);
+}
+/**
+ * Minimum-cost assignment of rows to columns (Hungarian algorithm with potentials, O(n²m)).
+ * `cost` is rows × columns with rows ≤ columns; returns the column of each row.
+ */
+function assign(cost) {
+    const n = cost.length;
+    const m = n ? cost[0].length : 0;
+    const u = new Array(n + 1).fill(0);
+    const v = new Array(m + 1).fill(0);
+    const p = new Array(m + 1).fill(0);
+    const way = new Array(m + 1).fill(0);
+    for (let i = 1; i <= n; i++) {
+        p[0] = i;
+        let j0 = 0;
+        const minv = new Array(m + 1).fill(Infinity);
+        const used = new Array(m + 1).fill(false);
+        do {
+            used[j0] = true;
+            const i0 = p[j0];
+            let delta = Infinity;
+            let j1 = 0;
+            for (let j = 1; j <= m; j++) {
+                if (used[j])
+                    continue;
+                const cur = cost[i0 - 1][j - 1] - u[i0] - v[j];
+                if (cur < minv[j]) {
+                    minv[j] = cur;
+                    way[j] = j0;
+                }
+                if (minv[j] < delta) {
+                    delta = minv[j];
+                    j1 = j;
+                }
+            }
+            for (let j = 0; j <= m; j++) {
+                if (used[j]) {
+                    u[p[j]] += delta;
+                    v[j] -= delta;
+                }
+                else
+                    minv[j] -= delta;
+            }
+            j0 = j1;
+        } while (p[j0] !== 0);
+        do {
+            const j1 = way[j0];
+            p[j0] = p[j1];
+            j0 = j1;
+        } while (j0);
+    }
+    const column = new Array(n).fill(-1);
+    for (let j = 1; j <= m; j++)
+        if (p[j])
+            column[p[j] - 1] = j - 1;
+    return column;
+}
+const clusterSimilarity = (cluster, item) => Math.max(...cluster.members.map(m => similarity(m.item, item)));
+/**
+ * The judges' items grouped into findings. Judges are taken in order; each judge's items are
+ * assigned one-to-one to the findings so far by the Hungarian algorithm (a finding scores as its
+ * closest member), never first-fit. An item left over that a finding already holding this judge
+ * resembles joins it (one judge split what another named once); any other leftover is a new finding.
+ */
+export function clusterItems(judges, items) {
+    const clusters = [];
+    judges.forEach((judge, j) => {
+        const mine = [...items[j]].sort(order);
+        const open = clusters.map((c, i) => ({ c, i })).filter(x => !x.c.members.some(m => m.judge === judge));
+        const sims = mine.map(item => open.map(x => clusterSimilarity(x.c, item)));
+        const placed = new Set();
+        if (mine.length && open.length) {
+            const transpose = mine.length > open.length;
+            const matrix = transpose ? open.map((_, k) => mine.map((__, i) => sims[i][k])) : sims;
+            const column = assign(matrix.map(row => row.map(s => (s >= MATCH_THRESHOLD ? 1 - s : 1))));
+            column.forEach((col, row) => {
+                if (col < 0)
+                    return;
+                const [i, k] = transpose ? [col, row] : [row, col];
+                if (sims[i][k] < MATCH_THRESHOLD)
+                    return;
+                open[k].c.members.push({ judge, item: mine[i] });
+                placed.add(i);
+            });
+        }
+        mine.forEach((item, i) => {
+            if (placed.has(i))
+                return;
+            // Only a finding another judge also holds: a judge's own two findings are never merged into one.
+            const home = clusters.filter(c => c.members.some(m => m.judge === judge) && c.members.some(m => m.judge !== judge)).map(c => ({ c, s: clusterSimilarity(c, item) }))
+                .filter(x => x.s >= MATCH_THRESHOLD).sort((a, b) => b.s - a.s || order(a.c.members[0].item, b.c.members[0].item))[0];
+            if (home)
+                home.c.members.push({ judge, item });
+            else
+                clusters.push({ members: [{ judge, item }] });
+        });
+    });
+    return clusters;
+}
+/**
+ * Status from every judge's call. Confirmed: a strict majority raised it or confirmed it with
+ * evidence. Dropped: refutations with evidence at least match the support and no judge is unsure.
+ * Disputed otherwise. With two judges: both raised it, or the other confirmed it; refuted, dropped.
+ */
+export function statusOf(calls, judges) {
+    const values = Object.values(calls);
+    const support = values.filter(c => c === 'raised' || c === 'confirm').length;
+    const refuted = values.filter(c => c === 'refute').length;
+    if (support > judges / 2)
+        return 'confirmed';
+    if (refuted && refuted >= support && !values.includes('unsure') && !values.includes('not asked'))
+        return 'dropped';
+    return 'disputed';
+}

package/dist/review/reviewer/context.d.ts

@@ -0,0 +1,75 @@
+import type { RouterPolicy } from '../../deep/router.js';
+import type { PanelItem } from './panel.js';
+import { type Exec } from './exec.js';
+import type { OpenItem } from './verdict.js';
+export declare const REVIEW_DISMISSALS: string;
+export interface ReviewDismissal {
+    id: string;
+    file?: string;
+    line?: number;
+    class: string;
+    issue: string;
+    reason: string;
+    at: string;
+    by?: string;
+}
+export declare function readReviewDismissals(cwd: string): ReviewDismissal[];
+/**
+ * The dismissal an item repeats: the same id, or the same finding re-worded: the same file and
+ * class, within a few lines, and mostly the same words. A different bug on the same line, or a
+ * finding that only shares the file and class, is not dismissed.
+ */
+export declare function dismissedAs(item: OpenItem, dismissals: ReviewDismissal[]): ReviewDismissal | undefined;
+export interface ContextInput {
+    cwd: string;
+    /** Where .rigour lives: the main checkout when cwd is the background reviewer's worktree. */
+    stateRoot: string;
+    /** The team's dismissals, when it allows them (empty otherwise). */
+    dismissals: ReviewDismissal[];
+    diff: string;
+    router: RouterPolicy | undefined;
+    /** The previous verdict's panel decisions, and the files changed since it. */
+    previousPanel: PanelItem[] | undefined;
+    touched: Set<string>;
+    /** Docs that name the changed code (relatedDocs). */
+    docs: Array<{
+        doc: string;
+        names: string[];
+    }>;
+    /** Findings Rigour's checks already report on this change, one line each. */
+    checks: string[];
+}
+/** A review's result as the reviewer's inputs: its hints, and what its checks found, as settled. */
+export declare function reviewerInputs(review: {
+    hints: string[];
+    findings: Array<{
+        files?: string[];
+        line?: number;
+        title: string;
+    }>;
+}): {
+    hints: string;
+    checks: string[];
+};
+/** The context pack as Markdown, its hash for the fingerprint, and the router's count of risky changed functions (undefined when it could not score). */
+export declare function buildContext(input: ContextInput): {
+    text: string;
+    key: string;
+    risky: number | undefined;
+};
+/**
+ * Tracked Markdown docs that name a changed file by path or by a distinctive file stem: one
+ * `git grep` over the docs, never a read of every one, stopping at the first few.
+ */
+export declare function relatedDocs(cwd: string, changedFiles: string[], exec?: Exec): Promise<Array<{
+    doc: string;
+    names: string[];
+}>>;
+/**
+ * `rigour dismiss <id>` on a reviewer finding: only where the team allows it (`review.reviewer.dismissals`), with a
+ * reason, recorded with who dismissed it. The item is found in this branch's latest verdict.
+ */
+export declare function dismissReviewerFinding(cwd: string, id: string, reason: string, allowed: boolean, exec?: Exec): Promise<{
+    item?: OpenItem;
+    error?: string;
+}>;

package/dist/review/reviewer/context.js

@@ -0,0 +1,140 @@
+/**
+ * What the team already knows, handed to every judge so a review starts from it instead of from
+ * nothing: the verified review lessons and the repository rules for the files the change touches,
+ * the findings the team settled (dismissed as not a bug, or refuted with evidence in an earlier
+ * round on a file nothing has changed since), and the docs that name the changed code. Built
+ * deterministically, without a model; its hash is part of the verdict's fingerprint, so a new
+ * lesson or dismissal is never answered by a verdict cached before it.
+ *
+ * The reviewer dismissal store lives here too: `rigour dismiss <id>` on a reviewer finding records
+ * the finding itself, so the same finding re-worded on the same file is recognised and never
+ * blocks again.
+ */
+import fs from 'fs';
+import path from 'path';
+import { createHash } from 'crypto';
+import { buildReviewTask } from '../review-task.js';
+import { reviewedKeys } from '../ledger.js';
+import { textSimilarity } from './consensus.js';
+import { defaultExec, GH_TIMEOUT_MS } from './exec.js';
+import { VerdictStore } from './store.js';
+export const REVIEW_DISMISSALS = path.join('.rigour', 'dismissed-review-items.json');
+const MAX_DOCS = 10;
+const MAX_SETTLED = 40;
+export function readReviewDismissals(cwd) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(cwd, REVIEW_DISMISSALS), 'utf8'));
+        return Array.isArray(parsed?.entries) ? parsed.entries.filter((e) => typeof e?.id === 'string' && typeof e?.issue === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Records "not a bug" for a reviewer finding; idempotent. A human's own review point is never dismissed this way. */
+function dismissReviewItem(cwd, item, reason, by, at = new Date().toISOString()) {
+    if (item.kind === 'prior')
+        return false;
+    const entries = readReviewDismissals(cwd);
+    if (entries.some(e => e.id === item.id))
+        return true;
+    entries.push({ id: item.id, ...(item.file ? { file: item.file } : {}), ...(item.line ? { line: item.line } : {}), class: item.class, issue: item.issue, reason, at, ...(by ? { by } : {}) });
+    fs.mkdirSync(path.join(cwd, '.rigour'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, REVIEW_DISMISSALS), JSON.stringify({ entries }, null, 2));
+    return true;
+}
+/** Close enough in place and wording that a dismissal of one is a dismissal of the other; a different bug nearby never is. */
+const DISMISSAL_LINES = 3;
+const DISMISSAL_WORDS = 0.6;
+/**
+ * The dismissal an item repeats: the same id, or the same finding re-worded: the same file and
+ * class, within a few lines, and mostly the same words. A different bug on the same line, or a
+ * finding that only shares the file and class, is not dismissed.
+ */
+export function dismissedAs(item, dismissals) {
+    if (item.kind === 'prior')
+        return undefined;
+    return dismissals.find(d => d.id === item.id) ?? dismissals.find(d => d.file === item.file && d.class === item.class
+        && (d.line === undefined || item.line === undefined || Math.abs(d.line - item.line) <= DISMISSAL_LINES)
+        && textSimilarity({ ...item, consequence: undefined }, { id: d.id, kind: 'finding', class: d.class, issue: d.issue }) >= DISMISSAL_WORDS);
+}
+/** A review's result as the reviewer's inputs: its hints, and what its checks found, as settled. */
+export function reviewerInputs(review) {
+    return { hints: review.hints.join('\n'), checks: review.findings.map(f => `${f.files?.[0] ?? '?'}${f.line ? `:${f.line}` : ''} ${f.title}`) };
+}
+/** The context pack as Markdown, its hash for the fingerprint, and the router's count of risky changed functions (undefined when it could not score). */
+export function buildContext(input) {
+    const sections = [];
+    let task;
+    try {
+        task = buildReviewTask(input.cwd, input.diff, input.router, undefined, undefined, reviewedKeys(input.stateRoot));
+    }
+    catch {
+        task = undefined;
+    }
+    if (task?.lessons.length)
+        sections.push(`## Lessons this team verified on earlier reviews, for the files this change touches\n${task.lessons.map(l => `- ${l.file}: ${l.text}${l.prs.length ? ` (PR ${l.prs.join(', ')})` : ''}`).join('\n')}`);
+    if (task?.rules.length)
+        sections.push(`## Repository rules that name what this change touches\n${task.rules.map(r => `- ${r.source}: ${r.text}`).join('\n')}`);
+    if (input.checks.length)
+        sections.push(`## Already found by Rigour's checks: they block on their own, so do not report them again\n${input.checks.slice(0, MAX_SETTLED).map(c => `- ${c}`).join('\n')}`);
+    const dismissed = input.dismissals.slice(-MAX_SETTLED).map(d => `- dismissed as not a bug${d.by ? ` by ${d.by}` : ''}: ${where(d)} [${d.class}] ${d.issue} (reason: ${d.reason})`);
+    const refuted = (input.previousPanel ?? []).filter(p => p.status === 'dropped' && !!p.item.file && !input.touched.has(p.item.file)).slice(0, MAX_SETTLED)
+        .map(p => `- refuted with evidence in the last round: ${where(p.item)} [${p.item.class}] ${p.item.issue} (${(p.cross ?? []).find(c => c.call === 'refute')?.evidence ?? 'evidence in the previous verdict'})`);
+    if (dismissed.length || refuted.length)
+        sections.push(`## Settled: do not raise these again unless the code now shows something new\n${[...dismissed, ...refuted].join('\n')}`);
+    const docs = input.docs;
+    if (docs.length)
+        sections.push(`## Docs that describe the changed code (read one when its claim matters to a finding)\n${docs.map(d => `- ${d.doc} (names ${d.names.join(', ')})`).join('\n')}`);
+    const text = sections.length ? `# What this team already knows\n\n${sections.join('\n\n')}\n` : 'none\n';
+    return { text, key: createHash('sha256').update(text).digest('hex').slice(0, 16), risky: task ? task.items.length + task.alreadyReviewed : undefined };
+}
+function where(x) {
+    return x.file ? `${x.file}${x.line ? `:${x.line}` : ''}` : '(no file)';
+}
+/**
+ * Tracked Markdown docs that name a changed file by path or by a distinctive file stem: one
+ * `git grep` over the docs, never a read of every one, stopping at the first few.
+ */
+export async function relatedDocs(cwd, changedFiles, exec = defaultExec) {
+    const names = [...new Set(changedFiles.flatMap(file => {
+            const stem = path.posix.basename(file).replace(/\.[^.]+$/, '');
+            return stem.length >= 5 && !/^(index|types|utils|helpers|config|main)$/.test(stem) ? [file, stem] : [file];
+        }))];
+    if (!names.length)
+        return [];
+    const grep = await exec('git', ['grep', '-I', '-F', '-o', ...names.flatMap(name => ['-e', name]), '--', '*.md'], { cwd, timeoutMs: GH_TIMEOUT_MS });
+    const found = new Map();
+    for (const line of grep.stdout.split('\n')) {
+        const at = line.indexOf(':');
+        if (at <= 0)
+            continue;
+        const doc = line.slice(0, at);
+        if (!found.has(doc) && found.size >= MAX_DOCS)
+            continue;
+        found.set(doc, (found.get(doc) ?? new Set()).add(line.slice(at + 1)));
+    }
+    return [...found].map(([doc, hits]) => ({ doc, names: [...hits].slice(0, 3) }));
+}
+/**
+ * `rigour dismiss <id>` on a reviewer finding: only where the team allows it (`review.reviewer.dismissals`), with a
+ * reason, recorded with who dismissed it. The item is found in this branch's latest verdict.
+ */
+export async function dismissReviewerFinding(cwd, id, reason, allowed, exec = defaultExec) {
+    if (!allowed)
+        return { error: 'this team does not dismiss reviewer findings (review.reviewer.dismissals is off): fix the code, or improve the reviewer (its prompt, rules or the reviewers it runs) so the finding is not raised' };
+    if (reason.trim().length < 5)
+        return { error: 'say why it is not a bug, in a few words' };
+    const store = await VerdictStore.open(cwd, exec);
+    if (!store)
+        return { error: 'not a git repository' };
+    const branch = (await exec('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, timeoutMs: GH_TIMEOUT_MS })).stdout.trim();
+    const state = store.branchState(branch);
+    const open = state ? store.readJson(store.openPath(state.verdict)) ?? [] : [];
+    const item = open.find(i => i.id === id);
+    if (!item)
+        return { error: `no open reviewer finding ${id} on ${branch}: run \`rigour review --reviewer\` and copy the id it shows` };
+    const who = (await exec('git', ['config', 'user.email'], { cwd, timeoutMs: GH_TIMEOUT_MS })).stdout.trim() || (await exec('git', ['config', 'user.name'], { cwd, timeoutMs: GH_TIMEOUT_MS })).stdout.trim();
+    if (!dismissReviewItem(cwd, item, reason, who))
+        return { error: `${id} is a human review point: answer it in the reply, it cannot be dismissed here` };
+    return { item };
+}

package/dist/review/reviewer/context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/review/reviewer/context.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { dismissedAs } from './context.js';
+const dismissal = { id: 'abcdef0123', file: 'src/x.ts', line: 40, class: 'correctness', issue: 'cache key built from user id may collide', reason: 'ids are unique per tenant', at: '2026-10-06' };
+const finding = (over) => ({ id: 'ffff000011', kind: 'finding', class: 'correctness', file: 'src/x.ts', line: 40, issue: 'cache key built from the user id may collide', consequence: 'two users share an entry', ...over });
+describe('a dismissal', () => {
+    it('covers the same finding re-worded nearby', () => {
+        expect(dismissedAs(finding({}), [dismissal])).toBe(dismissal);
+        expect(dismissedAs(finding({ line: 42, issue: 'the cache key built from user id may collide' }), [dismissal])).toBe(dismissal);
+        expect(dismissedAs(finding({ id: 'abcdef0123', issue: 'anything at all' }), [dismissal])).toBe(dismissal); // its own id
+    });
+    it('never hides a different bug, even on the same line and in the same class', () => {
+        expect(dismissedAs(finding({ issue: 'cache entry never invalidated when the user changes' }), [dismissal])).toBeUndefined();
+        expect(dismissedAs(finding({ line: 42, issue: 'cache entry never invalidated when user id changes' }), [dismissal])).toBeUndefined();
+        expect(dismissedAs(finding({ line: 80 }), [dismissal])).toBeUndefined(); // far away
+        expect(dismissedAs(finding({ class: 'production-cost' }), [dismissal])).toBeUndefined();
+        expect(dismissedAs({ ...finding({}), kind: 'prior' }, [dismissal])).toBeUndefined(); // a human's point is never dismissed this way
+    });
+});

package/dist/review/reviewer/exec.js

@@ -1,8 +1,12 @@
 /** How the reviewer runs commands (git, gh, the agent CLIs); tests replace it. */
 import { execa } from 'execa';
 export const defaultExec = async (command, args, options) => {
-    const result = await execa(command, args, { cwd: options.cwd, reject: false, timeout: options.timeoutMs, input: '', env: options.env ? { ...process.env, ...options.env } : undefined, maxBuffer: 64 * 1024 * 1024 });
-    return { exitCode: result.exitCode ?? 1, stdout: String(result.stdout ?? ''), stderr: String(result.stderr ?? '') };
+    // stdin is /dev/null, not an empty pipe: an agent CLI that reads stdin sees its end at once, and a command that exits
+    // before an empty write lands (git rev-parse) cannot fail the run with EPIPE, as it did on Linux.
+    const result = await execa(command, args, { cwd: options.cwd, reject: false, timeout: options.timeoutMs, stdin: 'ignore', env: options.env ? { ...process.env, ...options.env } : undefined, maxBuffer: 64 * 1024 * 1024 });
+    const stderr = String(result.stderr ?? '');
+    // A command that could not start, timed out or was killed writes nothing itself: say which, never an empty failure.
+    return { exitCode: result.exitCode ?? 1, stdout: String(result.stdout ?? ''), stderr: stderr || (result.failed && 'shortMessage' in result ? String(result.shortMessage) : '') };
 };
 export const GH_TIMEOUT_MS = 60_000;
 /** The named GitHub account's token for `gh`, when the person keeps several; otherwise gh's own. */

package/dist/review/reviewer/exec.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/review/reviewer/exec.test.js

@@ -0,0 +1,23 @@
+import os from 'os';
+import { describe, expect, it } from 'vitest';
+import { defaultExec } from './exec.js';
+describe('running a command', () => {
+    it('passes the command\'s own output through', async () => {
+        const result = await defaultExec(process.execPath, ['-e', 'process.stdout.write("out"); process.stderr.write("err"); process.exit(3)'], { cwd: os.tmpdir(), timeoutMs: 30_000 });
+        expect(result).toEqual({ exitCode: 3, stdout: 'out', stderr: 'err' });
+    });
+    it('gives the command an ended stdin, so one that reads it never waits and one that exits at once never fails', async () => {
+        const reader = await defaultExec(process.execPath, ['-e', 'let n = 0; process.stdin.on("data", d => n += d.length).on("end", () => process.stdout.write(`read ${n}`))'], { cwd: os.tmpdir(), timeoutMs: 30_000 });
+        expect(reader).toEqual({ exitCode: 0, stdout: 'read 0', stderr: '' });
+        const runs = await Promise.all(Array.from({ length: 50 }, () => defaultExec(process.execPath, ['-e', 'process.stdout.write("ok")'], { cwd: os.tmpdir(), timeoutMs: 30_000 })));
+        expect(runs.every(r => r.exitCode === 0 && r.stdout === 'ok')).toBe(true);
+    });
+    it('says why a command that never answered failed: not started, or timed out', async () => {
+        const missing = await defaultExec('rigour-no-such-command', [], { cwd: os.tmpdir(), timeoutMs: 30_000 });
+        expect(missing.exitCode).not.toBe(0);
+        expect(missing.stderr).toContain('rigour-no-such-command'); // ENOENT on Unix, "is not recognized" on Windows
+        const slow = await defaultExec(process.execPath, ['-e', 'setTimeout(() => {}, 10_000)'], { cwd: os.tmpdir(), timeoutMs: 200 });
+        expect(slow.exitCode).not.toBe(0);
+        expect(slow.stderr).toMatch(/timed out/i);
+    });
+});

package/dist/review/reviewer/inputs.d.ts

@@ -22,6 +22,8 @@ export declare function findPullRequest(gh: Gh, branch: string, head: string, na
     pr?: PullRequest;
     error?: string;
 }>;
+/** Written by a person: not a bot, and not the pull request's author answering their own review. */
+export declare function isHuman(item: any, author: string): boolean;
 /** Every review by a person and every inline comment by a person, hidden from `reviewsBefore` on. */
 export declare function humanReviews(gh: Gh, pr: PullRequest, reviewsBefore: string | undefined): Promise<{
     reviews?: HumanReviews;

package/dist/review/reviewer/inputs.js

@@ -47,6 +47,10 @@ async function viewPullRequest(gh, selector) {
         return { error: `gh returned something other than a pull request for ${selector}: ${result.stdout.slice(0, 120)}` };
     }
 }
+/** Written by a person: not a bot, and not the pull request's author answering their own review. */
+export function isHuman(item, author) {
+    return !!item?.user && item.user.type !== 'Bot' && !/\[bot\]$/.test(item.user.login) && item.user.login !== author;
+}
 /** Every review by a person and every inline comment by a person, hidden from `reviewsBefore` on. */
 export async function humanReviews(gh, pr, reviewsBefore) {
     const reviews = await gh(['api', `repos/{owner}/{repo}/pulls/${pr.number}/reviews`, '--paginate']);
@@ -55,7 +59,7 @@ export async function humanReviews(gh, pr, reviewsBefore) {
     const comments = await gh(['api', `repos/{owner}/{repo}/pulls/${pr.number}/comments`, '--paginate']);
     if (comments.exitCode !== 0)
         return { error: `could not read the comments of pull request ${pr.number}: ${comments.stderr.trim().slice(0, 200)}` };
-    const human = (x) => x?.user && x.user.type !== 'Bot' && !/\[bot\]$/.test(x.user.login) && x.user.login !== pr.author;
+    const human = (x) => isHuman(x, pr.author);
     const before = (at) => !reviewsBefore || (typeof at === 'string' && at < reviewsBefore);
     const rounds = parseJsonArrays(reviews.stdout).filter((r) => human(r) && String(r.body ?? '').trim() && before(r.submitted_at));
     const inline = parseJsonArrays(comments.stdout).filter((c) => human(c) && before(c.created_at));

package/dist/review/reviewer/panel.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Two or three judges as a panel, run around the consensus rules (consensus.ts). The judges' own
+ * items are grouped into findings; a finding a strict majority raised is confirmed. Every other
+ * judge then cross-examines, in one batched call each, only the findings it did not raise: confirm
+ * or refute with file:line evidence; no evidence or no answer is unsure. The calls decide by
+ * majority; a disputed finding is shown and never blocks. A finding disputed before, on a file no
+ * commit has touched since, stays disputed without another call; past the item cap, disputed too.
+ *
+ * Every finding keeps what a later re-scoring needs (who raised it, every judge's call, the
+ * cross-examination answers, each judge's own item and the class), so a probabilistic truth model
+ * can be fitted to the ledger later without running anyone again.
+ */
+import { type Call, type PanelStatus } from './consensus.js';
+import type { OpenItem } from './verdict.js';
+export interface PanelItem {
+    /** The item as its first raiser reported it. */
+    item: OpenItem;
+    /** The judges who raised it unprompted. */
+    judges: string[];
+    /** Every judge's call on it, raised or answered in cross-examination. */
+    calls: Record<string, Call>;
+    /** Every cross-examination answer about it, with the code each judge quoted. */
+    cross?: Array<{
+        by: string;
+        call: Call;
+        evidence?: string;
+    }>;
+    /** Each judge's own item when more than one wrote it: what a later re-scoring of the panel needs. */
+    members?: Array<{
+        judge: string;
+        item: OpenItem;
+    }>;
+    status: PanelStatus;
+    /** Why it is disputed without a cross-examination (over the cap, disputed before and untouched since). */
+    note?: string;
+}
+/** A judge's answer about another judge's items: confirm or refute, each with the code that shows it. */
+export interface Answer {
+    id: string;
+    call: 'confirm' | 'refute' | 'unsure';
+    evidence?: string;
+}
+export interface PanelInput {
+    judges: string[];
+    items: OpenItem[][];
+    /** Items disputed in the previous verdict, and the files changed since it. */
+    previousDisputed: OpenItem[];
+    touched: Set<string>;
+    maxItems: number;
+    /** Asks `judge` about items other judges raised; resolves to its answers (a missing one counts as unsure). */
+    ask: (judge: string, items: OpenItem[]) => Promise<Answer[]>;
+    /** Why no more agent runs may start today (a daily cap), checked before each judge's cross-examination. */
+    capped?: () => string | undefined;
+    /** Whether an answer's evidence quotes real code: a `file:line` the checkout has. */
+    evidenced: (evidence: string) => boolean;
+}
+/** The panel's decision on every finding any judge raised. */
+export declare function runPanel(input: PanelInput): Promise<PanelItem[]>;
+/** The answers in a judge's cross-examination reply; nothing usable is no answers (every item then disputed). */
+export declare function parseAnswers(text: string): Answer[];
+/** The accounting with the panel's decision applied: the judges' own items leave, and only what it confirmed blocks. */
+export declare function applyPanel<T extends {
+    open: OpenItem[];
+}>(accounted: T, judgeItemIds: Set<string>, decided: PanelItem[]): T & {
+    disputed: OpenItem[];
+    dropped: OpenItem[];
+};