rovecode 0.4.0-beta.3 → 0.4.0

package/src/cli/setup.ts

@@ -0,0 +1,187 @@
+/** `rovecode setup` — connect a model in one sitting: pick a provider, name the model, paste the key
+ *  (masked, via auth.ts readSecret), one tiny real call, and the pick becomes the default in
+ *  ~/.rovecode/providers.json. Every step reads through an injectable seam (ask / secret / save /
+ *  probe) so the whole flow is unit-testable with scripted answers and no network. Piped stdin
+ *  (no TTY) prints the three-line recipe and exits 2 — a wizard must not consume a script's input.
+ *  Wording: core/voice.ts rules — rovecode speaks, short lines, every problem ends with "→ next:". */
+
+import { createInterface } from "node:readline";
+import { readSecret, saveCredential } from "../providers/auth.ts";
+import { PROVIDER_ID_RE, inferProtocol, isConfigured } from "../providers/provider-config.ts";
+import type { ProviderRegistry } from "../providers/registry.ts";
+import { next, noModelHint } from "../core/voice.ts";
+
+export interface ProbeResult { ok: boolean; model: string; detail: string }
+
+export interface SetupDeps {
+  registry: ProviderRegistry;
+  /** default console.log */
+  out?: (line: string) => void;
+  /** one plain-text answer (default: readline on stdin, echoed) */
+  ask?: (prompt: string) => Promise<string>;
+  /** one secret (default: readSecret — masked on a TTY) */
+  secret?: (prompt: string) => Promise<string>;
+  /** default auth.ts saveCredential */
+  save?: (id: string, secret: string, keyEnv: string) => void;
+  /** default registry.probe (one tiny real call) */
+  probe?: (id: string, model?: string) => Promise<ProbeResult>;
+  /** default process.stdin.isTTY === true */
+  tty?: boolean;
+}
+
+interface Pick { key: string; label: string; id?: string; local?: boolean; url?: "openai" | "anthropic" }
+
+/** the numbered menu: the common hosted providers, the two local servers, and two "your own URL" doors */
+export const SETUP_PICKS: readonly Pick[] = [
+  { key: "0", id: "rovecode", label: "rovecode — sign in with your account, no key pasting (recommended)" },
+  { key: "1", id: "anthropic", label: "anthropic — Claude models" },
+  { key: "2", id: "openai", label: "openai" },
+  { key: "3", id: "openrouter", label: "openrouter — many models behind one key" },
+  { key: "4", id: "deepseek", label: "deepseek" },
+  { key: "5", id: "groq", label: "groq" },
+  { key: "6", id: "ollama", label: "ollama — local, no key needed", local: true },
+  { key: "7", id: "lmstudio", label: "lmstudio — local, no key needed", local: true },
+  { key: "8", label: "another OpenAI-compatible URL (a proxy, vLLM, …)", url: "openai" },
+  { key: "9", label: "another Anthropic-protocol URL", url: "anthropic" },
+];
+
+export const SETUP_DONE = 'Done. Try:  rovecode "explain this repo"';
+
+/** one echoed line from the terminal — shared with main.ts's numbered model picker */
+export function askLine(prompt: string): Promise<string> {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let settled = false;
+    rl.question(prompt, (a) => { if (settled) return; settled = true; rl.close(); resolve(a.trim()); });
+    rl.once("close", () => { if (!settled) { settled = true; resolve(""); } });
+  });
+}
+
+/** exit code: 0 connected (or added with a clear next step), 2 not a TTY / cancelled / invalid input */
+export async function runSetup(deps: SetupDeps): Promise<number> {
+  const out = deps.out ?? console.log;
+  const ask = deps.ask ?? askLine;
+  const secret = deps.secret ?? ((p: string) => readSecret(p));
+  const save = deps.save ?? saveCredential;
+  const reg = deps.registry;
+  const probe = deps.probe ?? ((id: string, model?: string) => reg.probe(id, model));
+  const tty = deps.tty ?? process.stdin.isTTY === true;
+
+  if (!tty) { out(noModelHint("cli")); out("  (rovecode setup needs a terminal — this stdin is a pipe)"); return 2; }
+
+  out("◆ rovecode setup — let's connect a model. Two or three questions.");
+  out("");
+  for (const p of SETUP_PICKS) out(`  ${p.key}  ${p.label}`);
+  out("");
+  let pick: Pick | undefined;
+  for (let tries = 0; tries < 3 && pick === undefined; tries++) {
+    const a = (await ask("Which one? [0-9, empty = cancel]: ")).trim();
+    if (a.length === 0) { out(`cancelled — nothing changed. ${next("rovecode setup")} whenever you like`); return 2; }
+    pick = SETUP_PICKS.find((p) => p.key === a || p.id === a);
+    if (pick === undefined) out(`  "${a}" is not on the list — a number from 0 to 9, please.`);
+  }
+  if (pick === undefined) return 2;
+
+  // ---- rovecode account: device login does everything — key, provider, default model ----
+  if (pick.id === "rovecode") {
+    const { runDeviceLogin } = await import("../account/login.ts");
+    const { ensureRovecodeProvider, ROVECODE_DEFAULT_MODEL } = await import("../account/provision.ts");
+    out("◆ signing you in — approve in the browser that opens.");
+    const result = await runDeviceLogin({
+      apiBase: process.env.ROVECODE_AUTH_API ?? "https://www.rovecode.dev",
+      onCode: ({ userCode, verificationUri, expiresIn }) => {
+        out("");
+        out(`  your code:  ${userCode}`);
+        out(`  open:       ${verificationUri}`);
+        out(`  expires in about ${Math.max(1, Math.round(expiresIn / 60))} min — waiting for approval…`);
+        out("");
+      },
+    });
+    if (!result.ok) { out(`  sign-in failed (${result.reason}). ${next("rovecode login")} or pick another provider`); return 2; }
+    out(`◆ linked ${result.account.email || "your account"}.`);
+    if (!result.account.apiKey) { out(`  the site didn't mint a key this time. ${next("rovecode setup")} and pick another door, or re-run rovecode login`); return 2; }
+    const pv = ensureRovecodeProvider(result.account.apiKey);
+    if (pv.error !== undefined) { out(`  provider setup failed: ${pv.error}. ${next("rovecode provider add rovecode https://api.rovecode.dev/v1")}`); return 2; }
+    out(`◆ rovecode provider ready (key stored hidden, ~/.rovecode/credentials.json).`);
+    out(`◆ testing rovecode/${ROVECODE_DEFAULT_MODEL} …`);
+    const r = await probe("rovecode", ROVECODE_DEFAULT_MODEL);
+    if (r.ok) out(`  ${r.detail}`);
+    else out(`  probe failed: ${r.detail} — the key is stored; ${next("rovecode provider test rovecode " + ROVECODE_DEFAULT_MODEL)}`);
+    if (pv.defaulted) out(`◆ default → rovecode/${ROVECODE_DEFAULT_MODEL}.`);
+    else out(`◆ kept your existing default model — switch anytime: rovecode model use rovecode/${ROVECODE_DEFAULT_MODEL}`);
+    out("");
+    out(SETUP_DONE);
+    out("  or open the cockpit:  rovecode");
+    return 0;
+  }
+
+  // ---- the provider: a built-in, a keyless local server, or a URL of your own ----
+  let id: string;
+  if (pick.url !== undefined) {
+    id = (await ask("Short name for it (letters, digits, - _ .): ")).trim().toLowerCase();
+    if (!PROVIDER_ID_RE.test(id)) { out(`  "${id}" won't work as an id. ${next("rovecode setup, and pick a name like myproxy")}`); return 2; }
+    const baseUrl = (await ask("Base URL (e.g. https://host/v1): ")).trim();
+    if (!/^https?:\/\//.test(baseUrl)) { out(`  "${baseUrl}" is not an http(s) URL. ${next("rovecode setup")}`); return 2; }
+    const protocol = pick.url === "anthropic" ? "anthropic" : baseUrl.includes("anthropic.com") ? inferProtocol(baseUrl) : "openai";
+    const noKey = (await ask("Does it need an API key? [Y/n]: ")).trim().toLowerCase().startsWith("n");
+    const r = reg.add({ id, baseUrl, protocol, ...(noKey ? { noKey: true } : {}) }, "user");
+    if ("error" in r) { out(`  ${r.error}. ${next("rovecode setup")}`); return 2; }
+    out(`◆ ${id} registered (${protocol} protocol, ${baseUrl}).`);
+  } else {
+    id = pick.id!;
+    const known = reg.get(id);
+    if (known === undefined) { out(`  ${id} is missing from the built-in table — that is a bug. ${next("rovecode provider add " + id + " <baseUrl>")}`); return 2; }
+    if (pick.local === true && known.noKey !== true) {
+      // the built-in row expects a key env; a local server needs none — the user entry says so
+      const r = reg.add({ id, baseUrl: known.baseUrl, protocol: known.protocol, noKey: true, ...(known.defaultModel !== undefined ? { defaultModel: known.defaultModel } : {}) }, "user");
+      if ("error" in r) { out(`  ${r.error}. ${next("rovecode setup")}`); return 2; }
+      out(`◆ ${id} marked as a local server (${known.baseUrl}, no key).`);
+    }
+  }
+
+  // ---- the model ----
+  const spec = reg.get(id)!;
+  const suggested = spec.defaultModel;
+  const modelAnswer = (await ask(suggested !== undefined ? `Model id [${suggested}]: ` : "Model id (empty = choose later with rovecode model list): ")).trim();
+  const model = modelAnswer.length > 0 ? modelAnswer : suggested;
+
+  // ---- the key ----
+  let hasKey = isConfigured(spec);
+  if (!hasKey) {
+    const s = await secret(`${spec.keyEnv} (hidden): `);
+    if (s.trim().length === 0) {
+      out(`◆ no key stored — I can't call ${id} without one.`);
+      out(`  ${next(`rovecode auth set ${id}`)}   (or set ${spec.keyEnv} in your environment)`);
+    } else {
+      save(id, s.trim(), spec.keyEnv);
+      reg.refresh();
+      hasKey = true;
+      out(`◆ key stored for ${id} (hidden; ~/.rovecode/credentials.json).`);
+    }
+  } else out(`◆ ${id} already has a key (${spec.keySource === "stored" ? "stored" : `env ${spec.keyEnv}`}).`);
+
+  // ---- one tiny real call ----
+  if (hasKey && model !== undefined) {
+    out(`◆ testing ${id}/${model} …`);
+    const r = await probe(id, model);
+    if (r.ok) out(`  ${r.detail}`);
+    else {
+      out(`  that didn't work: ${r.detail}`);
+      out(`  ${next(`check the key and the URL, then rovecode provider test ${id} ${model}`)}`);
+    }
+  }
+
+  // ---- make it the default ----
+  if (model !== undefined) {
+    const d = reg.setDefault(`${id}/${model}`, "user");
+    if ("error" in d) { out(`  ${d.error}. ${next(`rovecode model use ${id}/<model>`)}`); return 2; }
+    out(`◆ default → ${d.provider}/${d.model} (~/.rovecode/providers.json; running TUIs switch live).`);
+  } else {
+    out(`◆ ${id} is set up but has no model yet.`);
+    out(`  ${next(`rovecode model list ${id}, then rovecode model use ${id}/<model>`)}`);
+  }
+  out("");
+  out(SETUP_DONE);
+  out("  or open the cockpit:  rovecode");
+  return 0;
+}

package/src/cli/update-cmd.ts

@@ -0,0 +1,78 @@
+/** `rovecode update [--check] [--channel beta|latest|auto]` — and the flow the TUI's /update and
+ *  the autoUpdate boot hook share. The brain is core/update.ts (detect → plan → run); this file is
+ *  the surface: spawn glue, the words on the terminal, the exit code.
+ *
+ *  Rules: never swap the running process (on Windows the files under a live bun are being replaced;
+ *  the honest promise is "restart to run it"), never move between channels silently (a beta stays
+ *  on beta unless --channel says otherwise), and a binary install gets the release page URL rather
+ *  than a half-done self-swap. */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { channelFor, detectInstallMode, planUpdate, runUpdate, type DetectedInstall, type UpdateChannel } from "../core/update.ts";
+import { checkForUpdate, updateLine } from "../core/update-check.ts";
+
+const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+
+async function spawnCmd(cmd: string[], cwd?: string): Promise<{ code: number; out: string }> {
+  const argv = cmd[0] === "npm" ? [npmCmd, ...cmd.slice(1)] : cmd;
+  const p = Bun.spawn(argv, { cwd, stdout: "pipe", stderr: "pipe" });
+  const [o, e] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()]);
+  const code = await p.exited;
+  return { code, out: o + e };
+}
+
+async function npmGlobalPrefix(): Promise<string | undefined> {
+  try {
+    const p = Bun.spawn([npmCmd, "prefix", "-g"], { stdout: "pipe", stderr: "ignore" });
+    const t = (await new Response(p.stdout).text()).trim();
+    await p.exited;
+    return t.length > 0 ? t : undefined;
+  } catch { return undefined; }
+}
+
+export interface UpdateFlowOpts {
+  version: string;
+  /** the running entry module's path (import.meta.path of the CLI entry) */
+  entry: string;
+  /** every line the flow wants the surface to show (CLI: stdout; TUI: notes) */
+  log(line: string): void;
+  /** unit-test seam: replace the spawners */
+  deps?: { spawn?: typeof spawnCmd; prefix?: typeof npmGlobalPrefix; install?: DetectedInstall };
+}
+
+/** The whole job: check → detect → plan → run. Returns the process exit code (0 = fine or already
+ *  current, 1 = an update was wanted and did not land, 2 = bad flags). */
+export async function updateFlow(words: string[], opts: UpdateFlowOpts): Promise<number> {
+  const checkOnly = words.includes("--check");
+  const chanWord = words.includes("--channel") ? words[words.indexOf("--channel") + 1] : "auto";
+  if (chanWord !== "auto" && chanWord !== "beta" && chanWord !== "latest") {
+    opts.log("error: --channel must be beta, latest or auto");
+    return 2;
+  }
+  const status = await checkForUpdate(opts.version, checkOnly ? { cacheOnly: true } : {});
+  if (checkOnly) { opts.log(updateLine(status, true) ?? `up to date (${opts.version})`); return 0; }
+  if (!status.newer) {
+    opts.log(status.latest === undefined
+      ? `no newer release is known (${updateLine(status, true) ?? `current: ${opts.version}`})`
+      : `up to date (${opts.version})`);
+    return 0;
+  }
+  const install = opts.deps?.install ?? detectInstallMode({ entry: opts.entry });
+  const distBuilt = install.mode === "source" && install.root !== undefined && existsSync(join(install.root, "dist", "cli", "main.js"));
+  const plan = planUpdate(install, { currentVersion: opts.version, channel: chanWord as UpdateChannel | "auto", distBuilt });
+  opts.log(`update available: ${opts.version} → ${status.latest} · this copy is a ${install.mode} install · channel ${plan.channel} (${channelFor(opts.version, chanWord as UpdateChannel | "auto")} follows the running version)`);
+  if (plan.commands.length === 0) { opts.log(plan.manual ?? "nothing to run"); return 1; }
+  const r = await runUpdate(plan, install, {
+    spawn: opts.deps?.spawn ?? spawnCmd,
+    npmGlobalPrefix: opts.deps?.prefix ?? npmGlobalPrefix,
+    log: opts.log,
+  });
+  opts.log(r.ok ? r.detail : `update failed: ${r.detail}`);
+  return r.ok ? 0 : 1;
+}
+
+/** the CLI surface: `rovecode update …` */
+export async function cmdUpdate(words: string[], version: string, entry: string): Promise<number> {
+  return updateFlow(words, { version, entry, log: (l) => console.log(l) });
+}

package/src/cli/workflow-cmd.ts

@@ -0,0 +1,100 @@
+/** `rovecode workflow run <file.ts> [--resume <runId>] [--json]` (F3, sdk-blueprint.md §4).
+ *
+ *  The file's default export is a WorkflowSpec (defineWorkflow). Steps ride the runtime's
+ *  TaskManager, so every running step appears on the Mission Control agent tree (/ui,
+ *  GET /events) while the workflow runs. Gates ask on the TTY; off a TTY a gate REJECTS
+ *  (a headless workflow must be gate-free — asking nobody would hang forever). */
+
+import { join, resolve } from "node:path";
+import { defineWorkflow, listWorkflowRuns, runWorkflow, type WorkflowExecutor, type WorkflowSpec } from "../workflow/engine.ts";
+import { askLine } from "./setup.ts";
+
+export async function cmdWorkflow(words: string[]): Promise<number> {
+  const [action, ...rest] = words;
+  const cwd = process.cwd();
+  const dir = join(cwd, ".rovecode", "workflows");
+
+  if (action === "list") {
+    const runs = listWorkflowRuns(dir);
+    if (process.argv.includes("--json")) { console.log(JSON.stringify({ runs }, null, 2)); return 0; }
+    if (runs.length === 0) { console.log(`no workflow runs in ${dir}`); return 0; }
+    for (const r of runs) console.log(`${r.runId}  done: ${r.done.length > 0 ? r.done.join(", ") : "(none)"}`);
+    return 0;
+  }
+
+  if (action !== "run" || rest[0] === undefined) {
+    console.error("usage: rovecode workflow run <file.ts> [--resume <runId>] [--json] | rovecode workflow list");
+    return 2;
+  }
+
+  const file = resolve(cwd, rest[0]);
+  let spec: WorkflowSpec;
+  try {
+    const mod = (await import(file)) as { default?: WorkflowSpec };
+    if (!mod.default) throw new Error("the file must `export default defineWorkflow({…})`");
+    spec = defineWorkflow(mod.default);
+  } catch (e) {
+    console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
+    return 2;
+  }
+
+  const resumeIdx = process.argv.indexOf("--resume");
+  const resumeId = resumeIdx !== -1 ? process.argv[resumeIdx + 1] : undefined;
+  const asJson = process.argv.includes("--json");
+
+  const { bootRuntime } = await import("./runtime.ts");
+  const rt = await bootRuntime();
+  const exit = async (code: number): Promise<never> => {
+    rt.tasks.cancelAll();
+    await rt.tasks.drain(2_000);
+    await rt.hooks.close();
+    await rt.mcp?.close().catch(() => {});
+    // cmdRun's lesson: runtime keeps the event loop alive (watchers, MCP); return
+    // the code and the process never exits. One-shot commands end the process.
+    return process.exit(code);
+  };
+  const why = rt.noProviderReason();
+  if (why !== null && process.env.ROVECODE_MOCK !== "1") { console.error(`error: ${why}`); return exit(2); }
+
+  const tty = process.stdin.isTTY === true;
+  const exec: WorkflowExecutor = {
+    runAgent: async (step) => {
+      const start = rt.tasks.start(
+        { agent: step.agent ?? "main", goal: step.goal },
+        { label: `${spec.name}/${step.name}` },
+      );
+      if (!start.ok) return { ok: false, summary: start.reason };
+      const info = await rt.tasks.result(start.id);
+      if (!info) return { ok: false, summary: "task vanished" };
+      return {
+        ok: info.status === "done",
+        summary: info.summary ?? info.error ?? info.status,
+        ...(info.usage !== undefined ? { usage: info.usage } : {}),
+      };
+    },
+    askGate: async (prompt) => {
+      if (!tty) { console.error(`gate '${prompt}': no TTY — rejected (run workflows with gates interactively)`); return false; }
+      const a = (await askLine(`gate [${spec.name}]: ${prompt} [y/N] `)).trim().toLowerCase();
+      return a === "y" || a === "yes";
+    },
+    cancelAgent: () => { rt.tasks.cancelAll(); },
+  };
+
+  const emit = (e: { type: string } & Record<string, unknown>): void => {
+    if (asJson) { console.log(JSON.stringify(e)); return; }
+    if (e.type === "workflow_started") console.log(`workflow ${e.name} (${e.runId}) — ${e.steps} steps`);
+    else if (e.type === "step_started") console.log(`  ▸ ${e.step} (attempt ${e.attempt})`);
+    else if (e.type === "step_done") console.log(`  ✓ ${e.step} — ${String(e.summary ?? "").slice(0, 120)}`);
+    else if (e.type === "step_failed") console.error(`  ✗ ${e.step} — ${String(e.error ?? "").slice(0, 120)}`);
+    else if (e.type === "gate_waiting") { /* askGate prints the prompt */ }
+    else if (e.type === "workflow_done") console.log(`workflow ${e.status} (${e.runId})`);
+  };
+
+  const result = await runWorkflow(spec, exec, {
+    dir,
+    emit,
+    ...(resumeId !== undefined ? { runId: resumeId } : {}),
+  });
+  if (asJson) console.log(JSON.stringify({ runId: result.runId, status: result.status, steps: result.steps, usage: result.usage }, null, 2));
+  return exit(result.status === "done" ? 0 : 1);
+}

package/src/coding/checkpoints.ts

@@ -0,0 +1,270 @@
+/** 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, 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("-")) ?? ""): 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).
+  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];
+  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;
+}
+
+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);
+    // dot-only ids ("."/"..") survive the charwise filter but escape or collapse the
+    // shadow root under join() — fold them (and "") to underscores
+    const cleaned = opts.sessionId.replace(/[^A-Za-z0-9._-]/g, "_");
+    const session = /^\.*$/.test(cleaned) ? cleaned.replace(/\./g, "_") || "_" : cleaned;
+    const shadowDir = join(opts.shadowRoot ?? join(workspace, ".rovecode", "checkpoints"), session);
+    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]; }
+
+  /** 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 } : {}),
+    };
+  }
+}