@rigour-labs/core 6.6.5 → 6.6.6

package/dist/review/lint-overlay.d.ts

@@ -0,0 +1,21 @@
+export interface OverlayMessage {
+    file: string;
+    line: number;
+    column: number;
+    rule: string;
+    message: string;
+}
+/** Why the overlay cannot run here, or undefined when it can. */
+export declare function overlayUnavailable(cwd: string): string | undefined;
+/**
+ * Writes the overlay config to a scratch directory and returns its path. It is an ES module that
+ * imports the repository's config by absolute path, so it is never written into the repository.
+ */
+export declare function writeOverlayConfig(cwd: string): string;
+/** ESLint's JSON report, kept to messages on changed lines; the rest is counted. */
+export declare function onChangedLines(json: string, cwd: string, changedLines: Record<string, Set<number>>): {
+    blocking: OverlayMessage[];
+    preexisting: number;
+} | {
+    error: string;
+};

package/dist/review/lint-overlay.js

@@ -0,0 +1,89 @@
+/**
+ * Type-checked lint rules the repository does not enable yet, on changed lines only. They are the
+ * mechanical dead-code classes a person keeps finding after lint is green: a condition that can
+ * never be true once the types say so, a `?.` on a member every host supplies, a redundant
+ * comparison, a promise nobody awaits. The overlay loads the repository's own flat config first,
+ * so nothing it enforces is lost, and uses its own `typescript-eslint` (never a download). A
+ * message on a line the change did not touch is the team's backlog: counted, not blocking.
+ */
+import fs from 'fs';
+import { createRequire } from 'module';
+import os from 'os';
+import path from 'path';
+import { pathToFileURL } from 'url';
+const CONFIG_FILES = ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs', 'eslint.config.ts', 'eslint.config.mts'];
+const TYPED_RULES = {
+    '@typescript-eslint/no-unnecessary-condition': 'error',
+    '@typescript-eslint/no-unnecessary-boolean-literal-compare': 'error',
+    '@typescript-eslint/no-unnecessary-type-assertion': 'error',
+    '@typescript-eslint/no-redundant-type-constituents': 'error',
+    '@typescript-eslint/prefer-optional-chain': 'error',
+    '@typescript-eslint/switch-exhaustiveness-check': 'error',
+    '@typescript-eslint/no-floating-promises': 'error',
+    '@typescript-eslint/no-misused-promises': 'error',
+};
+/** Why the overlay cannot run here, or undefined when it can. */
+export function overlayUnavailable(cwd) {
+    if (!CONFIG_FILES.some(name => fs.existsSync(path.join(cwd, name))))
+        return 'no eslint.config.* in this repository';
+    try {
+        createRequire(path.join(cwd, 'package.json')).resolve('typescript-eslint');
+    }
+    catch {
+        return 'typescript-eslint is not installed';
+    }
+    return undefined;
+}
+/**
+ * Writes the overlay config to a scratch directory and returns its path. It is an ES module that
+ * imports the repository's config by absolute path, so it is never written into the repository.
+ */
+export function writeOverlayConfig(cwd) {
+    const base = CONFIG_FILES.find(name => fs.existsSync(path.join(cwd, name)));
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rigour-lint-overlay-'));
+    const file = path.join(dir, 'eslint.overlay.config.mjs');
+    fs.writeFileSync(file, `import path from 'node:path';
+import { createRequire } from 'node:module';
+const repo = ${JSON.stringify(cwd)};
+const require = createRequire(path.join(repo, 'package.json'));
+const base = (await import(${JSON.stringify(pathToFileURL(path.join(cwd, base)).href)})).default;
+const ts = require('typescript-eslint');
+const typed = ${JSON.stringify(TYPED_RULES, null, 4)};
+export default [
+    ...base,
+    {
+        files: ['**/*.ts', '**/*.mts', '**/*.cts', '**/*.js', '**/*.mjs', '**/*.svelte.ts', '**/*.svelte.js'],
+        ignores: ['**/*.d.ts'],
+        languageOptions: { parser: ts.parser, parserOptions: { projectService: { allowDefaultProject: ['*.mjs', 'scripts/*.mjs'] }, tsconfigRootDir: repo } },
+        rules: typed,
+    },
+    { files: ['**/*.svelte'], rules: typed },
+    // A test fake deliberately covers cases the types call impossible.
+    { files: ['**/*.test.ts', '**/*.spec.ts', '**/*.svelte.test.ts', 'tests/**', 'test/**', '**/__tests__/**'], rules: { '@typescript-eslint/no-unnecessary-condition': 'off', '@typescript-eslint/no-floating-promises': 'off' } },
+];
+`);
+    return file;
+}
+/** ESLint's JSON report, kept to messages on changed lines; the rest is counted. */
+export function onChangedLines(json, cwd, changedLines) {
+    let results;
+    try {
+        results = JSON.parse(json);
+    }
+    catch {
+        return { error: `eslint printed no JSON: ${json.trim().slice(0, 200)}` };
+    }
+    const blocking = [];
+    let preexisting = 0;
+    for (const result of results) {
+        const file = path.relative(cwd, result.filePath).split(path.sep).join('/');
+        const lines = changedLines[file];
+        for (const message of result.messages) {
+            if (lines?.has(message.line))
+                blocking.push({ file, line: message.line, column: message.column, rule: message.ruleId ?? 'error', message: message.message });
+            else
+                preexisting++;
+        }
+    }
+    return { blocking, preexisting };
+}

package/dist/review/quiet.d.ts

@@ -1,6 +1,12 @@
 import type { Failure } from '../types/index.js';
 export declare const DISMISSED_FILE: string;
 export declare function isProven(failure: Failure): boolean;
+/**
+ * What a change must fix: a proven finding, a critical one, or a high one the semantic engine
+ * verified or a security gate found. The one rule behind the review's verdict, the stop hook and
+ * the push gate, so the three never disagree about the same finding.
+ */
+export declare function mustFix(failure: Failure): boolean;
 /** The same finding across runs and pushes: gate, file and message, never the line (lines move). */
 export declare function findingKey(failure: Failure): string;
 export interface QuietSplit {

package/dist/review/quiet.js

@@ -20,11 +20,21 @@ import fs from 'fs';
 import path from 'path';
 import { checkId, isMuted, readOutcomes, recordOutcome, reportedCheck } from './check-outcomes.js';
 import { readStateFile } from './trusted-state.js';
-const PROVEN_GATES = new Set(['semantic-bugs', 'hallucinated-imports', 'security-patterns', 'deep-analysis', 'diff-tests', 'unused-export', 'orphan-file', 'offset-paging', 'unbounded-window', 'duplicate-function', 'partial-fix', 'partial-wiring']);
+const PROVEN_GATES = new Set(['semantic-bugs', 'hallucinated-imports', 'security-patterns', 'deep-analysis', 'diff-tests', 'unused-export', 'orphan-file', 'offset-paging', 'unbounded-window', 'duplicate-function', 'partial-fix', 'partial-wiring', 'migration-order',
+    'duplicate-null-filter', 'nullable-filtered-column', 'optional-always-supplied', 'write-only-property', 'typed-checks-unavailable']);
 export const DISMISSED_FILE = path.join('.rigour', 'dismissed.json');
 export function isProven(failure) {
     return PROVEN_GATES.has(failure.id);
 }
+/**
+ * What a change must fix: a proven finding, a critical one, or a high one the semantic engine
+ * verified or a security gate found. The one rule behind the review's verdict, the stop hook and
+ * the push gate, so the three never disagree about the same finding.
+ */
+export function mustFix(failure) {
+    const severity = failure.severity ?? 'medium';
+    return isProven(failure) || severity === 'critical' || (severity === 'high' && (failure.verified === true || failure.provenance === 'security'));
+}
 /** The same finding across runs and pushes: gate, file and message, never the line (lines move). */
 export function findingKey(failure) {
     return crypto.createHash('sha256').update(`${failure.id}\u0000${failure.files?.[0] ?? ''}\u0000${failure.details}`).digest('hex').slice(0, 16);
@@ -39,7 +49,7 @@ export function quietSplit(cwd, findings, includeHeuristics = false, trustedRef)
             split.dismissed++;
             split.dismissedByGate[finding.id] = (split.dismissedByGate[finding.id] ?? 0) + 1;
         }
-        else if (includeHeuristics || isProven(finding))
+        else if (includeHeuristics || mustFix(finding))
             split.speaking.push(finding);
         else if (isMuted(outcomes[checkId(finding)]))
             split.muted++;

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,7 +35,7 @@ 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);
@@ -44,6 +45,10 @@ export async function reviewChange(input) {
     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 +71,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,35 @@
+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 it, what the run cost. */
+    answer(stdout: string): {
+        text: string;
+        costUsd?: 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 first
+ * available of another vendor. Empty when none is installed.
+ */
+export declare function selectReviewers(candidates: ReviewerName[], mode: ReviewMode, authors: Set<Vendor>, available: Set<ReviewerName>): ReviewerName[];

package/dist/review/reviewer/adapters.js

@@ -0,0 +1,156 @@
+/**
+ * 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';
+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);
+                return { text: String(parsed.result ?? ''), ...(typeof parsed.total_cost_usd === 'number' ? { costUsd: parsed.total_cost_usd } : {}) };
+            }
+            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.
+        answer: stdout => {
+            let text = '';
+            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;
+                }
+                catch {
+                    // not an event line
+                }
+            }
+            return { text: text || stdout };
+        },
+    },
+};
+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 first
+ * available of another vendor. Empty when none is installed.
+ */
+export function selectReviewers(candidates, mode, authors, available) {
+    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 second = installed.find(name => name !== first && ADAPTERS[name].vendor !== ADAPTERS[first].vendor);
+    return second ? [first, second] : [first];
+}

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

@@ -0,0 +1,34 @@
+import type { Config } from '../../types/index.js';
+import { type ReviewerResult } from '../reviewer.js';
+import { type Exec } from './exec.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;
+    };
+    /** The last verdict recorded for the branch. */
+    last?: {
+        head: string;
+        mode: 'full' | 'delta';
+        at: string;
+        open: 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,128 @@
+/**
+ * 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 { runReviewer } from '../reviewer.js';
+import { defaultExec, GH_TIMEOUT_MS } from './exec.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 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 hints = (await reviewChange({ cwd: worktree, config, source: { mode: 'base', base: job.base }, typed: true })).hints.join('\n');
+        const result = await runReviewer(worktree, job.base, config, exec, log, { trigger: 'push', branch: job.branch, hints });
+        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 });
+        const pidFile = store.branchFile(job.branch, 'pid');
+        if (fs.existsSync(pidFile) && fs.readFileSync(pidFile, 'utf8').startsWith(`${process.pid} `))
+            fs.unlinkSync(pidFile);
+    }
+}
+/** 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 };
+    const running = runningJob(store, branch);
+    if (running)
+        status.running = running;
+    const state = store.branchState(branch);
+    if (state)
+        status.last = { head: state.head, mode: state.mode, at: state.at, open: store.readJson(store.openPath(state.verdict)) ?? [] };
+    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 });
+}

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

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