@thaut/claude-ide 0.0.0-stage → 1.0.0

package/server/subagents.test.ts

@@ -0,0 +1,43 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { listSessionSubagents, subagentMessages, subagentHistoryPage, subagentHistoryMessage } from "./subagents.ts";
+
+test("nested SDK-discovered agents retain metadata, paged history and full message reads (CACHE-006)", async (t) => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "ide-subagents-"));
+  const original = process.env.CLAUDE_CONFIG_DIR;
+  process.env.CLAUDE_CONFIG_DIR = root;
+  t.after(async () => {
+    if (original === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+    else process.env.CLAUDE_CONFIG_DIR = original;
+    await fs.rm(root, { recursive: true, force: true });
+  });
+  const projectPath = "/tmp/ide-nested-agent-fixture";
+  const sessionId = "12345678-1234-1234-1234-123456789abc";
+  const project = path.join(root, "projects", projectPath.replace(/[^a-zA-Z0-9]/g, "-"));
+  const agents = path.join(project, sessionId, "subagents");
+  const nested = path.join(agents, "parent", "children");
+  await fs.mkdir(nested, { recursive: true });
+  await fs.writeFile(path.join(project, `${sessionId}.jsonl`), JSON.stringify({ type: "user", uuid: "main", parentUuid: null, sessionId, cwd: projectPath, message: { role: "user", content: "main" } }) + "\n");
+  const records = Array.from({ length: 110 }, (_, i) => ({ type: "user", uuid: `u${i}`, parentUuid: i ? `u${i - 1}` : null, sessionId, isSidechain: true, message: { role: "user", content: `agent message ${i}` } }));
+  await fs.writeFile(path.join(nested, "agent-child.jsonl"), records.map((r) => JSON.stringify(r)).join("\n") + "\n");
+  const metadata = { toolUseId: "toolu_nested", agentType: "general-purpose", description: "nested task" };
+  await fs.writeFile(path.join(nested, "agent-child.meta.json"), JSON.stringify(metadata));
+  const directReply = { type: "assistant", uuid: "direct-reply", parentUuid: "u0", sessionId, isSidechain: true, message: { role: "assistant", id: "api-reply", model: "saved-agent-model", content: [{ type: "text", text: "done" }] } };
+  await fs.writeFile(path.join(agents, "agent-direct.jsonl"), [records[0], directReply].map((r) => JSON.stringify(r)).join("\n") + "\n");
+  await fs.writeFile(path.join(agents, "agent-direct.meta.json"), JSON.stringify({ toolUseId: "toolu_direct" }));
+
+  const listed = await listSessionSubagents(projectPath, sessionId);
+  assert.deepEqual(listed.find((a) => a.agentId === "child"), { agentId: "child", ...metadata });
+  assert.equal(listed.find((a) => a.agentId === "direct")?.toolUseId, "toolu_direct");
+  const sdk = await subagentMessages(projectPath, sessionId, "child");
+  const latest = await subagentHistoryPage(projectPath, sessionId, "child", {});
+  const older = await subagentHistoryPage(projectPath, sessionId, "child", { cursor: latest.older });
+  assert.deepEqual([...older.items, ...latest.items].map((m) => m.uuid), sdk.map((m) => m.uuid));
+  assert.equal((await subagentHistoryMessage(projectPath, sessionId, "child", "u0")).uuid, "u0");
+  const directHistory = await subagentHistoryPage(projectPath, sessionId, "direct", {});
+  assert.deepEqual(directHistory.items.map((m) => m.uuid), ["u0", "direct-reply"]);
+  assert.equal((directHistory.items[1]?.message as { model?: string }).model, "saved-agent-model", "paged history retains actual response model metadata");
+});

package/server/subagents.ts

@@ -0,0 +1,58 @@
+import fs from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import path from "node:path";
+import { getSubagentMessages, listSubagents } from "@anthropic-ai/claude-agent-sdk";
+import { historyPage, historyMessage, historyReadPath, type PageOptions } from "./history-pages.ts";
+import { sessionFileDir } from "./cli-files.ts";
+
+export type SubagentInfo = { agentId: string; toolUseId?: string; agentType?: string; description?: string };
+
+export async function listSessionSubagents(projectPath: string, sessionId: string): Promise<SubagentInfo[]> {
+  const ids = await listSubagents(sessionId, { dir: projectPath }).catch(() => [] as string[]);
+  return Promise.all(ids.map(async (agentId) => {
+    const metaFile = (await agentFile(projectPath, sessionId, agentId))?.replace(/\.jsonl$/, ".meta.json");
+    try {
+      const meta = JSON.parse(await fs.readFile(metaFile!, "utf8"));
+      return { agentId, toolUseId: meta.toolUseId, agentType: meta.agentType, description: meta.description };
+    } catch {
+      return { agentId };
+    }
+  }));
+}
+
+export async function subagentMessages(projectPath: string, sessionId: string, agentId: string) {
+  if (!/^[a-zA-Z0-9_-]+$/.test(agentId)) throw new Error("bad agent id");
+  return getSubagentMessages(sessionId, agentId, { dir: projectPath });
+}
+
+async function agentFile(projectPath: string, sessionId: string, agentId: string): Promise<string | undefined> {
+  if (!/^[a-zA-Z0-9_-]+$/.test(agentId)) throw new Error("bad agent id");
+  if (!/^[a-fA-F0-9-]{36}$/.test(sessionId)) return undefined;
+  const dir = await sessionFileDir(projectPath, sessionId);
+  if (!dir) return undefined;
+  const name = `agent-${agentId}.jsonl`;
+  // The SDK lists nested transcript directories as well as direct children.
+  async function find(directory: string): Promise<string | undefined> {
+    let children: Dirent[];
+    try { children = await fs.readdir(directory, { withFileTypes: true }); } catch { return undefined; }
+    for (const child of children) {
+      if (child.isFile() && child.name === name) return path.join(directory, child.name);
+      if (child.isDirectory()) {
+        const found = await find(path.join(directory, child.name));
+        if (found) return found;
+      }
+    }
+    return undefined;
+  }
+  return find(path.join(dir, sessionId, "subagents"));
+}
+export async function subagentHistoryPage(projectPath: string, sessionId: string, agentId: string, options: PageOptions) {
+  return historyPage(await agentFile(projectPath, sessionId, agentId), { ...options, sidechain: true });
+}
+export async function subagentHistoryMessage(projectPath: string, sessionId: string, agentId: string, uuid: string) {
+  return historyMessage(await agentFile(projectPath, sessionId, agentId), uuid, undefined, true);
+}
+
+export async function subagentReadPath(projectPath: string, sessionId: string, agentId: string, toolId: string) {
+  return historyReadPath(await agentFile(projectPath, sessionId, agentId), toolId, undefined, true);
+}

package/server/tool-images.test.ts

@@ -0,0 +1,76 @@
+import { after, test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { channelFixture } from "./http-channel-test-fixture.ts";
+
+const fixture = await channelFixture();
+const outside = fs.mkdtempSync(path.join(os.tmpdir(), "ide-read-images-"));
+after(async () => { await fixture.close(); fs.rmSync(outside, { recursive: true, force: true }); });
+const { registerToolImageRoutes } = await import("./tool-images.ts");
+registerToolImageRoutes(fixture.app);
+const png = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==", "base64");
+const dir = path.join(process.env.CLAUDE_CONFIG_DIR!, "projects", fixture.tmp.replace(/[^a-zA-Z0-9]/g, "-"));
+fs.mkdirSync(dir, { recursive: true });
+function transcript(sid: string, calls: { id: string; name?: string; file: string }[], agent?: string) {
+  const records = [
+    { type: "user", uuid: "prompt", parentUuid: null, sessionId: sid, cwd: outside, isSidechain: !!agent, message: { role: "user", content: "read" } },
+    { type: "assistant", uuid: "read-owner", parentUuid: "prompt", sessionId: sid, cwd: outside, isSidechain: !!agent,
+      message: { role: "assistant", id: "api-read", content: calls.map((call) => ({ type: "tool_use", id: call.id, name: call.name ?? "Read", input: { file_path: call.file } })) } },
+  ];
+  const file = agent ? path.join(dir, sid, "subagents", `agent-${agent}.jsonl`) : path.join(dir, `${sid}.jsonl`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, records.map((record) => JSON.stringify(record)).join("\n") + "\n");
+}
+const read = (sid: string, tool: string, query?: Record<string, string>) => fixture.app.request(
+  `/api/projects/${fixture.project.id}/sessions/${sid}/tools/${tool}/image?${new URLSearchParams(query)}`);
+
+test("Read images outside the project are served temporarily from their recorded path and cwd", async () => {
+  const sid = fixture.newSession();
+  const image = path.join(outside, "crop.png");
+  fs.writeFileSync(image, png);
+  transcript(sid, [{ id: "absolute", file: image }, { id: "relative", file: "crop.png" }]);
+  for (const tool of ["absolute", "relative"]) {
+    const response = await read(sid, tool, { path: "/not/a/client/controlled/path.png" });
+    assert.equal(response.status, 200);
+    assert.equal(response.headers.get("content-type"), "image/png");
+    assert.equal(response.headers.get("cache-control"), "no-store");
+    assert.equal(response.headers.get("x-content-type-options"), "nosniff");
+    assert.deepEqual(Buffer.from(await response.arrayBuffer()), png);
+  }
+  fs.unlinkSync(image);
+  assert.equal((await read(sid, "absolute")).status, 404, "deleted temporary images are not retained");
+});
+
+test("image requests stay in the selected Read scope and reject unavailable targets", async () => {
+  const sid = fixture.newSession();
+  fs.writeFileSync(path.join(outside, "valid.png"), png);
+  fs.writeFileSync(path.join(outside, "text.txt"), "not an image");
+  const huge = path.join(outside, "huge.png"), fd = fs.openSync(huge, "w");
+  try { fs.ftruncateSync(fd, 20 * 1024 * 1024 + 1); } finally { fs.closeSync(fd); }
+  fs.mkdirSync(path.join(outside, "directory.png"));
+  transcript(sid, [
+    { id: "read", file: path.join(outside, "valid.png") },
+    { id: "edit", name: "Edit", file: path.join(outside, "valid.png") },
+    { id: "text", file: path.join(outside, "text.txt") },
+    { id: "huge", file: huge }, { id: "dir", file: path.join(outside, "directory.png") },
+  ]);
+  for (const tool of ["edit", "text", "huge", "dir", "unknown"]) assert.equal((await read(sid, tool)).status, 404, tool);
+  fixture.db.prepare("UPDATE session_view SET rewind_anchor='prompt' WHERE session_id=?").run(sid);
+  assert.equal((await read(sid, "read")).status, 404, "discarded calls do not grant access");
+});
+
+test("subagent previews use their own transcript and SVG remains sandboxed", async () => {
+  const sid = fixture.newSession();
+  const svg = path.join(outside, "view.svg");
+  fs.writeFileSync(svg, '<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>');
+  transcript(sid, []);
+  transcript(sid, [{ id: "child-read", file: svg }], "child");
+  assert.equal((await read(sid, "child-read")).status, 404);
+  const response = await read(sid, "child-read", { agent: "child" });
+  assert.equal(response.status, 200);
+  assert.equal(response.headers.get("content-type"), "image/svg+xml");
+  assert.match(response.headers.get("content-security-policy")!, /sandbox/);
+  assert.equal((await read(sid, "child-read", { agent: "../child" })).status, 404);
+});

package/server/tool-images.ts

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { Hono } from "hono";
+import { IMAGE_TYPES } from "./files.ts";
+import { FsHttpError, route } from "./fsutil.ts";
+import { projectPath, sessionReadPath } from "./sessions.ts";
+import { historyCwd } from "./session-dirs.ts";
+import { subagentReadPath } from "./subagents.ts";
+
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+
+/** Best-effort views of existing Read targets. No copies, base64 or durable cache. */
+export function registerToolImageRoutes(app: Hono) {
+  app.get("/api/projects/:pid/sessions/:sid/tools/:tid/image", route(async (c) => {
+    c.header("cache-control", "no-store");
+    const project = projectPath(c.req.param("pid")!);
+    const sid = c.req.param("sid")!, toolId = c.req.param("tid")!, agent = c.req.query("agent");
+    if (agent !== undefined && !/^[a-zA-Z0-9_-]+$/.test(agent)) throw new FsHttpError(404, "图片不存在");
+    const target = agent ? await subagentReadPath(project, sid, agent, toolId) : await sessionReadPath(sid, project, toolId);
+    const file = path.resolve(target.cwd ?? await historyCwd(project, sid), target.path);
+    const mime = IMAGE_TYPES[path.extname(file).toLowerCase()];
+    if (!mime) throw new FsHttpError(404, "图片不存在");
+    let handle: fs.promises.FileHandle | undefined;
+    try {
+      // Non-blocking open also lets us reject named pipes without waiting on a writer.
+      handle = await fs.promises.open(file, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+      const stat = await handle.stat();
+      if (!stat.isFile() || !stat.size || stat.size > MAX_IMAGE_BYTES) throw new FsHttpError(404, "图片不可用");
+      const bytes = Buffer.alloc(stat.size);
+      let offset = 0;
+      while (offset < bytes.length) {
+        const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, offset);
+        if (!bytesRead) throw new FsHttpError(404, "图片不可用");
+        offset += bytesRead;
+      }
+      return new Response(new Uint8Array(bytes), { headers: {
+        "content-type": mime, "content-length": String(bytes.length), "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+        "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; sandbox",
+      } });
+    } catch {
+      throw new FsHttpError(404, "图片不可用");
+    } finally { await handle?.close(); }
+  }));
+}

package/server/turn-changes.ts

@@ -0,0 +1,308 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { Hunk, TurnChanges, TurnChangesInfo, TurnFile, TurnFileDiff, TurnFileStatus } from "../shared/project.ts";
+import { lineDiff } from "../web/src/diff.ts";
+import { claudeDir, forkedFrom, sessionFileDir } from "./cli-files.ts";
+import { sessionCwd } from "./session-dirs.ts";
+import { HttpError } from "./sessions.ts";
+
+/**
+ * Which files each turn changed, from the CLI's own records (see NOTES.md "SDK：fork 与回退"):
+ * - `file-history-snapshot{messageId, snapshot.trackedFileBackups}` is written when a prompt is
+ *   sent: the state of every already-tracked file at the start of that turn.
+ * - `file-history-delta{snapshotMessageId, trackingPath, backup}` is written when a turn touches
+ *   a file for the first time: its state before the edit (`backupFileName: null` = did not exist).
+ * - Backups live in `~/.claude/file-history/<session>/<backupFileName>`.
+ * So a file's content before turn N is its delta in N or its entry in snapshot N, and after
+ * turn N it is its entry in the next turn's snapshot/delta, or the file on disk for the last turn.
+ * Edit/Write/MultiEdit/NotebookEdit calls of the turn add files the checkpoints missed; Bash
+ * and subagent edits are not tracked by the CLI at all.
+ */
+
+const FILE_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+const MAX_BYTES = 1024 * 1024;
+
+type Backup = { backupFileName: string | null; version?: number };
+type Rec = {
+  type?: string;
+  uuid?: string;
+  parentUuid?: string | null;
+  logicalParentUuid?: string | null;
+  isSidechain?: boolean;
+  isMeta?: boolean;
+  isCompactSummary?: boolean;
+  messageId?: string;
+  snapshotMessageId?: string;
+  trackingPath?: string;
+  backup?: Backup;
+  snapshot?: { messageId?: string; trackedFileBackups?: Record<string, Backup> };
+  isSnapshotUpdate?: boolean;
+  message?: { content?: unknown };
+  toolUseResult?: unknown;
+};
+
+type ToolUse = { id: string; name: string; abs: string };
+type ToolOutcome = { isError: boolean; patch?: Hunk[]; created?: string };
+type Turn = { id: string; prompt: string; tools: ToolUse[]; snapshot: Map<string, Backup>; deltas: Map<string, Backup> };
+type Parsed = { cwd: string; sessionIds: string[]; turns: Turn[]; outcomes: Map<string, ToolOutcome> };
+
+async function readRecords(file: string): Promise<Rec[]> {
+  const out: Rec[] = [];
+  for (const line of (await fs.readFile(file, "utf8")).split("\n")) {
+    if (!line) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      // partial line while the CLI is writing
+    }
+  }
+  return out;
+}
+
+function blocks(r: Rec): { type?: string; [k: string]: unknown }[] {
+  const c = r.message?.content;
+  if (typeof c === "string") return [{ type: "text", text: c }];
+  return Array.isArray(c) ? c : [];
+}
+
+/** A user record the transcript shows as a prompt (not a tool result or CLI-internal message). */
+function isPrompt(r: Rec) {
+  if (r.type !== "user" || r.isMeta || r.isCompactSummary || r.isSidechain) return false;
+  return blocks(r).some((b) => b.type === "text" || b.type === "image");
+}
+
+/** The records of the current branch, oldest first (rewinds leave other branches in the file). */
+function currentBranch(recs: Rec[]): Rec[] {
+  const byUuid = new Map<string, Rec>();
+  let leaf: Rec | undefined;
+  for (const r of recs) {
+    if (!r.uuid || r.isSidechain) continue;
+    byUuid.set(r.uuid, r);
+    if (r.type === "user" || r.type === "assistant" || r.type === "system") leaf = r;
+  }
+  const chain: Rec[] = [];
+  const seen = new Set<string>();
+  for (let r = leaf; r && r.uuid && !seen.has(r.uuid); ) {
+    seen.add(r.uuid);
+    chain.push(r);
+    const parent = r.parentUuid ?? r.logicalParentUuid;
+    r = parent ? byUuid.get(parent) : undefined;
+  }
+  return chain.reverse();
+}
+
+async function parse(projectPath: string, sessionId: string): Promise<Parsed> {
+  const dir = await sessionFileDir(projectPath, sessionId);
+  if (!dir) throw new HttpError(404, "会话文件不存在");
+  const cwd = await sessionCwd(projectPath, sessionId);
+  const recs = await readRecords(path.join(dir, `${sessionId}.jsonl`));
+  const abs = (p: string) => (path.isAbsolute(p) ? path.normalize(p) : path.join(cwd, p));
+
+  const snapshots = new Map<string, Map<string, Backup>>();
+  const deltas = new Map<string, Map<string, Backup>>();
+  for (const r of recs) {
+    if (r.type === "file-history-snapshot" && r.messageId) {
+      const cur = (r.isSnapshotUpdate && snapshots.get(r.messageId)) || new Map<string, Backup>();
+      for (const [p, b] of Object.entries(r.snapshot?.trackedFileBackups ?? {})) cur.set(abs(p), b);
+      snapshots.set(r.messageId, cur);
+    } else if (r.type === "file-history-delta" && r.snapshotMessageId && r.trackingPath && r.backup) {
+      const m = deltas.get(r.snapshotMessageId) ?? new Map<string, Backup>();
+      if (!m.has(abs(r.trackingPath))) m.set(abs(r.trackingPath), r.backup);
+      deltas.set(r.snapshotMessageId, m);
+    }
+  }
+
+  const turns: Turn[] = [];
+  const outcomes = new Map<string, ToolOutcome>();
+  let prompt: string | undefined;
+  let cur: Turn | undefined;
+  for (const r of currentBranch(recs)) {
+    if (isPrompt(r)) prompt = r.uuid;
+    if (r.uuid && snapshots.has(r.uuid)) {
+      cur = { id: r.uuid, prompt: prompt ?? r.uuid, tools: [], snapshot: snapshots.get(r.uuid)!, deltas: deltas.get(r.uuid) ?? new Map() };
+      turns.push(cur);
+    }
+    for (const b of blocks(r)) {
+      if (r.type === "assistant" && b.type === "tool_use" && FILE_TOOLS.has(String(b.name)) && cur) {
+        const input = (b.input ?? {}) as { file_path?: unknown; notebook_path?: unknown };
+        const p = typeof input.file_path === "string" ? input.file_path : typeof input.notebook_path === "string" ? input.notebook_path : "";
+        if (p) cur.tools.push({ id: String(b.id), name: String(b.name), abs: abs(p) });
+      } else if (r.type === "user" && b.type === "tool_result") {
+        const tur = r.toolUseResult as { structuredPatch?: Hunk[]; type?: string; content?: string } | undefined;
+        outcomes.set(String(b.tool_use_id), {
+          isError: !!b.is_error,
+          patch: Array.isArray(tur?.structuredPatch) ? tur.structuredPatch : undefined,
+          created: tur?.type === "create" && typeof tur.content === "string" ? tur.content : undefined,
+        });
+      }
+    }
+  }
+  const origin = (await forkedFrom(projectPath, sessionId))?.sessionId;
+  return { cwd, sessionIds: origin ? [sessionId, origin] : [sessionId], turns, outcomes };
+}
+
+type Content = string | null | undefined; // null = absent, undefined = unknown
+
+async function readCapped(file: string): Promise<{ text: string; binary: boolean; truncated: boolean }> {
+  const fh = await fs.open(file, "r");
+  try {
+    const size = (await fh.stat()).size;
+    const buf = Buffer.alloc(Math.min(size, MAX_BYTES));
+    await fh.read(buf, 0, buf.length, 0);
+    const binary = buf.subarray(0, 8000).includes(0);
+    return { text: binary ? "" : buf.toString("utf8"), binary, truncated: size > MAX_BYTES };
+  } finally {
+    await fh.close();
+  }
+}
+
+type Loaded = { content: Content; binary: boolean; truncated: boolean };
+
+async function exists(p: string) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function loadBackup(p: Parsed, b: Backup | undefined): Promise<Loaded> {
+  if (!b) return { content: undefined, binary: false, truncated: false };
+  if (b.backupFileName === null) return { content: null, binary: false, truncated: false };
+  for (const sid of p.sessionIds) {
+    const f = path.join(claudeDir(), "file-history", sid, b.backupFileName);
+    if (await exists(f)) {
+      const r = await readCapped(f);
+      return { content: r.text, binary: r.binary, truncated: r.truncated };
+    }
+  }
+  return { content: undefined, binary: false, truncated: false };
+}
+
+async function loadDisk(file: string): Promise<Loaded> {
+  try {
+    if (!(await fs.stat(file)).isFile()) return { content: null, binary: false, truncated: false };
+    const r = await readCapped(file);
+    return { content: r.text, binary: r.binary, truncated: r.truncated };
+  } catch {
+    return { content: null, binary: false, truncated: false };
+  }
+}
+
+function filesOf(t: Turn): string[] {
+  const set = new Set<string>([...t.deltas.keys(), ...t.tools.map((x) => x.abs)]);
+  const internal = claudeDir() + path.sep;
+  // Plan files and other CLI-internal writes are not project changes.
+  return [...set].filter((f) => !f.startsWith(internal));
+}
+
+/** Content of `file` before turn `i` and after it. */
+async function beforeAfter(p: Parsed, i: number, file: string): Promise<{ before: Loaded; after: Loaded }> {
+  const t = p.turns[i]!;
+  const before = await loadBackup(p, t.deltas.get(file) ?? t.snapshot.get(file));
+  for (let j = i + 1; j < p.turns.length; j++) {
+    const n = p.turns[j]!;
+    const b = n.snapshot.get(file) ?? n.deltas.get(file);
+    if (b) return { before, after: await loadBackup(p, b) };
+  }
+  return { before, after: await loadDisk(file) };
+}
+
+function toolPatches(p: Parsed, t: Turn, file: string): Hunk[] {
+  const out: Hunk[] = [];
+  for (const tu of t.tools) {
+    if (tu.abs !== file) continue;
+    const o = p.outcomes.get(tu.id);
+    if (!o || o.isError) continue;
+    if (o.patch?.length) out.push(...o.patch);
+    else if (o.created !== undefined) out.push({ oldStart: 0, newStart: 1, lines: o.created.split("\n").map((l) => "+" + l) });
+  }
+  return out;
+}
+
+function statusOf(before: Content, after: Content, t: Turn, p: Parsed, file: string): TurnFileStatus {
+  if (before === null && after !== null) return "A";
+  if (after === null && before !== null) return "D";
+  if (before === undefined && t.tools.some((tu) => tu.abs === file && p.outcomes.get(tu.id)?.created !== undefined)) return "A";
+  return "M";
+}
+
+function display(p: Parsed, file: string) {
+  const rel = path.relative(p.cwd, file);
+  return !rel.startsWith("..") && !path.isAbsolute(rel) ? rel.split(path.sep).join("/") : file;
+}
+
+const lineCount = (s: string) => (s === "" ? 0 : s.replace(/\n$/, "").split("\n").length);
+
+function countDiff(before: string, after: string) {
+  if (before === "" || after === "") return { additions: lineCount(after), deletions: lineCount(before) };
+  let additions = 0;
+  let deletions = 0;
+  for (const r of lineDiff(before, after, 0)) {
+    if (r.type === "+") additions++;
+    else if (r.type === "-") deletions++;
+  }
+  return { additions, deletions };
+}
+
+export async function turnChanges(projectPath: string, sessionId: string): Promise<TurnChangesInfo> {
+  let p: Parsed;
+  try {
+    p = await parse(projectPath, sessionId);
+  } catch (err) {
+    if (err instanceof HttpError && err.status === 404) return { turns: [] };
+    throw err;
+  }
+  const turns: TurnChanges[] = [];
+  for (const [i, t] of p.turns.entries()) {
+    const files: TurnFile[] = [];
+    for (const file of filesOf(t)) {
+      const tools = [...new Set(t.tools.filter((x) => x.abs === file && !p.outcomes.get(x.id)?.isError).map((x) => x.name))];
+      const { before, after } = await beforeAfter(p, i, file);
+      const checkpoint = before.content !== undefined && after.content !== undefined;
+      let counts = { additions: 0, deletions: 0 };
+      let unchanged = false;
+      if (checkpoint) {
+        unchanged = before.content === after.content;
+        if (!before.binary && !after.binary) counts = countDiff(before.content ?? "", after.content ?? "");
+      } else {
+        // Only failed calls touched it and nothing was checkpointed: not a change.
+        if (tools.length === 0) continue;
+        for (const h of toolPatches(p, t, file))
+          for (const l of h.lines) {
+            if (l.startsWith("+")) counts.additions++;
+            else if (l.startsWith("-")) counts.deletions++;
+          }
+      }
+      files.push({
+        path: display(p, file),
+        status: statusOf(before.content, after.content, t, p, file),
+        ...counts,
+        tools,
+        checkpoint,
+        ...(unchanged ? { unchanged } : {}),
+      });
+    }
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    if (files.length) turns.push({ id: t.id, prompt: t.prompt, files });
+  }
+  return { turns };
+}
+
+export async function turnFileDiff(projectPath: string, sessionId: string, turnId: string, filePath: string): Promise<TurnFileDiff> {
+  const p = await parse(projectPath, sessionId);
+  const i = p.turns.findIndex((t) => t.id === turnId);
+  if (i === -1) throw new HttpError(404, "找不到这一轮");
+  const t = p.turns[i]!;
+  const file = path.isAbsolute(filePath) ? path.normalize(filePath) : path.join(p.cwd, filePath);
+  // Only files this turn is known to have touched can be read through here.
+  if (!filesOf(t).includes(file)) throw new HttpError(404, "这一轮没有改动这个文件");
+  const { before, after } = await beforeAfter(p, i, file);
+  const status = statusOf(before.content, after.content, t, p, file);
+  if (before.content !== undefined && after.content !== undefined) {
+    if (before.binary || after.binary) return { path: display(p, file), status, binary: true };
+    return { path: display(p, file), status, before: before.content, after: after.content, truncated: before.truncated || after.truncated };
+  }
+  return { path: display(p, file), status, patches: toolPatches(p, t, file) };
+}

package/server/worktree-git.ts

@@ -0,0 +1,87 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+
+/**
+ * `git worktree` plumbing shared by the session list and the worktree routes. Kept free of
+ * session imports so sessions.ts can use it without an import cycle.
+ *
+ * Layout follows the CLI's `--worktree`: `<repo top>/.claude/worktrees/<name>` on branch
+ * `worktree-<name>`. Only worktrees in that directory belong to a project; others (made by hand
+ * elsewhere) are left alone.
+ */
+
+export function git(args: string[], cwd: string): Promise<{ code: number; stdout: string; stderr: string }> {
+  return new Promise((resolve) => {
+    execFile(
+      "git",
+      args,
+      { cwd, encoding: "utf8", maxBuffer: 16 * 1024 * 1024, env: { ...process.env, GIT_TERMINAL_PROMPT: "0", LC_ALL: "C.UTF-8" } },
+      (err, stdout, stderr) => {
+        const code = err ? (typeof (err as { code?: unknown }).code === "number" ? ((err as { code: number }).code) : 1) : 0;
+        resolve({ code, stdout: stdout ?? "", stderr: stderr ?? String(err ?? "") });
+      },
+    );
+  });
+}
+
+export type RepoInfo = { top: string; prefix: string };
+
+/** The checkout the project lives in (top) and the project's subdirectory inside it ("" or "a/b/"). */
+async function pathExists(p: string) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function repoOf(projectPath: string): Promise<RepoInfo | undefined> {
+  if (!(await pathExists(projectPath))) return undefined;
+  const r = await git(["rev-parse", "--show-toplevel", "--show-prefix"], projectPath);
+  if (r.code !== 0) return undefined;
+  const [top = "", prefix = ""] = r.stdout.split("\n");
+  if (prefix) {
+    // A scratch directory ignored by an enclosing repository is not part of it.
+    const ign = await git(["check-ignore", "-q", "--", "."], projectPath);
+    if (ign.code === 0) return undefined;
+  }
+  return { top, prefix };
+}
+
+export type PorcelainWorktree = { path: string; head: string; branch: string | null; locked: boolean; prunable: boolean; bare: boolean };
+
+export function parsePorcelain(out: string): PorcelainWorktree[] {
+  const list: PorcelainWorktree[] = [];
+  for (const block of out.split("\n\n")) {
+    const lines = block.split("\n").filter(Boolean);
+    const wt = lines.find((l) => l.startsWith("worktree "));
+    if (!wt) continue;
+    const branch = lines.find((l) => l.startsWith("branch "))?.slice(7) ?? null;
+    list.push({
+      path: wt.slice(9),
+      head: lines.find((l) => l.startsWith("HEAD "))?.slice(5) ?? "",
+      branch: branch?.replace(/^refs\/heads\//, "") ?? null,
+      locked: lines.some((l) => l === "locked" || l.startsWith("locked ")),
+      prunable: lines.some((l) => l === "prunable" || l.startsWith("prunable ")),
+      bare: lines.includes("bare"),
+    });
+  }
+  return list;
+}
+
+export const worktreesDir = (top: string) => path.join(top, ".claude", "worktrees");
+
+/** The project's worktrees: entries of `git worktree list` under `<top>/.claude/worktrees/`. */
+export async function projectWorktrees(projectPath: string): Promise<{ repo: RepoInfo; worktrees: (PorcelainWorktree & { name: string; cwd: string })[] } | undefined> {
+  const repo = await repoOf(projectPath);
+  if (!repo) return undefined;
+  const r = await git(["worktree", "list", "--porcelain"], projectPath);
+  if (r.code !== 0) return { repo, worktrees: [] };
+  const base = worktreesDir(repo.top) + path.sep;
+  const worktrees = parsePorcelain(r.stdout)
+    .filter((w) => w.path.startsWith(base) && !w.path.slice(base.length).includes(path.sep))
+    .map((w) => ({ ...w, name: w.path.slice(base.length), cwd: repo.prefix ? path.join(w.path, repo.prefix).replace(/\/$/, "") : w.path }));
+  return { repo, worktrees };
+}