@orion-agents/orion-code 0.3.15 → 0.3.18

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

@@ -1,13 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GitReadModelServiceV1 = void 0;
+exports.normalizeCommitMessage = normalizeCommitMessage;
+exports.assertRelativeGitPath = assertRelativeGitPath;
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const redaction_1 = require("../services/redaction");
 const errors_1 = require("./errors");
+const git_diff_document_1 = require("./git-diff-document");
+const git_patch_builder_1 = require("./git-patch-builder");
+const git_history_service_1 = require("./git-history-service");
+const git_compare_service_1 = require("./git-compare-service");
+const git_version_service_1 = require("./git-version-service");
+const git_file_source_1 = require("./git-file-source");
+const git_index_transaction_1 = require("./git-index-transaction");
 const GIT_TIMEOUT_MS = 5000;
+/** plan §7.9 — the commit runner gets its own bounded budget for hooks and signing. */
+const GIT_COMMIT_TIMEOUT_MS = 60000;
 const GIT_MAX_BUFFER = 8 * 1024 * 1024;
 const DEFAULT_STATUS_PAGE_SIZE = 200;
 const MAX_STATUS_PAGE_SIZE = 2000;
@@ -20,12 +31,18 @@ const MAX_DIFF_BYTES = 1024 * 1024;
 const GIT_NULL_DEVICE = process.platform === 'win32' ? 'NUL' : '/dev/null';
 /** Bounded argv-only Git status/log/diff projection for one active Workspace. */
 class GitReadModelServiceV1 {
-    constructor(workspace) {
+    constructor(workspace, options = {}) {
         this.secret = (0, crypto_1.randomBytes)(32);
-        this.pathById = new Map();
-        this.idByPath = new Map();
+        /**
+         * v0.3.17 S1 — tokens are keyed by (source, path), not by path alone. A file that is
+         * both staged and modified in the worktree is two different selectable objects, so a
+         * path-only key silently conflated the two comparison sources.
+         */
+        this.targetById = new Map();
+        this.idByKey = new Map();
         this.performance = { processCount: 0, bytesRead: 0, itemsParsed: 0 };
         this.workspace = canonicalDirectory(workspace);
+        this.commitTimeoutMs = boundedInteger(options.commitTimeoutMs ?? GIT_COMMIT_TIMEOUT_MS, 1000, 600000, 'commitTimeoutMs');
     }
     performanceCounters() {
         return Object.freeze({ ...this.performance });
@@ -33,16 +50,38 @@ class GitReadModelServiceV1 {
     async status(input = {}) {
         const snapshot = await this.capture();
         const pageSize = boundedInteger(input.pageSize ?? DEFAULT_STATUS_PAGE_SIZE, 1, MAX_STATUS_PAGE_SIZE, 'pageSize');
+        const group = normalizeSource(input.group);
+        const query = normalizeQuery(input.query);
+        // v0.3.17 S1 — the query scope is bound into the cursor, so pages can never be
+        // stitched across two different filters.
+        const scope = statusScope(group, query);
+        const matched = snapshot.records.filter(record => {
+            if (group && !recordSources(record).includes(group))
+                return false;
+            return query === undefined || record.path.toLocaleLowerCase().includes(query);
+        });
         const offset = input.cursor
-            ? this.decodeCursor(input.cursor, 'status', snapshot.revision).offset
+            ? this.decodeCursor(input.cursor, 'status', snapshot.revision, undefined, scope).offset
             : 0;
-        const records = snapshot.records.slice(offset, offset + pageSize);
-        const projected = records.map(record => this.projectFile(record));
-        const staged = projected.filter(file => file.indexStatus !== ' ' && file.indexStatus !== '?' && !isConflict(file));
-        const unstaged = projected.filter(file => file.worktreeStatus !== ' ' && file.worktreeStatus !== '?' && !isConflict(file));
-        const untracked = projected.filter(file => file.indexStatus === '?');
-        const conflicted = projected.filter(isConflict);
-        const nextOffset = offset + records.length;
+        const page = matched.slice(offset, offset + pageSize);
+        const staged = [];
+        const unstaged = [];
+        const untracked = [];
+        const conflicted = [];
+        const buckets = {
+            staged,
+            unstaged,
+            untracked,
+            conflict: conflicted,
+        };
+        for (const record of page) {
+            for (const source of recordSources(record)) {
+                buckets[source].push(this.projectFile(record, source));
+            }
+        }
+        // Totals cover the whole matched scope, never just the loaded page.
+        const counts = countSources(matched);
+        const nextOffset = offset + page.length;
         return Object.freeze({
             isRepository: snapshot.isRepository,
             repositoryRevision: snapshot.revision,
@@ -58,14 +97,16 @@ class GitReadModelServiceV1 {
             unstaged: Object.freeze(unstaged),
             untracked: Object.freeze(untracked),
             conflicted: Object.freeze(conflicted),
-            totalFiles: snapshot.records.length,
-            truncated: nextOffset < snapshot.records.length,
-            nextCursor: nextOffset < snapshot.records.length
+            totalFiles: matched.length,
+            counts: Object.freeze({ ...counts, loaded: page.length }),
+            truncated: nextOffset < matched.length,
+            nextCursor: nextOffset < matched.length
                 ? this.encodeCursor({
-                    version: 1,
+                    version: 2,
                     kind: 'status',
                     revision: snapshot.revision,
                     offset: nextOffset,
+                    scope,
                 })
                 : null,
         });
@@ -102,7 +143,7 @@ class GitReadModelServiceV1 {
             items: Object.freeze(items),
             nextCursor: hasMore
                 ? this.encodeCursor({
-                    version: 1,
+                    version: 2,
                     kind: 'log',
                     revision: snapshot.revision,
                     offset: offset + items.length,
@@ -115,22 +156,30 @@ class GitReadModelServiceV1 {
         if (!snapshot.isRepository || !snapshot.root) {
             throw new errors_1.WebWorkbenchError(404, 'Git repository is unavailable.', 'git_not_repository');
         }
-        const path = this.pathById.get(input.fileId);
-        if (!path)
-            throw new errors_1.WebWorkbenchError(404, 'Git file was not found.', 'git_file_not_found');
+        const target = this.resolveTarget(input.fileId);
+        const { path } = target;
         const record = snapshot.records.find(candidate => candidate.path === path);
         if (!record) {
             throw new errors_1.WebWorkbenchError(409, 'Git file changed before diff.', 'git_revision_conflict');
         }
+        // A token names one comparison source. If that source no longer exists (the file was
+        // staged away, or the worktree edit was reverted), the selection is stale rather than
+        // silently rendered against the other side.
+        if (!recordStillMatches(record, target.source)) {
+            throw new errors_1.WebWorkbenchError(409, 'Git file changed before diff.', 'git_revision_conflict');
+        }
         if (isSensitiveGitRecord(record)) {
             throw new errors_1.WebWorkbenchError(403, 'Sensitive file content is not available in the Web Workbench.', 'sensitive_file_blocked');
         }
         const lineLimit = boundedInteger(input.lineLimit ?? DEFAULT_DIFF_LINES, 1, MAX_DIFF_LINES, 'lineLimit');
         const byteLimit = boundedInteger(input.byteLimit ?? DEFAULT_DIFF_BYTES, 1024, MAX_DIFF_BYTES, 'byteLimit');
+        // Defaulted once so the command, the cursor and the document all describe the same view.
+        const ignoreWhitespace = input.ignoreWhitespace === true;
+        const wordDiff = input.wordDiff === true;
         const offset = input.cursor
-            ? this.decodeCursor(input.cursor, 'diff', snapshot.revision, input.fileId).offset
+            ? this.decodeCursor(input.cursor, 'diff', snapshot.revision, input.fileId, diffScope(ignoreWhitespace, wordDiff)).offset
             : 0;
-        const commands = diffCommands(record, path);
+        const commands = diffCommands(path, target.source, ignoreWhitespace, wordDiff);
         const page = await streamDiffPage({
             cwd: snapshot.root,
             commands,
@@ -157,21 +206,252 @@ class GitReadModelServiceV1 {
         return Object.freeze({
             fileId: input.fileId,
             path: (0, redaction_1.redactTraceText)(path),
+            source: target.source,
             repositoryRevision: snapshot.revision,
             binary,
             lines: Object.freeze(lines),
             nextCursor: page.hasMore
                 ? this.encodeCursor({
-                    version: 1,
+                    version: 2,
                     kind: 'diff',
                     revision: snapshot.revision,
                     offset: offset + page.returnedLines,
                     fileId: input.fileId,
+                    scope: diffScope(ignoreWhitespace, wordDiff),
                 })
                 : null,
             truncated: page.hasMore,
         });
     }
+    /**
+     * v0.3.17 S2 — the structured form of the same comparison. It reuses `diff()` verbatim,
+     * so the hardened read path, byte/line budget and pagination stay in one place; only the
+     * projection changes.
+     */
+    async diffDocument(input) {
+        const page = await this.diff(input);
+        return (0, git_diff_document_1.parseGitDiffDocument)({
+            fileToken: page.fileId,
+            path: page.path,
+            source: page.source,
+            repositoryRevision: page.repositoryRevision,
+            lines: page.lines,
+            hasMore: page.nextCursor !== null,
+            nextCursor: page.nextCursor,
+        });
+    }
+    historyReader() {
+        this.historyReaderInstance ?? (this.historyReaderInstance = (0, git_history_service_1.createGitHistoryReader)({
+            runGit: async (args) => this.runGit(args, await this.requireRepositoryRoot()),
+            requireRoot: () => this.requireRepositoryRoot(),
+            revision: async () => (await this.capture()).revision,
+        }));
+        return this.historyReaderInstance;
+    }
+    compareReader() {
+        this.compareReaderInstance ?? (this.compareReaderInstance = (0, git_compare_service_1.createGitCompareReader)({
+            runGit: async (args) => this.runGit(args, await this.requireRepositoryRoot()),
+        }));
+        return this.compareReaderInstance;
+    }
+    /**
+     * v0.3.17 S5 — branch/version comparison. Read-only.
+     *
+     * The resolved OIDs are part of the result on purpose: the UI freezes the opened result
+     * against them, so a ref that moves afterwards produces a "there is an update" hint
+     * instead of silently comparing against a different tree.
+     */
+    async compare(input) {
+        return this.compareReader().compare(input);
+    }
+    /** Resolves a pair of refs without computing a comparison (used to detect ref movement). */
+    async resolveComparePair(baseRef, headRef) {
+        const pair = await this.compareReader().resolvePair(baseRef, headRef);
+        return Object.freeze({ baseOid: pair.baseOid, headOid: pair.headOid });
+    }
+    /**
+     * v0.3.17 S5 — the diff one file shows between two arbitrary commits.
+     *
+     * Same bounded stream as every other diff; the only new thing is that the base is a
+     * caller-supplied resolved OID instead of a parent. The cursor margin binds the page to
+     * this exact base/head/path triple, so a different comparison cannot continue it.
+     */
+    async compareFileDiffDocument(input) {
+        const root = await this.requireRepositoryRoot();
+        const path = assertRelativeGitPath(input.path);
+        if ((0, redaction_1.isSensitiveFilePath)(path)) {
+            throw new errors_1.WebWorkbenchError(403, 'Sensitive file content is not available in the Web Workbench.', 'sensitive_file_blocked');
+        }
+        for (const oid of [input.baseOid, input.headOid]) {
+            if (!/^[0-9a-f]{7,64}$/iu.test(oid)) {
+                throw new errors_1.WebWorkbenchError(400, 'A commit hash is required.', 'git_revision_invalid');
+            }
+        }
+        const snapshot = await this.capture();
+        const lineLimit = boundedInteger(input.lineLimit ?? DEFAULT_DIFF_LINES, 1, MAX_DIFF_LINES, 'lineLimit');
+        const byteLimit = boundedInteger(input.byteLimit ?? DEFAULT_DIFF_BYTES, 1024, MAX_DIFF_BYTES, 'byteLimit');
+        const margin = (0, crypto_1.createHash)('sha256')
+            .update(`compare-diff:${input.baseOid}:${input.headOid}:${path}:${snapshot.revision}`)
+            .digest('hex')
+            .slice(0, 24);
+        const offset = input.cursor ? decodeCommitDiffCursor(input.cursor, margin) : 0;
+        const page = await streamDiffPage({
+            cwd: root,
+            commands: Object.freeze([
+                {
+                    title: 'Compare',
+                    args: [
+                        'diff',
+                        '--no-ext-diff',
+                        '--no-textconv',
+                        '--unified=3',
+                        input.baseOid,
+                        input.headOid,
+                        '--',
+                        path,
+                    ],
+                },
+            ]),
+            offset,
+            lineLimit,
+            byteLimit,
+            onProcess: () => {
+                this.performance.processCount += 1;
+            },
+            onBytes: bytes => {
+                this.performance.bytesRead += bytes;
+            },
+        });
+        this.performance.itemsParsed += page.linesParsed;
+        const document = (0, git_diff_document_1.parseGitDiffDocument)({
+            fileToken: `compare_${margin}`,
+            path,
+            source: 'commit',
+            repositoryRevision: snapshot.revision,
+            lines: page.lines,
+            hasMore: page.hasMore,
+            nextCursor: page.hasMore
+                ? encodeCommitDiffCursor({ margin, offset: offset + page.returnedLines })
+                : null,
+        });
+        return Object.freeze({
+            ...document,
+            baseOid: input.baseOid,
+            baseLabel: `比较 ${input.baseOid.slice(0, 10)} → ${input.headOid.slice(0, 10)}`,
+        });
+    }
+    versionReader() {
+        this.versionReaderInstance ?? (this.versionReaderInstance = (0, git_version_service_1.createGitVersionReader)({
+            runGit: async (args) => this.runGit(args, await this.requireRepositoryRoot()),
+            runGitBytes: async (args) => this.runGitBytes(args, await this.requireRepositoryRoot()),
+        }));
+        return this.versionReaderInstance;
+    }
+    /**
+     * v0.3.17 S5 — base / ours / theirs / worktree for a conflicted file.
+     *
+     * Read from index stages 1/2/3 rather than assembled from two diffs: a modify/delete
+     * conflict genuinely has no base, and pretending otherwise is what plan G6 forbids.
+     */
+    async conflictVersions(path) {
+        return this.versionReader().conflict(path);
+    }
+    /** Reads one file at a revision — including a file that no longer exists locally. */
+    async fileBlob(input) {
+        return this.versionReader().blob(input);
+    }
+    /** Recorded gitlink SHAs only; submodules are never traversed (plan G6). */
+    async submodules() {
+        return this.versionReader().submodules();
+    }
+    async refs() {
+        return this.historyReader().refs();
+    }
+    async history(query) {
+        return this.historyReader().history(query);
+    }
+    async commitDetail(oid, parentIndex = 0) {
+        return this.historyReader().commit(oid, parentIndex);
+    }
+    async commitFiles(oid, parentIndex = 0) {
+        return this.historyReader().commitFiles(oid, parentIndex);
+    }
+    async graph(input = {}) {
+        return this.historyReader().graph(input);
+    }
+    async blame(input) {
+        return this.historyReader().blame(input);
+    }
+    async fileHistory(input) {
+        return this.historyReader().fileHistory(input);
+    }
+    /**
+     * v0.3.17 S4 — the diff a commit introduced to one file.
+     *
+     * Rebuilds the comparison from the commit's real base (first parent, a chosen parent, or the
+     * empty tree for a root commit) and reuses `streamDiffPage`, so the byte/line budget,
+     * pagination and `--no-ext-diff`/`--no-textconv` hardening are the same code the working-tree
+     * diff uses. There is no second diff implementation to keep in sync.
+     */
+    async commitDiffDocument(input) {
+        const root = await this.requireRepositoryRoot();
+        const path = assertRelativeGitPath(input.path);
+        if ((0, redaction_1.isSensitiveFilePath)(path)) {
+            throw new errors_1.WebWorkbenchError(403, 'Sensitive file content is not available in the Web Workbench.', 'sensitive_file_blocked');
+        }
+        const parentIndex = input.parentIndex ?? 0;
+        const detail = await this.commitDetail(input.oid, parentIndex);
+        const snapshot = await this.capture();
+        const lineLimit = boundedInteger(input.lineLimit ?? DEFAULT_DIFF_LINES, 1, MAX_DIFF_LINES, 'lineLimit');
+        const byteLimit = boundedInteger(input.byteLimit ?? DEFAULT_DIFF_BYTES, 1024, MAX_DIFF_BYTES, 'byteLimit');
+        // The margin decides which comparison this page belongs to; a different commit or parent
+        // is a different document, not a continuation.
+        const margin = (0, crypto_1.createHash)('sha256')
+            .update(`commit-diff:${detail.id}:${detail.baseOid}:${parentIndex}:${snapshot.revision}`)
+            .digest('hex')
+            .slice(0, 24);
+        const offset = input.cursor ? decodeCommitDiffCursor(input.cursor, margin) : 0;
+        const page = await streamDiffPage({
+            cwd: root,
+            commands: Object.freeze([
+                {
+                    title: 'Commit',
+                    args: [
+                        'diff',
+                        '--no-ext-diff',
+                        '--no-textconv',
+                        '--unified=3',
+                        detail.baseOid,
+                        detail.id,
+                        '--',
+                        path,
+                    ],
+                },
+            ]),
+            offset,
+            lineLimit,
+            byteLimit,
+            onProcess: () => {
+                this.performance.processCount += 1;
+            },
+            onBytes: bytes => {
+                this.performance.bytesRead += bytes;
+            },
+        });
+        this.performance.itemsParsed += page.linesParsed;
+        const document = (0, git_diff_document_1.parseGitDiffDocument)({
+            fileToken: `commit_${margin}`,
+            path,
+            source: 'commit',
+            repositoryRevision: snapshot.revision,
+            lines: page.lines,
+            hasMore: page.hasMore,
+            nextCursor: page.hasMore
+                ? encodeCommitDiffCursor({ margin, offset: offset + page.returnedLines })
+                : null,
+        });
+        return Object.freeze({ ...document, baseLabel: detail.baseLabel, baseOid: detail.baseOid });
+    }
     async capture() {
         let root;
         try {
@@ -193,14 +473,21 @@ class GitReadModelServiceV1 {
                 behind: 0,
                 records: Object.freeze([]),
                 rawStatus: '',
+                stagedRecords: 0,
+                conflictedRecords: 0,
+                indexDigest: (0, crypto_1.createHash)('sha256').update('').digest('hex'),
                 revision,
             });
         }
-        const [rawStatus, branchResult, headResult, upstreamResult] = await Promise.all([
+        const [rawStatus, branchResult, headResult, upstreamResult, indexListing] = await Promise.all([
             this.runGit(['status', '--porcelain=v1', '-z', '--untracked-files=all'], root),
             this.tryGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], root),
             this.tryGit(['rev-parse', 'HEAD'], root),
             this.tryGit(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'], root),
+            // v0.3.17 S1 — the index snapshot is what makes a state revision change on
+            // stage/unstage even though HEAD does not move. `--stage` yields
+            // mode/oid/stage/path for every entry, including unmerged stages.
+            this.tryGit(['ls-files', '--stage', '-z'], root),
         ]);
         const branch = branchResult?.trim() || null;
         const head = headResult?.trim() || null;
@@ -215,7 +502,21 @@ class GitReadModelServiceV1 {
         }
         const records = parsePorcelainV1(rawStatus);
         this.performance.itemsParsed += records.length;
+        let stagedRecords = 0;
+        let conflictedRecords = 0;
+        for (const record of records) {
+            const sources = recordSources(record);
+            if (sources.includes('conflict'))
+                conflictedRecords += 1;
+            else if (sources.includes('staged'))
+                stagedRecords += 1;
+        }
         const fileFingerprints = records.map(record => fingerprintWorktreePath(root, record.path));
+        // Hash the index listing on its own so a large index never builds a second full copy
+        // of itself inside the JSON payload.
+        const indexDigest = (0, crypto_1.createHash)('sha256')
+            .update(indexListing ?? '')
+            .digest('hex');
         const revision = (0, crypto_1.createHash)('sha256')
             .update(JSON.stringify({
             root,
@@ -226,6 +527,7 @@ class GitReadModelServiceV1 {
             behind,
             rawStatus,
             fileFingerprints,
+            indexDigest,
         }))
             .digest('hex');
         return Object.freeze({
@@ -238,68 +540,404 @@ class GitReadModelServiceV1 {
             behind,
             records: Object.freeze(records),
             rawStatus,
+            stagedRecords,
+            conflictedRecords,
+            indexDigest,
             revision,
         });
     }
-    projectFile(record) {
+    projectFile(record, source) {
         return Object.freeze({
-            fileId: this.rememberPath(record.path),
+            fileId: this.rememberTarget(source, record.path),
             path: (0, redaction_1.redactTraceText)(record.path),
+            source,
             indexStatus: record.indexStatus,
             worktreeStatus: record.worktreeStatus,
             ...(record.renamedFrom ? { renamedFrom: (0, redaction_1.redactTraceText)(record.renamedFrom) } : {}),
         });
     }
-    rememberPath(path) {
-        const existing = this.idByPath.get(path);
+    rememberTarget(source, path) {
+        const key = `${source}\u0000${path}`;
+        const existing = this.idByKey.get(key);
         if (existing)
             return existing;
         const id = `git_${(0, crypto_1.createHmac)('sha256', this.secret)
-            .update(path)
+            .update(key)
             .digest('base64url')
             .slice(0, 32)}`;
-        this.idByPath.set(path, id);
-        this.pathById.set(id, path);
+        this.idByKey.set(key, id);
+        this.targetById.set(id, Object.freeze({ source, path }));
         return id;
     }
+    /**
+     * v0.3.17 S1 — the single place a Git file token becomes a path. Git mutations resolve
+     * tokens here instead of going through FileReadService, whose token space is unrelated.
+     */
+    resolveTarget(fileId) {
+        if (typeof fileId !== 'string' || fileId.length === 0 || fileId.length > 256) {
+            throw new errors_1.WebWorkbenchError(400, 'A Git file id is invalid.', 'file_id_invalid');
+        }
+        const target = this.targetById.get(fileId);
+        if (!target) {
+            throw new errors_1.WebWorkbenchError(404, 'Git file was not found.', 'git_file_not_found');
+        }
+        return target;
+    }
+    /**
+     * v0.3.17 S1 — resolve Git file tokens for a mutation and enforce the source each
+     * action may write. This replaces FileReadService token lookup, whose token space is
+     * unrelated to Git and silently rejected every real Git list token.
+     */
+    resolveMutationPaths(action, fileIds) {
+        if (!Array.isArray(fileIds) || fileIds.length === 0 || fileIds.length > 200) {
+            throw new errors_1.WebWorkbenchError(400, 'fileIds must list 1 through 200 files.');
+        }
+        const paths = [];
+        for (const fileId of fileIds) {
+            const target = this.resolveTarget(fileId);
+            const writable = action === 'stage'
+                ? target.source === 'unstaged' || target.source === 'untracked'
+                : target.source === 'staged';
+            if (!writable) {
+                // Conflict entries are deliberately not writable in this version (plan G3).
+                throw new errors_1.WebWorkbenchError(409, `A ${target.source} file cannot be ${action === 'stage' ? 'staged' : 'unstaged'}.`, 'git_source_not_writable');
+            }
+            paths.push(target.path);
+        }
+        assertSafeGitPaths(paths);
+        return paths;
+    }
     /** 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() };
+        const pathsInfo = await this.resolveIndexPaths();
+        await (0, git_index_transaction_1.withIndexTransaction)(pathsInfo, context => this.readTreeEmpty(context), async (context) => {
+            await this.runGit(['add', '--', ...paths], pathsInfo.root, 'index', context.env);
+            await this.assertIndexMatchesWorktree(pathsInfo.root, context.env, paths);
+        });
+        return this.mutationResult();
+    }
+    /**
+     * v0.3.17 S3 — prove the index entry for each path really equals what `git add` should
+     * have produced.
+     *
+     * Checking "the path is present in the index" is not enough: the path was usually already
+     * there, so a silent no-op would pass. `hash-object --path` applies exactly the filters and
+     * attributes git itself would, so comparing the two oids is a precise postcondition — and
+     * it is what turns a stat-cache no-op into a loud failure instead of a lost edit.
+     */
+    async assertIndexMatchesWorktree(root, env, paths) {
+        const entries = await this.indexEntries(root, env);
+        for (const path of paths) {
+            const entry = entries.get(path);
+            const absolute = (0, path_1.resolve)(root, path);
+            if (!isWithinRoot(absolute, root)) {
+                throw new errors_1.WebWorkbenchError(400, 'A path escaped the repository.', 'git_path_unsafe');
+            }
+            if (!(0, fs_1.existsSync)(absolute)) {
+                // A worktree deletion must have dropped the index entry.
+                if (entry !== undefined) {
+                    throw new errors_1.WebWorkbenchError(409, `The index still records a deleted file: ${path}`, 'git_index_verify_failed');
+                }
+                continue;
+            }
+            const expected = (await this.runGit(['hash-object', `--path=${path}`, '--', absolute], root, 'index', env)).trim();
+            if (entry !== expected) {
+                throw new errors_1.WebWorkbenchError(409, `The index did not record the current content of ${path}.`, 'git_index_verify_failed');
+            }
+        }
     }
     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() };
+        const pathsInfo = await this.resolveIndexPaths();
+        const head = (await this.tryGit(['rev-parse', '--verify', 'HEAD'], pathsInfo.root)) !== undefined;
+        // Captured up front so the postcondition is checked against a frozen expectation.
+        const headBlobs = new Map();
+        for (const path of paths) {
+            headBlobs.set(path, head
+                ? ((await this.tryGit(['rev-parse', `HEAD:${path}`], pathsInfo.root))?.trim() ?? null)
+                : null);
+        }
+        await (0, git_index_transaction_1.withIndexTransaction)(pathsInfo, context => this.readTreeEmpty(context), async (context) => {
+            // A repository without HEAD cannot `reset`; `rm --cached` is the index operation
+            // that matches a first-commit workflow and leaves worktree files alone (plan G3).
+            const args = head
+                ? ['reset', '-q', '--', ...paths]
+                : ['rm', '--cached', '-q', '--', ...paths];
+            await this.runGit(args, pathsInfo.root, 'index', context.env);
+            const entries = await this.indexEntries(pathsInfo.root, context.env);
+            for (const path of paths) {
+                const entry = entries.get(path);
+                const expected = headBlobs.get(path) ?? null;
+                if (expected === null) {
+                    if (entry !== undefined) {
+                        throw new errors_1.WebWorkbenchError(409, 'The index did not drop the expected entry.', 'git_index_verify_failed');
+                    }
+                }
+                else if (entry !== expected) {
+                    throw new errors_1.WebWorkbenchError(409, 'The index did not return to the committed version.', 'git_index_verify_failed');
+                }
+            }
+        });
+        return this.mutationResult();
+    }
+    /**
+     * v0.3.17 S3 — apply a hunk or line selection to the index only (plan §7.6/§7.8).
+     *
+     * The document is re-read on the Host, the patch is rebuilt from it, and `--check` runs
+     * before the write. The browser only ever sends ids, never patch text.
+     */
+    async applySelection(input) {
+        const document = await this.diffDocument({ fileId: input.fileId });
+        const built = (0, git_patch_builder_1.buildSelectionPatch)(document, {
+            ...(input.hunkIds ? { hunkIds: input.hunkIds } : {}),
+            ...(input.lineIds ? { lineIds: input.lineIds } : {}),
+        });
+        if (!built.ok) {
+            throw new errors_1.WebWorkbenchError(409, built.reason, 'git_patch_not_applicable');
+        }
+        // Unstaging a selection is the same patch applied backwards against the index.
+        const reverse = document.source === 'staged';
+        return this.applyIndexPatch(built.patch, { reverse });
     }
-    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.');
+    /**
+     * Applies a Host-rebuilt patch to the index only (plan §7.6). The patch never comes from
+     * the browser: it is rebuilt from the reviewed document, and `--check` runs first so a
+     * patch that cannot apply is rejected before anything is written into the private index.
+     */
+    async applyIndexPatch(patch, options = {}) {
+        if (typeof patch !== 'string' || patch.length === 0 || patch.length > 1000000) {
+            throw new errors_1.WebWorkbenchError(400, 'A patch must be a bounded string.', 'git_patch_invalid');
         }
+        const pathsInfo = await this.resolveIndexPaths();
+        const direction = options.reverse ? ['--reverse'] : [];
+        await (0, git_index_transaction_1.withIndexTransaction)(pathsInfo, context => this.readTreeEmpty(context), async (context) => {
+            // `--recount` derives line counts from the body, so a partially rebuilt hunk still
+            // applies exactly as written. `--check` first: nothing is written on a failed check.
+            await this.runGit(['apply', '--cached', '--check', '--recount', ...direction, '-'], pathsInfo.root, 'index', context.env, patch).catch(error => {
+                const message = error instanceof Error ? error.message : '';
+                // A patch rebuilt from the reviewed document can still be inapplicable to the real
+                // index. CRLF line endings are the common cause: the diff text cannot represent them
+                // unambiguously, so the rebuilt context does not match the stored bytes. The plan
+                // requires such a selection to be refused explicitly rather than to fail as a Git
+                // error — nothing has been written at this point.
+                throw new errors_1.WebWorkbenchError(409, /patch failed|patch does not apply/iu.test(message)
+                    ? 'This selection cannot be applied to the index (CRLF line endings are a common cause).'
+                    : message, 'git_patch_not_applicable');
+            });
+            await this.runGit(['apply', '--cached', '--recount', ...direction, '-'], pathsInfo.root, 'index', context.env, patch);
+        });
+        return this.mutationResult();
+    }
+    async readTreeEmpty(context) {
         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.runGit(['read-tree', '--empty'], root, 'index', context.env);
+    }
+    /** `ls-files --stage -z` parsed into path → blob oid, honouring a private index env. */
+    async indexEntries(root, env) {
+        const raw = await this.runGit(['ls-files', '--stage', '-z'], root, 'index', env);
+        const entries = new Map();
+        for (const record of raw.split('\0')) {
+            if (!record)
+                continue;
+            const tab = record.indexOf('\t');
+            if (tab < 0)
+                continue;
+            const meta = record.slice(0, tab).split(' ');
+            const path = record.slice(tab + 1);
+            // Unmerged stages share a path; the first stage recorded is enough for verification.
+            if (!entries.has(path))
+                entries.set(path, meta[1] ?? '');
         }
-        await this.mutate(['commit', '-m', trimmed]);
-        const sha = (await this.runGit(['rev-parse', 'HEAD'], root)).trim();
-        return { repositoryRevision: await this.revisionAfterMutation(), commitSha: sha };
+        return entries;
     }
-    async mutate(args) {
+    /** Resolves root, git dir and the real index path (worktree-aware). */
+    async resolveIndexPaths() {
         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.
+        // `--git-path index` resolves into `.git/worktrees/<name>/index` for a linked worktree,
+        // which is the index this workspace actually writes — not the main worktree's.
+        const indexPath = (0, path_1.resolve)(root, (await this.runGit(['rev-parse', '--git-path', 'index'], root)).trim());
+        const gitDir = (await this.runGit(['rev-parse', '--absolute-git-dir'], root)).trim();
+        return { root, gitDir, indexPath };
+    }
+    async mutationResult() {
+        return { repositoryRevision: await this.revisionAfterMutation() };
+    }
+    /**
+     * v0.3.17 S3 — what a commit would actually include.
+     *
+     * This is deliberately independent of the change-list filter: plan G3 requires the form to
+     * show the real index, not the currently filtered view, so the reader can never commit a
+     * subset they did not intend.
+     */
+    async commitPreview() {
+        const snapshot = await this.capture();
+        if (!snapshot.isRepository || !snapshot.root) {
+            throw new errors_1.WebWorkbenchError(409, 'Git repository is unavailable.', 'git_not_repository');
+        }
+        const root = snapshot.root;
+        const entries = [];
+        for (const record of snapshot.records) {
+            const sources = recordSources(record);
+            if (sources.includes('conflict')) {
+                entries.push(Object.freeze({
+                    path: (0, redaction_1.redactTraceText)(record.path),
+                    source: 'conflict',
+                    status: `${record.indexStatus}${record.worktreeStatus}`,
+                }));
+                continue;
+            }
+            if (sources.includes('staged')) {
+                entries.push(Object.freeze({
+                    path: (0, redaction_1.redactTraceText)(record.path),
+                    source: 'staged',
+                    status: `${record.indexStatus}${record.worktreeStatus}`,
+                }));
+            }
+        }
+        const stats = await this.stagedNumstat(root);
+        const identity = await this.describeCommitConfiguration(root);
+        const hasConflict = snapshot.conflictedRecords > 0;
+        const blockedReason = hasConflict
+            ? '存在未解决的冲突，请先在 Files 中处理。'
+            : entries.length === 0
+                ? '暂存区为空，没有可提交的改动。'
+                : null;
+        return Object.freeze({
+            repositoryRevision: snapshot.revision,
+            branch: snapshot.branch,
+            detached: !snapshot.branch,
+            entries: Object.freeze(entries),
+            additions: stats.additions,
+            deletions: stats.deletions,
+            filesChanged: entries.length,
+            identity,
+            canCommit: blockedReason === null,
+            blockedReason,
+        });
+    }
+    /** Bounded `--cached --numstat` read; used only for the summary line of the form. */
+    async stagedNumstat(root) {
+        const raw = await this.tryGit(['diff', '--cached', '--numstat', '--no-ext-diff', '--no-textconv', '-z'], root);
+        if (!raw)
+            return { additions: 0, deletions: 0 };
+        let additions = 0;
+        let deletions = 0;
+        for (const record of raw.split('\0')) {
+            if (!record)
+                continue;
+            const [added, removed] = record.split('\t');
+            // Binary entries report `-` for both counts and contribute nothing to the totals.
+            if (/^\d+$/u.test(added ?? ''))
+                additions += Number(added);
+            if (/^\d+$/u.test(removed ?? ''))
+                deletions += Number(removed);
+        }
+        return { additions, deletions };
+    }
+    /**
+     * v0.3.17 S3 — commit against a frozen expectation of HEAD and the index tree (plan §7.9).
+     *
+     * Differences from the previous implementation, all deliberate:
+     *   - a **separate runner** that leaves the repository's own hooks and signing
+     *     configuration in place, instead of the read hardening that disables hooks;
+     *   - the message may contain real newlines (summary + body) and is rejected only for
+     *     control characters that would corrupt a commit object;
+     *   - the index and HEAD are captured before and re-read after, and any change that is not
+     *     ours is reported rather than rolled back;
+     *   - a timeout is not treated as "not committed": the outcome is queried by requestId.
+     */
+    async commit(input) {
+        const message = normalizeCommitMessage(input.summary, input.body);
+        if (typeof input.requestId !== 'string' || !/^[A-Za-z0-9_-]{8,64}$/u.test(input.requestId)) {
+            throw new errors_1.WebWorkbenchError(400, 'requestId is invalid.', 'git_request_id_invalid');
+        }
+        const pathsInfo = await this.resolveIndexPaths();
+        const before = await this.capture();
+        if (!before.isRepository) {
+            throw new errors_1.WebWorkbenchError(409, 'Git repository is unavailable.', 'git_not_repository');
+        }
+        if (before.revision !== input.expectedRepositoryRevision) {
+            throw new errors_1.WebWorkbenchError(409, 'Repository changed before commit.', 'git_revision_conflict');
+        }
+        if (before.conflictedRecords > 0) {
+            throw new errors_1.WebWorkbenchError(409, 'Unresolved conflicts must be handled before committing.', 'git_conflict_unresolved');
+        }
+        if (before.stagedRecords === 0) {
+            throw new errors_1.WebWorkbenchError(409, 'Nothing is staged to commit.', 'git_nothing_staged');
+        }
+        const previousHead = before.head;
+        const identity = await this.describeCommitConfiguration(pathsInfo.root);
+        const startedAt = Date.now();
+        try {
+            // `-F -` so the message travels as a literal payload; no shell, no argument parsing.
+            await this.runGit(['commit', '-F', '-'], pathsInfo.root, 'commit', undefined, message);
         }
+        catch (error) {
+            // A timed-out or interrupted commit may still have landed. Always report the truth.
+            const recovery = await this.recoverCommit(pathsInfo.root, previousHead);
+            if (recovery.committed && recovery.commitSha) {
+                return Object.freeze({
+                    status: 'committed',
+                    commitSha: recovery.commitSha,
+                    repositoryRevision: await this.revisionAfterMutation(),
+                    durationMs: Date.now() - startedAt,
+                    identity,
+                    warning: `提交进程报告失败，但提交已实际完成：${describeError(error)}`,
+                });
+            }
+            throw error;
+        }
+        const after = await this.recoverCommit(pathsInfo.root, previousHead);
+        if (!after.committed || !after.commitSha) {
+            throw new errors_1.WebWorkbenchError(503, 'The commit did not produce a new HEAD.', 'git_commit_unconfirmed');
+        }
+        return Object.freeze({
+            status: 'committed',
+            commitSha: after.commitSha,
+            repositoryRevision: await this.revisionAfterMutation(),
+            durationMs: Date.now() - startedAt,
+            identity,
+        });
+    }
+    /**
+     * A commit is confirmed by HEAD having moved to a *new* commit, never by exit code alone.
+     * This is what makes the timeout path safe: we ask Git what actually happened.
+     */
+    async recoverCommit(root, previousHead) {
+        const head = (await this.tryGit(['rev-parse', '--verify', 'HEAD'], root))?.trim() ?? null;
+        if (!head)
+            return { committed: false, commitSha: null };
+        if (head === previousHead)
+            return { committed: false, commitSha: null };
+        return { committed: true, commitSha: head };
+    }
+    /** Identity and hook configuration the commit will actually run under (plan §7.9). */
+    async describeCommitConfiguration(root) {
+        const name = (await this.tryGit(['config', 'user.name'], root))?.trim() ?? null;
+        const email = (await this.tryGit(['config', 'user.email'], root))?.trim() ?? null;
+        const signingKey = (await this.tryGit(['config', 'user.signingkey'], root))?.trim() ?? null;
+        const gpgsign = (await this.tryGit(['config', 'commit.gpgsign'], root))?.trim() ?? null;
+        // `rev-parse --git-path hooks` accounts for core.hooksPath; a missing directory means no
+        // hooks will run, which the form states instead of silently skipping them.
+        const hooksPath = (await this.tryGit(['rev-parse', '--git-path', 'hooks'], root))?.trim() ?? null;
+        const hooksDir = hooksPath ? (0, path_1.resolve)(root, hooksPath) : null;
+        return Object.freeze({
+            name,
+            email,
+            signingKey,
+            signingEnabled: gpgsign === 'true',
+            hooksDir,
+            hooksPresent: hooksDir !== null && (0, fs_1.existsSync)(hooksDir),
+        });
+    }
+    async mutate(args) {
+        const root = await this.requireRepositoryRoot();
+        await this.runGit(args, root, 'index');
     }
     async requireRepositoryRoot() {
         const snapshot = await this.capture();
@@ -308,41 +946,133 @@ class GitReadModelServiceV1 {
         }
         return snapshot.root;
     }
+    /**
+     * v0.3.17 S1 — a mutation reports the same state digest `status()` reports. Returning
+     * `rev-parse HEAD` was a different value space AND did not move on stage/unstage, so it
+     * could never express "the index changed".
+     *
+     * NOTE: this is post-write verification, not an atomic compare-and-swap. The real
+     * check-write window is S3 scope (plan §7.7); until then nothing may claim atomicity.
+     */
     async revisionAfterMutation() {
-        const root = await this.requireRepositoryRoot();
-        return this.runGit(['rev-parse', 'HEAD'], root).then(value => value.trim());
+        const snapshot = await this.capture();
+        if (!snapshot.isRepository)
+            throw new Error('Git repository is unavailable.');
+        return snapshot.revision;
     }
-    runGit(args, cwd) {
+    /**
+     * v0.3.17 S3 — one exec path, three explicit profiles.
+     *
+     * `read` keeps every hardening from v0.3.12. `index` relaxes only what staging must
+     * resolve (user config for filters/CRLF) while keeping hooks disabled. `commit` is the
+     * deliberate exception from plan §7.9: it lets the repository's own hooks and signing
+     * configuration run, and gets its own bounded budget instead of the 5s read budget.
+     * The profiles are separate on purpose — enabling commit hooks must not relax reads.
+     *
+     * Implemented with `spawn` rather than `execFile` for two reasons found the hard way:
+     *   1. the async `execFile`/`exec` `input` option is silently ignored, so `git apply -`
+     *      blocked forever waiting for stdin that never closed;
+     *   2. a timeout must kill the whole process group, otherwise a slow `pre-commit` hook
+     *      survives as an orphan while we report failure.
+     */
+    runGit(args, cwd, profile = 'read', env, input) {
+        return this.runGitBytes(args, cwd, profile, env, input).then(buffer => buffer.toString('utf8'));
+    }
+    /**
+     * v0.3.17 S5 — the byte-level primitive behind `runGit`.
+     *
+     * Historical file content may not be valid UTF-8, so blob reads must not round-trip
+     * through a string. Everything else (hardening prefix, profile, byte budget, timeout,
+     * process-group kill) is shared, which is why this is the same body and not a copy.
+     */
+    runGitBytes(args, cwd, profile = 'read', env, 
+    /** stdin payload, used by `git apply -` and `git commit -F -`. Never browser input. */
+    input) {
+        const prefix = profile === 'read'
+            ? hardenedGitPrefix()
+            : profile === 'index'
+                ? (0, git_index_transaction_1.writeGitPrefix)()
+                : commitGitPrefix();
+        const environment = profile === 'read' ? gitEnvironment() : (env ?? (0, git_index_transaction_1.writeGitEnvironment)());
+        const timeout = profile === 'commit' ? this.commitTimeoutMs : GIT_TIMEOUT_MS;
         return new Promise((resolvePromise, reject) => {
             this.performance.processCount += 1;
-            (0, child_process_1.execFile)('git', [...hardenedGitPrefix(), ...args], {
+            const child = (0, child_process_1.spawn)('git', [...prefix, ...args], {
                 cwd,
-                encoding: 'utf8',
-                timeout: GIT_TIMEOUT_MS,
-                maxBuffer: GIT_MAX_BUFFER,
-                env: gitEnvironment(),
-            }, (error, stdout, stderr) => {
-                this.performance.bytesRead +=
-                    Buffer.byteLength(stdout, 'utf8') + Buffer.byteLength(stderr, 'utf8');
+                env: environment,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                // Own process group, so a timeout can take the hook processes down with it.
+                detached: true,
+            });
+            const stdout = [];
+            const stderr = [];
+            let bytes = 0;
+            let settled = false;
+            let timedOut = false;
+            let overflowed = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                killProcessTree(child);
+            }, timeout);
+            child.stdout.on('data', (chunk) => {
+                bytes += chunk.length;
+                this.performance.bytesRead += chunk.length;
+                if (bytes > GIT_MAX_BUFFER) {
+                    overflowed = true;
+                    killProcessTree(child);
+                    return;
+                }
+                stdout.push(chunk);
+            });
+            child.stderr.on('data', (chunk) => {
+                bytes += chunk.length;
+                this.performance.bytesRead += chunk.length;
+                if (bytes > GIT_MAX_BUFFER) {
+                    overflowed = true;
+                    killProcessTree(child);
+                    return;
+                }
+                stderr.push(chunk);
+            });
+            const settle = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
                 if (error) {
-                    const processError = error;
-                    const timedOut = processError.code === 'ETIMEDOUT' ||
-                        (processError.killed && processError.signal === 'SIGTERM');
-                    const outputTooLarge = processError.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' ||
-                        /maxBuffer length exceeded/iu.test(processError.message);
-                    reject(new errors_1.WebWorkbenchError(503, timedOut
-                        ? 'Git command timed out.'
-                        : outputTooLarge
-                            ? 'Git output exceeded the bounded read limit.'
-                            : (0, redaction_1.redactTraceText)(stderr || error.message || 'Git command failed.'), timedOut
-                        ? 'git_timeout'
-                        : outputTooLarge
-                            ? 'git_output_too_large'
-                            : 'git_command_failed'));
+                    reject(error);
+                    return;
+                }
+                resolvePromise(Buffer.concat(stdout));
+            };
+            child.on('error', (error) => {
+                settle(new errors_1.WebWorkbenchError(503, (0, redaction_1.redactTraceText)(error.message), 'git_command_failed'));
+            });
+            child.on('close', (code) => {
+                if (timedOut) {
+                    settle(new errors_1.WebWorkbenchError(503, 'Git command timed out.', 'git_timeout'));
+                    return;
+                }
+                if (overflowed) {
+                    settle(new errors_1.WebWorkbenchError(503, 'Git output exceeded the bounded read limit.', 'git_output_too_large'));
                     return;
                 }
-                resolvePromise(stdout);
+                if (code === 0) {
+                    settle();
+                    return;
+                }
+                const message = Buffer.concat(stderr).toString('utf8').trim();
+                settle(new errors_1.WebWorkbenchError(503, (0, redaction_1.redactTraceText)(message || `Git exited with code ${code ?? 'unknown'}.`), 'git_command_failed'));
             });
+            if (input === undefined) {
+                child.stdin.end();
+                return;
+            }
+            // stdin must be explicitly closed; a `-` argument otherwise blocks the child forever.
+            child.stdin.on('error', () => {
+                // The child may exit before consuming the payload; the close handler already decided.
+            });
+            child.stdin.end(input, 'utf8');
         });
     }
     async tryGit(args, cwd) {
@@ -358,7 +1088,7 @@ class GitReadModelServiceV1 {
         const signature = (0, crypto_1.createHmac)('sha256', this.secret).update(body).digest('base64url');
         return `${body}.${signature}`;
     }
-    decodeCursor(cursor, kind, revision, fileId) {
+    decodeCursor(cursor, kind, revision, fileId, scope) {
         if (!cursor || cursor.length > 4096)
             return invalidCursor();
         const [body, encodedSignature, extra] = cursor.split('.');
@@ -377,9 +1107,10 @@ class GitReadModelServiceV1 {
         }
         try {
             const parsed = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
-            if (parsed.version !== 1 ||
+            if (parsed.version !== 2 ||
                 parsed.kind !== kind ||
                 parsed.fileId !== fileId ||
+                parsed.scope !== scope ||
                 !Number.isSafeInteger(parsed.offset) ||
                 parsed.offset < 0) {
                 return invalidCursor();
@@ -431,11 +1162,8 @@ function safeGitPath(path) {
         !path.startsWith('../') &&
         !path.includes('/../'));
 }
-function isConflict(file) {
-    return (file.indexStatus === 'U' ||
-        file.worktreeStatus === 'U' ||
-        `${file.indexStatus}${file.worktreeStatus}` === 'AA' ||
-        `${file.indexStatus}${file.worktreeStatus}` === 'DD');
+function recordStillMatches(record, source) {
+    return recordSources(record).includes(source);
 }
 function parseCommit(record) {
     const [id, shortId, timestamp, authorName, subject] = record.split('\x1f');
@@ -454,38 +1182,128 @@ function parseCommit(record) {
         subject: (0, redaction_1.redactTraceText)(subject),
     });
 }
-function diffCommands(record, path) {
-    const commands = [];
-    if (isConflictRecord(record) || (record.indexStatus !== ' ' && record.indexStatus !== '?')) {
-        commands.push({
+/**
+ * v0.3.17 S1 — the token's source decides the command, so exactly one comparison is
+ * produced. Previously a mixed (`MM`) file emitted both `--cached` and worktree diffs and
+ * the caller merged them into one page, making the two sources indistinguishable.
+ */
+function diffCommands(path, source, ignoreWhitespace = false, wordDiff = false) {
+    const modes = [
+        ...(ignoreWhitespace ? ['--ignore-all-space'] : []),
+        ...(wordDiff ? ['--word-diff=plain'] : []),
+    ];
+    if (source === 'staged') {
+        return Object.freeze([
+            {
+                title: 'Staged',
+                args: ['diff', '--cached', ...modes, '--no-ext-diff', '--no-textconv', '--unified=3', '--', path],
+            },
+        ]);
+    }
+    if (source === 'unstaged') {
+        return Object.freeze([
+            {
+                title: 'Working tree',
+                args: ['diff', ...modes, '--no-ext-diff', '--no-textconv', '--unified=3', '--', path],
+            },
+        ]);
+    }
+    if (source === 'untracked') {
+        return Object.freeze([
+            {
+                title: 'Untracked',
+                args: [
+                    'diff',
+                    '--no-index',
+                    ...modes,
+                    '--no-ext-diff',
+                    '--no-textconv',
+                    '--unified=3',
+                    '--',
+                    GIT_NULL_DEVICE,
+                    path,
+                ],
+                acceptedExitCodes: [0, 1],
+            },
+        ]);
+    }
+    // Conflict version selection (base / ours / theirs) is S5 scope. Until then keep the
+    // pre-existing index-vs-worktree pair so nothing regresses.
+    return Object.freeze([
+        {
             title: 'Staged',
             args: ['diff', '--cached', '--no-ext-diff', '--no-textconv', '--unified=3', '--', path],
-        });
-    }
-    if (isConflictRecord(record) ||
-        (record.worktreeStatus !== ' ' && record.worktreeStatus !== '?')) {
-        commands.push({
+        },
+        {
             title: 'Working tree',
             args: ['diff', '--no-ext-diff', '--no-textconv', '--unified=3', '--', path],
-        });
+        },
+    ]);
+}
+/** v0.3.17 S1 — every comparison source a status record participates in. */
+// A status record is always a working-tree state; typing the result narrowly makes the
+// compiler enforce that no comparison-only source can ever leak into a status bucket.
+function recordSources(record) {
+    if (isConflictRecord(record))
+        return Object.freeze(['conflict']);
+    if (record.indexStatus === '?')
+        return Object.freeze(['untracked']);
+    const sources = [];
+    if (record.indexStatus !== ' ')
+        sources.push('staged');
+    if (record.worktreeStatus !== ' ')
+        sources.push('unstaged');
+    return Object.freeze(sources);
+}
+function countSources(records) {
+    let conflicted = 0;
+    let staged = 0;
+    let unstaged = 0;
+    let untracked = 0;
+    for (const record of records) {
+        for (const source of recordSources(record)) {
+            if (source === 'staged')
+                staged += 1;
+            else if (source === 'unstaged')
+                unstaged += 1;
+            else if (source === 'untracked')
+                untracked += 1;
+            else
+                conflicted += 1;
+        }
     }
-    if (record.indexStatus === '?') {
-        commands.push({
-            title: 'Untracked',
-            args: [
-                'diff',
-                '--no-index',
-                '--no-ext-diff',
-                '--no-textconv',
-                '--unified=3',
-                '--',
-                '/dev/null',
-                path,
-            ],
-            acceptedExitCodes: [0, 1],
-        });
+    return { total: records.length, conflicted, staged, unstaged, untracked };
+}
+/**
+ * v0.3.17 S4 — the status group filter accepts only a working-tree source.
+ *
+ * The distinction is load-bearing: passing the wider comparison-source union here would let a
+ * caller ask for the `commit` group and silently get nothing, hiding the mistake. It is
+ * rejected up front with a clear code instead.
+ */
+function normalizeSource(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (!git_file_source_1.GIT_WORKTREE_SOURCES_V1.includes(value)) {
+        throw new errors_1.WebWorkbenchError(400, 'group must be a known Git file source.', 'git_query_invalid');
+    }
+    return value;
+}
+function normalizeQuery(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (typeof value !== 'string' || value.length > 256) {
+        throw new errors_1.WebWorkbenchError(400, 'query must be a string of at most 256 characters.', 'git_query_invalid');
     }
-    return commands;
+    const trimmed = value.trim();
+    return trimmed ? trimmed.toLocaleLowerCase() : undefined;
+}
+/** Binds the active filter into the cursor so pages never mix two query scopes. */
+function statusScope(group, query) {
+    return (0, crypto_1.createHash)('sha256')
+        .update(`${group ?? '*'}\u0000${query ?? '*'}`)
+        .digest('hex')
+        .slice(0, 16);
 }
 function isConflictRecord(record) {
     return (record.indexStatus === 'U' ||
@@ -681,6 +1499,117 @@ function hardenedGitPrefix() {
         '--literal-pathspecs',
     ];
 }
+/**
+ * v0.3.17 S3 — commit runner prefix.
+ *
+ * This is the one place where hooks are deliberately **not** disabled and the user's own
+ * configuration is authoritative (plan §7.9). It is a separate function, not a parameter on
+ * the read prefix, so enabling commit hooks can never leak into Git reads.
+ */
+function commitGitPrefix() {
+    return ['-c', 'core.quotepath=false', '--literal-pathspecs'];
+}
+/**
+ * v0.3.17 S3 — summary plus optional body.
+ *
+ * The previous validator rejected any newline, which made a real commit body impossible
+ * (plan G3 asks for exactly that fix). What must still be rejected are characters that would
+ * corrupt or truncate the commit object: NUL and other C0 controls, except the newlines and
+ * tabs a message legitimately contains.
+ */
+function normalizeCommitMessage(summary, body) {
+    if (typeof summary !== 'string') {
+        throw new errors_1.WebWorkbenchError(400, 'A commit summary is required.', 'git_message_invalid');
+    }
+    const trimmedSummary = summary.trim();
+    if (!trimmedSummary) {
+        throw new errors_1.WebWorkbenchError(400, 'A commit summary is required.', 'git_message_invalid');
+    }
+    if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/u.test(trimmedSummary)) {
+        throw new errors_1.WebWorkbenchError(400, 'A commit summary must not contain control characters.', 'git_message_invalid');
+    }
+    const trimmedBody = (body ?? '').replace(/\r\n/gu, '\n').trim();
+    if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/u.test(trimmedBody)) {
+        throw new errors_1.WebWorkbenchError(400, 'A commit body must not contain control characters.', 'git_message_invalid');
+    }
+    const message = trimmedBody ? `${trimmedSummary}\n\n${trimmedBody}\n` : `${trimmedSummary}\n`;
+    // Bound the whole payload, not just each half.
+    if (message.length > 20000) {
+        throw new errors_1.WebWorkbenchError(400, 'A commit message is too long.', 'git_message_invalid');
+    }
+    return message;
+}
+/** Binds the two content-changing diff modes into the pagination cursor scope. */
+function diffScope(ignoreWhitespace, wordDiff) {
+    return `iw:${ignoreWhitespace ? 1 : 0}:wd:${wordDiff ? 1 : 0}`;
+}
+function describeError(error) {
+    return (0, redaction_1.redactTraceText)(error instanceof Error ? error.message : 'unknown error');
+}
+/**
+ * v0.3.17 S4 — a repository-relative path coming from a history request.
+ *
+ * Validated, never escaped: anything that could be read as a revision expression, a pathspec
+ * magic prefix or an absolute path is refused outright rather than passed to argv.
+ */
+function assertRelativeGitPath(path) {
+    if (typeof path !== 'string' || !path || path.length > 1024) {
+        throw new errors_1.WebWorkbenchError(400, 'A file path is required.', 'git_path_invalid');
+    }
+    if (path.startsWith('/') || path.includes('\0') || path.startsWith(':')) {
+        throw new errors_1.WebWorkbenchError(400, 'Unsafe Git path.', 'git_path_unsafe');
+    }
+    const segments = path.split('/');
+    if (segments.some(segment => segment === '..' || segment === '.' || segment === '')) {
+        throw new errors_1.WebWorkbenchError(400, 'Unsafe Git path.', 'git_path_unsafe');
+    }
+    return path;
+}
+/**
+ * A commit-diff cursor carries its comparison identity, so a page from a different commit,
+ * base or parent is rejected instead of silently stitched onto the wrong document.
+ */
+function encodeCommitDiffCursor(input) {
+    return Buffer.from(JSON.stringify({ v: 1, ...input }), 'utf8').toString('base64url');
+}
+function decodeCommitDiffCursor(cursor, margin) {
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new errors_1.WebWorkbenchError(400, 'Diff cursor is not valid.', 'git_cursor_invalid');
+    }
+    const candidate = parsed;
+    if (candidate.margin !== margin ||
+        typeof candidate.offset !== 'number' ||
+        !Number.isInteger(candidate.offset) ||
+        candidate.offset < 0) {
+        throw new errors_1.WebWorkbenchError(409, 'Diff changed; reload before paginating.', 'git_cursor_invalid');
+    }
+    return candidate.offset;
+}
+/**
+ * Kills a detached child and everything it spawned.
+ *
+ * A `pre-commit` hook runs as a child of `git`, so killing only `git` on timeout would leave
+ * the hook running and, worse, leave `index.lock` behind if the hook owned it.
+ */
+function killProcessTree(child) {
+    if (child.pid === undefined)
+        return;
+    try {
+        process.kill(-child.pid, 'SIGKILL');
+    }
+    catch {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
 function canonicalDirectory(path) {
     try {
         const canonical = (0, fs_1.realpathSync)((0, path_1.resolve)(path));