@senad-d/branchme 0.3.15 → 0.3.16

package/src/git-history.ts

@@ -0,0 +1,112 @@
+import { getGitDiff } from "./git-diff.ts";
+import {
+  boundedGitText, decodeReadCursor, encodeReadCursor, fingerprint, OBJECT_ID, openGitReader,
+  readBlob, readGit, READ_PAGE_SIZE, resolveReadCommit, safeGitText, validateKeys,
+  validateReadPath, validateReadPaths, validateReadRef, type GitAPI, type GitReader,
+} from "./git-read.ts";
+import type { GitCommandContext } from "./git.ts";
+
+export interface GitLogInput { ref?: string; excludeRef?: string; paths?: string[]; after?: string; worktreePath?: string }
+export interface GitShowInput { ref?: string; output?: "summary" | "patch" | "file"; path?: string; parent?: number; worktreePath?: string }
+export interface HistoryCommit { head: string; parents: string[]; date: string; subject: string; subjectTruncated?: boolean; message?: string; messageTruncated?: boolean }
+const LOG_FORMAT = "%H%x00%P%x00%aI%x00%s";
+
+function parseCommits(raw: string, reader: GitReader): HistoryCommit[] {
+  if (!raw) return [];
+  const fields = raw.endsWith("\0") ? raw.slice(0, -1).split("\0") : [];
+  if (fields.length % 4 || !fields.length) throw new Error("Malformed history output.");
+  const commits: HistoryCommit[] = [];
+  for (let i = 0; i < fields.length; i += 4) {
+    const [head, parentText, date, subject] = fields.slice(i, i + 4);
+    const parents = parentText ? parentText.split(" ") : [];
+    if (!OBJECT_ID.test(head) || !parents.every(isOid) || parents.length > 16 || date.length > 40 || !/^\d{4}-\d\d-\d\dT/u.test(date) || !Number.isFinite(Date.parse(date))) throw new Error("Malformed history identities/date.");
+    const preview = boundedGitText(subject, reader.tokens, 512, 1);
+    commits.push({ head, parents, date, subject: preview.text, subjectTruncated: preview.truncated });
+  }
+  return commits;
+}
+function isOid(value: string): boolean { return OBJECT_ID.test(value); }
+async function unbornHead(reader: GitReader): Promise<boolean> {
+  const head = await readGit(reader, ["rev-parse", "--verify", "--quiet", "HEAD"], true);
+  if (head.code === 0) return false;
+  const symbolic = await readGit(reader, ["symbolic-ref", "--quiet", "HEAD"], true);
+  if (head.code !== 1 || symbolic.code !== 0 || !symbolic.stdout.startsWith("refs/heads/")) return false;
+  const ref = symbolic.stdout.trimEnd();
+  const present = await readGit(reader, ["show-ref", "--verify", "--quiet", ref], true);
+  return present.code === 1;
+}
+export async function getGitLog(host: GitAPI, ctx: GitCommandContext, input: GitLogInput = {}, signal?: AbortSignal, tokens: readonly string[] = []) {
+  validateKeys(input, ["ref", "excludeRef", "paths", "after", "worktreePath"]);
+  validateReadRef(input.ref ?? "HEAD");
+  if (input.excludeRef !== undefined) validateReadRef(input.excludeRef);
+  validateReadPaths(input.paths);
+  const reader = await openGitReader(host, ctx, input.worktreePath, signal, tokens);
+  const shallow = (await readGit(reader, ["rev-parse", "--is-shallow-repository"])).stdout.trim() === "true";
+  const query = fingerprint(JSON.stringify([reader.ctx.cwd, input.ref ?? "HEAD", input.excludeRef ?? null, input.paths ?? []]));
+  let start: string;
+  let exclude: string | null;
+  let offset = 0;
+  if (input.after !== undefined) {
+    const fields = decodeReadCursor(input.after);
+    if (fields.length !== 5 || fields[0] !== "log1" || fields[1] !== query || typeof fields[2] !== "string" || !OBJECT_ID.test(fields[2]) || (fields[3] !== null && (typeof fields[3] !== "string" || !OBJECT_ID.test(fields[3]))) || !Number.isSafeInteger(fields[4]) || Number(fields[4]) < 1 || Number(fields[4]) > 100000) throw new Error("History continuation belongs to another query or is invalid; restart without after.");
+    start = await resolveReadCommit(reader, fields[2]);
+    exclude = fields[3] === null ? null : await resolveReadCommit(reader, fields[3] as string);
+    offset = fields[4] as number;
+  } else {
+    if ((input.ref ?? "HEAD") === "HEAD" && await unbornHead(reader)) return { action: "git_log", repoRoot: safeGitText(reader.ctx.cwd, tokens), start: null, exclude: null, unborn: true, shallow, commits: [], complete: true, next: null };
+    start = await resolveReadCommit(reader, input.ref ?? "HEAD");
+    exclude = input.excludeRef === undefined ? null : await resolveReadCommit(reader, input.excludeRef);
+  }
+  const result = await readGit(reader, ["--literal-pathspecs", "log", "-z", `--format=${LOG_FORMAT}`, "--no-show-signature", "--no-decorate", "--no-notes", "--topo-order", `--skip=${offset}`, `--max-count=${READ_PAGE_SIZE + 1}`, start, ...(exclude ? [`^${exclude}`] : []), "--", ...(input.paths ?? [])]);
+  const all = parseCommits(result.stdout, reader);
+  const commits = all.slice(0, READ_PAGE_SIZE);
+  const complete = all.length <= READ_PAGE_SIZE;
+  return { action: "git_log", repoRoot: safeGitText(reader.ctx.cwd, tokens), start, exclude, unborn: false, shallow, commits, complete, next: complete ? null : encodeReadCursor(["log1", query, start, exclude, offset + commits.length]) };
+}
+
+function validateShowInput(input: GitShowInput): void {
+  validateKeys(input, ["ref", "output", "path", "parent", "worktreePath"]);
+  validateReadRef(input.ref ?? "HEAD");
+  const output = input.output ?? "summary";
+  if (!["summary", "patch", "file"].includes(output)) throw new TypeError("Unknown git_show output.");
+  if (input.path !== undefined) validateReadPath(input.path);
+  if (input.parent !== undefined && (!Number.isInteger(input.parent) || input.parent < 1 || input.parent > 100 || output === "file")) throw new TypeError("parent must select a 1-based commit parent for summary/patch output.");
+  if (output === "file" && input.path === undefined) throw new TypeError("git_show file output requires one literal path.");
+}
+
+async function showFile(reader: GitReader, commit: HistoryCommit, path: string) {
+  const tree = await readGit(reader, ["--literal-pathspecs", "ls-tree", "-z", commit.head, "--", path]);
+  const match = /^([0-7]{6}) blob ([a-f0-9]{40}|[a-f0-9]{64})\t([^\0]+)\0$/u.exec(tree.stdout);
+  if (match?.[3] !== path) throw new Error("Path does not name one blob at the captured commit (directories/gitlinks are unsupported).");
+  return { action: "git_show", commit, output: "file", path: safeGitText(path, reader.tokens), mode: match[1], blob: match[2], ...await readBlob(reader, match[2]) };
+}
+
+function validateShowParent(commit: HistoryCommit, parent: number | undefined): void {
+  if (commit.parents.length > 1 && parent === undefined) throw new Error("Merge commit inspection requires an explicit 1-based parent comparison.");
+  if (parent !== undefined && parent > commit.parents.length) throw new Error("Requested commit parent does not exist.");
+}
+
+export async function getGitShow(host: GitAPI, ctx: GitCommandContext, input: GitShowInput = {}, signal?: AbortSignal, tokens: readonly string[] = []) {
+  validateShowInput(input);
+  const output = input.output ?? "summary";
+  const reader = await openGitReader(host, ctx, input.worktreePath, signal, tokens);
+  const head = await resolveReadCommit(reader, input.ref ?? "HEAD");
+  const metadata = await readGit(reader, ["log", "-z", "-1", `--format=${LOG_FORMAT}`, "--no-show-signature", "--no-notes", head, "--"]);
+  const commit = parseCommits(metadata.stdout, reader)[0];
+  if (commit?.head !== head) throw new Error("Commit metadata did not match captured identity.");
+  const message = boundedGitText((await readGit(reader, ["log", "-1", "--format=%B", "--no-show-signature", "--no-notes", head, "--"])).stdout, tokens, 4096, 100);
+  commit.message = message.text;
+  commit.messageTruncated = message.truncated;
+  if (output === "file") return showFile(reader, commit, input.path!);
+  validateShowParent(commit, input.parent);
+  const base = commit.parents[(input.parent ?? 1) - 1] ?? null;
+  let comparison;
+  if (base) {
+    const diff = await getGitDiff(host, reader.ctx, { mode: "range", baseRef: base, targetRef: head, output: output === "patch" ? "patch" : "name-status", ...(input.path ? { paths: [input.path] } : {}) }, signal, tokens);
+    comparison = { text: diff.diff, truncated: diff.truncated };
+  } else {
+    const diff = await readGit(reader, ["--literal-pathspecs", "-c", "diff.noprefix=false", "diff-tree", "--no-relative", "--src-prefix=a/", "--dst-prefix=b/", "--root", "--no-commit-id", "-r", "--no-ext-diff", "--no-textconv", "--no-color", "--no-renames", "--ignore-submodules=dirty", output === "patch" ? "--patch" : "--name-status", head, "--", ...(input.path ? [input.path] : [])]);
+    comparison = boundedGitText(diff.stdout, tokens);
+  }
+  return { action: "git_show", commit, output, comparisonBase: base, ...comparison };
+}

package/src/git-index.ts

@@ -0,0 +1,119 @@
+import { lstat } from "node:fs/promises";
+import { getGitOperationState, runGit, withRepositoryMutationQueue, type GitCommandContext } from "./git.ts";
+import { checkedFilePath, fileExpectation, getGitStatus } from "./git-status.ts";
+import { fingerprint, OBJECT_ID, openGitReader, readGit, safeGitText, validateKeys, validateReadPaths, type GitAPI, type GitReader } from "./git-read.ts";
+
+export interface IndexInput { paths: string[]; expectedHead: string | null; expectedIndex: string; worktreePath?: string }
+export interface IndexRecord { flag: string; mode: string; oid: string; path: string }
+export async function inspectIndex(reader: GitReader): Promise<{ raw: string; index: string; entries: IndexRecord[] }> {
+  const raw = (await readGit(reader, ["ls-files", "--stage", "-v", "-z"])).stdout;
+  if (raw && !raw.endsWith("\0")) throw new Error("Incomplete index inspection.");
+  const entries = [];
+  for (const record of raw ? raw.slice(0, -1).split("\0") : []) {
+    const match = /^([A-Za-z]) ([0-7]{6}) ([a-f0-9]{40}|[a-f0-9]{64}) ([0-3])\t([^\0]+)$/u.exec(record);
+    if (match?.[4] !== "0") throw new Error("Unmerged or unsupported index; use git_conflicts/conclude_merge for conflicts.");
+    if (match[1] !== "H" || !["100644", "100755", "120000"].includes(match[2])) throw new Error("Index contains assume-unchanged, skip-worktree, gitlink, or unsupported entries; no mutation performed.");
+    entries.push({ flag: match[1], mode: match[2], oid: match[3], path: match[5] });
+  }
+  return { raw, index: fingerprint(raw), entries };
+}
+export async function requireSimpleIndex(reader: GitReader): Promise<void> {
+  for (const key of ["GIT_INDEX_FILE", "GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_OBJECT_DIRECTORY"]) if (process.env[key] !== undefined) throw new Error("Git path environment overrides must be unset for guarded file/index mutations.");
+  if ((await getGitOperationState(reader.pi, reader.ctx, reader.signal)).active.length) throw new Error("An in-progress Git operation must be completed or aborted first.");
+  const visible = await readGit(reader, ["diff", "--cached", "--raw", "-z", "--no-ext-diff", "--no-textconv", "--no-renames", "--ita-visible-in-index"]);
+  const invisible = await readGit(reader, ["diff", "--cached", "--raw", "-z", "--no-ext-diff", "--no-textconv", "--no-renames", "--ita-invisible-in-index"]);
+  if (visible.stdout !== invisible.stdout) throw new Error("Intent-to-add entries are unsupported for guarded file/index mutations.");
+  const split = await readGit(reader, ["rev-parse", "--shared-index-path"]);
+  if (split.stdout.trim()) throw new Error("Split indexes are unsupported for guarded file/index mutations.");
+  const configs = await Promise.all(["core.sparsecheckout", "index.sparse"].map(readSparseConfig.bind(undefined, reader)));
+  for (const config of configs) {
+    if (config.code !== 0 && config.code !== 1) throw new Error("Cannot verify sparse-index configuration.");
+    if (config.code === 0 && config.stdout.trim() !== "false") throw new Error("Sparse checkouts/indexes are unsupported for guarded file/index mutations.");
+  }
+}
+function readSparseConfig(reader: GitReader, name: string) { return readGit(reader, ["config", "--bool", "--get", name], true); }
+export function validateIndexInput(input: IndexInput, extraKeys: string[] = []): void {
+  validateKeys(input, ["paths", "expectedHead", "expectedIndex", "worktreePath", ...extraKeys]);
+  validateReadPaths(input.paths);
+  if (!input.paths?.length || input.paths.some((path) => path.length > 512 || path.split("/").some((part) => !part || part === ".")) || input.paths.reduce((bytes, path) => bytes + Buffer.byteLength(path), 0) > 8192 || new Set(input.paths).size !== input.paths.length) throw new TypeError("Require distinct exact file paths, at most 512 characters each / 8 KiB combined; split larger batches. Directories and normalized aliases are unsupported.");
+  if ((input.expectedHead !== null && (typeof input.expectedHead !== "string" || !OBJECT_ID.test(input.expectedHead))) || typeof input.expectedIndex !== "string" || !/^[a-f0-9]{64}$/u.test(input.expectedIndex)) throw new TypeError("Require expectedHead (or null before the first commit) and expectedIndex from git_status.");
+}
+export async function captureSelectedFiles(reader: GitReader, paths: string[]): Promise<Map<string, string>> {
+  return new Map(await Promise.all(paths.map(captureSelectedFile.bind(undefined, reader))));
+}
+async function captureSelectedFile(reader: GitReader, path: string): Promise<[string, string]> {
+  const file = await checkedFilePath(reader.ctx.cwd, path);
+  if (!file || safeGitText(path, reader.tokens) !== path) throw new Error("A selected path is not a reusable repository-local identity.");
+  try {
+    const info = await lstat(file);
+    if (!info.isFile() && !info.isSymbolicLink()) throw new Error("Selected paths must be exact regular files or symlinks, not directories/gitlinks.");
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  const expectation = await fileExpectation(reader.ctx.cwd, path, reader.signal);
+  if (!expectation.fingerprint) throw new Error("A selected file has no safe content expectation (oversized or unsupported).");
+  return [path, expectation.fingerprint];
+}
+export async function requireExpectedState(reader: GitReader, input: IndexInput, checkRenameSides = true) {
+  const status = await getGitStatus(reader.pi, reader.ctx, { paths: input.paths }, reader.signal, reader.tokens);
+  if (status.head !== input.expectedHead || status.index !== input.expectedIndex) throw new Error("HEAD/index changed; inspect git_status and use fresh expectations.");
+  for (const entry of status.entries) if (checkRenameSides && entry.originalPath && (input.paths.includes(entry.path) || input.paths.includes(entry.originalPath)) && (!input.paths.includes(entry.path) || !input.paths.includes(entry.originalPath))) throw new Error("Both sides of a selected rename must be explicitly approved.");
+  return status;
+}
+function unrelated(entries: IndexRecord[], paths: string[]): string { return JSON.stringify(entries.filter((entry) => !paths.includes(entry.path))); }
+async function mutateIndexInside(host: GitAPI, reader: GitReader, input: IndexInput, action: "stage_changes" | "unstage_changes") {
+  await requireSimpleIndex(reader);
+  const before = await inspectIndex(reader);
+  const statusBefore = await requireExpectedState(reader, input);
+  const files = await captureSelectedFiles(reader, input.paths);
+  await Promise.all(input.paths.map(validateSelectedIndexPath.bind(undefined, reader, input, action, before.entries, statusBefore, files)));
+  await requireExpectedState(reader, input);
+  if (JSON.stringify([...files]) !== JSON.stringify([...await captureSelectedFiles(reader, input.paths)])) throw new Error("Selected files changed during preparation; inspect git_status again.");
+  const stagePaths = input.paths.filter((path) => files.get(path) !== fingerprint("missing") || before.entries.some((entry) => entry.path === path));
+  const args = indexMutationArgs(input, action, stagePaths);
+  reader.signal?.throwIfAborted();
+  try {
+    if (action !== "stage_changes" || stagePaths.length) await runGit(host, reader.ctx, ["--no-lazy-fetch", "--literal-pathspecs", "-c", "core.fsmonitor=false", ...args], { signal: reader.signal, tokens: reader.tokens });
+    const final = { ...reader, signal: undefined };
+    const after = await inspectIndex(final);
+    const status = await getGitStatus(host, reader.ctx, {}, undefined, reader.tokens);
+    if (status.head !== input.expectedHead || status.branch !== statusBefore.branch || status.operations.length || unrelated(before.entries, input.paths) !== unrelated(after.entries, input.paths) || JSON.stringify([...files]) !== JSON.stringify([...await captureSelectedFiles(final, input.paths)])) throw new Error("Unrelated index entries, HEAD, or working-file bytes changed.");
+    await verifySelectedIndex(final, input, action, files, after.entries);
+    return { action, paths: input.paths, head: status.head, index: after.index, committed: false, workingFilesPreserved: true };
+  } catch (error) { throw new Error(`${action} outcome requires inspection with git_status; index may have changed. No rollback attempted. ${safeGitText(String(error), reader.tokens).slice(0, 2000)}`); }
+}
+function indexMutationArgs(input: IndexInput, action: string, stagePaths: string[]): string[] {
+  if (action === "stage_changes") return ["add", "--", ...stagePaths];
+  if (input.expectedHead === null) return ["update-index", "--force-remove", "--", ...input.paths];
+  return ["restore", "--staged", `--source=${input.expectedHead}`, "--", ...input.paths];
+}
+async function validateSelectedIndexPath(reader: GitReader, input: IndexInput, action: string, entries: IndexRecord[], statusBefore: Awaited<ReturnType<typeof requireExpectedState>>, files: Map<string, string>, path: string) {
+  const tracked = entries.some((entry) => entry.path === path);
+  const atHead = input.expectedHead === null ? "" : (await readGit(reader, ["--literal-pathspecs", "ls-tree", "-z", input.expectedHead, "--", path])).stdout;
+  if (atHead && !atHead.endsWith(`\t${path}\0`)) throw new Error("Selected path does not exactly match its tracked identity.");
+  if (!tracked && !atHead) {
+    if (action === "unstage_changes") throw new Error("Selected path is not staged or tracked at HEAD.");
+    if (!statusBefore.entries.some((entry) => entry.kind === "untracked" && entry.path === path && entry.reusablePath)) throw new Error("Selected addition is ignored or not an exact reusable untracked path; aliases and implicit expansion are refused.");
+    const ignored = await readGit(reader, ["check-ignore", "--quiet", "--", path], true);
+    if (ignored.code !== 1) throw new Error("Selected addition is ignored or could not be verified; force-add is unsupported.");
+    if (files.get(path) === fingerprint("missing")) throw new Error("Selected path is missing and untracked.");
+  }
+}
+async function verifySelectedIndex(final: GitReader, input: IndexInput, action: string, files: Map<string, string>, entries: IndexRecord[]) {
+  if (action === "stage_changes") {
+    const unstaged = await readGit(final, ["--literal-pathspecs", "diff", "--no-ext-diff", "--no-textconv", "--quiet", "--ignore-submodules=all", "--", ...input.paths], true);
+    if (unstaged.code !== 0) throw new Error("Selected content is not fully staged.");
+    for (const path of input.paths) if (files.get(path) !== fingerprint("missing") && !entries.some((entry) => entry.path === path)) throw new Error("Selected file was not added to the index.");
+  } else {
+    await Promise.all(input.paths.map(verifyUnstagedPath.bind(undefined, final, input, entries)));
+  }
+}
+async function verifyUnstagedPath(final: GitReader, input: IndexInput, entries: IndexRecord[], path: string) {
+  const entry = entries.find((candidate) => candidate.path === path);
+  const atHead = input.expectedHead === null ? "" : (await readGit(final, ["--literal-pathspecs", "ls-tree", "-z", input.expectedHead, "--", path])).stdout;
+  if (!atHead && entry) throw new Error("Selected addition remained staged.");
+  if (atHead && (!entry || !atHead.startsWith(`${entry.mode} blob ${entry.oid}\t`))) throw new Error("Selected index entry does not match captured HEAD.");
+}
+export async function changeIndex(host: GitAPI, ctx: GitCommandContext, input: IndexInput, action: "stage_changes" | "unstage_changes", signal?: AbortSignal, tokens: readonly string[] = []) {
+  validateIndexInput(input);
+  const reader = await openGitReader(host, ctx, input.worktreePath, signal, tokens);
+  return withRepositoryMutationQueue(reader.ctx.cwd, mutateIndexInside.bind(undefined, host, reader, input, action));
+}

package/src/git-read.ts

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import { isAbsolute, win32 } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getCanonicalGitWorktreeRoot, resolveRepositoryWorktreeCwd, runGit, type GitCommandContext } from "./git.ts";
+import { redactSecrets } from "./redaction.ts";
+
+export type GitAPI = Pick<ExtensionAPI, "exec">;
+export interface GitReader { pi: GitAPI; ctx: GitCommandContext; signal?: AbortSignal; tokens: readonly string[] }
+export const OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
+export const READ_RAW_BYTES = 4 * 1024 * 1024;
+export const READ_PAGE_SIZE = 25;
+export const READ_CURSOR_CHARS = 1024;
+
+export function errorText(error: unknown): string { return error instanceof Error ? error.message : String(error); }
+export function fingerprint(value: string | Buffer): string { return createHash("sha256").update(value).digest("hex"); }
+function escapeControl(character: string): string { return character === "\n" || character === "\t" ? character : String.raw`\u${character.codePointAt(0)!.toString(16).padStart(4, "0")}`; }
+export function safeGitText(text: string, tokens: readonly string[] = []): string {
+  return redactSecrets(text, tokens).replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, escapeControl);
+}
+export function boundedGitText(raw: string, tokens: readonly string[] = [], maxBytes = 32 * 1024, maxLines = 1000): { text: string; truncated: boolean } {
+  const text = safeGitText(raw, tokens);
+  let result = "";
+  let bytes = 0;
+  let lines = 0;
+  for (const character of text) {
+    const size = Buffer.byteLength(character);
+    if (bytes + size > maxBytes || lines >= maxLines) break;
+    result += character;
+    bytes += size;
+    if (character === "\n") lines++;
+  }
+  return { text: result, truncated: result.length !== text.length };
+}
+export function validateReadRef(value: unknown): asserts value is string {
+  if (typeof value !== "string" || !value || value.length > 512 || value.startsWith("-") || /[\s:\p{Cc}\p{Cf}]/u.test(value) || value.includes("..")) throw new TypeError("Expected a bounded single local commit revision, not a range, option, or path.");
+}
+export function validateReadPath(value: unknown): asserts value is string {
+  if (typeof value !== "string" || !value.trim() || value.length > 4096 || isAbsolute(value) || win32.isAbsolute(value) || /[\\\p{Cc}\p{Cf}\ufffd]/u.test(value) || value.split("/").some(unsafeSegment)) throw new TypeError("Expected a literal root-relative path without traversal, .git, backslashes, or controls.");
+}
+function unsafeSegment(part: string): boolean { return part === ".." || part.toLowerCase() === ".git"; }
+export function validateReadPaths(paths: unknown): asserts paths is string[] | undefined {
+  if (paths === undefined) return;
+  if (!Array.isArray(paths) || !paths.length || paths.length > 25) throw new TypeError("paths must contain 1–25 literal paths.");
+  for (const path of paths) validateReadPath(path);
+}
+export function validateKeys(input: unknown, keys: string[]): void {
+  if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some((key) => !keys.includes(key))) throw new TypeError("Only documented input fields are accepted.");
+}
+async function execRead(host: GitAPI, tokens: readonly string[], command: string, args: string[], options: Parameters<GitAPI["exec"]>[2]) {
+  let result;
+  try { result = await host.exec(command, ["--no-optional-locks", "--no-lazy-fetch", "--no-pager", "-c", "core.fsmonitor=false", ...args], options); }
+  catch (error) {
+    if (options?.signal?.aborted) throw error;
+    throw new Error(boundedGitText(String(error), tokens, 4000).text);
+  }
+  if (result.killed) throw new Error("Local Git inspection was killed or timed out; retry once, then report the failure.");
+  if (result.code !== 0) {
+    if (/unknown option[^\n]*no-lazy-fetch/iu.test(result.stderr)) throw new Error("Git with --no-lazy-fetch support is required; update Git rather than weakening read-only safeguards.");
+    return { ...result, stdout: boundedGitText(result.stdout, tokens, 4000).text, stderr: boundedGitText(result.stderr, tokens, 4000).text };
+  }
+  if (Buffer.byteLength(result.stdout) > READ_RAW_BYTES) throw new Error("Local Git inspection exceeded the 4 MiB safety limit. Narrow the query; no completeness claim is possible.");
+  return result;
+}
+export async function openGitReader(host: GitAPI, ctx: GitCommandContext, worktreePath?: string, signal?: AbortSignal, tokens: readonly string[] = []): Promise<GitReader> {
+  signal?.throwIfAborted();
+  if (worktreePath !== undefined && (typeof worktreePath !== "string" || !isAbsolute(worktreePath) || worktreePath.length > 4096 || /[\p{Cc}\p{Cf}]/u.test(worktreePath))) throw new TypeError("worktreePath must be a bounded absolute worktree root.");
+  const pi = { exec: execRead.bind(undefined, host, tokens) };
+  const cwd = worktreePath === undefined ? ctx.cwd : await resolveRepositoryWorktreeCwd(pi, ctx, worktreePath, signal);
+  return { pi, ctx: { cwd: await getCanonicalGitWorktreeRoot(pi, { cwd }, signal) }, signal, tokens };
+}
+export async function readGit(reader: GitReader, args: string[], allowFailure = false) {
+  reader.signal?.throwIfAborted();
+  return runGit(reader.pi, reader.ctx, args, { signal: reader.signal, tokens: reader.tokens, allowFailure });
+}
+export async function resolveReadCommit(reader: GitReader, ref: string): Promise<string> {
+  validateReadRef(ref);
+  const result = await readGit(reader, ["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`], true);
+  if (result.code !== 0 || !OBJECT_ID.test(result.stdout.trim())) throw new Error("Commit revision is not locally available. Inspect git_log/list_branches; fetch separately only when intended.");
+  return result.stdout.trim();
+}
+export function encodeReadCursor(fields: unknown[]): string { return Buffer.from(JSON.stringify(fields)).toString("base64url"); }
+export function decodeReadCursor(value: unknown): unknown[] {
+  if (typeof value !== "string" || !value || value.length > READ_CURSOR_CHARS || !/^[A-Za-z0-9_-]+$/u.test(value)) throw new TypeError("Invalid continuation; use the unchanged next cursor.");
+  try {
+    const fields: unknown = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+    if (!Array.isArray(fields) || encodeReadCursor(fields) !== value) throw new Error("Noncanonical continuation fields.");
+    return fields;
+  } catch { throw new TypeError("Invalid continuation; restart without after."); }
+}
+export async function readBlob(reader: GitReader, oid: string): Promise<{ size: number; binary: boolean; text: string; truncated: boolean }> {
+  if (!OBJECT_ID.test(oid)) throw new Error("Invalid blob identity.");
+  const result = await readGit(reader, ["cat-file", "-s", oid]);
+  if (!/^\d+\n?$/u.test(result.stdout)) throw new Error("Invalid blob size.");
+  const size = Number(result.stdout.trim());
+  if (!Number.isSafeInteger(size)) throw new Error("Invalid blob size.");
+  if (size > READ_RAW_BYTES) return { size, binary: false, text: "Object too large for a safe preview.", truncated: true };
+  const blob = await readGit(reader, ["cat-file", "blob", oid]);
+  const binary = blob.stdout.includes("\0") || blob.stdout.includes("\ufffd");
+  return { size, binary, ...(binary ? { text: "Binary or non-UTF-8 object; content omitted.", truncated: false } : boundedGitText(blob.stdout, reader.tokens)) };
+}

package/src/git-rebase.ts

@@ -0,0 +1,42 @@
+import { getCurrentBranch, getGitOperationState, getLocalBranchCommit, isCommitAncestor, requireCurrentBranch, resolveWorktreeBaseCommit, runGit, withRepositoryMutationQueue, type GitCommandContext } from "./git.ts";
+import { getGitStatus } from "./git-status.ts";
+import { boundedGitText, errorText, openGitReader, readGit, safeGitText, validateReadRef, type GitAPI, type GitReader } from "./git-read.ts";
+
+async function otherRefs(reader: GitReader, branch: string): Promise<string> {
+  const raw = (await readGit(reader, ["for-each-ref", "--format=%(refname) %(objectname)"])).stdout;
+  return raw.split("\n").filter((line) => !line.startsWith(`refs/heads/${branch} `)).join("\n");
+}
+async function rebaseInside(host: GitAPI, reader: GitReader, baseRef: string) {
+  const branch = await requireCurrentBranch(reader.pi, reader.ctx, reader.signal);
+  if (safeGitText(branch, reader.tokens) !== branch) throw new Error("Current branch is not a reusable identity.");
+  const source = await getLocalBranchCommit(reader.pi, reader.ctx, branch, reader.signal);
+  const status = await getGitStatus(reader.pi, reader.ctx, {}, reader.signal, reader.tokens);
+  if (status.hasChanges || status.operations.length) throw new Error("Explicit-base rebase requires a clean idle checkout.");
+  // Rebase has no no-overwrite-ignore switch. Refuse local-only residue rather than
+  // silently allowing Git's intermediate checkouts to overwrite ignored files.
+  if ((await readGit(reader, ["ls-files", "--others", "--ignored", "--exclude-standard", "-z"])).stdout) throw new Error("Explicit-base rebase refuses ignored local-only files; preserve them outside the checkout first.");
+  const base = await resolveWorktreeBaseCommit(reader.pi, reader.ctx, baseRef, reader.signal);
+  const refs = await otherRefs(reader, branch);
+  const config = (await readGit(reader, ["config", "--null", "--list"])).stdout;
+  reader.signal?.throwIfAborted();
+  let failure: unknown;
+  try {
+    await runGit(host, reader.ctx, ["rebase", "--no-autostash", "--no-update-refs", "--no-autosquash", "--no-rebase-merges", base], { signal: reader.signal, timeout: 120000, tokens: reader.tokens });
+  } catch (error) { failure = error; }
+  const final = { ...reader, signal: undefined };
+  if (failure) {
+    try {
+      const operation = await getGitOperationState(final.pi, final.ctx);
+      if (operation.active.includes("rebase")) await runGit(host, reader.ctx, ["rebase", "--abort"], { timeout: 30000, tokens: reader.tokens });
+      if ((await getCurrentBranch(final.pi, final.ctx)).currentBranch !== branch || await getLocalBranchCommit(final.pi, final.ctx, branch) !== source || (await getGitStatus(final.pi, final.ctx)).hasChanges || (await getGitOperationState(final.pi, final.ctx)).active.length || await otherRefs(final, branch) !== refs || (await readGit(final, ["config", "--null", "--list"])).stdout !== config) throw new Error("Restoration could not be verified.");
+    } catch { throw new Error("Explicit-base rebase recovery is uncertain. Stop mutations and inspect git_status; a person must resolve any remaining rebase state."); }
+    throw new Error(`Rebase failed; restoration was verified. ${boundedGitText(errorText(failure), reader.tokens, 2000).text}`);
+  }
+  if ((await getCurrentBranch(final.pi, final.ctx)).currentBranch !== branch || !(await isCommitAncestor(final.pi, final.ctx, base, await getLocalBranchCommit(final.pi, final.ctx, branch))) || (await getGitOperationState(final.pi, final.ctx)).active.length || await otherRefs(final, branch) !== refs || (await readGit(final, ["config", "--null", "--list"])).stdout !== config) throw new Error("Rebase postconditions are uncertain; inspect git_status before another mutation.");
+  return { action: "rebase_branch", currentBranch: branch, upstream: safeGitText(baseRef, reader.tokens), base, previousHead: source, head: await getLocalBranchCommit(final.pi, final.ctx, branch), publicationWarning: "History was rewritten locally; force-push remains unsupported. Prefer update_from_base for published feature updates." };
+}
+export async function rebaseOntoBase(host: GitAPI, ctx: GitCommandContext, baseRef: string, signal?: AbortSignal, tokens: readonly string[] = []) {
+  validateReadRef(baseRef);
+  const reader = await openGitReader(host, ctx, undefined, signal, tokens);
+  return withRepositoryMutationQueue(reader.ctx.cwd, rebaseInside.bind(undefined, host, reader, baseRef));
+}

package/src/git-remotes.ts

@@ -0,0 +1,129 @@
+import { lstat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { getCanonicalCommonGitDirectory, inspectDirectLocalBranchRef, inspectDirectRemoteTrackingRef, runGit, validateBranchName, withRepositoryMutationQueue } from "./git.ts";
+import { boundedGitText, fingerprint, openGitReader, readGit, safeGitText, validateKeys, type GitAPI, type GitReader } from "./git-read.ts";
+import type { GitCommandContext } from "./git.ts";
+
+interface ConfigEntry { scope: string; origin: string; key: string; value: string }
+async function configuration(reader: GitReader): Promise<ConfigEntry[]> {
+  const raw = (await readGit(reader, ["config", "--null", "--show-scope", "--show-origin", "--list"])).stdout;
+  const fields = raw ? raw.slice(0, -1).split("\0") : [];
+  if ((raw && !raw.endsWith("\0")) || fields.length % 3) throw new Error("Malformed Git configuration inspection.");
+  const entries = [];
+  for (let i = 0; i < fields.length; i += 3) {
+    const separator = fields[i + 2].indexOf("\n");
+    if (separator < 0) throw new Error("Malformed Git configuration entry.");
+    entries.push({ scope: fields[i], origin: fields[i + 1], key: fields[i + 2].slice(0, separator), value: fields[i + 2].slice(separator + 1) });
+  }
+  return entries;
+}
+function configIdentity(entries: ConfigEntry[]): string { return fingerprint(JSON.stringify(entries)); }
+function remoteNames(entries: ConfigEntry[]): string[] {
+  return [...new Set(entries.map(remoteName).filter((name): name is string => name !== undefined))].sort((a, b) => a.localeCompare(b));
+}
+function remoteName(entry: ConfigEntry): string | undefined { return /^remote\.(.+)\.[^.]+$/u.exec(entry.key)?.[1]; }
+function values(entries: ConfigEntry[], key: string): string[] { return entries.filter((entry) => entry.key === key).map((entry) => entry.value); }
+function safeName(name: unknown): asserts name is string {
+  if (typeof name !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._/-]{0,127}$/u.test(name) || name === "." || name.includes("..") || name.endsWith("/") || name.includes("//")) throw new TypeError("Expected a safe configured remote name, not a URL or option.");
+}
+function safeDestination(value: unknown): asserts value is string {
+  if (typeof value !== "string" || value.length > 2048 || /[\s\p{Cc}\p{Cf}]/u.test(value) || safeGitText(value) !== value) throw new TypeError("Remote destination must be credential-free HTTPS or SSH.");
+  if (/^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+:[a-zA-Z0-9_./-]+$/u.test(value)) return;
+  let url: URL;
+  try { url = new URL(value); } catch { throw new TypeError("Remote destination must be an explicit HTTPS or SSH URL."); }
+  if (!["https:", "ssh:"].includes(url.protocol) || !url.hostname || !url.pathname || url.pathname === "/" || url.password || url.search || url.hash || (url.protocol === "https:" && url.username) || (url.username && !/^[a-zA-Z0-9._-]+$/u.test(url.username))) throw new TypeError("Unsupported remote transport or embedded credentials.");
+}
+export async function listRemotes(host: GitAPI, ctx: GitCommandContext, signal?: AbortSignal, tokens: readonly string[] = []) {
+  const reader = await openGitReader(host, ctx, undefined, signal, tokens);
+  const entries = await configuration(reader);
+  const names = remoteNames(entries);
+  if (names.length > 100) throw new Error("Remote inventory exceeds the 100-remote safety limit.");
+  const remotes = await Promise.all(names.slice(0, 25).map(inspectRemote.bind(undefined, reader, entries, tokens)));
+  return { action: "list_remotes", configuration: configIdentity(entries), remotes, omitted: Math.max(0, names.length - 25), complete: names.length <= 25 };
+}
+async function inspectRemote(reader: GitReader, entries: ConfigEntry[], tokens: readonly string[], name: string) {
+  const configured = values(entries, `remote.${name}.url`);
+  const push = values(entries, `remote.${name}.pushurl`);
+  let validName = true;
+  try { safeName(name); } catch { validName = false; }
+  let supported = validName && configured.length === 1 && push.length <= 1;
+  try { for (const url of [...configured, ...push]) safeDestination(url); } catch { supported = false; }
+  const effectiveFetch = validName ? await readGit(reader, ["remote", "get-url", "--all", "--", name], true) : { stdout: "Unsupported remote name." };
+  const effectivePush = validName ? await readGit(reader, ["remote", "get-url", "--push", "--all", "--", name], true) : { stdout: "Unsupported remote name." };
+  return { name: boundedGitText(name, tokens, 128, 1).text, reusableName: validName && safeGitText(name, tokens) === name && name.length <= 128, supported, configuredFetch: configured.slice(0, 2).map((url) => boundedGitText(url, tokens, 128, 1).text), configuredPush: push.slice(0, 2).map((url) => boundedGitText(url, tokens, 128, 1).text), omittedUrls: Math.max(0, configured.length - 2) + Math.max(0, push.length - 2), effectiveFetch: boundedGitText(effectiveFetch.stdout, tokens, 256, 2).text, effectivePush: boundedGitText(effectivePush.stdout, tokens, 256, 2).text };
+}
+async function requireWritableConfiguration(reader: GitReader, entries: ConfigEntry[], expected: string): Promise<string> {
+  for (const key of ["GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_CONFIG"]) if (process.env[key] !== undefined) throw new Error("Git path/config environment overrides must be unset for guarded repository configuration writes.");
+  if (!/^[a-f0-9]{64}$/u.test(expected) || configIdentity(entries) !== expected) throw new Error("Configuration changed; call list_remotes again and use its configuration fingerprint.");
+  if (entries.some((entry) => entry.key === "extensions.worktreeconfig" && entry.value !== "false")) throw new Error("Configuration mutations do not support worktree-specific config.");
+  const common = await getCanonicalCommonGitDirectory(reader.pi, reader.ctx, reader.signal);
+  const path = join(common, "config");
+  const info = await lstat(path);
+  if (!info.isFile() || info.isSymbolicLink()) throw new Error("Repository config must be a regular non-symlink file.");
+  return `file:${path}`;
+}
+export interface AddRemoteInput { name: string; url: string; expectedConfig: string }
+export async function addRemote(host: GitAPI, ctx: GitCommandContext, input: AddRemoteInput, signal?: AbortSignal, tokens: readonly string[] = []) {
+  validateKeys(input, ["name", "url", "expectedConfig"]); safeName(input.name); safeDestination(input.url);
+  if (safeGitText(input.name, tokens) !== input.name) throw new Error("Remote name is not a reusable safe identity.");
+  if (safeGitText(input.url, tokens) !== input.url) throw new Error("Credentials must not be stored in remote URLs.");
+  const reader = await openGitReader(host, ctx, undefined, signal, tokens);
+  const common = await getCanonicalCommonGitDirectory(reader.pi, reader.ctx, signal);
+  return withRepositoryMutationQueue(common, addRemoteInside.bind(undefined, host, reader, input));
+}
+async function addRemoteInside(host: GitAPI, reader: GitReader, input: AddRemoteInput) {
+  const { signal, tokens } = reader;
+  const before = await configuration(reader);
+  await requireWritableConfiguration(reader, before, input.expectedConfig);
+  if (before.some((entry) => entry.key.startsWith("url."))) throw new Error("URL rewriting configuration is unsupported for add_remote; no configuration changed.");
+  const names = remoteNames(before);
+  if (names.some((name) => name.toLowerCase() === input.name.toLowerCase() || name.toLowerCase().startsWith(`${input.name.toLowerCase()}/`) || input.name.toLowerCase().startsWith(`${name.toLowerCase()}/`))) throw new Error("Remote exists or overlaps another remote namespace.");
+  if (configIdentity(await configuration(reader)) !== input.expectedConfig) throw new Error("Configuration changed during preparation; retry list_remotes.");
+  try {
+    await runGit(host, reader.ctx, ["remote", "add", "--", input.name, input.url], { signal, tokens });
+    const after = await configuration({ ...reader, signal: undefined });
+    const unrelated = after.filter((entry) => !entry.key.startsWith(`remote.${input.name}.`));
+    if (JSON.stringify(unrelated) !== JSON.stringify(before) || values(after, `remote.${input.name}.url`).join() !== input.url || values(after, `remote.${input.name}.fetch`).join() !== `+refs/heads/*:refs/remotes/${input.name}/*`) throw new Error("Remote configuration did not match the requested state.");
+    return { action: "add_remote", name: input.name, configuration: configIdentity(after), fetched: false };
+  } catch (error) { throw new Error(`Remote setup outcome requires inspection with list_remotes; no rollback attempted. ${boundedGitText(String(error), tokens, 2000).text}`); }
+}
+export interface SetUpstreamInput { branchName: string; upstream?: string; unset?: boolean; expectedConfig: string }
+export async function setUpstream(host: GitAPI, ctx: GitCommandContext, input: SetUpstreamInput, signal?: AbortSignal, tokens: readonly string[] = []) {
+  validateKeys(input, ["branchName", "upstream", "unset", "expectedConfig"]);
+  if ((input.upstream === undefined) === (input.unset !== true) || (input.unset !== undefined && input.unset !== true)) throw new TypeError("Supply exactly upstream or unset: true.");
+  const reader = await openGitReader(host, ctx, undefined, signal, tokens);
+  const common = await getCanonicalCommonGitDirectory(reader.pi, reader.ctx, signal);
+  return withRepositoryMutationQueue(common, setUpstreamInside.bind(undefined, host, reader, input));
+}
+function requireSafeTrackingIdentities(input: SetUpstreamInput, tokens: readonly string[]): void {
+  if (safeGitText(input.branchName, tokens) !== input.branchName || (input.upstream !== undefined && safeGitText(input.upstream, tokens) !== input.upstream)) throw new Error("Tracking identities cannot be safely reused.");
+}
+async function setUpstreamInside(host: GitAPI, reader: GitReader, input: SetUpstreamInput) {
+  const { signal, tokens } = reader;
+  await validateBranchName(reader.pi, reader.ctx, input.branchName, signal);
+  requireSafeTrackingIdentities(input, tokens);
+  if ((await inspectDirectLocalBranchRef(reader.pi, reader.ctx, input.branchName, signal)).status !== "present") throw new Error("Local branch does not exist.");
+  const before = await configuration(reader);
+  const origin = await requireWritableConfiguration(reader, before, input.expectedConfig);
+  const keys = [`branch.${input.branchName}.remote`, `branch.${input.branchName}.merge`];
+  const owned = before.filter((entry) => keys.includes(entry.key));
+  if (owned.some((entry) => entry.scope !== "local" || !entry.origin.startsWith("file:") || resolve(reader.ctx.cwd, entry.origin.slice(5)) !== origin.slice(5)) || keys.some((key) => values(before, key).length > 1)) throw new Error("Upstream settings are inherited, included, or ambiguous; no configuration changed.");
+  let remote: string | undefined;
+  let merge: string | undefined;
+  if (input.upstream !== undefined) {
+    await validateBranchName(reader.pi, reader.ctx, input.upstream, signal);
+    const candidates = remoteNames(before).filter((name) => input.upstream!.startsWith(`${name}/`));
+    if (candidates.length !== 1) throw new Error("Upstream must name one existing configured remote-tracking branch.");
+    remote = candidates[0]; safeName(remote);
+    merge = `refs/heads/${input.upstream.slice(remote.length + 1)}`;
+    if ((await inspectDirectRemoteTrackingRef(reader.pi, reader.ctx, input.upstream, signal)).status !== "present") throw new Error("Upstream tracking ref is missing or symbolic; fetch separately first.");
+  }
+  if (configIdentity(await configuration(reader)) !== input.expectedConfig) throw new Error("Configuration changed during preparation; call list_remotes again.");
+  if (!input.upstream && !owned.length) return { action: "set_upstream", branchName: input.branchName, upstream: null, configuration: input.expectedConfig, changed: false };
+  try {
+    await runGit(host, reader.ctx, ["branch", ...(input.upstream ? [`--set-upstream-to=refs/remotes/${input.upstream}`] : ["--unset-upstream"]), "--", input.branchName], { signal, tokens });
+    const after = await configuration({ ...reader, signal: undefined });
+    if (JSON.stringify(before.filter((entry) => !keys.includes(entry.key))) !== JSON.stringify(after.filter((entry) => !keys.includes(entry.key))) || values(after, keys[0]).join() !== (remote ?? "") || values(after, keys[1]).join() !== (merge ?? "")) throw new Error("Upstream postconditions were not verified.");
+    return { action: "set_upstream", branchName: safeGitText(input.branchName, tokens), upstream: input.upstream ? safeGitText(input.upstream, tokens) : null, configuration: configIdentity(after), changed: true };
+  } catch (error) { throw new Error(`Upstream outcome requires inspection with list_remotes; no rollback attempted. ${boundedGitText(String(error), tokens, 2000).text}`); }
+}

package/src/git-restore.ts

@@ -0,0 +1,53 @@
+import { captureSelectedFiles, inspectIndex, requireExpectedState, requireSimpleIndex, validateIndexInput, type IndexInput, type IndexRecord } from "./git-index.ts";
+import { OBJECT_ID, openGitReader, readGit, resolveReadCommit, safeGitText, type GitAPI, type GitReader } from "./git-read.ts";
+import { getGitStatus } from "./git-status.ts";
+import { runGit, withRepositoryMutationQueue, type GitCommandContext } from "./git.ts";
+
+export interface RestoreInput extends IndexInput {
+  sourceRef?: string;
+  preview?: boolean;
+  discardChanges?: boolean;
+  expectedFiles?: { path: string; fingerprint: string }[];
+}
+async function previewRestorePath(reader: GitReader, entries: IndexRecord[], files: Map<string, string>, source: string | null, path: string) {
+  const entry = entries.find((candidate) => candidate.path === path)!;
+  const tree = source === null ? `${entry.mode} blob ${entry.oid}\t${path}\0` : (await readGit(reader, ["--literal-pathspecs", "ls-tree", "-z", source, "--", path])).stdout;
+  if (tree && (!/^(?:100644|100755|120000) blob /u.test(tree) || !tree.endsWith(`\t${path}\0`))) throw new Error("Source path is not a supported regular file or symlink.");
+  return { path, fingerprint: files.get(path)!, operation: tree ? "replace" : "delete", source: tree ? tree.slice(0, tree.indexOf("\t")) : null };
+}
+function requireRestoreApproval(input: RestoreInput, source: string | null, files: Map<string, string>): void {
+  if (input.discardChanges !== true) throw new Error("Restoration discards local edits. Require explicit discardChanges: true after inspecting the preview.");
+  if (source !== null && !OBJECT_ID.test(input.sourceRef!)) throw new Error("Apply must use the full sourceCommit from the preview, not a moving ref.");
+  if (!Array.isArray(input.expectedFiles) || input.expectedFiles.length !== input.paths.length || new Set(input.expectedFiles.map((entry) => entry.path)).size !== input.paths.length || input.expectedFiles.some((entry) => !input.paths.includes(entry.path) || !/^[a-f0-9]{64}$/u.test(entry.fingerprint) || files.get(entry.path) !== entry.fingerprint)) throw new Error("Selected working files changed or preview expectations are missing; request a fresh restore_paths preview.");
+}
+async function restoreInside(host: GitAPI, reader: GitReader, input: RestoreInput) {
+  await requireSimpleIndex(reader);
+  const before = await inspectIndex(reader);
+  const statusBefore = await requireExpectedState(reader, input, false);
+  if (input.paths.some((path) => !before.entries.some((entry) => entry.path === path))) throw new Error("restore_paths only restores index-tracked files; untracked/ignored content is protected.");
+  const files = await captureSelectedFiles(reader, input.paths);
+  const source = input.sourceRef === undefined ? null : await resolveReadCommit(reader, input.sourceRef);
+  const preview = await Promise.all(input.paths.map(previewRestorePath.bind(undefined, reader, before.entries, files, source)));
+  if (input.preview === true) return { action: "restore_paths", applied: false, head: input.expectedHead, index: input.expectedIndex, sourceCommit: source, expectedFiles: preview.map((entry) => ({ path: entry.path, fingerprint: entry.fingerprint })), preview };
+  requireRestoreApproval(input, source, files);
+  await requireExpectedState(reader, input, false);
+  if (JSON.stringify([...files]) !== JSON.stringify([...await captureSelectedFiles(reader, input.paths)])) throw new Error("Selected files changed during preparation; request a fresh preview.");
+  reader.signal?.throwIfAborted();
+  try {
+    await runGit(host, reader.ctx, ["--no-optional-locks", "--no-lazy-fetch", "--literal-pathspecs", "-c", "core.fsmonitor=false", "restore", "--worktree", "--no-overlay", ...(source ? [`--source=${source}`] : []), "--", ...input.paths], { signal: reader.signal, tokens: reader.tokens });
+    const final = { ...reader, signal: undefined };
+    const after = await inspectIndex(final);
+    const status = await getGitStatus(host, reader.ctx, {}, undefined, reader.tokens);
+    const verify = await readGit(final, ["--literal-pathspecs", "diff", "--no-ext-diff", "--no-textconv", "--quiet", "--ignore-submodules=all", ...(source ? [source] : []), "--", ...input.paths], true);
+    if (before.raw !== after.raw || status.head !== input.expectedHead || status.branch !== statusBefore.branch || status.operations.length || verify.code !== 0) throw new Error("Index/HEAD preservation or selected restoration could not be verified.");
+    return { action: "restore_paths", applied: true, head: status.head, index: after.index, sourceCommit: source, paths: preview.map((entry) => ({ path: entry.path, operation: entry.operation })), committed: false };
+  } catch (error) { throw new Error(`Restoration may have partially changed selected paths; inspect git_status. No rollback attempted. ${safeGitText(String(error), reader.tokens).slice(0, 2000)}`); }
+}
+export async function restorePaths(host: GitAPI, ctx: GitCommandContext, input: RestoreInput, signal?: AbortSignal, tokens: readonly string[] = []) {
+  validateIndexInput(input, ["sourceRef", "preview", "discardChanges", "expectedFiles"]);
+  if (input.preview !== undefined && typeof input.preview !== "boolean") throw new TypeError("preview must be boolean.");
+  if (input.discardChanges !== undefined && typeof input.discardChanges !== "boolean") throw new TypeError("discardChanges must be boolean.");
+  if (input.expectedFiles !== undefined && (!Array.isArray(input.expectedFiles) || input.expectedFiles.some((entry) => !entry || typeof entry !== "object" || Object.keys(entry).some((key) => !["path", "fingerprint"].includes(key))))) throw new TypeError("Malformed selected-file expectations.");
+  const reader = await openGitReader(host, ctx, input.worktreePath, signal, tokens);
+  return withRepositoryMutationQueue(reader.ctx.cwd, restoreInside.bind(undefined, host, reader, input));
+}