@orion-agents/orion-code 0.3.27 → 0.3.28

package/CHANGELOG.md

@@ -22,9 +22,70 @@ which is **not** a pass.
 
 ## [Unreleased]
 
-## [0.3.27] — UNRELEASED
+## [0.3.28] — UNRELEASED
+
+> **Status: candidate.** Open. 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
+> input returns the usage text instead of silently continuing as an ordinary
+> chat turn. The review runs against the admission-time frozen Git snapshot
+> through a bounded single-pass model completion; the model's findings are
+> validated against the contract and anchored to the snapshot manifest, with
+> invalid or unanchored findings counted and surfaced rather than silently
+> dropped. Every run produces a digest-verifiable `CodeReviewResultV1` receipt
+> rendered by the shared formatter with honest state banners: an empty scope
+> 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.
 
-> **Status: candidate.** Open. First slice of the professional code review loop
+### Added
+
+- `src/services/code-review/selector.ts` — the typed `/review` argument
+  parser: empty / `all` → worktree scope, `--base <ref>` → base scope,
+  repeatable `--path <path>` filters, single bare relative path kept as a
+  back-compat worktree filter; unknown options, missing values, repeated
+  `--base`, absolute paths and traversal are typed usage errors. Fourteen
+  tests pin every accepted shape and rejection path.
+- `src/services/code-review/runner.ts` — the bounded single-pass review
+  runner: `resolveReviewBudgets` (tighten-only) → `captureReviewSnapshot`
+  (worktree contained reader) → frozen unified diff captured with the same
+  admission-time arguments → rules digest binding the read-only constraints
+  digest plus ancestor `AGENTS.md` contents → one model completion through an
+  injected adapter → contract validation + snapshot-membership anchoring +
+  `maxFindings` budget → `resolveReviewConclusion` → receipt digest
+  recomputation. Empty scope completes without a model call and is labeled
+  `empty_scope_no_changes`; cancellation, model errors and unparsable output
+  are typed failures, never green passes.
+- `src/services/code-review/format.ts` — the shared TUI formatter: scope and
+  resolved target header, findings grouped P0→P3 with side:line locations,
+  invalid-finding counts, coverage / skips / budget exhaustion footer and a
+  receipt digest line; partial / failed / cancelled banners never render as a
+  clean pass.
+- `/review` command wiring (`src/commands/workflow-commands.ts`,
+  `workflow-command-handlers.ts`): the command is now a read-only builtin
+  that runs the typed workflow; unrecognized arguments return usage, a
+  missing model returns an explicit error, and no path falls back to ordinary
+  chat.
+
+### Changed
+
+- `src/services/code-review/snapshot.ts` exports `reviewUnifiedDiffArgs` so
+  the runner reuses the exact frozen diff arguments instead of re-deriving
+  OIDs after admission; no frozen semantics changed.
+
+### Not run
+
+- Real-PTY CLI verification, Web E2E (no Web changes in this slice), and the
+  paid human-annotated review-quality benchmark remain `not_run`, matching
+  the v0.3.27 plan's PR3/PR4 sequencing.
+
+## [0.3.27] — 2026-10-22
+
+> **Status: published, 2026-10-22.** Tagged `v0.3.27` (`0be5b18`), merged via
+> #283, and visible on npm as registry `latest`. First slice of the
+> professional code review loop
 > (plan: `docs/plan/v0.3.27-plan.md`): the shared review contract (selectors,
 > states, conclusions, findings, tighten-only budgets, receipt digests,
 > stale-applicability) is frozen in `src/services/code-review` and bound by
@@ -34,7 +95,7 @@ which is **not** a pass.
 > workflow constraints deny every non-read tool by default with a dispatch-level
 > guard whose digest binds receipts. Runtime / CLI wiring (PR2), the Web loop
 > (PR3) and the qualification benchmark (PR4) are subsequent slices of the same
-> plan and are not part of this release. Not merged, tagged or published.
+> plan and are not part of this release; PR2's core CLI slice ships in 0.3.28.
 
 ### Added
 

package/README.md

@@ -2,14 +2,15 @@
 
 Local-first, goal-driven coding agent for the terminal and browser.
 
-> v0.3.27 candidate — open. First slice of the professional code review loop: the
-> shared review contract (selectors, states, conclusions, findings, tighten-only
-> budgets, receipt digests, stale-applicability) is frozen and contract-tested,
-> the shared Git snapshot reader captures worktree and frozen-base scopes with
-> typed errors, and the read-only workflow constraints deny every non-read tool
-> by default. Runtime/CLI wiring, the Web loop and the qualification benchmark
-> are subsequent slices of the same plan. The previous release 0.3.26 is on npm
-> (registry `latest`), tagged `v0.3.26` (`b810996`, #278) and released on GitHub.
+> 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.
 
 [中文说明](README.zh-CN.md) ·
 [v0.3.24 plan](docs/plan/v0.3.24-plan.md) ·
@@ -172,10 +173,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.27 package when it is available on npm:
+To install the pinned v0.3.28 package when it is available on npm:
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.27
+npm install -g @orion-agents/orion-code@0.3.28
 orion --version
 orion doctor
 ```

package/README.zh-CN.md

@@ -2,11 +2,12 @@
 
 面向终端与浏览器、本地优先的目标驱动 Coding Agent。
 
-> v0.3.27 候选版本：进行中。专业代码审查闭环首切片：共享审查契约（selector、状态、结论、
-> finding、只收紧预算、receipt digest、stale 标注）已冻结并通过契约测试；共享 Git snapshot
-> reader 捕获 worktree 与冻结 base 两种范围并给出类型化错误；只读 workflow 约束默认拒绝一切
-> 非读取工具。Runtime/CLI 接线、Web 闭环与资格验证为同一计划的后续切片。上一版 0.3.26 已发布
-> npm（registry `latest`）、打 tag `v0.3.26`（`b810996`，#278）并发布 GitHub Release。
+> 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。
 
 [English](README.md) ·
 [v0.3.24 方案](docs/plan/v0.3.24-plan.md) ·
@@ -101,10 +102,10 @@ MCP 仍是用户可见的扩展边界。
 支持 Node.js 22.12+、24 和 26。生产环境建议使用 Node 24 LTS，当前开发环境也支持 Node 26
 Current。Node 20 已结束上游维护，不再属于 v0.3 Runtime 合同。
 
-v0.3.27 在 npm 可用后，可安装固定版本：
+v0.3.28 在 npm 可用后，可安装固定版本：
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.27
+npm install -g @orion-agents/orion-code@0.3.28
 orion --version
 orion doctor
 ```

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

@@ -4,5 +4,13 @@ declare function handlePlan(ctx: CommandContext, args: string): Promise<CommandR
 declare function handleDiff(ctx: CommandContext, args: string): CommandResult;
 declare function handleCommitPlan(ctx: CommandContext, args: string): CommandResult;
 declare function continueAsSlashChat(name: string, args: string): CommandResult;
-export { handlePlan, handleDiff, handleCommitPlan, continueAsSlashChat };
+/**
+ * v0.3.28 — the typed `/review` workflow (docs/plan/v0.3.28-plan.md S4).
+ * Arguments are parsed into a frozen selector; unrecognized input returns the
+ * usage text instead of silently continuing as an ordinary chat turn. The
+ * run goes through the bounded single-pass review runner against the frozen
+ * 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, };
 //# sourceMappingURL=workflow-command-handlers.d.ts.map

package/dist/commands/workflow-command-handlers.js

@@ -5,9 +5,13 @@ exports.handlePlan = handlePlan;
 exports.handleDiff = handleDiff;
 exports.handleCommitPlan = handleCommitPlan;
 exports.continueAsSlashChat = continueAsSlashChat;
+exports.handleReview = handleReview;
 const workspace_diff_1 = require("../services/workspace-diff");
 const commit_plan_1 = require("../services/commit-plan");
 const agent_mode_1 = require("../framework/agent-mode");
+const selector_1 = require("../services/code-review/selector");
+const runner_1 = require("../services/code-review/runner");
+const format_1 = require("../services/code-review/format");
 async function handlePlan(ctx, args) {
     const task = args.trim();
     const [subcommand = '', ...tail] = task.split(/\s+/);
@@ -92,4 +96,66 @@ function continueAsSlashChat(name, args) {
         chatInput: `/${name}${trimmed ? ` ${trimmed}` : ''}`,
     };
 }
+/**
+ * v0.3.28 — the typed `/review` workflow (docs/plan/v0.3.28-plan.md S4).
+ * Arguments are parsed into a frozen selector; unrecognized input returns the
+ * usage text instead of silently continuing as an ordinary chat turn. The
+ * run goes through the bounded single-pass review runner against the frozen
+ * Git snapshot, and the receipt is rendered by the shared formatter.
+ */
+async function handleReview(ctx, args) {
+    const parsed = (0, selector_1.parseReviewSelector)(args);
+    if (!parsed.ok)
+        return { success: false, error: parsed.usage };
+    if (!ctx.llm) {
+        return {
+            success: false,
+            error: 'Code review needs a configured model. Run /model first, then retry /review.',
+        };
+    }
+    const llm = ctx.llm;
+    const outcome = await (0, runner_1.runCodeReview)({
+        cwd: ctx.cwd,
+        selector: parsed.selector,
+        adapter: {
+            async complete(messages) {
+                const response = await llm.chat(messages.map(message => ({ role: message.role, content: message.content })));
+                return {
+                    content: response.content,
+                    model: response.model,
+                    usage: {
+                        inputTokens: response.usage?.promptTokens ?? 0,
+                        outputTokens: response.usage?.completionTokens ?? 0,
+                    },
+                };
+            },
+        },
+        identity: {
+            workspaceIdentity: ctx.cwd,
+            sessionId: ctx.sessionId ?? 'pending-session',
+            threadId: ctx.sessionId ?? 'pending-session',
+            turnId: String(ctx.turnId ?? 'ad-hoc'),
+        },
+        ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}),
+    });
+    if (!outcome.ok) {
+        const failure = outcome.failure;
+        if (failure.kind === 'cancelled')
+            return { success: false, error: 'Review cancelled.' };
+        if (failure.kind === 'budget') {
+            return { success: false, error: `Review budget rejected: ${failure.field}` };
+        }
+        if (failure.kind === 'snapshot') {
+            return {
+                success: false,
+                error: `Review scope error (${failure.code}): ${failure.message}`,
+            };
+        }
+        if (failure.kind === 'model_error') {
+            return { success: false, error: `Review model call failed: ${failure.message}` };
+        }
+        return { success: false, error: `Review output could not be parsed: ${failure.message}` };
+    }
+    return { success: true, output: (0, format_1.formatReviewReport)(outcome.result) };
+}
 //# sourceMappingURL=workflow-command-handlers.js.map

package/dist/commands/workflow-commands.js

@@ -54,14 +54,14 @@ exports.WORKFLOW_COMMANDS = [
     },
     {
         name: 'review',
-        description: 'Review the current change or requested files',
-        argumentHint: '[scope]',
+        description: 'Run a bounded read-only code review of the current change or a base comparison',
+        argumentHint: '[all | --base <ref>] [--path <path>]',
         category: 'workflow',
         priority: 10,
-        type: 'chat',
-        execution: 'agent-workflow',
+        type: 'builtin',
+        execution: 'builtin',
         risk: 'read-only',
-        execute: (_ctx, args) => (0, workflow_command_handlers_1.continueAsSlashChat)('review', args),
+        execute: (ctx, args) => (0, workflow_command_handlers_1.handleReview)(ctx, args),
     },
     {
         name: 'research',

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

@@ -0,0 +1,12 @@
+/**
+ * v0.3.28 — TUI rendering of a code-review receipt (docs/plan/v0.3.28-plan.md
+ * S3). The formatter is deliberately honest about state: a partial, failed,
+ * cancelled or inconclusive run never renders as a green "no findings" pass,
+ * and an empty scope is reported as "no changes under review", distinct from a
+ * completed review that found nothing (v0.3.27 plan §4.1).
+ */
+import type { CodeReviewResultV1 } from './contract';
+/** Renders the full report shown after `/review` finishes. `fileLabels` maps
+ *  snapshot fileKeys to human paths when the caller still holds the manifest. */
+export declare function formatReviewReport(result: CodeReviewResultV1, fileLabels?: ReadonlyMap<string, string>): string;
+//# sourceMappingURL=format.d.ts.map

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

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatReviewReport = formatReviewReport;
+const PRIORITY_ORDER = ['P0', 'P1', 'P2', 'P3'];
+const STATE_BANNERS = {
+    queued: 'Review queued.',
+    running: 'Review running.',
+    completed: 'Review completed.',
+    partial: 'Review PARTIAL — coverage was incomplete; findings below are valid but not exhaustive.',
+    failed: 'Review FAILED — no conclusions can be drawn from this run.',
+    cancelled: 'Review CANCELLED — no conclusions can be drawn from this run.',
+};
+function formatScope(result) {
+    const selector = result.requestedSelector;
+    if (selector.kind === 'base') {
+        const paths = selector.paths?.length ? ` paths: ${selector.paths.join(', ')}` : '';
+        return `base ${selector.ref} (${result.resolvedTarget.baseOid?.slice(0, 12) ?? '?'}..${result.resolvedTarget.headOid?.slice(0, 12) ?? '?'})${paths}`;
+    }
+    const paths = selector.paths?.length ? ` paths: ${selector.paths.join(', ')}` : '';
+    return `worktree (snapshot ${result.resolvedTarget.snapshotId})${paths}`;
+}
+/** Renders the full report shown after `/review` finishes. `fileLabels` maps
+ *  snapshot fileKeys to human paths when the caller still holds the manifest. */
+function formatReviewReport(result, fileLabels) {
+    const lines = [];
+    lines.push(`Code review ${result.reviewId} — ${formatScope(result)}`);
+    lines.push(`Model: ${result.model.provider}/${result.model.model} · input snapshot ${result.inputSnapshotDigest.slice(0, 12)}`);
+    const emptyScope = result.limits.includes('empty_scope_no_changes');
+    if (emptyScope) {
+        lines.push('');
+        lines.push('No changes under the selected scope — nothing to review.');
+        return lines.join('\n');
+    }
+    lines.push('');
+    lines.push(STATE_BANNERS[result.state]);
+    if (result.findings.length > 0) {
+        lines.push('');
+        lines.push(`Findings (${result.findings.length}):`);
+        for (const priority of PRIORITY_ORDER) {
+            const group = result.findings.filter(finding => finding.priority === priority);
+            if (group.length === 0)
+                continue;
+            for (const finding of group) {
+                lines.push('');
+                lines.push(`[${priority}] ${finding.title}`);
+                lines.push(`  Location: ${fileLabels?.get(finding.fileKey) ?? finding.fileKey.slice(0, 12)} ${finding.side}:${finding.startLine}-${finding.endLine}`);
+                lines.push(`  Trigger: ${finding.trigger}`);
+                lines.push(`  Impact: ${finding.impact}`);
+                lines.push(`  Evidence: ${finding.evidence}`);
+            }
+        }
+    }
+    else if (result.state === 'completed' && result.conclusion === 'no_findings') {
+        lines.push('No findings within the reviewed scope.');
+    }
+    if (result.invalidFindingCount > 0) {
+        lines.push('');
+        lines.push(`${result.invalidFindingCount} finding(s) from the model were invalid or outside the frozen snapshot and are not shown.`);
+    }
+    lines.push('');
+    const coverage = result.coverage;
+    lines.push(`Coverage: ${coverage.inspectedFiles.length} file(s) inspected, ${coverage.skipped.length} skipped${coverage.truncated ? ', output truncated' : ''}`);
+    for (const skip of coverage.skipped) {
+        lines.push(`  skipped: ${skip.fileKey} (${skip.reason})`);
+    }
+    if (coverage.budgetExhausted.length > 0) {
+        lines.push(`Budget exhausted: ${coverage.budgetExhausted.join(', ')}`);
+    }
+    for (const limit of result.limits) {
+        if (limit !== 'empty_scope_no_changes')
+            lines.push(`Limit: ${limit}`);
+    }
+    if (!result.coverageAssertion.complete && result.state === 'completed') {
+        lines.push(`Coverage incomplete: ${result.coverageAssertion.reason ?? 'not all changed files were reviewed'}`);
+    }
+    lines.push(`Receipt digest: ${result.receiptDigest.slice(0, 16)}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=format.js.map

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

@@ -0,0 +1,71 @@
+import { DEFAULT_REVIEW_BUDGETS, type CodeReviewResultV1, type ReviewBudgetsV1, type ReviewSelectorV1 } from './contract';
+import { type ReviewGitRunner } from './snapshot';
+/** One bounded model completion. CLI wiring adapts `LLMService.chat`. */
+export interface ReviewModelAdapterV1 {
+    complete(messages: readonly {
+        readonly role: 'system' | 'user';
+        readonly content: string;
+    }[]): Promise<{
+        readonly content: string;
+        readonly model: string;
+        readonly usage?: {
+            readonly inputTokens: number;
+            readonly outputTokens: number;
+        };
+    }>;
+}
+export interface ReviewRunIdentityV1 {
+    readonly workspaceIdentity: string;
+    readonly sessionId: string;
+    readonly threadId: string;
+    readonly turnId: string;
+}
+export interface ReviewRunOptionsV1 {
+    readonly cwd: string;
+    readonly selector: ReviewSelectorV1;
+    readonly adapter: ReviewModelAdapterV1;
+    readonly identity: ReviewRunIdentityV1;
+    readonly budgets?: Partial<ReviewBudgetsV1>;
+    readonly abortSignal?: AbortSignal;
+    readonly runGit?: ReviewGitRunner;
+    readonly now?: () => number;
+}
+export type ReviewRunFailureV1 = {
+    readonly kind: 'budget';
+    readonly field: string;
+} | {
+    readonly kind: 'snapshot';
+    readonly code: string;
+    readonly message: string;
+} | {
+    readonly kind: 'cancelled';
+} | {
+    readonly kind: 'model_error';
+    readonly message: string;
+} | {
+    readonly kind: 'unparsable_output';
+    readonly message: string;
+};
+export type ReviewRunOutcomeV1 = {
+    readonly ok: true;
+    readonly result: CodeReviewResultV1;
+} | {
+    readonly ok: false;
+    readonly failure: ReviewRunFailureV1;
+};
+/** Production git runner: argument arrays, no shell, read-only profile is the
+ *  caller's responsibility (the runner only issues read commands). */
+export declare function createProcessGitRunner(cwd: string): ReviewGitRunner;
+/** 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. */
+export declare function computeReviewRulesDigest(cwd: string): Promise<string>;
+/** The frozen review instruction set assembled for the model. */
+export declare function buildReviewSystemPrompt(rulesDigest: string): string;
+/**
+ * Runs one bounded review. Never throws for expected review failures — the
+ * outcome is typed; unexpected internal errors surface as `model_error`.
+ */
+export declare function runCodeReview(options: ReviewRunOptionsV1): Promise<ReviewRunOutcomeV1>;
+export { DEFAULT_REVIEW_BUDGETS };
+//# sourceMappingURL=runner.d.ts.map

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

@@ -0,0 +1,354 @@
+"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),
+        });
+        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,83 @@
+"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/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@orion-agents/orion-code",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@orion-agents/orion-code",
-      "version": "0.3.27",
+      "version": "0.3.28",
       "license": "MIT",
       "dependencies": {
         "@clack/prompts": "^0.7.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orion-agents/orion-code",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "description": "Orion Code - local-first goal-driven coding agent for terminal and Web.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",