tmux-ide 2.6.1 → 2.8.0

package/packages/daemon/src/lib/tui-binary.ts

@@ -0,0 +1,165 @@
+/**
+ * Per-platform TUI binary: the runtime-download fallback that lets a clean
+ * `npm i -g tmux-ide` run the full OpenTUI/Solid cockpit WITHOUT `bun`.
+ *
+ * The dev checkout runs the `.tsx` surfaces via bun; an npm install with no bun
+ * needs a self-contained binary. We do NOT bundle that ~70MB blob in the npm
+ * tarball (a surprise on every install) — instead the release workflow
+ * (`.github/workflows/release-binaries.yml`) cross-compiles one per platform and
+ * uploads them as GitHub release assets, and this module downloads the right one
+ * on demand (explicit `tmux-ide update --tui-binary`, or a consented first run).
+ *
+ * The mapping/URL/path helpers are PURE (unit-tested); {@link downloadTuiBinary}
+ * and {@link findDownloadedTui} are the thin io that fetch and probe.
+ */
+import { chmodSync, existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { getCurrentVersion } from "./update-check.ts";
+
+/** The `<os>-<arch>` tags we publish a prebuilt TUI binary for. */
+export type TuiPlatformTag = "darwin-arm64" | "darwin-x64" | "linux-x64" | "linux-arm64";
+
+/** The GitHub repo the release assets live under. */
+export const RELEASE_REPO = "wavyrai/tmux-ide";
+
+/** A downloaded binary smaller than this is treated as corrupt/truncated. */
+export const MIN_TUI_BINARY_BYTES = 10 * 1024 * 1024;
+
+const SUPPORTED: Record<string, TuiPlatformTag> = {
+  "darwin-arm64": "darwin-arm64",
+  "darwin-x64": "darwin-x64",
+  "linux-x64": "linux-x64",
+  "linux-arm64": "linux-arm64",
+};
+
+// ---------------------------------------------------------------------------
+// Pure
+// ---------------------------------------------------------------------------
+
+/**
+ * PURE — map a Node `process.platform`/`process.arch` pair to the release tag,
+ * or null when we don't publish a binary for it (e.g. windows, freebsd) so the
+ * caller can fall back to the "install bun" message.
+ */
+export function tuiPlatformTag(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): TuiPlatformTag | null {
+  return SUPPORTED[`${platform}-${arch}`] ?? null;
+}
+
+/** PURE — the `bun build --compile --target` flag for a tag (`bun-<tag>`). */
+export function bunTargetForTag(tag: TuiPlatformTag): string {
+  return `bun-${tag}`;
+}
+
+/** PURE — the release asset filename for a tag (gzip-compressed binary). */
+export function releaseAssetName(tag: TuiPlatformTag): string {
+  return `tmux-ide-tui-${tag}.gz`;
+}
+
+/** PURE — strip a leading `v` from a version string; `2.6.1` and `v2.6.1` both → `2.6.1`. */
+export function normalizeVersion(version: string): string {
+  return version.startsWith("v") ? version.slice(1) : version;
+}
+
+/**
+ * PURE — the GitHub download URL for a platform's asset at a given version:
+ * `https://github.com/<repo>/releases/download/v<version>/tmux-ide-tui-<tag>.gz`.
+ */
+export function releaseAssetUrl(version: string, tag: TuiPlatformTag): string {
+  return `https://github.com/${RELEASE_REPO}/releases/download/v${normalizeVersion(version)}/${releaseAssetName(tag)}`;
+}
+
+/**
+ * PURE — where a downloaded binary lives: `<home>/bin/tmux-ide-tui-<tag>-<version>`.
+ * The version is stamped INTO the name so a `tmux-ide update` to a new version
+ * misses the old download and re-fetches (rather than launching a stale binary).
+ */
+export function downloadedTuiPath(home: string, tag: TuiPlatformTag, version: string): string {
+  return join(home, "bin", `tmux-ide-tui-${tag}-${normalizeVersion(version)}`);
+}
+
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+
+/**
+ * io — the tmux-ide state home (`TMUX_IDE_HOME` override, else `~/.tmux-ide`),
+ * the same resolution the update-check cache and welcome marker use.
+ */
+export function tuiStateHome(): string {
+  return process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+}
+
+/**
+ * io — locate a previously downloaded per-platform binary for THIS version and
+ * platform, or null. Feeds the resolution order in `tui/compiled.ts` after the
+ * shipped/local compiled binary and before the honest "unavailable" error.
+ */
+export function findDownloadedTui(version: string = getCurrentVersion()): string | null {
+  const tag = tuiPlatformTag();
+  if (!tag) return null;
+  const path = downloadedTuiPath(tuiStateHome(), tag, version);
+  return existsSync(path) ? path : null;
+}
+
+/**
+ * io — download, verify, and install the per-platform TUI binary for the running
+ * version. Fetches the gzip asset, inflates it, rejects anything under
+ * {@link MIN_TUI_BINARY_BYTES} (a truncated download or an HTML error page),
+ * writes it `0o755`, and atomically renames it into place (temp-in-same-dir →
+ * rename, so a crashed download never leaves a half-written executable).
+ *
+ * Throws with an actionable message on an unsupported platform or a failed
+ * fetch. Returns the installed path and byte size.
+ */
+export async function downloadTuiBinary(
+  opts: {
+    version?: string;
+    log?: (msg: string) => void;
+  } = {},
+): Promise<{ path: string; bytes: number }> {
+  const log = opts.log ?? (() => {});
+  const version = normalizeVersion(opts.version ?? getCurrentVersion());
+  const tag = tuiPlatformTag();
+  if (!tag) {
+    throw new Error(
+      `no prebuilt TUI binary is published for ${process.platform}-${process.arch} — ` +
+        `install bun (https://bun.sh) to run the TUI surfaces from source instead`,
+    );
+  }
+
+  const url = releaseAssetUrl(version, tag);
+  const dest = downloadedTuiPath(tuiStateHome(), tag, version);
+  mkdirSync(dirname(dest), { recursive: true });
+
+  log(`downloading ${url}`);
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(
+      `could not download the TUI binary (${url} → HTTP ${res.status} ${res.statusText}). ` +
+        `Check that release v${version} exists and published its assets.`,
+    );
+  }
+
+  const gz = Buffer.from(await res.arrayBuffer());
+  const bin = gunzipSync(gz);
+  if (bin.byteLength < MIN_TUI_BINARY_BYTES) {
+    throw new Error(
+      `the downloaded TUI binary is only ${bin.byteLength} bytes (expected >10MB) — ` +
+        `treating it as corrupt and leaving the previous binary (if any) in place`,
+    );
+  }
+
+  const tmp = `${dest}.${process.pid}.tmp`;
+  writeFileSync(tmp, bin, { mode: 0o755 });
+  chmodSync(tmp, 0o755);
+  renameSync(tmp, dest);
+
+  const mb = (bin.byteLength / 1024 / 1024).toFixed(1);
+  log(`installed ${dest} (${mb} MB)`);
+  return { path: dest, bytes: bin.byteLength };
+}

package/packages/daemon/src/lib/update-check.ts

@@ -252,6 +252,11 @@ export function getUpdateStatus({
 export async function runUpdateCheck({ now = Date.now() }: { now?: number } = {}): Promise<void> {
   const cache = readUpdateCache();
   if (!shouldCheck(cache?.lastCheckedAt ?? null, now)) return;
+  // The agent-detection manifest-pack refresh RIDES this same daily throttle
+  // (M25.4) — no timer of its own, gated again inside on `updates.manifests`
+  // (default false) and never throwing. Dynamic import: manifest-pack imports
+  // this module for getCurrentVersion, so a static import would be a cycle.
+  void import("./manifest-pack.ts").then((m) => m.maybeRefreshManifestPack()).catch(() => {});
   const fetched = await fetchLatestVersion();
   writeUpdateCache({
     lastCheckedAt: now,

package/packages/daemon/src/restore.ts

@@ -13,9 +13,11 @@
  *
  * `--resume-agents` (or `{ "restore": { "resumeAgents": true } }` in
  * `~/.tmux-ide/config.json`) layers native agent-resume on top: a rebuilt
- * claude pane that carries a recorded `@agent_session_id` relaunches as
- * `claude --resume <id>`, reviving the actual conversation rather than opening
- * a fresh shell. See {@link paneResumeCommand} for the exact decision table.
+ * agent pane that carries a recorded `@agent_session_id` relaunches with its
+ * kind's VERIFIED resume invocation (`claude --resume <id>`, `codex resume
+ * <id>`, … — {@link AGENT_RESUME_COMMANDS}), reviving the actual conversation
+ * rather than opening a fresh shell. See {@link paneResumeCommand} for the
+ * exact decision table.
  *
  * {@link buildRestorePlan} + {@link paneResumeCommand} + {@link restorePrefs}
  * are PURE (unit-tested); {@link restore} is the thin io wrapper that reads the
@@ -92,22 +94,57 @@ export function buildRestorePlan(
 // Pure — agent resume decision
 // ---------------------------------------------------------------------------
 
-/** A session id is trusted only if it's the uuid alphabet — nothing shell-active. */
-const SAFE_SESSION_ID = /^[A-Za-z0-9-]+$/;
+/** A session id is trusted only if it's uuid-ish (`[A-Za-z0-9_-]` — underscore
+ *  covers opencode's `ses_…` ids) — nothing shell-active. */
+const SAFE_SESSION_ID = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * The native session-resume invocation per agent kind (M24.1 — the table was
+ * claude-only until then). ONLY VERIFIED entries ship; each spelling's source:
+ *  - `claude --resume <id>`: the shipped integration (its hooks record the id).
+ *  - `codex resume <id>`: `codex resume --help` — "Usage: codex resume
+ *    [OPTIONS] [SESSION_ID]  … Session id (UUID) or session name".
+ *  - `opencode --session <id>`: `opencode --help` — "-s, --session  session id
+ *    to continue".
+ *  - `cursor-agent --resume <id>`: `cursor-agent --help` — "--resume [chatId]
+ *    Select a session to resume".
+ *  - `copilot --resume=<id>`: GitHub Copilot CLI command reference —
+ *    "--resume[=VALUE]  Resume a previous interactive session … Optionally
+ *    specify a session ID" (the `=` form, since the value is optional).
+ * Unverified (no entry): gemini, aider, goose, amp — no confirmed native
+ * per-session resume invocation at the time of writing.
+ *
+ * How `@agent_session_id` gets recorded per kind (M25.3):
+ *  - claude — the hooks integration (`integration install claude`).
+ *  - opencode — the plugin integration (`integration install opencode`).
+ *  - codex, cursor — automatic: the chrome updater probes the agent's own
+ *    on-disk session state ({@link ./tui/detect/session-id.ts}).
+ *  - copilot — no automatic capture (skipped with evidence — see the
+ *    session-id module header); fires only for panes whose agent self-reported
+ *    the id per the agent contract
+ *    (`tmux set-option -p @agent_session_id <id>`), which any kind may do.
+ */
+export const AGENT_RESUME_COMMANDS: Record<string, (id: string) => string> = {
+  claude: (id) => `claude --resume ${id}`,
+  codex: (id) => `codex resume ${id}`,
+  opencode: (id) => `opencode --session ${id}`,
+  cursor: (id) => `cursor-agent --resume ${id}`,
+  copilot: (id) => `copilot --resume=${id}`,
+};
 
 /**
  * PURE — the command to relaunch a pane so its agent conversation is revived,
  * or `null` for "no resume — leave it a plain shell (or replay `command`)".
  *
  * Decision table (only fires when `resumeAgents` is on):
- *  - claude + a recorded `@agent_session_id` → `claude --resume <id>`. The id is
- *    a uuid, but we don't trust the snapshot: unless it matches
- *    {@link SAFE_SESSION_ID} (`[A-Za-z0-9-]`) we bail to `null` rather than risk
- *    feeding shell metacharacters into send-keys.
- *  - claude with NO session id → `null`. `claude --continue` would be too
- *    magical here (it resumes the most-recent conversation in the cwd, which may
- *    belong to a different pane); a fresh shell is the safe, predictable default.
- *  - any other agent → `null`. No native resume story yet.
+ *  - a kind in {@link AGENT_RESUME_COMMANDS} + a recorded `@agent_session_id` →
+ *    that kind's resume invocation. The id is uuid-ish, but we don't trust the
+ *    snapshot: unless it matches {@link SAFE_SESSION_ID} we bail to `null`
+ *    rather than risk feeding shell metacharacters into send-keys.
+ *  - a known kind with NO session id → `null`. A "continue most recent" flag
+ *    would be too magical here (it resumes the cwd's most-recent conversation,
+ *    which may belong to a different pane); a fresh shell is the safe default.
+ *  - any other agent → `null`. No VERIFIED resume story.
  *  - `resumeAgents` off → always `null`.
  */
 export function paneResumeCommand(
@@ -115,10 +152,11 @@ export function paneResumeCommand(
   opts: { resumeAgents: boolean },
 ): string | null {
   if (!opts.resumeAgents) return null;
-  if (pane.agent !== "claude") return null;
+  const resume = pane.agent ? AGENT_RESUME_COMMANDS[pane.agent] : undefined;
+  if (!resume) return null;
   const id = pane.agentSessionId;
   if (!id || !SAFE_SESSION_ID.test(id)) return null;
-  return `claude --resume ${id}`;
+  return resume(id);
 }
 
 /** PURE — how many of a session's panes would resume under `resumeAgents`. */

package/packages/daemon/src/send.ts

@@ -86,24 +86,36 @@ function prepareMessage(message: string, busyStatus: PaneBusyStatus): string {
   return message;
 }
 
-export async function send(targetDir: string | undefined, opts: SendOptions): Promise<void> {
-  const dir = resolve(targetDir ?? ".");
-  const { name: session } = getSessionName(dir);
-  const { json, to: target, message: rawMessage, noEnter } = opts;
-
-  if (!target) {
-    throw new IdeError("Missing target. Usage: tmux-ide send <target> <message>", {
-      code: "USAGE",
-    });
-  }
+/** What a delivery reports back (the `send --json` payload, and the control
+ *  socket's `send` verb data). */
+export interface DeliverResult {
+  ok: true;
+  session: string;
+  target: { paneId: string; name: string | null; title: string; role: string | null };
+  message: string;
+  busyStatus: PaneBusyStatus;
+  sentViaFile: boolean;
+  warning?: "agent_busy";
+}
 
-  if (!rawMessage) {
-    throw new IdeError("Missing message. Usage: tmux-ide send <target> <message>", {
-      code: "USAGE",
-    });
-  }
+/**
+ * Deliver `message` to a pane of `session` — the SHARED core behind the
+ * `tmux-ide send` CLI case and the control socket's `send` verb. Resolves
+ * `target` (pane id / @ide_name / title / role / partial title), adapts to
+ * the pane's busy status, and routes long messages through a dispatch file
+ * under `dir` when one is given (without a `dir` the text is sent directly).
+ * Throws `IdeError` (SESSION_NOT_FOUND / PANE_NOT_FOUND) — no printing here.
+ */
+export function deliverMessage(opts: {
+  session: string;
+  target: string;
+  message: string;
+  noEnter?: boolean;
+  /** The project dir long messages are dispatched through as a file. */
+  dir?: string;
+}): DeliverResult {
+  const { session, target, noEnter, dir } = opts;
 
-  // Verify session is running
   const state = getSessionState(session);
   if (!state.running) {
     throw new IdeError(`Session "${session}" is not running`, {
@@ -126,13 +138,13 @@ export async function send(targetDir: string | undefined, opts: SendOptions): Pr
   }
 
   const busyStatus = getPaneBusyStatus(session, pane.id);
-  const message = prepareMessage(rawMessage, busyStatus);
+  const message = prepareMessage(opts.message, busyStatus);
 
   let sentViaFile = false;
   if (noEnter) {
     sendText(session, pane.id, message);
   } else {
-    const dispatch = writeDispatchFile(dir, pane.id, message);
+    const dispatch = dir ? writeDispatchFile(dir, pane.id, message) : null;
     if (dispatch) {
       sendCommand(session, pane.id, dispatch.triggerCmd);
       sentViaFile = true;
@@ -141,7 +153,7 @@ export async function send(targetDir: string | undefined, opts: SendOptions): Pr
     }
   }
 
-  const result = {
+  return {
     ok: true,
     session,
     target: {
@@ -153,8 +165,30 @@ export async function send(targetDir: string | undefined, opts: SendOptions): Pr
     message,
     busyStatus,
     sentViaFile,
-    ...(busyStatus === "agent" ? { warning: "agent_busy" } : {}),
+    ...(busyStatus === "agent" ? { warning: "agent_busy" as const } : {}),
   };
+}
+
+export async function send(targetDir: string | undefined, opts: SendOptions): Promise<void> {
+  const dir = resolve(targetDir ?? ".");
+  const { name: session } = getSessionName(dir);
+  const { json, to: target, message: rawMessage, noEnter } = opts;
+
+  if (!target) {
+    throw new IdeError("Missing target. Usage: tmux-ide send <target> <message>", {
+      code: "USAGE",
+    });
+  }
+
+  if (!rawMessage) {
+    throw new IdeError("Missing message. Usage: tmux-ide send <target> <message>", {
+      code: "USAGE",
+    });
+  }
+
+  const result = deliverMessage({ session, target, message: rawMessage, noEnter, dir });
+  const { message, busyStatus } = result;
+  const pane = result.target;
 
   if (json) {
     console.log(JSON.stringify(result, null, 2));
@@ -163,7 +197,7 @@ export async function send(targetDir: string | undefined, opts: SendOptions): Pr
 
   const label = pane.name ?? pane.title;
   const preview = message.length > 60 ? message.slice(0, 60) + "..." : message;
-  console.log(`Sent to "${label}" (${pane.id}): ${preview}`);
+  console.log(`Sent to "${label}" (${pane.paneId}): ${preview}`);
 
   if (busyStatus === "agent") {
     console.log("Warning: agent appears busy. Message sent anyway.");

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

@@ -13,8 +13,8 @@
  * file, and appends.
  */
 import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { stateHome } from "../../lib/state-home.ts";
 import type { AgentStatus } from "../detect/classify.ts";
 
 /** A single session-level status transition. `from` is null the first time a session is seen. */
@@ -86,9 +86,9 @@ export function formatEventLine(
   return `${isoTime(ev.ts)} ${ev.session} ${from} → ${paint(ev.to, ev.to)}`;
 }
 
-/** Absolute path to the fleet event log. */
+/** Absolute path to the fleet event log (under the `TMUX_IDE_HOME`-aware home). */
 export function eventsPath(): string {
-  return join(homedir(), ".tmux-ide", "events.jsonl");
+  return join(stateHome(), "events.jsonl");
 }
 
 /**
@@ -106,7 +106,7 @@ export function appendEvents(
   if (events.length === 0) return;
   const path = eventsPath();
   try {
-    mkdirSync(join(homedir(), ".tmux-ide"), { recursive: true });
+    mkdirSync(stateHome(), { recursive: true });
     if (existsSync(path) && shouldRotate(statSync(path).size)) {
       renameSync(path, `${path}.1`);
     }

package/packages/daemon/src/tui/chrome/front-door.ts

@@ -0,0 +1,39 @@
+/**
+ * The chrome front door (M25.1) — the tiny, LEAF constants + argv builders the
+ * unified app needs to get a session watched without importing the chrome/data
+ * graph (app.tsx deliberately never imports the sync fleet-scan modules that
+ * {@link ./updater.ts} pulls in; see the FleetSession note there).
+ *
+ * "Watched" means: stamped with {@link ADOPTED_OPTION} so the background
+ * updater enumerates it (VERIFIED inert for a session that never ran `adopt` —
+ * none of adopt's status-row/border options are set, so the updater's status/
+ * chip var writes land on options nothing reads), and the updater itself
+ * ensured up. The sync twin of that flow lives in `updater.ts`
+ * (`startUpdaterIfNeeded`); the app uses these argvs with async execFile (the
+ * render-loop law).
+ */
+
+/** Per-session marker option set on adopt so the updater can enumerate adopted
+ *  sessions. (Owned here; re-exported by `updater.ts` for its callers.) */
+export const ADOPTED_OPTION = "@tmux_ide_adopted";
+
+/** The hidden internal session that hosts the updater loop. */
+export const UPDATER_SESSION = "_tmux-ide-chrome";
+
+/** PURE — stamp `session` watched (see the header: inert re: chrome painting). */
+export function adoptMarkArgv(session: string): string[] {
+  return ["set-option", "-t", session, ADOPTED_OPTION, "1"];
+}
+
+/** PURE — the existence probe for the updater session (`=` exact-match, so a
+ *  user session that merely starts with the name can't shadow it). Exit 0 =
+ *  running. */
+export function updaterProbeArgv(): string[] {
+  return ["has-session", "-t", `=${UPDATER_SESSION}`];
+}
+
+/** PURE — the argv that spawns the updater loop, detached. `exec` replaces the
+ *  shell so the pane IS the loop; killing the session stops it. */
+export function updaterSpawnArgv(): string[] {
+  return ["new-session", "-d", "-s", UPDATER_SESSION, "exec tmux-ide chrome-updater"];
+}

package/packages/daemon/src/tui/chrome/notify-prefs.ts

@@ -0,0 +1,58 @@
+/**
+ * Notification PREFERENCES — the pure shapes and parsing, hoisted out of
+ * {@link ./notify.ts} (which is io: node:child_process, node:fs, tmux).
+ *
+ * Why the split: `settings-model.ts` is pure and only needs `NotificationPrefs`
+ * + `parseHHMM`, but importing them from notify.ts dragged the whole io graph in
+ * behind them. That's invisible in the daemon (node has `process`), and it broke
+ * the moment a pure surface was imported anywhere else — the web host loads
+ * these same modules in a browser, where `process` does not exist.
+ *
+ * The rule this restores is the repo's own: pure core, thin io. Anything a pure
+ * module needs belongs in a pure module.
+ *
+ * notify.ts re-exports these, so existing importers are untouched.
+ */
+import type { NotificationSound } from "../../lib/app-config.ts";
+
+/** A local-time window, `HH:MM`–`HH:MM`. */
+export interface QuietHours {
+  /** Local `HH:MM` the window opens (e.g. `22:00`). */
+  start: string;
+  /** Local `HH:MM` the window closes (e.g. `08:00`). */
+  end: string;
+}
+
+export interface NotificationPrefs {
+  /** Master switch — false silences every channel. */
+  enabled: boolean;
+  /** In-terminal status-line toasts. */
+  toast: boolean;
+  /** System banners (native macOS helper, Linux `notify-send`). */
+  macos: boolean;
+  /** Terminal-native banners — OSC 9/99 escapes to eligible client ttys (M25.2). */
+  terminal: boolean;
+  /** Seconds the OS-level channels wait + re-verify before firing (0 = immediate). */
+  delaySeconds: number;
+  /** Sound channel — ping sound + BEL routing (M25.2). */
+  sound: NotificationSound;
+  /** Ping when an agent goes `blocked`. */
+  onBlocked: boolean;
+  /** Ping when an agent goes `done`. */
+  onDone: boolean;
+  /** Optional local-time window that suppresses every OS-LEVEL channel (banner,
+   *  terminal escape, sound, BEL — since M25.2). In-app toasts and the event
+   *  log stay on. */
+  quietHours: QuietHours | null;
+}
+
+/** PURE — parse `HH:MM` to minutes-since-midnight, or null when malformed / out of range. */
+export function parseHHMM(value: unknown): number | null {
+  if (typeof value !== "string") return null;
+  const m = /^(\d{2}):(\d{2})$/.exec(value.trim());
+  if (!m) return null;
+  const hours = Number(m[1]);
+  const minutes = Number(m[2]);
+  if (hours > 23 || minutes > 59) return null;
+  return hours * 60 + minutes;
+}

package/packages/daemon/src/tui/chrome/notify-state.ts

@@ -0,0 +1,76 @@
+/**
+ * Persistence for the notification debounce map (M25.1) — `lastNotified`
+ * survives updater restarts, so a respawned updater can't re-ping inside the
+ * debounce window (the old in-memory map made every restart an amnesty).
+ *
+ * Same split and same home discipline as {@link ../../lib/update-check.ts}:
+ * {@link serializeLastNotified} + {@link parseLastNotified} are PURE (and prune
+ * entries older than the debounce window — a stamp that can no longer suppress
+ * anything is dead weight); {@link loadLastNotified} / {@link saveLastNotified}
+ * are the thin, never-throwing io wrappers over
+ * `<TMUX_IDE_HOME>/notify-state.json`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stateHome } from "../../lib/state-home.ts";
+import { NOTIFY_DEBOUNCE_MS } from "./notify.ts";
+
+/** Absolute path to the persisted debounce map. */
+export function notifyStatePath(): string {
+  return join(stateHome(), "notify-state.json");
+}
+
+/** PURE — the JSON body for a debounce map, dropping entries whose timestamp
+ *  is already outside the debounce window (they can't suppress anything). */
+export function serializeLastNotified(map: ReadonlyMap<string, number>, nowMs: number): string {
+  const lastNotified: Record<string, number> = {};
+  for (const [key, ts] of map) {
+    if (nowMs - ts < NOTIFY_DEBOUNCE_MS) lastNotified[key] = ts;
+  }
+  return JSON.stringify({ lastNotified });
+}
+
+/** PURE — parse a persisted body back into the map, pruning stale entries.
+ *  Malformed input (or a FUTURE timestamp beyond the window — clock skew)
+ *  yields an empty/partial map, never a throw. */
+export function parseLastNotified(json: string, nowMs: number): Map<string, number> {
+  const out = new Map<string, number>();
+  try {
+    const parsed = JSON.parse(json) as { lastNotified?: unknown };
+    const raw = parsed?.lastNotified;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
+    for (const [key, ts] of Object.entries(raw as Record<string, unknown>)) {
+      if (typeof ts !== "number") continue;
+      if (nowMs - ts >= NOTIFY_DEBOUNCE_MS) continue; // expired
+      if (ts - nowMs > NOTIFY_DEBOUNCE_MS) continue; // absurd future stamp
+      out.set(key, ts);
+    }
+  } catch {
+    // unreadable state just means a fresh debounce map
+  }
+  return out;
+}
+
+/** io — load the persisted map (empty when missing/unreadable). Never throws. */
+export function loadLastNotified(nowMs: number = Date.now()): Map<string, number> {
+  const path = notifyStatePath();
+  if (!existsSync(path)) return new Map();
+  try {
+    return parseLastNotified(readFileSync(path, "utf-8"), nowMs);
+  } catch {
+    return new Map();
+  }
+}
+
+/** io — persist the map (creating the home if needed). Best-effort. */
+export function saveLastNotified(
+  map: ReadonlyMap<string, number>,
+  nowMs: number = Date.now(),
+): void {
+  try {
+    mkdirSync(stateHome(), { recursive: true });
+    writeFileSync(notifyStatePath(), serializeLastNotified(map, nowMs));
+  } catch {
+    // an unwritable map just means a restart re-arms the debounce — never fatal
+  }
+}