pi-jar 0.1.4 → 0.1.6

package/src/ask-tool.ts

@@ -26,13 +26,18 @@ type PickResult = { kind: "answer"; selected: string[] } | { kind: "custom" } |
 
 const fit = (line: string, width: number) => truncateToWidth(line, Math.max(0, width));
 
-async function pickQuestion(ctx: ExtensionContext, question: AskQuestion, index: number, total: number): Promise<PickResult> {
+async function pickQuestion(ctx: ExtensionContext, question: AskQuestion, index: number, total: number, signal?: AbortSignal): Promise<PickResult> {
   const options = (question.options ?? []).map((option) => ({
     label: cleanText(option.label, 120),
     description: option.description ? cleanText(option.description, 240) : undefined
   })).filter((option) => !!option.label);
-  if (!ctx.hasUI || ctx.mode !== "tui") return { kind: "cancel" };
-  return ctx.ui.custom<PickResult>((tui, theme, _keys, done) => {
+  if (!ctx.hasUI || ctx.mode !== "tui" || signal?.aborted) return { kind: "cancel" };
+  let abort: (() => void) | undefined;
+  try { return await ctx.ui.custom<PickResult>((tui, theme, _keys, complete) => {
+    const done = (result: PickResult) => { if (abort) signal?.removeEventListener("abort", abort); complete(result); };
+    abort = () => done({ kind: "cancel" });
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) queueMicrotask(abort);
     const multi = !!question.multi;
     const allowCustom = question.allowCustom !== false;
     const actions = [
@@ -131,13 +136,13 @@ async function pickQuestion(ctx: ExtensionContext, question: AskQuestion, index:
         return lines.map((line) => visibleWidth(line) <= width ? line : fit(line, width));
       }
     };
-  });
+  }); } finally { if (abort) signal?.removeEventListener("abort", abort); }
 }
 
-async function askOne(ctx: ExtensionContext, question: AskQuestion, index: number, total: number): Promise<AskAnswer> {
+export async function askOne(ctx: ExtensionContext, question: AskQuestion, index = 0, total = 1, signal?: AbortSignal): Promise<AskAnswer> {
   const id = cleanText(question.id ?? "q" + String(index + 1), 64) || "q" + String(index + 1);
-  const picked = await pickQuestion(ctx, question, index, total);
-  if (!picked || picked.kind === "cancel") return { id, cancelled: true };
+  const picked = await pickQuestion(ctx, question, index, total, signal);
+  if (signal?.aborted || !picked || picked.kind === "cancel") return { id, cancelled: true };
   if (picked.kind === "custom") {
     const text = await ctx.ui.editor("✎ Your answer · " + cleanText(question.header ?? "Question", 48), "");
     return text?.trim() ? { id, answer: text.trim() } : { id, cancelled: true };

package/src/compact-tools.ts

@@ -8,7 +8,7 @@ import {
   type ExtensionAPI,
   type ExtensionContext
 } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { Box, Container, Text } from "@earendil-works/pi-tui";
 
 type ToolResult = { content: Array<{ type: string; text?: string }>; details?: unknown };
 
@@ -67,6 +67,61 @@ function boundedLineCount(text: string, limit = SUMMARY_SCAN_CHARS): { lines: nu
 
 const expandHint = " · [ expand ] Ctrl+O";
 
+/** Streaming arguments arrive partially: a field can be missing or not yet a string. */
+const str = (value: unknown): string => typeof value === "string" ? value : "";
+
+type CardTheme = { bg(color: "toolPendingBg" | "toolErrorBg" | "toolSuccessBg", text: string): string };
+interface CardContext { state?: { compactCard?: Box }; isPartial?: boolean; isError?: boolean; lastComponent?: unknown }
+/**
+ * Pi's edit tool renders its own framing (`renderShell: "self"`) so its expanded diff can own the
+ * background. Collapsed, pi-jar draws the same padded, state-colored box Pi gives read/write, with the
+ * call line and result summary in one card; the result renderer then contributes nothing.
+ */
+function compactCard(theme: CardTheme, context: CardContext, header: Text): Box | Text {
+  if (!context.state) return header;
+  const card = context.state.compactCard ??= new Box(1, 1);
+  const color = context.isPartial !== false ? "toolPendingBg" : context.isError ? "toolErrorBg" : "toolSuccessBg";
+  card.setBgFn((text) => theme.bg(color, text));
+  card.clear();
+  card.addChild(header);
+  return card;
+}
+function intoCard(context: CardContext, line: Text): Container | Text {
+  const card = context.state?.compactCard;
+  if (!card) return line;
+  card.addChild(line);
+  const empty = context.lastComponent instanceof Container && !(context.lastComponent instanceof Box) ? context.lastComponent : new Container();
+  empty.clear();
+  return empty;
+}
+
+/** One collapsed edit result line: +/− counts from the diff, or the tool's own message. */
+function editSummary(result: ToolResult, isPartial: boolean | undefined, theme: { fg(color: string, text: string): string }): Text {
+  if (isPartial) return new Text(theme.fg("warning", "editing…"), 0, 0);
+  const details = result.details as { diff?: string } | undefined;
+  const diff = details?.diff ?? "";
+  if (!diff) {
+    const text = summarizeResult(result).sample;
+    return new Text(theme.fg(text.startsWith("Error") ? "error" : "success", compactText(text || "applied", 96)), 0, 0);
+  }
+  if (diff.length > DIFF_SCAN_CHARS) return new Text(theme.fg("muted", `large diff${expandHint}`), 0, 0);
+  let counts = diffCountCache.get(details!);
+  if (counts?.diff !== diff) {
+    counts = { diff, additions: 0, removals: 0 };
+    for (let start = 0; start < diff.length;) {
+      const end = diff.indexOf("\n", start);
+      const stop = end < 0 ? diff.length : end;
+      const first = diff[start];
+      if (first === "+" && !diff.startsWith("+++", start)) counts.additions++;
+      else if (first === "-" && !diff.startsWith("---", start)) counts.removals++;
+      start = stop + 1;
+    }
+    diffCountCache.set(details!, counts);
+  }
+  return new Text(theme.fg("success", `+${counts.additions}`) + theme.fg("dim", " / ")
+    + theme.fg("error", `-${counts.removals}`) + theme.fg("dim", expandHint), 0, 0);
+}
+
 /**
  * Whitespace-collapsed, trimmed text cut to `max` characters. Only a bounded prefix is scanned: a call
  * card re-renders on every streamed argument delta, so collapsing a whole heredoc each time was O(n²).
@@ -114,10 +169,10 @@ export function installCompactBuiltinTools(pi: ExtensionAPI): void {
     ...read,
     renderCall(args, theme, context) {
       if (context.expanded && read.renderCall) return read.renderCall(args, theme, context);
-      const range = args.offset || args.limit
+      const range = args?.offset || args?.limit
         ? theme.fg("dim", ` · ${args.offset ?? 1}${args.limit ? `+${args.limit}` : ""}`)
         : "";
-      return new Text(theme.fg("toolTitle", theme.bold("read ")) + theme.fg("accent", args.path) + range, 0, 0);
+      return new Text(theme.fg("toolTitle", theme.bold("read ")) + theme.fg("accent", str(args?.path)) + range, 0, 0);
     },
     renderResult(result, options, theme, context) {
       if (options.expanded && read.renderResult) return read.renderResult(result, options, theme, context);
@@ -135,7 +190,7 @@ export function installCompactBuiltinTools(pi: ExtensionAPI): void {
     },
     renderCall(args, theme, context) {
       if (context.expanded && bash.renderCall) return bash.renderCall(args, theme, context);
-      return new Text(theme.fg("toolTitle", theme.bold("$ ")) + theme.fg("accent", compactText(args.command, 88)), 0, 0);
+      return new Text(theme.fg("toolTitle", theme.bold("$ ")) + theme.fg("accent", compactText(str(args?.command), 88)), 0, 0);
     },
     renderResult(result, options, theme, context) {
       if (options.expanded && bash.renderResult) return bash.renderResult(result as Parameters<NonNullable<typeof bash.renderResult>>[0], options, theme, context);
@@ -156,30 +211,12 @@ export function installCompactBuiltinTools(pi: ExtensionAPI): void {
     ...edit,
     renderCall(args, theme, context) {
       if (context.expanded && edit.renderCall) return edit.renderCall(args, theme, context);
-      return new Text(theme.fg("toolTitle", theme.bold("edit ")) + theme.fg("accent", args.path), 0, 0);
+      const path = str(args?.path) || str((args as { file_path?: unknown } | undefined)?.file_path);
+      return compactCard(theme, context, new Text(theme.fg("toolTitle", theme.bold("edit ")) + theme.fg("accent", path), 0, 0));
     },
     renderResult(result, options, theme, context) {
       if (options.expanded && edit.renderResult) return edit.renderResult(result, options, theme, context);
-      if (options.isPartial) return new Text(theme.fg("warning", "editing…"), 0, 0);
-      const details = result.details as { diff?: string } | undefined;
-      const diff = details?.diff ?? "";
-      if (!diff) {
-        const summary = summarizeResult(result);
-        const text = summary.sample;
-        return new Text(theme.fg(text.startsWith("Error") ? "error" : "success", compactText(text || "applied", 96)), 0, 0);
-      }
-      if (diff.length > DIFF_SCAN_CHARS) return new Text(theme.fg("muted", `large diff${expandHint}`), 0, 0);
-      let counts = diffCountCache.get(details!);
-      if (counts?.diff !== diff) {
-        counts = { diff, additions: 0, removals: 0 };
-        for (const line of diff.split("\n")) {
-          if (line.startsWith("+") && !line.startsWith("+++")) counts.additions++;
-          else if (line.startsWith("-") && !line.startsWith("---")) counts.removals++;
-        }
-        diffCountCache.set(details!, counts);
-      }
-      return new Text(theme.fg("success", `+${counts.additions}`) + theme.fg("dim", " / ")
-        + theme.fg("error", `-${counts.removals}`) + theme.fg("dim", expandHint), 0, 0);
+      return intoCard(context, editSummary(result, options.isPartial, theme));
     }
   });
 
@@ -187,13 +224,14 @@ export function installCompactBuiltinTools(pi: ExtensionAPI): void {
     ...write,
     renderCall(args, theme, context) {
       if (context.expanded && write.renderCall) return write.renderCall(args, theme, context);
+      const content = str(args?.content);
       let count = args && typeof args === "object" ? writeCountCache.get(args as object) : undefined;
       if (!count) {
-        count = boundedLineCount(args.content);
+        count = boundedLineCount(content);
         if (args && typeof args === "object") writeCountCache.set(args as object, count);
       }
-      return new Text(theme.fg("toolTitle", theme.bold("write ")) + theme.fg("accent", args.path)
-        + theme.fg("dim", ` · ${count.lines}${count.truncated ? "+" : ""} lines`), 0, 0);
+      return new Text(theme.fg("toolTitle", theme.bold("write ")) + theme.fg("accent", str(args?.path))
+        + theme.fg("dim", ` · ${count.lines}${count.truncated ? "+" : ""} line${count.lines === 1 && !count.truncated ? "" : "s"}`), 0, 0);
     },
     renderResult(result, options, theme, context) {
       if (options.expanded && write.renderResult) return write.renderResult(result, options, theme, context);

package/src/delegate-worktree.ts

@@ -0,0 +1,360 @@
+import { execFileSync } from "node:child_process";
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  rmSync,
+  renameSync,
+  rmdirSync,
+  writeFileSync,
+  symlinkSync,
+  unlinkSync,
+  type Stats
+} from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { MAX_TRACKED_BYTES, type ChangeTracker } from "./changes.ts";
+
+/** Present only in writable delegated children. The child extension treats this as its filesystem boundary. */
+export const CHILD_WORKTREE_ENV = "PI_JAR_WORKTREE_ROOT";
+const MAX_GIT_OUTPUT = 64 * 1024 * 1024;
+
+export interface DelegateWorktree {
+  /** Git repository root in the parent workspace. */
+  repoRoot: string;
+  /** Disposable worktree root. */
+  root: string;
+  /** Child cwd matching the parent's relative cwd inside the repository. */
+  cwd: string;
+  /** Snapshot commit that exactly represents the parent workspace when delegation started. */
+  baseline: string;
+  /** Temporary directory containing the worktree. */
+  tempRoot: string;
+}
+
+const safeGitArgs = (cwd: string, args: string[]) => ["-C", cwd, "--literal-pathspecs", "-c", "core.hooksPath=/dev/null",
+  "-c", "core.fsmonitor=false", ...args];
+
+const gitText = (cwd: string, args: string[], input?: string | Buffer): string =>
+  execFileSync("git", safeGitArgs(cwd, args), {
+    encoding: "utf8",
+    ...(input === undefined ? {} : { input }),
+    maxBuffer: MAX_GIT_OUTPUT,
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+
+const gitBuffer = (cwd: string, args: string[]): Buffer =>
+  execFileSync("git", safeGitArgs(cwd, args), {
+    encoding: null,
+    maxBuffer: MAX_GIT_OUTPUT,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+
+const nulList = (value: string): string[] => value.split("\0").filter(Boolean);
+
+const inside = (root: string, candidate: string): boolean => {
+  const rel = relative(root, candidate);
+  return rel === "" || (rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute(rel));
+};
+
+/** Normalize Pi tool path spellings before applying the filesystem boundary. */
+export function normalizeWorkspacePath(cwd: string, value: string): string | null {
+  try {
+    let path = value.replace(/[\u00a0\u2000-\u200a\u202f\u205f\u3000]/g, " ");
+    if (path.startsWith("@")) path = path.slice(1);
+    if (process.platform === "win32" && !path.includes("\\") && !path.startsWith("//")) {
+      const drive = path.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+      if (drive) path = `${drive[1]!.toUpperCase()}:\\${drive[2]?.replaceAll("/", "\\") ?? ""}`;
+    }
+    // Match Pi exactly: single-slash file: spellings are literal relative filenames.
+    if (path.startsWith("file://")) path = fileURLToPath(path);
+    if (path === "~") path = homedir();
+    else if (path.startsWith("~/") || (process.platform === "win32" && path.startsWith("~\\"))) path = join(homedir(), path.slice(2));
+    else if (path.startsWith("~")) return null;
+    if (!path || path.includes("\0")) return null;
+    return resolve(cwd, path);
+  } catch { return null; }
+}
+
+const statIfPresent = (path: string): Stats | null => {
+  try { return lstatSync(path); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+};
+
+const hasGitMetadata = (root: string, path: string) =>
+  relative(root, path).split(sep).some(part => part.toLowerCase() === ".git");
+
+// Finalization disallows ancestor symlinks entirely, even aliases back into the tree.
+const safeFilePath = (root: string, rel: string): boolean => {
+  const target = resolve(root, rel);
+  if (!rel || isAbsolute(rel) || !inside(root, target) || target === root || hasGitMetadata(root, target)) return false;
+  try {
+    if (lstatSync(root).isSymbolicLink() || realpathSync(root) !== resolve(root)) return false;
+    let probe = dirname(target);
+    while (probe !== root) {
+      const stat = statIfPresent(probe);
+      if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) return false;
+      probe = dirname(probe);
+    }
+    return true;
+  } catch { return false; }
+};
+
+/** Resolve existing and dangling symlinks, and deny Git administrative paths. */
+export function workspacePathAllowed(root: string, cwd: string, value: string, readFallbacks = false): boolean {
+  if (readFallbacks) {
+    const path = normalizeWorkspacePath(cwd, value);
+    if (!path) return false;
+    // Pi read tries these alternate spellings after a missing exact path. Check every possible
+    // target, including dangling links, rather than guarding a spelling the reader won't use.
+    const nfd = path.normalize("NFD");
+    const variants = new Set([path, path.replace(/ (AM|PM)\./gi, "\u202f$1."), nfd,
+      path.replace(/'/g, "\u2019"), nfd.replace(/'/g, "\u2019")]);
+    return [...variants].every((variant) => canonicalWorkspacePathAllowed(root, variant));
+  }
+  const path = normalizeWorkspacePath(cwd, value);
+  return path !== null && canonicalWorkspacePathAllowed(root, path);
+}
+
+function canonicalWorkspacePathAllowed(root: string, lexical: string): boolean {
+  let physicalRoot: string;
+  try { physicalRoot = realpathSync(root); } catch { return false; }
+  // macOS /var -> /private/var and other trusted root aliases are equivalent.
+  if (inside(resolve(root), lexical)) lexical = resolve(physicalRoot, relative(resolve(root), lexical));
+  if (!inside(physicalRoot, lexical) || hasGitMetadata(physicalRoot, lexical)) return false;
+  try {
+    let probe = lexical;
+    while (!statIfPresent(probe)) {
+      const parent = dirname(probe);
+      if (parent === probe) return false;
+      probe = parent;
+    }
+    const physical = realpathSync(probe);
+    return inside(physicalRoot, physical) && !hasGitMetadata(physicalRoot, physical);
+  } catch { return false; }
+}
+
+const copyInto = (fromRoot: string, toRoot: string, rel: string): void => {
+  const from = resolve(fromRoot, rel);
+  const to = resolve(toRoot, rel);
+  if (!safeFilePath(fromRoot, rel) || !safeFilePath(toRoot, rel)) throw new Error("unsafe worktree path: " + rel);
+  mkdirSync(dirname(to), { recursive: true });
+  if (lstatSync(from).isSymbolicLink()) symlinkSync(readlinkSync(from), to);
+  else cpSync(from, to, { force: true, dereference: false });
+};
+
+/**
+ * Create a detached disposable worktree and commit a private baseline snapshot containing the
+ * parent's tracked modifications plus non-ignored untracked files. The parent index/branch is not
+ * touched. That baseline lets multiple children run against the exact same starting filesystem.
+ */
+export function createDelegateWorktree(cwd: string): DelegateWorktree {
+  const requested = realpathSync(cwd);
+  const repoRoot = realpathSync(gitText(requested, ["rev-parse", "--show-toplevel"]).trim());
+  if (!inside(repoRoot, requested)) throw new Error("working directory is outside the git repository");
+  const relCwd = relative(repoRoot, requested);
+  const tempRoot = realpathSync(mkdtempSync(join(tmpdir(), "pi-jar-worktree-")));
+  const root = join(tempRoot, "workspace");
+  let added = false;
+  try {
+    // Never checkout/add: they execute clean/smudge filters and alter byte baselines.
+    gitText(repoRoot, ["worktree", "add", "--no-checkout", "--detach", root, "HEAD"]);
+    added = true;
+    gitText(root, ["read-tree", "--empty"]);
+    const paths = new Set(nulList(gitText(repoRoot, ["ls-files", "--cached", "--others", "--exclude-standard", "-z"])));
+    for (const rel of paths) {
+      if (!safeFilePath(repoRoot, rel)) throw new Error("unsafe snapshot path: " + rel);
+      const source = resolve(repoRoot, rel);
+      const stat = statIfPresent(source);
+      if (!stat) continue;
+      if (!stat.isFile() && !stat.isSymbolicLink()) throw new Error("unsupported snapshot file: " + rel);
+      const bytes = stat.isSymbolicLink() ? Buffer.from(readlinkSync(source)) : readFileSync(source);
+      const oid = gitText(root, ["hash-object", "-w", "--no-filters", "--stdin"], bytes).trim();
+      const mode = stat.isSymbolicLink() ? "120000" : (stat.mode & 0o111) ? "100755" : "100644";
+      gitText(root, ["update-index", "--add", "--cacheinfo", mode, oid, rel]);
+      copyInto(repoRoot, root, rel);
+    }
+    const tree = gitText(root, ["write-tree"]).trim();
+    const baseline = gitText(root, ["-c", "user.name=pi-jar", "-c", "user.email=pi-jar@local",
+      "commit-tree", "--no-gpg-sign", tree, "-p", "HEAD", "-m", "pi-jar delegate baseline"]).trim();
+    gitText(root, ["update-ref", "HEAD", baseline]);
+    const childCwd = relCwd ? resolve(root, relCwd) : root;
+    if (!workspacePathAllowed(root, root, childCwd)) throw new Error("unsafe child working directory");
+    if (!existsSync(childCwd)) mkdirSync(childCwd, { recursive: true });
+    return { repoRoot, root, cwd: childCwd, baseline, tempRoot };
+  } catch (error) {
+    if (added) {
+      try { gitText(repoRoot, ["worktree", "remove", "--force", root]); } catch { /* best effort */ }
+    }
+    rmSync(tempRoot, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+/** Files whose final worktree state differs from the snapshot, including new untracked files. */
+export function worktreeChangedFiles(worktree: DelegateWorktree): string[] {
+  const baselinePaths = nulList(gitText(worktree.root, ["ls-tree", "-r", "--name-only", "-z", worktree.baseline]));
+  const currentPaths = nulList(gitText(worktree.root, ["ls-files", "--cached", "--others", "--exclude-standard", "-z"]));
+  return [...new Set([...baselinePaths, ...currentPaths])]
+    .filter(rel => !parentMatchesBaseline(worktree, worktree.root, rel)).sort();
+}
+
+type BaselineEntry = { mode: string; content: Buffer } | null;
+
+const baselineEntry = (worktree: DelegateWorktree, rel: string): BaselineEntry => {
+  const line = gitText(worktree.root, ["ls-tree", "-z", worktree.baseline, "--", rel]);
+  if (!line || line.slice(line.indexOf("\t") + 1, -1) !== rel) return null;
+  const [mode, type, oid] = line.slice(0, line.indexOf("\t")).split(" ");
+  if (type !== "blob" || !mode || !oid) throw new Error("unsupported baseline entry: " + rel);
+  return { mode, content: gitBuffer(worktree.root, ["cat-file", "blob", oid]) };
+};
+
+const parentMatchesBaseline = (worktree: DelegateWorktree, parentRoot: string, rel: string): boolean => {
+  const target = resolve(parentRoot, rel);
+  if (!safeFilePath(parentRoot, rel)) return false;
+  const baseline = baselineEntry(worktree, rel);
+  const stat = statIfPresent(target);
+  if (!baseline) return !stat;
+  if (!stat) return false;
+  if (baseline.mode === "120000") {
+    return stat.isSymbolicLink() && Buffer.from(readlinkSync(target)).equals(baseline.content);
+  }
+  if (!stat.isFile()) return false;
+  if (baseline.mode === "100644" || baseline.mode === "100755") {
+    const expectedExecutable = baseline.mode === "100755";
+    const actualExecutable = (stat.mode & 0o111) !== 0;
+    if (expectedExecutable !== actualExecutable) return false;
+  }
+  return readFileSync(target).equals(baseline.content);
+};
+
+const reviewableBytes = (bytes: Buffer): boolean => bytes.length <= MAX_TRACKED_BYTES
+  && !bytes.includes(0) && Buffer.from(bytes.toString("utf8")).equals(bytes);
+
+/**
+ * Copy a completed child's changed files back to the parent only when every target still equals the
+ * baseline snapshot. The parent is therefore never overwritten after another actor changed a file.
+ */
+export function applyDelegateWorktree(worktree: DelegateWorktree, parentCwd: string, files: readonly string[],
+  tracker?: ChangeTracker): string[] {
+  const parentRoot = realpathSync(gitText(parentCwd, ["rev-parse", "--show-toplevel"]).trim());
+  if (parentRoot !== worktree.repoRoot) throw new Error("parent repository changed while subagent was running");
+  // Review identities follow the caller's cwd spelling (e.g. /var rather than /private/var).
+  const reviewRoot = resolve(parentCwd, relative(realpathSync(parentCwd), parentRoot));
+  for (const rel of files) {
+    if (!safeFilePath(parentRoot, rel) || statIfPresent(resolve(parentRoot, rel))?.isSymbolicLink()) {
+      throw new Error("unsafe parent changed path: " + rel);
+    }
+    if (!parentMatchesBaseline(worktree, parentRoot, rel)) {
+      throw new Error(`parent changed since delegation started: ${rel}`);
+    }
+    const parentStat = statIfPresent(resolve(parentRoot, rel));
+    if (parentStat?.isFile() && !reviewableBytes(readFileSync(resolve(parentRoot, rel)))) {
+      throw new Error("cannot add changed file to /diff review: " + rel);
+    }
+    const source = resolve(worktree.root, rel);
+    if (!safeFilePath(worktree.root, rel)) throw new Error("unsafe changed path: " + rel);
+    if (statIfPresent(source)) {
+      const stat = lstatSync(source);
+      if (stat.isSymbolicLink()) throw new Error("refusing to apply symlink change: " + rel);
+      if (!stat.isFile()) throw new Error("refusing to apply non-file change: " + rel);
+      const bytes = readFileSync(source);
+      if (!reviewableBytes(bytes)) {
+        throw new Error("cannot add changed file to /diff review: " + rel);
+      }
+    }
+  }
+
+  if (tracker) {
+    for (const rel of files) {
+      const target = resolve(reviewRoot, rel);
+      if (!tracker.capture(target)) throw new Error("cannot add changed file to /diff review: " + rel);
+    }
+  }
+
+  const staged: Array<{ rel: string; target: string; directory: string; replacement?: string; backup?: string }> = [];
+  const createdDirectories: string[] = [];
+  const applied: typeof staged = [];
+  try {
+    // Prepare every replacement and rollback backup before modifying any parent file.
+    // Permission/disk failures in later files therefore cannot leave earlier files half-applied.
+    for (const rel of files) {
+      const source = resolve(worktree.root, rel);
+      const target = resolve(parentRoot, rel);
+      if (!safeFilePath(parentRoot, rel) || !safeFilePath(worktree.root, rel)
+        || statIfPresent(target)?.isSymbolicLink() || statIfPresent(source)?.isSymbolicLink()) {
+        throw new Error("unsafe changed path: " + rel);
+      }
+      const missing: string[] = [];
+      for (let path = dirname(target); !statIfPresent(path); path = dirname(path)) missing.push(path);
+      mkdirSync(dirname(target), { recursive: true });
+      createdDirectories.push(...missing.reverse());
+      const directory = mkdtempSync(join(dirname(target), ".pi-jar-apply-"));
+      const entry: (typeof staged)[number] = { rel, target, directory };
+      staged.push(entry);
+      const before = statIfPresent(target);
+      if (before) {
+        entry.backup = join(directory, "before");
+        writeFileSync(entry.backup, readFileSync(target), { mode: before.mode & 0o777 });
+        chmodSync(entry.backup, before.mode & 0o777);
+      }
+      const after = statIfPresent(source);
+      if (after) {
+        entry.replacement = join(directory, "after");
+        writeFileSync(entry.replacement, readFileSync(source), { mode: after.mode & 0o777 });
+        chmodSync(entry.replacement, after.mode & 0o777);
+      }
+    }
+    for (const entry of staged) {
+      if (!safeFilePath(parentRoot, entry.rel) || !parentMatchesBaseline(worktree, parentRoot, entry.rel)) {
+        throw new Error("parent changed while preparing finalization: " + entry.rel);
+      }
+      if (entry.replacement) renameSync(entry.replacement, entry.target);
+      else if (statIfPresent(entry.target)) unlinkSync(entry.target);
+      applied.push(entry);
+    }
+    for (const entry of applied) tracker?.markDirty(resolve(reviewRoot, entry.rel));
+    return applied.map((entry) => entry.rel);
+  } catch (error) {
+    const unrestored: string[] = [];
+    for (const entry of [...applied].reverse()) {
+      try {
+        if (!safeFilePath(parentRoot, entry.rel)) throw new Error("unsafe rollback path");
+        if (entry.backup) renameSync(entry.backup, entry.target);
+        else if (statIfPresent(entry.target)) unlinkSync(entry.target);
+      } catch { unrestored.push(entry.rel); tracker?.markDirty(resolve(reviewRoot, entry.rel)); }
+    }
+    if (unrestored.length) throw new WorktreeApplyError(String(error) + "; rollback failed for: " + unrestored.join(", "), unrestored);
+    throw error;
+  } finally {
+    for (const entry of staged) { try { rmSync(entry.directory, { recursive: true, force: true }); } catch { /* best effort */ } }
+    for (const directory of createdDirectories.reverse()) { try { rmdirSync(directory); } catch { /* keep non-empty/successfully applied directories */ } }
+  }
+}
+
+/** Exceptional rollback failure: expose any actual parent mutations in the moderator handoff. */
+export class WorktreeApplyError extends Error {
+  readonly appliedFiles: string[];
+  constructor(message: string, appliedFiles: string[]) { super(message); this.appliedFiles = appliedFiles; }
+}
+
+/** Remove a disposable worktree and its dangling snapshot commit reference. */
+export function disposeDelegateWorktree(worktree: DelegateWorktree): void {
+  try { gitText(worktree.repoRoot, ["worktree", "remove", "--force", worktree.root]); }
+  catch {
+    rmSync(worktree.tempRoot, { recursive: true, force: true });
+    try { gitText(worktree.repoRoot, ["worktree", "prune"]); } catch { /* best effort */ }
+    return;
+  }
+  rmSync(worktree.tempRoot, { recursive: true, force: true });
+}