Merge pull request #693: feat: edit history panel for local claude sessions (files edited, diffs, generated images)

src/edit-history-local-source.ts

@@ -0,0 +1,242 @@
+/**
+ * @fileoverview Reads a local claude session's transcripts for its edit history: the main
+ * transcript and its subagent transcripts, each from a byte offset.
+ *
+ * WHICH FILE (`resolveClaudeTranscript`). The transcript watcher's path, which the session's
+ * hooks report, so a session is read from wherever its claude really writes. Before the first
+ * hook after a server restart the watcher has none, and `findClaudeTranscript` looks for
+ * `<id>.jsonl` under the session's own `CLAUDE_CONFIG_DIR` override, else the server's
+ * (`claudeProjectsDir()`, as the relaunch pin does). A config dir set outside Codeman is not
+ * guessed; it is found with the next hook. Subagents live in
+ * `<main path without .jsonl>/subagents/agent-<id>.jsonl`.
+ *
+ * HOW MUCH. A requested file is read from its `offset` (clamped to its size), an unrequested
+ * (new) one from `budget` bytes before its end, and a new subagent's `.meta.json` (≤ 8 KB)
+ * comes along. `budgetBytes` is shared by all files, main first; once spent, files still
+ * report their size with an empty chunk. A request with `len` is a block that must end at
+ * `offset + len` (an "older" block ends at the floor): short of budget, its end is read.
+ * With `onlyRequested` ("older" reads) unrequested files are left out.
+ *
+ * Tests: `test/edit-history-local-source.test.ts`.
+ *
+ * @module edit-history-local-source
+ */
+
+import { open, readdir, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, isAbsolute, join } from 'node:path';
+import { probePathKind, type PathProbeKind } from './utils/bounded-path-probe.js';
+import { claudeProjectsDir } from './utils/claude-transcript.js';
+
+const ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+const REL_PATH_PATTERN = /^(main|subagents\/agent-[A-Za-z0-9_-]+\.jsonl)$/;
+const AGENT_FILE_PATTERN = /^agent-([A-Za-z0-9_-]+)\.jsonl$/;
+const META_MAX_BYTES = 8192;
+
+/** One file to read from where the last read stopped (`len` only for an "older" block). */
+export interface EditSourceRequest {
+  /** `main` or `subagents/agent-<id>.jsonl`. */
+  relPath: string;
+  offset: number;
+  len?: number;
+}
+
+export interface EditSourceFile {
+  relPath: string;
+  /** The file's size when it was read. */
+  size: number;
+  startOffset: number;
+  chunk: Buffer;
+}
+
+export interface EditSources {
+  /** The conversation id: the main transcript's file name without `.jsonl`. */
+  transcriptId: string;
+  files: EditSourceFile[];
+  /** `agent-<id>.meta.json` text of each subagent read for the first time, by agent id. */
+  metas: Record<string, string>;
+}
+
+export interface EditSourceReadOptions {
+  /** Read only the requested files; the others are not listed. */
+  onlyRequested?: boolean;
+}
+
+/** What a path turned out to be (for Bash image candidates). */
+export interface PathProbe {
+  /** The path with symlinks resolved. */
+  realPath: string;
+  kind: 'file' | 'directory' | 'other';
+  /** Size in bytes (0 for anything that is not a regular file). */
+  size: number;
+  mtimeMs: number;
+}
+
+async function readRange(path: string, offset: number, len: number): Promise<Buffer> {
+  if (len <= 0) return Buffer.alloc(0);
+  const fh = await open(path, 'r');
+  try {
+    const buf = Buffer.alloc(len);
+    const { bytesRead } = await fh.read(buf, 0, len, offset);
+    return buf.subarray(0, bytesRead);
+  } catch {
+    return Buffer.alloc(0);
+  } finally {
+    await fh.close();
+  }
+}
+
+async function fileSize(path: string): Promise<number | null> {
+  try {
+    const s = await stat(path);
+    return s.isFile() ? s.size : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The newest `<id>.jsonl` under any project dir, for the first id that has one; null when none does. */
+export async function findClaudeTranscript(
+  ids: readonly string[],
+  projectsDir: string = claudeProjectsDir()
+): Promise<string | null> {
+  let dirs: string[];
+  try {
+    dirs = await readdir(projectsDir);
+  } catch {
+    return null;
+  }
+  for (const id of new Set(ids)) {
+    if (!ID_PATTERN.test(id)) continue;
+    let best: { path: string; mtime: number } | null = null;
+    for (const dir of dirs) {
+      const path = join(projectsDir, dir, `${id}.jsonl`);
+      try {
+        const s = await stat(path);
+        if (s.isFile() && (!best || s.mtimeMs > best.mtime)) best = { path, mtime: s.mtimeMs };
+      } catch {
+        // not in this project dir
+      }
+    }
+    if (best) return best.path;
+  }
+  return null;
+}
+
+/**
+ * The session's main transcript: the transcript watcher's (hook-reported) path when there is
+ * one, else the newest `<id>.jsonl` under `configDir` (the session's `CLAUDE_CONFIG_DIR`
+ * override; the server's config dir when unset). Null when neither finds one.
+ */
+export async function resolveClaudeTranscript(
+  watcherPath: string | null | undefined,
+  ids: readonly string[],
+  configDir?: string
+): Promise<string | null> {
+  return watcherPath || findClaudeTranscript(ids, claudeProjectsDir(configDir));
+}
+
+/**
+ * Read the main transcript at `mainPath` and its subagent transcripts. Null when `mainPath`
+ * is not an absolute `<id>.jsonl` path or the file does not exist.
+ */
+export async function readClaudeEditSources(
+  mainPath: string,
+  requests: readonly EditSourceRequest[],
+  budgetBytes: number,
+  opts: EditSourceReadOptions = {}
+): Promise<EditSources | null> {
+  if (!isAbsolute(mainPath) || !mainPath.endsWith('.jsonl')) return null;
+  const transcriptId = basename(mainPath, '.jsonl');
+  if (!ID_PATTERN.test(transcriptId)) return null;
+
+  const byPath = new Map<string, EditSourceRequest>();
+  for (const r of requests) {
+    if (!REL_PATH_PATTERN.test(r.relPath) || byPath.has(r.relPath)) continue;
+    if (!Number.isSafeInteger(r.offset) || r.offset < 0) continue;
+    if (r.len !== undefined && (!Number.isSafeInteger(r.len) || r.len < 0)) continue;
+    byPath.set(r.relPath, r);
+  }
+
+  const subDir = join(mainPath.slice(0, -'.jsonl'.length), 'subagents');
+  const sources: Array<{ relPath: string; path: string; agentId?: string }> = [{ relPath: 'main', path: mainPath }];
+  try {
+    for (const name of (await readdir(subDir)).sort()) {
+      const m = AGENT_FILE_PATTERN.exec(name);
+      if (m) sources.push({ relPath: `subagents/${name}`, path: join(subDir, name), agentId: m[1] });
+    }
+  } catch {
+    // no subagents yet
+  }
+
+  let remaining = Math.max(0, Math.floor(budgetBytes));
+  const files: EditSourceFile[] = [];
+  const metas: Record<string, string> = {};
+  for (const src of sources) {
+    const size = await fileSize(src.path);
+    if (size === null) {
+      if (src.relPath === 'main') return null;
+      continue;
+    }
+    const req = byPath.get(src.relPath);
+    if (!req && opts.onlyRequested) continue;
+    let start: number;
+    let len: number;
+    if (req?.len !== undefined) {
+      const blockStart = Math.min(req.offset, size);
+      const blockEnd = Math.min(req.offset + req.len, size);
+      len = Math.min(blockEnd - blockStart, remaining);
+      start = blockEnd - len;
+    } else if (req) {
+      start = Math.min(req.offset, size);
+      len = Math.min(remaining, size - start);
+    } else {
+      len = Math.min(size, remaining);
+      start = size - len;
+    }
+    const chunk = await readRange(src.path, start, len);
+    remaining -= chunk.length;
+    files.push({ relPath: src.relPath, size, startOffset: start, chunk });
+    if (!req && src.agentId) {
+      const metaPath = join(subDir, `agent-${src.agentId}.meta.json`);
+      const metaSize = await fileSize(metaPath);
+      if (metaSize !== null) {
+        metas[src.agentId] = (await readRange(metaPath, 0, Math.min(metaSize, META_MAX_BYTES))).toString('utf8');
+      }
+    }
+  }
+  return { transcriptId, files, metas };
+}
+
+/**
+ * Per path its resolved path, kind, size and mtime, or null when it is not a regular file
+ * (missing, a directory, or on a filesystem that did not answer). `~/` means this user's home.
+ *
+ * The paths come from Bash output, so the agent chose them: each one first goes through the
+ * bounded probe (`probePathKind`, no `pastCap`, this is a bulk scan), and only a path it saw
+ * as a file is touched by `realpath` + `stat`. A path on a mount that stopped answering
+ * then costs one stalled stat at most, never a sync that cannot finish (#516 rule).
+ * Sequential, so one sync holds at most one threadpool worker.
+ */
+export async function probeLocalPaths(
+  paths: readonly string[],
+  home: string = homedir(),
+  probeKind: (path: string) => Promise<PathProbeKind> = probePathKind
+): Promise<Array<PathProbe | null>> {
+  const out: Array<PathProbe | null> = [];
+  for (const p of paths) {
+    const path = p.startsWith('~/') ? join(home, p.slice(2)) : p;
+    if (!isAbsolute(path) || (await probeKind(path)) !== 'file') {
+      out.push(null);
+      continue;
+    }
+    try {
+      const real = await realpath(path);
+      const s = await stat(real);
+      out.push(s.isFile() ? { realPath: real, kind: 'file', size: s.size, mtimeMs: Math.floor(s.mtimeMs) } : null);
+    } catch {
+      out.push(null);
+    }
+  }
+  return out;
+}

src/edit-history-parse.ts

@@ -0,0 +1,352 @@
+/**
+ * @fileoverview Edit history parser: claude JSONL transcript lines → the files the agent
+ * edited (with their diff) and the images its Bash calls may have produced.
+ *
+ * Every `Edit`/`Write` result line carries `toolUseResult.filePath` and a
+ * `structuredPatch` (hunks with ` `/`+`/`-` prefixed lines), so a per-edit diff needs no
+ * git. The whole-file fields next to it (`originalFile`, `content`) are never kept.
+ *
+ * Images rarely come from `Write`; they come from scripts run through Bash. A Bash call
+ * yields a CANDIDATE: the image-looking paths in its command and output, with the call's
+ * start and end time. Whether a candidate file was actually produced by the call (its
+ * mtime falls inside that window) is decided later by whoever can stat it, locally or on
+ * the remote host — this module does no IO.
+ *
+ * Chunked input: a transcript is read in byte ranges, so a Bash `tool_use` and its result
+ * can land in different chunks. Unanswered calls are handed back as `pending` and passed
+ * into the next call.
+ *
+ * Tests: `test/edit-history-parse.test.ts`.
+ *
+ * @module edit-history-parse
+ */
+
+import { posix } from 'node:path';
+
+/** Per-record budget for kept hunk lines; a larger patch is cut and marked `truncated`. */
+export const MAX_HUNK_BYTES = 64 * 1024;
+/** Image paths kept per Bash call. */
+export const MAX_IMAGE_CANDIDATES = 20;
+/** Unanswered Bash calls carried between chunks (an interrupted call never gets a result). */
+export const MAX_PENDING_BASH = 200;
+/**
+ * Command text kept per unanswered Bash call. Pending calls are persisted with the store, so
+ * this bounds it; an image path past this point of a command is still found in the output.
+ */
+export const MAX_PENDING_COMMAND_CHARS = 8192;
+/** Longest id, cwd or agent id of an unanswered Bash call; a call with a longer one is not kept. */
+export const MAX_PENDING_FIELD_CHARS = 4096;
+
+export type EditKind = 'code' | 'image';
+/** `edit` = a result with a path and a patch from a tool other than Edit/Write. */
+export type EditTool = 'Edit' | 'Write' | 'edit';
+
+export interface EditHunk {
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  lines: string[];
+}
+
+export interface EditRecord {
+  /** The `tool_use_id` of the edit — unique per edit, used to deduplicate. */
+  id: string;
+  /** ms since epoch, from the result line's `timestamp` (0 when missing). */
+  ts: number;
+  path: string;
+  kind: EditKind;
+  tool: EditTool;
+  /** A `Write` that created the file. */
+  created: boolean;
+  /** Counted over the whole patch, also when `hunks` was cut. */
+  added: number;
+  removed: number;
+  hunks: EditHunk[];
+  truncated: boolean;
+  /** Set for lines of a subagent transcript. */
+  agentId?: string;
+}
+
+export interface PendingBash {
+  id: string;
+  ts: number;
+  command: string;
+  cwd: string;
+  agentId?: string;
+}
+
+export interface ImageCandidate {
+  toolUseId: string;
+  start: number;
+  end: number;
+  paths: string[];
+  agentId?: string;
+  /**
+   * Files claude handed to the user (`SendUserFile`): shown on purpose, so no mtime window
+   * applies; the file must still exist, and a version already listed is not listed again.
+   */
+  sent?: boolean;
+}
+
+export interface EditParseResult {
+  records: EditRecord[];
+  candidates: ImageCandidate[];
+  pending: PendingBash[];
+}
+
+const IMAGE_EXT = '(?:png|jpe?g|gif|webp|avif|svg)';
+const IMAGE_PATH_RE = new RegExp(`\\.${IMAGE_EXT}$`, 'i');
+// After the extension: no further name character, and no `.ext` (a.png.bak).
+const EXT_END = '(?![\\w-])(?!\\.\\w)';
+// Characters that end an unquoted path token.
+const TOKEN_CHAR = '[^\\s\'"`<>|;&()=,:*?]';
+const PATH_TOKEN_RE = new RegExp(
+  [
+    // 1. file:// URL (Codex: `Saved to: file:///…`) — may contain spaces up to the extension.
+    //    The lazy scan stops at the next `file://`: otherwise it runs to the line end from
+    //    every `file://` of a line that repeats it (quadratic). `:` stays allowed, so a
+    //    timestamped name (`plot-12:30.png`) is still found.
+    `file://(/(?:(?!file://)[^\\n])*?\\.${IMAGE_EXT})${EXT_END}`,
+    // 2./3. Quoted paths, spaces allowed.
+    `"([^"\\n]*\\.${IMAGE_EXT})"`,
+    `'([^'\\n]*\\.${IMAGE_EXT})'`,
+    // 4. Unquoted token. A match starts only at a token boundary (line start or a character
+    //    that ends a token), never inside a URL (`:` is not a boundary), a glob or a longer
+    //    name. Anchoring at boundaries keeps this linear: a lookbehind that only excluded
+    //    some characters let a match start at every other character of a long token
+    //    (`####…`, a base64 blob) and rescan the token from each, quadratic in the line
+    //    length. The name before the extension must not be empty.
+    `(?<=^|[\\s'"\`<>|;&()=,*?])((?:${TOKEN_CHAR}*/)?[^\\s'"\`<>|;&()=,:*?/]+\\.${IMAGE_EXT})${EXT_END}`,
+  ].join('|'),
+  'gi'
+);
+
+/** `image` for the image extensions the panel can thumbnail, else `code`. */
+export function classifyEditPath(path: string): EditKind {
+  return IMAGE_PATH_RE.test(path) ? 'image' : 'code';
+}
+
+/**
+ * Image-looking paths in a Bash call's command and output, in order of appearance,
+ * deduplicated and capped at {@link MAX_IMAGE_CANDIDATES}. Absolute paths are normalised,
+ * `~/` paths stay literal (the host that stats them expands `~`), relative ones are
+ * resolved against `cwd` and dropped when `cwd` is not absolute. URLs and globs are
+ * skipped.
+ */
+export function extractImagePathCandidates(command: string, stdout: string, stderr: string, cwd: string): string[] {
+  const text = [command, stdout, stderr].join('\n');
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const m of text.matchAll(PATH_TOKEN_RE)) {
+    const raw = m[1] ?? m[2] ?? m[3] ?? m[4];
+    if (!raw || raw.includes('://') || /[*?]/.test(raw)) continue;
+    let resolved: string;
+    if (raw.startsWith('/')) resolved = posix.normalize(raw);
+    else if (raw.startsWith('~/')) resolved = raw;
+    else if (cwd.startsWith('/')) resolved = posix.resolve(cwd, raw);
+    else continue;
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push(resolved);
+    if (out.length >= MAX_IMAGE_CANDIDATES) break;
+  }
+  return out;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * The hunks of `patch` with their string lines, cut once the lines reach {@link MAX_HUNK_BYTES}
+ * (`truncated`). Also applied to hunks loaded from a store file.
+ */
+export function capHunks(patch: readonly unknown[]): { hunks: EditHunk[]; truncated: boolean } {
+  const hunks: EditHunk[] = [];
+  let budget = MAX_HUNK_BYTES;
+  let truncated = false;
+  for (const h of patch) {
+    if (!isRecord(h) || !Array.isArray(h.lines)) continue;
+    if (truncated) break;
+    const kept: string[] = [];
+    for (const l of h.lines) {
+      if (typeof l !== 'string') continue;
+      const cost = Buffer.byteLength(l) + 3;
+      if (cost > budget) {
+        truncated = true;
+        break;
+      }
+      budget -= cost;
+      kept.push(l);
+    }
+    hunks.push({
+      oldStart: Number(h.oldStart) || 0,
+      oldLines: Number(h.oldLines) || 0,
+      newStart: Number(h.newStart) || 0,
+      newLines: Number(h.newLines) || 0,
+      lines: kept,
+    });
+  }
+  return { hunks, truncated };
+}
+
+function toHunks(patch: unknown[]): { hunks: EditHunk[]; added: number; removed: number; truncated: boolean } {
+  let added = 0;
+  let removed = 0;
+  for (const h of patch) {
+    if (!isRecord(h) || !Array.isArray(h.lines)) continue;
+    for (const l of h.lines) {
+      if (typeof l !== 'string') continue;
+      if (l.startsWith('+')) added++;
+      else if (l.startsWith('-')) removed++;
+    }
+  }
+  return { ...capHunks(patch), added, removed };
+}
+
+/** A new file's content as one all-added hunk, in `structuredPatch` form. */
+function createdFileHunk(content: string): Record<string, unknown> {
+  const lines = content.split('\n');
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  return { oldStart: 0, oldLines: 0, newStart: 1, newLines: lines.length, lines: lines.map((l) => `+${l}`) };
+}
+
+function toEditRecord(id: string, ts: number, result: unknown, agentId: string | undefined): EditRecord | null {
+  if (!isRecord(result)) return null;
+  const { filePath, structuredPatch } = result;
+  if (typeof filePath !== 'string' || !filePath || !Array.isArray(structuredPatch)) return null;
+  const tool: EditTool = typeof result.type === 'string' ? 'Write' : 'oldString' in result ? 'Edit' : 'edit';
+  const kind = classifyEditPath(filePath);
+  // A Write that created a file reports an empty patch; its diff is the whole content.
+  const patch =
+    result.type === 'create' && structuredPatch.length === 0 && kind !== 'image' && typeof result.content === 'string'
+      ? [createdFileHunk(result.content)]
+      : structuredPatch;
+  const { hunks, added, removed, truncated } = toHunks(patch);
+  const record: EditRecord = {
+    id,
+    ts,
+    path: filePath,
+    kind,
+    tool,
+    created: result.type === 'create',
+    added,
+    removed,
+    hunks,
+    truncated,
+  };
+  if (agentId) record.agentId = agentId;
+  return record;
+}
+
+/**
+ * Image paths of a `SendUserFile` result (`{ caption, attachments: [{ path }] }`): the
+ * files claude delivered to the user, which is how a session shows generated images.
+ */
+function sentImagePaths(result: unknown): string[] {
+  if (!isRecord(result) || !Array.isArray(result.attachments)) return [];
+  const out: string[] = [];
+  for (const a of result.attachments) {
+    if (!isRecord(a) || typeof a.path !== 'string' || !a.path.startsWith('/')) continue;
+    if (IMAGE_PATH_RE.test(a.path) && !out.includes(a.path)) out.push(a.path);
+  }
+  return out;
+}
+
+/** The text of a `tool_result` block's content (a string or a list of text blocks). */
+function blockText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .map((b) => (isRecord(b) && typeof b.text === 'string' ? b.text : ''))
+    .filter(Boolean)
+    .join('\n');
+}
+
+/**
+ * Parse transcript lines into edit records and Bash image candidates.
+ *
+ * @param text complete JSONL lines; a first line cut mid-record (a byte range starting
+ *   inside it) and anything else that does not parse is skipped.
+ * @param pending unanswered Bash calls from the previous chunk.
+ */
+export function parseClaudeEditLines(text: string, pending: readonly PendingBash[] = []): EditParseResult {
+  const open = new Map<string, PendingBash>(pending.map((p) => [p.id, p]));
+  const records: EditRecord[] = [];
+  const candidates: ImageCandidate[] = [];
+
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    let rec: unknown;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecord(rec)) continue;
+    const message = rec.message;
+    const content = isRecord(message) ? message.content : undefined;
+    if (!Array.isArray(content)) continue;
+    const parsedTs = typeof rec.timestamp === 'string' ? Date.parse(rec.timestamp) : NaN;
+    const ts = Number.isFinite(parsedTs) ? parsedTs : 0;
+    const agentId = typeof rec.agentId === 'string' && rec.agentId ? rec.agentId : undefined;
+    const cwd = typeof rec.cwd === 'string' ? rec.cwd : '';
+
+    if (rec.type === 'assistant') {
+      for (const block of content) {
+        if (!isRecord(block) || block.type !== 'tool_use' || block.name !== 'Bash') continue;
+        if (typeof block.id !== 'string' || !isRecord(block.input)) continue;
+        const command = block.input.command;
+        if (typeof command !== 'string') continue;
+        if ([block.id, cwd, agentId ?? ''].some((f) => f.length > MAX_PENDING_FIELD_CHARS)) continue;
+        const entry: PendingBash = { id: block.id, ts, command: command.slice(0, MAX_PENDING_COMMAND_CHARS), cwd };
+        if (agentId) entry.agentId = agentId;
+        open.delete(block.id);
+        open.set(block.id, entry);
+        while (open.size > MAX_PENDING_BASH) open.delete(open.keys().next().value as string);
+      }
+      continue;
+    }
+
+    if (rec.type !== 'user') continue;
+    const results = content.filter(
+      (b): b is Record<string, unknown> => isRecord(b) && b.type === 'tool_result' && typeof b.tool_use_id === 'string'
+    );
+    // `toolUseResult` describes the line's result; it is unambiguous only for one block.
+    const single = results.length === 1;
+    for (const block of results) {
+      const id = block.tool_use_id as string;
+      if (single) {
+        const edit = toEditRecord(id, ts, rec.toolUseResult, agentId);
+        if (edit) records.push(edit);
+      }
+      const sent = single ? sentImagePaths(rec.toolUseResult) : [];
+      if (sent.length > 0) {
+        const candidate: ImageCandidate = { toolUseId: id, start: ts, end: ts, paths: sent, sent: true };
+        if (agentId) candidate.agentId = agentId;
+        candidates.push(candidate);
+      }
+      const call = open.get(id);
+      if (!call) continue;
+      open.delete(id);
+      const r = single ? rec.toolUseResult : undefined;
+      let stdout: string;
+      let stderr = '';
+      if (isRecord(r) && (typeof r.stdout === 'string' || typeof r.stderr === 'string')) {
+        stdout = typeof r.stdout === 'string' ? r.stdout : '';
+        stderr = typeof r.stderr === 'string' ? r.stderr : '';
+      } else {
+        stdout = blockText(block.content);
+      }
+      const paths = extractImagePathCandidates(call.command, stdout, stderr, call.cwd);
+      if (paths.length === 0) continue;
+      const candidate: ImageCandidate = { toolUseId: id, start: call.ts, end: ts, paths };
+      if (call.agentId) candidate.agentId = call.agentId;
+      candidates.push(candidate);
+    }
+  }
+
+  return { records, candidates, pending: [...open.values()] };
+}

src/edit-history-store.ts

@@ -0,0 +1,678 @@
+/**
+ * @fileoverview Per-session edit history: the parsed edits and Bash images of one claude
+ * session, plus where in each transcript file reading stopped.
+ *
+ * Sources are the main transcript (`main`) and each subagent transcript
+ * (`subagents/agent-<id>.jsonl`). Each has a cursor:
+ *   - `offset` — the next byte to read forward; always a line boundary.
+ *   - `floor`  — the lowest byte already parsed; > 0 while older lines are unread
+ *                ("ältere laden" reads `[floor − budget, floor)`, see `olderRange`).
+ * The reader (`edit-history-local-source.ts`) reads forward from each `offset` of the
+ * current conversation, a file without one from `budget` bytes before its end, and hands the
+ * bytes to `apply`. Cuts happen only at `\n`, which never occurs inside a UTF-8 sequence, so
+ * multibyte characters split by a chunk boundary are never decoded half.
+ *
+ * A first read of a file starts `budget` bytes before its end (transcripts reach 100 MB+),
+ * drops the cut first line and leaves `floor` there. A line longer than the budget is
+ * skipped instead of blocking the cursor, reading forward (`midLine`) and backward
+ * (`floorMidLine`); the line after it (forward) or before it (backward) is read whole.
+ * That needs every chunk to be a full budget unless it reaches the file's end (forward) or
+ * start (older): a chunk with no line end then means one line longer than the budget. The
+ * caller does not hand over a chunk that a budget shared by several files cut short.
+ *
+ * A new conversation (`/clear`, resume) arrives as a new `transcriptId`: cursors and
+ * pending Bash calls start over, entries stay. Entries are capped at {@link MAX_ENTRIES}
+ * and {@link MAX_STORE_BYTES} of diff text; the oldest by time are dropped. Besides them
+ * the file holds one cursor per transcript file of the current conversation, at most
+ * {@link MAX_PENDING_BASH} unanswered Bash calls and at most {@link MAX_AGENTS} subagent labels.
+ *
+ * ⚠️ The file holds secrets: a diff carries whatever the agent wrote, keys and `.env`
+ * contents included. So, like `intents.json`, it is written 0600 via tmp+rename, bounded,
+ * deleted with the session (`remove()`; `sweep()` at startup removes files no session owns),
+ * never fed to `/api/search`, and blocked from the file routes by `isSensitivePath`
+ * (`web/sensitive-path.ts`). `load()` takes the file as untrusted: past
+ * {@link MAX_FILE_BYTES} it is not parsed, and every part is rebuilt under the same bounds.
+ *
+ * Persisted as JSON under `dataPath('edit-history', '<sessionId>.json')`, written debounced.
+ *
+ * Tests: `test/edit-history-store.test.ts`.
+ *
+ * @module edit-history-store
+ */
+
+import { randomBytes } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { dataPath } from './config/instance.js';
+import {
+  capHunks,
+  MAX_HUNK_BYTES,
+  MAX_PENDING_BASH,
+  MAX_PENDING_COMMAND_CHARS,
+  MAX_PENDING_FIELD_CHARS,
+  parseClaudeEditLines,
+  type EditRecord,
+  type EditTool,
+  type ImageCandidate,
+  type PendingBash,
+} from './edit-history-parse.js';
+
+export const MAX_ENTRIES = 500;
+/** Diff text (and paths) kept per session; see {@link entryBytes}. */
+export const MAX_STORE_BYTES = 4 * 1024 * 1024;
+/** Longest string kept from a subagent's `meta.json` field. */
+export const MAX_AGENT_META_CHARS = 1024;
+/**
+ * Subagent labels kept; past it the oldest one no entry uses is dropped. One more than
+ * {@link MAX_ENTRIES}, so besides the newest label there always is one.
+ */
+export const MAX_AGENTS = MAX_ENTRIES + 1;
+/** Bytes read per file and pass (first read, forward step, "older" step). */
+export const READ_BUDGET_BYTES = 8 * 1024 * 1024;
+/**
+ * A store file larger than this is not parsed (starts empty). One written within the caps
+ * above stays far below it; JSON escaping at most doubles ordinary text.
+ */
+export const MAX_FILE_BYTES = 32 * 1024 * 1024;
+export const MAIN_SOURCE = 'main';
+const SAVE_DEBOUNCE_MS = 1000;
+const FILE_VERSION = 1;
+const NL = 0x0a;
+/** A transcript id as the reader takes it (`<id>.jsonl`): no path separators. */
+const TRANSCRIPT_ID = /^[A-Za-z0-9._-]+$/;
+/**
+ * Names this process's tmp files (`<id>.json.<tag>.tmp`); any other tmp file is left over from
+ * an earlier run (`sweep`), even one whose pid this process has again (a container's pid 1).
+ */
+export const TMP_TAG = `${process.pid}-${randomBytes(4).toString('hex')}`;
+
+/** `bash`: an image a Bash call wrote; `sent`: an image claude delivered to the user. */
+export type EditHistoryTool = EditTool | 'bash' | 'sent';
+
+export interface EditHistoryEntry extends Omit<EditRecord, 'tool'> {
+  tool: EditHistoryTool;
+}
+
+export interface SourceCursor {
+  offset: number;
+  floor: number;
+  /** The next forward read starts inside a line longer than the budget; skip to its end. */
+  midLine?: boolean;
+  /** `floor` lies inside a line longer than the budget; the next older read drops its tail. */
+  floorMidLine?: boolean;
+}
+
+export interface AgentMeta {
+  description: string;
+  agentType: string;
+  worktreePath?: string;
+  worktreeBranch?: string;
+}
+
+export interface ByteRange {
+  offset: number;
+  len: number;
+}
+
+export interface ApplyInput {
+  transcriptId: string;
+  /** `main` or `subagents/agent-<id>.jsonl`. */
+  source: string;
+  startOffset: number;
+  chunk: Buffer;
+  /** Size of the file when the chunk was read. */
+  size: number;
+}
+
+export interface ApplyResult {
+  added: number;
+  candidates: ImageCandidate[];
+}
+
+export interface ConfirmedImage {
+  toolUseId: string;
+  path: string;
+  ts: number;
+  agentId?: string;
+  tool?: 'bash' | 'sent';
+}
+
+export interface EditHistoryStoreOptions {
+  /** Directory holding `<sessionId>.json`; default `dataPath('edit-history')`. */
+  dir?: string;
+  debounceMs?: number;
+}
+
+interface StoreFile {
+  version: number;
+  sessionId: string;
+  transcriptId: string | null;
+  cursors: Record<string, SourceCursor>;
+  pendingBash: PendingBash[];
+  agents: Record<string, AgentMeta>;
+  entries: EditHistoryEntry[];
+}
+
+function isObj(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** What an entry costs against {@link MAX_STORE_BYTES}: its strings and diff lines, plus a fixed overhead. */
+export function entryBytes(e: EditHistoryEntry): number {
+  let n = 128 + Buffer.byteLength(e.id) + Buffer.byteLength(e.path) + Buffer.byteLength(e.agentId ?? '');
+  for (const h of e.hunks) for (const l of h.lines) n += Buffer.byteLength(l) + 3;
+  return n;
+}
+
+function metaString(v: unknown): string | undefined {
+  return typeof v === 'string' && v ? v.slice(0, MAX_AGENT_META_CHARS) : undefined;
+}
+
+/** Parse an `agent-<id>.meta.json` text; null when it is not an object. */
+export function parseAgentMeta(text: string): AgentMeta | null {
+  try {
+    return agentMetaFrom(JSON.parse(text));
+  } catch {
+    return null;
+  }
+}
+
+function isOffset(v: unknown): v is number {
+  return Number.isSafeInteger(v) && (v as number) >= 0;
+}
+
+// The loaders below take the persisted file as untrusted: a hand-edited or damaged store
+// loses the broken parts instead of failing every request or stalling a cursor.
+
+function agentMetaFrom(raw: unknown): AgentMeta | null {
+  if (!isObj(raw)) return null;
+  const meta: AgentMeta = {
+    description: metaString(raw.description) ?? '',
+    agentType: metaString(raw.agentType) ?? '',
+  };
+  const worktreePath = metaString(raw.worktreePath);
+  const worktreeBranch = metaString(raw.worktreeBranch);
+  if (worktreePath) meta.worktreePath = worktreePath;
+  if (worktreeBranch) meta.worktreeBranch = worktreeBranch;
+  return meta;
+}
+
+function cursorFrom(raw: unknown): SourceCursor | null {
+  if (!isObj(raw) || !isOffset(raw.offset) || !isOffset(raw.floor) || raw.floor > raw.offset) return null;
+  const cursor: SourceCursor = { offset: raw.offset, floor: raw.floor };
+  if (raw.midLine === true) cursor.midLine = true;
+  if (raw.floorMidLine === true) cursor.floorMidLine = true;
+  return cursor;
+}
+
+const loadedField = (v: unknown): v is string => typeof v === 'string' && v.length <= MAX_PENDING_FIELD_CHARS;
+
+function pendingBashFrom(raw: unknown): PendingBash | null {
+  if (!isObj(raw)) return null;
+  const { id, ts, command, cwd, agentId } = raw;
+  if (!loadedField(id) || !Number.isFinite(ts) || typeof command !== 'string' || !loadedField(cwd)) return null;
+  if (agentId !== undefined && !loadedField(agentId)) return null;
+  const pending: PendingBash = { id, ts: ts as number, command: command.slice(0, MAX_PENDING_COMMAND_CHARS), cwd };
+  if (agentId) pending.agentId = agentId;
+  return pending;
+}
+
+const ENTRY_KINDS = new Set(['code', 'image']);
+const ENTRY_TOOLS = new Set(['Edit', 'Write', 'edit', 'bash', 'sent']);
+const countFrom = (v: unknown): number => (Number.isSafeInteger(v) && (v as number) >= 0 ? (v as number) : 0);
+
+/**
+ * A loaded entry rebuilt from its known fields: unknown fields and non-string diff lines are
+ * dropped and the per-edit {@link MAX_HUNK_BYTES} is applied again; null when it is unusable.
+ */
+function entryFrom(raw: unknown): EditHistoryEntry | null {
+  if (!isObj(raw) || typeof raw.id !== 'string' || !raw.id || typeof raw.path !== 'string' || !raw.path) return null;
+  if (!Number.isFinite(raw.ts) || !ENTRY_KINDS.has(raw.kind as string) || !ENTRY_TOOLS.has(raw.tool as string)) {
+    return null;
+  }
+  if (!Array.isArray(raw.hunks)) return null;
+  const { hunks, truncated } = capHunks(raw.hunks);
+  const entry: EditHistoryEntry = {
+    id: raw.id,
+    ts: raw.ts as number,
+    path: raw.path,
+    kind: raw.kind as EditHistoryEntry['kind'],
+    tool: raw.tool as EditHistoryTool,
+    created: raw.created === true,
+    added: countFrom(raw.added),
+    removed: countFrom(raw.removed),
+    hunks,
+    truncated: truncated || raw.truncated === true,
+  };
+  if (typeof raw.agentId === 'string' && raw.agentId) entry.agentId = raw.agentId;
+  return entry;
+}
+
+export class EditHistoryStore {
+  readonly sessionId: string;
+  private readonly file: string;
+  private readonly debounceMs: number;
+  private transcriptId: string | null = null;
+  private cursors = new Map<string, SourceCursor>();
+  private pendingBash: PendingBash[] = [];
+  private agents = new Map<string, AgentMeta>();
+  private entries = new Map<string, EditHistoryEntry>();
+  /** Sum of {@link entryBytes} over `entries`. */
+  private bytes = 0;
+  private saveTimer: NodeJS.Timeout | null = null;
+  /** The last queued write; `remove()` waits for it. */
+  private writing: Promise<void> | null = null;
+  private removed = false;
+
+  constructor(sessionId: string, opts: EditHistoryStoreOptions = {}) {
+    this.sessionId = sessionId;
+    this.file = join(opts.dir ?? dataPath('edit-history'), `${sessionId}.json`);
+    this.debounceMs = opts.debounceMs ?? SAVE_DEBOUNCE_MS;
+  }
+
+  /**
+   * A store with the persisted state of `sessionId`; empty when the file is missing,
+   * unreadable or larger than {@link MAX_FILE_BYTES}.
+   */
+  static async load(sessionId: string, opts: EditHistoryStoreOptions = {}): Promise<EditHistoryStore> {
+    const store = new EditHistoryStore(sessionId, opts);
+    let data: unknown;
+    try {
+      if ((await stat(store.file)).size > MAX_FILE_BYTES) return store;
+      data = JSON.parse(await readFile(store.file, 'utf-8'));
+    } catch {
+      return store;
+    }
+    if (!isObj(data)) return store;
+    if (data.version !== FILE_VERSION) return store;
+    const f = data as unknown as StoreFile;
+    // The sync builds the previous transcript's path from it (`/clear`), so only a plain id counts.
+    store.transcriptId =
+      typeof f.transcriptId === 'string' && TRANSCRIPT_ID.test(f.transcriptId) ? f.transcriptId : null;
+    // Cursors are offsets into that conversation's files; without it they mean nothing.
+    const cursors = store.transcriptId !== null && isObj(f.cursors) ? f.cursors : {};
+    for (const [k, raw] of Object.entries(cursors)) {
+      const cursor = cursorFrom(raw);
+      if (cursor) store.cursors.set(k, cursor);
+    }
+    if (Array.isArray(f.pendingBash)) {
+      store.pendingBash = f.pendingBash
+        .map(pendingBashFrom)
+        .filter((p): p is PendingBash => p !== null)
+        .slice(-MAX_PENDING_BASH);
+    }
+    if (Array.isArray(f.entries)) {
+      store.addRecords(f.entries.map(entryFrom).filter((e): e is EditHistoryEntry => e !== null));
+    }
+    for (const [k, raw] of Object.entries(isObj(f.agents) ? f.agents : {})) {
+      const meta = k.length <= MAX_AGENT_META_CHARS ? agentMetaFrom(raw) : null;
+      if (meta) store.putAgent(k, meta);
+    }
+    return store;
+  }
+
+  /**
+   * Delete the stored history of every session `keep` rejects, and tmp files other processes
+   * left behind (startup: a crash between removing a session's record and deleting its file,
+   * or mid-write; an older build).
+   * Returns how many sessions' files were deleted.
+   */
+  static async sweep(
+    keep: (sessionId: string) => boolean,
+    opts: Pick<EditHistoryStoreOptions, 'dir'> = {}
+  ): Promise<number> {
+    const dir = opts.dir ?? dataPath('edit-history');
+    let names: string[];
+    try {
+      names = await readdir(dir);
+    } catch {
+      return 0;
+    }
+    let removed = 0;
+    for (const name of names) {
+      const tmp = /\.json\.[\w-]+\.tmp$/.test(name);
+      const stale = tmp
+        ? !name.endsWith(`.json.${TMP_TAG}.tmp`)
+        : name.endsWith('.json') && !keep(name.slice(0, -'.json'.length));
+      if (!stale) continue;
+      await unlink(join(dir, name)).catch(() => undefined);
+      if (!tmp) removed++;
+    }
+    return removed;
+  }
+
+  /** Delete the stored history of `sessionId` without loading it. */
+  static async delete(sessionId: string, opts: Pick<EditHistoryStoreOptions, 'dir'> = {}): Promise<void> {
+    await new EditHistoryStore(sessionId, opts).remove();
+  }
+
+  getTranscriptId(): string | null {
+    return this.transcriptId;
+  }
+
+  getCursor(source: string): SourceCursor | undefined {
+    const c = this.cursors.get(source);
+    return c ? { ...c } : undefined;
+  }
+
+  /**
+   * True while any source has unread older lines that could still be shown. At a cap (no
+   * room left for another entry) an older edit would be dropped the moment it is read, so
+   * there is nothing more to load.
+   */
+  get backfillTruncated(): boolean {
+    if (this.entries.size >= MAX_ENTRIES || this.bytes > MAX_STORE_BYTES - MAX_HUNK_BYTES) return false;
+    for (const c of this.cursors.values()) if (c.floor > 0) return true;
+    return false;
+  }
+
+  /** Entries newest first. */
+  list(): EditHistoryEntry[] {
+    return [...this.entries.values()].sort((a, b) => b.ts - a.ts);
+  }
+
+  get(id: string): EditHistoryEntry | undefined {
+    return this.entries.get(id);
+  }
+
+  getAgents(): Record<string, AgentMeta> {
+    return Object.fromEntries(this.agents);
+  }
+
+  hasAgentMeta(agentId: string): boolean {
+    return this.agents.has(agentId);
+  }
+
+  /** Record a subagent's `meta.json`; ignored when it does not parse. */
+  setAgentMeta(agentId: string, metaText: string): void {
+    const meta = this.removed ? null : parseAgentMeta(metaText);
+    if (!meta) return;
+    this.putAgent(agentId, meta);
+    this.scheduleSave();
+  }
+
+  /** The next older range of `source` ("ältere laden"), or null when it is read to its start. */
+  olderRange(source: string, budget = READ_BUDGET_BYTES): ByteRange | null {
+    const cursor = this.cursors.get(source);
+    if (!cursor || cursor.floor <= 0) return null;
+    const offset = Math.max(0, cursor.floor - budget);
+    return { offset, len: cursor.floor - offset };
+  }
+
+  /** Every source with a cursor in the current conversation. */
+  knownSources(): string[] {
+    return [...this.cursors.keys()];
+  }
+
+  /** Sources with older lines left. */
+  sourcesWithOlder(): string[] {
+    return [...this.cursors.entries()].filter(([, c]) => c.floor > 0).map(([s]) => s);
+  }
+
+  /**
+   * A source whose file is gone (a deleted subagent transcript): its cursor goes, so it no
+   * longer offers older lines. Its entries stay.
+   */
+  dropSource(source: string): void {
+    if (this.removed || !this.cursors.delete(source)) return;
+    this.scheduleSave();
+  }
+
+  /**
+   * Apply a forward chunk: read from the source's cursor, or, without one, its last `budget`
+   * bytes; a full budget unless it reaches the file's end. A file that shrank below its cursor
+   * (replaced) loses the cursor and is read from its end next time. Returns new entries and
+   * Bash image candidates.
+   */
+  apply(input: ApplyInput): ApplyResult {
+    if (this.removed) return { added: 0, candidates: [] };
+    const { transcriptId, source, startOffset, chunk, size } = input;
+    if (transcriptId !== this.transcriptId) {
+      this.transcriptId = transcriptId;
+      this.cursors.clear();
+      this.pendingBash = [];
+    }
+    let cursor = this.cursors.get(source);
+    if (cursor && size < cursor.offset) {
+      this.cursors.delete(source);
+      cursor = undefined;
+    }
+    if (cursor && startOffset !== cursor.offset) return { added: 0, candidates: [] };
+
+    const atEof = startOffset + chunk.length >= size;
+    // Bytes before `from` belong to a line that started before this chunk.
+    let from = 0;
+    if (cursor ? cursor.midLine : startOffset > 0) {
+      const nl = chunk.indexOf(NL);
+      if (nl === -1) {
+        // Still inside that line: move past it unless it is the line being written. A first
+        // read began inside it, so the floor does too.
+        if (!atEof) this.setCursor(source, cursor, startOffset + chunk.length, startOffset, true, true);
+        return { added: 0, candidates: [] };
+      }
+      from = nl + 1;
+    }
+    const lastNl = chunk.lastIndexOf(NL);
+    if (lastNl < from) {
+      if (from > 0) {
+        // The skipped (or cut first) line ended here; the next one is read from its start.
+        this.setCursor(source, cursor, startOffset + from, startOffset + from, false);
+      } else if (!atEof && chunk.length > 0) {
+        // One line longer than the budget: skip it instead of re-reading it forever.
+        this.setCursor(source, cursor, startOffset + chunk.length, startOffset, true);
+      } else if (!cursor) {
+        this.setCursor(source, undefined, startOffset, startOffset, false);
+      }
+      return { added: 0, candidates: [] };
+    }
+    const end = lastNl + 1;
+    this.setCursor(source, cursor, startOffset + end, startOffset + from, false);
+    const parsed = parseClaudeEditLines(chunk.subarray(from, end).toString('utf8'), this.pendingBash);
+    this.pendingBash = parsed.pending;
+    const added = this.addRecords(parsed.records);
+    this.scheduleSave();
+    return { added, candidates: parsed.candidates };
+  }
+
+  /**
+   * Apply a chunk read at `olderRange`: a full budget unless it reaches the file's start. It
+   * ends at the floor, which is a line start, or with `floorMidLine` lies inside a line longer
+   * than the budget (its part in this chunk is dropped).
+   */
+  applyOlder(input: ApplyInput): ApplyResult {
+    const { transcriptId, source, startOffset, chunk } = input;
+    const cursor = this.removed ? undefined : this.cursors.get(source);
+    if (transcriptId !== this.transcriptId || !cursor || startOffset + chunk.length !== cursor.floor) {
+      return { added: 0, candidates: [] };
+    }
+    const none = { added: 0, candidates: [] };
+    let end = chunk.length;
+    if (cursor.floorMidLine) {
+      const lastNl = chunk.lastIndexOf(NL);
+      if (lastNl === -1 && startOffset > 0) {
+        // Still inside the long line.
+        cursor.floor = startOffset;
+        this.scheduleSave();
+        return none;
+      }
+      // The long line starts at `end`: drop its part.
+      end = lastNl + 1;
+      delete cursor.floorMidLine;
+    }
+    let from = 0;
+    if (startOffset > 0) {
+      // The newline at `end - 1` closes a line that may have started before this chunk.
+      const nl = chunk.subarray(0, end).indexOf(NL);
+      if (nl === -1 || nl === end - 1) {
+        if (end < chunk.length) {
+          // It ends where the long line starts: the next block, ending there, holds it whole.
+          cursor.floor = startOffset + end;
+        } else {
+          // No line starts in this chunk: it lies inside one line longer than the budget. Skip it.
+          cursor.floor = startOffset;
+          cursor.floorMidLine = true;
+        }
+        this.scheduleSave();
+        return none;
+      }
+      from = nl + 1;
+    }
+    cursor.floor = startOffset + from;
+    // Calls whose results lie in already-read newer lines cannot be paired here.
+    const parsed = parseClaudeEditLines(chunk.subarray(from, end).toString('utf8'));
+    const added = this.addRecords(parsed.records);
+    this.scheduleSave();
+    return { added, candidates: parsed.candidates };
+  }
+
+  /** Add Bash images whose mtime was confirmed inside their call's window. */
+  addImageEntries(images: readonly ConfirmedImage[]): number {
+    if (this.removed) return 0;
+    const records: EditHistoryEntry[] = images.map((img) => {
+      const entry: EditHistoryEntry = {
+        id: `${img.toolUseId}:${img.path}`,
+        ts: img.ts,
+        path: img.path,
+        kind: 'image',
+        tool: img.tool ?? 'bash',
+        created: false,
+        added: 0,
+        removed: 0,
+        hunks: [],
+        truncated: false,
+      };
+      if (img.agentId) entry.agentId = img.agentId;
+      return entry;
+    });
+    const added = this.addRecords(records);
+    if (added) this.scheduleSave();
+    return added;
+  }
+
+  /**
+   * Write pending changes, if any, and wait for a write under way (the store is dropped from
+   * memory and loaded again later). Unlike `flush()`, a store without changes writes nothing.
+   */
+  async settle(): Promise<void> {
+    if (this.saveTimer) return this.flush();
+    await this.writing;
+  }
+
+  /** Write now (cancels a pending debounced write). Writes run one after another. */
+  async flush(): Promise<void> {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    const run = (this.writing ?? Promise.resolve()).then(() => this.write());
+    this.writing = run.catch(() => undefined);
+    await run;
+  }
+
+  /**
+   * Delete the persisted file (session deleted) and forget the content. The store takes no
+   * changes afterwards, so a read still in flight neither writes nor refills it.
+   */
+  /** True once {@link remove} ran: the store ignores every later write. */
+  isRemoved(): boolean {
+    return this.removed;
+  }
+
+  async remove(): Promise<void> {
+    this.removed = true;
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    this.entries.clear();
+    this.bytes = 0;
+    this.cursors.clear();
+    this.pendingBash = [];
+    this.agents.clear();
+    // A write already under way ends first (or sees `removed`), so it cannot rename its
+    // tmp file over the deleted store afterwards.
+    await this.writing;
+    await unlink(this.file).catch(() => undefined);
+  }
+
+  private async write(): Promise<void> {
+    if (this.removed) return;
+    const data: StoreFile = {
+      version: FILE_VERSION,
+      sessionId: this.sessionId,
+      transcriptId: this.transcriptId,
+      cursors: Object.fromEntries(this.cursors),
+      pendingBash: this.pendingBash,
+      agents: Object.fromEntries(this.agents),
+      entries: this.list(),
+    };
+    const dir = join(this.file, '..');
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    // `mode` applies only to a file being created: the fresh tmp file is 0600, and the rename
+    // makes it the store, so an existing store never keeps wider bits.
+    const tmp = `${this.file}.${TMP_TAG}.tmp`;
+    await writeFile(tmp, JSON.stringify(data), { mode: 0o600 });
+    if (this.removed) {
+      await unlink(tmp).catch(() => undefined);
+      return;
+    }
+    await rename(tmp, this.file);
+  }
+
+  private putAgent(agentId: string, meta: AgentMeta): void {
+    this.agents.delete(agentId);
+    this.agents.set(agentId, meta);
+    if (this.agents.size <= MAX_AGENTS) return;
+    const used = new Set<string>();
+    for (const e of this.entries.values()) if (e.agentId) used.add(e.agentId);
+    for (const id of this.agents.keys()) {
+      if (this.agents.size <= MAX_AGENTS) break;
+      // The newest label has no entries yet: they come with its transcript.
+      if (id !== agentId && !used.has(id)) this.agents.delete(id);
+    }
+  }
+
+  private setCursor(
+    source: string,
+    cursor: SourceCursor | undefined,
+    offset: number,
+    firstFloor: number,
+    midLine: boolean,
+    firstFloorMidLine = false
+  ): void {
+    const next: SourceCursor = { offset, floor: cursor ? cursor.floor : firstFloor };
+    if (midLine) next.midLine = true;
+    if (cursor ? cursor.floorMidLine : firstFloorMidLine) next.floorMidLine = true;
+    this.cursors.set(source, next);
+  }
+
+  private addRecords(records: readonly EditHistoryEntry[]): number {
+    const fresh: string[] = [];
+    for (const r of records) {
+      if (this.entries.has(r.id)) continue;
+      this.entries.set(r.id, r);
+      this.bytes += entryBytes(r);
+      fresh.push(r.id);
+    }
+    if (this.entries.size > MAX_ENTRIES || this.bytes > MAX_STORE_BYTES) {
+      for (const e of [...this.entries.values()].sort((a, b) => a.ts - b.ts)) {
+        if (this.entries.size <= MAX_ENTRIES && this.bytes <= MAX_STORE_BYTES) break;
+        this.entries.delete(e.id);
+        this.bytes -= entryBytes(e);
+      }
+    }
+    // Only what is still there counts: an "older" block past the cap adds nothing.
+    return fresh.filter((id) => this.entries.has(id)).length;
+  }
+
+  private scheduleSave(): void {
+    if (this.removed || this.saveTimer) return;
+    this.saveTimer = setTimeout(() => {
+      this.saveTimer = null;
+      void this.flush().catch((err) => {
+        console.warn(`[EditHistory] Save failed for session ${this.sessionId}:`, err);
+      });
+    }, this.debounceMs);
+    this.saveTimer.unref?.();
+  }
+}

src/session.ts

@@ -2830,7 +2830,7 @@ export class Session extends EventEmitter {
     if (entry?.launch.chain !== 'fallback') return options;
 
     const resumeIdPattern = entry.launch.params?.resumeId;
-    const configDir = this._claudeConfigDir();
+    const configDir = this.claudeConfigDir();
     const chainTail = this._claudeSessionChain[this._claudeSessionChain.length - 1];
     const candidates = [chainTail, options.resumeSessionId, this.id].filter((v): v is string => !!v);
     for (const candidate of candidates) {
@@ -2852,8 +2852,11 @@ export class Session extends EventEmitter {
     return options;
   }
 
-  /** The session's Claude config dir when it has been relocated (#255), else undefined. */
-  private _claudeConfigDir(): string | undefined {
+  /**
+   * The session's Claude config dir when it has been relocated (#255), else undefined.
+   * Public for the edit history reader, which looks for the transcript there.
+   */
+  claudeConfigDir(): string | undefined {
     // Trimmed like `claudeProjectsDir()` trims the process-wide override: the
     // envOverrides schema validates keys only, and a whitespace-only value would
     // otherwise resolve to a relative path and read "no transcript" for everything.

src/web/edit-history-sync.ts

@@ -0,0 +1,497 @@
+/**
+ * @fileoverview Reads a claude session's edit history on request: the new bytes of its
+ * transcripts (main + subagents) go into its `EditHistoryStore`, and the Bash image
+ * candidates that came with them are confirmed against the files on disk.
+ *
+ * WHEN. Only when the panel asks (`GET …/edits?sync=1` on open and while it follows the
+ * session, `POST …/edits/older`): no timer, no hook, no background read for sessions nobody
+ * looks at. One sync per session runs at a time; requests during a run are folded into one
+ * more forward read and/or one more older read afterwards.
+ *
+ * HOW MUCH. A forward read shares one budget over all files, main first. A file whose chunk
+ * the shared budget cut short is not applied (the store would take a chunk with no line end
+ * for a line longer than the budget) but read in the next pass; up to
+ * {@link MAX_FORWARD_PASSES} passes per sync, the rest with the next one.
+ *
+ * NEW CONVERSATION. When the transcript path names another conversation (`/clear`, resume),
+ * the previous transcript (same directory) is first read to its end, so edits it got after
+ * the last read are not lost with its cursors; then the new one is read from its end.
+ * "Load older" reaches back within the current conversation only.
+ *
+ * MEMORY. At most {@link MAX_LOADED_STORES} stores stay loaded; past that the least recently
+ * used one without a run is written (if it changed) and dropped, and loaded again on demand.
+ *
+ * GONE. `remove()` (the session's record is deleted) marks the session gone, deletes the file
+ * and then drops the session's slot: a run in flight stops after its current read and its
+ * store no longer writes; a request during the removal reads nothing (`unavailable`, reason
+ * `removed`). A session that comes back with the same id (reboot restore) starts afresh.
+ * `sweep()` deletes, at startup, the stored history of sessions that no longer exist. A
+ * subagent transcript that vanished loses its cursor (`dropSource`), not its entries.
+ *
+ * OLDER. "Load older" reads a full budget block of up to {@link MAX_OLDER_SOURCES} sources
+ * with older lines per click; with more sources they take turns.
+ *
+ * WHICH SESSIONS. Local claude sessions. Remote, Docker and non-claude sessions answer
+ * `unsupported` and are never read.
+ *
+ * IMAGES. A Bash candidate counts only when the file's mtime lies in the call's window
+ * (start − 2 s … end + 2 s), so `ls *.png` lists nothing.
+ *
+ * Tests: `test/edit-history-sync.test.ts`.
+ *
+ * @module web/edit-history-sync
+ */
+
+import { basename, dirname, join } from 'node:path';
+import type { SessionRemote } from '../types/session.js';
+import type { EditSourceReadOptions, EditSourceRequest, EditSources, PathProbe } from '../edit-history-local-source.js';
+import type { ImageCandidate } from '../edit-history-parse.js';
+import { EditHistoryStore, READ_BUDGET_BYTES, type ConfirmedImage } from '../edit-history-store.js';
+import { getCli } from '../config/cli-registry/registry.js';
+
+/** Slack around a Bash call's window for the image mtime check. */
+export const IMAGE_MTIME_SLACK_MS = 2000;
+/** Forward passes per sync when files grew by more than one budget. */
+export const MAX_FORWARD_PASSES = 3;
+/** Sources read back per "Load older" click, a full budget each. */
+export const MAX_OLDER_SOURCES = 3;
+/** Stores kept in memory; the least recently used one past this is dropped. */
+export const MAX_LOADED_STORES = 3;
+/** `reason` when the session has no transcript yet (no prompt yet, or not found). */
+export const NO_TRANSCRIPT = 'no-transcript';
+/** `reason` once the session's history was deleted. */
+export const REMOVED = 'removed';
+
+export type EditHistoryState = 'ok' | 'unavailable' | 'unsupported';
+
+export interface EditHistoryStatus {
+  state: EditHistoryState;
+  reason?: string;
+}
+
+/** The slice of a session this needs. */
+export interface EditHistorySession {
+  id: string;
+  mode: string;
+  remote: SessionRemote | undefined;
+  docker?: unknown;
+  claudeSessionId: string | null;
+  /** The session's own `CLAUDE_CONFIG_DIR` (Codeman env override), if it has one. */
+  claudeConfigDir?: string;
+}
+
+export interface EditHistorySyncDeps {
+  /** The session's main transcript path, or null when it has none yet. */
+  transcriptPath(session: EditHistorySession): Promise<string | null>;
+  readSources(
+    mainPath: string,
+    requests: readonly EditSourceRequest[],
+    budget: number,
+    opts?: EditSourceReadOptions
+  ): Promise<EditSources | null>;
+  probe(paths: readonly string[]): Promise<Array<PathProbe | null>>;
+  loadStore(sessionId: string): Promise<EditHistoryStore>;
+  /** Delete a session's stored history without loading it. */
+  deleteStore(sessionId: string): Promise<void>;
+  /** Delete the stored history of every session `keep` rejects; returns how many. */
+  sweepStores(keep: (sessionId: string) => boolean): Promise<number>;
+  budget?: number;
+}
+
+export interface SyncOptions {
+  older?: boolean;
+}
+
+/** Why a session has no edit history, or undefined when it can have one. */
+export function unsupportedReason(session: EditHistorySession): string | undefined {
+  if (session.remote) return 'remote';
+  if (session.docker) return 'docker';
+  if (getCli(session.mode)?.capabilities.transcript !== 'claude-jsonl') return 'mode';
+  return undefined;
+}
+
+/** One turn of the event loop, between synchronous parses of up to one budget each. */
+function breathe(): Promise<void> {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
+/**
+ * Bash candidates whose probed file is a regular file with an mtime inside the call's window
+ * (files claude sent to the user skip the window: they exist and were shown on purpose).
+ * A candidate whose file version is already recorded is skipped: `known(path)` is the newest
+ * entry time for that path, and an entry at or after `mtime − slack` saw this version — the
+ * `ls *.png` right after the render, or a Write followed by a listing. Candidates are taken
+ * in call order so a batch dedupes itself the same way.
+ */
+export function confirmImages(
+  candidates: readonly ImageCandidate[],
+  probe: (path: string) => PathProbe | null | undefined,
+  known: (path: string) => number | undefined = () => undefined
+): ConfirmedImage[] {
+  const out: ConfirmedImage[] = [];
+  const seen = new Map<string, number>();
+  for (const c of [...candidates].sort((a, b) => a.end - b.end)) {
+    for (const path of c.paths) {
+      const p = probe(path);
+      if (!p || p.kind !== 'file' || !p.mtimeMs) continue;
+      const inWindow = p.mtimeMs >= c.start - IMAGE_MTIME_SLACK_MS && p.mtimeMs <= c.end + IMAGE_MTIME_SLACK_MS;
+      if (!c.sent && !inWindow) continue;
+      const entryPath = path.startsWith('~/') ? p.realPath : path;
+      const last = Math.max(seen.get(entryPath) ?? -Infinity, known(entryPath) ?? -Infinity);
+      if (last >= p.mtimeMs - IMAGE_MTIME_SLACK_MS) continue;
+      seen.set(entryPath, c.end);
+      const img: ConfirmedImage = {
+        toolUseId: c.toolUseId,
+        path: entryPath,
+        ts: c.end,
+        tool: c.sent ? 'sent' : 'bash',
+      };
+      if (c.agentId) img.agentId = c.agentId;
+      out.push(img);
+    }
+  }
+  return out;
+}
+
+interface SyncWant {
+  forward: boolean;
+  older: boolean;
+}
+
+interface SessionSlot {
+  store?: Promise<EditHistoryStore>;
+  status: EditHistoryStatus;
+  running?: Promise<void>;
+  again?: SyncWant;
+  /** The history was deleted: nothing reads for this session any more. */
+  gone?: boolean;
+  /** The last source the previous "Load older" read; the next one starts after it. */
+  olderAfter?: string;
+}
+
+export class EditHistorySync {
+  /** By session, least recently used first. */
+  private readonly slots = new Map<string, SessionSlot>();
+  /** Writes of dropped stores; loading that session again waits for its write. */
+  private readonly unloading = new Map<string, Promise<void>>();
+  private readonly budget: number;
+
+  constructor(private readonly deps: EditHistorySyncDeps) {
+    this.budget = deps.budget ?? READ_BUDGET_BYTES;
+  }
+
+  /** The session's store, loaded from disk on first use (one load for concurrent callers). */
+  getStore(sessionId: string): Promise<EditHistoryStore> {
+    return this.storeOf(sessionId, this.slot(sessionId));
+  }
+
+  getStatus(sessionId: string): EditHistoryStatus {
+    return { ...this.slot(sessionId).status };
+  }
+
+  /**
+   * Read what is new (or, with `older`, the next older block). Resolves when this
+   * request's run is done; never rejects. A call during a run queues one more run.
+   */
+  async sync(session: EditHistorySession, opts: SyncOptions = {}): Promise<EditHistoryStatus> {
+    const why = unsupportedReason(session);
+    const slot = this.slot(session.id);
+    if (slot.gone) return { ...slot.status };
+    if (why) {
+      slot.status = { state: 'unsupported', reason: why };
+      return { ...slot.status };
+    }
+    const want: SyncWant = { forward: !opts.older, older: !!opts.older };
+    if (slot.running) {
+      slot.again = {
+        forward: (slot.again?.forward ?? false) || want.forward,
+        older: (slot.again?.older ?? false) || want.older,
+      };
+      await slot.running;
+      // The queued run starts when the current one ends; wait for it too.
+      if (slot.running) await slot.running;
+      return { ...slot.status };
+    }
+    slot.running = this.runLoop(session, slot, want);
+    try {
+      await slot.running;
+    } finally {
+      slot.running = undefined;
+      this.unloadIdle(slot);
+    }
+    return { ...slot.status };
+  }
+
+  /** Write every loaded store's pending changes (server shutdown). */
+  async flushAll(): Promise<void> {
+    await Promise.all([
+      ...[...this.slots.values()].map(async (slot) => (await slot.store?.catch(() => undefined))?.settle()),
+      ...this.unloading.values(),
+    ]);
+  }
+
+  /**
+   * Delete a session's stored history (its record is gone). While it runs the session is
+   * marked, so a run in flight or a request meanwhile cannot load and write a new store for
+   * it; then its slot goes, and a session that comes back with this id starts afresh.
+   */
+  async remove(sessionId: string): Promise<void> {
+    const slot = this.slot(sessionId);
+    slot.gone = true;
+    slot.again = undefined;
+    slot.status = { state: 'unavailable', reason: REMOVED };
+    try {
+      const store = await slot.store?.catch(() => undefined);
+      if (store) {
+        await store.remove();
+      } else {
+        await this.unloading.get(sessionId);
+        await this.deps.deleteStore(sessionId);
+      }
+      await slot.running;
+    } finally {
+      if (this.slots.get(sessionId) === slot) this.slots.delete(sessionId);
+    }
+  }
+
+  /**
+   * Delete the stored history of sessions that no longer exist (startup: left behind by a
+   * crash during deletion, or by an older build). A session in use here is kept.
+   */
+  sweep(exists: (sessionId: string) => boolean): Promise<number> {
+    return this.deps.sweepStores((id) => this.slots.has(id) || exists(id));
+  }
+
+  /** The session's slot, now the most recently used. */
+  private slot(sessionId: string): SessionSlot {
+    const slot = this.slots.get(sessionId) ?? { status: { state: 'ok' } };
+    this.slots.delete(sessionId);
+    this.slots.set(sessionId, slot);
+    return slot;
+  }
+
+  private storeOf(sessionId: string, slot: SessionSlot): Promise<EditHistoryStore> {
+    if (!slot.store) {
+      const loading = (async () => {
+        await this.unloading.get(sessionId);
+        return this.deps.loadStore(sessionId);
+      })();
+      slot.store = loading;
+      loading.catch(() => {
+        if (slot.store === loading) slot.store = undefined;
+      });
+      this.unloadIdle(slot);
+    }
+    return slot.store;
+  }
+
+  /**
+   * Past {@link MAX_LOADED_STORES}, drop the least recently used stores no run uses: each is
+   * written if it changed, and a later request loads it again (after that write).
+   */
+  private unloadIdle(keep?: SessionSlot): void {
+    let loaded = 0;
+    for (const slot of this.slots.values()) if (slot.store) loaded++;
+    for (const [sessionId, slot] of this.slots) {
+      if (loaded <= MAX_LOADED_STORES) break;
+      if (!slot.store || slot.running || slot.gone || slot === keep) continue;
+      this.slots.delete(sessionId);
+      loaded--;
+      const writing: Promise<void> = slot.store
+        .then((store) => store.settle())
+        .catch((err) => {
+          console.warn(`[EditHistory] Saving the history of ${sessionId} failed:`, err);
+        })
+        .finally(() => {
+          if (this.unloading.get(sessionId) === writing) this.unloading.delete(sessionId);
+        });
+      this.unloading.set(sessionId, writing);
+    }
+  }
+
+  private async runLoop(session: EditHistorySession, slot: SessionSlot, want: SyncWant): Promise<void> {
+    let next: SyncWant | undefined = want;
+    while (next && !slot.gone) {
+      if (next.forward) await this.runOnce(session, slot, false);
+      if (next.older && !slot.gone) await this.runOnce(session, slot, true);
+      next = slot.again;
+      slot.again = undefined;
+    }
+  }
+
+  private async runOnce(session: EditHistorySession, slot: SessionSlot, older: boolean): Promise<void> {
+    let status: EditHistoryStatus;
+    try {
+      // This slot's store: a run still in flight after `remove()` cannot reach a later one.
+      const store = await this.storeOf(session.id, slot);
+      const path = slot.gone ? null : await this.deps.transcriptPath(session);
+      let found: boolean;
+      if (!path) {
+        found = false;
+      } else if (older) {
+        found = await this.readOlder(path, store, slot);
+      } else {
+        found = true;
+        for (let pass = 0; pass < MAX_FORWARD_PASSES && found && !slot.gone; pass++) {
+          const r = await this.readForward(path, store);
+          found = r.found;
+          if (!r.more) break;
+        }
+      }
+      status = found ? { state: 'ok' } : { state: 'unavailable', reason: NO_TRANSCRIPT };
+    } catch (err) {
+      status = { state: 'unavailable', reason: err instanceof Error ? err.message : String(err) };
+    }
+    if (!slot.gone) slot.status = status;
+  }
+
+  private forwardRequests(store: EditHistoryStore): EditSourceRequest[] {
+    const out: EditSourceRequest[] = [];
+    for (const relPath of store.knownSources()) {
+      const c = store.getCursor(relPath);
+      if (c) out.push({ relPath, offset: c.offset });
+    }
+    return out;
+  }
+
+  /**
+   * One forward read of all sources. `more` = some file has unread bytes after it, or was cut
+   * short by the shared budget and left for the next pass. A transcript other than the stored
+   * one (`/clear`, resume) is read like a first read, once the stored one is read to its end.
+   */
+  private async readForward(path: string, store: EditHistoryStore): Promise<{ found: boolean; more: boolean }> {
+    const own = this.storedTranscript(path, store);
+    if (own !== path && store.knownSources().length > 0) {
+      const previous = await this.readFrom(own, store, this.forwardRequests(store));
+      if (previous.more) return { found: true, more: true };
+    }
+    return this.readFrom(path, store, own === path ? this.forwardRequests(store) : []);
+  }
+
+  /**
+   * The path of the conversation the store holds cursors for: `path` itself, or the previous
+   * conversation's transcript next to it (`/clear` and resume keep the project directory).
+   */
+  private storedTranscript(path: string, store: EditHistoryStore): string {
+    const known = store.getTranscriptId();
+    return known === null || basename(path) === `${known}.jsonl` ? path : join(dirname(path), `${known}.jsonl`);
+  }
+
+  private async readFrom(
+    path: string,
+    store: EditHistoryStore,
+    requests: EditSourceRequest[]
+  ): Promise<{ found: boolean; more: boolean }> {
+    const res = await this.deps.readSources(path, requests, this.budget);
+    if (!res) return { found: false, more: false };
+    this.dropMissing(store, requests, res);
+    for (const [agentId, text] of Object.entries(res.metas)) {
+      if (!store.hasAgentMeta(agentId)) store.setAgentMeta(agentId, text);
+    }
+    const requested = new Set(requests.map((r) => r.relPath));
+    let more = false;
+    const candidates: ImageCandidate[] = [];
+    let parsed = false;
+    for (const f of res.files) {
+      // Each file is up to one budget (8 MiB) of synchronous parsing: yield between them.
+      if (parsed) await breathe();
+      if (store.isRemoved()) break;
+      // A requested file reads on from its cursor, a new one its tail.
+      const available = requested.has(f.relPath) ? f.size - f.startOffset : f.size;
+      if (f.chunk.length < Math.min(this.budget, available)) {
+        more = true;
+        continue;
+      }
+      parsed = true;
+      const r = store.apply({
+        transcriptId: res.transcriptId,
+        source: f.relPath,
+        startOffset: f.startOffset,
+        chunk: f.chunk,
+        size: f.size,
+      });
+      candidates.push(...r.candidates);
+      if (f.startOffset + f.chunk.length < f.size) more = true;
+    }
+    await this.addImages(store, candidates);
+    return { found: true, more };
+  }
+
+  private async readOlder(path: string, store: EditHistoryStore, slot: SessionSlot): Promise<boolean> {
+    if (!store.backfillTruncated) return true;
+    // Older lines belong to the stored conversation, even before a forward read moved on.
+    path = this.storedTranscript(path, store);
+    const sources = store.sourcesWithOlder().sort();
+    if (sources.length === 0) return true;
+    // Take turns: start after the last source the previous click read.
+    const after = slot.olderAfter;
+    const first =
+      after === undefined
+        ? 0
+        : Math.max(
+            0,
+            sources.findIndex((s) => s > after)
+          );
+    const picked = [...sources.slice(first), ...sources.slice(0, first)].slice(0, MAX_OLDER_SOURCES);
+    const requests: EditSourceRequest[] = [];
+    for (const relPath of picked) {
+      const range = store.olderRange(relPath, this.budget);
+      if (range) requests.push({ relPath, offset: range.offset, len: range.len });
+    }
+    if (requests.length === 0) return true;
+    slot.olderAfter = picked[picked.length - 1];
+    const res = await this.deps.readSources(path, requests, this.budget * requests.length, { onlyRequested: true });
+    if (!res) return false;
+    if (res.transcriptId !== store.getTranscriptId()) return true;
+    this.dropMissing(store, requests, res);
+    const wanted = new Set(requests.map((r) => r.relPath));
+    const candidates: ImageCandidate[] = [];
+    let parsed = false;
+    for (const f of res.files) {
+      if (!wanted.has(f.relPath)) continue;
+      // Each file is up to one budget (8 MiB) of synchronous parsing: yield between them.
+      if (parsed) await breathe();
+      parsed = true;
+      if (slot.gone) return true;
+      const r = store.applyOlder({
+        transcriptId: res.transcriptId,
+        source: f.relPath,
+        startOffset: f.startOffset,
+        chunk: f.chunk,
+        size: f.size,
+      });
+      candidates.push(...r.candidates);
+    }
+    await this.addImages(store, candidates);
+    return true;
+  }
+
+  /** Requested files the reader no longer lists are gone: their cursors go too. */
+  private dropMissing(store: EditHistoryStore, requests: readonly EditSourceRequest[], res: EditSources): void {
+    const listed = new Set(res.files.map((f) => f.relPath));
+    for (const r of requests) if (!listed.has(r.relPath)) store.dropSource(r.relPath);
+  }
+
+  private async addImages(store: EditHistoryStore, candidates: readonly ImageCandidate[]): Promise<void> {
+    const paths = [...new Set(candidates.flatMap((c) => c.paths))];
+    // A removed store keeps nothing: do not probe agent-printed paths for it.
+    if (paths.length === 0 || store.isRemoved()) return;
+    let probes: Array<PathProbe | null>;
+    try {
+      probes = await this.deps.probe(paths);
+    } catch {
+      // The edits of this read are in; only its images are lost. The read itself succeeded.
+      return;
+    }
+    const byPath = new Map(paths.map((p, i) => [p, probes[i]]));
+    const newest = new Map<string, number>();
+    for (const e of store.list()) newest.set(e.path, Math.max(newest.get(e.path) ?? -Infinity, e.ts));
+    store.addImageEntries(
+      confirmImages(
+        candidates,
+        (p) => byPath.get(p),
+        (p) => newest.get(p)
+      )
+    );
+  }
+}

src/web/ports/session-port.ts

@@ -24,6 +24,11 @@ export interface SessionPort {
    */
   addSession(session: Session, placement?: SessionPlacementHint): Promise<TabLayout>;
   cleanupSession(sessionId: string, killMux?: boolean, reason?: string): Promise<void>;
+  /**
+   * Delete a session's stored edit history once its record is gone. `cleanupSession` does it
+   * itself; this is for removing a record without a live session (DELETE route).
+   */
+  forgetEditHistory(sessionId: string): void;
   setupSessionListeners(session: Session): Promise<void>;
   persistSessionState(session: Session): void;
   persistSessionStateNow(session: Session): void;

src/web/public/app.js

@@ -286,6 +286,10 @@ const _SSE_HANDLER_MAP = [
   [SSE_EVENTS.IMAGE_DETECTED, '_onImageDetected'],
   [SSE_EVENTS.ATTACHMENT_DETECTED, '_onAttachmentDetected'],
 
+  // Edit history (edit-history-ui.js): an open panel follows its session's tool ends
+  // (and its turn ends, from _onSessionIdle: one handler per event in this map)
+  [SSE_EVENTS.TRANSCRIPT_TOOL_END, '_onEditHistoryTranscriptEvent'],
+
   // Tunnel
   [SSE_EVENTS.TUNNEL_STARTED, '_onTunnelStarted'],
   [SSE_EVENTS.TUNNEL_STOPPED, '_onTunnelStopped'],
@@ -3587,6 +3591,9 @@ class CodemanApp {
       this.sendPendingCtrlL(data.id);
       if (data.id === this.activeSessionId) this._updateLocalEchoState();
     }
+    // An open Edit history panel re-reads at the end of its session's turn (edit-history-ui.js),
+    // not after Codeman's own keep-alive turn, which edits nothing.
+    if (!data.keepAlive) this.onEditHistorySessionIdle?.(data.id);
     // Start stuck detection timer (only if no respawn running). Not at the end of Codeman's
     // own keep-alive turn (`keepAlive`): the session has been waiting since the last real
     // turn, whose timer is still running or has already fired.
@@ -10008,6 +10015,8 @@ class CodemanApp {
     // Remote-host reachability banner: only meaningful for a remote session, so this
     // also clears it when the newly active tab is local.
     this.refreshHostWakeBanner?.(sessionId);
+    // An open Edit history panel follows the active session (edit-history-ui.js; no poll).
+    this.onEditHistoryActiveSession?.(sessionId);
 
     // Restore flushed offset AND text IMMEDIATELY so backspace/typing work during
     // the async buffer load.  Without this, the offset is 0 during the

src/web/public/edit-history-ui.js

@@ -0,0 +1,630 @@
+/**
+ * @fileoverview Edit history: a header button (next to Attachments) and the floating panel it opens
+ * right below, listing every file edit the ACTIVE session's agent (and its subagents) made, newest
+ * first.
+ *
+ * OPTIONAL and per-device: `showEditHistory` (App Settings → Header & Panels → Header), default
+ * OFF. While it is off the button never shows and nothing is requested. The panel DRIVES the
+ * server's reading, which never runs in the background: it reads
+ * `GET /api/sessions/:id/edits?sync=1` when it opens and when the active session changes, and,
+ * only while it is open, re-reads (debounced) on the active session's `transcript:tool_end` for a
+ * tool that can change files (the existing transcript watcher's event) and on its `session:idle`
+ * (the end of a turn). No poll, and nothing at all while the panel is closed.
+ *
+ * - A code entry opens its diff inline (`GET /api/sessions/:id/edits/:entryId`), drawn with the Git
+ *   panel's diff classes (`git-diff`, `git-diff-line--hunk|add|del`).
+ * - An image entry opens the shared file preview (panels-ui.js `openFilePreview`), as does a click
+ *   on any path; inside the workspace it also shows a thumbnail. Both go through the existing file
+ *   routes only: the thumbnail is the confined `file-raw`, and the preview of a file outside the
+ *   workspace registers it on click with `notify: false` (`_registerExternalPreview`, which
+ *   enforces the attachment guard and its extension allowlist). A path from the transcript is
+ *   never served by a route of its own.
+ * - `backfillTruncated` offers "Load older" (`POST /api/sessions/:id/edits/older`).
+ *
+ * Paths, agent descriptions and diffs are untrusted text: they are only ever written with
+ * `textContent`, never `innerHTML`.
+ *
+ * @mixin Extends CodemanApp.prototype via Object.assign
+ * @dependency app.js (this.activeSessionId, this.sessions, this.loadAppSettingsFromStorage, this.getDefaultSettings, this.$)
+ * @dependency api-client.js (this._api, this._apiJson; resolved at call time)
+ * @dependency panels-ui.js (openFilePreview, _isExternalPreviewPath)
+ * @dependency i18n.js (window.codemanT)
+ * @loadorder 12.58 of 16, after git-status-ui.js, before entrance-animations.js
+ */
+
+/** SSE bursts (one event per tool call) collapse into one read. */
+const EDIT_HISTORY_SSE_DEBOUNCE_MS = 600;
+/** Tools whose end can mean changed files (Agent/Task: a subagent's edits; SendUserFile: an image). */
+const EDIT_HISTORY_FOLLOW_TOOLS = new Set([
+  'Edit',
+  'Write',
+  'MultiEdit',
+  'NotebookEdit',
+  'Bash',
+  'Agent',
+  'Task',
+  'SendUserFile',
+]);
+/** Per-device view toggles (a viewer convenience, so plain localStorage). */
+const EDIT_HISTORY_GROUP_KEY = 'codeman-edit-history-group';
+const EDIT_HISTORY_MAIN_ONLY_KEY = 'codeman-edit-history-main-only';
+
+Object.assign(CodemanApp.prototype, {
+  /** Per-device setting, default OFF. */
+  isEditHistoryEnabled() {
+    const settings = this.loadAppSettingsFromStorage();
+    const defaults = this.getDefaultSettings();
+    return (settings.showEditHistory ?? defaults.showEditHistory ?? false) === true;
+  },
+
+  /** Translate an English source string (i18n.js), with `{var}` interpolation. */
+  _eht(source, vars) {
+    if (typeof window.codemanT === 'function') return window.codemanT(source, vars);
+    return vars ? source.replace(/\{(\w+)\}/g, (m, k) => (k in vars ? String(vars[k]) : m)) : source;
+  },
+
+  /** A row badge ("new"/"edit") through its scoped i18n key; English shows the bare word. */
+  _ehBadge(word) {
+    const key = `Edit history badge: ${word}`;
+    const out = this._eht(key);
+    return out === key ? word : out;
+  },
+
+  /** Called from applyHeaderVisibilitySettings() (boot and every settings save). */
+  applyEditHistoryVisibility() {
+    const on = this.isEditHistoryEnabled();
+    // Marker class, not [hidden]: the base rule is display:inline-flex !important (src/web/CLAUDE.md).
+    this.$('editHistoryBtn')?.classList.toggle('btn-edit-history--hidden', !on);
+    if (!on) {
+      this.closeEditHistoryPanel();
+      this._editHistory = null;
+      this._editHistoryEpoch = (this._editHistoryEpoch || 0) + 1; // an in-flight read must not repaint
+      clearTimeout(this._editHistoryDebounce);
+      this._editHistoryDebounce = null;
+    }
+  },
+
+  // ── Per-device view toggles ─────────────────────────────────────────────
+
+  _editHistoryPref(key) {
+    try {
+      return localStorage.getItem(key) === '1';
+    } catch {
+      return false;
+    }
+  },
+
+  _setEditHistoryPref(key, on) {
+    try {
+      localStorage.setItem(key, on ? '1' : '0');
+    } catch {
+      /* private window / blocked storage: the toggle still works for this page */
+    }
+  },
+
+  isEditHistoryGrouped() {
+    return this._editHistoryGroupOn ?? (this._editHistoryGroupOn = this._editHistoryPref(EDIT_HISTORY_GROUP_KEY));
+  },
+
+  isEditHistoryMainOnly() {
+    return this._editHistoryMainOnly ?? (this._editHistoryMainOnly = this._editHistoryPref(EDIT_HISTORY_MAIN_ONLY_KEY));
+  },
+
+  setEditHistoryGrouped(on) {
+    this._editHistoryGroupOn = !!on;
+    this._setEditHistoryPref(EDIT_HISTORY_GROUP_KEY, !!on);
+    this._renderEditHistoryPanel();
+  },
+
+  setEditHistoryMainOnly(on) {
+    this._editHistoryMainOnly = !!on;
+    this._setEditHistoryPref(EDIT_HISTORY_MAIN_ONLY_KEY, !!on);
+    this._renderEditHistoryPanel();
+  },
+
+  // ── Data ────────────────────────────────────────────────────────────────
+
+  /** The data for the session on screen, or null. */
+  _currentEditHistory() {
+    const h = this._editHistory;
+    return h && h.sessionId === this.activeSessionId ? h : null;
+  },
+
+  _editHistoryBase(sid) {
+    return `/api/sessions/${encodeURIComponent(sid)}/edits`;
+  },
+
+  /**
+   * Read the active session's history and repaint. `older` asks the server for entries before the
+   * backfill window (POST), otherwise the normal read. Answers for another session are dropped.
+   */
+  async refreshEditHistory({ older = false } = {}) {
+    if (!this.isEditHistoryEnabled()) return;
+    const sid = this.activeSessionId || null;
+    if (!sid) {
+      this._editHistory = null;
+      this._renderEditHistoryPanel();
+      return;
+    }
+    const epoch = (this._editHistoryEpoch = (this._editHistoryEpoch || 0) + 1);
+    const prev = this._currentEditHistory();
+    if (!prev) {
+      // Another session's list must not stay on screen while this one loads.
+      this._editHistory = { sessionId: sid, state: 'loading', data: null, diffs: new Map(), open: new Set() };
+      this._renderEditHistoryPanel();
+    } else if (older) {
+      prev.loadingOlder = true;
+      this._renderEditHistoryPanel();
+    }
+    const base = this._editHistoryBase(sid);
+    const data = older
+      ? await this._apiJson(`${base}/older`, { method: 'POST', body: {} })
+      : await this._apiJson(`${base}?sync=1`);
+    if (epoch !== this._editHistoryEpoch || sid !== this.activeSessionId || !this.isEditHistoryEnabled()) return;
+    const cur = this._currentEditHistory() || {
+      sessionId: sid,
+      diffs: new Map(),
+      open: new Set(),
+    };
+    cur.loadingOlder = false;
+    if (data && typeof data === 'object') {
+      cur.state = 'ok';
+      cur.data = data;
+    } else if (!cur.data) {
+      cur.state = 'error';
+    }
+    this._editHistory = cur;
+    this._renderEditHistoryPanel();
+  },
+
+  loadOlderEditHistory() {
+    return this.refreshEditHistory({ older: true });
+  },
+
+  /**
+   * SSE `transcript:tool_end` ({ sessionId, toolName }), and the end of a turn through
+   * `onEditHistorySessionIdle`: while the panel is open on that session, re-read after a tool that
+   * can change files, and when the turn ends (a parallel tool call reports only one tool end; a
+   * background subagent writes after the tool end that started it). Closed: nothing.
+   */
+  _onEditHistoryTranscriptEvent(data) {
+    if (!data || data.sessionId !== this.activeSessionId || !this._isEditHistoryPanelOpen()) return;
+    if (data.toolName !== undefined && !EDIT_HISTORY_FOLLOW_TOOLS.has(data.toolName)) return;
+    if (!this.isEditHistoryEnabled()) return;
+    clearTimeout(this._editHistoryDebounce);
+    this._editHistoryDebounce = setTimeout(() => {
+      this._editHistoryDebounce = null;
+      if (this._isEditHistoryPanelOpen()) this.refreshEditHistory();
+    }, EDIT_HISTORY_SSE_DEBOUNCE_MS);
+  },
+
+  /**
+   * Called by app.js's `session:idle` handler ({ id }): the end of a turn. Claude's interactive
+   * transcript has no `result` line, so the transcript watcher's `transcript:complete` never fires
+   * for these sessions.
+   */
+  onEditHistorySessionIdle(sessionId) {
+    this._onEditHistoryTranscriptEvent({ sessionId });
+  },
+
+  /** Called by selectSession(): the open panel follows the active session. */
+  onEditHistoryActiveSession(sessionId) {
+    if (!this.isEditHistoryEnabled() || !this._isEditHistoryPanelOpen()) return;
+    if (this._editHistory?.sessionId === sessionId) return;
+    this.refreshEditHistory();
+  },
+
+  // ── Panel ───────────────────────────────────────────────────────────────
+
+  _isEditHistoryPanelOpen() {
+    return !!this.$('editHistoryPanel')?.classList.contains('visible');
+  },
+
+  toggleEditHistoryPanel() {
+    if (this._isEditHistoryPanelOpen()) {
+      this.closeEditHistoryPanel();
+      return;
+    }
+    const panel = this.$('editHistoryPanel');
+    if (!panel) return;
+    panel.classList.add('visible');
+    this.$('editHistoryBtn')?.setAttribute('aria-expanded', 'true');
+    const group = this.$('editHistoryGroupToggle');
+    if (group) group.checked = this.isEditHistoryGrouped();
+    const main = this.$('editHistoryMainOnlyToggle');
+    if (main) main.checked = this.isEditHistoryMainOnly();
+    this._ensureEditHistoryPanelDrag();
+    this._renderEditHistoryPanel();
+    this.refreshEditHistory();
+  },
+
+  closeEditHistoryPanel() {
+    const panel = this.$('editHistoryPanel');
+    if (panel) {
+      panel.classList.remove('visible');
+      // Reset a dragged position so it reopens at the default spot (a resized size is kept).
+      panel.style.left = panel.style.top = panel.style.right = panel.style.bottom = '';
+    }
+    this.$('editHistoryBtn')?.setAttribute('aria-expanded', 'false');
+    clearTimeout(this._editHistoryDebounce);
+    this._editHistoryDebounce = null;
+  },
+
+  /** Drag by the header (pointer events: mouse, pen and touch). One set of listeners per page. */
+  _ensureEditHistoryPanelDrag() {
+    const panel = this.$('editHistoryPanel');
+    const handle = panel?.querySelector('.edit-history-header');
+    if (!panel || !handle || handle._dragReady) return;
+    handle._dragReady = true;
+    let drag = null;
+    handle.addEventListener('pointerdown', (e) => {
+      if (e.target.closest('button')) return;
+      const rect = panel.getBoundingClientRect();
+      drag = { dx: e.clientX - rect.left, dy: e.clientY - rect.top };
+      // Switch from right/bottom anchoring to explicit left/top so the drag has one coordinate system.
+      panel.style.left = `${rect.left}px`;
+      panel.style.top = `${rect.top}px`;
+      panel.style.right = 'auto';
+      panel.style.bottom = 'auto';
+      // Pin the size too: the phone layout stretches between left and right, which a drag gives up.
+      panel.style.width = `${rect.width}px`;
+      panel.style.height = `${rect.height}px`;
+      handle.setPointerCapture?.(e.pointerId);
+      e.preventDefault();
+    });
+    handle.addEventListener('pointermove', (e) => {
+      if (!drag) return;
+      const maxX = window.innerWidth - panel.offsetWidth - 4;
+      const maxY = window.innerHeight - panel.offsetHeight - 4;
+      panel.style.left = `${Math.max(4, Math.min(e.clientX - drag.dx, maxX))}px`;
+      panel.style.top = `${Math.max(4, Math.min(e.clientY - drag.dy, maxY))}px`;
+    });
+    const end = (e) => {
+      drag = null;
+      handle.releasePointerCapture?.(e.pointerId);
+    };
+    handle.addEventListener('pointerup', end);
+    handle.addEventListener('pointercancel', end);
+  },
+
+  _ehEl(tag, className, text) {
+    const el = document.createElement(tag);
+    if (className) el.className = className;
+    if (text !== undefined) el.textContent = text;
+    return el;
+  },
+
+  /** "14:03:22", with the date in front when it is not today. */
+  _editHistoryTime(ts) {
+    const d = new Date(ts);
+    if (Number.isNaN(d.getTime())) return '';
+    const time = d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' });
+    return d.toDateString() === new Date().toDateString() ? time : `${d.toLocaleDateString()} ${time}`;
+  },
+
+  /** Open `path` in the shared file preview overlay (panels-ui.js). */
+  _openEditHistoryPreview(path) {
+    const sid = this.activeSessionId;
+    if (sid && path) this.openFilePreview?.(path, sid);
+  },
+
+  _editHistoryUrl(url) {
+    return typeof CodemanBase !== 'undefined' && CodemanBase.url ? CodemanBase.url(url) : url;
+  },
+
+  /**
+   * Thumbnail URL for an image entry inside the workspace: the confined `file-raw` route the file
+   * preview uses. An image outside the workspace gets none: showing it needs an attachment id
+   * (`POST …/attachments`, `notify: false`), and minting one per rendered row would push the
+   * session's real attachments out of its capped registry. Clicking it opens the file preview,
+   * which registers it like any other external file. SVGs get none either (`file-raw` serves
+   * them as a download).
+   */
+  _editHistoryThumbSrc(path, sid) {
+    if (!path || /\.svg$/i.test(path) || this._isExternalPreviewPath?.(path, sid) !== false) return null;
+    return this._editHistoryUrl(`/api/sessions/${encodeURIComponent(sid)}/file-raw?path=${encodeURIComponent(path)}`);
+  },
+
+  _renderEditHistoryPanel() {
+    const body = this.$('editHistoryBody');
+    const count = this.$('editHistoryCount');
+    if (!body || !this._isEditHistoryPanelOpen()) return;
+    const el = (tag, cls, text) => this._ehEl(tag, cls, text);
+    const t = (s, v) => this._eht(s, v);
+    const focusKey = body.contains(document.activeElement)
+      ? document.activeElement.closest?.('[data-edit-key]')?.dataset.editKey
+      : null;
+    const scroll = body.scrollTop;
+    body.replaceChildren();
+    if (count) count.textContent = '';
+
+    if (!this.activeSessionId) {
+      body.append(el('div', 'edit-history-empty', t('Open a session to see its edits.')));
+      return;
+    }
+    const h = this._currentEditHistory();
+    if (!h || h.state === 'loading') {
+      body.append(el('div', 'edit-history-empty', t('Reading the edit history…')));
+      return;
+    }
+    if (h.state === 'error' || !h.data) {
+      body.append(el('div', 'edit-history-empty', t('Could not read the edit history.')));
+      return;
+    }
+    const data = h.data;
+    if (data.state === 'unsupported') {
+      body.append(el('div', 'edit-history-empty', t('Edit history is only available for local Claude sessions.')));
+      return;
+    }
+    if (data.state === 'unavailable') {
+      body.append(
+        el(
+          'div',
+          'edit-history-note edit-history-note--warn',
+          data.reason === 'no-transcript'
+            ? t(
+                'No transcript found for this session yet. It is picked up with the next prompt; until then a CLAUDE_CONFIG_DIR set outside Codeman cannot be found.'
+              )
+            : t('Showing saved entries only: {reason}', { reason: data.reason || '' })
+        )
+      );
+    }
+
+    const all = Array.isArray(data.entries) ? data.entries : [];
+    const entries = this.isEditHistoryMainOnly() ? all.filter((e) => !e.agentId) : all;
+    if (count) count.textContent = all.length ? String(entries.length) : '';
+    if (!all.length) {
+      body.append(el('div', 'edit-history-empty', t('No edits yet.')));
+    } else if (!entries.length) {
+      body.append(el('div', 'edit-history-empty', t('No edits by the main agent.')));
+    } else if (this.isEditHistoryGrouped()) {
+      const groups = new Map();
+      for (const e of entries) {
+        const key = e.path || e.relPath;
+        if (!groups.has(key)) groups.set(key, []);
+        groups.get(key).push(e);
+      }
+      for (const items of groups.values()) body.append(this._editHistoryGroup(items, data, h));
+    } else {
+      const list = el('div', 'edit-history-list');
+      for (const e of entries) list.append(...this._editHistoryEntry(e, data, h, true));
+      body.append(list);
+    }
+
+    if (data.backfillTruncated) {
+      const more = el(
+        'button',
+        'btn-toolbar btn-sm edit-history-older',
+        h.loadingOlder ? t('Loading older edits…') : t('Load older')
+      );
+      more.type = 'button';
+      more.disabled = !!h.loadingOlder;
+      more.addEventListener('click', () => this.loadOlderEditHistory());
+      body.append(more);
+    }
+
+    body.scrollTop = scroll;
+    if (focusKey) {
+      const again = [...body.querySelectorAll('[data-edit-key]')].find((n) => n.dataset.editKey === focusKey);
+      again?.focus({ preventScroll: true });
+    }
+  },
+
+  /** One file with all its edits (newest first), for the "group by file" view. */
+  _editHistoryGroup(items, data, h) {
+    const el = (tag, cls, text) => this._ehEl(tag, cls, text);
+    const first = items[0];
+    const group = el('section', 'edit-history-group');
+    const head = el('div', 'edit-history-group-head');
+    head.append(this._editHistoryPathButton(first));
+    const code = items.filter((e) => e.kind !== 'image');
+    if (code.length) {
+      const added = code.reduce((s, e) => s + (Number(e.added) || 0), 0);
+      const removed = code.reduce((s, e) => s + (Number(e.removed) || 0), 0);
+      head.append(this._editHistoryStats(added, removed));
+    }
+    head.append(el('span', 'edit-history-group-count', String(items.length)));
+    group.append(head);
+    for (const e of items) group.append(...this._editHistoryEntry(e, data, h, false));
+    return group;
+  },
+
+  /**
+   * The path as folder + file name: the folder is cut from its start when the row is narrow, so a
+   * long absolute path (an image in claude's scratchpad) still shows which file it is.
+   */
+  _editHistoryPathButton(e) {
+    const shown = e.relPath || e.path || '';
+    const btn = this._ehEl('button', 'edit-history-path');
+    const cut = shown.lastIndexOf('/') + 1;
+    if (cut > 0) {
+      const dir = this._ehEl('span', 'edit-history-path-dir');
+      const bdi = this._ehEl('bdi', null, shown.slice(0, cut));
+      bdi.dir = 'ltr';
+      dir.append(bdi);
+      btn.append(dir);
+    }
+    btn.append(this._ehEl('span', 'edit-history-path-name', shown.slice(cut)));
+    btn.type = 'button';
+    btn.title = e.path || e.relPath || '';
+    btn.addEventListener('click', (ev) => {
+      ev.stopPropagation();
+      this._openEditHistoryPreview(e.path);
+    });
+    return btn;
+  },
+
+  _editHistoryStats(added, removed) {
+    const stats = this._ehEl('span', 'edit-history-stats');
+    stats.append(this._ehEl('span', 'edit-history-add', `+${added}`));
+    stats.append(this._ehEl('span', 'edit-history-del', `−${removed}`));
+    return stats;
+  },
+
+  /** A row, followed by its diff when the row is open. `withPath` false inside a file group. */
+  _editHistoryEntry(e, data, h, withPath) {
+    const el = (tag, cls, text) => this._ehEl(tag, cls, text);
+    const t = (s, v) => this._eht(s, v);
+    const isImage = e.kind === 'image';
+    const row = el('div', `edit-history-entry edit-history-entry--${isImage ? 'image' : 'code'}`);
+    row.dataset.editKey = e.id;
+    row.tabIndex = 0;
+    row.setAttribute('role', 'button');
+    row.append(el('span', 'edit-history-time', this._editHistoryTime(e.ts)));
+
+    let badge;
+    if (isImage) {
+      badge = el('span', 'edit-history-badge edit-history-badge--image');
+      const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+      svg.setAttribute('viewBox', '0 0 24 24');
+      svg.setAttribute('width', '12');
+      svg.setAttribute('height', '12');
+      svg.setAttribute('aria-hidden', 'true');
+      for (const [tag, attrs] of [
+        ['rect', { x: '3', y: '4', width: '18', height: '16', rx: '2' }],
+        ['circle', { cx: '9', cy: '10', r: '2' }],
+        ['path', { d: 'M21 17l-5-5-9 8' }],
+      ]) {
+        const n = document.createElementNS('http://www.w3.org/2000/svg', tag);
+        for (const [k, v] of Object.entries(attrs)) n.setAttribute(k, v);
+        svg.append(n);
+      }
+      badge.append(svg);
+      badge.title = t('Image');
+    } else if (e.created) {
+      badge = el('span', 'edit-history-badge edit-history-badge--new', this._ehBadge('new'));
+      badge.title = t('File created');
+    } else {
+      badge = el('span', 'edit-history-badge edit-history-badge--edit', this._ehBadge('edit'));
+      badge.title = t('File edited ({tool})', { tool: e.tool || '' });
+    }
+    row.append(badge);
+
+    if (withPath) row.append(this._editHistoryPathButton(e));
+    row.append(el('span', 'edit-history-spacer'));
+    if (!isImage) row.append(this._editHistoryStats(Number(e.added) || 0, Number(e.removed) || 0));
+
+    if (e.agentId) {
+      const agent = data.agents?.[e.agentId];
+      const chip = el('span', 'edit-history-agent', agent?.description || e.agentId);
+      const bits = [agent?.agentType, agent?.worktreeBranch].filter(Boolean);
+      chip.title = bits.join(' · ') || t('Subagent');
+      row.append(chip);
+    }
+
+    const out = [row];
+    if (isImage) {
+      row.title = t('Open in the file preview');
+      const open = () => this._openEditHistoryPreview(e.path);
+      row.addEventListener('click', open);
+      row.addEventListener('keydown', (ev) => {
+        if (ev.key === 'Enter' || ev.key === ' ') {
+          ev.preventDefault();
+          open();
+        }
+      });
+      const src = this._editHistoryThumbSrc(e.path, h.sessionId);
+      if (src) {
+        const img = el('img', 'edit-history-thumb');
+        img.loading = 'lazy';
+        img.alt = e.relPath || '';
+        img.addEventListener('click', (ev) => {
+          ev.stopPropagation();
+          open();
+        });
+        img.addEventListener('error', () => img.remove());
+        img.src = src;
+        out.push(img);
+      }
+      return out;
+    }
+
+    const isOpen = h.open.has(e.id);
+    row.setAttribute('aria-expanded', isOpen ? 'true' : 'false');
+    row.title = isOpen ? t('Hide the diff') : t('Show what changed');
+    const toggle = () => this.toggleEditHistoryDiff(e.id);
+    row.addEventListener('click', toggle);
+    row.addEventListener('keydown', (ev) => {
+      if (ev.key === 'Enter' || ev.key === ' ') {
+        ev.preventDefault();
+        toggle();
+      }
+    });
+    if (isOpen) {
+      row.classList.add('edit-history-entry--open');
+      out.push(this._editHistoryDiffView(h.diffs.get(e.id)));
+    }
+    return out;
+  },
+
+  /** Open or close one entry's diff; the first open loads it, later ones reuse it. */
+  async toggleEditHistoryDiff(entryId) {
+    const h = this._currentEditHistory();
+    if (!h) return;
+    if (h.open.has(entryId)) {
+      h.open.delete(entryId);
+      this._renderEditHistoryPanel();
+      return;
+    }
+    h.open.add(entryId);
+    const cached = h.diffs.get(entryId);
+    if (cached && cached.state !== 'error') {
+      this._renderEditHistoryPanel();
+      return;
+    }
+    const view = { state: 'loading' };
+    h.diffs.set(entryId, view);
+    this._renderEditHistoryPanel();
+    const res = await this._api(`${this._editHistoryBase(h.sessionId)}/${encodeURIComponent(entryId)}`);
+    let body = null;
+    try {
+      body = res ? await res.json() : null;
+    } catch {
+      /* fall through */
+    }
+    if (h.diffs.get(entryId) !== view) return;
+    if (res && res.ok && body?.success && typeof body.data?.diff === 'string') {
+      view.state = 'ok';
+      view.diff = body.data.diff;
+      view.truncated = !!body.data.truncated;
+    } else {
+      view.state = 'error';
+      view.error = body?.error || this._eht('Could not read the diff.');
+    }
+    if (this._editHistory === h) this._renderEditHistoryPanel();
+  },
+
+  /** The diff block under an open row, drawn with the Git panel's classes. */
+  _editHistoryDiffView(view) {
+    const el = (tag, cls, text) => this._ehEl(tag, cls, text);
+    const t = (s, v) => this._eht(s, v);
+    const wrap = el('div', 'edit-history-diff');
+    if (!view || view.state === 'loading') {
+      wrap.append(el('div', 'edit-history-empty', t('Reading the diff…')));
+      return wrap;
+    }
+    if (view.state === 'error') {
+      wrap.append(el('div', 'edit-history-empty', view.error));
+      return wrap;
+    }
+    if (!view.diff.trim()) {
+      wrap.append(el('div', 'edit-history-empty', t('No textual changes.')));
+    } else {
+      const pre = el('pre', 'git-diff');
+      const frag = document.createDocumentFragment();
+      for (const line of view.diff.replace(/\n$/, '').split('\n')) {
+        let cls = 'git-diff-line';
+        // The API sends hunks only (no `---`/`+++` headers), so a `---` line is a removed `--` line.
+        if (line.startsWith('@@')) cls += ' git-diff-line--hunk';
+        else if (line.startsWith('+')) cls += ' git-diff-line--add';
+        else if (line.startsWith('-')) cls += ' git-diff-line--del';
+        frag.append(el('span', cls, line + '\n'));
+      }
+      pre.append(frag);
+      wrap.append(pre);
+    }
+    if (view.truncated)
+      wrap.append(el('div', 'edit-history-more', t('Diff cut short: it is larger than the viewer shows.')));
+    return wrap;
+  },
+});

src/web/public/i18n.js

@@ -553,6 +553,39 @@
     'Fetch git status': '拉取 Git 状态',
     'Refresh git status': '刷新 Git 状态',
     'Close git status': '关闭 Git 状态',
+    // Edit history (edit-history-ui.js): settings chip, header button and panel.
+    // The two row badges use scoped keys: a bare "new"/"edit" key would also
+    // translate unrelated words elsewhere (the lookup is case-insensitive).
+    'Edit history': '编辑历史',
+    'Open edit history': '打开编辑历史',
+    'Refresh edit history': '刷新编辑历史',
+    'Close edit history': '关闭编辑历史',
+    'Group by file': '按文件分组',
+    'Main agent only': '仅主智能体',
+    'Open a session to see its edits.': '打开一个会话以查看其编辑。',
+    'Reading the edit history…': '正在读取编辑历史…',
+    'Could not read the edit history.': '无法读取编辑历史。',
+    'Edit history is only available for local Claude sessions.': '编辑历史仅适用于本地 Claude 会话。',
+    'Showing saved entries only: {reason}': '仅显示已保存的条目：{reason}',
+    'No transcript found for this session yet. It is picked up with the next prompt; until then a CLAUDE_CONFIG_DIR set outside Codeman cannot be found.':
+      '尚未找到此会话的记录。它会在下一次提示时被识别；在此之前，在 Codeman 之外设置的 CLAUDE_CONFIG_DIR 无法被找到。',
+    'No edits yet.': '暂无编辑。',
+    'No edits by the main agent.': '主智能体没有编辑。',
+    'Load older': '加载更早的编辑',
+    'Loading older edits…': '正在加载更早的编辑…',
+    'Edit history badge: new': '新建',
+    'Edit history badge: edit': '编辑',
+    'File created': '已创建文件',
+    'File edited ({tool})': '已编辑文件（{tool}）',
+    Image: '图片',
+    Subagent: '子智能体',
+    'Open in the file preview': '在文件预览中打开',
+    'Show what changed': '显示更改内容',
+    'Hide the diff': '隐藏差异',
+    'Reading the diff…': '正在读取差异…',
+    'Could not read the diff.': '无法读取差异。',
+    'No textual changes.': '没有文本更改。',
+    'Diff cut short: it is larger than the viewer shows.': '差异已截断：内容超出查看器可显示的范围。',
     Panels: '面板',
     Monitor: '监视器',
     'Project Insights': '项目洞察',

src/web/public/index.html

@@ -216,6 +216,13 @@
           <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>
           <span class="attachment-history-badge" id="attachmentHistoryBadge" style="display:none;">0</span>
         </button>
+        <!-- Edit history of the active session (edit-history-ui.js), next to Attachments: both show
+             what the session produced, and the panel opens right below. Optional and per-device
+             (App Settings → Header & Panels → Header, default OFF): hidden by its marker class,
+             never on phones (mobile.css). -->
+        <button type="button" class="btn-icon-header btn-edit-history btn-edit-history--hidden" id="editHistoryBtn" aria-expanded="false" aria-controls="editHistoryPanel" title="Edit history" aria-label="Open edit history" onclick="app.toggleEditHistoryPanel()">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/><path d="M3 3v5h5"/><path d="M12 7v5l4 2"/></svg>
+        </button>
         <button class="btn-icon-header btn-file-viewer" onclick="app.toggleFileBrowserButton()" title="File Viewer" aria-label="Open file viewer" aria-expanded="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path class="icon-folder-closed" d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><g class="icon-folder-open"><path d="M3 17V7a2 2 0 0 1 2-2h4l2 2h6a2 2 0 0 1 2 2v1.5"/><path d="M3 17l2.3-5.4A2 2 0 0 1 7.2 10.5H20a1.5 1.5 0 0 1 1.4 2l-1.9 5.2A2 2 0 0 1 17.6 19H5a2 2 0 0 1-2-2z"/></g></svg></button>
         <button class="btn-icon-header btn-multimonitor btn-multimonitor--hidden" onclick="app.launchMultiMonitor()" title="Open Codeman across all displays" aria-label="Open Codeman across all displays"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg></button>
         <button class="btn-icon-header btn-split btn-split--hidden" onclick="app.openSplitPicker(event)" title="Split: open a second session beside this one" aria-label="Split: open a second session beside this one" aria-pressed="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="3" width="20" height="18" rx="2"/><line x1="12" y1="3" x2="12" y2="21"/></svg></button>
@@ -633,6 +640,22 @@
       <div class="git-status-footer" id="gitStatusFooter" data-i18n-skip></div>
     </div>
 
+    <!-- Edit history panel (edit-history-ui.js): every file edit the active session's agents made. -->
+    <div class="edit-history-panel" id="editHistoryPanel" role="dialog" aria-label="Edit history">
+      <div class="edit-history-header">
+        <span class="edit-history-title">Edit history <span class="edit-history-count" id="editHistoryCount" data-i18n-skip></span></span>
+        <div class="edit-history-actions">
+          <button class="btn-icon-sm" onclick="app.refreshEditHistory()" title="Refresh" aria-label="Refresh edit history">&#x21BB;</button>
+          <button class="btn-icon-sm" onclick="app.closeEditHistoryPanel()" title="Close" aria-label="Close edit history">&times;</button>
+        </div>
+      </div>
+      <div class="edit-history-controls">
+        <label class="edit-history-toggle"><input type="checkbox" id="editHistoryGroupToggle" onchange="app.setEditHistoryGrouped(this.checked)"><span>Group by file</span></label>
+        <label class="edit-history-toggle"><input type="checkbox" id="editHistoryMainOnlyToggle" onchange="app.setEditHistoryMainOnly(this.checked)"><span>Main agent only</span></label>
+      </div>
+      <div class="edit-history-body" id="editHistoryBody" data-i18n-skip></div>
+    </div>
+
     <!-- File Preview Overlay -->
     <div class="file-preview-overlay" id="filePreviewOverlay">
       <div class="file-preview-window">
@@ -2205,6 +2228,7 @@
                     <label class="set-chip" data-preview="header" data-preview-order="5"><input type="checkbox" id="appSettingsShowAwayDigestButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M8 6h13"/><path d="M8 12h13"/><path d="M8 18h13"/><path d="M3 6h.01"/><path d="M3 12h.01"/><path d="M3 18h.01"/></svg><span>Away Digest</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="6"><input type="checkbox" id="appSettingsShowSessionButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="12 2 2 7 12 12 22 7 12 2"/><polyline points="2 17 12 22 22 17"/><polyline points="2 12 12 17 22 12"/></svg><span>Session Manager</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="9"><input type="checkbox" id="appSettingsShowAttachmentsButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg><span>Attachments</span></label>
+                    <label class="set-chip" data-search="edit history edits changed files diffs" data-preview="header" data-preview-order="9.5"><input type="checkbox" id="appSettingsShowEditHistory"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8"/><path d="M3 3v5h5"/><path d="M12 7v5l4 2"/></svg><span>Edit history</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="10"><input type="checkbox" id="appSettingsShowFileViewerButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg><span>File Viewer</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="11"><input type="checkbox" id="appSettingsShowMultiMonitorButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg><span>Multi-monitor</span></label>
                     <label class="set-chip" data-search="split pane side by side two sessions" data-preview="header" data-preview-order="11.5"><input type="checkbox" id="appSettingsShowSplitButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="3" width="20" height="18" rx="2"/><line x1="12" y1="3" x2="12" y2="21"/></svg><span>Split</span></label>
@@ -4641,6 +4665,7 @@
   <script defer src="mobile-overview.js"></script>
   <script defer src="home-sessions.js"></script>
   <script defer src="git-status-ui.js"></script>
+  <script defer src="edit-history-ui.js"></script>
   <script defer src="entrance-animations.js"></script>
   <script defer src="ralph-wizard.js"></script>
   <script defer src="api-client.js"></script>

src/web/public/mobile.css

@@ -586,6 +586,8 @@ html.mobile-init .file-browser-panel {
   .btn-icon-header.btn-away-digest,
   .btn-icon-header.btn-session-manager,
   .btn-icon-header.btn-file-viewer,
+  /* Edit history: a desktop panel; phones never show the button (opt-in, default OFF anyway). */
+  .btn-icon-header.btn-edit-history,
   /* Approvals bell: phones answer from the overview's NEEDS YOU rows instead
      (inline approve/deny in mobile-overview.js); the bell would only crowd the
      header it was designed to stay out of. */

src/web/public/settings-ui.js

@@ -610,6 +610,7 @@ Object.assign(CodemanApp.prototype, {
     // below and are not stripped from a save: a stripped key would never reach the scheduler.
     document.getElementById('appSettingsGitFetchEnabled').checked = settings.gitFetchEnabled === true;
     document.getElementById('appSettingsGitFetchIntervalSeconds').value = settings.gitFetchIntervalSeconds ?? 300;
+    document.getElementById('appSettingsShowEditHistory').checked = settings.showEditHistory ?? defaults.showEditHistory ?? false;
     // Gesture control lives in the Input section (alongside Local Echo / CJK Input)
     // but is only available when the instance runs with CODEMAN_GESTURE=1 (server sets
     // window.__codemanGestureAvailable). Hide just this item otherwise so the toggle
@@ -3158,6 +3159,7 @@ Object.assign(CodemanApp.prototype, {
         3600,
         Math.max(30, parseInt(document.getElementById('appSettingsGitFetchIntervalSeconds').value, 10) || 300)
       ),
+      showEditHistory: document.getElementById('appSettingsShowEditHistory').checked,
       gestureControlEnabled: document.getElementById('appSettingsGestureControl').checked,
       subagentTrackingEnabled: document.getElementById('appSettingsSubagentTracking').checked,
       subagentActiveTabOnly: document.getElementById('appSettingsSubagentActiveTabOnly').checked,
@@ -3465,6 +3467,8 @@ Object.assign(CodemanApp.prototype, {
       gitStatusTree: _gst,
       gitStatusMaxRepos: _gsm,
       gitStatusTimeoutSeconds: _gst2,
+      // Per-device header button (edit-history-ui.js), likewise absent from the .strict() schema.
+      showEditHistory: _seh,
       showTabDetachButton: _tdb,
       showTabNewButton: _tnb,
       // Detach Tiles: what a tile drag does is a property of this device's
@@ -4826,6 +4830,8 @@ Object.assign(CodemanApp.prototype, {
     // Bottom-bar Git indicator (git-status-ui.js): opt-in, per-device. Starts or stops its poll to
     // match the setting, so a live toggle needs no reload.
     this.applyGitStatusVisibility?.();
+    // Header Edit history button (edit-history-ui.js): opt-in, per-device, marker-class hidden.
+    this.applyEditHistoryVisibility?.();
 
     // Notification bell is retired (notifications live in Settings → Notifications
     // + the drawer); keep it hidden regardless of the notification-enabled state.
@@ -5189,7 +5195,7 @@ Object.assign(CodemanApp.prototype, {
       'language',
       'terminalWheelLocalScrollback',
       'autoCopySelection', 'copyStripMargin',
-      'showSessionButton', 'showAwayDigestButton', 'showCronButton', 'showGitStatus', 'gitStatusTree', 'gitStatusMaxRepos', 'gitStatusTimeoutSeconds',
+      'showSessionButton', 'showAwayDigestButton', 'showCronButton', 'showGitStatus', 'gitStatusTree', 'gitStatusMaxRepos', 'gitStatusTimeoutSeconds', 'showEditHistory',
       'showTabDetachButton',
       'showTabNewButton',
       'mobileOverviewEnabled',

src/web/public/styles.css

@@ -22679,6 +22679,297 @@ html .toolbar .btn-git-status[aria-expanded='true'] {
   font-size: 0.68rem;
 }
 
+/* ── Edit history: header button + panel (edit-history-ui.js) ───────────────── */
+
+/* "Edit history" header button — opt-in (App Settings → Header & Panels), hidden by default.
+   Same marker pattern as the Attachments button: a base inline-flex !important so an inline
+   style can't override it, and a more-specific marker rule to hide. Phones hide it regardless
+   (mobile.css). */
+.btn-edit-history {
+  display: inline-flex !important;
+}
+.btn-edit-history.btn-edit-history--hidden {
+  display: none !important;
+}
+
+.btn-edit-history[aria-expanded='true'] {
+  background: color-mix(in srgb, currentColor 16%, transparent);
+}
+
+/* Same frame as the Git and Files windows: draggable by the header, resizable at the corner. */
+.edit-history-panel {
+  position: fixed;
+  top: calc(var(--header-height) + 10px);
+  /* Left of the Git window's default spot; on a narrow viewport slide right so the left edge stays on screen. */
+  right: clamp(8px, calc(100vw - 428px), 410px);
+  width: 420px;
+  max-width: calc(100vw - 16px);
+  height: calc(100vh - var(--header-height) - var(--toolbar-height) - 40px);
+  height: calc(100dvh - var(--header-height) - var(--toolbar-height) - 40px);
+  max-height: 640px;
+  min-width: 260px;
+  min-height: 220px;
+  background: var(--floating-bg);
+  backdrop-filter: blur(20px);
+  -webkit-backdrop-filter: blur(20px);
+  border: 1px solid var(--control-border);
+  border-radius: 12px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4), 0 2px 8px rgba(0, 0, 0, 0.2);
+  z-index: 100;
+  display: none;
+  flex-direction: column;
+  overflow: hidden;
+  resize: both;
+}
+
+.edit-history-panel.visible {
+  display: flex;
+}
+
+.edit-history-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.4rem 0.6rem;
+  background: var(--bg-input);
+  border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+  cursor: move;
+  user-select: none;
+  touch-action: none;
+}
+
+.edit-history-title {
+  font-size: 0.8rem;
+  font-weight: 600;
+  color: var(--text);
+}
+
+.edit-history-count {
+  margin-left: 0.4rem;
+  font-family: 'SF Mono', Monaco, monospace;
+  font-size: 0.7rem;
+  font-weight: 400;
+  color: var(--text-muted);
+}
+
+.edit-history-actions {
+  display: flex;
+  gap: 0.25rem;
+}
+
+.edit-history-controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.3rem 0.9rem;
+  padding: 0.3rem 0.6rem;
+  border-bottom: 1px solid var(--border);
+  font-size: 0.68rem;
+  color: var(--text-muted);
+  flex-shrink: 0;
+}
+
+.edit-history-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.3rem;
+  cursor: pointer;
+}
+
+.edit-history-body {
+  flex: 1;
+  overflow-y: auto;
+  padding: 0.4rem 0.5rem;
+  font-size: 0.74rem;
+  color: var(--text);
+}
+
+.edit-history-empty,
+.edit-history-note,
+.edit-history-more {
+  color: var(--text-muted);
+  padding: 0.25rem 0;
+}
+
+.edit-history-note--warn {
+  color: #e0a030;
+}
+
+.edit-history-entry {
+  display: flex;
+  align-items: baseline;
+  gap: 0.45rem;
+  padding: 0.15rem 0.25rem;
+  border-radius: 4px;
+  min-width: 0;
+  cursor: pointer;
+}
+
+.edit-history-entry:hover,
+.edit-history-entry:focus-visible,
+.edit-history-entry--open {
+  background: var(--bg-hover);
+  outline: none;
+}
+
+.edit-history-time {
+  flex: 0 0 auto;
+  font-family: 'SF Mono', Monaco, monospace;
+  font-size: 0.64rem;
+  color: var(--text-muted);
+}
+
+.edit-history-badge {
+  flex: 0 0 auto;
+  min-width: 2rem;
+  text-align: center;
+  font-size: 0.6rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: #e0a030;
+}
+
+.edit-history-badge--new {
+  color: rgb(34, 197, 94);
+}
+
+.edit-history-badge--image {
+  color: var(--text-muted);
+  align-self: center;
+}
+
+.edit-history-badge--image svg {
+  display: block;
+  margin: 0 auto;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+/* Only the name itself opens the preview: the rest of the row (the spacer) toggles the diff. */
+/* The folder part gives way first, so the file name stays readable (…/icons/bremse_alt1.png). */
+.edit-history-path {
+  display: inline-flex;
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--text);
+  text-align: left;
+  font-family: 'SF Mono', Monaco, monospace;
+  font-size: 0.7rem;
+  cursor: pointer;
+}
+
+.edit-history-path-dir {
+  /* Shrinks long before the name does; the name only gives way once the folder is at min-width. */
+  flex: 0 10000 auto;
+  min-width: 1.2em;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  /* Ellipsis at the START of the folder (rtl); the inner <bdi dir="ltr"> keeps its text in order. */
+  direction: rtl;
+  text-align: left;
+  opacity: 0.7;
+}
+
+.edit-history-path-name {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.edit-history-path:hover,
+.edit-history-path:focus-visible {
+  text-decoration: underline;
+}
+
+.edit-history-spacer {
+  flex: 1;
+  align-self: stretch;
+  min-width: 0.5rem;
+  min-height: 1em;
+}
+
+.edit-history-stats {
+  flex: 0 0 auto;
+  display: inline-flex;
+  gap: 0.3rem;
+  font-family: 'SF Mono', Monaco, monospace;
+  font-size: 0.64rem;
+}
+
+.edit-history-add {
+  color: rgb(34, 197, 94);
+}
+
+.edit-history-del {
+  color: #e5534b;
+}
+
+.edit-history-agent {
+  flex: 0 1 auto;
+  max-width: 40%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  padding: 0 0.4rem;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  font-size: 0.62rem;
+  color: var(--text-muted);
+}
+
+.edit-history-thumb {
+  display: block;
+  max-width: 160px;
+  max-height: 90px;
+  margin: 0.15rem 0 0.35rem 3.2rem;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  object-fit: contain;
+  cursor: zoom-in;
+}
+
+.edit-history-diff {
+  margin: 0.2rem 0 0.5rem 0.25rem;
+}
+
+.edit-history-group {
+  margin-bottom: 0.45rem;
+  padding-bottom: 0.2rem;
+  border-bottom: 1px solid var(--border);
+}
+
+.edit-history-group-head {
+  display: flex;
+  align-items: baseline;
+  gap: 0.45rem;
+  padding: 0.2rem 0.25rem;
+  min-width: 0;
+}
+
+.edit-history-group-head .edit-history-path {
+  font-weight: 600;
+}
+
+.edit-history-group-count {
+  flex: 0 0 auto;
+  font-size: 0.64rem;
+  color: var(--text-muted);
+}
+
+.edit-history-older {
+  margin: 0.5rem auto 0.25rem;
+}
+
 /* ============================================================
    Tab grouping by state (tabArrangement: 'state', opt-in;
    Discussion #426 option C)

src/web/routes/edit-history-routes.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview The edit history panel's API: which files a claude session edited (main agent
+ * and subagents), each edit's diff, and Bash-generated images (src/web/edit-history-sync.ts).
+ *
+ *   GET  /api/sessions/:id/edits[?sync=1]   list (no diffs); `sync=1` reads what is new first
+ *   GET  /api/sessions/:id/edits/:entryId   one edit's diff as unified text
+ *   POST /api/sessions/:id/edits/older      read the next older block, then list
+ *
+ * Read-only, and reads only on these requests (the panel drives it; nothing syncs in the
+ * background). Remote, Docker and non-claude sessions answer `state: 'unsupported'`
+ * without being read. Ownership goes through `findSessionOrFail` with `req`, like every
+ * session-scoped route. No route here serves a file: an image entry is shown through the
+ * existing file routes (workspace `file-raw`, or the attachment routes outside it).
+ */
+
+import type { FastifyInstance } from 'fastify';
+import { ApiErrorCode, createErrorResponse, type ApiResponse } from '../../types.js';
+import { findSessionOrFail } from '../route-helpers.js';
+import type { SessionPort } from '../ports/index.js';
+import type { EditHistoryEntry, EditHistoryStore } from '../../edit-history-store.js';
+import type { EditHunk } from '../../edit-history-parse.js';
+import {
+  unsupportedReason,
+  type EditHistorySession,
+  type EditHistoryState,
+  type EditHistoryStatus,
+  type EditHistorySync,
+} from '../edit-history-sync.js';
+
+export interface EditHistoryListEntry extends Omit<EditHistoryEntry, 'hunks'> {
+  relPath: string;
+}
+
+export interface EditHistoryList {
+  state: EditHistoryState;
+  reason?: string;
+  backfillTruncated: boolean;
+  agents: Record<string, { description: string; agentType: string; worktreeBranch?: string }>;
+  entries: EditHistoryListEntry[];
+}
+
+export interface EditHistoryDiff {
+  diff: string;
+  truncated: boolean;
+}
+
+/** `path` relative to `base` when it lies below it, else unchanged. */
+export function relativeTo(path: string, base: string | undefined): string {
+  if (!base) return path;
+  const root = base.endsWith('/') ? base : `${base}/`;
+  return path.startsWith(root) ? path.slice(root.length) : path;
+}
+
+/** Hunks as unified diff text, the form the Git panel's renderer reads. */
+export function hunksToUnified(hunks: readonly EditHunk[]): string {
+  const out: string[] = [];
+  for (const h of hunks) {
+    out.push(`@@ -${h.oldStart},${h.oldLines} +${h.newStart},${h.newLines} @@`);
+    out.push(...h.lines);
+  }
+  return out.join('\n');
+}
+
+function listOf(
+  store: EditHistoryStore,
+  workingDir: string,
+  status: { state: EditHistoryState; reason?: string }
+): EditHistoryList {
+  const agents = store.getAgents();
+  const entries = store.list().map(({ hunks: _hunks, ...rest }) => ({
+    ...rest,
+    relPath: relativeTo(rest.path, (rest.agentId && agents[rest.agentId]?.worktreePath) || workingDir),
+  }));
+  const publicAgents: EditHistoryList['agents'] = {};
+  for (const [id, a] of Object.entries(agents)) {
+    publicAgents[id] = { description: a.description, agentType: a.agentType };
+    if (a.worktreeBranch) publicAgents[id].worktreeBranch = a.worktreeBranch;
+  }
+  const list: EditHistoryList = {
+    state: status.state,
+    backfillTruncated: store.backfillTruncated,
+    agents: publicAgents,
+    entries,
+  };
+  if (status.reason) list.reason = status.reason;
+  return list;
+}
+
+/** The answer for a session that is never read (remote, Docker, non-claude): no store involved. */
+function unsupportedList(reason: string): EditHistoryList {
+  return { state: 'unsupported', reason, backfillTruncated: false, agents: {}, entries: [] };
+}
+
+export function registerEditHistoryRoutes(app: FastifyInstance, ctx: SessionPort, sync: EditHistorySync): void {
+  const sessionOf = (id: string, req: Parameters<typeof findSessionOrFail>[2]) => {
+    const session = findSessionOrFail(ctx, id, req);
+    const view: EditHistorySession = {
+      id: session.id,
+      mode: session.mode,
+      remote: session.remote,
+      docker: session.docker,
+      claudeSessionId: session.claudeSessionId,
+      claudeConfigDir: session.claudeConfigDir(),
+    };
+    return { session, view };
+  };
+
+  app.get('/api/sessions/:id/edits', async (req): Promise<ApiResponse<EditHistoryList>> => {
+    const { id } = req.params as { id: string };
+    const { sync: doSync } = req.query as { sync?: string };
+    const { session, view } = sessionOf(id, req);
+    const why = unsupportedReason(view);
+    // Never read: answer an empty list without loading (or creating) a store for it.
+    if (why) return { success: true, data: unsupportedList(why) };
+    // The sync starts in the same tick as the session check: a deletion right after it marks
+    // the running sync gone (EditHistorySync.remove), so nothing writes a deleted session.
+    const status: EditHistoryStatus = doSync === '1' ? await sync.sync(view) : sync.getStatus(session.id);
+    return { success: true, data: listOf(await sync.getStore(session.id), session.workingDir, status) };
+  });
+
+  app.post('/api/sessions/:id/edits/older', async (req): Promise<ApiResponse<EditHistoryList>> => {
+    const { id } = req.params as { id: string };
+    const { session, view } = sessionOf(id, req);
+    const why = unsupportedReason(view);
+    if (why) return { success: true, data: unsupportedList(why) };
+    const status = await sync.sync(view, { older: true });
+    return { success: true, data: listOf(await sync.getStore(session.id), session.workingDir, status) };
+  });
+
+  app.get('/api/sessions/:id/edits/:entryId', async (req, reply): Promise<ApiResponse<EditHistoryDiff>> => {
+    const { id, entryId } = req.params as { id: string; entryId: string };
+    const { session, view } = sessionOf(id, req);
+    const entry = unsupportedReason(view) ? undefined : (await sync.getStore(session.id)).get(entryId);
+    if (!entry) {
+      reply.code(404);
+      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'No such edit in this session');
+    }
+    return { success: true, data: { diff: hunksToUnified(entry.hunks), truncated: entry.truncated } };
+  });
+}

src/web/routes/index.ts

@@ -16,6 +16,7 @@ export { registerInboxRoutes } from './inbox-routes.js';
 export { registerRebootRestoreRoutes } from './reboot-restore-routes.js';
 export { registerReadMyMindRoutes } from './readmymind-routes.js';
 export { registerGitStatusRoutes } from './git-status-routes.js';
+export { registerEditHistoryRoutes } from './edit-history-routes.js';
 export { registerStatusTelemetryRoutes } from './status-telemetry-routes.js';
 export { registerCaseRoutes } from './case-routes.js';
 export { registerWorktreeRoutes } from './worktree-routes.js';

src/web/routes/session-routes.ts

@@ -1729,7 +1729,8 @@ export function registerSessionRoutes(
       // Called for its existence/ownership 404 side effect only — demoteOrRemoveSession
       // below re-looks-up the record by id, so the returned SessionState is unused here.
       findPersistedSessionOrFail(ctx.store, id, req);
-      ctx.store.demoteOrRemoveSession(id);
+      // The edit history goes with the record (same rule as `cleanupSession`).
+      if (ctx.store.demoteOrRemoveSession(id) === 'removed') ctx.forgetEditHistory(id);
       // A detached session kept its agent inbox (server.ts _doCleanupSession drops it
       // only on killMux); retiring the row is the delete, so the mail goes now.
       agentInbox.drop(id);

src/web/routes/system-routes.ts

@@ -856,6 +856,7 @@ export function registerSystemRoutes(
       // Keeping a pane that died while detached errs toward the 12 h TTL and the boot
       // prune, the same trade the boot keep set makes.
       if (!ctx.mux.getSession(s.id)) agentInbox.drop(s.id);
+      ctx.forgetEditHistory(s.id);
     }
     return { cleanedSessions: result.count };
   });

src/web/sensitive-path.ts

@@ -102,6 +102,10 @@ const SENSITIVE_PATTERNS: RegExp[] = [
   /\/\.codeman[^/]*\/intents\.json$/,
   // Pending agent-inbox messages (opt-in snapshot): same text as prompts, same 0600.
   /\/\.codeman[^/]*\/agent-inbox\.json$/,
+  // The edit history panel's stores (edit-history-store.ts) hold every diff an
+  // agent wrote, keys and .env contents included; written 0600 and kept out of
+  // /api/search for the same reason as intents.json.
+  /\/\.codeman[^/]*\/edit-history\//,
 ];
 
 /**

src/web/server.ts

@@ -137,6 +137,9 @@ import { probePathKind } from '../utils/bounded-path-probe.js';
 import { defaultDockerWorkspaces } from './routes/git-status-routes.js';
 import { composerIsEmpty, plainFrame } from '../session-submit-verifier.js';
 import { detectUsageLimitPause } from '../usage-limit-patterns.js';
+import { EditHistorySync } from './edit-history-sync.js';
+import { EditHistoryStore } from '../edit-history-store.js';
+import { probeLocalPaths, readClaudeEditSources, resolveClaudeTranscript } from '../edit-history-local-source.js';
 import { stopDeepSeekWeb } from '../deepseek-web-server.js';
 import {
   wireRespawnListeners,
@@ -222,6 +225,7 @@ import {
   registerRebootRestoreRoutes,
   registerReadMyMindRoutes,
   registerGitStatusRoutes,
+  registerEditHistoryRoutes,
   registerStatusTelemetryRoutes,
   registerSystemRoutes,
   registerCaseRoutes,
@@ -351,6 +355,24 @@ function getOrCreateSelfSignedCert(): { key: string; cert: string } {
 export class WebServer extends EventEmitter {
   private app: FastifyInstance;
   private sessions: Map<string, Session> = new Map();
+  /**
+   * The edit history panel's reader (edit-history-sync.ts). Reads only when the panel asks;
+   * the main transcript is the one the transcript watcher follows (hook-reported path), or,
+   * before the first hook after a restart, a lookup under the session's claude config dir.
+   */
+  private readonly editHistorySync = new EditHistorySync({
+    transcriptPath: (session) =>
+      resolveClaudeTranscript(
+        this.transcriptWatchers.get(session.id)?.getPath(),
+        [session.claudeSessionId || session.id, session.id],
+        session.claudeConfigDir
+      ),
+    readSources: readClaudeEditSources,
+    probe: probeLocalPaths,
+    loadStore: (sessionId) => EditHistoryStore.load(sessionId),
+    deleteStore: (sessionId) => EditHistoryStore.delete(sessionId),
+    sweepStores: (keep) => EditHistoryStore.sweep(keep),
+  });
   private respawnControllers: Map<string, RespawnController> = new Map();
   private respawnTimers: Map<string, { timer: NodeJS.Timeout; endAt: number; startedAt: number }> = new Map();
   private runSummaryTrackers: Map<string, RunSummaryTracker> = new Map();
@@ -902,6 +924,7 @@ export class WebServer extends EventEmitter {
       addSession: this.registerSessionWithLayout.bind(this),
       tabLayouts: this.tabLayouts,
       cleanupSession: this.cleanupSession.bind(this),
+      forgetEditHistory: this.forgetEditHistory.bind(this),
       setupSessionListeners: this.setupSessionListeners.bind(this),
       persistSessionState: this.persistSessionState.bind(this),
       persistSessionStateNow: this._persistSessionStateNow.bind(this),
@@ -1319,6 +1342,7 @@ export class WebServer extends EventEmitter {
     registerRebootRestoreRoutes(this.app, ctx);
     registerReadMyMindRoutes(this.app, ctx);
     registerGitStatusRoutes(this.app, ctx);
+    registerEditHistoryRoutes(this.app, ctx, this.editHistorySync);
     // Git fetch on an interval: this is only the wake-up, the scheduler itself decides what is due. Off in
     // tests for the same reason as the polls below: a test drives `tick()` directly instead of waiting on
     // a timer the harness would have to keep alive. The setting is read FRESH inside `tick()`, so turning
@@ -1831,7 +1855,8 @@ export class WebServer extends EventEmitter {
       // Only remove from state.json if we're also killing the mux session.
       // When killMux=false (server shutdown), preserve state for recovery.
       if (killMux) {
-        this.store.demoteOrRemoveSession(sessionId);
+        // The edit history goes with the record; a pinned session's demoted record keeps it.
+        if (this.store.demoteOrRemoveSession(sessionId) !== 'preserved') this.forgetEditHistory(sessionId);
       }
     }
 
@@ -2673,10 +2698,27 @@ export class WebServer extends EventEmitter {
     const lifecycleLog = getLifecycleLog();
     for (const s of result.cleaned) {
       lifecycleLog.log({ event: 'stale_cleaned', sessionId: s.id, name: s.name });
+      this.forgetEditHistory(s.id);
     }
+    // History files no session owns (a crash between removing a record and deleting its file).
+    const exists = (id: string) => this.sessions.has(id) || !!this.store.getSession(id);
+    await this.editHistorySync.sweep(exists).catch((err) => {
+      console.warn('[EditHistory] Sweeping orphaned histories failed:', getErrorMessage(err));
+    });
     return result.count;
   }
 
+  /**
+   * Delete a session's edit history (diffs can hold secrets) once its record is gone: deleted
+   * live (`cleanupSession`), deleted as a record only (DELETE route), or cleaned as stale
+   * (startup, `POST /api/cleanup-state`).
+   */
+  private forgetEditHistory(sessionId: string): void {
+    void this.editHistorySync.remove(sessionId).catch((err) => {
+      console.warn(`[EditHistory] Removing history of ${sessionId} failed:`, getErrorMessage(err));
+    });
+  }
+
   /**
    * Get lightweight state for SSE init - excludes full terminal buffers
    * to prevent browser freezes. Terminal buffers are fetched on-demand.
@@ -4622,6 +4664,9 @@ export class WebServer extends EventEmitter {
     this.respawnTimers.clear();
     this.runSummaryTrackers.clear();
     this.transcriptWatchers.clear();
+    await this.editHistorySync.flushAll().catch((err) => {
+      console.warn('[EditHistory] Saving on shutdown failed:', getErrorMessage(err));
+    });
     this.sessionListenerRefs.clear();
     this.scheduledRuns.clear();
     // Dispose StaleExpirationMaps (stops internal cleanup timers)