@stardustlc/dsh-review 0.0.0-stage → 0.3.1

package/lib/exec.js

@@ -0,0 +1,82 @@
+/**
+ * 受信任的结构化 Git 读取。证据命令由宿主 Bash 工具执行。
+ *
+ * @module dsh-review/exec
+ */
+import { spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+const DEFAULT_OUTPUT_LIMIT = 256 * 1024;
+export function run(command, args, options) {
+    const started = Date.now();
+    const limit = options.maxOutputBytes ?? DEFAULT_OUTPUT_LIMIT;
+    return new Promise(resolve => {
+        let settled = false;
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            windowsHide: true,
+            shell: false,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let truncated = false;
+        let bytes = 0;
+        const decoders = { stdout: new StringDecoder('utf8'), stderr: new StringDecoder('utf8') };
+        const abort = () => child.kill('SIGKILL');
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, options.timeoutMs);
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', abort);
+            stdout += decoders.stdout.end();
+            stderr += decoders.stderr.end();
+            resolve({ ok: code === 0 && !timedOut && !options.signal?.aborted && !truncated, code, stdout, stderr, timedOut, truncated, durationMs: Date.now() - started });
+        };
+        const collect = (stream, chunk) => {
+            const available = Math.max(0, limit - bytes);
+            const accepted = chunk.subarray(0, available);
+            bytes += accepted.length;
+            const value = decoders[stream].write(accepted);
+            if (stream === 'stdout')
+                stdout += value;
+            else
+                stderr += value;
+            if (accepted.length < chunk.length)
+                truncated = true;
+        };
+        child.stdout?.on('data', (chunk) => collect('stdout', chunk));
+        child.stderr?.on('data', (chunk) => collect('stderr', chunk));
+        child.on('error', (error) => { stderr += error.message; finish(null); });
+        child.on('close', (code) => finish(code));
+        if (options.input !== undefined) {
+            child.stdin?.end(options.input);
+        }
+        else {
+            child.stdin?.end();
+        }
+    });
+}
+export async function git(cwd, args, timeoutMs = 30000, maxOutputBytes = DEFAULT_OUTPUT_LIMIT, signal) {
+    return run('git', ['-c', 'core.quotepath=false', '-c', 'color.ui=false', '-c', 'core.fsmonitor=false', ...args], { cwd, timeoutMs, maxOutputBytes, signal });
+}
+/** 输出裁剪：保留头部与尾部，中间省略。 */
+export function excerpt(text, maxLines = 40, maxChars = 4000) {
+    const trimmed = text.trimEnd();
+    if (trimmed === '')
+        return '';
+    const lines = trimmed.split(/\r?\n/);
+    let out = lines.length > maxLines ? [...lines.slice(0, maxLines), '… (' + (lines.length - maxLines) + ' 行省略)'].join('\n') : trimmed;
+    if (out.length > maxChars)
+        out = out.slice(0, maxChars) + '…';
+    return out;
+}

package/lib/fingerprint.d.ts

@@ -0,0 +1,12 @@
+/**
+ * finding 指纹：用"种类 + 文件 + 归一化代码行"生成稳定 id，
+ * 这样重排、rebase、加空行都不会让同一条 finding 变新，天然支持"不复报"。
+ *
+ * @module dsh-review/fingerprint
+ */
+export declare function normalizeLine(text: string): string;
+export declare function fingerprintOf(input: {
+    kind: string;
+    file: string;
+    anchor: string;
+}): string;

package/lib/fingerprint.js

@@ -0,0 +1,14 @@
+/**
+ * finding 指纹：用"种类 + 文件 + 归一化代码行"生成稳定 id，
+ * 这样重排、rebase、加空行都不会让同一条 finding 变新，天然支持"不复报"。
+ *
+ * @module dsh-review/fingerprint
+ */
+import { createHash } from 'node:crypto';
+export function normalizeLine(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+export function fingerprintOf(input) {
+    const payload = [input.kind.trim().toLowerCase(), input.file.replace(/\\/g, '/').trim(), normalizeLine(input.anchor)].join('\u0000');
+    return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}

package/lib/gate.d.ts

@@ -0,0 +1,81 @@
+import { type ReviewConfig } from './config.js';
+import type { HeadRecord, Ledger } from './ledger.js';
+import { type ReviewTarget } from './target.js';
+export declare const DROP_KINDS: string[];
+export interface Witness {
+    file: string;
+    line: number;
+    anchor: string;
+    side?: 'before' | 'after';
+}
+export interface CandidateFinding {
+    id?: string;
+    file: string;
+    line: number;
+    kind: string;
+    severity: 'blocker' | 'important' | 'nit';
+    message: string;
+    anchor: string;
+    evidence: string;
+    lens?: string;
+    classOfBug?: string;
+    side?: 'before' | 'after';
+    introducedBy?: Witness;
+    carried?: boolean;
+}
+export interface Vote {
+    candidateId: string;
+    decision: 'confirm' | 'reject' | 'pre-existing' | 'unverifiable';
+    reason: string;
+    witnesses: Witness[];
+    taskId: string;
+}
+export interface GatedFinding {
+    fingerprint: string;
+    file: string;
+    line: number;
+    kind: string;
+    lens: string;
+    severity: 'blocker' | 'important' | 'nit' | 'pre-existing';
+    message: string;
+    evidence: string;
+    preexisting: boolean;
+    anchor: string;
+    targetId: string;
+    verification: Vote[];
+    classOfBug?: string;
+}
+export interface GateResult {
+    postable: GatedFinding[];
+    suppressed: number;
+    suppressedFingerprints: string[];
+    dropped: number;
+    droppedDetail: Array<{
+        file: string;
+        reason: string;
+    }>;
+    unverified: number;
+    declined: unknown[];
+    rejected: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+export declare function candidateId(f: CandidateFinding, target: ReviewTarget): string;
+export declare function parseCandidate(raw: unknown, lens: string, target: ReviewTarget): CandidateFinding | null;
+export declare function parseVote(raw: unknown, taskId: string, expected: string, target: ReviewTarget, candidate?: CandidateFinding): Vote;
+export declare function voteDecision(votes: Vote[], required: number): Vote['decision'];
+export declare function gateFindings(options: {
+    root: string;
+    head: string;
+    base: string;
+    mode: string;
+    findings: CandidateFinding[];
+    config: ReviewConfig;
+    rules: ReviewTarget['rules'];
+    record: HeadRecord;
+    ledger: Ledger;
+    target: ReviewTarget;
+    votes: Record<string, Vote[]>;
+    requiredVotes: number;
+}): GateResult;

package/lib/gate.js

@@ -0,0 +1,149 @@
+import { severityRank } from './config.js';
+import { fingerprintOf } from './fingerprint.js';
+import { sourceMatches } from './target.js';
+export const DROP_KINDS = ['style', 'formatting', 'format', 'diagnostics', 'diagnostic', 'cleanup', 'nitpick', 'naming', 'whitespace'];
+export function candidateId(f, target) {
+    const file = target.files.find(item => (f.side === 'before' ? item.oldPath : item.path) === f.file);
+    const lines = ((f.side === 'before' ? file?.before : file?.after) ?? '').split(/\r?\n/);
+    const occurrence = lines.slice(0, f.line).filter(line => line === f.anchor).length;
+    return fingerprintOf({ kind: f.kind + ':' + (f.classOfBug ?? '') + ':' + occurrence, file: f.file, anchor: f.anchor });
+}
+export function parseCandidate(raw, lens, target) {
+    const item = raw;
+    if (!item || typeof item !== 'object' || typeof item.kind !== 'string')
+        throw new Error('Invalid finding shape');
+    if (DROP_KINDS.includes(item.kind.toLowerCase()))
+        return null;
+    if (!['correctness', 'state', 'breaking', 'security'].includes(item.kind))
+        throw new Error('Unknown finding kind');
+    for (const key of ['file', 'anchor', 'message'])
+        if (typeof item[key] !== 'string' || !item[key].trim())
+            throw new Error('Finding requires ' + key);
+    if (!['blocker', 'important', 'nit'].includes(item.severity))
+        throw new Error('Invalid finding severity');
+    if (item.side !== undefined && !['before', 'after'].includes(item.side))
+        throw new Error('Invalid finding side');
+    const side = item.side === 'before' ? 'before' : 'after';
+    if (!sourceMatches(target, item.file, item.line, item.anchor, side))
+        throw new Error('Finding does not quote exact snapshot source');
+    const introducedBy = item.introducedBy ?? { file: item.file, line: item.line, anchor: item.anchor, side };
+    if (introducedBy.side !== undefined && !['before', 'after'].includes(introducedBy.side))
+        throw new Error('Invalid introducing side');
+    if (!sourceMatches(target, introducedBy.file, introducedBy.line, introducedBy.anchor, introducedBy.side ?? 'after'))
+        throw new Error('Invalid introducing evidence');
+    const changed = target.files.find(file => (introducedBy.side === 'before' ? file.oldPath : file.path) === introducedBy.file);
+    if (!(introducedBy.side === 'before' ? changed?.removedLines : changed?.addedLines)?.includes(introducedBy.line))
+        throw new Error('Finding is not linked to a changed introducing line');
+    const finding = { file: item.file, line: item.line, kind: item.kind, severity: item.severity, message: item.message, anchor: item.anchor, evidence: typeof item.evidence === 'string' ? item.evidence : '', lens, side, introducedBy,
+        ...(typeof item.classOfBug === 'string' && item.classOfBug.trim() ? { classOfBug: item.classOfBug.trim() } : {}) };
+    finding.id = candidateId(finding, target);
+    return finding;
+}
+export function parseVote(raw, taskId, expected, target, candidate) {
+    const item = raw;
+    if (!item || item.candidateId !== expected || !['confirm', 'reject', 'pre-existing', 'unverifiable'].includes(item.decision) || typeof item.reason !== 'string' || item.reason.trim().length < 12 || !Array.isArray(item.witnesses))
+        throw new Error('Invalid independent verification');
+    for (const witness of item.witnesses)
+        if (!witness || typeof witness.file !== 'string' || typeof witness.anchor !== 'string' || !witness.anchor.trim() || (witness.side !== undefined && !['before', 'after'].includes(witness.side)) || !sourceMatches(target, witness.file, witness.line, witness.anchor, witness.side ?? 'after'))
+            throw new Error('Verifier witness is blank or outside the immutable snapshot');
+    if (item.decision !== 'unverifiable' && item.witnesses.length === 0)
+        throw new Error('Verifier supplied no checkable source witness');
+    if (item.decision !== 'unverifiable') {
+        if (!candidate || (candidate.id ?? candidateId(candidate, target)) !== expected)
+            throw new Error('Verifier requires the exact candidate being checked');
+        const locations = [candidate, ...(candidate.introducedBy ? [candidate.introducedBy] : [])];
+        if (!item.witnesses.some(witness => locations.some(location => witness.file === location.file && Math.abs(witness.line - location.line) <= 3)))
+            throw new Error('Verifier witness is unrelated to the candidate or introducing change');
+    }
+    if (item.decision === 'pre-existing' && !item.witnesses.some(witness => witness.side === 'before'))
+        throw new Error('Pre-existing verdict requires base evidence');
+    return { candidateId: expected, decision: item.decision, reason: item.reason.trim(), witnesses: item.witnesses, taskId };
+}
+export function voteDecision(votes, required) {
+    if (votes.length !== required)
+        return 'unverifiable';
+    const majority = Math.floor(required / 2) + 1;
+    for (const decision of ['confirm', 'reject', 'pre-existing'])
+        if (votes.filter(vote => vote.decision === decision).length >= majority)
+            return decision;
+    return 'unverifiable';
+}
+export function gateFindings(options) {
+    const { record, target, config, rules } = options;
+    const result = { postable: [], suppressed: 0, suppressedFingerprints: [], dropped: 0, droppedDetail: [], unverified: 0, declined: [], rejected: [] };
+    let nits = 0;
+    const unique = new Map();
+    for (const finding of options.findings) {
+        if (DROP_KINDS.includes(finding.kind.toLowerCase())) {
+            result.dropped++;
+            continue;
+        }
+        const id = finding.id ?? candidateId(finding, target), prior = unique.get(id);
+        if (!prior || severityRank(finding.severity) > severityRank(prior.severity))
+            unique.set(id, { ...finding, id });
+    }
+    for (const finding of [...unique.values()].sort((a, b) => severityRank(b.severity) - severityRank(a.severity))) {
+        const id = finding.id, votes = options.votes[id] ?? [], decision = voteDecision(votes, options.requiredVotes);
+        if (decision === 'unverifiable') {
+            result.unverified++;
+            continue;
+        }
+        if (decision === 'reject') {
+            const prior = record.posted[id];
+            if (prior && !prior.disposition) {
+                const source = target.files.find(file => file.path === prior.file || file.oldPath === prior.file);
+                const removed = source !== undefined && typeof prior.anchor === 'string' && prior.anchor.trim() !== '' && (source.after === null || !source.after.split(/\r?\n/).includes(prior.anchor));
+                if (!removed) {
+                    result.unverified++;
+                    result.rejected.push({ id, reason: 'The original source anchor remains, or its removal is not covered by this snapshot; human review is required.' });
+                    continue;
+                }
+                prior.disposition = 'fixed';
+                prior.note = 'Independent re-verification and snapshot source confirm removal on target ' + target.id;
+                prior.verification = votes;
+                prior.targetId = target.id;
+            }
+            result.rejected.push({ id, reason: votes.map(v => v.reason).join('\n') });
+            continue;
+        }
+        if (decision !== 'pre-existing' && severityRank(finding.severity) < severityRank(rules.severityFloor ?? config.severityFloor)) {
+            result.dropped++;
+            continue;
+        }
+        if (finding.severity === 'nit' && nits++ >= (rules.maxNits ?? config.maxNits)) {
+            result.dropped++;
+            continue;
+        }
+        if (result.postable.length >= config.maxFindings) {
+            result.unverified++;
+            continue;
+        }
+        const entry = { fingerprint: id, file: finding.file, line: finding.line, kind: finding.kind, lens: finding.lens ?? 'unknown', severity: decision === 'pre-existing' ? 'pre-existing' : finding.severity,
+            message: finding.message, evidence: votes.map(v => v.reason).join('\n'), preexisting: decision === 'pre-existing', anchor: finding.anchor, targetId: target.id, verification: votes,
+            ...(finding.classOfBug ? { classOfBug: finding.classOfBug } : {}) };
+        const prior = record.posted[id];
+        if (prior && prior.targetId === target.id) {
+            prior.repeats++;
+            result.suppressed++;
+            result.suppressedFingerprints.push(id);
+            prior.verification = votes;
+            prior.evidence = entry.evidence;
+            if (severityRank(entry.severity) > severityRank(prior.severity)) {
+                prior.severity = entry.severity;
+                prior.message = entry.message;
+            }
+            continue;
+        }
+        if (prior && !prior.disposition) {
+            result.suppressed++;
+            result.suppressedFingerprints.push(id);
+        }
+        else
+            result.postable.push(entry);
+        options.ledger.remember(record, { ...entry, at: new Date().toISOString(), repeats: prior?.repeats ?? 0 });
+    }
+    record.unverified = result.unverified;
+    record.dropped += result.dropped;
+    record.reviewedFiles = target.files.map(file => file.path);
+    return result;
+}

package/lib/github.d.ts

@@ -0,0 +1,2 @@
+import type { PullRequestEvidence } from './policy.js';
+export declare function githubEvidence(repository: string, number: number, token: string, expectedHead: string, expectedBase: string, fetcher?: typeof fetch): Promise<PullRequestEvidence>;

package/lib/github.js

@@ -0,0 +1,53 @@
+export async function githubEvidence(repository, number, token, expectedHead, expectedBase, fetcher = fetch) {
+    if (!/^[\w.-]+\/[\w.-]+$/.test(repository) || !Number.isSafeInteger(number) || number < 1 || [expectedHead, expectedBase].some(sha => !/^[a-f0-9]{40,64}$/.test(sha)))
+        throw new Error('Invalid GitHub repository, pull request or commit');
+    const request = async (route, body) => {
+        const response = await fetcher('https://api.github.com' + route, { method: body ? 'POST' : 'GET', redirect: 'error', signal: AbortSignal.timeout(15000),
+            headers: { accept: 'application/vnd.github+json', 'content-type': 'application/json', authorization: 'Bearer ' + token, 'X-GitHub-Api-Version': '2026-03-10', 'user-agent': 'dsh-review-gate' }, ...(body ? { body: JSON.stringify(body) } : {}) });
+        if (!response.ok)
+            throw new Error('GitHub evidence unavailable (HTTP ' + response.status + '); gate remains blocked');
+        return response.json();
+    };
+    const prefix = '/repos/' + repository, pr = await request(prefix + '/pulls/' + number);
+    if (pr.head?.sha !== expectedHead || pr.base?.sha !== expectedBase || pr.base?.repo?.full_name?.toLowerCase() !== repository.toLowerCase())
+        throw new Error('GitHub PR head/base changed or repository mismatch');
+    const paged = async (route, field) => {
+        const values = [];
+        for (let page = 1; page <= 30; page++) {
+            const data = await request(route + (route.includes('?') ? '&' : '?') + 'per_page=100&page=' + page), rows = field ? data[field] : data;
+            if (!Array.isArray(rows))
+                throw new Error('Malformed GitHub evidence');
+            values.push(...rows);
+            if (rows.length < 100)
+                return values;
+        }
+        throw new Error('GitHub evidence pagination exceeds coverage limit');
+    };
+    const [reviews, checks, files] = await Promise.all([
+        paged(prefix + '/pulls/' + number + '/reviews'),
+        paged(prefix + '/commits/' + expectedHead + '/check-runs?filter=all', 'check_runs'),
+        paged(prefix + '/pulls/' + number + '/files'),
+    ]);
+    if (files.length !== pr.changed_files || files.some(f => typeof f.filename !== 'string'))
+        throw new Error('Incomplete GitHub changed-file inventory');
+    const [owner, repo] = repository.split('/');
+    let cursor = null, unresolvedThreads = 0;
+    for (let page = 0;; page++) {
+        if (page >= 30)
+            throw new Error('Review-thread coverage limit exceeded');
+        const result = await request('/graphql', { query: 'query($owner:String!,$repo:String!,$number:Int!,$cursor:String){repository(owner:$owner,name:$repo){pullRequest(number:$number){headRefOid reviewThreads(first:100,after:$cursor){nodes{isResolved} pageInfo{hasNextPage endCursor}}}}}', variables: { owner, repo, number, cursor } });
+        const pull = result.data?.repository?.pullRequest, threads = pull?.reviewThreads;
+        if (result.errors || pull?.headRefOid !== expectedHead || !Array.isArray(threads?.nodes) || !threads.pageInfo || threads.nodes.some((t) => typeof t?.isResolved !== 'boolean'))
+            throw new Error('Review-thread evidence unavailable or changed');
+        unresolvedThreads += threads.nodes.filter((t) => !t.isResolved).length;
+        if (threads.pageInfo.hasNextPage === false)
+            break;
+        if (threads.pageInfo.hasNextPage !== true || typeof threads.pageInfo.endCursor !== 'string' || threads.pageInfo.endCursor === cursor)
+            throw new Error('Invalid thread pagination');
+        cursor = threads.pageInfo.endCursor;
+    }
+    const current = await request(prefix + '/pulls/' + number);
+    if (current.head?.sha !== expectedHead || current.base?.sha !== expectedBase)
+        throw new Error('PR changed while reading approval evidence');
+    return { head: expectedHead, author: pr.user, paths: files.flatMap(f => f.previous_filename ? [f.filename, f.previous_filename] : [f.filename]), draft: pr.draft, reviews, checks, unresolvedThreads };
+}

package/lib/index.d.ts

@@ -0,0 +1,36 @@
+import { type ReviewConfig } from './config.js';
+import { type ReviewToolDefinition } from './tools.js';
+import { type SubagentService } from './dispatch.js';
+export declare const name = "review";
+export declare const inject: string[];
+interface HostResult {
+    isError?: boolean;
+    value?: any;
+    error?: {
+        message?: string;
+    };
+}
+export interface ReviewPluginContext {
+    effect?(effect: () => () => void): unknown;
+    tools: {
+        register(definition: ReviewToolDefinition): () => void;
+        execute(call: Record<string, unknown>): Promise<HostResult>;
+        get?(name: string, agent: unknown): unknown;
+    };
+    subagents: SubagentService;
+    permissionPresets: {
+        current(session: unknown): string;
+        resolve(name: string): {
+            sandbox: string;
+        };
+    };
+    jobs: {
+        kill(id: string, caller?: string, reason?: string): unknown;
+        wait(id: string, timeoutMs: number, caller?: string): Promise<{
+            status: string;
+        }>;
+    };
+}
+export declare function apply(ctx: ReviewPluginContext, config?: Partial<ReviewConfig> | null): void;
+export { resolveConfig, DEFAULT_CONFIG } from './config.js';
+export type { ReviewConfig } from './config.js';

package/lib/index.js

@@ -0,0 +1,56 @@
+import { resolveConfig } from './config.js';
+import { buildReviewTools } from './tools.js';
+import { createDispatcher } from './dispatch.js';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+export const name = 'review';
+export const inject = ['tools', 'subagents', 'permissionPresets', 'jobs'];
+export function apply(ctx, config) {
+    const resolved = resolveConfig(config);
+    const runner = async (input) => {
+        const agent = input.exec.agent;
+        if (!agent)
+            throw new Error('Evidence execution requires the live calling agent');
+        const preset = ctx.permissionPresets.current(agent.session);
+        if (ctx.permissionPresets.resolve(preset).sandbox === 'read-only')
+            throw new Error('Evidence command denied in a read-only session; use static source evidence or request the normal workspace permission');
+        const tools = agent.ctx?.get?.('tools') ?? ctx.tools;
+        let toolName = 'bash', command = input.command;
+        if (process.platform === 'win32' && !tools.get?.('bash', agent) && tools.get?.('pwsh', agent)) {
+            const bash = [path.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'Git', 'bin', 'bash.exe'), path.join(process.env.LOCALAPPDATA ?? '', 'Programs', 'Git', 'bin', 'bash.exe')].find(file => existsSync(file));
+            if (!bash)
+                throw new Error('This Windows preset exposes pwsh only. Install Git Bash or enable the controlled Bash tool; no direct process fallback is allowed.');
+            // The official Windows preset exposes pwsh. It remains the policy/cancellation
+            // boundary; use Git Bash underneath, preserving the original visible command.
+            const quote = (s) => "'" + s.replaceAll("'", "''") + "'";
+            command = "if ($PSVersionTable.PSVersion -lt [version]'7.3') { throw 'Git Bash bridging requires PowerShell 7.3+' }; $PSNativeCommandArgumentPassing = 'Standard'; & " + quote(bash) + ' -lc ' + quote(input.command) + '; exit $LASTEXITCODE';
+            toolName = 'pwsh';
+        }
+        const result = await tools.execute({ callId: 'review-check-' + randomUUID(), name: toolName, arguments: { command, description: 'Run review evidence in Git Bash', workdir: input.cwd, timeoutMs: 600000 }, agent, signal: input.signal });
+        if (result.isError || !result.value)
+            throw new Error(result.error?.message ?? 'Controlled Bash execution failed');
+        const value = result.value;
+        if (value.kind === 'promoted' || value.kind === 'background') {
+            ctx.jobs.kill(value.jobId, agent.id, 'Review checks cannot continue in the background');
+            for (;;) {
+                const view = await ctx.jobs.wait(value.jobId, 5000, agent.id);
+                if (!['running', 'stopping'].includes(view.status))
+                    break;
+            }
+            throw new Error('Evidence command exceeded the foreground budget and was stopped');
+        }
+        const truncated = value.stdout?.truncated === true || value.stderr?.truncated === true;
+        return { ok: value.exitCode === 0 && !value.timedOut && !value.aborted && !value.sandbox?.denied && !truncated,
+            exitCode: value.exitCode ?? null, timedOut: !!value.timedOut, aborted: !!value.aborted, truncated,
+            output: String(value.stdout?.text ?? '') + (value.stderr?.text ? '\n' + value.stderr.text : '') };
+    };
+    const dispatcher = (exec, root, signal) => createDispatcher({ subagents: ctx.subagents, parent: exec.agent, provider: resolved.subagentProvider, signal, cwd: root });
+    for (const definition of buildReviewTools(resolved, { runner, dispatcher })) {
+        if (ctx.effect)
+            ctx.effect(() => ctx.tools.register(definition));
+        else
+            ctx.tools.register(definition);
+    }
+}
+export { resolveConfig, DEFAULT_CONFIG } from './config.js';

package/lib/ledger.d.ts

@@ -0,0 +1,140 @@
+import type { Mode } from './modes.js';
+import type { ReviewTarget } from './target.js';
+import type { LensTask } from './lenses.js';
+import type { CandidateFinding } from './gate.js';
+import type { ReviewScope } from './scope.js';
+export type Disposition = 'fixed' | 'wrong' | 'intentional' | 'wontfix';
+export type RunStatus = 'pending' | 'running' | 'complete' | 'incomplete' | 'failed' | 'cancelled' | 'stale';
+export interface LedgerFinding {
+    fingerprint: string;
+    file: string;
+    line: number;
+    kind: string;
+    lens?: string;
+    severity: 'blocker' | 'important' | 'nit' | 'pre-existing';
+    message: string;
+    evidence: string;
+    at: string;
+    disposition?: Disposition;
+    note?: string;
+    repeats: number;
+    targetId?: string;
+    anchor?: string;
+    classOfBug?: string;
+    verification?: unknown;
+}
+export interface HeadRecord {
+    head: string;
+    base?: string;
+    targetId?: string;
+    series?: string;
+    latestRunId?: string;
+    round: number;
+    mode: Mode;
+    posted: Record<string, LedgerFinding>;
+    reviewedFiles: string[];
+    dropped: number;
+    suppressed: number;
+    unverified: number;
+    updatedAt: string;
+}
+export interface StoredRun {
+    id: string;
+    targetId: string;
+    series: string;
+    head: string;
+    target: ReviewTarget;
+    mode: Mode;
+    status: RunStatus;
+    stage: 'find' | 'verify' | 'arbiter' | 'done';
+    tasks: LensTask[];
+    results: Record<string, unknown>;
+    candidates: CandidateFinding[];
+    round: number;
+    calls: number;
+    errors: string[];
+    createdAt: string;
+    completedAt?: string;
+    postable: unknown[];
+    rejected: unknown[];
+    unverified: number;
+    accepted?: LedgerFinding[];
+    independent: boolean;
+    scope?: ReviewScope;
+    lease?: string;
+    leasePid?: number;
+    summary?: string;
+    risk?: {
+        tier: 'low' | 'medium' | 'high';
+        extraHuman: boolean;
+        reasons: string[];
+    };
+}
+export interface Receipt {
+    id: string;
+    runId: string;
+    targetId: string;
+    command: string;
+    cwd: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    aborted: boolean;
+    truncated: boolean;
+    output: string;
+    at: string;
+}
+export interface LedgerState {
+    version: 2;
+    revision: number;
+    heads: Record<string, HeadRecord>;
+    runs: Record<string, StoredRun>;
+    receipts: Record<string, Receipt>;
+    legacy?: unknown;
+    evaluations?: {
+        cases: Record<string, unknown>;
+        results: Record<string, unknown>;
+    };
+}
+export declare function stateDirectory(root: string, stateDir: string): string;
+export declare class Ledger {
+    private readonly root;
+    readonly directory: string;
+    private readonly file;
+    private state;
+    constructor(root: string, stateDir: string);
+    private read;
+    private locked;
+    private write;
+    transaction<T>(work: (state: LedgerState) => T): T;
+    save(): void;
+    event(type: string, payload: Record<string, unknown>): void;
+    snapshot(): LedgerState;
+    head(head: string): HeadRecord | undefined;
+    ensureHead(head: string, mode: Mode): HeadRecord;
+    beginRound(head: string, mode: Mode): HeadRecord;
+    remember(record: HeadRecord, finding: LedgerFinding): void;
+    respond(head: string, fingerprint: string, disposition: Disposition, note?: string): LedgerFinding | undefined;
+    status(head?: string): {
+        heads: number;
+        round: number;
+        posted: number;
+        byDisposition: Record<string, number>;
+        noiseRate: number | null;
+        repeatRate: number | null;
+        unverified: number;
+        dropped: number;
+        topKinds: {
+            kind: string;
+            count: number;
+        }[];
+        runs: {
+            id: string;
+            targetId: string;
+            status: RunStatus;
+            stage: "find" | "verify" | "arbiter" | "done";
+            calls: number;
+            errors: string[];
+        }[];
+        legacyPresent: boolean;
+    };
+}