@bachi/pi-coder 1.0.0

package/extensions/rewind/checkpoints.ts

@@ -0,0 +1,820 @@
+/**
+ * pi-rewind core — checkpoint storage on a shadow git repository.
+ *
+ * Zero pi imports: pure git + fs operations so the whole module is testable
+ * with `node --test`.
+ *
+ * Why a shadow repo instead of refs in the user's repository (the approach
+ * pi-rewind/checkpoint-pi use):
+ *   - the user's repo keeps zero extra refs, objects and history entries;
+ *   - the user's real index/HEAD are never touched, so a restore cannot move
+ *     HEAD or discard staged work (Claude Code behaves the same way: its
+ *     checkpoints "live beside your git history, not inside it");
+ *   - checkpointing also works when the working directory is not a git repo.
+ *
+ * A checkpoint is a worktree tree object plus a commit that keeps it reachable
+ * through refs/pi-rewind/<id>, so `git gc --auto` can never prune a live
+ * checkpoint. Snapshotting respects .gitignore (plus the real repo's
+ * info/exclude, copied into the shadow repo once), so node_modules and friends
+ * are never copied into snapshots.
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve as resolvePath } from "node:path";
+
+/** Ref namespace that keeps checkpoint objects reachable inside the shadow repo. */
+export const REF_PREFIX = "refs/pi-rewind";
+
+/** Claude Code keeps file snapshots for the 100 most recent checkpoints per session. */
+export const MAX_CHECKPOINTS_PER_SESSION = 100;
+
+/** Claude Code's retention sweep deletes snapshots ~30 days after the session last saved one. */
+export const RETENTION_DAYS = 30;
+
+/** Pre-images larger than this are skipped: they would bloat the shadow store. */
+export const MAX_EXTERNAL_FILE_BYTES = 8 * 1024 * 1024;
+
+export type CheckpointKind = "session-start" | "prompt" | "safety";
+
+/**
+ * Pre-image of a file the worktree snapshot cannot see — one outside the
+ * project root, or one inside it that `.gitignore` hides from `git add -A`.
+ *
+ * `blob` names a content-addressed copy under <projectDir>/files, or is null
+ * when the file did not exist at capture time (so a restore deletes it).
+ */
+export interface ExternalFile {
+  /** Absolute path of the file on disk. */
+  path: string;
+  /** Content-addressed blob name, or null for "did not exist". */
+  blob: string | null;
+}
+
+export interface Checkpoint {
+  /** Unique id; also the shadow-repo ref name suffix. */
+  id: string;
+  /** Session this checkpoint belongs to. */
+  sessionId: string;
+  /** "session-start" = snapshot taken when the session opened,
+   *  "prompt" = snapshot taken before a user prompt,
+   *  "safety" = snapshot taken right before a code restore (undo net). */
+  kind: CheckpointKind;
+  /** User prompt text ("" for session-start / safety checkpoints). */
+  prompt: string;
+  /** Session entry id of the user message, once resolved. Conversation
+   *  restore navigates the session tree to this entry. */
+  entryId?: string;
+  /** Worktree tree sha in the shadow repo. */
+  tree: string;
+  /** Pre-images of files this checkpoint's turn edited outside the worktree
+   *  snapshot (recorded lazily, first touch wins). */
+  files?: ExternalFile[];
+  /** Commit sha holding the tree (reachable via refs/pi-rewind/<id>). */
+  commit: string;
+  /** Epoch ms. */
+  timestamp: number;
+}
+
+export interface RewindStore {
+  /** Absolute path of the snapshot working tree (the project directory). */
+  root: string;
+  /** Shadow GIT_DIR — outside the project, never the project's own .git. */
+  gitDir: string;
+  /** Metadata file holding every session's checkpoint list. */
+  metaFile: string;
+  /** Directory holding the pre-image blobs referenced by `files`. */
+  filesDir: string;
+  /** Stable per-project key (hash of the root path). */
+  projectKey: string;
+}
+
+export interface DiffEntry {
+  /** git name-status letter: A / M / D / R… / T */
+  status: string;
+  path: string;
+}
+
+export interface CheckpointDiff {
+  entries: DiffEntry[];
+  /** True when the two trees are identical (nothing to restore). */
+  empty: boolean;
+}
+
+export interface RestoreResult {
+  /** Untracked files that were deleted because the checkpoint did not have them. */
+  removed: string[];
+}
+
+interface StoreMeta {
+  version: 1;
+  root: string;
+  updatedAt: number;
+  sessions: Record<string, Checkpoint[]>;
+}
+
+// ---------------------------------------------------------------------------
+// git plumbing
+// ---------------------------------------------------------------------------
+
+export interface GitRunOptions {
+  input?: string;
+  /** Resolve with stderr instead of rejecting on a non-zero exit code. */
+  allowFailure?: boolean;
+}
+
+/** Run git against the shadow repo. Args are passed as an array (no shell). */
+export function git(
+  store: RewindStore,
+  args: string[],
+  options: GitRunOptions = {},
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", args, {
+      cwd: store.root,
+      env: shadowEnv(store),
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => (stdout += chunk));
+    child.stderr.on("data", (chunk) => (stderr += chunk));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) resolve(stdout.trim());
+      else if (options.allowFailure) resolve(stderr.trim());
+      else reject(new Error(stderr.trim() || `git ${args[0]} failed (code ${code})`));
+    });
+
+    if (child.stdin) {
+      if (options.input) child.stdin.write(options.input);
+      child.stdin.end();
+    }
+  });
+}
+
+/** git env for the shadow repo: strips inherited git plumbing variables so a
+ *  stray GIT_DIR/GIT_INDEX_FILE in pi's environment can never redirect us. */
+function shadowEnv(store: RewindStore): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  for (const key of [
+    "GIT_DIR",
+    "GIT_WORK_TREE",
+    "GIT_INDEX_FILE",
+    "GIT_OBJECT_DIRECTORY",
+    "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+    "GIT_NAMESPACE",
+    "GIT_COMMON_DIR",
+  ]) {
+    delete env[key];
+  }
+  env.GIT_DIR = store.gitDir;
+  env.GIT_WORK_TREE = store.root;
+  // commit-tree needs an identity; checkpoint commits are never authored by the user.
+  env.GIT_AUTHOR_NAME = "pi-rewind";
+  env.GIT_AUTHOR_EMAIL = "pi-rewind@pi";
+  env.GIT_COMMITTER_NAME = "pi-rewind";
+  env.GIT_COMMITTER_EMAIL = "pi-rewind@pi";
+  return env;
+}
+
+/** Absolute path of the directory that holds every project's shadow repo. */
+export function rewindBaseDir(agentDir: string): string {
+  return join(agentDir, "rewind");
+}
+
+/** Stable per-project key so two checkouts of the same repo do not collide. */
+export function projectKeyFor(root: string): string {
+  return createHash("sha1").update(root).digest("hex").slice(0, 16);
+}
+
+/**
+ * Open (and on first use create) the shadow repo for `root`.
+ * Idempotent; safe to call on every session start.
+ */
+export function openStore(root: string, agentDir: string): RewindStore {
+  const absoluteRoot = resolveRoot(root);
+  const projectKey = projectKeyFor(absoluteRoot);
+  const projectDir = join(rewindBaseDir(agentDir), projectKey);
+  const gitDir = join(projectDir, "git");
+  const metaFile = join(projectDir, "checkpoints.json");
+  const filesDir = join(projectDir, "files");
+
+  mkdirSync(projectDir, { recursive: true });
+
+  if (!existsSync(join(gitDir, "HEAD"))) {
+    mkdirSync(gitDir, { recursive: true });
+    // `git init <path>` would create <path>/.git (it treats the argument as a
+    // work tree), so the repo structure is initialised through GIT_DIR instead.
+    const child = spawnSyncGit(["init", "--quiet", "--initial-branch=pi-rewind"], {
+      GIT_DIR: gitDir,
+    });
+    if (child.status !== 0) {
+      throw new Error(`git init failed for ${gitDir}: ${child.stderr || `code ${child.status}`}`);
+    }
+  }
+
+  // Re-adopted on every open so later edits to the real repo's exclude file
+  // are picked up; a missing file leaves any previous copy untouched.
+  adoptRealRepoExcludes(absoluteRoot, gitDir);
+
+  return { root: absoluteRoot, gitDir, metaFile, filesDir, projectKey };
+}
+
+function resolveRoot(root: string): string {
+  // A normalized absolute path is stable enough for the project key; realpath
+  // would add a failure mode on dangling symlinks.
+  const absolute = resolvePath(root);
+  return absolute.replace(/\/+$/, "") || "/";
+}
+
+/**
+ * Copy the real repository's info/exclude into the shadow repo so paths the
+ * user deliberately keeps out of git are not snapshotted (and therefore not
+ * deleted by a restore's `git clean`).
+ */
+function adoptRealRepoExcludes(root: string, gitDir: string): void {
+  const realExclude = join(root, ".git", "info", "exclude");
+  try {
+    if (!statSync(realExclude).isFile()) return;
+    mkdirSync(join(gitDir, "info"), { recursive: true });
+    copyFileSync(realExclude, join(gitDir, "info", "exclude"));
+  } catch {
+    // No real repo, or nothing to adopt — both fine.
+  }
+}
+
+/** Small sync git helper used only for `git init` during openStore. */
+function spawnSyncGit(
+  args: string[],
+  envOverrides: Record<string, string> = {},
+): { status: number | null; stderr: string } {
+  const result = spawnSync("git", args, {
+    encoding: "utf8",
+    env: { ...process.env, ...envOverrides },
+  });
+  return { status: result.status, stderr: (result.stderr || "").trim() };
+}
+
+// ---------------------------------------------------------------------------
+// metadata
+// ---------------------------------------------------------------------------
+
+export function readMeta(store: RewindStore): StoreMeta {
+  try {
+    const parsed = JSON.parse(readFileSync(store.metaFile, "utf8")) as StoreMeta;
+    if (parsed && parsed.version === 1 && parsed.sessions) return parsed;
+  } catch {
+    // Missing or corrupt metadata: start over. Checkpoint objects stay in the
+    // shadow repo but become unreachable and are collected by the next gc.
+  }
+  return { version: 1, root: store.root, updatedAt: 0, sessions: {} };
+}
+
+export function writeMeta(store: RewindStore, meta: StoreMeta): void {
+  meta.updatedAt = Date.now();
+  mkdirSync(dirname(store.metaFile), { recursive: true });
+  writeFileSync(store.metaFile, `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+}
+
+export function listCheckpoints(store: RewindStore, sessionId: string): Checkpoint[] {
+  const meta = readMeta(store);
+  const list = meta.sessions[sessionId] ?? [];
+  // Defensive copy, oldest first.
+  return [...list].sort((a, b) => a.timestamp - b.timestamp);
+}
+
+/** Newest-first view used by the menu. */
+export function listCheckpointsNewestFirst(store: RewindStore, sessionId: string): Checkpoint[] {
+  return listCheckpoints(store, sessionId).reverse();
+}
+
+function replaceSessionList(
+  store: RewindStore,
+  sessionId: string,
+  mutate: (list: Checkpoint[]) => Checkpoint[],
+): void {
+  const meta = readMeta(store);
+  const current = meta.sessions[sessionId] ?? [];
+  const next = mutate([...current].sort((a, b) => a.timestamp - b.timestamp));
+  if (next.length === 0) delete meta.sessions[sessionId];
+  else meta.sessions[sessionId] = next;
+  writeMeta(store, meta);
+}
+
+/** Attach the resolved user-message entry id to a checkpoint. */
+export function attachEntryId(
+  store: RewindStore,
+  sessionId: string,
+  checkpointId: string,
+  entryId: string,
+): boolean {
+  let found = false;
+  replaceSessionList(store, sessionId, (list) =>
+    list.map((cp) => {
+      if (cp.id !== checkpointId || cp.entryId) return cp;
+      found = true;
+      return { ...cp, entryId };
+    }),
+  );
+  return found;
+}
+
+/** Oldest checkpoint of a session that still lacks an entry id. */
+export function findUnresolvedCheckpoint(
+  store: RewindStore,
+  sessionId: string,
+): Checkpoint | undefined {
+  return listCheckpoints(store, sessionId).find((cp) => cp.kind === "prompt" && !cp.entryId);
+}
+
+/** Newest safety checkpoint (the "undo last rewind" target), if any. */
+export function latestSafetyCheckpoint(
+  store: RewindStore,
+  sessionId: string,
+): Checkpoint | undefined {
+  const safety = listCheckpoints(store, sessionId).filter((cp) => cp.kind === "safety");
+  return safety.length > 0 ? safety[safety.length - 1] : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// snapshot / checkpoint creation
+// ---------------------------------------------------------------------------
+
+/**
+ * Hash the current worktree into the shadow repo and return its tree sha.
+ * Also leaves the shadow index warm, which keeps later snapshots cheap.
+ */
+export async function snapshotTree(store: RewindStore): Promise<string> {
+  // -A stages modifications, deletions and new files; .gitignore still applies.
+  await git(store, ["add", "-A", "--ignore-errors", "--"], { allowFailure: true });
+  return git(store, ["write-tree"]);
+}
+
+export interface CreateCheckpointOptions {
+  sessionId: string;
+  kind: CheckpointKind;
+  prompt?: string;
+  entryId?: string;
+  /** Reuse an existing tree sha instead of hashing the worktree again. */
+  tree?: string;
+  /** Pre-images for files outside the worktree snapshot (safety checkpoints). */
+  files?: ExternalFile[];
+  timestamp?: number;
+}
+
+/**
+ * Snapshot the worktree and record a checkpoint.
+ *
+ * When the worktree is unchanged since the session's previous checkpoint the
+ * existing commit is reused (no new object, no new ref) — read-only turns cost
+ * nothing but a metadata row.
+ */
+export async function createCheckpoint(
+  store: RewindStore,
+  options: CreateCheckpointOptions,
+): Promise<Checkpoint> {
+  const timestamp = options.timestamp ?? Date.now();
+  const tree = options.tree ?? (await snapshotTree(store));
+  const previous = listCheckpoints(store, options.sessionId);
+  const reusable = previous.find((cp) => cp.tree === tree);
+
+  let commit: string;
+  if (reusable) {
+    commit = reusable.commit;
+  } else {
+    const message = [
+      `pi-rewind ${options.kind}`,
+      `session ${options.sessionId}`,
+      `created ${new Date(timestamp).toISOString()}`,
+      options.prompt ? `prompt ${options.prompt.slice(0, 200)}` : null,
+    ]
+      .filter(Boolean)
+      .join("\n");
+    commit = await git(store, ["commit-tree", tree], { input: message });
+  }
+
+  const id = `${options.kind}-${timestamp}-${createHash("sha1").update(`${tree}:${timestamp}`).digest("hex").slice(0, 8)}`;
+  await git(store, ["update-ref", `${REF_PREFIX}/${id}`, commit]);
+
+  const checkpoint: Checkpoint = {
+    id,
+    sessionId: options.sessionId,
+    kind: options.kind,
+    prompt: options.prompt ?? "",
+    ...(options.entryId ? { entryId: options.entryId } : {}),
+    ...(options.files && options.files.length > 0 ? { files: options.files } : {}),
+    tree,
+    commit,
+    timestamp,
+  };
+
+  replaceSessionList(store, options.sessionId, (list) => [...list, checkpoint]);
+  return checkpoint;
+}
+
+// ---------------------------------------------------------------------------
+// pre-images: files the worktree snapshot cannot see
+// ---------------------------------------------------------------------------
+
+/**
+ * A checkpoint only snapshots the worktree under the project root, and
+ * `git add -A` skips `.gitignore`d paths. Everything the agent edits elsewhere
+ * (`~/.pi/agent/themes/…`, `~/.claude/settings.json`, an ignored `.env`) would
+ * therefore be invisible to `/rewind` — its diff would come out empty and the
+ * menu would hide the code options entirely (the bug this section fixes).
+ *
+ * Such files are captured lazily instead: right before an `edit`/`write` tool
+ * runs, the bytes on disk are copied into the project's blob store and recorded
+ * on the session's newest checkpoint. The first touch inside a turn wins, so
+ * the record is the state as it was *before* the turn changed it.
+ */
+
+/**
+ * Is `path` covered by the worktree snapshot (inside the root and not ignored)?
+ * Only then can the shadow tree restore it, so only uncovered paths need a
+ * pre-image. `git check-ignore` is consulted because it applies exactly the
+ * rules `git add -A` uses — the project's `.gitignore` files plus the shadow
+ * repo's `info/exclude` (copied from the real repo).
+ */
+export function isWorktreeCovered(store: RewindStore, path: string): boolean {
+  const rel = relative(store.root, path);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return false;
+  const result = spawnSync("git", ["check-ignore", "-q", "--", rel], {
+    cwd: store.root,
+    env: shadowEnv(store),
+    stdio: ["ignore", "ignore", "ignore"],
+  });
+  // 0 = ignored, 1 = not ignored, anything else = no answer -> treat as covered.
+  return result.status !== 0;
+}
+
+/** Absolute form of a tool's `path` argument (relative resolves to the cwd). */
+export function resolveTargetPath(store: RewindStore, path: string): string {
+  return isAbsolute(path) ? resolvePath(path) : resolvePath(store.root, path);
+}
+
+/**
+ * Copy `path`'s current bytes into the blob store.
+ * Returns the blob name, null when the file does not exist (a pre-image that
+ * means "delete it on restore"), or undefined when it is not storable
+ * (directory, oversized, unreadable). Content addressing dedupes versions.
+ */
+function storeBlob(store: RewindStore, path: string): string | null | undefined {
+  try {
+    const stat = statSync(path, { throwIfNoEntry: false });
+    if (!stat) return null;
+    if (!stat.isFile() || stat.size > MAX_EXTERNAL_FILE_BYTES) return undefined;
+    const content = readFileSync(path);
+    const name = createHash("sha1").update(content).digest("hex");
+    const target = join(store.filesDir, name);
+    if (!existsSync(target)) {
+      mkdirSync(store.filesDir, { recursive: true });
+      writeFileSync(target, content);
+    }
+    return name;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Do the bytes on disk still match the pre-image? */
+function blobMatches(store: RewindStore, record: ExternalFile): boolean {
+  if (record.blob === null) return !existsSync(record.path);
+  try {
+    return readFileSync(record.path).equals(readFileSync(join(store.filesDir, record.blob)));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Record `path`'s current content as a pre-image on the session's newest
+ * checkpoint. Returns true when something was recorded.
+ *
+ * Called from the `tool_call` handler before the tool runs; the caller must
+ * serialize it with `createCheckpoint` (both rewrite the metadata file).
+ */
+export function captureExternalFile(
+  store: RewindStore,
+  sessionId: string,
+  path: string,
+): boolean {
+  const absolute = resolveTargetPath(store, path);
+  if (isWorktreeCovered(store, absolute)) return false;
+
+  const meta = readMeta(store);
+  const list = meta.sessions[sessionId];
+  if (!list || list.length === 0) return false;
+  const ordered = [...list].sort((a, b) => a.timestamp - b.timestamp);
+  const newest = ordered[ordered.length - 1];
+  if (newest.files?.some((file) => file.path === absolute)) return false;
+
+  const blob = storeBlob(store, absolute);
+  if (blob === undefined) return false;
+
+  meta.sessions[sessionId] = list.map((cp) =>
+    cp.id === newest.id
+      ? { ...cp, files: [...(cp.files ?? []), { path: absolute, blob }] }
+      : cp,
+  );
+  writeMeta(store, meta);
+  return true;
+}
+
+/**
+ * The restore target for `checkpoints[fromIndex..]` (oldest first): the first
+ * pre-image recorded for each path, so a file edited in several turns resolves
+ * to how it looked before the earliest of them.
+ */
+export function externalRestorePlan(
+  checkpoints: Checkpoint[],
+  fromIndex = 0,
+): ExternalFile[] {
+  const first = new Map<string, ExternalFile>();
+  for (let i = Math.max(0, fromIndex); i < checkpoints.length; i += 1) {
+    for (const file of checkpoints[i].files ?? []) {
+      if (!first.has(file.path)) first.set(file.path, file);
+    }
+  }
+  return [...first.values()];
+}
+
+/** What restoring `records` would change on disk right now. */
+export function diffExternalFiles(
+  store: RewindStore,
+  records: ExternalFile[],
+): CheckpointDiff {
+  const entries: DiffEntry[] = [];
+  for (const record of records) {
+    if (record.blob === null) {
+      // Not in the checkpoint: a restore removes it.
+      if (existsSync(record.path)) entries.push({ status: "A", path: record.path });
+      continue;
+    }
+    if (!existsSync(record.path)) {
+      entries.push({ status: "D", path: record.path });
+      continue;
+    }
+    if (!blobMatches(store, record)) entries.push({ status: "M", path: record.path });
+  }
+  return { entries, empty: entries.length === 0 };
+}
+
+/** Pre-images of how these paths look right now (the undo net for a restore). */
+export function captureFileStates(
+  store: RewindStore,
+  records: ExternalFile[],
+): ExternalFile[] {
+  const captured: ExternalFile[] = [];
+  for (const record of records) {
+    const blob = storeBlob(store, record.path);
+    if (blob === undefined) continue;
+    captured.push({ path: record.path, blob });
+  }
+  return captured;
+}
+
+/**
+ * Put pre-images back on disk: write the blob's bytes, or delete the file when
+ * the checkpoint predates it. Returns the paths that were deleted.
+ */
+export async function restoreExternalFiles(
+  store: RewindStore,
+  records: ExternalFile[],
+): Promise<string[]> {
+  const removed: string[] = [];
+  for (const record of records) {
+    if (record.blob === null) {
+      if (existsSync(record.path)) {
+        rmSync(record.path, { force: true });
+        removed.push(record.path);
+      }
+      continue;
+    }
+    if (blobMatches(store, record)) continue;
+    const content = readFileSync(join(store.filesDir, record.blob));
+    mkdirSync(dirname(record.path), { recursive: true });
+    writeFileSync(record.path, content);
+  }
+  return removed;
+}
+
+/** Drop blobs no checkpoint references any more. */
+export function pruneBlobs(store: RewindStore): number {
+  let names: string[];
+  try {
+    names = readdirSync(store.filesDir);
+  } catch {
+    return 0;
+  }
+
+  const referenced = new Set<string>();
+  const meta = readMeta(store);
+  for (const list of Object.values(meta.sessions)) {
+    for (const checkpoint of list) {
+      for (const file of checkpoint.files ?? []) {
+        if (file.blob) referenced.add(file.blob);
+      }
+    }
+  }
+
+  let removed = 0;
+  for (const name of names) {
+    if (referenced.has(name)) continue;
+    rmSync(join(store.filesDir, name), { force: true });
+    removed += 1;
+  }
+  return removed;
+}
+
+// ---------------------------------------------------------------------------
+// diff / restore
+// ---------------------------------------------------------------------------
+
+/** File-level difference between two checkpoint trees. */
+export async function diffTrees(
+  store: RewindStore,
+  fromTree: string,
+  toTree: string,
+): Promise<CheckpointDiff> {
+  if (fromTree === toTree) return { entries: [], empty: true };
+  const out = await git(store, [
+    "diff-tree",
+    "-r",
+    "--name-status",
+    "--no-commit-id",
+    "-M",
+    fromTree,
+    toTree,
+  ]);
+  if (!out) return { entries: [], empty: true };
+
+  const entries: DiffEntry[] = [];
+  for (const line of out.split("\n")) {
+    if (!line.trim()) continue;
+    const parts = line.split("\t");
+    const status = parts[0] ?? "?";
+    // Renames report "R100\told\tnew"; keep the new path.
+    const path = parts.length >= 3 ? parts[2] : parts[1] ?? "?";
+    entries.push({ status: status.charAt(0), path });
+  }
+  return { entries, empty: entries.length === 0 };
+}
+
+/** Combined file-level difference of two diffs, keeping the first status per path. */
+export function mergeDiffs(first: CheckpointDiff, second: CheckpointDiff): CheckpointDiff {
+  const seen = new Set(first.entries.map((entry) => entry.path));
+  const entries = [
+    ...first.entries,
+    ...second.entries.filter((entry) => !seen.has(entry.path)),
+  ];
+  return { entries, empty: entries.length === 0 };
+}
+
+/** Human-readable one-line summary of a diff, e.g. "3 files: +1 ~1 -1". */
+export function summarizeDiff(diff: CheckpointDiff): string {
+  if (diff.empty) return "no file changes";
+  let added = 0;
+  let modified = 0;
+  let deleted = 0;
+  for (const entry of diff.entries) {
+    if (entry.status === "A") added += 1;
+    else if (entry.status === "D") deleted += 1;
+    else modified += 1;
+  }
+  const bits: string[] = [];
+  if (added) bits.push(`+${added}`);
+  if (modified) bits.push(`~${modified}`);
+  if (deleted) bits.push(`-${deleted}`);
+  return `${diff.entries.length} file${diff.entries.length === 1 ? "" : "s"}: ${bits.join(" ")}`;
+}
+
+export interface RestoreOptions {
+  /** Pre-images to put back after the worktree reset. Defaults to the
+   *  checkpoint's own `files` (right for a safety checkpoint, whose records are
+   *  a snapshot of the state it is meant to restore). A rewind passes the plan
+   *  built by `externalRestorePlan` for the selected point instead. */
+  files?: ExternalFile[];
+}
+
+/**
+ * Restore the working tree to a checkpoint.
+ *
+ * Only the working tree changes: the project's own git index/HEAD are never
+ * touched, and ignored files (node_modules, build output, …) are never deleted
+ * because `git clean` runs without -x.
+ */
+export async function restoreCheckpoint(
+  store: RewindStore,
+  checkpoint: Checkpoint,
+  options: RestoreOptions = {},
+): Promise<RestoreResult> {
+  await git(store, ["read-tree", "--reset", "-u", checkpoint.tree]);
+  const cleanOutput = await git(store, ["clean", "-fd"], { allowFailure: true });
+  const removed: string[] = [];
+  for (const line of cleanOutput.split("\n")) {
+    const match = /^Removing\s+(.*)$/.exec(line.trim());
+    if (match?.[1]) removed.push(match[1]);
+  }
+  removed.push(...(await restoreExternalFiles(store, options.files ?? checkpoint.files ?? [])));
+  return { removed };
+}
+
+// ---------------------------------------------------------------------------
+// pruning
+// ---------------------------------------------------------------------------
+
+/** Drop a checkpoint's ref and metadata row. */
+export async function deleteCheckpoint(
+  store: RewindStore,
+  checkpoint: Checkpoint,
+): Promise<void> {
+  await git(store, ["update-ref", "-d", `${REF_PREFIX}/${checkpoint.id}`], {
+    allowFailure: true,
+  });
+  replaceSessionList(store, checkpoint.sessionId, (list) => list.filter((cp) => cp.id !== checkpoint.id));
+  pruneBlobs(store);
+}
+
+/**
+ * Keep at most `max` prompt/session-start checkpoints per session
+ * (Claude Code's 100). Safety checkpoints are always kept — they are the undo
+ * net for a restore that already happened.
+ */
+export async function pruneSession(
+  store: RewindStore,
+  sessionId: string,
+  max = MAX_CHECKPOINTS_PER_SESSION,
+): Promise<number> {
+  const all = listCheckpoints(store, sessionId);
+  const prunable = all.filter((cp) => cp.kind !== "safety");
+  if (prunable.length <= max) return 0;
+
+  const victims = prunable.slice(0, prunable.length - max);
+  const victimIds = new Set(victims.map((cp) => cp.id));
+  for (const victim of victims) {
+    await git(store, ["update-ref", "-d", `${REF_PREFIX}/${victim.id}`], { allowFailure: true });
+  }
+  replaceSessionList(store, sessionId, (list) => list.filter((cp) => !victimIds.has(cp.id)));
+  pruneBlobs(store);
+  return victims.length;
+}
+
+/**
+ * Retention sweep: drop every session whose newest checkpoint is older than
+ * `days` days, mirroring Claude Code's ~30 day snapshot cleanup.
+ */
+export async function pruneStaleSessions(
+  store: RewindStore,
+  now = Date.now(),
+  days = RETENTION_DAYS,
+): Promise<number> {
+  const meta = readMeta(store);
+  const cutoff = now - days * 24 * 60 * 60 * 1000;
+  let deleted = 0;
+
+  for (const [sessionId, list] of Object.entries(meta.sessions)) {
+    const newest = list.reduce((max, cp) => Math.max(max, cp.timestamp), 0);
+    if (newest >= cutoff) continue;
+    for (const cp of list) {
+      await git(store, ["update-ref", "-d", `${REF_PREFIX}/${cp.id}`], { allowFailure: true });
+      deleted += 1;
+    }
+    delete meta.sessions[sessionId];
+  }
+
+  if (deleted > 0) writeMeta(store, meta);
+  pruneBlobs(store);
+  return deleted;
+}
+
+/** Reclaim objects whose refs were deleted. Best-effort and non-blocking. */
+export function gc(store: RewindStore): Promise<void> {
+  return git(store, ["gc", "--quiet", "--prune=now"], { allowFailure: true }).then(() => undefined);
+}
+
+/** Remove a whole project's shadow repo (used by tests and manual cleanup). */
+export function removeStore(store: RewindStore): void {
+  rmSync(join(store.gitDir, ".."), { recursive: true, force: true });
+}
+
+/** Every project directory under the rewind base dir. */
+export function listProjectDirs(agentDir: string): string[] {
+  const base = rewindBaseDir(agentDir);
+  if (!existsSync(base)) return [];
+  return readdirSync(base, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(base, entry.name));
+}