@rigour-labs/core 6.6.5 → 6.7.0

package/dist/review/quiet.test.js

@@ -15,6 +15,17 @@ describe('quiet by default', () => {
         expect(quiet.advisory.map(f => f.id)).toEqual(['promise-safety', 'file-size']);
         expect(quietSplit(dir, all, true).speaking).toHaveLength(5);
     });
+    it('speaks on what must be fixed, the one rule the stop hook and the push gate share: critical, or high and verified or from a security gate', () => {
+        const all = [
+            { ...finding('frontend-secret-exposure'), severity: 'high', provenance: 'security' },
+            { ...finding('promise-safety'), severity: 'high' },
+            { ...finding('promise-safety', 'verified'), severity: 'high', verified: true },
+            { ...finding('file-size'), severity: 'critical' },
+            finding('migration-order'),
+        ];
+        expect(quietSplit(dir, all).speaking.map(f => f.id)).toEqual(['frontend-secret-exposure', 'promise-safety', 'file-size', 'migration-order']);
+        expect(quietSplit(dir, all).advisory.map(f => f.details)).toEqual(['d']);
+    });
     it('never reports a dismissed finding again, even after its line moves', () => {
         const leak = finding('security-patterns', 'Hardcoded token in `client`');
         expect(dismissFinding(dir, findingKey(leak), 'test fixture token, never deployed')).toBe(true);

package/dist/review/review.d.ts

@@ -14,6 +14,8 @@ export interface ReviewInput {
     deep?: Omit<DeepOptions, 'focusLines' | 'removedLines' | 'diff'>;
     /** Read dismissals and check outcomes at this commit (the base), not as the change left them. */
     trustedRef?: string;
+    /** Run the typed checks (review/typed): the project's TypeScript program takes seconds, so at push, in `rigour review` and in a backtest, not at every stop. */
+    typed?: boolean;
 }
 export interface ReviewResult {
     status: 'PASS' | 'FAIL' | 'ERROR';
@@ -39,6 +41,10 @@ export interface ReviewResult {
     gateErrors: string[];
     /** rigour.yml or .rigour/ files this change edits: they steer the review, so they are called out. */
     controlFilesChanged: string[];
+    /** Candidates for the reviewer to confirm (a nested scan, a property that only leaves through serialisation), from the typed checks. */
+    hints: string[];
+    /** Why the typed checks could not run on a TypeScript project (`gateErrors` then names `typed-checks-unavailable`). */
+    typedError?: string;
 }
 export interface ReviewFinding {
     id: string;

package/dist/review/review.js

@@ -24,6 +24,7 @@ import { unusedExportFailures } from './unused-exports.js';
 import { queryPatternFailures } from './query-patterns.js';
 import { optionalParamFailures } from './optional-params.js';
 import { duplicateFunctionFailures } from './duplicate-functions.js';
+import { typedChecks, TYPED_CHECKS } from './typed/redundancy.js';
 import { loopCopyFailures } from './loop-copies.js';
 import { partialFixFailures } from './partial-fixes.js';
 import { partialWiringFailures } from './partial-wiring.js';
@@ -34,16 +35,21 @@ export async function reviewChange(input) {
     const changedLines = withoutGenerated(input.cwd, parseDiff(diff));
     const targets = input.files?.length ? input.files : Object.keys(changedLines);
     if (targets.length === 0) {
-        return { status: 'PASS', findings: [], fileFindings: [], contextFindings: [], advisory: [], muted: 0, dismissed: 0, dismissedByGate: {}, unlocated: 0, excludedOutsideChangedLines: 0, preexisting: 0, changedLines, report: null, gateErrors: [], controlFilesChanged: controlFiles(diff) };
+        return { status: 'PASS', findings: [], fileFindings: [], contextFindings: [], advisory: [], muted: 0, dismissed: 0, dismissedByGate: {}, unlocated: 0, excludedOutsideChangedLines: 0, preexisting: 0, changedLines, report: null, gateErrors: [], controlFilesChanged: controlFiles(diff), hints: [] };
     }
     const deep = input.deep ? { ...input.deep, focusLines: changedLinesByFile(changedLines), removedLines: removedByFile(diff), diff } : undefined;
-    const report = await new GateRunner(input.config).run(input.cwd, await normalizeScopePatterns(input.cwd, targets), deep);
+    // The team's `commands:` run at push (toolchain.ts), where a failure blocks; here they would only cost time.
+    const report = await new GateRunner({ ...input.config, commands: {} }).run(input.cwd, await normalizeScopePatterns(input.cwd, targets), deep);
     const preexisting = await dropPreexisting(input, report, targets);
     if (input.diffTests && deep)
         report.failures.push(...await diffTestFailures(input.cwd, input.source, deep));
     report.failures.push(...migrationOrderFailures(input.cwd, diff, input.source, input.config));
     report.failures.push(...unusedExportFailures(input.cwd, diff, input.config), ...orphanFileFailures(input.cwd, diff, input.config));
     report.failures.push(...queryPatternFailures(input.cwd, changedLines, input.config), ...optionalParamFailures(input.cwd, changedLines, input.config), ...duplicateFunctionFailures(input.cwd, changedLines, input.config), ...loopCopyFailures(input.cwd, changedLines, input.config), ...partialFixFailures(input.cwd, changedLines, input.config), ...partialWiringFailures(input.cwd, changedLines, input.config));
+    const typed = input.typed ? typedChecks(input.cwd, changedLines, input.config) : { failures: [], hints: [] };
+    report.failures.push(...typed.failures);
+    if (typed.error)
+        report.summary[TYPED_CHECKS] = 'ERROR'; // a check that could not run is a crashed gate, never a pass
     const split = splitByChangedLines(report.failures, changedLines, deep ? changedFunctionSpans(input.cwd, changedLines) : {}, removedByFile(diff));
     const deepError = deepAnalysisError(report);
     const quiet = quietSplit(input.cwd, split.findings, input.config.review?.include_heuristics, input.trustedRef);
@@ -66,7 +72,9 @@ export async function reviewChange(input) {
         report,
         gateErrors,
         controlFilesChanged: controlFiles(diff),
+        hints: typed.hints,
         ...(deepError ? { deepError } : {}),
+        ...(typed.error ? { typedError: typed.error } : {}),
     };
 }
 /** Drop the rules' findings the base already had; returns how many. Model findings stay: the model reviews only the change. */

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

@@ -0,0 +1,51 @@
+import { type Exec } from './exec.js';
+export type ReviewerName = 'claude' | 'cursor' | 'codex';
+export type Vendor = 'anthropic' | 'cursor' | 'openai';
+export type ReviewMode = 'single' | 'cross' | 'full';
+export interface Adapter {
+    vendor: Vendor;
+    binary: string;
+    /** The command line for one review: the prompt is passed as text, never through a shell. */
+    args(prompt: string, model: string | undefined): string[];
+    /** The reviewer's final message and, when the CLI reports them, what the run cost and the tokens it used. */
+    answer(stdout: string): {
+        text: string;
+    } & Spend;
+}
+/** What a run used: dollars when the CLI reports them (Claude Code), tokens otherwise (Codex reports only tokens). */
+export interface Spend {
+    costUsd?: number;
+    tokens?: Tokens;
+}
+export interface Tokens {
+    input: number;
+    output: number;
+}
+export declare const ADAPTERS: Record<ReviewerName, Adapter>;
+export declare function isReviewerName(name: string): name is ReviewerName;
+export interface Installed {
+    binary: string;
+    version: string;
+}
+/**
+ * The newest installed copy of the adapter's CLI, or undefined when none is. Several copies are
+ * common (an old global npm install first on PATH, a current one from Homebrew), and the old one
+ * refuses current models, so the version decides, not PATH order.
+ */
+export declare function resolveAdapter(adapter: Adapter, cwd: string, exec: Exec): Promise<Installed | undefined>;
+/** Which vendors wrote the commits, from their Co-Authored-By trailers. No trailer means a person. */
+export declare function vendorsOf(trailers: string): Set<Vendor>;
+/**
+ * The reviewers a run uses. single: the first available of the list. cross: the first available
+ * whose vendor is not on the trailers, else the first available. full: that one plus the next
+ * available of each other vendor, up to `judges`. Empty when none is installed.
+ */
+export declare function selectReviewers(candidates: ReviewerName[], mode: ReviewMode, authors: Set<Vendor>, available: Set<ReviewerName>, judges?: number): ReviewerName[];
+/** Every reviewer Rigour can run, and whether this machine has it: what bounds the judges of a panel. */
+export declare function reviewerAvailability(cwd: string, exec?: Exec): Promise<Array<{
+    name: ReviewerName;
+    vendor: Vendor;
+    binary: string;
+    installed: boolean;
+    version?: string;
+}>>;

package/dist/review/reviewer/adapters.js

@@ -0,0 +1,181 @@
+/**
+ * Reviewer adapters: the person's own coding-agent CLIs, each run headless and read-only on the
+ * same prompt. `review.reviewer.reviewers` is the contract (an explicit list, any vendors); the
+ * mode picks among it: `single` runs the first available (the default, and the fastest), `cross`
+ * prefers a vendor not on the commits' Co-Authored-By trailers, `full` runs two vendors and the
+ * verdicts are merged. Which mode earns its minutes is decided by the backtest ledger, which
+ * records the reviewer behind each catch, not by preference.
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { defaultExec } from './exec.js';
+const n = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+const READ_ONLY_TOOLS = ['Read', 'Grep', 'Glob', 'Bash(git diff:*)', 'Bash(git show:*)', 'Bash(git log:*)', 'Bash(git grep:*)'];
+export const ADAPTERS = {
+    claude: {
+        vendor: 'anthropic',
+        binary: 'claude',
+        // Isolated: no MCP servers, no hooks, no user-level settings (an output style or permission
+        // of the author's session must not shape the reviewer), read-only tools.
+        args: (prompt, model) => [
+            '-p', prompt,
+            ...(model ? ['--model', model] : []),
+            '--output-format', 'json',
+            '--max-turns', '80',
+            '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}',
+            '--setting-sources', 'project', '--settings', '{"hooks":{},"outputStyle":"default"}',
+            '--allowedTools', ...READ_ONLY_TOOLS,
+            '--disallowedTools', 'Edit', 'Write', 'NotebookEdit', 'Bash(git push:*)', 'Bash(git commit:*)',
+        ],
+        answer: stdout => {
+            try {
+                const parsed = JSON.parse(stdout);
+                const usage = parsed.usage;
+                return {
+                    text: String(parsed.result ?? ''),
+                    ...(typeof parsed.total_cost_usd === 'number' ? { costUsd: parsed.total_cost_usd } : {}),
+                    ...(usage ? { tokens: { input: n(usage.input_tokens) + n(usage.cache_read_input_tokens) + n(usage.cache_creation_input_tokens), output: n(usage.output_tokens) } } : {}),
+                };
+            }
+            catch {
+                return { text: stdout };
+            }
+        },
+    },
+    cursor: {
+        vendor: 'cursor',
+        binary: 'cursor-agent',
+        // Ask mode is read-only and cannot run git: every input the prompt names is a file.
+        args: (prompt, model) => ['-p', '--print', '--output-format', 'json', '--trust', '--mode', 'ask', '--model', model ?? 'auto', prompt],
+        answer: stdout => {
+            try {
+                const pick = (o) => typeof o === 'string' ? o : o && typeof o === 'object' ? (Array.isArray(o) ? pick(o[o.length - 1]) : String(o.result ?? o.text ?? o.content ?? o.message ?? '')) : '';
+                return { text: pick(JSON.parse(stdout)) };
+            }
+            catch {
+                return { text: stdout };
+            }
+        },
+    },
+    codex: {
+        vendor: 'openai',
+        binary: 'codex',
+        args: (prompt, model) => ['exec', '--sandbox', 'read-only', '--json', ...(model ? ['--model', model] : []), '-c', 'model_reasoning_effort=high', prompt],
+        // `codex exec --json` streams events; the last text-bearing one carries the answer.
+        // Warnings arrive as `error` items with a `message`, not `text`, so they are never taken for the answer.
+        // `turn.completed` carries the tokens (Codex reports no dollars).
+        answer: stdout => {
+            let text = '';
+            let tokens;
+            for (const line of stdout.split('\n').filter(Boolean)) {
+                try {
+                    const event = JSON.parse(line);
+                    const candidate = event?.item?.text ?? event?.msg?.message ?? event?.text;
+                    if (typeof candidate === 'string')
+                        text = candidate;
+                    if (event?.type === 'turn.completed' && event.usage)
+                        tokens = { input: n(event.usage.input_tokens), output: n(event.usage.output_tokens) + n(event.usage.reasoning_output_tokens) };
+                }
+                catch {
+                    // not an event line
+                }
+            }
+            return { text: text || stdout, ...(tokens ? { tokens } : {}) };
+        },
+    },
+};
+export function isReviewerName(name) {
+    return name in ADAPTERS;
+}
+/** Where a CLI tends to be installed besides PATH: a global npm prefix, Homebrew, a user-local bin, the agent's own installer. */
+const EXTRA_BIN_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', path.join(os.homedir(), '.local', 'bin'), path.join(os.homedir(), '.npm-global', 'bin'), path.join(os.homedir(), '.claude', 'local')];
+/**
+ * The newest installed copy of the adapter's CLI, or undefined when none is. Several copies are
+ * common (an old global npm install first on PATH, a current one from Homebrew), and the old one
+ * refuses current models, so the version decides, not PATH order.
+ */
+export async function resolveAdapter(adapter, cwd, exec) {
+    const names = process.platform === 'win32' ? [`${adapter.binary}.cmd`, `${adapter.binary}.exe`, adapter.binary] : [adapter.binary];
+    const dirs = [...(process.env.PATH ?? '').split(path.delimiter), ...EXTRA_BIN_DIRS].filter(Boolean);
+    const candidates = new Set();
+    for (const dir of dirs) {
+        for (const name of names) {
+            const candidate = path.join(dir, name);
+            if (executable(candidate))
+                candidates.add(candidate);
+        }
+    }
+    let best;
+    for (const binary of candidates) {
+        const result = await exec(binary, ['--version'], { cwd, timeoutMs: 20_000 });
+        if (result.exitCode !== 0)
+            continue;
+        const version = result.stdout.trim().split('\n')[0];
+        if (!best || newer(version, best.version))
+            best = { binary, version };
+    }
+    return best;
+}
+function executable(file) {
+    try {
+        fs.accessSync(file, process.platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** `a` carries a higher dotted version than `b` (the first such run of digits in each line). */
+function newer(a, b) {
+    const parse = (line) => (line.match(/\d+(?:\.\d+)+/)?.[0] ?? '0').split('.').map(Number);
+    const [x, y] = [parse(a), parse(b)];
+    for (let i = 0; i < Math.max(x.length, y.length); i++) {
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) > (y[i] ?? 0);
+    }
+    return false;
+}
+/** Which vendors wrote the commits, from their Co-Authored-By trailers. No trailer means a person. */
+export function vendorsOf(trailers) {
+    const vendors = new Set();
+    for (const line of trailers.toLowerCase().split('\n')) {
+        if (/claude/.test(line))
+            vendors.add('anthropic');
+        if (/cursor/.test(line))
+            vendors.add('cursor');
+        if (/codex|openai/.test(line))
+            vendors.add('openai');
+    }
+    return vendors;
+}
+/**
+ * The reviewers a run uses. single: the first available of the list. cross: the first available
+ * whose vendor is not on the trailers, else the first available. full: that one plus the next
+ * available of each other vendor, up to `judges`. Empty when none is installed.
+ */
+export function selectReviewers(candidates, mode, authors, available, judges = 2) {
+    const installed = candidates.filter(name => available.has(name));
+    if (installed.length === 0)
+        return [];
+    let first = installed[0];
+    if (mode !== 'single')
+        first = installed.find(name => !authors.has(ADAPTERS[name].vendor)) ?? first;
+    if (mode !== 'full')
+        return [first];
+    const chosen = [first];
+    for (const name of installed) {
+        if (chosen.length >= judges)
+            break;
+        if (!chosen.some(c => ADAPTERS[c].vendor === ADAPTERS[name].vendor))
+            chosen.push(name);
+    }
+    return chosen;
+}
+/** Every reviewer Rigour can run, and whether this machine has it: what bounds the judges of a panel. */
+export async function reviewerAvailability(cwd, exec = defaultExec) {
+    return Promise.all(Object.keys(ADAPTERS).map(async (name) => {
+        const found = await resolveAdapter(ADAPTERS[name], cwd, exec);
+        return { name, vendor: ADAPTERS[name].vendor, binary: ADAPTERS[name].binary, installed: !!found, ...(found ? { version: found.version } : {}) };
+    }));
+}

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

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

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

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { ADAPTERS } from './adapters.js';
+/** A real `codex exec --json` run (codex-cli 0.160.1), the warning's path shortened: the shape the adapter must read. */
+const CODEX = [
+    '{"type":"thread.started","thread_id":"01a11477-f9fd-7472-8d31-5863de4cbbdb"}',
+    '{"type":"item.completed","item":{"id":"item_0","type":"error","message":"Codex is ignoring 1 unrecognized configuration setting. Check for typos or deprecated settings.\\n  user (~/.codex/config.toml)"}}',
+    '{"type":"turn.started"}',
+    '{"type":"item.completed","item":{"id":"item_2","type":"agent_message","text":"{\\"answers\\":[{\\"id\\":\\"a1\\",\\"call\\":\\"unsure\\",\\"evidence\\":\\"none\\"}]}"}}',
+    '{"type":"turn.completed","usage":{"input_tokens":26565,"cached_input_tokens":13184,"cache_write_input_tokens":0,"output_tokens":24,"reasoning_output_tokens":0}}',
+].join('\n');
+describe('reading an agent CLI\'s answer', () => {
+    it('takes Codex\'s last agent message, never a warning, and its tokens', () => {
+        expect(ADAPTERS.codex.answer(CODEX)).toEqual({ text: '{"answers":[{"id":"a1","call":"unsure","evidence":"none"}]}', tokens: { input: 26565, output: 24 } });
+    });
+    it('takes Claude Code\'s result, its cost and its tokens', () => {
+        const out = JSON.stringify({ result: '{"prior_points":[]}', total_cost_usd: 0.42, usage: { input_tokens: 10, cache_read_input_tokens: 900, cache_creation_input_tokens: 90, output_tokens: 300 } });
+        expect(ADAPTERS.claude.answer(out)).toEqual({ text: '{"prior_points":[]}', costUsd: 0.42, tokens: { input: 1000, output: 300 } });
+    });
+    it('falls back to the raw output when it is not what the CLI usually prints', () => {
+        expect(ADAPTERS.claude.answer('not json')).toEqual({ text: 'not json' });
+        expect(ADAPTERS.codex.answer('plain text')).toEqual({ text: 'plain text' });
+    });
+});

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

@@ -0,0 +1,41 @@
+import type { Config } from '../../types/index.js';
+import { type ModeRecord, type ReviewerResult } from '../reviewer.js';
+import { type Exec } from './exec.js';
+import { type DaySpend, type ReviewAttempt } from './store.js';
+import { type OpenItem } from './verdict.js';
+export interface BackgroundJob {
+    head: string;
+    branch: string;
+    base: string;
+}
+/**
+ * Starts `command` detached (its own process group, output to the branch's log) and records its
+ * pid; a job still running for the same branch is ended first. Returns the log path.
+ */
+export declare function startBackgroundReview(cwd: string, job: BackgroundJob, command: string[], exec?: Exec): Promise<string | undefined>;
+/** The detached process: review the commit in a worktree of its own, write the verdict, tell the person. */
+export declare function backgroundReview(cwd: string, job: BackgroundJob, config: Config, exec?: Exec, log?: (line: string) => void): Promise<ReviewerResult>;
+export interface ReviewStatus {
+    branch: string;
+    /** A review still running, and for which commit. */
+    running?: {
+        pid: number;
+        head: string;
+    };
+    /** What the reviewer spent today in this repository: the count the daily caps are checked against. */
+    today: DaySpend;
+    /** The last review that ended without a verdict, when it is newer than the last verdict. */
+    attempt?: ReviewAttempt;
+    /** The last verdict recorded for the branch. */
+    last?: {
+        head: string;
+        mode: 'full' | 'delta';
+        at: string;
+        open: OpenItem[];
+        ran?: ModeRecord;
+        disputed: OpenItem[];
+    };
+    log?: string;
+}
+/** What the background reviewer has done for a branch: running, the last verdict and its open items. */
+export declare function reviewStatus(cwd: string, branch: string, exec?: Exec): Promise<ReviewStatus | undefined>;

package/dist/review/reviewer/background.js

@@ -0,0 +1,153 @@
+/**
+ * The model review that does not hold the push. Once the deterministic gates pass, the pushed
+ * commit is reviewed in a detached worktree of that exact commit (later commits or edits cannot
+ * change what it reads), in its own process group, so the push returns in seconds. A newer push
+ * of the same branch ends a review still running for an older commit. The verdict goes to the
+ * store (shared by the worktree, the checkout and the status command), a desktop notification
+ * and `rigour review --status`. The hard stop stays explicit: `rigour review --reviewer --full`
+ * before asking a person to look.
+ */
+import { spawn, spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { reviewChange } from '../review.js';
+import { pushReviewSkip, runReviewer } from '../reviewer.js';
+import { defaultExec, GH_TIMEOUT_MS } from './exec.js';
+import { dismissedAs, readReviewDismissals, reviewerInputs } from './context.js';
+import { VerdictStore } from './store.js';
+import { itemLine } from './verdict.js';
+/**
+ * Starts `command` detached (its own process group, output to the branch's log) and records its
+ * pid; a job still running for the same branch is ended first. Returns the log path.
+ */
+export async function startBackgroundReview(cwd, job, command, exec = defaultExec) {
+    const store = await VerdictStore.open(cwd, exec);
+    if (!store)
+        return undefined;
+    endRunning(store, job.branch);
+    const log = store.branchFile(job.branch, 'log');
+    const out = fs.openSync(log, 'w');
+    const child = spawn(command[0], command.slice(1), { cwd, detached: true, stdio: ['ignore', out, out], env: process.env });
+    fs.closeSync(out);
+    if (child.pid)
+        fs.writeFileSync(store.branchFile(job.branch, 'pid'), `${child.pid} ${job.head}\n`);
+    child.unref();
+    return log;
+}
+/** The detached process: review the commit in a worktree of its own, write the verdict, tell the person. */
+export async function backgroundReview(cwd, job, config, exec = defaultExec, log = line => process.stdout.write(`${line}\n`)) {
+    const store = await VerdictStore.open(cwd, exec);
+    if (!store)
+        throw new Error(`${cwd} is not a repository`);
+    const skip = await pushReviewSkip(cwd, job.branch, job.head, config, exec);
+    if (skip) {
+        store.recordAttempt(job.branch, { head: job.head, outcome: 'skipped', reason: skip, at: new Date().toISOString() });
+        log(`review of ${job.head.slice(0, 9)}: skipped (${skip})`);
+        clearPid(store, job.branch);
+        return { outcome: 'skipped', items: [], unverified: [], resolved: [], answerInReply: [], notes: [], disputed: [], dropped: [], dismissed: [], reason: skip, reviewers: [], cached: false };
+    }
+    const worktree = store.worktreeDir(job.head);
+    const added = await exec('git', ['worktree', 'add', '--detach', worktree, job.head], { cwd, timeoutMs: 5 * GH_TIMEOUT_MS });
+    if (added.exitCode !== 0 && !fs.existsSync(path.join(worktree, '.git')))
+        throw new Error(`could not check out ${job.head.slice(0, 9)} for the review: ${added.stderr.trim()}`);
+    try {
+        shareDependencies(cwd, worktree);
+        // The typed checks' hints (a nested scan, a value that only leaves through serialisation) are the reviewer's candidates to confirm.
+        const review = await reviewChange({ cwd: worktree, config, source: { mode: 'base', base: job.base }, typed: true });
+        // The worktree has the commit, not the team's untracked state: dismissals and reviewed functions come from the checkout.
+        const result = await runReviewer(worktree, job.base, config, exec, log, { trigger: 'push', branch: job.branch, stateRoot: cwd, ...reviewerInputs(review) });
+        log(`review of ${job.head.slice(0, 9)}: ${result.outcome}${result.reason ? ` (${result.reason})` : ''}${result.items.length ? `, ${result.items.length} open item(s)` : ''}`);
+        for (const item of result.items)
+            log(`  ${itemLine(item)}`);
+        notify(`Rigour review of ${job.branch} @ ${job.head.slice(0, 9)}: ${result.outcome}${result.items.length ? `, ${result.items.length} open item(s)` : ''}`);
+        return result;
+    }
+    finally {
+        await exec('git', ['worktree', 'remove', '--force', worktree], { cwd, timeoutMs: 5 * GH_TIMEOUT_MS });
+        clearPid(store, job.branch);
+    }
+}
+/** What the background reviewer has done for a branch: running, the last verdict and its open items. */
+export async function reviewStatus(cwd, branch, exec = defaultExec) {
+    const store = await VerdictStore.open(cwd, exec);
+    if (!store)
+        return undefined;
+    const status = { branch, today: store.spend() };
+    const running = runningJob(store, branch);
+    if (running)
+        status.running = running;
+    const state = store.branchState(branch);
+    const attempt = store.attempt(branch);
+    if (attempt && (!state || attempt.at > state.at))
+        status.attempt = attempt;
+    if (state) {
+        const verdict = store.readJson(state.verdict);
+        const dismissals = readReviewDismissals(cwd);
+        status.last = {
+            head: state.head, mode: state.mode, at: state.at,
+            // A finding dismissed since this verdict is not work any more: it leaves the list now, not at the next review.
+            open: (store.readJson(store.openPath(state.verdict)) ?? []).filter(item => !dismissedAs(item, dismissals)),
+            ...(verdict?.inputs?.mode ? { ran: verdict.inputs.mode } : {}),
+            disputed: (verdict?.panel?.items ?? []).filter(d => d.status === 'disputed').map(d => ({ ...d.item, reviewer: d.judges.join('+') })),
+        };
+    }
+    const log = store.branchFile(branch, 'log');
+    if (fs.existsSync(log))
+        status.log = log;
+    return status;
+}
+function runningJob(store, branch) {
+    const pidFile = store.branchFile(branch, 'pid');
+    if (!fs.existsSync(pidFile))
+        return undefined;
+    const [pid, head] = fs.readFileSync(pidFile, 'utf8').trim().split(' ');
+    if (!alive(Number(pid))) {
+        fs.unlinkSync(pidFile);
+        return undefined;
+    }
+    return { pid: Number(pid), head: head ?? '' };
+}
+/** Ends a review still running for the branch (the whole process group: the CLI and the agent it runs). */
+function endRunning(store, branch) {
+    const running = runningJob(store, branch);
+    if (!running)
+        return;
+    try {
+        process.kill(process.platform === 'win32' ? running.pid : -running.pid, 'SIGTERM');
+    }
+    catch {
+        // already gone
+    }
+    fs.unlinkSync(store.branchFile(branch, 'pid'));
+}
+/** The checkout's installed dependencies serve the worktree too (the typed checks need the project's compiler), never a download. */
+function shareDependencies(cwd, worktree) {
+    const root = path.join(cwd, 'node_modules');
+    if (fs.existsSync(root) && !fs.existsSync(path.join(worktree, 'node_modules')))
+        fs.symlinkSync(root, path.join(worktree, 'node_modules'), 'junction');
+}
+function alive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A desktop notification where the platform has one; silence otherwise. */
+function notify(message) {
+    const safe = message.replace(/["\\]/g, '');
+    if (process.platform === 'darwin')
+        spawnSync('osascript', ['-e', `display notification "${safe}" with title "Rigour"`], { stdio: 'ignore', timeout: 5000 });
+    else if (process.platform === 'linux')
+        spawnSync('notify-send', ['Rigour', safe], { stdio: 'ignore', timeout: 5000 });
+}
+/** This process's pid record for the branch, removed when it ends (a newer job's record is left alone). */
+function clearPid(store, branch) {
+    const pidFile = store.branchFile(branch, 'pid');
+    if (fs.existsSync(pidFile) && fs.readFileSync(pidFile, 'utf8').startsWith(`${process.pid} `))
+        fs.unlinkSync(pidFile);
+}

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

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