@orion-agents/orion-code 0.3.11 → 0.3.12

package/CHANGELOG.md

@@ -22,9 +22,54 @@ which is **not** a pass.
 
 ## [Unreleased]
 
-## [0.3.11] — CANDIDATE
+## [0.3.12] — CANDIDATE
 
-> **Status: candidate.** Not merged, tagged or published to npm.
+> **Status: candidate.** Wide Right Workspace + repository-truth + guarded Git
+> mutations (plan docs/plan/v0.3.12-plan.md) plus the v0.3.13 follow-ups that
+> landed on this branch (plans v3/v4/v5). Not merged, tagged or published.
+
+### Added
+
+- Wide Right Workspace logic layer: five-panel registry, per-workspace layout
+  preferences (schema v4 with per-panel navigator widths), pure dock/rail/drawer
+  geometry with 320px conversation minimum and 360/560/960/max snap points.
+- Repository snapshot store shared by Git/Review/Files decorations
+  (coalescing, one-shot invalidation, revision-stale detection).
+- Progressive Review verification paging (GET /review/verification).
+- Guarded Git stage/unstage/commit (POST /git/\*) with host-resolved file ids,
+  repository-revision CAS and an explicit user-gesture header.
+- Bounded workspace search (GET /files/search; name/content scopes).
+- Context V2 file_range references (revision-bound, line-extracted, budgeted).
+- **Resource split layout (v0.3.13-plan-v4):** Files/Git/Review share one
+  content | splitter | navigator shell (`ResourceSplitLayout`) with explicit
+  named grid areas (no more sparse grid auto-placement gaps). Git now shows its
+  diff on the left, matching Files/Review. Each panel has an inner draggable
+  separator measured against the split root — never the workbench shell — so
+  dragging never moves the outer Right Workspace; per-workspace + per-panel
+  navigator widths are persisted (300px default, 160–420px drag range,
+  double-click/keyboard reset), and <=620px containers stack navigator-over-
+  content and hide the handle.
+- **Conversation history navigator (v0.3.13-plan-v5):** a left-inside rail on
+  the loaded transcript derived from the unified order timeline. A pure bucket
+  model (<=48–64 stable buckets, user/assistant/errors always visible) feeds
+  decorative ticks plus one focusable `role="slider"` (Arrow/Page/Home/End,
+  reduced-motion aware). An IntersectionObserver + rAF-throttled viewport
+  marker tracks the reading position; pointer scrub uses capture and cancels
+  pinned auto-follow; the top entry drives the existing paginated
+  load-earlier. Container-query degradation: full rail >760px, compact
+  641–760px, hidden <=640px with no horizontal overflow.
+- **Unified Orion brand mark (v0.3.13-plan-v5 §9):** one decorative
+  `OrionBrandMark` inline SVG (20×20 artboard, three bars, theme-token
+  gradients with forced-colors fallback) replaces the duplicated
+  `.brand-mark`/`.boot-mark` span CSS in the project navigator and boot
+  screen; the mark stays aria-hidden and non-interactive.
+- E2E: rail-panel scenario ids on the allowlist; real-conversation smoke spec;
+  Files/Review/Git split-layout, history-rail and brand visual specs.
+
+## [0.3.11] — NPM-PUBLISHED
+
+> **Status: npm-published.** `@orion-agents/orion-code@0.3.11` is available through the npm
+> registry (latest tag). Published 2026-09-05; git tag/release may lag.
 
 ### Added
 

package/README.md

@@ -2,10 +2,13 @@
 
 Local-first, goal-driven coding agent for the terminal and browser.
 
-> v0.3.11 candidate — the right work panel is a vertical-rail menu: a persistent
-> 48px icon rail shows exactly the panel you click (re-click collapses, Esc
-> closes), carries terminal status badges, and honors a persisted icon order.
-> Candidate source is not an npm publication, Git tag, or merge-ready release.
+> v0.3.12 candidate — a Wide Right Workspace on top of the vertical rail: pure
+> dock/rail/drawer geometry (detail dockable to 80vw while the conversation
+> keeps a 320px minimum), per-workspace layout preferences, a shared repository
+> snapshot store, progressive Review verification, guarded Git stage/unstage/
+> commit, bounded workspace search and revision-bound file_range Context
+> references. Candidate source is not an npm publication, Git tag, or
+> merge-ready release.
 
 [中文说明](README.zh-CN.md) ·
 [v0.3.7 plan](docs/plan/v0.3.7-left-rail-improvement-plan.md) ·
@@ -170,7 +173,7 @@ current development environments. Node 20 is upstream EOL and is no longer a v0.
 After the immutable `0.3.5` npm receipt exists:
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.11
+npm install -g @orion-agents/orion-code@0.3.12
 orion --version
 orion doctor
 ```

package/README.zh-CN.md

@@ -2,9 +2,10 @@
 
 面向终端与浏览器、本地优先的目标驱动 Coding Agent。
 
-> v0.3.11 候选版本：右侧工作面板改为**竖状 rail 菜单**——常驻 48px 竖栏，
-> 点击图标即展示对应面板（再点收起、Esc 关闭），带终端状态徽标并支持持久化图标顺序。
-> Candidate 源码不代表已创建 npm 发布、Git tag 或达到可合并状态。
+> v0.3.12 候选版本：在竖状 rail 之上的**大尺寸右侧工作区**——纯 dock/rail/drawer 几何
+> （详情面可拉宽至 80vw，对话保留 320px 最小宽度）、按 workspace 的布局偏好、共享仓库快照
+> store、Review 验证证据渐进分页、受控 Git stage/unstage/commit、受限工作区搜索与带版本
+> 约束的 file_range Context 引用。Candidate 源码不代表已创建 npm 发布、Git tag 或达到可合并状态。
 
 [English](README.md) ·
 [v0.3.7 方案](docs/plan/v0.3.7-left-rail-improvement-plan.md) ·
@@ -101,7 +102,7 @@ Current。Node 20 已结束上游维护，不再属于 v0.3 Runtime 合同。
 当 npm 已存在不可变的 `0.3.4` 发布凭据后：
 
 ```bash
-npm install -g @orion-agents/orion-code@0.3.11
+npm install -g @orion-agents/orion-code@0.3.12
 orion --version
 orion doctor
 ```

package/dist/cli.js

@@ -80,8 +80,21 @@ async function manageBackgroundHost(command, args) {
         if (status.state === 'running') {
             console.log(`orion web is running: ${status.pidfile.url} (pid ${status.pidfile.pid})`);
             console.log(`workspace ${status.pidfile.workspace} · started ${new Date(status.pidfile.startedAt).toISOString()}`);
+            return;
+        }
+        // No pidfile-owned host, or a stale one. A live listener on the port means
+        // an externally managed host (e.g. a launchd LaunchAgent) is serving it —
+        // report that instead of a confusing 'not running'.
+        if (await (0, host_daemon_1.isHostPortTaken)(options.port)) {
+            console.log(`Port ${options.port} is being served by an externally managed Orion host ` +
+                `(e.g. a launchd LaunchAgent such as ai.orion-code.web). It is not owned ` +
+                `by \`orion web status/stop\`; inspect it with \`launchctl list | grep orion\`.`);
+            if (status.state === 'stale') {
+                console.log(`Note: the pidfile for the former pid ${status.pid} is stale and can be removed safely.`);
+            }
+            return;
         }
-        else if (status.state === 'stale') {
+        if (status.state === 'stale') {
             console.log(`orion web is not running (stale pidfile for pid ${status.pid} on port ${status.port}).`);
         }
         else {

package/dist/web/context-text.d.ts

@@ -0,0 +1,17 @@
+/**
+ * v0.3.12 — Context text helpers shared by the controller when resolving
+ * version-bound references (file_range etc.). Pure and unit-tested.
+ */
+export interface ExtractedLines {
+    readonly text: string;
+    /** True when the requested range reached the end of the file before endLine. */
+    readonly clampedAtEnd: boolean;
+}
+/** Extract a 1-based inclusive line range. Never throws for out-of-range input. */
+export declare function extractLineRange(content: string, startLine: number, endLine: number): ExtractedLines;
+/** Soft per-reference byte budget for line content sent to the model context. */
+export declare function enforceContextBudget(text: string, maxBytes: number): {
+    readonly text: string;
+    readonly truncated: boolean;
+};
+//# sourceMappingURL=context-text.d.ts.map

package/dist/web/context-text.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * v0.3.12 — Context text helpers shared by the controller when resolving
+ * version-bound references (file_range etc.). Pure and unit-tested.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractLineRange = extractLineRange;
+exports.enforceContextBudget = enforceContextBudget;
+/** Extract a 1-based inclusive line range. Never throws for out-of-range input. */
+function extractLineRange(content, startLine, endLine) {
+    const start = Math.max(1, Math.trunc(startLine));
+    const end = Math.max(start, Math.trunc(endLine));
+    const lines = content.split('\n');
+    if (start > lines.length) {
+        return Object.freeze({ text: '', clampedAtEnd: true });
+    }
+    const last = Math.min(end, lines.length);
+    const slice = lines.slice(start - 1, last);
+    return Object.freeze({
+        text: slice.join('\n'),
+        clampedAtEnd: end > lines.length,
+    });
+}
+/** Soft per-reference byte budget for line content sent to the model context. */
+function enforceContextBudget(text, maxBytes) {
+    if (Buffer.byteLength(text, 'utf8') <= maxBytes) {
+        return Object.freeze({ text, truncated: false });
+    }
+    let low = 0;
+    let high = text.length;
+    while (low < high) {
+        const mid = (low + high + 1) >>> 1;
+        if (Buffer.byteLength(text.slice(0, mid), 'utf8') <= maxBytes)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return Object.freeze({ text: text.slice(0, low), truncated: true });
+}
+//# sourceMappingURL=context-text.js.map

package/dist/web/file-read-service.d.ts

@@ -45,12 +45,35 @@ export declare class FileReadServiceV1 {
     constructor(workspace: string);
     get rootId(): string;
     performanceCounters(): WebFileReadPerformanceCountersV1;
+    /** v0.3.12 S3 — resolve a remembered file id back to its workspace-relative path. */
+    pathForFileId(fileId: string): string;
     identifyRelativePath(relativePath: string): string;
     list(input?: {
         readonly parentId?: string;
         readonly cursor?: string;
         readonly pageSize?: number;
     }): WebFileTreePageV1;
+    /**
+     * v0.3.12 S4 — bounded workspace search. Name scope walks the tree (skipping
+     * VCS/dependency/ignored names, hidden directories, out-of-root symlinks and
+     * sensitive paths); content scope additionally matches inside the first
+     * 64 KiB of each text file and skips binary payloads. Results cap at
+     * `limit`; the scan stops early once the cap is reached or the file budget
+     * is exhausted.
+     */
+    search(input: {
+        readonly query: string;
+        readonly scope: 'name' | 'content';
+        readonly limit?: number;
+    }): {
+        readonly items: ReadonlyArray<{
+            readonly id: string;
+            readonly name: string;
+            readonly path: string;
+        }>;
+        readonly truncated: boolean;
+    };
+    private fileContainsQuery;
     readContent(input: {
         readonly fileId: string;
         readonly cursor?: string;

package/dist/web/file-read-service.js

@@ -41,6 +41,14 @@ class FileReadServiceV1 {
     performanceCounters() {
         return Object.freeze({ ...this.performance });
     }
+    /** v0.3.12 S3 — resolve a remembered file id back to its workspace-relative path. */
+    pathForFileId(fileId) {
+        const relativePath = this.pathById.get(fileId);
+        if (relativePath === undefined) {
+            throw new errors_1.WebWorkbenchError(404, 'File node was not found.', 'file_not_found');
+        }
+        return relativePath;
+    }
     identifyRelativePath(relativePath) {
         const normalized = normalizeRelativePath(relativePath);
         this.resolveRelative(normalized);
@@ -107,6 +115,132 @@ class FileReadServiceV1 {
                 : null,
         });
     }
+    /**
+     * v0.3.12 S4 — bounded workspace search. Name scope walks the tree (skipping
+     * VCS/dependency/ignored names, hidden directories, out-of-root symlinks and
+     * sensitive paths); content scope additionally matches inside the first
+     * 64 KiB of each text file and skips binary payloads. Results cap at
+     * `limit`; the scan stops early once the cap is reached or the file budget
+     * is exhausted.
+     */
+    search(input) {
+        const query = input.query.trim().slice(0, 200).toLowerCase();
+        if (!query) {
+            throw new errors_1.WebWorkbenchError(400, 'A non-empty search query is required.', 'file_search_query_required');
+        }
+        const limit = boundedPageSize(input.limit ?? 50);
+        const items = [];
+        const stack = [{ dir: this.root, rel: '' }];
+        let visitedDirectories = 0;
+        let visitedFiles = 0;
+        let truncated = false;
+        const fileBudget = 2500;
+        while (stack.length > 0 && visitedFiles < fileBudget) {
+            const { dir, rel } = stack.pop();
+            visitedDirectories += 1;
+            if (visitedDirectories > 4000) {
+                truncated = true;
+                break;
+            }
+            let directory;
+            try {
+                directory = (0, fs_1.opendirSync)(dir);
+            }
+            catch {
+                continue;
+            }
+            const entries = [];
+            try {
+                for (;;) {
+                    const entry = directory.readSync();
+                    if (!entry)
+                        break;
+                    if (IGNORED_NAMES.has(entry.name) ||
+                        (entry.name.startsWith('.') && entry.isDirectory())) {
+                        continue;
+                    }
+                    if (entry.isDirectory())
+                        entries.push({ name: entry.name, kind: 'directory' });
+                    else if (entry.isFile())
+                        entries.push({ name: entry.name, kind: 'file' });
+                    else if (entry.isSymbolicLink())
+                        entries.push({ name: entry.name, kind: 'link' });
+                }
+            }
+            finally {
+                directory.closeSync();
+            }
+            entries.sort((left, right) => left.name.localeCompare(right.name));
+            for (const entry of entries) {
+                if (items.length >= limit) {
+                    truncated = true;
+                    break;
+                }
+                const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+                const absolute = (0, path_1.resolve)(dir, entry.name);
+                if (entry.kind === 'directory') {
+                    stack.push({ dir: absolute, rel: childRel });
+                    continue;
+                }
+                if (entry.kind === 'link') {
+                    try {
+                        const canonical = (0, fs_1.realpathSync)(absolute);
+                        if (!isWithinRoot(canonical, this.root))
+                            continue;
+                        if ((0, fs_1.statSync)(canonical).isDirectory())
+                            continue;
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                visitedFiles += 1;
+                if ((0, redaction_1.isSensitiveFilePath)(childRel))
+                    continue;
+                const nameMatches = entry.name.toLowerCase().includes(query);
+                if (input.scope === 'name') {
+                    if (nameMatches) {
+                        items.push({ id: this.remember(childRel), name: entry.name, path: childRel });
+                    }
+                    continue;
+                }
+                let contentMatches = false;
+                if (!nameMatches) {
+                    contentMatches = this.fileContainsQuery(absolute, query);
+                }
+                if (nameMatches || contentMatches) {
+                    items.push({ id: this.remember(childRel), name: entry.name, path: childRel });
+                }
+            }
+        }
+        return Object.freeze({
+            items: Object.freeze(items.map(item => Object.freeze(item))),
+            truncated: truncated || visitedFiles >= fileBudget,
+        });
+    }
+    fileContainsQuery(absolutePath, query) {
+        try {
+            const descriptor = (0, fs_1.openSync)(absolutePath, fs_1.constants.O_RDONLY);
+            try {
+                const buffer = Buffer.alloc(64 * 1024);
+                const bytesRead = (0, fs_1.readSync)(descriptor, buffer, 0, buffer.length, 0);
+                if (bytesRead === 0)
+                    return false;
+                if (buffer.subarray(0, bytesRead).includes(0))
+                    return false;
+                return new util_1.TextDecoder('utf-8')
+                    .decode(buffer.subarray(0, bytesRead))
+                    .toLowerCase()
+                    .includes(query);
+            }
+            finally {
+                (0, fs_1.closeSync)(descriptor);
+            }
+        }
+        catch {
+            return false;
+        }
+    }
     readContent(input) {
         this.performance.readOperations += 1;
         const limitBytes = boundedContentBytes(input.limitBytes ?? DEFAULT_CONTENT_BYTES);

package/dist/web/git-read-model-service.d.ts

@@ -77,6 +77,20 @@ export declare class GitReadModelServiceV1 {
     private capture;
     private projectFile;
     private rememberPath;
+    /** v0.3.12 S3 — guarded stage: paths are host-resolved file ids only. */
+    stagePaths(paths: readonly string[]): Promise<{
+        readonly repositoryRevision: string;
+    }>;
+    unstagePaths(paths: readonly string[]): Promise<{
+        readonly repositoryRevision: string;
+    }>;
+    commit(message: string): Promise<{
+        readonly repositoryRevision: string;
+        readonly commitSha: string;
+    }>;
+    private mutate;
+    private requireRepositoryRoot;
+    private revisionAfterMutation;
     private runGit;
     private tryGit;
     private encodeCursor;

package/dist/web/git-read-model-service.js

@@ -262,6 +262,56 @@ class GitReadModelServiceV1 {
         this.pathById.set(id, path);
         return id;
     }
+    /** v0.3.12 S3 — guarded stage: paths are host-resolved file ids only. */
+    async stagePaths(paths) {
+        assertSafeGitPaths(paths);
+        if (paths.length === 0)
+            throw new Error('stage requires at least one path.');
+        await this.mutate(['add', '--', ...paths]);
+        return { repositoryRevision: await this.revisionAfterMutation() };
+    }
+    async unstagePaths(paths) {
+        assertSafeGitPaths(paths);
+        if (paths.length === 0)
+            throw new Error('unstage requires at least one path.');
+        await this.mutate(['reset', '-q', '--', ...paths]);
+        return { repositoryRevision: await this.revisionAfterMutation() };
+    }
+    async commit(message) {
+        const trimmed = message.trim();
+        if (!trimmed || trimmed.length > 2000 || /[\x00-\x1f]/.test(trimmed)) {
+            throw new Error('A valid commit message is required.');
+        }
+        const root = await this.requireRepositoryRoot();
+        const porcelain = (await this.runGit(['status', '--porcelain=v1'], root)).trim();
+        const stagedLines = porcelain
+            .split('\n')
+            .filter(line => line.length > 1 && line[0] !== ' ' && line[0] !== '?' && line[0] !== '!');
+        if (stagedLines.length === 0) {
+            throw new Error('Nothing is staged to commit.');
+        }
+        await this.mutate(['commit', '-m', trimmed]);
+        const sha = (await this.runGit(['rev-parse', 'HEAD'], root)).trim();
+        return { repositoryRevision: await this.revisionAfterMutation(), commitSha: sha };
+    }
+    async mutate(args) {
+        const root = await this.requireRepositoryRoot();
+        const output = await this.runGit(args, root);
+        if (output) {
+            // Warnings on stderr are not captured by runGit; treat non-empty as unexpected.
+        }
+    }
+    async requireRepositoryRoot() {
+        const snapshot = await this.capture();
+        if (!snapshot.isRepository || !snapshot.root) {
+            throw new Error('Git repository is unavailable.');
+        }
+        return snapshot.root;
+    }
+    async revisionAfterMutation() {
+        const root = await this.requireRepositoryRoot();
+        return this.runGit(['rev-parse', 'HEAD'], root).then(value => value.trim());
+    }
     runGit(args, cwd) {
         return new Promise((resolvePromise, reject) => {
             this.performance.processCount += 1;
@@ -590,6 +640,20 @@ function streamGitLines(input) {
         });
     });
 }
+function assertSafeGitPaths(paths) {
+    for (const path of paths) {
+        if (typeof path !== 'string' ||
+            path.length === 0 ||
+            path.length > 4096 ||
+            path.includes('\0') ||
+            path.startsWith('-') ||
+            path.includes('/../') ||
+            path === '..' ||
+            path.startsWith('../')) {
+            throw new Error(`Unsafe Git path rejected: ${JSON.stringify(path)}`);
+        }
+    }
+}
 function gitEnvironment() {
     return {
         PATH: process.env.PATH,

package/dist/web/host-daemon.d.ts

@@ -48,6 +48,15 @@ export declare function hostDaemonStatus(port: number): HostDaemonStatus;
  * stdio to `~/.orion-code/logs/web-<port>.log`, and wait for the pidfile so the
  * foreground command can print the URL and exit cleanly.
  */
+/**
+ * True when something already listens on 127.0.0.1:port — typically another
+ * Orion host process (e.g. one managed by launchd, which does not write a
+ * pidfile). Detecting this up front turns a raw EADDRINUSE crash into a
+ * friendly message.
+ */
+export declare function isHostPortTaken(port: number): Promise<boolean>;
+/** Best-effort tail of the host log used when a background child exits early. */
+export declare function readHostLogTail(port: number, lines?: number): string;
 export declare function spawnBackgroundHost(options: {
     readonly cwd: string;
     readonly port: number;

package/dist/web/host-daemon.js

@@ -9,6 +9,8 @@ exports.writeHostPidfile = writeHostPidfile;
 exports.clearHostPidfile = clearHostPidfile;
 exports.isProcessAlive = isProcessAlive;
 exports.hostDaemonStatus = hostDaemonStatus;
+exports.isHostPortTaken = isHostPortTaken;
+exports.readHostLogTail = readHostLogTail;
 exports.spawnBackgroundHost = spawnBackgroundHost;
 exports.stopBackgroundHost = stopBackgroundHost;
 /**
@@ -26,6 +28,7 @@ exports.stopBackgroundHost = stopBackgroundHost;
  *     "startedAt": 1725000000000, "workspace": "/abs/path" }
  */
 const child_process_1 = require("child_process");
+const net_1 = require("net");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const paths_1 = require("../product/paths");
@@ -119,7 +122,48 @@ function childArgs(webArgs) {
  * stdio to `~/.orion-code/logs/web-<port>.log`, and wait for the pidfile so the
  * foreground command can print the URL and exit cleanly.
  */
-function spawnBackgroundHost(options) {
+/**
+ * True when something already listens on 127.0.0.1:port — typically another
+ * Orion host process (e.g. one managed by launchd, which does not write a
+ * pidfile). Detecting this up front turns a raw EADDRINUSE crash into a
+ * friendly message.
+ */
+function isHostPortTaken(port) {
+    return new Promise(resolve => {
+        const socket = (0, net_1.connect)({ host: '127.0.0.1', port });
+        let settled = false;
+        const done = (taken) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(taken);
+        };
+        socket.once('connect', () => done(true));
+        socket.once('error', () => done(false));
+        socket.setTimeout(800, () => done(false));
+    });
+}
+/** Best-effort tail of the host log used when a background child exits early. */
+function readHostLogTail(port, lines = 6) {
+    try {
+        const raw = (0, fs_1.readFileSync)((0, path_1.join)(hostLogsDirectory(), `web-${port}.log`), 'utf8');
+        return raw.split('\n').filter(Boolean).slice(-lines).join('\n');
+    }
+    catch {
+        return '';
+    }
+}
+async function assertHostPortAvailable(port) {
+    if (await isHostPortTaken(port)) {
+        throw new Error(`Port ${port} is already served by another Orion host process. This is ` +
+            `often a launchd LaunchAgent (ai.orion-code.web). Check with ` +
+            '`launchctl list | grep orion`; if the running host belongs to this ' +
+            `CLI, use \`orion web status --port ${port}\` to confirm before stopping it.`);
+    }
+}
+async function spawnBackgroundHost(options) {
+    await assertHostPortAvailable(options.port);
     const logsDirectory = hostLogsDirectory();
     (0, fs_1.mkdirSync)(logsDirectory, { recursive: true });
     const logPath = (0, path_1.join)(logsDirectory, `web-${options.port}.log`);

package/dist/web/protocol.d.ts

@@ -171,6 +171,13 @@ export type WebContextReferenceV1 = {
     readonly id: string;
     readonly label: string;
     readonly revision: string;
+} | {
+    readonly kind: 'file_range';
+    readonly id: string;
+    readonly label: string;
+    readonly revision: string;
+    readonly startLine: number;
+    readonly endLine: number;
 } | {
     readonly kind: 'folder';
     readonly id: string;

package/dist/web/protocol.js

@@ -523,6 +523,7 @@ function parseContextReferences(value) {
         const row = requireRecord(entry, `contextReferences[${index}]`);
         const kind = requireEnum(row.kind, `contextReferences[${index}].kind`, [
             'file',
+            'file_range',
             'folder',
             'review',
             'session',
@@ -534,6 +535,22 @@ function parseContextReferences(value) {
         }
         seen.add(`${kind}:${id}`);
         const label = requireBoundedString(row.label, `contextReferences[${index}].label`, 200);
+        if (kind === 'file_range') {
+            assertOnlyKeys(row, ['kind', 'id', 'label', 'revision', 'startLine', 'endLine'], 'Context reference');
+            const startLine = requireLineNumber(row.startLine, `contextReferences[${index}].startLine`);
+            const endLine = requireLineNumber(row.endLine, `contextReferences[${index}].endLine`);
+            if (endLine < startLine) {
+                throw new WebProtocolError('file_range endLine must not precede startLine');
+            }
+            return Object.freeze({
+                kind,
+                id,
+                label,
+                revision: requireBoundedString(row.revision, `contextReferences[${index}].revision`, 256),
+                startLine,
+                endLine,
+            });
+        }
         if (kind === 'file' || kind === 'folder') {
             assertOnlyKeys(row, ['kind', 'id', 'label', 'revision'], 'Context reference');
             return Object.freeze({
@@ -573,6 +590,15 @@ function assertOnlyKeys(row, keys, subject = 'command') {
     if (unknown)
         throw new WebProtocolError(`Unknown ${subject} field: ${unknown}`);
 }
+function requireLineNumber(value, name) {
+    if (typeof value !== 'number' ||
+        !Number.isSafeInteger(value) ||
+        value < 1 ||
+        value > 100000000) {
+        throw new WebProtocolError(`${name} must be an integer line number from 1 through 100000000`);
+    }
+    return value;
+}
 function requireBoundedString(value, name, maxLength) {
     if (typeof value !== 'string' || !value.trim()) {
         throw new WebProtocolError(`${name} must be a non-empty string`);

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

@@ -34,6 +34,20 @@ export declare class ReviewServiceV1 {
     private readonly listReceiptRefs;
     constructor(git: GitReadModelServiceV1, listReceiptRefs: () => Promise<readonly VerifiedDurableToolReceiptRefV1[]> | readonly VerifiedDurableToolReceiptRefV1[]);
     snapshot(): Promise<WebReviewSnapshotV1>;
+    /**
+     * v0.3.12 S2 — progressive verification evidence. The Review summary loads
+     * first; receipts page in behind it, optionally filtered to one session.
+     */
+    verificationPage(input: {
+        readonly sessionId?: string;
+        readonly cursor?: number;
+        readonly pageSize?: number;
+    }): Promise<{
+        readonly items: readonly WebReviewVerificationV1[];
+        readonly nextCursor: number | null;
+        readonly totalForSession: number;
+    }>;
+    private projectVerification;
     diff(input: Parameters<GitReadModelServiceV1['diff']>[0]): Promise<WebGitDiffPageV1>;
 }
 //# sourceMappingURL=review-service.d.ts.map