@orion-agents/orion-code 0.3.27 → 0.3.29

package/dist/services/code-review/runner.js

@@ -0,0 +1,368 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REVIEW_BUDGETS = void 0;
+exports.createProcessGitRunner = createProcessGitRunner;
+exports.computeReviewRulesDigest = computeReviewRulesDigest;
+exports.buildReviewSystemPrompt = buildReviewSystemPrompt;
+exports.runCodeReview = runCodeReview;
+/**
+ * v0.3.28 — the bounded single-pass code-review runner (docs/plan/
+ * v0.3.28-plan.md S2). Wires the frozen PR0 contract and the PR1 snapshot
+ * reader into an executable review: a typed selector is resolved to a frozen
+ * Git snapshot, the snapshot material is assembled into a bounded prompt, one
+ * model completion is requested, and the output is validated against the
+ * contract before a digest-verifiable `CodeReviewResultV1` receipt is built.
+ *
+ * Read-only posture: the runner performs no writes inside the reviewed
+ * repository — git runs read-only with argument arrays, working files are read
+ * through the contained reader, and the model receives the frozen material
+ * inline instead of an open tool surface. `REVIEW_WORKFLOW_CONSTRAINTS` is
+ * bound into the receipt's rules digest so receipts record the policy that
+ * governed the run.
+ */
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const crypto_2 = require("crypto");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const contract_1 = require("./contract");
+Object.defineProperty(exports, "DEFAULT_REVIEW_BUDGETS", { enumerable: true, get: function () { return contract_1.DEFAULT_REVIEW_BUDGETS; } });
+const constraints_1 = require("./constraints");
+const snapshot_1 = require("./snapshot");
+function sha256(value) {
+    return (0, crypto_1.createHash)('sha256').update(value, 'utf8').digest('hex');
+}
+/** Production git runner: argument arrays, no shell, read-only profile is the
+ *  caller's responsibility (the runner only issues read commands). */
+function createProcessGitRunner(cwd) {
+    return async (args) => new Promise((resolvePromise, reject) => {
+        (0, child_process_1.execFile)('git', args, { cwd, maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new Error(`git ${args.join(' ')} failed: ${stderr || error.message}`));
+                return;
+            }
+            resolvePromise(stdout);
+        });
+    });
+}
+/** Rules provenance: AGENTS.md contents from cwd up to the filesystem root
+ *  (bounded to 16 levels), combined with the frozen read-only constraints
+ *  digest. Changing the rules or the policy invalidates applicability. */
+async function computeReviewRulesDigest(cwd) {
+    const chunks = [];
+    let current = (0, path_1.resolve)(cwd);
+    for (let depth = 0; depth < 16; depth += 1) {
+        try {
+            const content = await (0, promises_1.readFile)((0, path_1.join)(current, 'AGENTS.md'), 'utf8');
+            chunks.push(`${current}::${content}`);
+        }
+        catch {
+            // No AGENTS.md at this level — fine.
+        }
+        const parent = (0, path_1.dirname)(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return sha256(`${constraints_1.REVIEW_WORKFLOW_CONSTRAINTS.constraintsDigest}\n${chunks.join('\n---\n')}`);
+}
+/** The frozen review instruction set assembled for the model. */
+function buildReviewSystemPrompt(rulesDigest) {
+    return [
+        'You are a strict code reviewer operating inside Orion Code.',
+        'You receive a frozen snapshot of the changes under review.',
+        'Report only defects introduced or worsened by these changes, with concrete evidence.',
+        'Exclude pure style opinions, speculation without evidence, and duplicates.',
+        'Never suggest running commands, editing files, or any other action: this review is read-only.',
+        'Respond with a single JSON object of the shape {"findings":[...]} and nothing else.',
+        'Each finding object needs exactly these fields:',
+        '  findingId: 8-64 hex characters, stable within this response;',
+        '  priority: "P0" (blocks usage, proven) | "P1" | "P2" | "P3";',
+        '  title: short imperative summary;',
+        '  trigger: the concrete condition under which the defect manifests;',
+        '  impact: what breaks and for whom;',
+        '  fileKey: copy the file key from the snapshot material verbatim;',
+        '  side: "old" for removed/base lines, "new" for added/current lines;',
+        '  startLine, endLine: 1-based inclusive line numbers in that side;',
+        '  evidence: the code excerpt or reasoning that proves the finding.',
+        `Active policy digest: ${constraints_1.REVIEW_WORKFLOW_CONSTRAINTS.constraintsDigest}.`,
+        `Rules digest: ${rulesDigest}.`,
+    ].join('\n');
+}
+/** Assembles the bounded user prompt material from the frozen snapshot plus
+ *  the diff text captured inside the admission window. */
+function buildSnapshotMaterial(snapshot, diffText, budgets) {
+    const sections = [
+        `Snapshot: ${snapshot.snapshotId} (kind=${snapshot.kind}`,
+        snapshot.kind === 'base'
+            ? `base=${snapshot.baseOid} head=${snapshot.headOid})`
+            : 'worktree scope)',
+        `Input snapshot digest: ${snapshot.inputSnapshotDigest}`,
+        'Changed files (fileKey -> path):',
+        ...snapshot.files.map(file => {
+            const sides = file.sides.map(side => side.source).join('+') || 'no-content';
+            return `  ${file.fileKey} ${file.path}${file.oldPath ? ` (from ${file.oldPath})` : ''} [${sides}]`;
+        }),
+        snapshot.skipped.length > 0
+            ? `Skipped by the host: ${snapshot.skipped.map(skip => `${skip.path} (${skip.reason})`).join('; ')}`
+            : 'Skipped by the host: none',
+        'Unified diff:',
+        diffText,
+    ];
+    const text = sections.join('\n');
+    if (Buffer.byteLength(text, 'utf8') <= budgets.maxBodyBytes) {
+        return { text, truncated: false };
+    }
+    const clipped = Buffer.alloc(budgets.maxBodyBytes);
+    const written = Buffer.from(text, 'utf8').subarray(0, budgets.maxBodyBytes);
+    clipped.set(written);
+    return { text: clipped.toString('utf8'), truncated: true };
+}
+function extractFindingsPayload(content) {
+    const trimmed = content.trim();
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const candidate = fenced ? fenced[1].trim() : trimmed;
+    const start = candidate.indexOf('{');
+    const end = candidate.lastIndexOf('}');
+    if (start < 0 || end <= start)
+        return null;
+    try {
+        const parsed = JSON.parse(candidate.slice(start, end + 1));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        const record = parsed;
+        if (!Array.isArray(record.findings))
+            return null;
+        return { findings: record.findings };
+    }
+    catch {
+        return null;
+    }
+}
+function snapshotAuthorizesFile(snapshot, finding) {
+    const file = snapshot.files.find(candidate => candidate.fileKey === finding.fileKey);
+    if (!file)
+        return false;
+    if (finding.side === 'old' && !file.oldPath && file.hunks.every(hunk => hunk.oldLines === 0)) {
+        return false;
+    }
+    const relevant = file.hunks.filter(hunk => finding.side === 'old'
+        ? hunk.oldLines > 0 &&
+            finding.startLine <= hunk.oldStart + hunk.oldLines - 1 &&
+            finding.endLine >= hunk.oldStart
+        : hunk.newLines > 0 &&
+            finding.startLine <= hunk.newStart + hunk.newLines - 1 &&
+            finding.endLine >= hunk.newStart);
+    // A finding whose lines touch no diff hunk is not anchored in the frozen
+    // material; the model must cite the changes under review.
+    return relevant.length > 0;
+}
+/**
+ * Runs one bounded review. Never throws for expected review failures — the
+ * outcome is typed; unexpected internal errors surface as `model_error`.
+ */
+async function runCodeReview(options) {
+    const now = options.now ?? Date.now;
+    const startedAt = now();
+    const budgets = (0, contract_1.resolveReviewBudgets)(options.budgets);
+    if (!budgets.ok)
+        return { ok: false, failure: { kind: 'budget', field: budgets.field } };
+    const aborted = () => options.abortSignal?.aborted === true;
+    if (aborted())
+        return { ok: false, failure: { kind: 'cancelled' } };
+    const runGit = options.runGit ?? createProcessGitRunner(options.cwd);
+    let snapshot;
+    let diffText;
+    try {
+        snapshot = await (0, snapshot_1.captureReviewSnapshot)({
+            root: options.cwd,
+            selector: options.selector,
+            budgets: budgets.budgets,
+            runGit,
+            readWorktreeFile: (0, snapshot_1.createContainedWorktreeReader)(options.cwd),
+        });
+        options.onSnapshotCaptured?.(snapshot);
+        if (aborted())
+            return { ok: false, failure: { kind: 'cancelled' } };
+        // The exact same frozen diff arguments the snapshot used, against the
+        // OIDs the snapshot resolved; captured once inside the admission window
+        // and never re-read afterwards.
+        diffText = await runGit((0, snapshot_1.reviewUnifiedDiffArgs)(options.selector, {
+            baseOid: snapshot.baseOid,
+            headOid: snapshot.headOid,
+        }));
+    }
+    catch (error) {
+        const code = error instanceof snapshot_1.ReviewSnapshotError ? error.code : 'not_a_repository';
+        return {
+            ok: false,
+            failure: {
+                kind: 'snapshot',
+                code,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+    const rulesDigest = await computeReviewRulesDigest(options.cwd);
+    const limits = [];
+    const budgetExhausted = [];
+    if (snapshot.files.length === 0) {
+        limits.push('empty_scope_no_changes');
+        const endedAt = now();
+        const coverage = {
+            inspectedFiles: [],
+            inspectedRanges: [],
+            skipped: [],
+            truncated: false,
+            budgetExhausted: [],
+        };
+        const base = {
+            schemaVersion: 1,
+            reviewId: `cr-${(0, crypto_2.randomBytes)(8).toString('hex')}`,
+            workspaceIdentity: options.identity.workspaceIdentity,
+            sessionId: options.identity.sessionId,
+            threadId: options.identity.threadId,
+            turnId: options.identity.turnId,
+            requestedSelector: options.selector,
+            resolvedTarget: {
+                kind: snapshot.kind,
+                ...(snapshot.baseOid ? { baseOid: snapshot.baseOid } : {}),
+                ...(snapshot.headOid ? { headOid: snapshot.headOid } : {}),
+                snapshotId: snapshot.snapshotId,
+            },
+            inputSnapshotDigest: snapshot.inputSnapshotDigest,
+            rulesDigest,
+            state: 'completed',
+            conclusion: 'no_findings',
+            findings: [],
+            invalidFindingCount: 0,
+            coverage,
+            coverageAssertion: { complete: true },
+            limits,
+            model: { provider: 'none', model: 'none' },
+            usage: { inputTokens: 0, outputTokens: 0 },
+            startedAt,
+            endedAt,
+        };
+        return {
+            ok: true,
+            result: Object.freeze({ ...base, receiptDigest: (0, contract_1.computeReceiptDigest)(base) }),
+        };
+    }
+    const material = buildSnapshotMaterial(snapshot, diffText, budgets.budgets);
+    if (material.truncated) {
+        budgetExhausted.push('maxBodyBytes');
+        limits.push('prompt_material_truncated');
+    }
+    if (aborted())
+        return { ok: false, failure: { kind: 'cancelled' } };
+    let completion;
+    try {
+        completion = await options.adapter.complete([
+            { role: 'system', content: buildReviewSystemPrompt(rulesDigest) },
+            { role: 'user', content: material.text },
+        ]);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failure: {
+                kind: 'model_error',
+                message: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+    const durationExceeded = now() - startedAt > budgets.budgets.maxDurationMs;
+    if (durationExceeded)
+        budgetExhausted.push('maxDurationMs');
+    const payload = extractFindingsPayload(completion.content);
+    if (!payload) {
+        return {
+            ok: false,
+            failure: {
+                kind: 'unparsable_output',
+                message: 'The model response did not contain a {"findings":[...]} JSON object.',
+            },
+        };
+    }
+    const validFindings = [];
+    let invalidFindingCount = 0;
+    for (const raw of payload.findings) {
+        const validated = (0, contract_1.validateReviewFinding)(raw);
+        if (!validated.valid) {
+            invalidFindingCount += 1;
+            continue;
+        }
+        if (validFindings.length >= budgets.budgets.maxFindings) {
+            invalidFindingCount += 1;
+            budgetExhausted.push('maxFindings');
+            continue;
+        }
+        if (!snapshotAuthorizesFile(snapshot, validated.finding)) {
+            invalidFindingCount += 1;
+            continue;
+        }
+        validFindings.push(validated.finding);
+    }
+    const truncated = material.truncated || budgetExhausted.includes('maxFindings');
+    const coverage = {
+        inspectedFiles: snapshot.files.map(file => file.path),
+        inspectedRanges: [],
+        skipped: snapshot.skipped.map(skip => ({
+            fileKey: skip.path,
+            reason: skip.reason,
+            ...(skip.detail ? { detail: skip.detail } : {}),
+        })),
+        truncated,
+        budgetExhausted: [...new Set(budgetExhausted)],
+    };
+    const coverageComplete = snapshot.skipped.length === 0 && !truncated && !durationExceeded && !material.truncated;
+    let state = 'completed';
+    if (aborted())
+        return { ok: false, failure: { kind: 'cancelled' } };
+    if (truncated || durationExceeded || snapshot.skipped.length > 0)
+        state = 'partial';
+    const conclusion = (0, contract_1.resolveReviewConclusion)({
+        state,
+        validFindingCount: validFindings.length,
+        invalidFindingCount,
+        coverageComplete,
+    });
+    const base = {
+        schemaVersion: 1,
+        reviewId: `cr-${(0, crypto_2.randomBytes)(8).toString('hex')}`,
+        workspaceIdentity: options.identity.workspaceIdentity,
+        sessionId: options.identity.sessionId,
+        threadId: options.identity.threadId,
+        turnId: options.identity.turnId,
+        requestedSelector: options.selector,
+        resolvedTarget: {
+            kind: snapshot.kind,
+            ...(snapshot.baseOid ? { baseOid: snapshot.baseOid } : {}),
+            ...(snapshot.headOid ? { headOid: snapshot.headOid } : {}),
+            snapshotId: snapshot.snapshotId,
+        },
+        inputSnapshotDigest: snapshot.inputSnapshotDigest,
+        rulesDigest,
+        state,
+        conclusion,
+        findings: Object.freeze(validFindings),
+        invalidFindingCount,
+        coverage,
+        coverageAssertion: { complete: coverageComplete },
+        limits,
+        model: { provider: 'orion-llm', model: completion.model },
+        usage: {
+            inputTokens: completion.usage?.inputTokens ?? 0,
+            outputTokens: completion.usage?.outputTokens ?? 0,
+        },
+        startedAt,
+        endedAt: now(),
+    };
+    const result = Object.freeze({
+        ...base,
+        receiptDigest: (0, contract_1.computeReceiptDigest)(base),
+    });
+    return { ok: true, result };
+}
+//# sourceMappingURL=runner.js.map

package/dist/services/code-review/selector.d.ts

@@ -0,0 +1,24 @@
+/**
+ * v0.3.28 — typed `/review` selector parsing (docs/plan/v0.3.28-plan.md S1).
+ *
+ * Slash arguments are parsed once into the frozen `ReviewSelectorV1` contract
+ * from PR0. Unknown arguments produce a typed usage error instead of falling
+ * back to an ordinary chat turn (v0.3.27 plan §3.1: "不能当成分支、路径或任意
+ * 普通聊天悄悄继续").
+ */
+import type { ReviewSelectorV1 } from './contract';
+export type ReviewSelectorParseResult = {
+    readonly ok: true;
+    readonly selector: ReviewSelectorV1;
+} | {
+    readonly ok: false;
+    readonly usage: string;
+};
+export declare const REVIEW_USAGE_TEXT: string;
+/**
+ * Parses `/review` arguments. Tokens: `all` alias, `--base <ref>` (once),
+ * `--path <path>` (repeatable, also `--path=<path>`), a single bare relative
+ * path (back-compat path filter). Anything else is a usage error.
+ */
+export declare function parseReviewSelector(rawArgs: string): ReviewSelectorParseResult;
+//# sourceMappingURL=selector.d.ts.map

package/dist/services/code-review/selector.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REVIEW_USAGE_TEXT = void 0;
+exports.parseReviewSelector = parseReviewSelector;
+exports.REVIEW_USAGE_TEXT = [
+    'Usage: /review [all | --base <ref>] [--path <path>]...',
+    '  /review                    Review the current worktree (staged + unstaged + untracked)',
+    '  /review all                Alias for the current worktree',
+    '  /review --base main        Review committed changes merge-base(main, HEAD)..HEAD',
+    '  /review --path src/foo.ts  Restrict the review to a path (repeatable)',
+].join('\n');
+function ok(selector) {
+    return { ok: true, selector: Object.freeze({ ...selector }) };
+}
+function usageError(reason) {
+    return { ok: false, usage: `${reason}\n\n${exports.REVIEW_USAGE_TEXT}` };
+}
+function looksLikeRelativePath(value) {
+    return (value.length > 0 &&
+        !value.startsWith('/') &&
+        !value.startsWith('-') &&
+        !value.includes('\\') &&
+        value.split('/').every(segment => segment && segment !== '.' && segment !== '..'));
+}
+/**
+ * Parses `/review` arguments. Tokens: `all` alias, `--base <ref>` (once),
+ * `--path <path>` (repeatable, also `--path=<path>`), a single bare relative
+ * path (back-compat path filter). Anything else is a usage error.
+ */
+function parseReviewSelector(rawArgs) {
+    const tokens = rawArgs
+        .trim()
+        .split(/\s+/)
+        .filter(token => token.length > 0);
+    let base = null;
+    const paths = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token === 'all') {
+            if (tokens.length !== 1) {
+                return usageError('`all` cannot be combined with other arguments.');
+            }
+            return ok({ kind: 'worktree' });
+        }
+        if (token === '--base' || token.startsWith('--base=')) {
+            if (base !== null)
+                return usageError('--base may only be given once.');
+            const value = token.startsWith('--base=') ? token.slice('--base='.length) : tokens[index + 1];
+            if (!value)
+                return usageError('--base requires a ref argument.');
+            if (token === '--base')
+                index += 1;
+            base = value;
+            continue;
+        }
+        if (token === '--path' || token.startsWith('--path=')) {
+            const value = token.startsWith('--path=') ? token.slice('--path='.length) : tokens[index + 1];
+            if (!value)
+                return usageError('--path requires a path argument.');
+            if (token === '--path')
+                index += 1;
+            if (!looksLikeRelativePath(value)) {
+                return usageError(`Invalid --path value: ${value}`);
+            }
+            paths.push(value);
+            continue;
+        }
+        if (token.startsWith('-')) {
+            return usageError(`Unknown option: ${token}`);
+        }
+        // Bare argument: back-compat single existing-path filter. Multiple bare
+        // arguments are ambiguous and rejected rather than guessed.
+        if (paths.length > 0 || base !== null) {
+            return usageError(`Unexpected argument: ${token}`);
+        }
+        if (!looksLikeRelativePath(token)) {
+            return usageError(`Invalid path argument: ${token}`);
+        }
+        paths.push(token);
+    }
+    if (base !== null) {
+        return ok(paths.length > 0 ? { kind: 'base', ref: base, paths } : { kind: 'base', ref: base });
+    }
+    return ok(paths.length > 0 ? { kind: 'worktree', paths } : { kind: 'worktree' });
+}
+//# sourceMappingURL=selector.js.map

package/dist/services/code-review/snapshot.d.ts

@@ -53,6 +53,13 @@ export interface ReviewSnapshotOptionsV1 {
     readonly readWorktreeFile?: (relativePath: string) => Promise<string | null>;
     readonly snapshotIdPrefix?: string;
 }
+/** The read-only git arguments for the scope's unified diff. Exported so the
+ *  v0.3.28 runner captures the exact same diff the snapshot froze instead of
+ *  re-deriving OIDs after admission. */
+export declare function reviewUnifiedDiffArgs(selector: ReviewSelectorV1, oids: {
+    readonly baseOid: string | null;
+    readonly headOid: string | null;
+}): string[];
 /** Resolves the selector to a frozen snapshot. Every OID and digest in the
  *  returned object was taken at admission time; callers persist the returned
  *  digest as the review's input identity. */

package/dist/services/code-review/snapshot.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReviewSnapshotError = void 0;
+exports.reviewUnifiedDiffArgs = reviewUnifiedDiffArgs;
 exports.captureReviewSnapshot = captureReviewSnapshot;
 exports.createContainedWorktreeReader = createContainedWorktreeReader;
 /**
@@ -107,6 +108,14 @@ function pathMatches(path, requestedPaths) {
         return true;
     return requestedPaths.some(filter => path === filter || path.startsWith(`${filter}/`));
 }
+/** The read-only git arguments for the scope's unified diff. Exported so the
+ *  v0.3.28 runner captures the exact same diff the snapshot froze instead of
+ *  re-deriving OIDs after admission. */
+function reviewUnifiedDiffArgs(selector, oids) {
+    return selector.kind === 'base'
+        ? ['diff', '--no-ext-diff', '--no-textconv', oids.baseOid, oids.headOid]
+        : ['diff', '--no-ext-diff', '--no-textconv', 'HEAD'];
+}
 /** Resolves the selector to a frozen snapshot. Every OID and digest in the
  *  returned object was taken at admission time; callers persist the returned
  *  digest as the review's input identity. */
@@ -138,7 +147,7 @@ async function captureReviewSnapshot(options) {
             baseOid,
             headOid,
         ];
-        unifiedArgs = ['diff', '--no-ext-diff', '--no-textconv', baseOid, headOid];
+        unifiedArgs = reviewUnifiedDiffArgs(options.selector, { baseOid, headOid });
     }
     else {
         nameStatusArgs = [
@@ -150,7 +159,7 @@ async function captureReviewSnapshot(options) {
             '-z',
             'HEAD',
         ];
-        unifiedArgs = ['diff', '--no-ext-diff', '--no-textconv', 'HEAD'];
+        unifiedArgs = reviewUnifiedDiffArgs(options.selector, { baseOid, headOid });
     }
     const nameStatusRaw = await runGit(nameStatusArgs);
     const changed = parseNameStatusZ(nameStatusRaw.split('\0')).filter(entry => {

package/dist/web/code-review-run-service.d.ts

@@ -0,0 +1,68 @@
+import { type CodeReviewResultV1, type ReviewRunStateV1, type ReviewSelectorV1 } from '../services/code-review/contract';
+import { runCodeReview, type ReviewModelAdapterV1 } from '../services/code-review/runner';
+export interface WebCodeReviewRunRecordV1 {
+    readonly runId: string;
+    readonly selector: ReviewSelectorV1;
+    readonly status: ReviewRunStateV1 | 'running';
+    readonly startedAt: number;
+    readonly endedAt: number | null;
+    /** Repository revision captured at admission; compared against the current
+     *  value on read to mark a stored receipt stale. */
+    readonly repositoryRevisionAtAdmission: string;
+    /** fileKey -> path mapping captured with the frozen snapshot, so findings
+     *  can be anchored to a diff without changing the receipt contract. */
+    readonly files: ReadonlyArray<{
+        readonly fileKey: string;
+        readonly path: string;
+    }>;
+    /** Present only for finished runs whose receipt passed digest re-verification. */
+    readonly result: CodeReviewResultV1 | null;
+    readonly failure: {
+        readonly kind: string;
+        readonly message: string;
+    } | null;
+    /** Recomputed on read: true when the repository changed since admission. */
+    readonly stale: boolean;
+}
+export interface WebCodeReviewRunServiceOptionsV1 {
+    /** Returns the review model adapter, or null when the Host has no model. */
+    readonly adapterProvider: () => ReviewModelAdapterV1 | null;
+    /** Workspace root used for the review snapshot; read at start time. */
+    readonly cwdProvider: () => string;
+    /** Current repository revision, sampled on every read for staleness. */
+    readonly repositoryRevisionProvider: () => Promise<string>;
+    /** Injectable runner (tests use fakes); defaults to the shared runner. */
+    readonly runReview?: typeof runCodeReview;
+    readonly now?: () => number;
+    /** Bounded receipt history; oldest finished records are evicted first. */
+    readonly maxRuns?: number;
+}
+export declare class WebCodeReviewRunServiceV1 {
+    private readonly records;
+    private readonly inflight;
+    private readonly adapterProvider;
+    private readonly cwdProvider;
+    private readonly repositoryRevisionProvider;
+    private readonly runReview;
+    private readonly now;
+    private readonly maxRuns;
+    constructor(options: WebCodeReviewRunServiceOptionsV1);
+    /** Admission is synchronous and fast: validate, record, return. The model
+     *  completion continues in the background. */
+    start(selector: ReviewSelectorV1): Promise<{
+        readonly runId: string;
+        readonly status: 'running';
+    }>;
+    /** Cancels a running review; finished or unknown runs are a no-op. */
+    cancel(runId: string): void;
+    list(): Promise<readonly WebCodeReviewRunRecordV1[]>;
+    get(runId: string): Promise<WebCodeReviewRunRecordV1>;
+    private execute;
+    private evictFinished;
+    private present;
+}
+/** v0.3.29 — validates the JSON selector accepted by `POST /review/run`.
+ *  Mirrors the CLI selector contract: worktree scope, base ref scope, optional
+ *  path filters. Unknown shapes are typed 400s, never guesses. */
+export declare function parseWebReviewSelectorV1(value: unknown): ReviewSelectorV1;
+//# sourceMappingURL=code-review-run-service.d.ts.map