rovecode 0.3.2

package/src/coding/bash.ts

@@ -0,0 +1,148 @@
+/** The bash tool (ports #10, #21, #55). Runs a shell command through the Executor seam — the probed rung
+ *  (direct / wsl / docker) shapes the argv, and the abort path is the rung's tree kill (Windows Job Object
+ *  + taskkill sweep; SIGTERM to the process group on POSIX).
+ *
+ *  It lived at the end of coding/hashline.ts until #55 gave it a timeout and a background flag. That file
+ *  is the anchored-edit implementation; shell execution had simply drifted into its last fifty lines.
+ *  hashline.ts re-exports `bashTool`, so the ten files importing it from there are untouched.
+ *
+ *  ONE TOOL, THREE SHAPES, and the reason it is one tool rather than three: policy runs UPSTREAM of
+ *  execute() — the permission rules, execpolicy, the hooks and the human approval all decide before this
+ *  function is entered. A separate `bash_background` tool would be a second door onto the same room, and
+ *  every rule written for `bash` would have to be written again for it.
+ *    plain              await it, one automatic retry on a non-zero exit
+ *    timeout_ms         the same, with a deadline; a timed-out run KEEPS its partial output and says so
+ *    run_in_background  hand it to the job manager and return the id at once (tools/bash-jobs.ts) */
+
+import type { Tool, ToolContext, ToolOutput } from "../core/types.ts";
+import { getExecutor } from "../core/executor.ts";
+import { startBashJob, hasJobManager } from "../tools/bash-jobs.ts";
+
+/** Upper bound on `timeout_ms`, so a model cannot ask for a deadline that never arrives. Ten minutes:
+ *  past that the honest answer is a background job, which is the flag sitting next to it. */
+export const MAX_TIMEOUT_MS = 600_000;
+
+export const bashTool: Tool = {
+  schema: {
+    name: "bash",
+    description:
+      "Run a shell command in the workspace (cwd locked to the session cwd). One automatic retry on non-zero exit. " +
+      "Destructive system commands are refused by a best-effort blocklist — this is NOT a sandbox. Output truncated to 10k chars. " +
+      `\`timeout_ms\` gives up after that long and RETURNS what the command printed (max ${MAX_TIMEOUT_MS}ms); the process tree is killed. ` +
+      "`run_in_background: true` returns a job id at once instead of waiting — for a dev server, a long build, a slow test run. " +
+      "Read it later with bash_output (only NEW output per read), see them with bash_list, stop one with bash_kill; a finished job also posts one note here by itself.",
+    args: {
+      type: "object",
+      properties: {
+        command: { type: "string" },
+        timeout_ms: { type: "number", description: `give up after this many ms and return the partial output (1..${MAX_TIMEOUT_MS}); a timeout is never retried` },
+        run_in_background: { type: "boolean", description: "start it as a background job and return its id immediately (bash_output reads it)" },
+      },
+      required: ["command"],
+    },
+  },
+  kind: "execute",
+  sequential: true,
+  async execute(args, ctx): Promise<ToolOutput> {
+    const a = args as { command: string; timeout_ms?: unknown; run_in_background?: unknown };
+    const cmd = String(a.command);
+    const denied = deniedCommand(cmd);
+    if (denied) return { ok: false, output: denied };
+
+    // #55: the background flag is read AFTER the blocklist and BEFORE anything runs — a command we
+    // would refuse in the foreground must not become startable by asking for it in the background.
+    if (a.run_in_background === true) {
+      if (!hasJobManager()) {
+        // Deliberately a refusal, not a silent foreground run: the caller asked NOT to be blocked, and
+        // quietly blocking it is the wrong answer to a request we cannot honour.
+        return { ok: false, output: "background jobs are not available on this surface — drop run_in_background to run it in the foreground" };
+      }
+      const started = startBashJob(cmd, ctx.cwd);
+      if (!started.ok) return { ok: false, output: started.reason };
+      return {
+        ok: true,
+        output: `started background job ${started.info.id}: ${cmd}\nIt runs while you continue — do NOT poll in a loop. \`bash_output ${started.info.id}\` reads what is new; a note lands here when it finishes.`,
+        data: started.info,
+      };
+    }
+
+    const timeout = timeoutFrom(a.timeout_ms);
+    if (timeout instanceof Error) return { ok: false, output: timeout.message };
+
+    // port #10: shell execution goes through the Executor seam (direct/wsl/docker
+    // rungs, probed not assumed). Direct rung is byte-compatible with the old
+    // inline runOnce; a missing bash now returns exit=-1 instead of throwing.
+    const run = async (): Promise<{ code: number; text: string; timedOut: boolean }> => {
+      if (timeout === undefined) {
+        const r = await getExecutor().run(cmd, ctx.cwd, ctx.signal);
+        return { code: r.code, text: r.text, timedOut: false };
+      }
+      // The deadline aborts a controller the executor is watching, which IS the tree-kill path — the
+      // same one Esc uses. A timeout that returned while the process kept running would be a lie in
+      // the other direction, and on Windows it would hold the pipe open too.
+      const ac = new AbortController();
+      const onOuter = (): void => ac.abort();
+      ctx.signal.addEventListener("abort", onOuter, { once: true });
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let fired = false;
+      try {
+        timer = setTimeout(() => { fired = true; ac.abort(); }, timeout);
+        const r = await getExecutor().run(cmd, ctx.cwd, ac.signal);
+        return { code: r.code, text: r.text, timedOut: fired };
+      } finally {
+        clearTimeout(timer);
+        ctx.signal.removeEventListener("abort", onOuter);
+      }
+    };
+
+    let r = await run();
+    // single self-contained retry — but NEVER after an abort (port #21): the kill
+    // makes the exit non-zero, and a blind retry would respawn the cancelled
+    // command as a detached subprocess that outlives the run. Nor after a TIMEOUT:
+    // a command that needed more time than it was given needs more time, not twice.
+    if (r.code !== 0 && !r.timedOut && !ctx.signal.aborted) r = await run();
+    if (r.timedOut) {
+      // The partial output is the whole point. A build that timed out has usually already printed the
+      // reason it was slow, and throwing that away leaves the model with only "it took too long".
+      return { ok: false, output: `timed out after ${timeout}ms (process tree killed; what it printed follows)\n${r.text}` };
+    }
+    return { ok: r.code === 0, output: `exit=${r.code}\n${r.text}` };
+  },
+};
+
+/** undefined = no deadline; an Error is a refusal to be RETURNED as tool output, never thrown. */
+function timeoutFrom(raw: unknown): number | undefined | Error {
+  if (raw === undefined || raw === null) return undefined;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return new Error(`timeout_ms must be a positive number of milliseconds (got ${JSON.stringify(raw)})`);
+  if (n > MAX_TIMEOUT_MS) return new Error(`timeout_ms ${n} is longer than the ${MAX_TIMEOUT_MS}ms cap — use run_in_background for work that takes longer`);
+  return Math.floor(n);
+}
+
+// ---------- Bash safety (best-effort blocklist, NOT a sandbox) ----------
+
+/** Footgun guard on the raw command string. A determined agent bypasses it;
+ *  real isolation belongs at the process/OS layer. */
+const denyPatterns: RegExp[] = [
+  /rm\s+(-[a-z]*\s+)*\/(\s|$)/,           // rm -rf /
+  /rm\s+(-[a-z]*\s+)*\/\*/,               // rm -rf /*
+  /rm\s+(-[a-z]*\s+)*(--no-preserve-root\s+)?\*(\s|$)/, // rm -rf *
+  /:\(\)\s*\{/,                            // fork bomb body :(){ ...
+  /\bmkfs(\.\w+)?\b/,
+  /\b(shutdown|reboot|poweroff|halt)\b/,
+  /(^|[;&|\s])(sudo\s+)?format\s+(\/|[c-z]:)/i,  // windows format
+  /(^|[;&|\s])(sudo\s+)?del\s+\/[fqs]/i,         // windows del /f
+  /(^|[;&|\s])(sudo\s+)?rd\s+\/[sq]/i,
+  /(^|[;&|\s])(sudo\s+)?remove-item\s+-(rec|r|f|force)/i,
+  /\bdd\s+[^|]*of=\/dev\/(sd|nvme|hd|disk)/,  // raw disk overwrite
+  />\s*\/dev\/(sd|nvme|hd|disk)/,
+  /\bsudo\b.*\b(rm|mkfs|dd|shutdown|reboot|halt|format)\b/, // sudo + destructive core
+];
+
+export function deniedCommand(cmd: string): string | null {
+  const hit = denyPatterns.find((re) => re.test(cmd));
+  return hit
+    ? `command refused by safety blocklist (matched ${hit.source}): this tool is not a sandbox; rephrase without destructive system commands`
+    : null;
+}
+

package/src/coding/checkpoints.ts

@@ -0,0 +1,327 @@
+/** Shadow-git checkpoints (PORT #11, cline port, Apache-2.0 — see THIRD_PARTY_NOTICES).
+ *
+ *  KNOWN COST, and the design that would remove it — measured 2026-09-06, kept here so the next reader
+ *  starts from the answer rather than the question. The shadow git-dir is per SESSION, so every new
+ *  session pays `git init` + a full `add` of the workspace inside its FIRST write or bash call: 3.45–3.56 s
+ *  in this repository (init+config 160 ms, first add 1.4 s, first commit 1.5 s writing 565 loose objects
+ *  on Windows). Later calls in that session are 210–335 ms, of which ~200 ms is git. It does not amortise
+ *  across sessions because nothing is shared.
+ *
+ *  The cut is one shadow repo per REPOSITORY with a ref per session — a new session's first snapshot
+ *  becomes an incremental add, ~80 ms measured. cline keeps one shadow repo per TASK because a task is its
+ *  unit of restore; ours is the repository, so sessions in one workspace can share an object store and
+ *  differ only by ref. It is NOT a configuration change: a shared git-dir means a shared index and a
+ *  shared HEAD, and today's `add . && commit` / `reset --hard && clean -fd` would collide on index.lock
+ *  (the second writer silently gets no checkpoint) and move HEAD under another session. It has to be
+ *  re-done on plumbing: GIT_INDEX_FILE=<shadow>/<session>.index per session, then add → write-tree →
+ *  commit-tree -p <that session's last> → update-ref refs/rovecode/<session> (atomic per ref, and the
+ *  object store is atomic per object); restore becomes read-tree --reset -u then clean -fd against that
+ *  same index, with no HEAD involved. A hash stays a hash, so restoring one session's checkpoint from
+ *  another finally works — the case per-session storage never allowed, and the one that needs its own
+ *  test, alongside a two-writers concurrency test. Sessions whose old per-session repo exists keep using
+ *  it; nothing needs migrating.
+ *
+ *  A SECOND git repository whose git-dir lives under .rovecode/checkpoints/<session> and whose
+ *  work-tree is the WORKSPACE, so the user's own .git is never written. This is cline's
+ *  shadow-git design: the @8eb5f3d snapshot's docs still describe it (docs/core-workflows/
+ *  checkpoints.mdx:17 "shadow Git repository separate from your project's actual Git
+ *  history … Your main Git repository stays untouched"), but its v4 CODE moved to in-repo
+ *  `git stash create` + refs/cline/* (sdk/packages/core/src/hooks/checkpoint-hooks.ts:172,
+ *  sdk/packages/core/src/session/checkpoint-restore.ts:444-477), which requires a git
+ *  workspace and rewrites the user's HEAD — incompatible with this bar. The mechanics here
+ *  therefore port cline's last shadow-git implementation, v3.89.2
+ *  apps/vscode/src/integrations/checkpoints/:
+ *   - `git init` in the checkpoints dir, then core.worktree=<workspace>, commit.gpgSign
+ *     off, own identity (CheckpointGitOperations.ts:88-94); git-dir = <dir>/.git and
+ *     worktree-mismatch reuse check (CheckpointUtils.ts:20-23, GitOperations.ts:70-73)
+ *   - excludes written to <git-dir>/info/exclude, list headed by ".git/"
+ *     (CheckpointExclusions.ts:42-46 + 297-301)
+ *   - snapshot = `add . --ignore-errors` (CheckpointGitOperations.ts:213) +
+ *     `commit --allow-empty --no-verify` (CheckpointTracker.ts:251-253)
+ *   - restore = `reset --hard <hash>` (CheckpointTracker.ts:364) + `clean -fd` so files
+ *     created after the checkpoint are rewound away while ignored paths (node_modules,
+ *     .rovecode, build output) survive — the reset+clean pair of the snapshot's own restore
+ *     (checkpoint-restore.ts:458-470)
+ *  Deviations from v3.89.2: the shadow repo lives IN-WORKSPACE under .rovecode (bar) so
+ *  ".rovecode/" is excluded from itself; the nested-.git rename dance
+ *  (CheckpointGitOperations.ts:148-166, 207 ".git_disabled") is NOT ported — renaming the
+ *  user's nested .git would violate "user .git never touched", so nested repos become
+ *  inert gitlink entries instead (their contents are not checkpointed, never modified);
+ *  core.autocrlf=false is set so restores are byte-exact on Windows.
+ *
+ *  Conversation restore returns the session entryId to branch to — the CALLER feeds it to
+ *  SessionStore.branch() (port #2 leaf machinery); this module never imports session.ts. */
+
+import { execFile } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export interface Checkpoint {
+  hash: string;          // shadow commit hash
+  label: string;         // e.g. the mutating tool's name
+  entryId?: string;      // session entry to branch to on conversation restore
+  createdAt: number;
+}
+
+export type RestoreMode = "files" | "conversation" | "both";
+
+export type RestoreResult =
+  | { ok: true; mode: RestoreMode; checkpoint: Checkpoint; entryId?: string }
+  | { ok: false; error: string };
+
+/** ToolKind values whose calls mutate the workspace → snapshot after each (bar:
+ *  "snapshot commit after every mutating tool call"). memory writes land under the
+ *  excluded .rovecode/; spawned children's own write/execute calls hit the same hook. */
+export const MUTATING_KINDS: ReadonlySet<string> = new Set(["write", "execute"]);
+
+/** Conversation-restore anchor for a snapshot: the LAST role:"user" message on the
+ *  active path. At snapshot time the tail entry is the assistant message that ISSUED
+ *  the in-flight tool call (the loop appends it pre-dispatch), so anchoring the tail
+ *  branches to a history ending in tool_calls with no tool replies → provider 400.
+ *  cline anchors the user run message instead (checkpoint-restore.ts:217-250).
+ *  Wiring contract (like MUTATING_KINDS): runtime.ts withCheckpoint computes
+ *  `anchorEntryId(activeStore.messages())`. */
+export function anchorEntryId(messages: ReadonlyArray<{ id: string; role: string }>): string | undefined {
+  return messages.findLast((m) => m.role === "user")?.id;
+}
+
+export interface CheckpointsInit {
+  workspace: string;
+  sessionId: string;
+  /** override the shadow root (default <workspace>/.rovecode/checkpoints) — tests/global mode */
+  shadowRoot?: string;
+}
+
+/** cline's default exclusions (CheckpointExclusions.ts:42-70), structural entries first, then the media /
+ *  archive / binary categories. The first port kept only the structural entries, and the snapshot's
+ *  `git add .` then hashed every file the WORKSPACE tracks: in a repo carrying 165 MB of tracked video
+ *  (site/media-src) the first mutating tool call of every session took 26–35 s and left a 232 MB shadow
+ *  repo under .rovecode/checkpoints/<session> (measured 2026-09-06, scripts/probe-turn.ts). A checkpoint
+ *  exists to restore what the agent changed, and the agent does not edit videos, screenshots, archives or
+ *  compiled binaries — those are excluded by extension, like cline does. With videos alone excluded the
+ *  same repo still took 10.7 s and 79 MB: 82 MB of site/screenshots/*.png. Text of any size is still
+ *  snapshotted, and so is SVG (text a designer or the agent writes). */
+const EXCLUDES = [
+  ".git/",
+  ".rovecode/",            // the shadow repo itself lives here (deviation: in-workspace)
+  "node_modules/",
+  "dist/",
+  "build/",
+  "out/",
+  ".next/",
+  "__pycache__/",
+  ".venv/",
+  "venv/",
+  ".DS_Store",
+  // media (cline getMediaFilePatterns): video, audio, raster images — not SVG
+  "*.mp4", "*.m4v", "*.mov", "*.avi", "*.mkv", "*.webm", "*.wmv", "*.flv", "*.mpg", "*.mpeg",
+  "*.mp3", "*.m4a", "*.wav", "*.flac", "*.ogg", "*.aac", "*.wma",
+  "*.png", "*.jpg", "*.jpeg", "*.gif", "*.bmp", "*.ico", "*.webp", "*.tif", "*.tiff", "*.heic", "*.avif", "*.psd",
+  // archives and disk images (getLargeDataFilePatterns)
+  "*.zip", "*.tar", "*.gz", "*.tgz", "*.bz2", "*.xz", "*.7z", "*.rar", "*.iso", "*.dmg",
+  // compiled binaries and native libraries
+  "*.exe", "*.dll", "*.so", "*.dylib", "*.node", "*.wasm", "*.o", "*.a", "*.class", "*.jar", "*.pyc",
+  // databases and caches (getDatabaseFilePatterns / getCacheFilePatterns)
+  "*.sqlite", "*.sqlite3", "*.db", "*.mdb", "*.log",
+];
+
+/** `verb` names the failing subcommand in errors; the default suits bare invocations
+ *  like ["init"], but --git-dir'd calls must pass it (the first non-dash arg there is
+ *  the git-dir PATH — blaming a path instead of the verb misled /restore users). */
+function runGit(args: string[], cwd: string, verb = args.find((a) => !a.startsWith("-")) ?? "", extra: Record<string, string> = {}): Promise<string> {
+  // Explicit env hygiene: a caller's GIT_* vars must not redirect shadow commands
+  // at the USER repo (cline relies on simple-git cwd instead — GitOperations.ts:88).
+  // `extra` is OUR explicit override (position()'s scratch GIT_INDEX_FILE), applied after the scrub.
+  const env = { ...process.env };
+  for (const k of ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_COMMON_DIR"]) delete env[k];
+  Object.assign(env, extra);
+  return new Promise((res, rej) => {
+    execFile("git", args, { cwd, env, windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) rej(new Error(`git ${verb} failed: ${stderr.trim() || err.message}`));
+      else res(stdout.trim());
+    });
+  });
+}
+
+/** Canonical form for workspace-identity compares: realpath fixes case/8.3 aliases of
+ *  EXISTING paths (C:\foo vs c:\foo reopened the shadow repo as "another workspace"
+ *  and silently disabled checkpoints); the case-fold below covers paths realpath
+ *  cannot resolve, on the case-insensitive platform only. */
+function canonPath(p: string): string {
+  let r = p;
+  try { r = (realpathSync.native ?? realpathSync)(p); } catch { /* nonexistent: compare as given */ }
+  return process.platform === "win32" ? r.toLowerCase() : r;
+}
+
+/** The ONE spelling of a session's shadow directory, `<workspace>/.rovecode/checkpoints/<sanitised id>`: the id is
+ *  folded charwise to [A-Za-z0-9._-] and dot-only ids ("."/"..", which survive the charwise filter but escape or
+ *  collapse the shadow root under join()) and "" become underscores. init() creates it; `rovecode sessions delete`
+ *  (core/session-ops.ts) removes it — both through here, so a delete never builds the path a second way. */
+export function checkpointShadowDir(workspace: string, sessionId: string, shadowRoot?: string): string {
+  const cleaned = sessionId.replace(/[^A-Za-z0-9._-]/g, "_");
+  const session = /^\.*$/.test(cleaned) ? cleaned.replace(/\./g, "_") || "_" : cleaned;
+  return join(shadowRoot ?? join(workspace, ".rovecode", "checkpoints"), session);
+}
+
+export class Checkpoints {
+  /** history, oldest first (sidecar-backed: survives process restarts) */
+  private readonly log: Checkpoint[] = [];
+
+  private constructor(
+    readonly workspace: string,
+    /** shadow repo GIT DIR: <workspace>/.rovecode/checkpoints/<session>/.git */
+    readonly gitDir: string,
+    private readonly sidecar: string,
+  ) {}
+
+  /** Every shadow command names its git-dir and work-tree explicitly, so no cwd or
+   *  environment state can ever point one at the user's repo. */
+  private git(...args: string[]): Promise<string> {
+    return runGit(["--git-dir", this.gitDir, "--work-tree", this.workspace, ...args], this.workspace, args[0]);
+  }
+
+  /** Create or reopen the shadow repo for a session. Works whether or not the workspace
+   *  is a git repo — the shadow git-dir is entirely separate (non-git workspaces bar). */
+  static async init(opts: CheckpointsInit): Promise<Checkpoints> {
+    const workspace = resolve(opts.workspace);
+    const shadowDir = checkpointShadowDir(workspace, opts.sessionId, opts.shadowRoot);
+    const gitDir = join(shadowDir, ".git"); // cline layout: <checkpointsDir>/.git (CheckpointUtils.ts:20-23)
+    mkdirSync(shadowDir, { recursive: true });
+    const cp = new Checkpoints(workspace, gitDir, join(shadowDir, "checkpoints.jsonl"));
+
+    if (!existsSync(join(gitDir, "HEAD"))) {
+      // plain `git init` in the shadow dir, exactly GitOperations.ts:88
+      await runGit(["init"], shadowDir);
+      // GitOperations.ts:91-94 config block (identity ours; autocrlf is an rovecode addition)
+      for (const [k, v] of [
+        ["core.worktree", workspace],
+        ["commit.gpgSign", "false"],
+        ["core.autocrlf", "false"],
+        ["user.name", "Rovecode Checkpoint"],
+        ["user.email", "checkpoint@rovecode.local"],
+      ] as const) await cp.git("config", k, v);
+    } else {
+      // reuse check: refuse a shadow repo whose recorded worktree is another path
+      // (GitOperations.ts:70-73 "Checkpoints can only be used in the original workspace").
+      // Compared canonically — a case-variant reopen (C:\foo vs c:\foo) is the SAME dir.
+      const wt = await cp.git("config", "core.worktree").catch(() => "");
+      if (canonPath(resolve(wt)) !== canonPath(workspace)) throw new Error(`checkpoints: shadow repo belongs to ${wt}, not ${workspace}`);
+    }
+    // (re)write excludes into the shadow git-dir every init (CheckpointExclusions.ts:297-301)
+    mkdirSync(join(gitDir, "info"), { recursive: true });
+    writeFileSync(join(gitDir, "info", "exclude"), EXCLUDES.join("\n") + "\n");
+    cp.loadSidecar();
+    return cp;
+  }
+
+  private loadSidecar(): void {
+    if (!existsSync(this.sidecar)) return;
+    for (const line of readFileSync(this.sidecar, "utf8").split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const c = JSON.parse(line) as Checkpoint;
+        if (typeof c.hash === "string" && typeof c.label === "string") this.log.push(c);
+      } catch { /* corrupt sidecar line: skip, never throw (session.ts reload pattern) */ }
+    }
+  }
+
+  /** Snapshot the whole workspace: stage-all + allow-empty commit
+   *  (GitOperations.ts:213 + CheckpointTracker.ts:251-253). Call after every mutating
+   *  tool call; `entryId` is the session entry a conversation restore should branch to. */
+  async snapshot(label: string, entryId?: string): Promise<Checkpoint> {
+    await this.git("add", ".", "--ignore-errors");
+    await this.git("commit", "--allow-empty", "--no-verify", "-m", `rovecode-checkpoint: ${label}`);
+    const hash = await this.git("rev-parse", "HEAD");
+    const c: Checkpoint = { hash, label, createdAt: Date.now(), ...(entryId !== undefined ? { entryId } : {}) };
+    appendFileSync(this.sidecar, JSON.stringify(c) + "\n");
+    this.log.push(c);
+    return c;
+  }
+
+  /** History oldest→newest. */
+  list(): Checkpoint[] { return [...this.log]; }
+
+  /** Where the workspace sits in the snapshot history (port #65 /undo). `at` — the NEWEST checkpoint whose tree
+   *  equals the work tree as it is now (staged into a SCRATCH index under the shadow git-dir, so the real index —
+   *  and changedSince's untracked list — stay untouched); null when no snapshot matches (the workspace drifted).
+   *  `previous` — the nearest ANCESTOR of `at` whose content differs (the pre-edit state; re-snapshots of an
+   *  unchanged tree are stepped over; after a restore the shadow history forks, so the parent chain is followed,
+   *  not the list order); null when nothing older differs. The git-call count does not grow with the history
+   *  (rev-parse takes the hashes in batches); any git failure degrades to `{ at: null, previous: null }`, which a
+   *  caller treats as a drifted workspace. */
+  async position(): Promise<{ at: Checkpoint | null; previous: Checkpoint | null }> {
+    const none = { at: null, previous: null };
+    if (this.log.length === 0) return none;
+    const scratch = join(this.gitDir, "rovecode-undo-index");
+    const base = ["--git-dir", this.gitDir, "--work-tree", this.workspace];
+    try {
+      rmSync(scratch, { force: true });
+      await runGit([...base, "add", ".", "--ignore-errors"], this.workspace, "add", { GIT_INDEX_FILE: scratch });
+      const tree = await runGit([...base, "write-tree"], this.workspace, "write-tree", { GIT_INDEX_FILE: scratch });
+      const trees: string[] = [];
+      for (let i = 0; i < this.log.length; i += 200) {
+        trees.push(...(await this.git("rev-parse", ...this.log.slice(i, i + 200).map((c) => `${c.hash}^{tree}`))).split("\n").map((s) => s.trim()));
+      }
+      const atIdx = trees.lastIndexOf(tree);
+      if (atIdx < 0) return none;
+      const at = this.log[atIdx]!;
+      for (const h of (await this.git("rev-list", at.hash)).split("\n").slice(1)) {
+        const i = this.log.findLastIndex((c) => c.hash === h.trim());
+        if (i >= 0 && trees[i] !== tree) return { at, previous: this.log[i]! };
+      }
+      return { at, previous: null };
+    } catch { return none; }
+    finally { rmSync(scratch, { force: true }); }
+  }
+
+  /** What a "files" restore of `hash` would touch (port #65 /undo's confirmation card): tracked paths whose
+   *  work-tree content differs from the snapshot (`diff --name-status <hash>`: M rewritten, D recreated) plus
+   *  the untracked, non-excluded paths `clean -fd` would remove (`?`). Read-only; null when git fails, so a
+   *  caller falls back to a generic card instead of a wrong list. */
+  async changedSince(hash: string): Promise<{ path: string; status: string }[] | null> {
+    try {
+      const out: { path: string; status: string }[] = [];
+      for (const line of (await this.git("diff", "--name-status", hash)).split("\n")) {
+        const m = /^([A-Z])\S*\t(.+)$/.exec(line.trim());
+        if (m) out.push({ status: m[1]!, path: m[2]!.split("\t").at(-1)! });
+      }
+      for (const p of (await this.git("ls-files", "--others", "--exclude-standard")).split("\n")) if (p.trim()) out.push({ status: "?", path: p.trim() });
+      return out;
+    } catch { return null; }
+  }
+
+  /** Restore a checkpoint by full hash or unique prefix.
+   *  - "files": worktree → checkpoint state (reset --hard + clean -fd; ignored paths survive)
+   *  - "conversation": NO file changes; returns the entryId for SessionStore.branch()
+   *  - "both": files restored AND entryId returned
+   *  Never throws — bad refs/modes AND shadow-git failures (a stale index.lock used to
+   *  escape here and kill the TUI on unhandled rejection) come back structured, the
+   *  error naming the failing verb (reset/clean). */
+  async restore(ref: string, mode: RestoreMode): Promise<RestoreResult> {
+    const hits = this.log.filter((c) => c.hash === ref || c.hash.startsWith(ref));
+    // duplicate hashes (identical content re-snapshotted) are ONE candidate — the
+    // LATEST entry wins so its (newer) conversation anchor is the one restored
+    const target = hits.at(-1);
+    if (!target || ref.length < 4) return { ok: false, error: `no checkpoint matches ${ref}` };
+    if (new Set(hits.map((h) => h.hash)).size > 1) return { ok: false, error: `ambiguous checkpoint prefix ${ref}` };
+    // conversation restore needs a recorded entryId — reject BEFORE touching any file,
+    // so "both" can never half-apply
+    if (mode !== "files" && target.entryId === undefined) {
+      return { ok: false, error: `checkpoint ${target.hash.slice(0, 8)} has no session entryId` };
+    }
+    if (mode !== "conversation") {
+      try {
+        await this.git("reset", "--hard", target.hash);        // CheckpointTracker.ts:364
+        // remove files created after the checkpoint; single -f spares nested git repos,
+        // no -x spares ignored/excluded paths (checkpoint-restore.ts:458-470)
+        await this.git("clean", "-fd");
+      } catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+      }
+    }
+    return {
+      ok: true, mode, checkpoint: target,
+      ...(mode !== "files" && target.entryId !== undefined ? { entryId: target.entryId } : {}),
+    };
+  }
+}

package/src/coding/diff.ts

@@ -0,0 +1,138 @@
+/** Port #24 — bounded unified-diff preview for edit/write approvals.
+ *
+ *  The post-change content is computed IN MEMORY (edit: hashline's pure apply over the
+ *  current file; write: the proposed content), diffed against the file with jsdiff
+ *  (`diff`, BSD-3-Clause — see THIRD_PARTY_NOTICES.md), and rendered git-style, clipped
+ *  to maxLines with an exact "… +N more lines" marker. Never throws: stale anchors,
+ *  binary content, malformed args and I/O errors all come back as kind "unavailable"
+ *  carrying the reason, so the approval overlay degrades instead of blocking the ask.
+ *  Shape follows gemini-cli's confirmation diffs — structuredPatch with a small context
+ *  (packages/core/src/tools/diffOptions.ts:10-18) and CR-tolerant line comparison
+ *  (diff-utils.ts:22 splits on /\r?\n/; here jsdiff's stripTrailingCr). No code copied. */
+
+import { existsSync, readFileSync } from "node:fs";
+import { relative } from "node:path";
+import { toolPath } from "../core/workspace.ts";
+import { structuredPatch } from "diff";
+import { applyEditsToContent, type EditFailure, type EditOp } from "./hashline.ts";
+
+export type DiffKind = "modify" | "create" | "unchanged" | "unavailable";
+export interface DiffPreview { text: string; truncated: boolean; kind: DiffKind }
+export interface DiffPreviewOptions { maxLines?: number; context?: number }
+
+/** default cap on rendered lines (headers + hunks); the TUI clips further to its rows */
+export const DIFF_MAX_LINES = 40;
+const DIFF_CONTEXT = 3;
+/** git's buffer_is_binary heuristic: a NUL byte within the first 8000 bytes */
+const BINARY_SNIFF = 8000;
+/** Myers budget: a rewrite beyond this many edited lines is reported, not diffed (bounded CPU);
+ *  the wall-clock cap is a safety net for huge files, the edit-length cap is the deterministic one */
+const MAX_EDIT_LENGTH = 2000;
+const MAX_DIFF_MS = 1000;
+const MAX_CHARS = 4_000_000;
+
+/** `… +N more lines` — the exact marker appended when the output is clipped. */
+export function moreMarker(n: number): string { return `… +${n} more line${n === 1 ? "" : "s"}`; }
+
+/** Keep the first `max` lines; the marker accounts for every hidden line. */
+export function clipLines(lines: string[], max: number): string[] {
+  return lines.length > max ? [...lines.slice(0, max), moreMarker(lines.length - max)] : lines;
+}
+
+/** the ladder's own spelling (core/workspace.ts toolPath): the preview names the file the tool will open */
+function resolvePath(cwd: string, p: string): string { return toolPath(cwd, p); }
+
+function hasNul(buf: Uint8Array): boolean {
+  const n = Math.min(buf.length, BINARY_SNIFF);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+const unavailable = (reason: string): DiffPreview => ({ text: `diff unavailable: ${reason}`, truncated: false, kind: "unavailable" });
+
+function failureReason(f: EditFailure): string {
+  switch (f.kind) {
+    case "tag-mismatch": return `stale read — file TAG is now ${f.actual}, the edit expects ${f.expected}`;
+    case "hash-mismatch": return `stale anchor — line ${f.line} hash is ${f.actual}, the edit expects ${f.expected}; ${f.nearest}`;
+    case "out-of-range": return `line ${f.line} out of range (file has ${f.lineCount} lines)`;
+  }
+}
+
+/** The edit tool's args, validated (a malformed call yields "unavailable", never a throw). */
+function editOps(args: Record<string, unknown>, path: string): EditOp[] | null {
+  if (!Array.isArray(args.edits)) return null;
+  const ops: EditOp[] = [];
+  for (const e of args.edits as unknown[]) {
+    const o = (typeof e === "object" && e !== null ? e : {}) as Record<string, unknown>;
+    if (typeof o.tag !== "string" || typeof o.anchorHash !== "string" || typeof o.anchorLine !== "number") return null;
+    if (!Array.isArray(o.newLines) || !o.newLines.every((l) => typeof l === "string")) return null;
+    ops.push({ path, tag: o.tag, anchorLine: o.anchorLine, anchorHash: o.anchorHash, newLines: o.newLines as string[] });
+  }
+  return ops;
+}
+
+/** Content → signed display lines: CRLF-tolerant, trailing newline dropped, missing EOF newline noted. */
+function signedLines(content: string, sign: "+" | "-"): string[] {
+  const lines = content.replace(/\r\n/g, "\n").split("\n");
+  const eofNewline = lines[lines.length - 1] === "";
+  if (eofNewline) lines.pop();
+  const out = lines.map((l) => sign + l);
+  if (!eofNewline && out.length > 0) out.push("\");
+  return out;
+}
+
+function renderUnified(rel: string, before: string | null, after: string, opts: DiffPreviewOptions): DiffPreview {
+  const maxLines = opts.maxLines ?? DIFF_MAX_LINES;
+  if (before === after) return { text: "", truncated: false, kind: "unchanged" };
+  const body: string[] = [];
+  let kind: DiffKind = "modify";
+  if (before === null) {
+    // new file: every line is an add — no Myers pass needed (nor its cost on big files)
+    kind = "create";
+    const adds = signedLines(after, "+");
+    if (adds.length > 0) body.push(`@@ -0,0 +1,${adds.filter((l) => l[0] === "+").length} @@`, ...adds);
+  } else {
+    if (before.length + after.length > MAX_CHARS) return unavailable("file too large to preview");
+    // stripTrailingCr: a CRLF file diffs by content, not by line ending (gemini-cli diff-utils.ts:22)
+    const patch = structuredPatch(rel, rel, before, after, undefined, undefined,
+      { context: opts.context ?? DIFF_CONTEXT, stripTrailingCr: true, maxEditLength: MAX_EDIT_LENGTH, timeout: MAX_DIFF_MS });
+    if (patch === undefined) return unavailable(`change too large to preview (over ${MAX_EDIT_LENGTH} edited lines or ${MAX_DIFF_MS}ms)`);
+    for (const h of patch.hunks) body.push(`@@ -${h.oldStart},${h.oldLines} +${h.newStart},${h.newLines} @@`, ...h.lines);
+    if (body.length === 0) return { text: "no content changes (line endings only)", truncated: false, kind: "unchanged" };
+  }
+  const lines = [`--- ${before === null ? "/dev/null" : `a/${rel}`}`, `+++ b/${rel}`, ...body];
+  return { text: clipLines(lines, maxLines).join("\n"), truncated: lines.length > maxLines, kind };
+}
+
+/** Preview what an edit/write tool call would do to its file, as a bounded unified diff.
+ *  `args` are the (revised) tool args exactly as the tool would receive them. */
+export function previewDiff(tool: "edit" | "write", args: unknown, cwd: string, opts: DiffPreviewOptions = {}): DiffPreview {
+  try {
+    const a = (typeof args === "object" && args !== null ? args : {}) as Record<string, unknown>;
+    if (typeof a.path !== "string" || a.path === "") return unavailable("missing path");
+    const abs = resolvePath(cwd, a.path);
+    const rel = relative(cwd, abs).replace(/\\/g, "/") || a.path;
+    let before: string | null = null;
+    if (existsSync(abs)) {
+      const buf = readFileSync(abs);
+      if (hasNul(buf)) return unavailable("binary file");
+      before = buf.toString("utf8");
+    }
+    let after: string;
+    if (tool === "write") {
+      if (typeof a.content !== "string") return unavailable("missing content");
+      after = a.content;
+    } else {
+      if (before === null) return unavailable(`file not found: ${abs}`);
+      const ops = editOps(a, abs);
+      if (ops === null) return unavailable("malformed edits");
+      const r = applyEditsToContent(before, ops, abs);
+      if (!r.ok) return unavailable(failureReason(r.failure));
+      after = r.content;
+    }
+    if (after.includes("\0")) return unavailable("binary content");
+    return renderUnified(rel, before, after, opts);
+  } catch (e) {
+    return unavailable(e instanceof Error ? e.message : String(e));
+  }
+}