@hienlh/ppm 0.23.12 → 0.23.14

package/src/services/session-file-baselines/session-file-changes.service.ts

@@ -0,0 +1,321 @@
+/**
+ * What a chat session has changed, file by file: its "before" against the file on disk now.
+ *
+ * The before is the session's own copy (`session-file-baselines.service.ts`) when it has one.
+ * A session older than those copies, or a file it changed in some way that took none, falls
+ * back to the file at git HEAD — but only inside the project, because outside it there is no
+ * reason to trust a path the browser names. Every read goes through the same guard as the
+ * generic file routes, so a credential file is never served.
+ *
+ * A file whose before and after are the same — edited and then put back, or a write that
+ * failed — has no change to review and is left out.
+ *
+ * A file the user marked reviewed (`session-review-marks.ts`) is still listed, flagged, so the
+ * browser can hide it; once it changes again it is compared with the state it was marked in
+ * rather than with its "before", so only what is new is left to read.
+ *
+ * Each text file is also cut into change blocks (`src/shared/review-blocks.ts`), flagged with
+ * the ones the user kept (`session-review-blocks.ts`); a file marked reviewed has every block
+ * kept. Keeping, reverting and undoing those answers is `session-review-actions.ts`.
+ */
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import simpleGit from "simple-git";
+import { decodeText, isBinaryContent } from "../binary-content.ts";
+import { assertReadPermitted } from "../fs-ops/fs-ops-read-write.service.ts";
+import { realPathOrSelf } from "../fs-ops/fs-real-path.ts";
+import { getBranchRow } from "../session-branch.service.ts";
+import { BASELINE_MAX_BYTES, listBaselines, readBaseline, type FileBaseline } from "./session-file-baselines.service.ts";
+import { clearReviewMark, findReviewMark, writeReviewMark, type ReviewMark } from "./session-review-marks.ts";
+import { hashBase, keptBlocks } from "./session-review-blocks.ts";
+import { blockCalls } from "./session-file-blame.ts";
+import { computeBlocks, type BlockDiff } from "../../shared/review-blocks.ts";
+import type {
+  SessionChangeStatus,
+  SessionFileChange,
+  SessionFileDiff,
+  SessionReviewResult,
+} from "../../shared/session-file-changes.ts";
+
+/** More than any session plausibly touches; a bigger request is cut, not refused. */
+export const MAX_SESSION_CHANGE_PATHS = 500;
+
+/** How far up a chain of edited versions and forks a missing "before" is looked for. */
+const MAX_ANCESTORS = 20;
+
+export type { SessionChangeStatus, SessionFileChange, SessionFileDiff, SessionReviewResult };
+
+/** One side of a comparison: absent, text, or something that cannot be shown as text. */
+type Present = { exists: true; text?: string; binary?: boolean; tooLarge?: boolean; version?: string; hash?: string };
+export type Side = { exists: false } | Present;
+
+/**
+ * The session and every session it was branched from, nearest first. An edited version or a
+ * fork carries its parent's history, and files are not rewound when one is made, so the
+ * parent's "before" is this session's too.
+ */
+export function lineage(sessionId: string): string[] {
+  const out = [sessionId];
+  let current = sessionId;
+  for (let i = 0; i < MAX_ANCESTORS; i++) {
+    const parent = getBranchRow(current)?.parent_id;
+    if (!parent || out.includes(parent)) break;
+    out.push(parent);
+    current = parent;
+  }
+  return out;
+}
+
+function findBaseline(chain: string[], path: string): FileBaseline | null {
+  for (const id of chain) {
+    const found = readBaseline(id, path);
+    if (found) return found;
+  }
+  return null;
+}
+
+function sideFromBaseline(b: FileBaseline): Side {
+  if (!b.existed) return { exists: false };
+  return { exists: true, text: b.content, binary: b.binary, tooLarge: b.tooLarge };
+}
+
+function sideFromBytes(bytes: Uint8Array): Present {
+  if (bytes.length > BASELINE_MAX_BYTES) return { exists: true, tooLarge: true };
+  if (isBinaryContent(bytes)) return { exists: true, binary: true };
+  return { exists: true, text: decodeText(bytes) };
+}
+
+/** The file on disk now, through the generic read guard. A refused path throws. */
+async function readCurrent(path: string): Promise<Side> {
+  assertReadPermitted(path, await realPathOrSelf(path));
+  try {
+    const st = await stat(path);
+    if (!st.isFile()) return { exists: false };
+    const version = `${st.size}:${st.mtimeMs}`;
+    if (st.size > BASELINE_MAX_BYTES) return { exists: true, tooLarge: true, version };
+    const bytes = await readFile(path);
+    return { ...sideFromBytes(bytes), version, hash: createHash("sha256").update(bytes).digest("hex") };
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT" || (e as NodeJS.ErrnoException).code === "ENOTDIR") {
+      return { exists: false };
+    }
+    throw e;
+  }
+}
+
+/** Repository roots by directory, for one request: a session's files share a few. */
+export type RepoCache = Map<string, Promise<string | null>>;
+
+function repoTop(dir: string, cache: RepoCache): Promise<string | null> {
+  let found = cache.get(dir);
+  if (!found) {
+    // simple-git refuses a directory that does not exist, as a deleted file's may not.
+    let existing = dir;
+    while (!existsSync(existing) && dirname(existing) !== existing) existing = dirname(existing);
+    found = simpleGit(existing).revparse(["--show-toplevel"]).then((t) => t.trim() || null, () => null);
+    cache.set(dir, found);
+  }
+  return found;
+}
+
+/**
+ * The bytes HEAD holds at `rel`: null when it holds nothing there, undefined when what it holds
+ * is no file's content — a symbolic link's blob is only the name it points to, so it is no
+ * "before" for the file that name reaches.
+ */
+async function headBlob(top: string, rel: string): Promise<Uint8Array | null | undefined> {
+  const git = simpleGit(top);
+  const listed = await git.raw(["ls-tree", "-z", "HEAD", "--", rel]).catch(() => "");
+  const entry = listed.split("\0").find((line) => line.slice(line.indexOf("\t") + 1) === rel);
+  if (!entry) return null;
+  if (!/^100(644|755) blob /.test(entry)) return undefined;
+  return git.showBuffer([`HEAD:${rel}`]).catch(() => null);
+}
+
+/** The file at git HEAD in whatever repository holds it; null when no repository does, or HEAD holds no file there. */
+async function readHead(path: string, cache: RepoCache): Promise<Side | null> {
+  const top = await repoTop(dirname(path), cache);
+  if (!top) return null;
+  const rel = relative(top, path).split(sep).join("/");
+  if (!rel || rel.startsWith("../")) return null;
+  const bytes = await headBlob(top, rel);
+  if (bytes === undefined) return null;
+  return bytes ? sideFromBytes(bytes) : { exists: false };
+}
+
+/** The file's bytes at git HEAD, for putting back a file that has no text to diff; null when no repository has it. */
+export async function headBytes(path: string): Promise<Uint8Array | null> {
+  const top = await repoTop(dirname(path), new Map());
+  if (!top) return null;
+  const rel = relative(top, path).split(sep).join("/");
+  if (!rel || rel.startsWith("../")) return null;
+  return (await headBlob(top, rel)) ?? null;
+}
+
+function isInside(root: string, path: string): boolean {
+  const rel = relative(root, path);
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+export interface Compared {
+  change: SessionFileChange;
+  /** What the change is counted and diffed against: the "before", or the state marked reviewed. */
+  before: Side;
+  after: Side;
+  /**
+   * The blocks between the two, or null when either side is not text or the diff would stall
+   * the server (a large file rewritten wholesale is the one case Myers' diff is slow at).
+   */
+  diff: BlockDiff | null;
+}
+
+function sideFromMark(mark: ReviewMark): Side {
+  if (!mark.existed) return { exists: false };
+  return { exists: true, text: mark.content, binary: mark.binary, tooLarge: mark.tooLarge };
+}
+
+/** Whether the file is still exactly as it was marked; past the size cap only its version can say. */
+function isAsMarked(mark: ReviewMark, now: Side): boolean {
+  if (!mark.existed || !now.exists) return !mark.existed && !now.exists;
+  return mark.hash && now.hash ? mark.hash === now.hash : mark.version === now.version;
+}
+
+/** How the session changed `path`, or null when it did not. A path the read guard refuses throws. */
+export async function compare(chain: string[], projectPath: string, path: string, repos: RepoCache = new Map()): Promise<Compared | null> {
+  const baseline = findBaseline(chain, path);
+  let before: Side | null = baseline ? sideFromBaseline(baseline) : null;
+  if (!before && isInside(projectPath, path)) before = await readHead(path, repos);
+  if (!before) return null;
+  const after = await readCurrent(path);
+  if (!before.exists && !after.exists) return null;
+
+  const status: SessionChangeStatus = !before.exists ? "added" : !after.exists ? "deleted" : "modified";
+  const beforeText = before.exists ? before.text : "";
+  const afterText = after.exists ? after.text : "";
+  if (beforeText !== undefined && afterText !== undefined && status === "modified" && beforeText === afterText) return null;
+
+  // What is left to review: a file marked reviewed is hidden while it stays as marked, and
+  // counted against the state it was marked in once it has moved on.
+  const mark = findReviewMark(chain, path);
+  const reviewed = !!mark && isAsMarked(mark, after);
+  const base = mark && !reviewed ? sideFromMark(mark) : before;
+  const baseText = base.exists ? base.text : "";
+  const binary = (base.exists && base.binary) || (after.exists && after.binary) || undefined;
+  const tooLarge = (base.exists && base.tooLarge) || (after.exists && after.tooLarge) || undefined;
+
+  const version = after.exists ? after.version ?? "" : "";
+  const change: SessionFileChange = { path, status, baseline: baseline ? "session" : "head", version };
+  if (binary) change.binary = true;
+  if (tooLarge) change.tooLarge = true;
+  if (reviewed) change.reviewed = true;
+  else if (mark) change.sinceReview = true;
+  const diff = baseText !== undefined && afterText !== undefined ? computeBlocks(baseText, afterText) : null;
+  if (diff) {
+    change.additions = diff.additions;
+    change.deletions = diff.deletions;
+    const baseHash = hashBase(baseText!);
+    change.base = baseHash.slice(0, 16);
+    const kept = reviewed ? null : keptBlocks(chain, path, baseHash);
+    const calls = blockCalls({
+      sessionId: chain[0]!,
+      path,
+      baseText: baseText!,
+      currentText: afterText!,
+      blocks: diff.blocks,
+      ...(base !== before && mark ? { markedAt: Date.parse(mark.markedAt) } : {}),
+    });
+    change.blocks = diff.blocks.map((b, i) => ({
+      key: b.key,
+      added: b.added,
+      removed: b.removed,
+      ...(!kept || kept.has(b.key) ? { kept: true } : {}),
+      ...(calls?.[i]?.length ? { calls: calls[i] } : {}),
+    }));
+  }
+  return { change, before: base, after, diff };
+}
+
+/** Mark a file reviewed as it stands in `compared`. False when the mark could not be written. */
+export function markReviewed(sessionId: string, compared: Compared): boolean {
+  const { path } = compared.change;
+  const now = compared.after;
+  return now.exists
+    ? writeReviewMark(sessionId, { path, existed: true, content: now.text, binary: now.binary, tooLarge: now.tooLarge, hash: now.hash, version: now.version })
+    : writeReviewMark(sessionId, { path, existed: false });
+}
+
+/** Every file the session changed: those it kept a "before" for, then any other `paths`. */
+export async function sessionFileChanges(p: {
+  sessionId: string;
+  projectPath: string;
+  paths?: string[];
+}): Promise<SessionFileChange[]> {
+  const chain = lineage(p.sessionId);
+  const seen = new Set<string>();
+  const ordered: string[] = [];
+  const add = (raw: string) => {
+    if (!raw || ordered.length >= MAX_SESSION_CHANGE_PATHS) return;
+    const path = resolve(p.projectPath, raw);
+    if (seen.has(path)) return;
+    seen.add(path);
+    ordered.push(path);
+  };
+  for (const id of [...chain].reverse()) for (const b of listBaselines(id)) add(b.path);
+  for (const raw of p.paths ?? []) add(raw);
+
+  const out: SessionFileChange[] = [];
+  const repos: RepoCache = new Map();
+  for (const path of ordered) {
+    try {
+      const compared = await compare(chain, p.projectPath, path, repos);
+      if (compared) out.push(compared.change);
+    } catch {
+      // A path the guard refuses, or one that vanished mid-read, is simply not listed.
+    }
+  }
+  return out;
+}
+
+/** Both sides of one file, for the diff editor. Null when the session did not change it. */
+export async function sessionFileDiff(p: { sessionId: string; projectPath: string; path: string }): Promise<SessionFileDiff | null> {
+  const path = resolve(p.projectPath, p.path);
+  const compared = await compare(lineage(p.sessionId), p.projectPath, path, new Map());
+  if (!compared) return null;
+  const text = (side: Side) => (side.exists && side.text !== undefined ? side.text : "");
+  return { ...compared.change, original: text(compared.before), modified: text(compared.after) };
+}
+
+/**
+ * Mark files reviewed in the state the browser showed them in, or unmark them. A file is
+ * marked only while it is still one of the session's changes and still at the `version` that
+ * was shown: one the agent moved on since would otherwise be hidden with a change nobody has
+ * read. Those are named in `stale`, for the browser to ask again.
+ */
+export async function setSessionFilesReviewed(p: {
+  sessionId: string;
+  projectPath: string;
+  files: { path: string; version: string }[];
+  reviewed: boolean;
+}): Promise<SessionReviewResult> {
+  const chain = lineage(p.sessionId);
+  const repos: RepoCache = new Map();
+  const updated: string[] = [];
+  const stale: string[] = [];
+  for (const file of p.files.slice(0, MAX_SESSION_CHANGE_PATHS)) {
+    const path = resolve(p.projectPath, file.path);
+    if (!p.reviewed) {
+      if (clearReviewMark(p.sessionId, chain, path)) updated.push(path);
+      continue;
+    }
+    // A path the read guard refuses is no change of the session's, as it is not listed either.
+    const compared = await compare(chain, p.projectPath, path, repos).catch(() => null);
+    if (!compared || compared.change.version !== file.version) {
+      stale.push(path);
+      continue;
+    }
+    (markReviewed(p.sessionId, compared) ? updated : stale).push(path);
+  }
+  return { updated, stale };
+}

package/src/services/session-file-baselines/session-file-history.ts

@@ -0,0 +1,347 @@
+/**
+ * Every state a file passed through in a chat session, call by call: what tells which turn
+ * wrote a block of the review (`session-file-blame.ts`), and what reverting a turn undoes.
+ *
+ * The session's "before" copy (`session-file-baselines.service.ts`) is one state per file; this
+ * is all of them. Each call that can write a file — a file tool, a shell command, a codex patch —
+ * reports the file as it was just before the call and just after it, so a change no call
+ * reported (the user's own edit, a formatter on save, another program) is told apart from the
+ * calls' own changes: it lies between one call's "after" and the next call's "before".
+ *
+ * A state is stored as the change from the state before it, a few hundred bytes for an ordinary
+ * edit, so a file edited two hundred times costs two hundred small deltas rather than two
+ * hundred copies. A state that is not text (binary, over the size cap) keeps only a hash and
+ * breaks the chain; the next text state is then stored whole.
+ *
+ * Layout: `<session dir>/history/<sha256 of the path>.jsonl`, appended to in order. Its first
+ * line names the path; every other line is one observation (`HistoryLine`). Only this server
+ * writes it, one observation of a file at a time.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, closeSync, fstatSync, mkdirSync, openSync, readdirSync, readSync, statSync, utimesSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { diffLines } from "diff";
+import { decodeText, isBinaryContent } from "../binary-content.ts";
+import { isCredentialPath } from "../fs-credential-path-guard.ts";
+import { realPathOrSelf } from "../fs-ops/fs-real-path.ts";
+import { splitLines } from "../../shared/review-blocks.ts";
+import { BASELINE_MAX_BYTES, sessionDir, type BaselineSource } from "./session-file-baselines.service.ts";
+
+/** A log past this keeps only hashes: a file rewritten whole hundreds of times is not worth more. */
+export const HISTORY_MAX_FILE_BYTES = 16 * 1024 * 1024;
+
+export type HistoryPhase = "before" | "after";
+
+/** Lines kept (> 0) and dropped (< 0) from the previous state, and lines put in (strings, terminators included), in order. */
+export type Delta = (number | string)[];
+
+/** One line of a history log. */
+interface HistoryLine {
+  /** The call: a tool use id, or a codex item id. */
+  c: string;
+  p: "b" | "a";
+  /** Milliseconds since the epoch. */
+  t: number;
+  /** `stateHash` of the text; null when the file did not exist. */
+  h: string | null;
+  /** The state is not kept: binary, over the size cap, or written past the log's cap. */
+  k?: "binary" | "large" | "cap";
+  /** The change from the previous state, when that state is known. */
+  d?: Delta;
+  /** The whole text, when the previous state is not known or the change would be bigger. */
+  f?: string;
+}
+
+export interface HistoryEntry {
+  call: string;
+  phase: HistoryPhase;
+  at: number;
+  /** Null when the file did not exist. */
+  hash: string | null;
+  /** The file's text — "" when it did not exist — or null when this state was not kept. */
+  text: string | null;
+}
+
+/** Where a replay stands: the bytes of the log read, and the state they led to. */
+export interface HistoryPosition {
+  bytes: number;
+  /** Undefined before the first observation. */
+  hash: string | null | undefined;
+  text: string | null;
+}
+
+export const HISTORY_START: HistoryPosition = { bytes: 0, hash: undefined, text: null };
+
+/** Names a text state: the first 64 bits of its SHA-256, plenty to tell one file's states apart. */
+export function stateHash(text: string): string {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+export function encodeDelta(prev: string, next: string, timeoutMs = 200): Delta | null {
+  const parts = diffLines(prev, next, { timeout: timeoutMs });
+  if (!parts) return null;
+  const out: Delta = [];
+  for (const part of parts) {
+    if (part.added) out.push(part.value);
+    else {
+      const n = splitLines(part.value).length;
+      out.push(part.removed ? -n : n);
+    }
+  }
+  return out;
+}
+
+/** `prev` with `delta` made in it; null when the delta does not fit it. */
+export function applyDelta(prev: string, delta: Delta): string | null {
+  const lines = splitLines(prev);
+  const out: string[] = [];
+  let i = 0;
+  for (const op of delta) {
+    if (typeof op === "string") out.push(op);
+    else if (op > 0) {
+      if (i + op > lines.length) return null;
+      for (let k = 0; k < op; k++) out.push(lines[i++]!);
+    } else {
+      i -= op;
+      if (i > lines.length) return null;
+    }
+  }
+  return i === lines.length ? out.join("") : null;
+}
+
+function historyDir(sessionId: string): string | null {
+  const dir = sessionDir(sessionId);
+  return dir ? join(dir, "history") : null;
+}
+
+function logName(path: string): string {
+  return `${createHash("sha256").update(path).digest("hex")}.jsonl`;
+}
+
+/** The log of `filePath` in the session, or null for an id that cannot name a directory. */
+export function historyFile(sessionId: string, filePath: string): string | null {
+  const dir = historyDir(sessionId);
+  return dir && filePath ? join(dir, logName(resolve(filePath))) : null;
+}
+
+interface State {
+  hash: string | null;
+  text: string | null;
+  kind?: "binary" | "large";
+}
+
+const ABSENT: State = { hash: null, text: "" };
+
+function stateOf(source: BaselineSource | string): State {
+  if (source === null) return ABSENT;
+  if (source === "tooLarge") return { hash: "large", text: null, kind: "large" };
+  if (typeof source === "string") return { hash: stateHash(source), text: source };
+  if (source.length > BASELINE_MAX_BYTES) return { hash: "large", text: null, kind: "large" };
+  if (isBinaryContent(source)) {
+    return { hash: `bin:${createHash("sha256").update(source).digest("hex").slice(0, 16)}`, text: null, kind: "binary" };
+  }
+  const text = decodeText(source);
+  return { hash: stateHash(text), text };
+}
+
+/** The file on disk now; null when it is not a file at all, or cannot be read. */
+async function readState(path: string): Promise<State | null> {
+  try {
+    const st = await stat(path);
+    if (!st.isFile()) return null;
+    if (st.size > BASELINE_MAX_BYTES) return { hash: `large:${st.size}:${st.mtimeMs}`, text: null, kind: "large" };
+    return stateOf(new Uint8Array(await readFile(path)));
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    return code === "ENOENT" || code === "ENOTDIR" ? ABSENT : null;
+  }
+}
+
+/** The complete lines of `file` from byte `from` on, and the byte after the last of them. */
+function readLines(file: string, from: number): { lines: string[]; end: number } {
+  let fd: number;
+  try {
+    fd = openSync(file, "r");
+  } catch {
+    return { lines: [], end: from };
+  }
+  try {
+    const size = fstatSync(fd).size;
+    if (size <= from) return { lines: [], end: from };
+    const buf = Buffer.alloc(size - from);
+    const read = readSync(fd, buf, 0, buf.length, from);
+    // A line still being appended has no terminator yet: it is read next time.
+    const last = buf.subarray(0, read).lastIndexOf(10);
+    if (last < 0) return { lines: [], end: from };
+    return { lines: buf.subarray(0, last).toString("utf8").split("\n"), end: from + last + 1 };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function parseLine(raw: string): HistoryLine | null {
+  try {
+    const line = JSON.parse(raw) as HistoryLine;
+    return typeof line?.c === "string" && (line.p === "b" || line.p === "a") ? line : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The text a line leaves, given the state before it. */
+function textAfter(prev: HistoryPosition, line: HistoryLine): string | null {
+  if (line.k) return null;
+  if (line.h === null) return "";
+  if (line.f !== undefined) return line.f;
+  if (line.d) return prev.text === null ? null : applyDelta(prev.text, line.d);
+  return line.h === prev.hash ? prev.text : null;
+}
+
+/**
+ * The observations of `filePath` from `from` on (the start of the log by default), each with
+ * the text it records, and where the replay ends.
+ */
+export function readHistory(sessionId: string, filePath: string, from: HistoryPosition = HISTORY_START): { entries: HistoryEntry[]; end: HistoryPosition } {
+  const file = historyFile(sessionId, filePath);
+  if (!file) return { entries: [], end: from };
+  return replay(file, from);
+}
+
+function replay(file: string, from: HistoryPosition): { entries: HistoryEntry[]; end: HistoryPosition } {
+  const { lines, end } = readLines(file, from.bytes);
+  const entries: HistoryEntry[] = [];
+  let pos: HistoryPosition = from;
+  for (const raw of lines) {
+    const line = parseLine(raw);
+    if (!line) continue;
+    const text = textAfter(pos, line);
+    entries.push({ call: line.c, phase: line.p === "b" ? "before" : "after", at: line.t, hash: line.h, text });
+    pos = { bytes: pos.bytes, hash: line.h, text };
+  }
+  return { entries, end: { bytes: end, hash: pos.hash, text: pos.text } };
+}
+
+/** Where each log's writes stand, so an observation does not replay its log to find the last state. */
+const tails = new Map<string, HistoryPosition>();
+const TAILS_KEPT = 512;
+
+function tailOf(file: string): HistoryPosition {
+  let size = 0;
+  try {
+    size = statSync(file).size;
+  } catch { /* no log yet */ }
+  const known = tails.get(file);
+  if (known && known.bytes === size) return known;
+  // Never seen, written by an earlier run, or gone with its session: read it again.
+  const from = known && known.bytes < size ? known : HISTORY_START;
+  return replay(file, from).end;
+}
+
+function rememberTail(file: string, pos: HistoryPosition): void {
+  tails.delete(file);
+  tails.set(file, pos);
+  if (tails.size > TAILS_KEPT) tails.delete(tails.keys().next().value!);
+}
+
+const queues = new Map<string, Promise<void>>();
+
+/** Run `task` after every earlier one for the same log, so its lines go in the order they were seen. */
+function serialized(key: string, task: () => Promise<void>): Promise<void> {
+  const next = (queues.get(key) ?? Promise.resolve()).then(task).catch((e) => {
+    console.warn(`[session-history] observation failed: ${(e as Error).message}`);
+  });
+  queues.set(key, next);
+  void next.finally(() => {
+    if (queues.get(key) === next) queues.delete(key);
+  });
+  return next;
+}
+
+/**
+ * Record `filePath` as it is just before or just after `call` changes it: read from disk, or
+ * given as `source` when it was read earlier (a shell command's "before") or worked out (a codex
+ * patch's). Never throws. A credential path is never recorded, as it is never copied.
+ */
+export function observeFile(sessionId: string, filePath: string, call: string, phase: HistoryPhase, source?: BaselineSource | string): Promise<void> {
+  const dir = historyDir(sessionId);
+  if (!dir || !filePath || !call) return Promise.resolve();
+  const path = resolve(filePath);
+  if (isCredentialPath(path)) return Promise.resolve();
+  const file = join(dir, logName(path));
+  const at = Date.now();
+  return serialized(file, async () => {
+    if (isCredentialPath(await realPathOrSelf(path))) return;
+    const state = source === undefined ? await readState(path) : stateOf(source);
+    if (!state) return;
+    const tail = tailOf(file);
+    const line: HistoryLine = { c: call, p: phase === "before" ? "b" : "a", t: at, h: state.hash };
+    if (state.kind) line.k = state.kind;
+    else if (tail.bytes > HISTORY_MAX_FILE_BYTES) line.k = "cap";
+    else if (state.hash !== null && (state.hash !== tail.hash || tail.text === null)) {
+      const text = state.text!;
+      const delta = tail.text !== null && tail.hash !== undefined ? encodeDelta(tail.text, text) : null;
+      // Checked once on the way in, so a replay can trust every delta it reads.
+      if (delta && JSON.stringify(delta).length < text.length && applyDelta(tail.text!, delta) === text) line.d = delta;
+      else line.f = text;
+    }
+    let out = `${JSON.stringify(line)}\n`;
+    if (tail.bytes === 0) {
+      mkdirSync(dir, { recursive: true });
+      out = `${JSON.stringify({ path })}\n${out}`;
+    }
+    appendFileSync(file, out);
+    rememberTail(file, { bytes: tail.bytes + Buffer.byteLength(out), hash: state.hash, text: line.k ? null : state.text });
+    // An append moves no directory's mtime, and the session's is what keeps its files from
+    // being pruned (`pruneSessionBaselines`): a session still writing files it captured long
+    // ago would otherwise lose their "before"s, and its next write record a state it produced.
+    try {
+      const now = new Date();
+      utimesSync(dirname(dir), now, now);
+    } catch { /* pruned meanwhile: the next capture makes it again */ }
+  });
+}
+
+/** Every path the session has a history for. */
+export function historyPaths(sessionId: string): string[] {
+  const dir = historyDir(sessionId);
+  if (!dir) return [];
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter((n) => n.endsWith(".jsonl"));
+  } catch {
+    return [];
+  }
+  const out: string[] = [];
+  for (const name of names) {
+    const path = headerPath(join(dir, name));
+    if (path) out.push(path);
+  }
+  return out;
+}
+
+/** The path a log's first line names. */
+function headerPath(file: string): string | null {
+  let fd: number;
+  try {
+    fd = openSync(file, "r");
+  } catch {
+    return null;
+  }
+  try {
+    const buf = Buffer.alloc(64 * 1024);
+    const read = readSync(fd, buf, 0, buf.length, 0);
+    const end = buf.subarray(0, read).indexOf(10);
+    const head = JSON.parse(buf.subarray(0, end < 0 ? read : end).toString("utf8")) as { path?: unknown };
+    return typeof head.path === "string" ? head.path : null;
+  } catch {
+    return null;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Test seam: forget every remembered log position. */
+export function _resetSessionFileHistory(): void {
+  tails.clear();
+}