@hienlh/ppm 0.23.13 → 0.23.15

package/src/services/remote-desktop/access-unit-assembler.ts

@@ -2,13 +2,17 @@
  * Groups the raw NAL units from `NalSplitter` into WebCodecs-ready access units.
  *
  * `VideoDecoder` decodes one access unit (one frame) per `EncodedVideoChunk`, not one
- * NAL — feeding SPS/PPS/slice as three separate chunks throws or corrupts decode. libx264
- * (no B-frames, `-bf 0`) emits at most one slice NAL per frame, optionally preceded by
- * SPS/PPS on a keyframe, so an AU boundary is simply "the next VCL NAL after we already
- * buffered one" — everything non-VCL (SPS/PPS/AUD/SEI) that arrived first attaches to the
- * AU it precedes.
+ * NAL — feeding SPS/PPS/slice as three separate chunks throws or corrupts decode. With no
+ * B-frames (`-bf 0`) an AU boundary is "the next slice that opens a new picture after we
+ * already buffered one" (`startsPicture`) — everything non-VCL (SPS/PPS/AUD/SEI) that arrived
+ * first attaches to the AU it precedes.
+ *
+ * A frame may be several slices, and all of them belong in its one chunk. Cutting at *every*
+ * slice — this file's rule until #48 — turned x264's `tune=zerolatency` output into ~17 chunks a
+ * frame: Chrome decoded none of them ("Decoding error.", a black canvas) and a Wayland host
+ * reported a solid green one.
  */
-import { NalSplitter, nalType, isVclNal, NAL_TYPE_IDR, NAL_TYPE_SPS, NAL_TYPE_PPS } from "./nal-splitter.ts";
+import { NalSplitter, nalType, isVclNal, startsPicture, NAL_TYPE_IDR, NAL_TYPE_SPS, NAL_TYPE_PPS } from "./nal-splitter.ts";
 
 export interface AccessUnit {
   /** Annex-B encoded bytes (start codes + NAL payloads) — one `EncodedVideoChunk` worth. */
@@ -48,7 +52,7 @@ export class AccessUnitAssembler {
       else if (type === NAL_TYPE_PPS) this.pps = nal;
 
       const vcl = isVclNal(nal);
-      if (vcl && this.pendingHasVcl) {
+      if (this.pendingHasVcl && startsPicture(nal)) {
         const au = this.flush();
         if (au) aus.push(au);
       }

package/src/services/remote-desktop/nal-splitter.ts

@@ -19,12 +19,25 @@ export function nalType(nal: Uint8Array): number {
   return (nal[0] ?? 0) & 0x1f;
 }
 
-/** A slice NAL starts a new access unit; SPS/PPS/AUD/SEI attach to whichever AU follows them. */
+/** A slice NAL — picture data, as opposed to SPS/PPS/AUD/SEI. */
 export function isVclNal(nal: Uint8Array): boolean {
   const t = nalType(nal);
   return t === NAL_TYPE_SLICE_NON_IDR || t === NAL_TYPE_IDR;
 }
 
+/**
+ * Whether a slice NAL opens a new picture rather than continuing the one already open.
+ *
+ * An encoder may cut one frame into several slices — x264 does under `tune=zerolatency`, one per
+ * thread, measured at ~17 per 1080p frame on a 24-thread host. Every slice after the first names
+ * the macroblock it starts at, and `first_mb_in_slice` is the slice header's first field: an
+ * Exp-Golomb number, in which only 0 is coded as a single leading 1 bit. The byte after the NAL
+ * header can never hold an emulation-prevention byte (that needs two zero bytes before it).
+ */
+export function startsPicture(nal: Uint8Array): boolean {
+  return isVclNal(nal) && ((nal[1] ?? 0) & 0x80) !== 0;
+}
+
 /** `Bun.spawn` stdout chunks type as `Uint8Array<ArrayBufferLike>` (could in principle back
  *  onto a SharedArrayBuffer), while `new Uint8Array(n)` types as the narrower
  *  `Uint8Array<ArrayBuffer>` — pin everything here to the wider type so a plain chunk and our

package/src/services/remote-desktop/remote-desktop-capture-wayland.ts

@@ -36,8 +36,8 @@ import { createLogger } from "../logger.ts";
 
 const log = createLogger("remote-desktop");
 
-/** Which GStreamer elements this host actually has. Probed once — `gst-inspect-1.0` is ~40 ms
- *  and this sits on the session-start path. */
+/** Which GStreamer elements this host actually has. Remembered once nothing is missing, for the
+ *  checklist; a capture asks afresh every time it starts. */
 export interface GstElements {
   /** `gst-launch-1.0` itself. */
   launch: string | null;
@@ -51,6 +51,10 @@ export interface GstElements {
 }
 
 let cachedElements: GstElements | null = null;
+/** The probe under way. Whoever asks meanwhile shares it instead of spawning four more
+ *  `gst-inspect-1.0`: a host missing anything is probed on every call, and right after a package
+ *  install a cold plugin registry makes each probe take seconds. */
+let probing: Promise<GstElements> | null = null;
 
 async function hasElement(name: string): Promise<boolean> {
   try {
@@ -63,26 +67,41 @@ async function hasElement(name: string): Promise<boolean> {
   }
 }
 
-export async function gstElements(force = false): Promise<GstElements> {
+/** How the host is asked. A test stands in for it: `Bun.which` and `Bun.spawn` resolve through
+ *  the PATH this process started with, which a test cannot change. */
+export interface GstProbe {
+  launch: () => string | null;
+  has: (element: string) => Promise<boolean>;
+}
+
+const HOST_PROBE: GstProbe = { launch: () => Bun.which("gst-launch-1.0"), has: hasElement };
+
+/** `force` passes over a remembered answer, never a probe already under way: that one is asking
+ *  the host now. */
+export async function gstElements(force = false, probe: GstProbe = HOST_PROBE): Promise<GstElements> {
   if (cachedElements && !force) return cachedElements;
-  const launch = Bun.which("gst-launch-1.0");
-  if (!launch) {
-    cachedElements = { launch: null, pipewiresrc: false, vapostproc: false, vah264enc: false, x264enc: false };
-    return cachedElements;
-  }
-  const [pipewiresrc, vapostproc, vah264enc, x264enc] = await Promise.all([
-    hasElement("pipewiresrc"),
-    hasElement("vapostproc"),
-    hasElement("vah264enc"),
-    hasElement("x264enc"),
-  ]);
-  cachedElements = { launch, pipewiresrc, vapostproc, vah264enc, x264enc };
-  return cachedElements;
+  probing ??= probeElements(probe).finally(() => { probing = null; });
+  return probing;
+}
+
+async function probeElements(probe: GstProbe): Promise<GstElements> {
+  const launch = probe.launch();
+  const [pipewiresrc, vapostproc, vah264enc, x264enc] = launch
+    ? await Promise.all([probe.has("pipewiresrc"), probe.has("vapostproc"), probe.has("vah264enc"), probe.has("x264enc")])
+    : [false, false, false, false];
+  const els = { launch, pipewiresrc, vapostproc, vah264enc, x264enc };
+  // Only a host with nothing left to install is remembered. Anything missing may be installed
+  // while PPM runs, and the GPU pair replaces the x264 fallback the moment it appears: caching
+  // the first answer kept a host that had just installed vah264enc on x264 until PPM restarted,
+  // and made the checklist's "PPM re-checks automatically" untrue (#48).
+  cachedElements = launch && pipewiresrc && vapostproc && vah264enc ? els : null;
+  return els;
 }
 
 /** Drop the probe cache, so a package installed while PPM is running is picked up. */
 export function _resetGstElements(): void {
   cachedElements = null;
+  probing = null;
 }
 
 /** `"4M"` / `"1500k"` / `"800000"` → kbps, which is what every GStreamer encoder takes.
@@ -135,9 +154,12 @@ export function buildWaylandCaptureArgs(
     "!", `video/x-raw,framerate=${fps}/1`,
     "!", ...convert,
     "!", ...encode,
-    "!", "h264parse",
-    // Annex-B with one buffer per access unit — exactly the shape `AccessUnitAssembler` and the
-    // RTSP remux both expect, and the same bytes ffmpeg's `-f h264 pipe:1` produces.
+    // Annex-B straight from the encoder — exactly the shape `AccessUnitAssembler` and the RTSP
+    // remux both expect, and the same bytes ffmpeg's `-f h264 pipe:1` produces. No `h264parse`:
+    // both encoders already emit byte-stream with SPS/PPS ahead of every IDR (measured), and the
+    // parser lives in gst-plugins-bad, which a host with x264enc (gst-plugins-ugly) need not have
+    // — there every session died at start with `no element "h264parse"` behind a checklist that
+    // said ready (#48).
     "!", "video/x-h264,stream-format=byte-stream,alignment=au",
     "!", "fdsink", "fd=1",
   ];
@@ -168,7 +190,7 @@ export interface WaylandCaptureOptions extends StartCaptureOptions {
  *  through the PATH this process started with, which a test cannot change. */
 export interface WaylandCaptureDeps {
   startPortal?: typeof startPortalScreenCast;
-  elements?: () => Promise<GstElements>;
+  elements?: (force: boolean) => Promise<GstElements>;
 }
 
 /**
@@ -180,7 +202,11 @@ export async function startWaylandCapture(
   opts: WaylandCaptureOptions,
   { startPortal = startPortalScreenCast, elements = gstElements }: WaylandCaptureDeps = {},
 ): Promise<CaptureHandle> {
-  const els = await elements();
+  // Asked afresh, not read from what the checklist remembered: a complete answer is kept for the
+  // life of the process, so a GPU encoder gone since (a driver update, a removed package) would
+  // fail every session at start until PPM restarted. One probe is ~30 ms with a warm registry. A
+  // respawn asks too — it opens a portal session of its own anyway.
+  const els = await elements(true);
   if (!els.launch) {
     throw new CaptureUnavailableError("gst-launch-1.0 is not installed (Wayland capture needs GStreamer)");
   }

package/src/services/remote-desktop/remote-desktop-encoder-args.ts

@@ -59,10 +59,12 @@ export function captureEncoderArgs(
       // assumptions hold unchanged.
       return ["-c:v", "h264_videotoolbox", "-realtime", "1", "-prio_speed", "1", "-allow_sw", "1", ...common];
     default:
-      // libx264 low-latency. `-tune zerolatency` enables sliced-threads (multi-slice NALs);
-      // access-unit-assembler.ts assumes one slice/frame, so force it back with sliced-threads=0.
+      // libx264 low-latency. `-tune zerolatency` threads *within* a frame (one slice per
+      // thread, which the AU assembler keeps together). Never `sliced-threads=0`: x264 then
+      // threads *across* frames and holds one frame per thread — measured ~1.1 s later per frame
+      // than single-threaded on a 24-thread host.
       return ["-c:v", "libx264", "-preset", "veryfast", "-tune", "zerolatency",
-        "-profile:v", "main", "-level", "4.0", "-x264-params", "sliced-threads=0:slices=1",
+        "-profile:v", "main", "-level", "4.0",
         "-bufsize", "1M", ...common];
   }
 }

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

@@ -194,6 +194,54 @@ export function listBaselines(sessionId: string): FileBaseline[] {
     .sort((a, b) => order(a) - order(b) || a.path.localeCompare(b.path));
 }
 
+/** Per session directory, each record's path and capture order: records never change, so each is parsed once. */
+const recordIndex = new Map<string, Map<string, { path: string; order: number }>>();
+const INDEXES_KEPT = 64;
+
+/**
+ * The paths the session has a "before" for, oldest capture first — `listBaselines` without
+ * parsing every record on every call. A session that touched thousands of files holds tens of
+ * MB of them, and the list asks for these on every request.
+ */
+export function baselinePaths(sessionId: string): string[] {
+  const dir = sessionDir(sessionId);
+  if (!dir) return [];
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter((n) => n.endsWith(".json"));
+  } catch {
+    recordIndex.delete(dir);
+    return [];
+  }
+  const known = recordIndex.get(dir) ?? new Map<string, { path: string; order: number }>();
+  recordIndex.delete(dir);
+  recordIndex.set(dir, known);
+  if (recordIndex.size > INDEXES_KEPT) recordIndex.delete(recordIndex.keys().next().value!);
+  const present = new Set(names);
+  for (const name of known.keys()) if (!present.has(name)) known.delete(name);
+  for (const name of names) {
+    if (known.has(name)) continue;
+    const rec = parseRecord(join(dir, name));
+    if (rec) known.set(name, { path: rec.path, order: order(rec) });
+  }
+  return [...known.values()].sort((a, b) => a.order - b.order || a.path.localeCompare(b.path)).map((r) => r.path);
+}
+
+/**
+ * How many files the session has a "before" for, from the directory listing alone: cheap enough
+ * to ask after every turn, where `listBaselines` parses every record (a session that touched
+ * thousands of files holds tens of MB of them).
+ */
+export function countBaselines(sessionId: string): number {
+  const dir = sessionDir(sessionId);
+  if (!dir) return 0;
+  try {
+    return readdirSync(dir).filter((n) => n.endsWith(".json")).length;
+  } catch {
+    return 0;
+  }
+}
+
 /**
  * Whether PPM keeps anything the session itself wrote: a "before" (`<hash>.json`) or a file's
  * history (`history/`). Review marks and undo journals are the user's answers, not its writes.

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

@@ -9,7 +9,9 @@
  * was kept, or a state that was not text.
  *
  * Replays are kept, per file and per base, and only the lines a log gained since are read, so
- * asking again after every edit costs that edit's diff and nothing more.
+ * asking again after every edit costs that edit's diff and nothing more. The first replay of a
+ * long log is the expensive one — one diff per observation, each allowed 200 ms — so it hands
+ * the event loop back every few milliseconds rather than holding the server for the whole log.
  */
 import { diffLines } from "diff";
 import { statSync } from "node:fs";
@@ -45,6 +47,25 @@ interface Replay {
 const replays = new Map<string, Replay>();
 const REPLAYS_KEPT = 256;
 
+/** Work done between two hand-backs to the event loop while a log is replayed. */
+const YIELD_AFTER_MS = 20;
+
+/** A 0 ms timer, not `setImmediate`: that one starves HTTP (see `file-list-index.service.ts`). */
+const breathe = () => new Promise<void>((done) => setTimeout(done, 0));
+
+const replaying = new Map<string, Promise<unknown>>();
+
+/** One replay of a key at a time: two would advance the same state from the same position. */
+function oneAtATime<T>(key: string, task: () => Promise<T>): Promise<T> {
+  const next = (replaying.get(key) ?? Promise.resolve()).then(task, task);
+  replaying.set(key, next);
+  const settle = () => {
+    if (replaying.get(key) === next) replaying.delete(key);
+  };
+  next.then(settle, settle);
+  return next;
+}
+
 function labelOf(r: Replay, call: string): number {
   let label = r.callLabels.get(call);
   if (label === undefined) {
@@ -125,28 +146,39 @@ function start(baseText: string, markedAt: number | undefined): Replay {
 }
 
 /** The replay of `path` from `baseText` up to the end of its log, reusing what was read before. */
-function replayed(sessionId: string, path: string, baseText: string, markedAt: number | undefined): Replay | null {
+function replayed(sessionId: string, path: string, baseText: string, markedAt: number | undefined): Promise<Replay | null> {
   const file = historyFile(sessionId, path);
-  if (!file) return null;
-  let size: number;
-  try {
-    size = statSync(file).size;
-  } catch {
-    return null;
-  }
+  if (!file) return Promise.resolve(null);
   const key = `${sessionId}\0${path}\0${stateHash(baseText)}\0${markedAt ?? ""}`;
-  let r = replays.get(key);
-  // A log shorter than what was read is one written again, after its session was deleted.
-  if (!r || size < r.pos.bytes) r = start(baseText, markedAt);
-  if (size > r.pos.bytes) {
-    const { entries, end } = readHistory(sessionId, path, r.pos);
-    for (const e of entries) step(r, e, markedAt);
-    r.pos = end;
-  }
-  replays.delete(key);
-  replays.set(key, r);
-  if (replays.size > REPLAYS_KEPT) replays.delete(replays.keys().next().value!);
-  return r;
+  return oneAtATime(key, async () => {
+    let size: number;
+    try {
+      size = statSync(file).size;
+    } catch {
+      return null;
+    }
+    let r = replays.get(key);
+    // A log shorter than what was read is one written again, after its session was deleted.
+    if (!r || size < r.pos.bytes) r = start(baseText, markedAt);
+    if (size > r.pos.bytes) {
+      const { entries, end } = readHistory(sessionId, path, r.pos);
+      // Stepped in place: one left half way, by a throw, could never be told from a whole one.
+      replays.delete(key);
+      let since = performance.now();
+      for (const e of entries) {
+        step(r, e, markedAt);
+        if (performance.now() - since > YIELD_AFTER_MS) {
+          await breathe();
+          since = performance.now();
+        }
+      }
+      r.pos = end;
+    }
+    replays.delete(key);
+    replays.set(key, r);
+    if (replays.size > REPLAYS_KEPT) replays.delete(replays.keys().next().value!);
+    return r;
+  });
 }
 
 /**
@@ -154,15 +186,15 @@ function replayed(sessionId: string, path: string, baseText: string, markedAt: n
  * they ran; an empty list where the history names none. `markedAt` is set when the base is the
  * state the file was marked reviewed in rather than its "before".
  */
-export function blockCalls(p: {
+export async function blockCalls(p: {
   sessionId: string;
   path: string;
   baseText: string;
   currentText: string;
   blocks: ReviewBlock[];
   markedAt?: number;
-}): string[][] | null {
-  const r = replayed(p.sessionId, p.path, p.baseText, p.markedAt);
+}): Promise<string[][] | null> {
+  const r = await replayed(p.sessionId, p.path, p.baseText, p.markedAt);
   if (!r) return null;
   // What changed since the last observation was changed by nobody the history names.
   let current = r.lines;
@@ -197,4 +229,5 @@ export function blockCalls(p: {
 /** Test seam: forget every kept replay. */
 export function _resetSessionFileBlame(): void {
   replays.clear();
+  replaying.clear();
 }

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

@@ -19,7 +19,7 @@
  * kept. Keeping, reverting and undoing those answers is `session-review-actions.ts`.
  */
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import simpleGit from "simple-git";
@@ -27,10 +27,12 @@ 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 { BASELINE_MAX_BYTES, baselinePaths, readBaseline, recordFile, sessionDir, 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 { answerRecordFiles, hashBase, keptBlocks } from "./session-review-blocks.ts";
 import { blockCalls } from "./session-file-blame.ts";
+import { historyFile } from "./session-file-history.ts";
+import { onSessionFileWritten } from "./session-file-writes.ts";
 import { computeBlocks, type BlockDiff } from "../../shared/review-blocks.ts";
 import type {
   SessionChangeStatus,
@@ -218,7 +220,7 @@ export async function compare(chain: string[], projectPath: string, path: string
     const baseHash = hashBase(baseText!);
     change.base = baseHash.slice(0, 16);
     const kept = reviewed ? null : keptBlocks(chain, path, baseHash);
-    const calls = blockCalls({
+    const calls = await blockCalls({
       sessionId: chain[0]!,
       path,
       baseText: baseText!,
@@ -246,36 +248,232 @@ export function markReviewed(sessionId: string, compared: Compared): boolean {
     : 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: {
+/**
+ * Each session's list, kept between asks: one entry per file, with a stamp of what it was worked
+ * out from. Working a file out reads its "before" and its text now, diffs the two and replays
+ * its history, which on a session that touched a few thousand files took minutes per ask;
+ * stamping it is a few `stat`s. So an ask works out again only the files whose stamp moved,
+ * whoever moved them — the agent, the user's answers, an editor, a checkout — and the agent's
+ * own writes are worked out as they land and pushed to the browser (`onSessionFileChanges`).
+ */
+interface Entry {
+  stamp: string;
+  /** Null when the file is no change of the session's, or one it may not read. */
+  change: SessionFileChange | null;
+}
+
+interface KeptList {
   sessionId: string;
   projectPath: string;
-  paths?: string[];
-}): Promise<SessionFileChange[]> {
-  const chain = lineage(p.sessionId);
+  /** The lineage at the last ask, which is what an entry's stamp was taken along. */
+  chain: string[];
+  entries: Map<string, Entry>;
+  /** Asks and pushes one at a time: two would work the same file out side by side. */
+  queue: Promise<unknown>;
+}
+
+const lists = new Map<string, KeptList>();
+const LISTS_KEPT = 32;
+
+/** Work done between two hand-backs to the event loop: a first ask can take minutes. */
+const YIELD_AFTER_MS = 20;
+
+/** A 0 ms timer, not `setImmediate`: that one starves HTTP (see `file-list-index.service.ts`). */
+const breathe = () => new Promise<void>((done) => setTimeout(done, 0));
+
+function listFor(sessionId: string, projectPath: string): KeptList {
+  // By the session's directory, which names the PPM directory too.
+  const key = `${sessionDir(sessionId)}\0${resolve(projectPath)}`;
+  const list = lists.get(key) ?? { sessionId, projectPath, chain: [sessionId], entries: new Map(), queue: Promise.resolve() };
+  lists.delete(key);
+  lists.set(key, list);
+  if (lists.size > LISTS_KEPT) lists.delete(lists.keys().next().value!);
+  return list;
+}
+
+function queued<T>(list: KeptList, task: () => Promise<T>): Promise<T> {
+  const next = list.queue.then(task, task);
+  list.queue = next.catch(() => {});
+  return next;
+}
+
+function statStamp(file: string | null): string {
+  if (!file) return "";
+  try {
+    const st = statSync(file);
+    return `${st.ino}:${st.size}:${st.mtimeMs}`;
+  } catch {
+    return "-";
+  }
+}
+
+type HeadCache = Map<string, Promise<string | null>>;
+
+/** The commit HEAD names in the repository holding `dir`, once per ask and repository. */
+async function headOf(dir: string, repos: RepoCache, heads: HeadCache): Promise<string | null> {
+  const top = await repoTop(dir, repos);
+  if (!top) return null;
+  let head = heads.get(top);
+  if (!head) {
+    head = simpleGit(top).revparse(["HEAD"]).then((h) => h.trim() || null, () => null);
+    heads.set(top, head);
+  }
+  return head;
+}
+
+/**
+ * What `compare` reads for `path`, by `stat` alone: the file now; each session's "before",
+ * review mark and kept blocks along the lineage; the history the blocks are named from; and for
+ * a file with no "before", the HEAD it falls back to. Equal stamps mean an equal answer. Taken
+ * before the file is worked out, so a write landing in between moves the next stamp, not this one.
+ */
+async function stampOf(chain: string[], projectPath: string, path: string, repos: RepoCache, heads: HeadCache): Promise<string> {
+  const parts = [chain.join(","), statStamp(path)];
+  let kept = false;
+  for (const id of chain) {
+    const dir = sessionDir(id);
+    const before = dir ? statStamp(recordFile(dir, path)) : "-";
+    if (before !== "-") kept = true;
+    const answers = answerRecordFiles(id, path);
+    parts.push(before, statStamp(answers?.[0] ?? null), statStamp(answers?.[1] ?? null));
+  }
+  parts.push(statStamp(historyFile(chain[0]!, path)));
+  if (!kept && isInside(projectPath, path)) parts.push((await headOf(dirname(path), repos, heads)) ?? "");
+  return parts.join("|");
+}
+
+/** The file's entry, worked out again only when its stamp moved. */
+async function entryOf(list: KeptList, path: string, repos: RepoCache, heads: HeadCache): Promise<{ change: SessionFileChange | null; redone: boolean }> {
+  const stamp = await stampOf(list.chain, list.projectPath, path, repos, heads);
+  const held = list.entries.get(path);
+  if (held && held.stamp === stamp) return { change: held.change, redone: false };
+  // A path the guard refuses, or one that vanished mid-read, is simply not listed.
+  const change = (await compare(list.chain, list.projectPath, path, repos).catch(() => null))?.change ?? null;
+  list.entries.set(path, { stamp, change });
+  workedOut++;
+  return { change, redone: true };
+}
+
+let workedOut = 0;
+
+/** Test seam: how many files the kept lists have worked out, from scratch or again. */
+export function _sessionFilesWorkedOut(): number {
+  return workedOut;
+}
+
+/**
+ * The files the list is made of: those the session and its ancestors kept a "before" for, oldest
+ * first, then `extra`. Past the cap the newest are kept — on a session that touched thousands of
+ * files, the ones its latest turns changed are the ones being reviewed.
+ */
+function listedPaths(chain: string[], projectPath: string, extra: string[]): string[] {
   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 (!raw) return;
+    const path = resolve(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);
+  for (const id of [...chain].reverse()) for (const path of baselinePaths(id)) add(path);
+  for (const raw of extra) add(raw);
+  return ordered.length > MAX_SESSION_CHANGE_PATHS ? ordered.slice(-MAX_SESSION_CHANGE_PATHS) : ordered;
+}
 
-  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.
+/** Every file the session changed: those it kept a "before" for, then any other `paths`. */
+export function sessionFileChanges(p: {
+  sessionId: string;
+  projectPath: string;
+  paths?: string[];
+}): Promise<SessionFileChange[]> {
+  const list = listFor(p.sessionId, p.projectPath);
+  return queued(list, async () => {
+    list.chain = lineage(list.sessionId);
+    const repos: RepoCache = new Map();
+    const heads: HeadCache = new Map();
+    const out: SessionFileChange[] = [];
+    let since = performance.now();
+    for (const path of listedPaths(list.chain, list.projectPath, p.paths ?? [])) {
+      const { change } = await entryOf(list, path, repos, heads);
+      if (change) out.push(change);
+      if (performance.now() - since > YIELD_AFTER_MS) {
+        await breathe();
+        since = performance.now();
+      }
     }
+    return out;
+  });
+}
+
+/** What a push carries: the rows of the files just worked out again, and the files no longer changed. */
+export interface SessionFileChangesPush {
+  sessionId: string;
+  projectPath: string;
+  files: SessionFileChange[];
+  gone: string[];
+}
+
+const pushListeners = new Set<(push: SessionFileChangesPush) => void>();
+
+/** Subscribe to the rows pushed after the agent changed files; returns the unsubscribe function. */
+export function onSessionFileChanges(cb: (push: SessionFileChangesPush) => void): () => void {
+  pushListeners.add(cb);
+  return () => {
+    pushListeners.delete(cb);
+  };
+}
+
+/** Folds one shell command's files, or a burst of edits, into one push. */
+const PUSH_DELAY_MS = 150;
+const written = new Map<string, Set<string>>();
+let pushTimer: ReturnType<typeof setTimeout> | null = null;
+
+onSessionFileWritten((sessionId, path) => {
+  let paths = written.get(sessionId);
+  if (!paths) written.set(sessionId, (paths = new Set()));
+  paths.add(resolve(path));
+  pushTimer ??= setTimeout(pushWritten, PUSH_DELAY_MS);
+});
+
+/** Work out again the files the agent wrote, in every kept list along whose lineage it wrote them, and push them. */
+function pushWritten(): void {
+  pushTimer = null;
+  const batch = new Map(written);
+  written.clear();
+  for (const list of lists.values()) {
+    const paths = new Set<string>();
+    for (const id of list.chain) for (const path of batch.get(id) ?? []) paths.add(path);
+    if (paths.size === 0) continue;
+    void queued(list, async () => {
+      const repos: RepoCache = new Map();
+      const heads: HeadCache = new Map();
+      const push: SessionFileChangesPush = { sessionId: list.sessionId, projectPath: list.projectPath, files: [], gone: [] };
+      for (const path of paths) {
+        const was = list.entries.get(path)?.change ?? null;
+        const { change, redone } = await entryOf(list, path, repos, heads);
+        if (!redone) continue;
+        if (change) push.files.push(change);
+        else if (was) push.gone.push(path);
+      }
+      if (push.files.length === 0 && push.gone.length === 0) return;
+      for (const cb of pushListeners) {
+        try {
+          cb(push);
+        } catch (e) {
+          console.warn(`[session-baselines] push listener failed: ${(e as Error).message}`);
+        }
+      }
+    }).catch((e) => console.warn(`[session-baselines] push failed: ${(e as Error).message}`));
   }
-  return out;
+}
+
+/** Test seam: forget every kept list and pending push. */
+export function _resetSessionFileChanges(): void {
+  lists.clear();
+  written.clear();
+  if (pushTimer) clearTimeout(pushTimer);
+  pushTimer = null;
 }
 
 /** Both sides of one file, for the diff editor. Null when the session did not change it. */