@anureo/code-review 0.0.0-stage → 0.3.0

package/src/cli.js

@@ -0,0 +1,157 @@
+import { parseArgs } from 'node:util';
+import { defaultAngles } from "./angles.js";
+import { createReviewClient, fixPermissionMode, reviewHarnesses } from "./client.js";
+import { formatFailure } from "./errors.js";
+import { formatReport } from "./report.js";
+import { DEFAULT_WORKFLOW_DIRECTORY, resolveReviewDirectory } from "./paths.js";
+import { reviewCode } from "./review.js";
+import { DEFAULT_REVIEW_CONCURRENCY, validatePositiveInteger, validateModuleIds, hasDuplicateIds } from "./options.js";
+/** Run the CLI with arguments following the executable name. The bin entry point awaits the result
+ * and assigns it to process.exitCode. Returns 0 for help or a complete review without findings,
+ * 1 for a complete review with findings, and 2 for incomplete coverage or reported errors.
+ * Help and CLI parsing failures acquire no backend. When a report is available, it is written
+ * before client disposal. The command awaits disposal before settling once a client is acquired.
+ * A failure to emit the final diagnostic can reject.
+ */
+export async function runCli(args, dependencies = {}) {
+    const runtime = {
+        ...dependencies,
+        env: dependencies.env ?? process.env,
+        stdout: dependencies.stdout ?? (text => { process.stdout.write(text); }),
+        stderr: dependencies.stderr ?? (text => { process.stderr.write(text); }),
+    };
+    try {
+        const command = parseCommand(args);
+        if (command.kind === 'help') {
+            runtime.stdout(help);
+            return 0;
+        }
+        return await executeReviewCommand(command, runtime);
+    }
+    catch (cause) {
+        runtime.stderr(`anureo-review: ${formatFailure(cause)}\n`);
+        return 2;
+    }
+}
+const help = `Usage: anureo-review [directory] [options]
+
+Analyze modules, then review modules and their angles concurrently.
+Defaults to the current directory and all built-in angles.
+Requires Bun and configured authentication for the selected harness.
+Pi runs in-process; CLI-based harnesses require their corresponding executable.
+
+Options:
+  --harness <id>          Review backend (default: codex): ${reviewHarnesses.join(', ')}
+  --model <name>          Model override (defaults to CODEX_MODEL or backend default)
+  --concurrency <number>  Maximum simultaneous review and fix agents (default: ${DEFAULT_REVIEW_CONCURRENCY})
+  --max-modules <number>  Review at most this many modules, in plan order
+  --module <id>          Select an analyzed module ID (repeatable)
+  --angle <id>           Select a built-in angle (repeatable): ${defaultAngles.map(angle => angle.id).join(', ')}
+  --focus <text>          Additional focus for module analysis and review
+  --fix                  Run each agent in a temporary Git worktree, apply
+                         validated edits, then re-review the selected scope.
+                         Existing uncommitted changes are included.
+  --workflow-dir <path>   Durable run storage (default: <directory>/${DEFAULT_WORKFLOW_DIRECTORY})
+  --json                 Print the structured report as JSON
+  --help, -h             Show this help
+
+Exit codes: 0 complete without findings, 1 complete with findings, 2 failed/incomplete.
+`;
+/** Parse CLI syntax and validate flags that can be checked before runCli acquires a client.
+ * Throws flag-specific errors. Help bypasses semantic checks after strict syntax parsing.
+ * reviewCode checks module selection against the analyzed plan. */
+function parseCommand(args) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, strict: true, options: {
+            help: { type: 'boolean', short: 'h' }, json: { type: 'boolean' }, fix: { type: 'boolean' },
+            model: { type: 'string' }, concurrency: { type: 'string' }, focus: { type: 'string' },
+            harness: { type: 'string' },
+            'workflow-dir': { type: 'string' },
+            'max-modules': { type: 'string' },
+            module: { type: 'string', multiple: true }, angle: { type: 'string', multiple: true },
+        } });
+    if (values.help)
+        return { kind: 'help' };
+    if (positionals.length > 1)
+        throw new Error('Expected at most one review directory');
+    const harness = values.harness === undefined ? 'codex' : reviewHarnesses.find(id => id === values.harness);
+    if (!harness)
+        throw new Error(`Unknown harness: ${values.harness}. Available: ${reviewHarnesses.join(', ')}`);
+    const concurrency = values.concurrency === undefined ? DEFAULT_REVIEW_CONCURRENCY : Number(values.concurrency);
+    validatePositiveInteger(concurrency, '--concurrency');
+    const maxModules = values['max-modules'] === undefined ? undefined : Number(values['max-modules']);
+    if (maxModules !== undefined)
+        validatePositiveInteger(maxModules, '--max-modules');
+    validateModuleIds(values.module, '--module requires unique nonempty module ids');
+    const angles = resolveSelectedAngles(values.angle);
+    return {
+        kind: 'review', directory: positionals[0], harness, concurrency, maxModules, angles,
+        moduleIds: values.module, focus: values.focus, model: values.model,
+        fix: values.fix, json: values.json, workflowDirectory: values['workflow-dir'],
+    };
+}
+/** Resolve built-in angle IDs in flag order for parseCommand. Omission lets reviewCode pick its
+ * defaults. Duplicate flags take precedence over unknown IDs in the diagnostic. */
+function resolveSelectedAngles(ids) {
+    if (ids && hasDuplicateIds(ids))
+        throw new Error('--angle requires unique angle ids');
+    return ids?.map(id => {
+        const angle = defaultAngles.find(angle => angle.id === id);
+        if (!angle)
+            throw new Error(`Unknown angle: ${id}. Available: ${defaultAngles.map(angle => angle.id).join(', ')}`);
+        return angle;
+    });
+}
+/** Acquire a client only after directory preflight and retain ownership through report output.
+ * runCli receives failures after disposal settles: a cleanup failure rejects an otherwise successful
+ * execution, while a review/output failure remains primary if the separate cleanup diagnostic succeeds.
+ * A throwing cleanup diagnostic can replace the original failure. */
+async function executeReviewCommand(command, runtime) {
+    const cwd = await resolveReviewDirectory(command.directory ?? runtime.cwd ?? process.cwd());
+    const client = await (runtime.createClient ?? createReviewClient)(cwd, command.harness);
+    let executionFailed = false;
+    try {
+        return await reviewAndPrintReport({ command, runtime, cwd, client });
+    }
+    catch (cause) {
+        executionFailed = true;
+        throw cause;
+    }
+    finally {
+        try {
+            await client.dispose();
+        }
+        catch (cause) {
+            if (!executionFailed)
+                throw cause;
+            runtime.stderr(`anureo-review: client cleanup failed: ${formatFailure(cause)}\n`);
+        }
+    }
+}
+/** Await reviewCode, synchronously print its report and derive the CLI exit code. Incomplete
+ * coverage takes precedence over finding count, which can include post-fix verification.
+ * Review rejections and output throws propagate to executeReviewCommand, which owns client cleanup.
+ * reviewCode invokes the progress observer synchronously and collects its exceptions in the report. */
+async function reviewAndPrintReport({ command, runtime, cwd, client }) {
+    const report = await reviewCode({
+        client, cwd, concurrency: command.concurrency, focus: command.focus, model: command.model ?? runtime.env.CODEX_MODEL,
+        angles: command.angles, moduleIds: command.moduleIds, maxModules: command.maxModules, fix: command.fix,
+        ...(command.fix ? { fixPermissionMode: fixPermissionMode(command.harness) } : {}),
+        workflowDirectory: command.workflowDirectory,
+        onProgress: event => runtime.stderr(formatProgress(event)),
+    });
+    runtime.stdout(command.json ? `${JSON.stringify(report, null, 2)}\n` : formatReport(report));
+    if (report.status === 'incomplete')
+        return 2;
+    return report.findingCount > 0 ? 1 : 0;
+}
+/** Render a progress event as one stderr line. reviewAndPrintReport registers the observer with
+ * reviewCode, so progress stays out of the report stream even in JSON mode. */
+function formatProgress(event) {
+    if (event.stage === 'workflow')
+        return `[workflow] ${event.runId} (${event.directory})\n`;
+    if (event.stage === 'analysis')
+        return `[analysis] ${event.status}\n`;
+    if (event.stage === 'fix')
+        return `[fix/${event.moduleId}] ${event.status}\n`;
+    return `[${event.stage === 'verification' ? 'verification/' : ''}${event.moduleId}/${event.angleId}] ${event.status}\n`;
+}

package/src/client.d.ts

@@ -0,0 +1,18 @@
+import { type Client, type HarnessAdapter } from '@anureo/sdk';
+/** Internal backend IDs accepted by the CLI, in help and unknown-harness diagnostic order. */
+export declare const reviewHarnesses: readonly ["codex", "claude", "hermes", "pi"];
+/** CLI backend selection shared by client construction and fix-session permissions. */
+export type ReviewHarness = (typeof reviewHarnesses)[number];
+/** Initialize the CLI client. executeReviewCommand awaits it before running the review and owns
+ * disposal. Direct source callers must also await disposal. Adapter construction and initialization
+ * failures reject.
+ *
+ * Defaults to Codex, which uses cwd for its initial process launch. An override replaces the
+ * built-in adapter. Keep harness aligned with that adapter because the SDK uses it in session bindings.
+ * The SDK handles approval requests using the narrowest advertised allow option and attempts
+ * cancellation when none is offered. */
+export declare function createReviewClient(cwd: string, harness?: ReviewHarness, override?: HarnessAdapter): Promise<Client>;
+/** Select the CLI fix agent's session permission mode for source edits and project checks.
+ * reviewAndPrintReport passes this to reviewCode only for --fix; undefined (Hermes/Pi) leaves
+ * fix sessions at backend defaults. Internal CLI policy. */
+export declare function fixPermissionMode(harness: ReviewHarness): string | undefined;

package/src/client.js

@@ -0,0 +1,54 @@
+// CLI-owned backend construction and fix-session permission policy.
+import { createClaudeAdapter } from '@anureo/adapter-claude';
+import { createCodexAdapter } from '@anureo/adapter-codex';
+import { createHermesAdapter } from '@anureo/adapter-hermes';
+import { createPiAdapter } from '@anureo/adapter-pi';
+import { approveWithNarrowestScope, createClient } from '@anureo/sdk';
+/** Internal backend IDs accepted by the CLI, in help and unknown-harness diagnostic order. */
+export const reviewHarnesses = ['codex', 'claude', 'hermes', 'pi'];
+/** Initialize the CLI client. executeReviewCommand awaits it before running the review and owns
+ * disposal. Direct source callers must also await disposal. Adapter construction and initialization
+ * failures reject.
+ *
+ * Defaults to Codex, which uses cwd for its initial process launch. An override replaces the
+ * built-in adapter. Keep harness aligned with that adapter because the SDK uses it in session bindings.
+ * The SDK handles approval requests using the narrowest advertised allow option and attempts
+ * cancellation when none is offered. */
+export async function createReviewClient(cwd, harness = 'codex', override) {
+    return createClient({
+        adapter: override ?? harnessConfig[harness].adapter(cwd),
+        identity: { adapterId: harness, runtimeConfigId: 'code-review' },
+        interactions: {
+            approval: approveWithNarrowestScope,
+        },
+    });
+}
+/** Select the CLI fix agent's session permission mode for source edits and project checks.
+ * reviewAndPrintReport passes this to reviewCode only for --fix; undefined (Hermes/Pi) leaves
+ * fix sessions at backend defaults. Internal CLI policy. */
+export function fixPermissionMode(harness) {
+    return harnessConfig[harness].fix;
+}
+/** Include a configured executable for Claude or Hermes. Trim only for the presence check so the
+ * adapter receives the exact configured path. An absent or blank override leaves adapter defaults in effect. */
+function optionalCommand(name) {
+    return process.env[name]?.trim() ? { command: process.env[name] } : {};
+}
+/** Pair each backend's adapter factory and fix permissions so additions must supply both.
+ * Factories defer process.env reads until client creation. Codex trims CODEX_BIN;
+ * Claude/Hermes use their raw override only when nonblank, otherwise their adapter defaults. */
+const harnessConfig = {
+    codex: {
+        adapter: (cwd) => createCodexAdapter({ command: process.env.CODEX_BIN?.trim() || 'codex', cwd }),
+        fix: 'agent',
+    },
+    claude: {
+        adapter: () => createClaudeAdapter({ defaultHome: true, env: process.env, ...optionalCommand('CLAUDE_BIN') }),
+        fix: 'bypassPermissions',
+    },
+    hermes: {
+        adapter: () => createHermesAdapter(optionalCommand('HERMES_BIN')),
+        fix: undefined,
+    },
+    pi: { adapter: () => createPiAdapter(), fix: undefined },
+};

package/src/errors.d.ts

@@ -0,0 +1,27 @@
+/** Diagnostic data carried by failed angle and fix outcomes and by progress observer errors.
+ * Inspect the enclosing outcome for coverage. Fatal workflow errors can reject reviewCode. */
+export interface ReviewFailure {
+    /** The cause's Error.message or its string representation. */
+    message: string;
+    /** String code from the cause, or null when none was supplied. */
+    code: string | null;
+    /** True when the cause explicitly reports execution uncertainty. Use FixReport.changedFiles to
+     * identify recorded edits in the original work tree. */
+    outcomeUnknown: boolean;
+    /** Present when validation details contain usable path/code pairs. String paths pass through
+     * unchanged. Copied array paths contain strings or nonnegative safe integers. */
+    issues?: Array<{
+        path: string | Array<string | number>;
+        code: string;
+    }>;
+}
+/** Project a caught or synthesized cause into report data. reviewAngle and failedAngleReview
+ * store it as missing coverage, applyFix returns it with the failed fix, and reviewCode collects
+ * it when onProgress throws. formatFailure uses the same projection for CLI diagnostics.
+ * Reading properties or converting the cause to a string can throw. */
+export declare function reviewFailure(cause: unknown): ReviewFailure;
+/** Return a CLI diagnostic with the message, any nonempty code, and an uncertainty notice when
+ * flagged. runCli writes it to stderr for command failures. executeReviewCommand uses it for a
+ * secondary cleanup failure. Both callers add the prefix and newline. Errors while projecting
+ * the cause propagate to the caller. */
+export declare function formatFailure(cause: unknown): string;

package/src/errors.js

@@ -0,0 +1,44 @@
+/** Project a caught or synthesized cause into report data. reviewAngle and failedAngleReview
+ * store it as missing coverage, applyFix returns it with the failed fix, and reviewCode collects
+ * it when onProgress throws. formatFailure uses the same projection for CLI diagnostics.
+ * Reading properties or converting the cause to a string can throw. */
+export function reviewFailure(cause) {
+    const issues = failureIssues(cause);
+    const metadata = cause && typeof cause === 'object' ? cause : undefined;
+    return {
+        message: cause instanceof Error ? cause.message : String(cause),
+        code: metadata && 'code' in metadata && typeof metadata.code === 'string' ? metadata.code : null,
+        outcomeUnknown: metadata !== undefined && 'outcomeUnknown' in metadata && metadata.outcomeUnknown === true,
+        ...(issues.length > 0 ? { issues } : {}),
+    };
+}
+/** Return a CLI diagnostic with the message, any nonempty code, and an uncertainty notice when
+ * flagged. runCli writes it to stderr for command failures. executeReviewCommand uses it for a
+ * secondary cleanup failure. Both callers add the prefix and newline. Errors while projecting
+ * the cause propagate to the caller. */
+export function formatFailure(cause) {
+    const error = reviewFailure(cause);
+    return `${error.message}${error.code ? ` [${error.code}]` : ''}${error.outcomeUnknown ? ' (execution outcome unknown)' : ''}`;
+}
+/** Keep valid validation paths and codes in source order while omitting issue messages and details.
+ * Copy array paths so the report does not retain the cause's path arrays. */
+function failureIssues(cause) {
+    const details = cause && typeof cause === 'object' && 'details' in cause ? cause.details : undefined;
+    if (!details || typeof details !== 'object' || !('issues' in details) || !Array.isArray(details.issues))
+        return [];
+    const candidates = details.issues;
+    const issues = [];
+    for (const issue of candidates) {
+        if (!issue || typeof issue !== 'object' || typeof issue.code !== 'string' || !issue.code)
+            continue;
+        const path = issue.path;
+        if (!isValidationIssuePath(path))
+            continue;
+        issues.push({ path: typeof path === 'string' ? path : [...path], code: issue.code });
+    }
+    return issues;
+}
+/** Accept SDK string paths and segmented paths with string keys or safe array indices. */
+function isValidationIssuePath(path) {
+    return typeof path === 'string' || (Array.isArray(path) && path.every(part => typeof part === 'string' || (typeof part === 'number' && Number.isSafeInteger(part) && part >= 0)));
+}

package/src/file-state.d.ts

@@ -0,0 +1,13 @@
+/** Observed state used to detect changes and test regular-file eligibility. */
+export interface TreeState {
+    /** Identity of mode and captured content. Null denotes a missing path. */
+    fingerprint: string | null;
+    regular: boolean;
+}
+/** Fingerprint mode plus regular-file bytes or symlink text. ENOENT returns a null fingerprint.
+ * Other filesystem failures reject. captureWorkingTreeBaseline and inspectWorkingTreeChanges
+ * use these states to detect edits, and checkOriginalSources compares the target with its patch
+ * baseline before applying. Callers supply an absolute checkout or scratch root and a
+ * Git-root-relative path. They check parent path resolution where required.
+ */
+export declare function fileState(cwd: string, file: string): Promise<TreeState>;

package/src/file-state.js

@@ -0,0 +1,24 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+/** Fingerprint mode plus regular-file bytes or symlink text. ENOENT returns a null fingerprint.
+ * Other filesystem failures reject. captureWorkingTreeBaseline and inspectWorkingTreeChanges
+ * use these states to detect edits, and checkOriginalSources compares the target with its patch
+ * baseline before applying. Callers supply an absolute checkout or scratch root and a
+ * Git-root-relative path. They check parent path resolution where required.
+ */
+export async function fileState(cwd, file) {
+    const path = resolve(cwd, file);
+    try {
+        const info = await lstat(path);
+        const content = info.isFile() ? await readFile(path) : info.isSymbolicLink() ? await readlink(path) : '';
+        const fingerprint = createHash('sha256').update(String(info.mode)).update('\0').update(content).digest('hex');
+        return { fingerprint, regular: info.isFile() };
+    }
+    catch (cause) {
+        if (cause && typeof cause === 'object' && 'code' in cause && cause.code === 'ENOENT') {
+            return { fingerprint: null, regular: false };
+        }
+        throw cause;
+    }
+}

package/src/fix-patch.d.ts

@@ -0,0 +1,13 @@
+import type { AgentWorktree } from "./worktree.js";
+/** Save regular, Git-root-relative source files under the worktree's scratch directory.
+ * captureFixBaseline awaits these copies before agent dispatch. applyFixPatch uses them for the
+ * diff and original-tree comparison. Copy failures and symlink paths reject.
+ */
+export declare function capturePatchBaseline(checkout: AgentWorktree, files: readonly string[]): Promise<void>;
+/** Apply one binary-capable Git patch for the nonempty list of validated, Git-root-relative
+ * edits supplied by applyFix. Uses the saved baseline to compare original bytes and mode
+ * before applying. Git leaves the original index alone and rejects the patch as a
+ * unit on a context conflict. A mismatched source or Git apply failure rejects as
+ * REVIEW_FIX_CONFLICT. withAgentWorktree owns scratch cleanup.
+ */
+export declare function applyFixPatch(root: string, checkout: AgentWorktree, files: readonly string[]): Promise<void>;

package/src/fix-patch.js

@@ -0,0 +1,86 @@
+// Transfers a validated fix from its checkout to the original work tree.
+import { copyFile, mkdir, realpath, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { HarnessSdkError } from '@anureo/sdk';
+import { fileState } from "./file-state.js";
+import { execGit, GIT_MAX_BUFFER, reviewGit } from "./git.js";
+/** Save regular, Git-root-relative source files under the worktree's scratch directory.
+ * captureFixBaseline awaits these copies before agent dispatch. applyFixPatch uses them for the
+ * diff and original-tree comparison. Copy failures and symlink paths reject.
+ */
+export function capturePatchBaseline(checkout, files) {
+    return copyPatchFiles(checkout, 'before', files);
+}
+/** Apply one binary-capable Git patch for the nonempty list of validated, Git-root-relative
+ * edits supplied by applyFix. Uses the saved baseline to compare original bytes and mode
+ * before applying. Git leaves the original index alone and rejects the patch as a
+ * unit on a context conflict. A mismatched source or Git apply failure rejects as
+ * REVIEW_FIX_CONFLICT. withAgentWorktree owns scratch cleanup.
+ */
+export async function applyFixPatch(root, checkout, files) {
+    await copyPatchFiles(checkout, 'after', files);
+    const patchPath = await writeFixPatch(checkout.scratch, files);
+    await checkOriginalSources(root, resolve(checkout.scratch, 'before'), files);
+    try {
+        await reviewGit(root, 'apply', '-p1', '--whitespace=nowarn', patchPath);
+    }
+    catch (cause) {
+        throw new HarnessSdkError('REVIEW_FIX_CONFLICT', cause instanceof Error ? cause.message : String(cause));
+    }
+}
+/** Copy Git-relative sources to the requested side of the patch, rejecting symlink paths
+ * before copying each file. Partial copies stay in scratch for withAgentWorktree's cleanup.
+ */
+async function copyPatchFiles(checkout, phase, files) {
+    const destinationRoot = resolve(checkout.scratch, phase);
+    for (const file of files) {
+        const source = resolve(checkout.root, file);
+        if (await realpath(source) !== source) {
+            throw new HarnessSdkError('REVIEW_FIX_SCOPE', `Fix source traverses a symlink: ${file}`);
+        }
+        const destination = resolve(destinationRoot, file);
+        await mkdir(dirname(destination), { recursive: true });
+        await copyFile(source, destination);
+    }
+}
+/** Write the combined patch from staged before and after files. Read, diff and write
+ * failures reject before applyFixPatch checks or writes original source files.
+ */
+async function writeFixPatch(scratch, files) {
+    const patches = [];
+    for (const file of files)
+        patches.push(await diffFile(scratch, file));
+    const patchPath = resolve(scratch, 'fix.patch');
+    await writeFile(patchPath, Buffer.concat(patches));
+    return patchPath;
+}
+/** Check every original target before applying any part of the patch. Reject missing paths,
+ * symlink resolution, nonregular targets and fingerprint mismatches against the scratch baseline.
+ */
+async function checkOriginalSources(root, before, files) {
+    for (const file of files) {
+        const path = resolve(root, file);
+        const originalPath = await realpath(path).catch(() => null);
+        const current = originalPath === path ? await fileState(root, file) : null;
+        const prior = await fileState(before, file);
+        if (!current?.regular || current.fingerprint !== prior.fingerprint) {
+            throw new HarnessSdkError('REVIEW_FIX_CONFLICT', `Source changed during the fix: ${file}`);
+        }
+    }
+}
+/** Return the binary-capable patch bytes for one file. Git diff status 1 also carries a
+ * successful patch on stdout. Other process failures reject.
+ */
+async function diffFile(cwd, file) {
+    try {
+        const { stdout } = await execGit('git', ['diff', '--no-index', '--no-prefix', '--no-ext-diff', '--no-textconv',
+            '--binary', '--', 'before/' + file, 'after/' + file], { cwd, encoding: 'buffer', maxBuffer: GIT_MAX_BUFFER });
+        return stdout;
+    }
+    catch (cause) {
+        if (cause && typeof cause === 'object' && 'code' in cause && cause.code === 1
+            && 'stdout' in cause && Buffer.isBuffer(cause.stdout))
+            return cause.stdout;
+        throw cause;
+    }
+}

package/src/fix-tree.d.ts

@@ -0,0 +1,25 @@
+import { type TreeState } from "./file-state.js";
+/** Capture selected files and existing Git-visible changes in the isolated checkout before
+ * agent dispatch. captureFixBaseline retains this snapshot for the post-agent comparison.
+ * root is the Git root and allowed paths are relative to it. Git and file-read failures reject.
+ */
+export declare function captureWorkingTreeBaseline(root: string, allowed: readonly string[]): Promise<WorkingTreeBaseline>;
+/** Compare baseline paths and current Git-visible changes after agent settlement. Including
+ * baseline paths detects edits that restore a dirty file to its committed contents. Return
+ * sorted Git-root-relative paths for selected files that were and remain regular, plus
+ * diagnostics for other detected changes. checkFixChanges rejects those diagnostics before
+ * integration. Git and file-read failures reject here.
+ */
+export declare function inspectWorkingTreeChanges(baseline: WorkingTreeBaseline): Promise<{
+    changedFiles: string[];
+    violations: string[];
+}>;
+/** Isolated checkout snapshot from before agent execution. All paths except root are
+ * Git-root-relative. states includes the allowed paths even when Git status is clean.
+ */
+interface WorkingTreeBaseline {
+    root: string;
+    allowed: readonly string[];
+    states: ReadonlyMap<string, TreeState>;
+}
+export {};

package/src/fix-tree.js

@@ -0,0 +1,43 @@
+// Reconciles fix edits against the isolated checkout's pre-agent state.
+import { fileState } from "./file-state.js";
+import { reviewGit } from "./git.js";
+/** Capture selected files and existing Git-visible changes in the isolated checkout before
+ * agent dispatch. captureFixBaseline retains this snapshot for the post-agent comparison.
+ * root is the Git root and allowed paths are relative to it. Git and file-read failures reject.
+ */
+export async function captureWorkingTreeBaseline(root, allowed) {
+    const files = new Set([...allowed, ...(await treeEntries(root)).keys()]);
+    const states = new Map(await Promise.all([...files].map(async (file) => [file, await fileState(root, file)])));
+    return { root, allowed, states };
+}
+/** Compare baseline paths and current Git-visible changes after agent settlement. Including
+ * baseline paths detects edits that restore a dirty file to its committed contents. Return
+ * sorted Git-root-relative paths for selected files that were and remain regular, plus
+ * diagnostics for other detected changes. checkFixChanges rejects those diagnostics before
+ * integration. Git and file-read failures reject here.
+ */
+export async function inspectWorkingTreeChanges(baseline) {
+    const { root, allowed, states: before } = baseline;
+    const scope = new Set(allowed);
+    const changedFiles = [];
+    const violations = [];
+    const entries = await treeEntries(root);
+    for (const file of new Set([...before.keys(), ...entries.keys()])) {
+        const previous = before.get(file);
+        const current = await fileState(root, file);
+        if (current.fingerprint === (previous?.fingerprint ?? null))
+            continue;
+        if (scope.has(file) && previous?.regular && current.regular)
+            changedFiles.push(file);
+        else
+            violations.push(`${entries.get(file)?.trim() || 'modified'} ${file}`);
+    }
+    return { changedFiles: changedFiles.sort(), violations };
+}
+/** Map changed Git paths to status codes for scope discovery and diagnostics. Disable rename
+ * detection so additions and removals can be compared independently. Git failures reject.
+ */
+async function treeEntries(root) {
+    const entries = await reviewGit(root, 'status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames');
+    return new Map(entries.split('\0').filter(Boolean).map(entry => [entry.slice(3), entry.slice(0, 2)]));
+}

package/src/fix.d.ts

@@ -0,0 +1,37 @@
+import { type Client } from '@anureo/sdk';
+import type { FixReport, ModuleReview } from "./results.js";
+export type { FixReport } from "./results.js";
+/** Execute a fix for validated module reviews. Incomplete reviews are skipped and an empty
+ * findings list needs no fix. Eligible runs await worktree cleanup and report actual edits
+ * relative to the review directory. A failed report can include edits if integration finished
+ * before cleanup or terminal progress reporting failed.
+ *
+ * createFixRunner calls this with writer and agent capacity held. It uses failed reports or
+ * rejections to stop later writers. The coordinator owns final verification and the client
+ * remains caller-owned. Workflow-level fatal agent failures can still reject the enclosing run.
+ */
+export declare function fixFindings(options: FixOptions): Promise<FixReport>;
+/** Inputs for a single writer run. */
+interface FixOptions {
+    /** Source fingerprint embedded in the fix prompt. Null omits provenance text. */
+    sourceVersion: string | null;
+    /** Borrowed client, kept usable until the fix settles. */
+    client: Client;
+    /** Canonical absolute review directory. The module files must already be validated relative to it. */
+    cwd: string;
+    /** Canonical Git root. Omission resolves it from cwd when a fix is needed. */
+    repositoryRoot?: string;
+    /** Absolute workflow storage directory, excluded when populating the isolated checkout. */
+    directory: string;
+    modules: readonly ModuleReview[];
+    /** Omission leaves model selection to the session/backend. */
+    model?: string;
+    /** Forwarded to session creation when supplied. */
+    permissionMode?: string;
+    /** Synchronous observer forwarded by createFixRunner to reviewCode's protected progress
+     * observer. Both early exits emit 'skipped'. For direct callers, exceptions before setup
+     * or during 'failed' reject. Exceptions after reconciliation produce a failed report
+     * if the subsequent 'failed' notification succeeds.
+     */
+    onProgress?: (status: 'started' | 'completed' | 'failed' | 'skipped') => void;
+}