@orion-agents/orion-code 0.3.11 → 0.3.14

package/CHANGELOG.md

@@ -22,9 +22,101 @@ which is **not** a pass.
 
 ## [Unreleased]
 
-## [0.3.11] — CANDIDATE
+## [0.3.14] — CANDIDATE
 
-> **Status: candidate.** Not merged, tagged or published to npm.
+> **Status: candidate.** Editable Files panel (guarded `POST /files/write` with
+> revision CAS) and removal of the legacy view-only controls. Not merged,
+> tagged or published.
+
+### Added
+
+- File editing in the Files panel: content view gains a view/edit toggle; the
+  edit mode is a controlled monospace textarea with dirty tracking, explicit
+  save (guarded `POST /files/write`), cancel/Esc with an unsaved-changes
+  confirmation, and a 409 conflict path that offers an explicit reload.
+- `POST /files/write`: workspace-fenced (registry + symlink escape checks),
+  sensitive-path block, 512 KiB text-only payload limit, on-disk stat
+  fingerprint CAS (`file_revision_conflict`), user-gesture header
+  (`file-mutation-v1`), idempotent `file.write` mutation ledger entry, and
+  one-shot snapshot invalidation so Git/Review decorations refresh after a
+  save.
+
+### Fixed
+
+- Resource refreshes keep the inspected file: `ReviewPanel` no longer drops the
+  open diff on a manual refresh, a `refreshEpoch` invalidation or a Git revision
+  conflict recovery; `FilesPanel` keeps the open file on refresh (still reset
+  when the workspace itself changes), so the editor no longer closes mid-edit.
+- The review summary counters are localised (已暂存 / 未暂存 / 未跟踪 / 冲突)
+  instead of raw English labels.
+- Binary detection tolerates an 8 KiB sample that ends inside one UTF-8 code
+  point, so CJK files are no longer rejected as binary on read or save.
+
+### Removed
+
+- The read-only file toolbar: 「跳转」（line jump）, 「复制」 and 「自动换行」
+  controls, the line-number gutter spans and the wrap-only styles.
+- The Review panel's 「验证证据」 module: the evidence list,
+  `WebReviewVerificationV1`, `ReviewServiceV1.verificationPage`, the
+  `GET /review/verification` route and the snapshot's `verification` /
+  `verificationTruncated` fields. The review overview is now composed only from
+  Git facts; durable tool receipts remain available to the runtime.
+
+## [0.3.13] — CANDIDATE
+
+> **Status: candidate.** Development baseline after v0.3.12 (version bump only;
+> no functional changes yet). Not merged, tagged or published.
+
+## [0.3.12] — NPM-PUBLISHED
+
+> **Status: npm-published.** `@orion-agents/orion-code@0.3.12` is available
+> through the npm registry (latest tag). Published 2026-09-07 via PR #252;
+> git tag/release may lag. Wide Right Workspace + repository-truth + guarded
+> Git mutations (v0.3.12-plan) plus resource split layout, conversation
+> history navigator and the unified brand mark (v0.3.13-plan v3/v4/v5).
+
+### 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

@@ -1,3 +1,4 @@
+import { type BigIntStats } from 'fs';
 export type WebFileKindV1 = 'file' | 'directory' | 'symlink';
 export interface WebFileNodeV1 {
     readonly id: string;
@@ -45,17 +46,49 @@ 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;
         readonly limitBytes?: number;
     }): WebFileContentPageV1;
+    /** v0.3.14 — write-path preflight for an existing in-root regular text file. */
+    writePreflight(fileId: string): {
+        readonly canonicalPath: string;
+        readonly relativePath: string;
+        readonly revision: string;
+        readonly sizeBytes: number;
+    };
+    /** v0.3.14 — post-write revision fingerprint for the response. */
+    revisionOf(canonicalPath: string): string;
     private projectNode;
     private resolveNode;
     private resolveRelative;
@@ -63,4 +96,6 @@ export declare class FileReadServiceV1 {
     private encodeCursor;
     private decodeCursor;
 }
+export declare function fingerprintStat(stat: BigIntStats): string;
+export declare function isBinary(buffer: Buffer): boolean;
 //# sourceMappingURL=file-read-service.d.ts.map

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

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileReadServiceV1 = void 0;
+exports.fingerprintStat = fingerprintStat;
+exports.isBinary = isBinary;
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const path_1 = require("path");
@@ -41,6 +43,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 +117,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);
@@ -135,7 +271,7 @@ class FileReadServiceV1 {
             if (sample.length > 0) {
                 this.performance.bytesRead += (0, fs_1.readSync)(descriptor, sample, 0, sample.length, 0);
             }
-            const binary = isBinary(sample);
+            const binary = isBinary(validUtf8Prefix(sample));
             if (binary) {
                 return Object.freeze({
                     fileId: input.fileId,
@@ -199,6 +335,27 @@ class FileReadServiceV1 {
             (0, fs_1.closeSync)(descriptor);
         }
     }
+    /** v0.3.14 — write-path preflight for an existing in-root regular text file. */
+    writePreflight(fileId) {
+        this.performance.readOperations += 1;
+        const node = this.resolveNode(fileId);
+        if (!node.stat.isFile()) {
+            throw new errors_1.WebWorkbenchError(409, 'File node is not a regular file.', 'file_not_regular');
+        }
+        if (isSensitiveResolvedPath(this.root, node.relativePath, node.canonicalPath)) {
+            throw new errors_1.WebWorkbenchError(403, 'Sensitive files are not writable in the Web Workbench.', 'sensitive_file_blocked');
+        }
+        return Object.freeze({
+            canonicalPath: node.canonicalPath,
+            relativePath: node.relativePath,
+            revision: fingerprintStat(node.stat),
+            sizeBytes: Number(node.stat.size),
+        });
+    }
+    /** v0.3.14 — post-write revision fingerprint for the response. */
+    revisionOf(canonicalPath) {
+        return fingerprintStat((0, fs_1.statSync)(canonicalPath, { bigint: true }));
+    }
     projectNode(relativePath) {
         const lexicalPath = (0, path_1.resolve)(this.root, relativePath);
         const lexicalStat = (0, fs_1.lstatSync)(lexicalPath, { bigint: true });

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

@@ -0,0 +1,16 @@
+import { FileReadServiceV1 } from './file-read-service';
+export interface WebFileWriteResultV1 {
+    readonly fileId: string;
+    readonly revision: string;
+    readonly sizeBytes: number;
+}
+export declare class FileWriteServiceV1 {
+    private readonly fileService;
+    constructor(fileService: FileReadServiceV1);
+    writeContent(input: {
+        readonly fileId: string;
+        readonly content: string;
+        readonly expectedRevision: string;
+    }): WebFileWriteResultV1;
+}
+//# sourceMappingURL=file-write-service.d.ts.map

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

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileWriteServiceV1 = void 0;
+const fs_1 = require("fs");
+const errors_1 = require("./errors");
+const file_read_service_1 = require("./file-read-service");
+const MAX_WRITE_BYTES = 512 * 1024;
+const WRITE_SAMPLE_BYTES = 8192;
+/**
+ * v0.3.14 — bounded, CAS-guarded writes for an existing in-root text file.
+ *
+ * Safety stack mirrors the read path: the file id resolves through the read
+ * service's fenced registry (workspace escape, symlink escape and sensitive
+ * paths fail closed there), the payload must be valid UTF-8 text without NULs
+ * within 512 KiB, and the write commits only when the on-disk revision still
+ * matches the caller's `expectedRevision` (compare-and-swap against the same
+ * stat fingerprint the read path returns).
+ */
+/**
+ * A bounded sample can end inside one UTF-8 code point (very likely for CJK
+ * text at an 8 KiB boundary); drop the trailing partial byte before judging the
+ * file as binary, mirroring the read path's `validUtf8Prefix`.
+ */
+function completeUtf8Tail(buffer) {
+    for (let trim = 0; trim <= Math.min(3, Math.max(0, buffer.length - 1)); trim += 1) {
+        const candidate = buffer.subarray(0, buffer.length - trim);
+        if (!(0, file_read_service_1.isBinary)(candidate))
+            return candidate;
+    }
+    return buffer;
+}
+class FileWriteServiceV1 {
+    constructor(fileService) {
+        this.fileService = fileService;
+    }
+    writeContent(input) {
+        const content = input.content;
+        if (typeof content !== 'string') {
+            throw new errors_1.WebWorkbenchError(400, 'File content must be a string.', 'file_content_invalid');
+        }
+        if (content.includes('\0')) {
+            throw new errors_1.WebWorkbenchError(415, 'Files containing NUL bytes are not editable in the Web Workbench.', 'file_binary');
+        }
+        const byteLength = Buffer.byteLength(content, 'utf8');
+        if (byteLength > MAX_WRITE_BYTES) {
+            throw new errors_1.WebWorkbenchError(413, 'Edited file content exceeds the 512 KiB Web editor limit.', 'file_too_large');
+        }
+        if (!/^[0-9a-f]{64}$/u.test(input.expectedRevision)) {
+            throw new errors_1.WebWorkbenchError(400, 'expectedRevision is invalid.', 'file_revision_invalid');
+        }
+        const preflight = this.fileService.writePreflight(input.fileId);
+        if (preflight.sizeBytes > MAX_WRITE_BYTES) {
+            throw new errors_1.WebWorkbenchError(413, 'Target file exceeds the 512 KiB Web editor limit.', 'file_too_large');
+        }
+        const payload = Buffer.from(content, 'utf8');
+        // Phase 1 (read descriptor): CAS + binary re-check. An O_WRONLY descriptor
+        // cannot readSync, so the preflight opens its own read handle first.
+        const readDescriptor = (0, fs_1.openSync)(preflight.canonicalPath, fs_1.constants.O_RDONLY);
+        let beforeSize;
+        try {
+            const before = (0, fs_1.fstatSync)(readDescriptor, { bigint: true });
+            beforeSize = before.size;
+            const sample = Buffer.alloc(Math.min(WRITE_SAMPLE_BYTES, Number(before.size)));
+            if (sample.length > 0) {
+                (0, fs_1.readSync)(readDescriptor, sample, 0, sample.length, 0);
+                if ((0, file_read_service_1.isBinary)(completeUtf8Tail(sample))) {
+                    throw new errors_1.WebWorkbenchError(415, 'Target file is not UTF-8 text.', 'file_binary');
+                }
+            }
+            if ((0, file_read_service_1.fingerprintStat)(before) !== input.expectedRevision) {
+                throw new errors_1.WebWorkbenchError(409, 'The file changed on disk before the save could run; reload it first.', 'file_revision_conflict');
+            }
+        }
+        finally {
+            (0, fs_1.closeSync)(readDescriptor);
+        }
+        // Phase 2 (write descriptor): CAS is re-checked by the kernel fingerprint
+        // window being as short as possible between the two handles.
+        const writeDescriptor = (0, fs_1.openSync)(preflight.canonicalPath, fs_1.constants.O_WRONLY);
+        try {
+            const before = (0, fs_1.fstatSync)(writeDescriptor, { bigint: true });
+            if ((0, file_read_service_1.fingerprintStat)(before) !== input.expectedRevision) {
+                throw new errors_1.WebWorkbenchError(409, 'The file changed on disk before the save could run; reload it first.', 'file_revision_conflict');
+            }
+            (0, fs_1.writeSync)(writeDescriptor, payload, 0, payload.length, 0);
+            // Shrink keeps the file exactly as long as the payload.
+            if (beforeSize > BigInt(payload.length)) {
+                (0, fs_1.truncateSync)(preflight.canonicalPath, payload.length);
+            }
+            const after = (0, fs_1.statSync)(preflight.canonicalPath, { bigint: true });
+            return Object.freeze({
+                fileId: input.fileId,
+                revision: (0, file_read_service_1.fingerprintStat)(after),
+                sizeBytes: Number(after.size),
+            });
+        }
+        finally {
+            (0, fs_1.closeSync)(writeDescriptor);
+        }
+    }
+}
+exports.FileWriteServiceV1 = FileWriteServiceV1;
+//# sourceMappingURL=file-write-service.js.map

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;