@orion-agents/orion-code 0.3.26 → 0.3.27

package/CHANGELOG.md

@@ -22,14 +22,54 @@ which is **not** a pass.
 
 ## [Unreleased]
 
-## [0.3.26] — UNRELEASED
-
-> **Status: candidate.** Open. Structured-diff integrity and Session lifecycle: body
-> rows that look like file headers stay body rows (#274), a hunk split across
-> pagination keeps its rows, line numbers and identity (#275), permanent Session
-> deletion removes the v2 Thread records (#276), and exiting a cutover Session no
-> longer rewrites its summary from the frozen legacy JSONL (#277). Plan:
-> `docs/plan/v0.3.26-plan.md`. Not merged, tagged or published.
+## [0.3.27] — UNRELEASED
+
+> **Status: candidate.** Open. 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
+> contract tests; the shared Git snapshot reader captures worktree (staged /
+> unstaged / untracked, separate sources) and base (frozen merge-base..HEAD
+> OIDs, rename tracking) scopes with typed scope errors; and the read-only
+> 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.
+
+### Added
+
+- #277-plan PR0: `src/services/code-review/contract.ts` — the shared review
+  contract with the plan §4.1 conclusion mapping (a partial, failed, cancelled
+  or untrustworthy review can never surface as a green "no findings"),
+  tighten-only budgets from plan §4.3, finding validation, receipt digests
+  verified by recomputation, and stale-applicability annotation that never
+  rewrites history. Twelve contract tests pin the semantics.
+- PR0: the human-annotation review-quality benchmark set (12 defect + 8 clean
+  samples across TypeScript/JavaScript/Python with content digests, expected
+  triggers, allowed locations and frozen scoring thresholds), awaiting
+  per-sample human sign-off before any paid model run (plan §9.3).
+- PR1: `src/services/code-review/snapshot.ts` — the shared Git snapshot reader:
+  worktree scope records staged (index OIDs), unstaged (working content with
+  before/after digest re-checks) and untracked changes as separate sources;
+  base scope freezes ref/HEAD/merge-base into immutable OIDs with rename
+  tracking and typed `ref_unresolved` / `no_merge_base` errors; sensitive and
+  binary entries are skipped without being read; tightened budgets skip the
+  excess with typed reasons; the contained worktree reader refuses to leave the
+  repository root.
+- PR1: `src/services/code-review/constraints.ts` — deny-by-default read-only
+  workflow constraints (only `read_file`, `list_files`, `glob`, `grep` pass the
+  dispatch-level guard) with a frozen digest that receipts bind.
+
+## [0.3.26] — 2026-10-17
+
+> **Status: published.** Released as `@orion-agents/orion-code@0.3.26` from
+> `refs/tags/v0.3.26`, and merged to `main` as `b810996` (#278). Structured-diff
+> integrity and Session lifecycle: header-lookalike body rows stay body rows
+> (#274), hunks split across pagination keep their rows, line numbers and
+> identity (#275), permanent Session deletion removes the v2 Thread records
+> (#276), and exiting a cutover Session no longer rewrites its summary from the
+> frozen legacy JSONL (#277). Plan: `docs/plan/v0.3.26-plan.md`. GitHub Release:
+> https://github.com/orion-agents/orion-code/releases/tag/v0.3.26
 
 ### Fixed
 

package/README.md

@@ -2,12 +2,14 @@
 
 Local-first, goal-driven coding agent for the terminal and browser.
 
-> v0.3.26 candidate — open. Structured-diff integrity and Session lifecycle: header-lookalike
-> body rows stay body rows (#274), hunks split across pagination keep their rows and line
-> numbers (#275), permanent Session deletion removes the v2 Thread records (#276), and
-> exiting a cutover Session no longer regresses its summary from the legacy JSONL (#277).
-> The previous release 0.3.25 is on npm (registry `latest`), tagged `v0.3.25` (`c356323`,
-> #273) and released on GitHub.
+> 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.
 
 [中文说明](README.zh-CN.md) ·
 [v0.3.24 plan](docs/plan/v0.3.24-plan.md) ·
@@ -170,10 +172,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.26 package when it is available on npm:
+To install the pinned v0.3.27 package when it is available on npm:
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.26
+npm install -g @orion-agents/orion-code@0.3.27
 orion --version
 orion doctor
 ```

package/README.zh-CN.md

@@ -2,10 +2,11 @@
 
 面向终端与浏览器、本地优先的目标驱动 Coding Agent。
 
-> v0.3.26 候选版本：进行中。结构化 diff 完整性与会话生命周期：形似文件头的 body 行保持为
-> body 行（#274）、跨页拆分的 hunk 保留行与行号（#275）、永久删除会话同时清除 v2 Thread
-> 记录（#276）、退出已切换会话不再从旧 JSONL 回退 summary（#277）。上一版 0.3.25 已发布
-> npm（registry `latest`）、打 tag `v0.3.25`（`c356323`，#273）并发布 GitHub Release。
+> 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。
 
 [English](README.md) ·
 [v0.3.24 方案](docs/plan/v0.3.24-plan.md) ·
@@ -100,10 +101,10 @@ MCP 仍是用户可见的扩展边界。
 支持 Node.js 22.12+、24 和 26。生产环境建议使用 Node 24 LTS，当前开发环境也支持 Node 26
 Current。Node 20 已结束上游维护，不再属于 v0.3 Runtime 合同。
 
-v0.3.26 在 npm 可用后，可安装固定版本：
+v0.3.27 在 npm 可用后，可安装固定版本：
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.26
+npm install -g @orion-agents/orion-code@0.3.27
 orion --version
 orion doctor
 ```

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

@@ -0,0 +1,25 @@
+/** Read-only tools the review turn may use. Only first-party core tools with
+ *  `readOnly: true` in their descriptors qualify (plan §5.1); `edit_file`,
+ *  `exec_command` and `write_file` are structurally excluded. */
+export declare const REVIEW_ALLOWED_TOOLS: ReadonlySet<string>;
+export interface ReviewWorkflowConstraintsV1 {
+    readonly schemaVersion: 1;
+    readonly workflow: 'code-review';
+    readonly allowedTools: readonly string[];
+    readonly constraintsDigest: string;
+    readonly policy: string;
+}
+/** The frozen constraint set with its digest. Receipts and capability
+ *  compilations bind this digest so a policy change invalidates old reviews'
+ *  rules provenance alongside the rules digest. */
+export declare const REVIEW_WORKFLOW_CONSTRAINTS: ReviewWorkflowConstraintsV1;
+export declare class ReviewToolPolicyError extends Error {
+    readonly code: 'review_tool_denied';
+    readonly toolName: string;
+    constructor(message: string, code: 'review_tool_denied', toolName: string);
+}
+/** Dispatch-level re-validation. Called on every tool invocation of a review
+ *  turn — direct calls, batch calls, aliases and steering all funnel through
+ *  here before the gateway executes anything. */
+export declare function assertReviewToolAllowed(toolName: string): void;
+//# sourceMappingURL=constraints.d.ts.map

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

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReviewToolPolicyError = exports.REVIEW_WORKFLOW_CONSTRAINTS = exports.REVIEW_ALLOWED_TOOLS = void 0;
+exports.assertReviewToolAllowed = assertReviewToolAllowed;
+/**
+ * v0.3.27 PR1 — read-only workflow constraints for code review (plan §5.1).
+ *
+ * The review turn runs through the normal AgentLoop / ToolGateway, but under
+ * immutable workflow constraints: the model only sees bounded read/list/glob/
+ * grep capabilities, and every dispatch re-validates against this module so
+ * aliases, batch calls, steering or permission escalation (AUTO / ALLOW) can
+ * never widen the turn. The constraint set is deny-by-default: a tool that is
+ * not explicitly allowlisted is rejected, which covers long-tail tools, MCP,
+ * network, task derivation and future additions without maintaining a denylist.
+ *
+ * PR2 wires this guard into the review workflow's dispatch; PR1 ships the
+ * frozen model, its digest, and the negative tests.
+ */
+const canonical_1 = require("../../runtime/protocol/canonical");
+/** Read-only tools the review turn may use. Only first-party core tools with
+ *  `readOnly: true` in their descriptors qualify (plan §5.1); `edit_file`,
+ *  `exec_command` and `write_file` are structurally excluded. */
+exports.REVIEW_ALLOWED_TOOLS = new Set([
+    'read_file',
+    'list_files',
+    'glob',
+    'grep',
+]);
+const REVIEW_CONSTRAINT_CONTENT = Object.freeze({
+    schemaVersion: 1,
+    workflow: 'code-review',
+    mode: 'read-only',
+    allowedTools: [...exports.REVIEW_ALLOWED_TOOLS].sort(),
+    deniedByDefault: Object.freeze([
+        'exec_command',
+        'write_file',
+        'edit_file',
+        'git mutations',
+        'mcp',
+        'network tools',
+        'dynamic skills',
+        'task derivation',
+        'settings mutation',
+    ]),
+    /** Rationale text is part of the digest: changing the policy changes every
+     *  receipt that binds it. */
+    policy: 'The review turn may only inspect the frozen snapshot through the ' +
+        'allowlisted read tools. Permission escalation (AUTO / ALLOW) may tighten ' +
+        'or maintain but never widen this set. Test commands are not run: they ' +
+        'can write caches and mutate the workspace under review.',
+});
+/** The frozen constraint set with its digest. Receipts and capability
+ *  compilations bind this digest so a policy change invalidates old reviews'
+ *  rules provenance alongside the rules digest. */
+exports.REVIEW_WORKFLOW_CONSTRAINTS = Object.freeze({
+    schemaVersion: 1,
+    workflow: 'code-review',
+    allowedTools: REVIEW_CONSTRAINT_CONTENT.allowedTools,
+    constraintsDigest: (0, canonical_1.digestRuntimeValue)(REVIEW_CONSTRAINT_CONTENT),
+    policy: REVIEW_CONSTRAINT_CONTENT.policy,
+});
+class ReviewToolPolicyError extends Error {
+    constructor(message, code, toolName) {
+        super(message);
+        this.code = code;
+        this.toolName = toolName;
+        this.name = 'ReviewToolPolicyError';
+    }
+}
+exports.ReviewToolPolicyError = ReviewToolPolicyError;
+/** Dispatch-level re-validation. Called on every tool invocation of a review
+ *  turn — direct calls, batch calls, aliases and steering all funnel through
+ *  here before the gateway executes anything. */
+function assertReviewToolAllowed(toolName) {
+    if (!exports.REVIEW_ALLOWED_TOOLS.has(toolName)) {
+        throw new ReviewToolPolicyError(`Tool "${toolName}" is not available in a read-only code review turn.`, 'review_tool_denied', toolName);
+    }
+}
+//# sourceMappingURL=constraints.js.map

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

@@ -0,0 +1,172 @@
+/** v0.3.27 §3.1 — what a review examines. Parsed once, frozen at admission. */
+export type ReviewSelectorV1 = {
+    readonly kind: 'worktree';
+    readonly paths?: readonly string[];
+} | {
+    readonly kind: 'base';
+    readonly ref: string;
+    readonly paths?: readonly string[];
+};
+/** v0.3.27 §4.1 — run states. `queued`/`running` never carry a conclusion. */
+export type ReviewRunStateV1 = 'queued' | 'running' | 'completed' | 'partial' | 'failed' | 'cancelled';
+/** v0.3.27 §4.1 — terminal conclusions. Absence can only be asserted when the
+ *  state is `completed`, coverage is complete and the output contained no
+ *  invalid findings; everything else maps to findings or inconclusive. */
+export type ReviewConclusionV1 = 'findings' | 'no_findings' | 'inconclusive';
+/** v0.3.27 §6.1 — a stored result's applicability after code or rules change.
+ *  History is never rewritten; staleness is an annotation, not an edit. */
+export type ReviewApplicabilityV1 = 'current' | 'stale';
+/** Priority levels. P0 requires evidence that the defect blocks usage without
+ *  special preconditions; the definition is frozen here and in PR0 tests. */
+export type ReviewFindingPriorityV1 = 'P0' | 'P1' | 'P2' | 'P3';
+/** v0.3.27 §4.1 — one review finding. `fileKey` is validated for shape here;
+ *  membership against the frozen snapshot manifest happens at Host validation
+ *  time (PR1+), never in the model's favor. */
+export interface ReviewFindingV1 {
+    readonly findingId: string;
+    readonly priority: ReviewFindingPriorityV1;
+    readonly title: string;
+    /** The condition under which the defect manifests — not a style opinion. */
+    readonly trigger: string;
+    readonly impact: string;
+    readonly fileKey: string;
+    readonly side: 'old' | 'new';
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly evidence: string;
+}
+/** Coverage is evidence, not a count: what was actually inspected, what was
+ *  skipped and why, and where truncation or budget exhaustion occurred. */
+export interface ReviewCoverageV1 {
+    readonly inspectedFiles: readonly string[];
+    readonly inspectedRanges: readonly {
+        readonly fileKey: string;
+        readonly startLine: number;
+        readonly endLine: number;
+    }[];
+    readonly skipped: readonly {
+        readonly fileKey: string;
+        readonly reason: 'over_budget_files' | 'over_budget_bytes' | 'binary' | 'sensitive' | 'unreadable' | 'changed_during_review' | 'other';
+        readonly detail?: string;
+    }[];
+    readonly truncated: boolean;
+    readonly budgetExhausted: readonly string[];
+}
+/** Whether the declared coverage is internally consistent and complete for the
+ *  resolved selector — computed by the Host from the frozen manifest, never
+ *  taken from the model's self-report (§4.1). */
+export interface ReviewCoverageAssertionV1 {
+    readonly complete: boolean;
+    readonly reason?: string;
+}
+/** v0.3.27 §4.1 — the persisted receipt. `receiptDigest` covers the canonical
+ *  form of everything above it and is recomputed on read. */
+export interface CodeReviewResultV1 {
+    readonly schemaVersion: 1;
+    readonly reviewId: string;
+    readonly workspaceIdentity: string;
+    readonly sessionId: string;
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly requestedSelector: ReviewSelectorV1;
+    /** The actually resolved target (commit OIDs, snapshot ids), not the request. */
+    readonly resolvedTarget: {
+        readonly kind: 'worktree' | 'base';
+        readonly baseOid?: string;
+        readonly headOid?: string;
+        readonly snapshotId: string;
+    };
+    /** Digest of the frozen input snapshot; a stored result is stale when this
+     *  no longer matches the current snapshot digest for the same selector. */
+    readonly inputSnapshotDigest: string;
+    readonly rulesDigest: string;
+    readonly state: ReviewRunStateV1;
+    readonly conclusion: ReviewConclusionV1;
+    readonly findings: readonly ReviewFindingV1[];
+    /** Findings that failed validation — counted and surfaced, never silently
+     *  dropped (dropping them must not turn the run into no_findings). */
+    readonly invalidFindingCount: number;
+    readonly coverage: ReviewCoverageV1;
+    readonly coverageAssertion: ReviewCoverageAssertionV1;
+    readonly limits: readonly string[];
+    readonly model: {
+        readonly provider: string;
+        readonly model: string;
+    };
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+    readonly startedAt: number;
+    readonly endedAt: number;
+    readonly receiptDigest: string;
+}
+/** Budgets are ceilings that may only be tightened (§4.3): a provider with a
+ *  smaller window takes the stricter value; nothing may widen them at runtime. */
+export interface ReviewBudgetsV1 {
+    readonly maxFiles: number;
+    readonly maxBodyBytes: number;
+    readonly maxDiffBytes: number;
+    readonly maxReadToolCalls: number;
+    readonly maxDurationMs: number;
+    readonly maxFindings: number;
+    readonly maxResultBytes: number;
+}
+export declare const DEFAULT_REVIEW_BUDGETS: ReviewBudgetsV1;
+/** Text size caps for finding fields, in characters. Chosen so 100 maximal
+ *  findings stay well inside the 256 KiB result bound. */
+export declare const FINDING_TEXT_LIMITS: Readonly<{
+    title: 200;
+    trigger: 2000;
+    impact: 2000;
+    evidence: 4000;
+    fileKey: 1024;
+}>;
+/** Validates one model-produced finding against the frozen shape. Returns the
+ *  finding unchanged when valid; a typed reason when not. Membership against
+ *  the snapshot manifest is a separate Host check (PR1+). */
+export declare function validateReviewFinding(value: unknown): {
+    readonly valid: true;
+    readonly finding: ReviewFindingV1;
+} | {
+    readonly valid: false;
+    readonly reason: 'not_an_object' | 'finding_id_invalid' | 'priority_invalid' | 'title_invalid' | 'trigger_invalid' | 'impact_invalid' | 'file_key_invalid' | 'side_invalid' | 'line_range_invalid' | 'evidence_invalid';
+};
+/**
+ * v0.3.27 §4.1 — the conclusion mapping, frozen as code so CLI and Web cannot
+ * diverge. The invariants:
+ * - `queued`/`running` results carry no conclusion (callers must not call this).
+ * - A state that is not `completed` can never conclude `no_findings`.
+ * - Invalid findings make the output untrustworthy: zero valid findings with
+ *   invalid ones present is `inconclusive`, never a green pass.
+ * - Zero findings without complete coverage is `inconclusive`, never a green
+ *   pass ("不静默截断后宣布全部完成").
+ */
+export declare function resolveReviewConclusion(input: {
+    readonly state: ReviewRunStateV1;
+    readonly validFindingCount: number;
+    readonly invalidFindingCount: number;
+    readonly coverageComplete: boolean;
+}): ReviewConclusionV1;
+/** Applies the budgets with the tighten-only rule: every override must be a
+ *  safe integer at or below the frozen default, otherwise the run is refused
+ *  rather than silently widened. */
+export declare function resolveReviewBudgets(overrides?: Partial<ReviewBudgetsV1>): {
+    readonly ok: true;
+    readonly budgets: ReviewBudgetsV1;
+} | {
+    readonly ok: false;
+    readonly field: string;
+};
+/** Marks a stored result's applicability against the current input snapshot and
+ *  rules digests. The receipt itself is never rewritten. */
+export declare function reviewApplicability(result: Pick<CodeReviewResultV1, 'inputSnapshotDigest' | 'rulesDigest'>, current: {
+    readonly inputSnapshotDigest: string;
+    readonly rulesDigest: string;
+}): ReviewApplicabilityV1;
+/** The receipt digest covers the canonical form of the result with the digest
+ *  field itself excluded, so verification is a recomputation, not a lookup. */
+export declare function computeReceiptDigest(result: Omit<CodeReviewResultV1, 'receiptDigest'>): string;
+/** Verifies a stored receipt by recomputing its digest. */
+export declare function verifyReceiptDigest(result: CodeReviewResultV1): boolean;
+//# sourceMappingURL=contract.d.ts.map

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

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FINDING_TEXT_LIMITS = exports.DEFAULT_REVIEW_BUDGETS = void 0;
+exports.validateReviewFinding = validateReviewFinding;
+exports.resolveReviewConclusion = resolveReviewConclusion;
+exports.resolveReviewBudgets = resolveReviewBudgets;
+exports.reviewApplicability = reviewApplicability;
+exports.computeReceiptDigest = computeReceiptDigest;
+exports.verifyReceiptDigest = verifyReceiptDigest;
+/**
+ * v0.3.27 PR0 — the shared code-review contract, frozen before any runtime
+ * wiring. This module is the single source of truth for review selectors,
+ * states, conclusions, findings, budgets and receipt digests; CLI and Web both
+ * consume it and neither may redefine the semantics locally (goal G3: one
+ * engine, one contract).
+ *
+ * Design sources: docs/plan/v0.3.27-plan.md §4 (identity, state, conclusions),
+ * §4.3 (bounded resources), §5 (read-only execution). The conclusion mapping
+ * encodes the plan's rule that tool success is not review success: a partial,
+ * failed, cancelled or untrustworthy output can never surface as a green
+ * "no findings".
+ */
+const canonical_1 = require("../../runtime/protocol/canonical");
+exports.DEFAULT_REVIEW_BUDGETS = Object.freeze({
+    maxFiles: 50,
+    maxBodyBytes: 2 * 1024 * 1024,
+    maxDiffBytes: 1024 * 1024,
+    maxReadToolCalls: 50,
+    maxDurationMs: 5 * 60 * 1000,
+    maxFindings: 100,
+    maxResultBytes: 256 * 1024,
+});
+/** Text size caps for finding fields, in characters. Chosen so 100 maximal
+ *  findings stay well inside the 256 KiB result bound. */
+exports.FINDING_TEXT_LIMITS = Object.freeze({
+    title: 200,
+    trigger: 2000,
+    impact: 2000,
+    evidence: 4000,
+    fileKey: 1024,
+});
+const FINDING_ID_PATTERN = /^[0-9a-f]{8,64}$/iu;
+const DIGEST_PATTERN = /^[0-9a-f]{64}$/;
+/** Validates one model-produced finding against the frozen shape. Returns the
+ *  finding unchanged when valid; a typed reason when not. Membership against
+ *  the snapshot manifest is a separate Host check (PR1+). */
+function validateReviewFinding(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return { valid: false, reason: 'not_an_object' };
+    }
+    const candidate = value;
+    const text = (field) => typeof candidate[field] === 'string' ? candidate[field] : '';
+    if (typeof candidate.findingId !== 'string' || !FINDING_ID_PATTERN.test(candidate.findingId)) {
+        return { valid: false, reason: 'finding_id_invalid' };
+    }
+    if (candidate.priority !== 'P0' &&
+        candidate.priority !== 'P1' &&
+        candidate.priority !== 'P2' &&
+        candidate.priority !== 'P3') {
+        return { valid: false, reason: 'priority_invalid' };
+    }
+    const title = text('title').trim();
+    if (!title || title.length > exports.FINDING_TEXT_LIMITS.title) {
+        return { valid: false, reason: 'title_invalid' };
+    }
+    const trigger = text('trigger').trim();
+    if (!trigger || trigger.length > exports.FINDING_TEXT_LIMITS.trigger) {
+        return { valid: false, reason: 'trigger_invalid' };
+    }
+    const impact = text('impact').trim();
+    if (!impact || impact.length > exports.FINDING_TEXT_LIMITS.impact) {
+        return { valid: false, reason: 'impact_invalid' };
+    }
+    const fileKey = text('fileKey');
+    if (!fileKey ||
+        fileKey.length > exports.FINDING_TEXT_LIMITS.fileKey ||
+        fileKey.startsWith('/') ||
+        fileKey.includes('\0') ||
+        fileKey.split('/').includes('..')) {
+        return { valid: false, reason: 'file_key_invalid' };
+    }
+    if (candidate.side !== 'old' && candidate.side !== 'new') {
+        return { valid: false, reason: 'side_invalid' };
+    }
+    const startLine = candidate.startLine;
+    const endLine = candidate.endLine;
+    if (!Number.isSafeInteger(startLine) ||
+        startLine < 1 ||
+        !Number.isSafeInteger(endLine) ||
+        endLine < startLine) {
+        return { valid: false, reason: 'line_range_invalid' };
+    }
+    const evidence = text('evidence').trim();
+    if (!evidence || evidence.length > exports.FINDING_TEXT_LIMITS.evidence) {
+        return { valid: false, reason: 'evidence_invalid' };
+    }
+    return {
+        valid: true,
+        finding: Object.freeze({
+            findingId: candidate.findingId,
+            priority: candidate.priority,
+            title,
+            trigger,
+            impact,
+            fileKey,
+            side: candidate.side,
+            startLine: startLine,
+            endLine: endLine,
+            evidence,
+        }),
+    };
+}
+/**
+ * v0.3.27 §4.1 — the conclusion mapping, frozen as code so CLI and Web cannot
+ * diverge. The invariants:
+ * - `queued`/`running` results carry no conclusion (callers must not call this).
+ * - A state that is not `completed` can never conclude `no_findings`.
+ * - Invalid findings make the output untrustworthy: zero valid findings with
+ *   invalid ones present is `inconclusive`, never a green pass.
+ * - Zero findings without complete coverage is `inconclusive`, never a green
+ *   pass ("不静默截断后宣布全部完成").
+ */
+function resolveReviewConclusion(input) {
+    if (input.state === 'queued' || input.state === 'running') {
+        throw new Error('A queued or running review cannot have a terminal conclusion.');
+    }
+    if (input.state === 'failed' || input.state === 'cancelled') {
+        return 'inconclusive';
+    }
+    if (input.validFindingCount > 0) {
+        return 'findings';
+    }
+    if (input.state === 'partial') {
+        return 'inconclusive';
+    }
+    // state === 'completed'
+    if (input.invalidFindingCount > 0) {
+        return 'inconclusive';
+    }
+    return input.coverageComplete ? 'no_findings' : 'inconclusive';
+}
+/** Applies the budgets with the tighten-only rule: every override must be a
+ *  safe integer at or below the frozen default, otherwise the run is refused
+ *  rather than silently widened. */
+function resolveReviewBudgets(overrides = {}) {
+    const resolved = {};
+    for (const [field, ceiling] of Object.entries(exports.DEFAULT_REVIEW_BUDGETS)) {
+        const requested = overrides[field];
+        if (requested === undefined) {
+            resolved[field] = ceiling;
+            continue;
+        }
+        if (!Number.isSafeInteger(requested) || requested < 1 || requested > ceiling) {
+            return { ok: false, field };
+        }
+        resolved[field] = requested;
+    }
+    return {
+        ok: true,
+        budgets: Object.freeze(resolved),
+    };
+}
+/** Marks a stored result's applicability against the current input snapshot and
+ *  rules digests. The receipt itself is never rewritten. */
+function reviewApplicability(result, current) {
+    return result.inputSnapshotDigest === current.inputSnapshotDigest &&
+        result.rulesDigest === current.rulesDigest
+        ? 'current'
+        : 'stale';
+}
+/** The receipt digest covers the canonical form of the result with the digest
+ *  field itself excluded, so verification is a recomputation, not a lookup. */
+function computeReceiptDigest(result) {
+    const content = { ...result };
+    delete content.receiptDigest;
+    const digest = (0, canonical_1.digestRuntimeValue)(content);
+    return DIGEST_PATTERN.test(digest) ? digest : digest.toLowerCase();
+}
+/** Verifies a stored receipt by recomputing its digest. */
+function verifyReceiptDigest(result) {
+    const { receiptDigest, ...content } = result;
+    return computeReceiptDigest(content) === receiptDigest;
+}
+//# sourceMappingURL=contract.js.map

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

@@ -0,0 +1,64 @@
+import { type ReviewBudgetsV1, type ReviewSelectorV1 } from './contract';
+export interface ReviewSnapshotFileSideV1 {
+    readonly source: 'staged' | 'unstaged' | 'base' | 'head';
+    readonly oid: string | null;
+    readonly contentDigest: string;
+    readonly byteSize: number;
+    readonly truncated: boolean;
+}
+export interface ReviewSnapshotHunkV1 {
+    readonly oldStart: number;
+    readonly oldLines: number;
+    readonly newStart: number;
+    readonly newLines: number;
+    readonly header: string;
+}
+export interface ReviewSnapshotFileV1 {
+    readonly fileKey: string;
+    readonly path: string;
+    readonly oldPath: string | null;
+    readonly sensitive: boolean;
+    readonly sides: readonly ReviewSnapshotFileSideV1[];
+    readonly hunks: readonly ReviewSnapshotHunkV1[];
+}
+export interface ReviewSnapshotSkipV1 {
+    readonly path: string;
+    readonly reason: 'over_budget_files' | 'over_budget_bytes' | 'binary' | 'sensitive' | 'unreadable' | 'changed_during_review' | 'other';
+    readonly detail?: string;
+}
+export interface CodeReviewSnapshotV1 {
+    readonly schemaVersion: 1;
+    readonly snapshotId: string;
+    readonly kind: 'worktree' | 'base';
+    readonly baseOid: string | null;
+    readonly headOid: string | null;
+    readonly requestedPaths: readonly string[];
+    readonly files: readonly ReviewSnapshotFileV1[];
+    readonly inputSnapshotDigest: string;
+    readonly skipped: readonly ReviewSnapshotSkipV1[];
+}
+export declare class ReviewSnapshotError extends Error {
+    readonly code: 'not_a_repository' | 'ref_unresolved' | 'no_merge_base' | 'path_invalid' | 'worktree_changed';
+    constructor(message: string, code: 'not_a_repository' | 'ref_unresolved' | 'no_merge_base' | 'path_invalid' | 'worktree_changed');
+}
+/** Runs a read-only git command with argument arrays. The caller injects this,
+ *  so tests drive real temporary repositories without spawning beyond git. */
+export type ReviewGitRunner = (args: readonly string[]) => Promise<string>;
+export interface ReviewSnapshotOptionsV1 {
+    readonly root: string;
+    readonly selector: ReviewSelectorV1;
+    readonly budgets?: Partial<ReviewBudgetsV1>;
+    readonly runGit: ReviewGitRunner;
+    /** Reads one working-tree file relative to the root, or null when missing. */
+    readonly readWorktreeFile?: (relativePath: string) => Promise<string | null>;
+    readonly snapshotIdPrefix?: 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. */
+export declare function captureReviewSnapshot(options: ReviewSnapshotOptionsV1): Promise<CodeReviewSnapshotV1>;
+/** Reads one working-tree file for review purposes, refusing to leave the
+ *  repository root (same containment discipline as the v0.3.25 conflict
+ *  reader). Returns null when the file is missing or unreadable. */
+export declare function createContainedWorktreeReader(rootInput: string): (relativePath: string) => Promise<string | null>;
+//# sourceMappingURL=snapshot.d.ts.map

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

@@ -0,0 +1,321 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReviewSnapshotError = void 0;
+exports.captureReviewSnapshot = captureReviewSnapshot;
+exports.createContainedWorktreeReader = createContainedWorktreeReader;
+/**
+ * v0.3.27 PR1 — the minimal shared Git snapshot reader for code review
+ * (plan §4.2). One reader, two scopes:
+ *
+ *  - `worktree`: staged, unstaged and untracked changes are recorded as
+ *    separate sources for the same path and are never merged into one
+ *    composite diff.
+ *  - `base`: the ref, HEAD and merge-base are resolved to immutable OIDs at
+ *    admission; later ref movement cannot change the frozen input.
+ *
+ * Security posture (§4.2.7): git runs with argument arrays through the read
+ * profile, never a shell; external diff drivers and textconv are disabled;
+ * blobs are read by OID; untracked working files are read directly under the
+ * same sensitive/binary/boundary policies as everything else. No optional
+ * locks, no arbitrary subcommands exposed to the model.
+ */
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const redaction_1 = require("../redaction");
+const contract_1 = require("./contract");
+class ReviewSnapshotError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'ReviewSnapshotError';
+    }
+}
+exports.ReviewSnapshotError = ReviewSnapshotError;
+function sha256(value) {
+    return (0, crypto_1.createHash)('sha256').update(value, 'utf8').digest('hex');
+}
+function assertSafePath(value) {
+    if (!value ||
+        value.length > 1024 ||
+        value.startsWith('/') ||
+        value.includes('\0') ||
+        value.split('/').includes('..')) {
+        throw new ReviewSnapshotError(`Unsafe review path: ${value}`, 'path_invalid');
+    }
+    return value;
+}
+/** Parses `git diff --name-status -z` records into status/path groups. */
+function parseNameStatusZ(records) {
+    const parsed = [];
+    let index = 0;
+    while (index < records.length) {
+        const record = records[index];
+        if (!record) {
+            index += 1;
+            continue;
+        }
+        const status = record.slice(0, 1);
+        const paths = [];
+        if (status === 'R' || status === 'C') {
+            paths.push(records[index + 1] ?? '', records[index + 2] ?? '');
+            index += 3;
+        }
+        else {
+            paths.push(records[index + 1] ?? '');
+            index += 2;
+        }
+        parsed.push({ status, paths });
+    }
+    return parsed;
+}
+function parseDiffHunks(diffText) {
+    const files = [];
+    let current;
+    const HUNK = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(.*)$/;
+    for (const line of diffText.split('\n')) {
+        if (line.startsWith('diff --git ')) {
+            const rest = line.slice('diff --git '.length);
+            const split = rest.indexOf(' b/');
+            current = {
+                path: split >= 0 ? rest.slice(split + 3) : rest,
+                hunks: [],
+                diffBytes: 0,
+            };
+            files.push(current);
+            continue;
+        }
+        if (!current)
+            continue;
+        current.diffBytes += line.length + 1;
+        const header = HUNK.exec(line);
+        if (header) {
+            current.hunks.push({
+                oldStart: Number(header[1]),
+                oldLines: header[2] === undefined ? 1 : Number(header[2]),
+                newStart: Number(header[3]),
+                newLines: header[4] === undefined ? 1 : Number(header[4]),
+                header: line,
+            });
+        }
+    }
+    return files;
+}
+function pathMatches(path, requestedPaths) {
+    if (requestedPaths.length === 0)
+        return true;
+    return requestedPaths.some(filter => path === filter || path.startsWith(`${filter}/`));
+}
+/** 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. */
+async function captureReviewSnapshot(options) {
+    const budgets = { ...contract_1.DEFAULT_REVIEW_BUDGETS, ...options.budgets };
+    const { runGit } = options;
+    const requestedPaths = (options.selector.paths ?? []).map(assertSafePath);
+    let baseOid = null;
+    let headOid = null;
+    let nameStatusArgs;
+    let unifiedArgs;
+    if (options.selector.kind === 'base') {
+        headOid = (await runGit(['rev-parse', '--verify', 'HEAD'])).trim();
+        const refOid = (await runGit(['rev-parse', '--verify', `${options.selector.ref}^{commit}`]).catch(() => '')).trim();
+        if (!refOid) {
+            throw new ReviewSnapshotError(`Review base ref could not be resolved: ${options.selector.ref}`, 'ref_unresolved');
+        }
+        baseOid = (await runGit(['merge-base', refOid, headOid]).catch(() => '')).trim();
+        if (!baseOid) {
+            throw new ReviewSnapshotError(`No merge base between ${options.selector.ref} and HEAD`, 'no_merge_base');
+        }
+        nameStatusArgs = [
+            'diff',
+            '--no-ext-diff',
+            '--no-textconv',
+            '--find-renames',
+            '--name-status',
+            '-z',
+            baseOid,
+            headOid,
+        ];
+        unifiedArgs = ['diff', '--no-ext-diff', '--no-textconv', baseOid, headOid];
+    }
+    else {
+        nameStatusArgs = [
+            'diff',
+            '--no-ext-diff',
+            '--no-textconv',
+            '--find-renames',
+            '--name-status',
+            '-z',
+            'HEAD',
+        ];
+        unifiedArgs = ['diff', '--no-ext-diff', '--no-textconv', 'HEAD'];
+    }
+    const nameStatusRaw = await runGit(nameStatusArgs);
+    const changed = parseNameStatusZ(nameStatusRaw.split('\0')).filter(entry => {
+        const path = entry.paths.at(-1);
+        return Boolean(path) && pathMatches(path, requestedPaths);
+    });
+    const files = [];
+    const skipped = [];
+    const seenPaths = new Set();
+    for (const entry of changed) {
+        const path = assertSafePath(entry.paths.at(-1));
+        if (seenPaths.has(path))
+            continue;
+        if (files.length >= budgets.maxFiles) {
+            skipped.push({ path, reason: 'over_budget_files' });
+            continue;
+        }
+        seenPaths.add(path);
+        const oldPath = entry.status === 'R' || entry.status === 'C' ? (entry.paths[0] ?? null) : null;
+        const sensitive = (0, redaction_1.isSensitiveFilePath)(path) || (oldPath ? (0, redaction_1.isSensitiveFilePath)(oldPath) : false);
+        if (sensitive) {
+            skipped.push({ path, reason: 'sensitive' });
+            continue;
+        }
+        if (entry.status === 'B') {
+            skipped.push({ path, reason: 'binary' });
+            continue;
+        }
+        files.push({
+            fileKey: sha256(`${entry.status}:${oldPath ?? ''}:${path}`).slice(0, 16),
+            path,
+            oldPath,
+            sensitive: false,
+            sides: [],
+            hunks: [],
+        });
+    }
+    const parsedFiles = parseDiffHunks(await runGit(unifiedArgs));
+    for (const file of files) {
+        const match = parsedFiles.find(candidate => candidate.path === file.path);
+        if (match)
+            file.hunks.push(...match.hunks);
+    }
+    for (const file of files) {
+        const totalDiff = file.hunks.reduce((sum, hunk) => sum + hunk.oldLines + hunk.newLines, 0);
+        if (totalDiff * 128 > budgets.maxDiffBytes) {
+            skipped.push({ path: file.path, reason: 'over_budget_bytes' });
+            continue;
+        }
+        if (options.selector.kind === 'base') {
+            const headOidForPath = (await runGit(['rev-parse', '--verify', `${headOid}:${file.path}`]).catch(() => '')).trim();
+            const baseOidForPath = (await runGit([
+                'rev-parse',
+                '--verify',
+                `${baseOid}:${file.oldPath ?? file.path}`,
+            ]).catch(() => '')).trim();
+            if (headOidForPath) {
+                file.sides.push({
+                    source: 'head',
+                    oid: headOidForPath,
+                    contentDigest: headOidForPath,
+                    byteSize: Number((await runGit(['cat-file', '-s', headOidForPath])).trim()) || 0,
+                    truncated: false,
+                });
+            }
+            if (baseOidForPath) {
+                file.sides.push({
+                    source: 'base',
+                    oid: baseOidForPath,
+                    contentDigest: baseOidForPath,
+                    byteSize: Number((await runGit(['cat-file', '-s', baseOidForPath])).trim()) || 0,
+                    truncated: false,
+                });
+            }
+        }
+        else {
+            const indexOid = (await runGit(['ls-files', '-s', '-z', '--', file.path]).then(raw => {
+                const record = raw.split('\0').find(item => item.length > 0);
+                return record ? (record.split(' ')[1] ?? '') : '';
+            })).trim();
+            if (indexOid) {
+                file.sides.push({
+                    source: 'staged',
+                    oid: indexOid,
+                    contentDigest: indexOid,
+                    byteSize: Number((await runGit(['cat-file', '-s', indexOid])).trim()) || 0,
+                    truncated: false,
+                });
+            }
+            if (options.readWorktreeFile) {
+                const before = await options.readWorktreeFile(file.path);
+                if (before === null) {
+                    file.sides.push({
+                        source: 'unstaged',
+                        oid: null,
+                        contentDigest: sha256(''),
+                        byteSize: 0,
+                        truncated: false,
+                    });
+                }
+                else {
+                    const beforeDigest = sha256(before);
+                    const after = await options.readWorktreeFile(file.path);
+                    if (after === null || sha256(after) !== beforeDigest) {
+                        throw new ReviewSnapshotError(`Working file changed while snapshotting: ${file.path}`, 'worktree_changed');
+                    }
+                    file.sides.push({
+                        source: 'unstaged',
+                        oid: null,
+                        contentDigest: beforeDigest,
+                        byteSize: Buffer.byteLength(before, 'utf8'),
+                        truncated: before.length > budgets.maxBodyBytes,
+                    });
+                }
+            }
+        }
+    }
+    const manifest = {
+        kind: options.selector.kind,
+        baseOid,
+        headOid,
+        requestedPaths,
+        files: files.map(file => ({
+            fileKey: file.fileKey,
+            path: file.path,
+            oldPath: file.oldPath,
+            sides: file.sides.map(side => ({ source: side.source, contentDigest: side.contentDigest })),
+        })),
+    };
+    const inputSnapshotDigest = sha256(JSON.stringify(manifest));
+    const snapshotId = `${options.snapshotIdPrefix ?? 'rev'}-${inputSnapshotDigest.slice(0, 16)}`;
+    return Object.freeze({
+        schemaVersion: 1,
+        snapshotId,
+        kind: options.selector.kind,
+        baseOid,
+        headOid,
+        requestedPaths,
+        files: Object.freeze(files.map(file => Object.freeze({
+            ...file,
+            sides: Object.freeze(file.sides),
+            hunks: Object.freeze(file.hunks),
+        }))),
+        inputSnapshotDigest,
+        skipped: Object.freeze(skipped),
+    });
+}
+/** Reads one working-tree file for review purposes, refusing to leave the
+ *  repository root (same containment discipline as the v0.3.25 conflict
+ *  reader). Returns null when the file is missing or unreadable. */
+function createContainedWorktreeReader(rootInput) {
+    const root = (0, fs_1.realpathSync)(rootInput);
+    return async (relativePath) => {
+        try {
+            const absolute = (0, path_1.resolve)(root, relativePath);
+            const fileReal = (0, fs_1.realpathSync)(absolute);
+            if (fileReal !== root && !fileReal.startsWith(root + path_1.sep))
+                return null;
+            if (!(0, fs_1.statSync)(fileReal).isFile())
+                return null;
+            return await (0, promises_1.readFile)(fileReal, 'utf8');
+        }
+        catch {
+            return null;
+        }
+    };
+}
+//# sourceMappingURL=snapshot.js.map

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@orion-agents/orion-code",
-  "version": "0.3.26",
+  "version": "0.3.27",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@orion-agents/orion-code",
-      "version": "0.3.26",
+      "version": "0.3.27",
       "license": "MIT",
       "dependencies": {
         "@clack/prompts": "^0.7.0",
@@ -4293,9 +4293,9 @@
       "license": "ISC"
     },
     "node_modules/follow-redirects": {
-      "version": "1.16.0",
-      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.16.0.tgz",
-      "integrity": "sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw==",
+      "version": "1.16.1",
+      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.16.1.tgz",
+      "integrity": "sha512-FNvFGzoMLWmE6Yj9spb/zjd7yiNCHiAW9/Tg9CXrQ8wuu32HtlJOwWO11OJafl5FfY3DxTdQ0vj42zU1kvv5jg==",
       "funding": [
         {
           "type": "individual",
@@ -4563,13 +4563,13 @@
       "license": "MIT"
     },
     "node_modules/handlebars": {
-      "version": "4.7.9",
-      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.9.tgz",
-      "integrity": "sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ==",
+      "version": "4.7.10",
+      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.10.tgz",
+      "integrity": "sha512-P5VJMVM7qgBn6vjXMw8WG9uVI+ncf2pi72j4de4yz5ZULLj2RGqLYaKOYGsgyrViQ0tePOVlN1tDCCXXtFqXKg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "minimist": "^1.2.5",
+        "minimist": "^1.2.8",
         "neo-async": "^2.6.2",
         "source-map": "^0.6.1",
         "wordwrap": "^1.0.0"
@@ -7147,9 +7147,9 @@
       }
     },
     "node_modules/source-map-js": {
-      "version": "1.2.1",
-      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
-      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.2.tgz",
+      "integrity": "sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==",
       "dev": true,
       "license": "BSD-3-Clause",
       "engines": {

package/package.json

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