@orion-agents/orion-code 0.3.28 → 0.3.29

package/CHANGELOG.md

@@ -22,9 +22,59 @@ which is **not** a pass.
 
 ## [Unreleased]
 
-## [0.3.28] — UNRELEASED
+## [0.3.29] — UNRELEASED
+
+> **Status: candidate.** Open. The Web shared review loop
+> (plan: `docs/plan/v0.3.29-plan.md`, PR3 core of the v0.3.27 review loop):
+> the Host now starts the same bounded single-pass review runner the CLI uses
+> (`runCodeReview`, v0.3.28) against the active Workspace. `POST /review/run`
+> performs fast admission (one in-flight run per Host, typed
+> `review_run_in_progress` 409 and `review_no_model` 422) and the model
+> completion continues in the background; `GET /review/runs` and
+> `GET /review/runs/:runId` read a bounded in-memory history where every
+> receipt passes digest re-verification and is flagged `stale` when the
+> repository revision changed after admission. The Review panel lists the runs
+> with honest state banners (running / cancelled / failed / partial / stale
+> never render as a green pass), groups findings P0→P3 with file:line anchors
+> into the existing diff view, counts contract-invalid model output instead of
+> hiding it, and can send each finding back to the Composer as a typed draft
+> the user still confirms. The fileKey→path mapping is captured through an
+> additive `onSnapshotCaptured` runner hook; the frozen receipt contract is
+> unchanged. Not merged, tagged or published.
 
-> **Status: candidate.** Open. The typed `/review` runtime & CLI slice
+### Added
+
+- `src/web/code-review-run-service.ts` — the Host-side review run service:
+  single-flight admission, background execution of the shared runner, bounded
+  receipt history (20 runs, oldest finished evicted first), digest
+  re-verification on read, repository-revision staleness flags, cancellation,
+  and the `parseWebReviewSelectorV1` request validation.
+- `src/web/workbench-controller.ts` — `reviewRunStart` / `reviewRunList` /
+  `reviewRunGet` / `reviewRunCancel`, with the review model adapter derived
+  from the control-plane Runtime's `llm` (typed 422 when the Host has no
+  configured model).
+- `src/web/server.ts` — `POST /review/run` and
+  `POST /review/runs/:runId/cancel` behind `assertMutation` +
+  `executeMutation`, plus read-only `GET /review/runs[/:runId]` with context
+  guards.
+- `web/src/components/review/ReviewRunsSection.tsx` and
+  `review-runs-view.ts` — the Review panel results section: run button,
+  polling while a run is in flight, priority-grouped findings, honest banners,
+  diff anchoring and typed Composer drafts.
+- Tests: `tests/web-code-review-run-service.test.ts` (10 unit tests),
+  `tests/web-review-run-endpoint.test.ts` (4 real-host tests on a temp Git
+  repository, including the 403 nonce guard and the 422 no-model path),
+  `tests/web-review-runs-view.test.tsx` (13 pure + SSR view tests).
+
+### Not run
+
+- Real Host + Chrome full-chain E2E and the human-labeled quality benchmark
+  (PR4) — the local automation sandbox has no model credentials; recorded
+  honestly as `not_run`, not silently skipped.
+
+## [0.3.28] — 2026-10-22
+
+> **Status: published.** The typed `/review` runtime & CLI slice
 > (plan: `docs/plan/v0.3.28-plan.md`, PR2 core of the v0.3.27 review loop):
 > `/review` arguments now parse into the frozen `ReviewSelectorV1` (worktree /
 > `--base` / repeatable `--path`, back-compat single-path filter) and unknown
@@ -38,7 +88,8 @@ which is **not** a pass.
 > reports "no changes under review" without calling the model, and partial,
 > failed, cancelled or inconclusive runs never render as a green pass.
 > Web wiring (PR3) and the qualification benchmark (PR4) remain subsequent
-> slices. Not merged, tagged or published.
+> slices. Merged as #284, tagged `v0.3.28` on main (`8a4722b`), published to
+> npm (registry `latest` = 0.3.28).
 
 ### Added
 

package/README.md

@@ -2,15 +2,13 @@
 
 Local-first, goal-driven coding agent for the terminal and browser.
 
-> v0.3.28 candidate — open. The typed `/review` workflow: slash arguments are
-> parsed into the frozen review selector (worktree / `--base` / `--path`, with
-> usage errors instead of silent chat fallback), the review runs against the
-> admission-time frozen Git snapshot through a bounded single-pass model call,
-> model findings are validated against the contract and the snapshot manifest,
-> and the run renders a digest-verifiable receipt with honest state banners
-> (empty scope ≠ review pass; partial / failed / cancelled never green). The
-> previous release 0.3.27 is on npm (registry `latest`), tagged `v0.3.27`
-> (`0be5b18`, #283) and released on GitHub.
+> v0.3.29 candidate — open. The Web shared review loop: the Host starts the same
+> bounded `/review` runner the CLI uses, the Review panel lists digest-verifiable
+> receipts with honest state banners (running / partial / failed / cancelled /
+> stale never green), findings are grouped P0→P3 and anchor to the existing diff
+> view, and each finding can be sent back to the Composer as a typed draft. The
+> previous release 0.3.28 is on npm (registry `latest`), tagged `v0.3.28`
+> (`8a4722b`, #284) and released on GitHub.
 
 [中文说明](README.zh-CN.md) ·
 [v0.3.24 plan](docs/plan/v0.3.24-plan.md) ·
@@ -173,10 +171,10 @@ user extension boundaries.
 Node.js 22.12+, 24, and 26 are supported. Use Node 24 LTS for production or Node 26 Current for
 current development environments. Node 20 is upstream EOL and is no longer a v0.3 runtime.
 
-To install the pinned v0.3.28 package when it is available on npm:
+To install the pinned v0.3.29 package when it is available on npm:
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.28
+npm install -g @orion-agents/orion-code@0.3.29
 orion --version
 orion doctor
 ```

package/README.zh-CN.md

@@ -2,12 +2,11 @@
 
 面向终端与浏览器、本地优先的目标驱动 Coding Agent。
 
-> v0.3.28 候选版本：进行中。类型化 `/review` 审查工作流：slash 参数解析为冻结的审查
-> selector（worktree / `--base` / `--path`，未知参数返回用法而非静默转入普通聊天）；审查
-> 基于 admission 时冻结的 Git snapshot，经有界单轮模型补全执行；模型 finding 按契约与
-> snapshot manifest 校验；输出 digest 可验证的 receipt 与如实状态横幅（空范围 ≠ 审查通过；
-> partial / failed / cancelled 永远不会显示为绿色）。上一版 0.3.27 已发布 npm
-> （registry `latest`）、打 tag `v0.3.27`（`0be5b18`，#283）并发布 GitHub Release。
+> v0.3.29 候选版本：进行中。Web 共享审查闭环：Host 复用 CLI 同一有界审查运行器发起
+> 审查；审阅面板列出 digest 可验证的 receipt 与如实状态横幅（running / partial /
+> failed / cancelled / 过期永远不会显示为绿色）；finding 按 P0→P3 分组并可定位到既有
+> diff 视图；每个 finding 可作为类型化草稿送回对话。上一版 0.3.28 已发布 npm
+> （registry `latest`）、打 tag `v0.3.28`（`8a4722b`，#284）并发布 GitHub Release。
 
 [English](README.md) ·
 [v0.3.24 方案](docs/plan/v0.3.24-plan.md) ·
@@ -102,10 +101,10 @@ MCP 仍是用户可见的扩展边界。
 支持 Node.js 22.12+、24 和 26。生产环境建议使用 Node 24 LTS，当前开发环境也支持 Node 26
 Current。Node 20 已结束上游维护，不再属于 v0.3 Runtime 合同。
 
-v0.3.28 在 npm 可用后，可安装固定版本：
+v0.3.29 在 npm 可用后，可安装固定版本：
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.28
+npm install -g @orion-agents/orion-code@0.3.29
 orion --version
 orion doctor
 ```

package/dist/commands/workflow-command-handlers.d.ts

@@ -12,5 +12,5 @@ declare function continueAsSlashChat(name: string, args: string): CommandResult;
  * Git snapshot, and the receipt is rendered by the shared formatter.
  */
 declare function handleReview(ctx: CommandContext, args: string): Promise<CommandResult>;
-export { handlePlan, handleDiff, handleCommitPlan, continueAsSlashChat, handleReview, };
+export { handlePlan, handleDiff, handleCommitPlan, continueAsSlashChat, handleReview };
 //# sourceMappingURL=workflow-command-handlers.d.ts.map

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

@@ -1,5 +1,5 @@
 import { DEFAULT_REVIEW_BUDGETS, type CodeReviewResultV1, type ReviewBudgetsV1, type ReviewSelectorV1 } from './contract';
-import { type ReviewGitRunner } from './snapshot';
+import { type CodeReviewSnapshotV1, type ReviewGitRunner } from './snapshot';
 /** One bounded model completion. CLI wiring adapts `LLMService.chat`. */
 export interface ReviewModelAdapterV1 {
     complete(messages: readonly {
@@ -29,6 +29,11 @@ export interface ReviewRunOptionsV1 {
     readonly abortSignal?: AbortSignal;
     readonly runGit?: ReviewGitRunner;
     readonly now?: () => number;
+    /** v0.3.29 — additive observation hook fired inside the admission window
+     *  right after the frozen snapshot is captured. Lets a host keep the
+     *  fileKey -> path mapping for diff anchoring without changing the frozen
+     *  receipt contract. */
+    readonly onSnapshotCaptured?: (snapshot: CodeReviewSnapshotV1) => void;
 }
 export type ReviewRunFailureV1 = {
     readonly kind: 'budget';

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

@@ -94,7 +94,9 @@ function buildReviewSystemPrompt(rulesDigest) {
 function buildSnapshotMaterial(snapshot, diffText, budgets) {
     const sections = [
         `Snapshot: ${snapshot.snapshotId} (kind=${snapshot.kind}`,
-        snapshot.kind === 'base' ? `base=${snapshot.baseOid} head=${snapshot.headOid})` : 'worktree scope)',
+        snapshot.kind === 'base'
+            ? `base=${snapshot.baseOid} head=${snapshot.headOid})`
+            : 'worktree scope)',
         `Input snapshot digest: ${snapshot.inputSnapshotDigest}`,
         'Changed files (fileKey -> path):',
         ...snapshot.files.map(file => {
@@ -145,8 +147,12 @@ function snapshotAuthorizesFile(snapshot, finding) {
         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);
+        ? 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;
@@ -175,6 +181,7 @@ async function runCodeReview(options) {
             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
@@ -189,7 +196,11 @@ async function runCodeReview(options) {
         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) },
+            failure: {
+                kind: 'snapshot',
+                code,
+                message: error instanceof Error ? error.message : String(error),
+            },
         };
     }
     const rulesDigest = await computeReviewRulesDigest(options.cwd);
@@ -233,7 +244,10 @@ async function runCodeReview(options) {
             startedAt,
             endedAt,
         };
-        return { ok: true, result: Object.freeze({ ...base, receiptDigest: (0, contract_1.computeReceiptDigest)(base) }) };
+        return {
+            ok: true,
+            result: Object.freeze({ ...base, receiptDigest: (0, contract_1.computeReceiptDigest)(base) }),
+        };
     }
     const material = buildSnapshotMaterial(snapshot, diffText, budgets.budgets);
     if (material.truncated) {

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

@@ -28,7 +28,10 @@ function looksLikeRelativePath(value) {
  * 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);
+    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) {

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

package/dist/web/code-review-run-service.js

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebCodeReviewRunServiceV1 = void 0;
+exports.parseWebReviewSelectorV1 = parseWebReviewSelectorV1;
+/**
+ * v0.3.29 — Host-side shared code-review run service
+ * (docs/plan/v0.3.29-plan.md S1). The Web Host starts the same bounded
+ * single-pass review runner the CLI uses (v0.3.28 `runCodeReview`) against the
+ * active Workspace, keeps a bounded in-memory receipt history, and re-verifies
+ * every receipt digest plus repository revision freshness when results are
+ * read. No second review engine: receipts, budgets, validation and honest
+ * failure states come from the frozen `src/services/code-review` contract.
+ *
+ * Delivery model: `start()` validates admission and returns immediately; the
+ * model completion runs in the background and clients poll `list()`/`get()`.
+ * At most one run is in flight per Host (a second start is a typed 409), and
+ * a run may be cancelled to release the slot.
+ */
+const crypto_1 = require("crypto");
+const contract_1 = require("../services/code-review/contract");
+const runner_1 = require("../services/code-review/runner");
+const errors_1 = require("./errors");
+class WebCodeReviewRunServiceV1 {
+    constructor(options) {
+        this.records = new Map();
+        this.inflight = new Map();
+        this.adapterProvider = options.adapterProvider;
+        this.cwdProvider = options.cwdProvider;
+        this.repositoryRevisionProvider = options.repositoryRevisionProvider;
+        this.runReview = options.runReview ?? runner_1.runCodeReview;
+        this.now = options.now ?? Date.now;
+        this.maxRuns = Math.max(1, options.maxRuns ?? 20);
+    }
+    /** Admission is synchronous and fast: validate, record, return. The model
+     *  completion continues in the background. */
+    async start(selector) {
+        if (this.inflight.size > 0) {
+            throw new errors_1.WebWorkbenchError(409, 'A code review is already running in this Host. Wait for it to finish or cancel it.', 'review_run_in_progress');
+        }
+        const adapter = this.adapterProvider();
+        if (!adapter) {
+            throw new errors_1.WebWorkbenchError(422, 'The Host has no configured model. Configure a model first, then retry the review.', 'review_no_model');
+        }
+        const runId = (0, crypto_1.randomUUID)();
+        const repositoryRevisionAtAdmission = await this.repositoryRevisionProvider();
+        const startedAt = this.now();
+        let capturedFiles = [];
+        this.records.set(runId, {
+            runId,
+            selector,
+            status: 'running',
+            startedAt,
+            endedAt: null,
+            repositoryRevisionAtAdmission,
+            files: capturedFiles,
+            result: null,
+            failure: null,
+            stale: false,
+        });
+        const abort = new AbortController();
+        this.inflight.set(runId, abort);
+        const cwd = this.cwdProvider();
+        void this.execute({
+            runId,
+            selector,
+            cwd,
+            adapter,
+            abort,
+            onSnapshot: snapshot => {
+                capturedFiles = Object.freeze(snapshot.files.map(file => ({ fileKey: file.fileKey, path: file.path })));
+                const record = this.records.get(runId);
+                if (record)
+                    this.records.set(runId, { ...record, files: capturedFiles });
+            },
+        });
+        return Object.freeze({ runId, status: 'running' });
+    }
+    /** Cancels a running review; finished or unknown runs are a no-op. */
+    cancel(runId) {
+        this.inflight.get(runId)?.abort();
+    }
+    async list() {
+        const currentRevision = await this.repositoryRevisionProvider();
+        return [...this.records.values()]
+            .sort((left, right) => right.startedAt - left.startedAt)
+            .map(record => this.present(record, currentRevision));
+    }
+    async get(runId) {
+        const record = this.records.get(runId);
+        if (!record) {
+            throw new errors_1.WebWorkbenchError(404, 'Unknown review run.', 'review_run_not_found');
+        }
+        const currentRevision = await this.repositoryRevisionProvider();
+        return this.present(record, currentRevision);
+    }
+    async execute(input) {
+        const { runId, selector, cwd, adapter, abort, onSnapshot } = input;
+        const options = {
+            cwd,
+            selector,
+            adapter,
+            identity: {
+                workspaceIdentity: cwd,
+                // Web control-plane runs are their own session identity; they are not
+                // attributed to any chat Session actor.
+                sessionId: `web-host:${runId}`,
+                threadId: `web-host:${runId}`,
+                turnId: runId,
+            },
+            abortSignal: abort.signal,
+            ...(onSnapshot ? { onSnapshotCaptured: onSnapshot } : {}),
+        };
+        let failure = null;
+        let result = null;
+        try {
+            const outcome = await this.runReview(options);
+            if (outcome.ok) {
+                result = outcome.result;
+            }
+            else {
+                failure = {
+                    kind: outcome.failure.kind,
+                    message: failureMessage(outcome.failure),
+                };
+            }
+        }
+        catch (error) {
+            failure = {
+                kind: 'model_error',
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        this.inflight.delete(runId);
+        const existing = this.records.get(runId);
+        if (!existing)
+            return;
+        const finished = {
+            ...existing,
+            status: result ? result.state : failure?.kind === 'cancelled' ? 'cancelled' : 'failed',
+            endedAt: this.now(),
+            result,
+            failure,
+        };
+        this.records.set(runId, finished);
+        this.evictFinished();
+    }
+    evictFinished() {
+        const finished = [...this.records.values()]
+            .filter(record => record.status !== 'running')
+            .sort((left, right) => (left.endedAt ?? left.startedAt) - (right.endedAt ?? right.startedAt));
+        let excess = this.records.size - this.maxRuns;
+        for (const record of finished) {
+            if (excess <= 0)
+                break;
+            this.records.delete(record.runId);
+            excess -= 1;
+        }
+    }
+    present(record, currentRevision) {
+        const stale = record.result !== null && record.repositoryRevisionAtAdmission !== currentRevision;
+        if (record.result && !(0, contract_1.verifyReceiptDigest)(record.result)) {
+            // A receipt that no longer verifies must never be presented as findings;
+            // surface it as a failed run with an honest message instead.
+            return {
+                ...record,
+                status: 'failed',
+                stale,
+                result: null,
+                failure: {
+                    kind: 'receipt_digest_mismatch',
+                    message: 'The stored review receipt failed digest re-verification.',
+                },
+            };
+        }
+        return { ...record, stale };
+    }
+}
+exports.WebCodeReviewRunServiceV1 = WebCodeReviewRunServiceV1;
+function failureMessage(failure) {
+    switch (failure.kind) {
+        case 'cancelled':
+            return 'Review cancelled.';
+        case 'budget':
+            return `Review budget rejected: ${failure.field ?? 'unknown'}`;
+        case 'snapshot':
+            return `Review scope error (${failure.code ?? 'unknown'}): ${failure.message ?? ''}`;
+        case 'model_error':
+            return `Review model call failed: ${failure.message ?? ''}`;
+        case 'unparsable_output':
+            return `Review output could not be parsed: ${failure.message ?? ''}`;
+        default:
+            return failure.message ?? 'Review failed.';
+    }
+}
+/** 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. */
+function parseWebReviewSelectorV1(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new errors_1.WebWorkbenchError(400, 'Review selector must be an object.', 'review_selector_invalid');
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    const allowed = record.kind === 'base' ? ['kind', 'paths', 'ref'] : ['kind', 'paths'];
+    if (keys.some(key => !allowed.includes(key))) {
+        throw new errors_1.WebWorkbenchError(400, `Review selector accepts only ${allowed.join(', ')}.`, 'review_selector_invalid');
+    }
+    const paths = parseSelectorPaths(record.paths);
+    if (record.kind === 'base') {
+        if (typeof record.ref !== 'string' || record.ref.trim() === '') {
+            throw new errors_1.WebWorkbenchError(400, 'Review selector base ref must be a non-empty string.', 'review_selector_invalid');
+        }
+        return Object.freeze({ kind: 'base', ref: record.ref, ...(paths ? { paths } : {}) });
+    }
+    if (record.kind === 'worktree') {
+        return Object.freeze({ kind: 'worktree', ...(paths ? { paths } : {}) });
+    }
+    throw new errors_1.WebWorkbenchError(400, 'Review selector kind must be "worktree" or "base".', 'review_selector_invalid');
+}
+function parseSelectorPaths(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some(path => typeof path !== 'string' || path.trim() === '')) {
+        throw new errors_1.WebWorkbenchError(400, 'Review selector paths must be an array of non-empty strings.', 'review_selector_invalid');
+    }
+    return Object.freeze([...value]);
+}
+//# sourceMappingURL=code-review-run-service.js.map

package/dist/web/server.js

@@ -9,6 +9,7 @@ const version_1 = require("../product/version");
 const redaction_1 = require("../services/redaction");
 const protocol_1 = require("./protocol");
 const errors_1 = require("./errors");
+const code_review_run_service_1 = require("./code-review-run-service");
 const cli_options_1 = require("./cli-options");
 const terminal_server_1 = require("./terminal-server");
 const workbench_controller_1 = require("./workbench-controller");
@@ -885,6 +886,42 @@ async function handleRequest(context) {
         sendJson(response, 200, await context.workbench.review(requireContextGuardQuery(url)));
         return;
     }
+    // v0.3.29 — shared code-review runs. Start is a fast mutation (admission
+    // only; the model completion runs in the background and clients poll the
+    // read-only list/get endpoints below).
+    if (method === 'POST' && path === '/review/run') {
+        assertMutation(request, context.nonce, context.origin);
+        const body = requireRecord(await readJson(request), 'Review run request');
+        assertOnlyKeys(body, ['requestId', 'selector', 'expectedContextRevision', 'workspaceId']);
+        const requestId = requireUuid(body.requestId, 'requestId');
+        const contextGuard = requireContextGuardRecord(body);
+        const selector = (0, code_review_run_service_1.parseWebReviewSelectorV1)(body.selector);
+        const result = await context.workbench.executeMutation(requestId, 'review.run', { selector, ...contextGuard }, () => context.workbench.reviewRunStart(selector, contextGuard));
+        sendJson(response, 200, result);
+        return;
+    }
+    if (method === 'GET' && path === '/review/runs') {
+        sendJson(response, 200, await context.workbench.reviewRunList(requireContextGuardQuery(url)));
+        return;
+    }
+    const reviewRunMatch = path.match(/^\/review\/runs\/([^/]+)$/);
+    if (method === 'GET' && reviewRunMatch) {
+        const runId = requireUuid(safeDecodePathSegment(reviewRunMatch[1]), 'runId');
+        sendJson(response, 200, await context.workbench.reviewRunGet(runId, requireContextGuardQuery(url)));
+        return;
+    }
+    const reviewRunCancelMatch = path.match(/^\/review\/runs\/([^/]+)\/cancel$/);
+    if (method === 'POST' && reviewRunCancelMatch) {
+        assertMutation(request, context.nonce, context.origin);
+        const body = requireRecord(await readJson(request), 'Review cancel request');
+        assertOnlyKeys(body, ['requestId', 'expectedContextRevision', 'workspaceId']);
+        const requestId = requireUuid(body.requestId, 'requestId');
+        const contextGuard = requireContextGuardRecord(body);
+        const runId = requireUuid(safeDecodePathSegment(reviewRunCancelMatch[1]), 'runId');
+        const result = await context.workbench.executeMutation(requestId, 'review.run.cancel', { runId, ...contextGuard }, () => context.workbench.reviewRunCancel(runId, contextGuard));
+        sendJson(response, 200, result);
+        return;
+    }
     if (method === 'GET' && path === '/terminals') {
         const contextGuard = requireContextGuardQuery(url);
         sendJson(response, 200, collectionPage(url, 'terminals', context.workbench.listTerminals(contextGuard), terminal => terminal.id));

package/dist/web/workbench-controller.d.ts

@@ -10,6 +10,7 @@ import { type WebComposerActionResultV1, type WebComposerActionV1, type WebCompo
 import { type NativeDirectoryPickResult, type NativeDirectoryPicker } from './native-directory-picker';
 import { WorkspaceDiscoveryTelemetryV1 } from './workspace-discovery';
 import { WorkspaceRootsRegistryV1 } from '../services/workspace-roots-registry';
+import type { ReviewSelectorV1 } from '../services/code-review/contract';
 import { type WebSessionRuntimeSummaryV1 } from './session-runtime-registry';
 import { TerminalManagerV1 } from './terminal-manager';
 export { WebWorkbenchError } from './errors';
@@ -70,6 +71,8 @@ export declare class WebWorkbenchController {
     private fileWriteService;
     private gitService;
     private reviewService;
+    /** v0.3.29 — shared code-review run history for the Review panel. */
+    private readonly codeReviewRuns;
     private contextRevisionValue;
     private composerRevisionValue;
     private composerAuthorityDigest;
@@ -281,6 +284,19 @@ export declare class WebWorkbenchController {
     gitLog(context: WebContextGuardV1, input: Parameters<GitReadModelServiceV1['log']>[0]): Promise<import("./git-read-model-service").WebGitLogPageV1>;
     gitDiff(context: WebContextGuardV1, input: Parameters<GitReadModelServiceV1['diff']>[0]): Promise<import("./git-read-model-service").WebGitDiffPageV1>;
     review(context: WebContextGuardV1): Promise<import("./review-service").WebReviewSnapshotV1>;
+    /** v0.3.29 — starts a shared code review run (fast admission, background run). */
+    reviewRunStart(selector: ReviewSelectorV1, context: WebContextGuardV1): Promise<{
+        readonly runId: string;
+        readonly status: 'running';
+    }>;
+    /** v0.3.29 — bounded list of review runs with freshness flags. */
+    reviewRunList(context: WebContextGuardV1): Promise<readonly import("./code-review-run-service").WebCodeReviewRunRecordV1[]>;
+    /** v0.3.29 — one review run record with digest re-verification. */
+    reviewRunGet(runId: string, context: WebContextGuardV1): Promise<import("./code-review-run-service").WebCodeReviewRunRecordV1>;
+    /** v0.3.29 — cancels a running review to release the single in-flight slot. */
+    reviewRunCancel(runId: string, context: WebContextGuardV1): {
+        readonly cancelled: boolean;
+    };
     listTerminals(context: WebContextGuardV1): readonly import("./terminal-manager").WebTerminalMetadataV1[];
     createSession(name?: string, context?: WebContextGuardV1): Promise<WebSessionSummaryV1>;
     activateSession(sessionId: string, context?: WebContextGuardV1): Promise<WebCommandResultV1>;