tmux-ide 2.6.0 → 2.6.1

package/packages/daemon/src/tui/chrome/sidebar.ts

@@ -0,0 +1,222 @@
+/**
+ * The tmux-ide SIDEBAR — the app's persistent nav column.
+ *
+ * Unlike the widget PANELS (floating popups) this is a real, always-visible
+ * tmux pane: a narrow full-height left column that lists the fleet
+ * (project → session → window) with live status glyphs and jumps the viewing
+ * client anywhere on enter. It's summoned per-session with a toggle key
+ * (`keys.sidebar`, default `M-b`) that runs `tmux-ide sidebar-toggle`, so the
+ * app column appears wherever you call for it — in ANY adopted session.
+ *
+ * This module owns the tmux mechanics: the pure toggle-key bind builders (bound
+ * server-wide by `adoptSession`, like the other chrome keys) and the io that
+ * opens/finds/closes the column pane. The pane is marked with
+ * {@link SIDEBAR_PANE_OPTION} so the data layer excludes it from status rollups
+ * (see `../team/sessions.ts`) and the chip updater never labels it an agent.
+ *
+ * The command builders are PURE (tested); the io wrappers are thin.
+ */
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runTmux } from "@tmux-ide/tmux-bridge";
+import type { ThemeConfig } from "../../types.ts";
+import { shellEscape } from "../../lib/shell.ts";
+import { SIDEBAR_PANE_OPTION } from "../team/sessions.ts";
+import { resolveTuiLaunch, findCompiledTui, isBunAvailable } from "../compiled.ts";
+
+export { SIDEBAR_PANE_OPTION };
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve the sidebar widget's `.tsx` entry, robust across BOTH run modes. The
+ * widget sources ship uncompiled and are spawned by `bun`, so a bundled caller
+ * (this module inlined into `bin/cli.js`) must reach them via a bin-anchored
+ * path, while a dev caller (this module at `tui/chrome/`) reaches them relatively
+ * — the two differ, so we probe candidates and take the first that exists. Falls
+ * back to the dev path so the returned command is at least well-formed.
+ */
+export function sidebarWidgetScript(): string {
+  const candidates = [
+    resolve(__dirname, "../../widgets/sidebar/index.tsx"),
+    resolve(__dirname, "../packages/daemon/src/widgets/sidebar/index.tsx"),
+  ];
+  return candidates.find((p) => existsSync(p)) ?? candidates[0]!;
+}
+
+/**
+ * PURE — the shell command the sidebar pane runs. `cd`s into the project dir
+ * first so bun finds `bunfig.toml` (the @opentui/solid JSX preload), then boots
+ * the widget with the current session, dir, and (optional) theme. Mirrors
+ * `resolveWidgetCommand`'s shape but self-locates the script so it survives the
+ * bundle (see {@link sidebarWidgetScript}).
+ */
+export function sidebarWidgetCommand(
+  scriptPath: string,
+  session: string,
+  dir: string,
+  theme: ThemeConfig | null,
+): string {
+  const args = [`--session=${session}`, `--dir=${dir}`];
+  if (theme) args.push(`--theme=${JSON.stringify(theme)}`);
+
+  const launch = resolveTuiLaunch({
+    surface: "sidebar",
+    scriptPath,
+    args,
+    checkoutExists: existsSync(scriptPath),
+    bunAvailable: isBunAvailable(),
+    compiledBinary: findCompiledTui(),
+  });
+  if (launch.mode === "unavailable") {
+    // Keep the pane command well-formed; the pane shows bun's own error. This
+    // path only trips on a broken install (no checkout, no bun, no binary).
+    return `cd ${shellEscape(dir)} && bun ${shellEscape(scriptPath)} ${args.map(shellEscape).join(" ")}`;
+  }
+
+  const escaped = launch.argv.map(shellEscape).join(" ");
+  // Both modes cd into the project dir first: bun needs a nearby bunfig only in
+  // a checkout (which sits above dir); the binary is self-contained.
+  return `cd ${shellEscape(dir)} && ${shellEscape(launch.bin)} ${escaped}`;
+}
+
+/**
+ * Root-table key that toggles the sidebar: `M-b` (Alt+b). Like the other chrome
+ * keys it lives in the ROOT table so it fires without the prefix from any
+ * adopted session; Alt-letter keys are low-collision in terminal apps. Default
+ * for {@link sidebarToggleBindCommand}; overridable via `keys.sidebar`.
+ */
+export const SIDEBAR_KEY = "M-b";
+
+/** Default sidebar column width in tmux columns — narrow enough to leave the
+ *  work area room, wide enough for a glyph + a truncated name. */
+export const DEFAULT_SIDEBAR_WIDTH = 30;
+
+/** Normalized sidebar settings. */
+export interface ResolvedSidebar {
+  enabled: boolean;
+  width: number;
+}
+
+/**
+ * PURE — normalize the ide.yml `sidebar` sugar (`true` | `{ width }` | `false` |
+ * undefined) into `{ enabled, width }`. A missing/invalid width falls back to
+ * {@link DEFAULT_SIDEBAR_WIDTH}; width is clamped to a sane floor so a typo can't
+ * produce a zero-width column.
+ */
+export function resolveSidebarConfig(raw: unknown): ResolvedSidebar {
+  if (raw === true) return { enabled: true, width: DEFAULT_SIDEBAR_WIDTH };
+  if (!raw || typeof raw !== "object") return { enabled: false, width: DEFAULT_SIDEBAR_WIDTH };
+  const width = parseSidebarWidth((raw as { width?: unknown }).width);
+  return { enabled: true, width };
+}
+
+/** PURE — parse a width value (string or number) to a positive int column count,
+ *  falling back to the default and flooring at 10. */
+export function parseSidebarWidth(value: unknown): number {
+  const n =
+    typeof value === "number" ? value : typeof value === "string" ? parseInt(value, 10) : NaN;
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_SIDEBAR_WIDTH;
+  return Math.max(10, Math.floor(n));
+}
+
+/**
+ * PURE — the tmux argv that binds the sidebar toggle key. `run-shell`
+ * format-expands `#{session_name}` into `--session` (bind args themselves do NOT
+ * expand; run-shell DOES — the same trick the menu bind uses), so the CLI toggles
+ * the column in whichever session the client is viewing. Server-wide root-table
+ * bind, mirroring the switcher's M-p — see the note on `unadoptSession`.
+ */
+export function sidebarToggleBindCommand(
+  cli = "tmux-ide sidebar-toggle",
+  key = SIDEBAR_KEY,
+): string[] {
+  return ["bind-key", "-n", key, "run-shell", `${cli} --session '#{session_name}'`];
+}
+
+/** PURE — the tmux argv that removes the sidebar toggle binding. */
+export function sidebarToggleUnbindCommand(key = SIDEBAR_KEY): string[] {
+  return ["unbind-key", "-n", key];
+}
+
+/**
+ * PURE — the `split-window` argv that opens the sidebar column. `-h -b -f`
+ * creates a horizontal split placed BEFORE (left of) the target that spans the
+ * FULL window height (`-f`) regardless of which pane is active, `-l <width>`
+ * fixes its column width, and `-P -F '#{pane_id}'` prints the new pane id. The
+ * trailing `widgetCmd` runs the sidebar widget in the pane.
+ */
+export function sidebarSplitCommand(
+  session: string,
+  dir: string,
+  width: number,
+  widgetCmd: string,
+): string[] {
+  return [
+    "split-window",
+    "-P",
+    "-F",
+    "#{pane_id}",
+    "-t",
+    session,
+    "-h",
+    "-b",
+    "-f",
+    "-l",
+    String(width),
+    "-c",
+    dir,
+    widgetCmd,
+  ];
+}
+
+/**
+ * io — the sidebar pane id already open in `session`, or null. Reads the
+ * {@link SIDEBAR_PANE_OPTION} marker off each pane so a toggle can find and close
+ * an existing column.
+ */
+export function findSidebarPane(session: string): string | null {
+  try {
+    const raw = runTmux(
+      ["list-panes", "-t", session, "-F", `#{pane_id}\t#{${SIDEBAR_PANE_OPTION}}`],
+      { encoding: "utf-8" },
+    )
+      .toString()
+      .trim();
+    for (const line of raw.split("\n").filter(Boolean)) {
+      const [id = "", flag = ""] = line.split("\t");
+      if (flag === "1" && id) return id;
+    }
+  } catch {
+    // no such session / tmux unavailable — treat as "no sidebar"
+  }
+  return null;
+}
+
+/**
+ * io — open the sidebar column in `session` on `dir`, mark the pane so the data
+ * layer excludes it, title it "sidebar" (the pane-border chip falls back to the
+ * title for non-agent panes), and return the new pane id.
+ */
+export function openSidebarPane(
+  session: string,
+  dir: string,
+  width: number,
+  theme: ThemeConfig | null,
+): string {
+  const widgetCmd = sidebarWidgetCommand(sidebarWidgetScript(), session, dir, theme);
+  const paneId = runTmux(sidebarSplitCommand(session, dir, width, widgetCmd), {
+    encoding: "utf-8",
+  })
+    .toString()
+    .trim();
+  runTmux(["set-option", "-pqt", paneId, SIDEBAR_PANE_OPTION, "1"]);
+  runTmux(["select-pane", "-t", paneId, "-T", "sidebar"]);
+  return paneId;
+}
+
+/** io — close the sidebar column pane. */
+export function closeSidebarPane(paneId: string): void {
+  runTmux(["kill-pane", "-t", paneId]);
+}

package/packages/daemon/src/tui/chrome/snapshot.ts

@@ -0,0 +1,425 @@
+/**
+ * Fleet snapshot — the fleet's DISASTER-RECOVERY layer.
+ *
+ * The chrome {@link ./updater.ts updater} sees the whole tmux server every
+ * tick. This module turns that view into a durable, structural picture of the
+ * fleet — every session's windows, panes, cwds, layouts, titles, and the agent
+ * that was running in each pane — and persists it to `~/.tmux-ide/snapshot.json`.
+ * When the tmux server dies for real, `tmux-ide restore` ({@link ../../restore.ts})
+ * rebuilds the fleet from this file.
+ *
+ * Split as usual: {@link buildSnapshot} + {@link snapshotFingerprint} are PURE
+ * (assembled from raw tmux lines + a process table, unit-tested without a live
+ * tmux), while {@link collectFleetSnapshot} / {@link writeSnapshot} /
+ * {@link readSnapshot} are the thin io wrappers. {@link createSnapshotter}
+ * carries the throttle + change-detection the updater loop drives each tick.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { runTmux } from "@tmux-ide/tmux-bridge";
+import { readProcessTable, resolveAgentCommand, type ProcEntry } from "../detect/process-tree.ts";
+import { isListableSession } from "../team/sessions.ts";
+
+// ---------------------------------------------------------------------------
+// Model
+// ---------------------------------------------------------------------------
+
+/** A single pane, frozen for rebuild. */
+export interface PaneSnapshot {
+  /** `pane_index` within its window. */
+  index: number;
+  /** `pane_current_path` — the pane's working directory. */
+  cwd: string;
+  /**
+   * The command to re-run under `--run-commands`, or `null` for a bare shell
+   * (which restores as a plain pane). An agent pane records the RESOLVED agent
+   * id (e.g. `claude`), not the generic `node`/`bun` shim; a non-shell,
+   * non-agent pane records its `pane_current_command` verbatim.
+   */
+  command: string | null;
+  /** Resolved agent id (e.g. `claude`), or `null` for a non-agent pane. */
+  agent: string | null;
+  /** `@agent_session_id` — the agent's own session id (0037 resumes from it). */
+  agentSessionId: string | null;
+  /** `@agent_state` — the authority status line. Excluded from the fingerprint (it churns every tick). */
+  agentState: string | null;
+  /** `pane_title`. */
+  title: string;
+}
+
+/** A single window (tab), with the layout string that restores its geometry. */
+export interface WindowSnapshot {
+  /** `window_index`. */
+  index: number;
+  /** `window_name`. */
+  name: string;
+  /** Whether this is the session's active window. */
+  active: boolean;
+  /** `window_layout` — the checksummed layout string tmux's `select-layout` accepts verbatim. */
+  layout: string;
+  panes: PaneSnapshot[];
+}
+
+/** A single session, with its adopted flag so restore re-adopts it. */
+export interface SessionSnapshot {
+  name: string;
+  /** Session cwd — the first window's first pane's cwd. */
+  cwd: string;
+  /** Whether the session was adopted into the chrome. */
+  adopted: boolean;
+  windows: WindowSnapshot[];
+}
+
+/** The whole fleet at one instant. */
+export interface FleetSnapshot {
+  version: 1;
+  savedAt: string;
+  sessions: SessionSnapshot[];
+}
+
+// ---------------------------------------------------------------------------
+// Read validation — a snapshot on disk is untrusted input
+// ---------------------------------------------------------------------------
+
+const PaneSnapshotSchemaZ = z.object({
+  index: z.number(),
+  cwd: z.string(),
+  command: z.string().nullable(),
+  agent: z.string().nullable(),
+  agentSessionId: z.string().nullable(),
+  agentState: z.string().nullable(),
+  title: z.string(),
+});
+
+const WindowSnapshotSchemaZ = z.object({
+  index: z.number(),
+  name: z.string(),
+  active: z.boolean(),
+  layout: z.string(),
+  panes: z.array(PaneSnapshotSchemaZ),
+});
+
+const SessionSnapshotSchemaZ = z.object({
+  name: z.string(),
+  cwd: z.string(),
+  adopted: z.boolean(),
+  windows: z.array(WindowSnapshotSchemaZ),
+});
+
+const FleetSnapshotSchemaZ = z.object({
+  version: z.literal(1),
+  savedAt: z.string(),
+  sessions: z.array(SessionSnapshotSchemaZ),
+});
+
+// ---------------------------------------------------------------------------
+// Pure assembly
+// ---------------------------------------------------------------------------
+
+/** The tab-separated `list-panes -a` fields {@link buildSnapshot} parses, in order. */
+export const SNAPSHOT_PANE_FORMAT = [
+  "#{session_name}",
+  "#{window_index}",
+  "#{window_name}",
+  "#{window_active}",
+  "#{window_layout}",
+  "#{pane_index}",
+  "#{pane_current_path}",
+  "#{pane_current_command}",
+  "#{pane_pid}",
+  "#{@agent_session_id}",
+  "#{@agent_state}",
+  "#{@agent_hint}",
+  "#{pane_title}",
+].join("\t");
+
+/** The `list-sessions` fields the adopted-flag pass parses. */
+export const SNAPSHOT_SESSION_FORMAT = ["#{session_name}", "#{@tmux_ide_adopted}"].join("\t");
+
+/** A bare interactive shell — restores as a plain pane, records no command. */
+function isBareShell(cmd: string): boolean {
+  return /^-?(zsh|bash|sh|fish|dash|ksh|tcsh|csh|nu)$/.test(cmd.trim());
+}
+
+/**
+ * Decide a pane's `agent` + `command` from its command line + process tree.
+ *
+ * A real agent (a manifest that isn't the `shell` catch-all) records its id as
+ * BOTH the agent and the restore command; a bare shell records neither; any
+ * other foreground process records its `pane_current_command` as the command.
+ */
+function resolvePaneCommand(
+  cmd: string,
+  pid: number,
+  hint: string,
+  table: ProcEntry[],
+): { agent: string | null; command: string | null } {
+  const { manifest } = resolveAgentCommand(cmd, pid, table, { hint: hint || undefined });
+  if (manifest && manifest.id !== "shell") {
+    return { agent: manifest.id, command: manifest.id };
+  }
+  if (isBareShell(cmd)) return { agent: null, command: null };
+  return { agent: null, command: cmd };
+}
+
+/** `""` → null, so absent user-options round-trip as null rather than empty string. */
+function nullable(value: string): string | null {
+  return value.length > 0 ? value : null;
+}
+
+/**
+ * PURE — assemble a {@link FleetSnapshot} from raw `list-panes -a` lines, raw
+ * `list-sessions` lines (for the adopted flag), and a process table (for agent
+ * resolution). Internal `_`-prefixed sessions are skipped. Windows and panes
+ * come out in ascending index order; a session's cwd is its first window's
+ * first pane's cwd.
+ */
+export function buildSnapshot(
+  rawPanes: string[],
+  rawSessions: string[],
+  table: ProcEntry[],
+  savedAt: string = new Date().toISOString(),
+): FleetSnapshot {
+  // Adopted flag per session (marker field exactly "1").
+  const adopted = new Set<string>();
+  for (const line of rawSessions) {
+    const [name = "", flag = ""] = line.split("\t");
+    if (name && flag === "1") adopted.add(name);
+  }
+
+  // Group panes → session → window, preserving insertion but sorting at the end.
+  interface WinAccum {
+    index: number;
+    name: string;
+    active: boolean;
+    layout: string;
+    panes: PaneSnapshot[];
+  }
+  const sessions = new Map<string, Map<number, WinAccum>>();
+
+  for (const line of rawPanes) {
+    if (line.length === 0) continue;
+    const [
+      session = "",
+      windowIndex = "0",
+      windowName = "",
+      windowActive = "0",
+      layout = "",
+      paneIndex = "0",
+      cwd = "",
+      cmd = "",
+      pid = "0",
+      agentSessionId = "",
+      agentState = "",
+      hint = "",
+      ...titleParts
+    ] = line.split("\t");
+    if (!session || !isListableSession(session)) continue;
+
+    let windows = sessions.get(session);
+    if (!windows) {
+      windows = new Map();
+      sessions.set(session, windows);
+    }
+    const wIndex = Number(windowIndex) || 0;
+    let win = windows.get(wIndex);
+    if (!win) {
+      win = {
+        index: wIndex,
+        name: windowName,
+        active: windowActive === "1",
+        layout,
+        panes: [],
+      };
+      windows.set(wIndex, win);
+    }
+
+    const { agent, command } = resolvePaneCommand(cmd, Number(pid) || 0, hint, table);
+    win.panes.push({
+      index: Number(paneIndex) || 0,
+      cwd,
+      command,
+      agent,
+      agentSessionId: nullable(agentSessionId),
+      agentState: nullable(agentState),
+      title: titleParts.join("\t"),
+    });
+  }
+
+  const out: SessionSnapshot[] = [];
+  for (const [name, windows] of sessions) {
+    const windowList: WindowSnapshot[] = [...windows.values()]
+      .sort((a, b) => a.index - b.index)
+      .map((w) => ({
+        index: w.index,
+        name: w.name,
+        active: w.active,
+        layout: w.layout,
+        panes: w.panes.slice().sort((a, b) => a.index - b.index),
+      }));
+    const cwd = windowList[0]?.panes[0]?.cwd ?? "";
+    out.push({ name, cwd, adopted: adopted.has(name), windows: windowList });
+  }
+  // Stable session order so the fingerprint doesn't churn on Map iteration.
+  out.sort((a, b) => a.name.localeCompare(b.name));
+
+  return { version: 1, savedAt, sessions: out };
+}
+
+/**
+ * PURE — a stable fingerprint of the fleet's STRUCTURE. Everything but
+ * `savedAt` and each pane's `agentState` is included, so the fingerprint is
+ * unchanged as agents churn working→idle every tick (agentState is a timestamped
+ * status line) but DOES change when a pane/window/session, a cwd, a layout, a
+ * title, or an agent-session-id changes. The updater rewrites the file only when
+ * this value moves — a steady fleet issues zero snapshot writes.
+ */
+export function snapshotFingerprint(snapshot: FleetSnapshot): string {
+  const structural = {
+    sessions: snapshot.sessions.map((s) => ({
+      name: s.name,
+      cwd: s.cwd,
+      adopted: s.adopted,
+      windows: s.windows.map((w) => ({
+        index: w.index,
+        name: w.name,
+        active: w.active,
+        layout: w.layout,
+        panes: w.panes.map((p) => ({
+          index: p.index,
+          cwd: p.cwd,
+          command: p.command,
+          agent: p.agent,
+          agentSessionId: p.agentSessionId,
+          title: p.title,
+          // agentState deliberately omitted — it churns every tick.
+        })),
+      })),
+    })),
+  };
+  return JSON.stringify(structural);
+}
+
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+
+/** Injectable io for {@link collectFleetSnapshot} — real tmux by default. */
+export interface SnapshotIo {
+  listPanes: () => string;
+  listSessions: () => string;
+  processTable: () => ProcEntry[];
+}
+
+const defaultIo: SnapshotIo = {
+  listPanes: () => runTmux(["list-panes", "-a", "-F", SNAPSHOT_PANE_FORMAT]).toString(),
+  listSessions: () => runTmux(["list-sessions", "-F", SNAPSHOT_SESSION_FORMAT]).toString(),
+  processTable: () => readProcessTable(),
+};
+
+/** Collect the live fleet into a {@link FleetSnapshot}. Thin io over {@link buildSnapshot}. */
+export function collectFleetSnapshot(io: SnapshotIo = defaultIo): FleetSnapshot {
+  const rawPanes = io.listPanes().split("\n").filter(Boolean);
+  const rawSessions = io.listSessions().split("\n").filter(Boolean);
+  return buildSnapshot(rawPanes, rawSessions, io.processTable());
+}
+
+/** Absolute path to the fleet snapshot. */
+export function snapshotPath(): string {
+  return join(homedir(), ".tmux-ide", "snapshot.json");
+}
+
+/**
+ * Write the snapshot atomically (temp + rename), keeping ONE previous
+ * generation as `snapshot.json.1`. Best-effort: a filesystem failure must never
+ * break the updater loop.
+ */
+export function writeSnapshot(snapshot: FleetSnapshot): void {
+  const path = snapshotPath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(snapshot, null, 2) + "\n");
+    // Rotate the current generation out of the way, then swap the new one in.
+    if (existsSync(path)) {
+      try {
+        renameSync(path, `${path}.1`);
+      } catch {
+        // one-generation rotation is best-effort
+      }
+    }
+    renameSync(tmp, path);
+  } catch {
+    // a failed write just means a staler snapshot — never fatal
+  }
+}
+
+/** Read + validate the snapshot on disk. Returns null when missing or malformed. */
+export function readSnapshot(): FleetSnapshot | null {
+  const path = snapshotPath();
+  try {
+    if (!existsSync(path)) return null;
+    const raw = readFileSync(path, "utf-8");
+    if (raw.trim().length === 0) return null;
+    const result = FleetSnapshotSchemaZ.safeParse(JSON.parse(raw));
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Throttle + change detection — driven by the updater loop
+// ---------------------------------------------------------------------------
+
+/** Snapshot every N ticks. At {@link ./updater.ts TICK_MS} = 2s, 15 ticks ≈ 30s. */
+export const SNAPSHOT_EVERY = 15;
+
+/** Resolve the tick throttle, honoring `TMUX_IDE_SNAPSHOT_EVERY` (tests/tuning). */
+export function snapshotEvery(): number {
+  const raw = process.env.TMUX_IDE_SNAPSHOT_EVERY;
+  const n = raw ? Number(raw) : NaN;
+  return Number.isInteger(n) && n > 0 ? n : SNAPSHOT_EVERY;
+}
+
+/** Deps for {@link createSnapshotter} — injectable so the throttle is unit-tested. */
+export interface SnapshotterDeps {
+  collect: () => FleetSnapshot;
+  read: () => FleetSnapshot | null;
+  write: (snapshot: FleetSnapshot) => void;
+  every: number;
+}
+
+/**
+ * A stateful snapshotter the updater loop pulses once per tick via
+ * {@link Snapshotter.onTick}. It fires only every `every` ticks, and even then
+ * writes only when the STRUCTURE changed since the last write (seeded from the
+ * existing file on first fire, so a restart doesn't rewrite an unchanged fleet).
+ */
+export interface Snapshotter {
+  onTick: () => void;
+}
+
+export function createSnapshotter(deps: SnapshotterDeps): Snapshotter {
+  let ticks = 0;
+  let seeded = false;
+  let lastFingerprint: string | null = null;
+  return {
+    onTick(): void {
+      ticks++;
+      if (deps.every <= 0 || ticks % deps.every !== 0) return;
+      if (!seeded) {
+        const existing = deps.read();
+        lastFingerprint = existing ? snapshotFingerprint(existing) : null;
+        seeded = true;
+      }
+      const snapshot = deps.collect();
+      const fingerprint = snapshotFingerprint(snapshot);
+      if (fingerprint === lastFingerprint) return;
+      lastFingerprint = fingerprint;
+      deps.write(snapshot);
+    },
+  };
+}