tmux-ide 2.7.0 → 2.9.0-beta.5

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

@@ -21,6 +21,13 @@
  * without a live tmux; `adoptedSessionsFrom` is a pure parser.
  */
 import { hasSession, isProcessAlive, runTmux } from "@tmux-ide/tmux-bridge";
+import {
+  ADOPTED_OPTION,
+  CHIP_OPTION,
+  PANE_CHROME_BORDER_FORMAT,
+  UPDATER_SESSION,
+  updaterSpawnArgv,
+} from "./front-door.ts";
 import { DEFAULT_THEME, getAppConfig, type AppTheme } from "../../lib/app-config.ts";
 import {
   maybeCheckForUpdate,
@@ -28,24 +35,33 @@ import {
   type UpdateStatus,
 } from "../../lib/update-check.ts";
 import { createStatusTracker, type AgentStatus } from "../detect/classify.ts";
+import { createSessionIdCapturer } from "../detect/session-id.ts";
 import { listTeamProjects, type TeamProject } from "../team/projects.ts";
 import type { PaneDetail } from "../team/sessions.ts";
 import { paneChip } from "./chip.ts";
 import { appendEvents, diffFleet, type AgentEventInit } from "./events.ts";
 import {
   decideNotifications,
+  decideTtyWrites,
   enabledStates,
   inQuietHours,
   listAttachedClients,
+  playPingSound,
+  readAppFocus,
   readNotificationPrefs,
   sendSystemNotification,
   sendToasts,
+  soundEligible,
+  writeTtys,
+  type AppFocus,
   type AttachedClient,
   type NotificationPrefs,
   type NotifyEvent,
   type SystemNotification,
   type ToastTarget,
+  type TtyWrite,
 } from "./notify.ts";
+import { loadLastNotified, saveLastNotified } from "./notify-state.ts";
 import {
   collectFleetSnapshot,
   createSnapshotter,
@@ -56,12 +72,16 @@ import { buildStatusline } from "./statusline.ts";
 
 /** Per-session user option holding the pre-rendered status-bar string. */
 export const STATUS_OPTION = "@tmux_ide_status";
-/** Per-PANE user option holding the pre-rendered agent chip (read by pane-border-format). */
-export const CHIP_OPTION = "@tmux_ide_chip";
-/** Per-session marker option set on adopt so the updater can enumerate adopted sessions. */
-export const ADOPTED_OPTION = "@tmux_ide_adopted";
-/** The hidden internal session that hosts the updater loop. */
-export const UPDATER_SESSION = "_tmux-ide-chrome";
+// The adopted marker, the updater session name, and their argv builders live
+// in the LEAF module front-door.ts (the unified app imports them without
+// pulling this module's fleet-scan graph); re-exported here for the chrome.
+export {
+  ADOPTED_OPTION,
+  CHIP_OPTION,
+  UPDATER_SESSION,
+  updaterProbeArgv,
+  updaterSpawnArgv,
+} from "./front-door.ts";
 /** Server option holding the running updater's pid (a lightweight single-owner guard). */
 export const UPDATER_PID_OPTION = "@tmux_ide_updater_pid";
 /** Default tick cadence — overridable via `updater.tickMs` in the app config. */
@@ -95,6 +115,94 @@ export function listAdoptedSessions(): string[] {
   }
 }
 
+/**
+ * Parse the single fleet-wide window probe into windows whose panel-chrome row
+ * is missing. Kept pure so the per-tick enforcement has no hidden grammar.
+ */
+export function paneChromeWindowTargetsFrom(
+  lines: readonly string[],
+  adoptedSessions: readonly string[],
+): string[] {
+  const adopted = new Set(adoptedSessions);
+  const targets: string[] = [];
+  for (const line of lines) {
+    const [session = "", windowId = "", status = ""] = line.split("\t");
+    if (adopted.has(session) && /^@\d+$/u.test(windowId) && status !== "top") {
+      targets.push(windowId);
+    }
+  }
+  return targets;
+}
+
+/**
+ * Parse every valid window identity belonging to the selected sessions. Used
+ * when removing chrome, where already-top windows must be restored too.
+ */
+export function paneChromeWindowIdsFrom(
+  lines: readonly string[],
+  sessions: readonly string[],
+): string[] {
+  const selected = new Set(sessions);
+  const targets: string[] = [];
+  for (const line of lines) {
+    const [session = "", windowId = ""] = line.split("\t");
+    if (selected.has(session) && /^@\d+$/u.test(windowId)) targets.push(windowId);
+  }
+  return targets;
+}
+
+function listPaneChromeWindows(): string[] {
+  const raw = runTmux([
+    "list-windows",
+    "-a",
+    "-F",
+    "#{session_name}\t#{window_id}\t#{pane-border-status}",
+  ])
+    .toString()
+    .trim();
+  return raw ? raw.split("\n") : [];
+}
+
+/**
+ * Keep every window of every adopted session on the shared top-border chrome
+ * contract. New tmux windows start with their own window options, so setting
+ * only the session's current window during adoption is insufficient.
+ */
+export function enforcePaneChromeWindows(adoptedSessions: readonly string[]): void {
+  if (adoptedSessions.length === 0) return;
+  const targets = paneChromeWindowTargetsFrom(listPaneChromeWindows(), adoptedSessions);
+  for (const windowId of targets) {
+    try {
+      runTmux(["set-option", "-w", "-t", windowId, "pane-border-status", "top"]);
+      runTmux([
+        "set-option",
+        "-w",
+        "-t",
+        windowId,
+        "pane-border-format",
+        PANE_CHROME_BORDER_FORMAT,
+      ]);
+    } catch {
+      // A window can disappear between the fleet probe and these writes. The
+      // next tick repairs survivors; a closing window needs no repair.
+    }
+  }
+}
+
+/** Restore inherited pane-border options on every window being unadopted. */
+export function clearPaneChromeWindows(sessions: readonly string[]): void {
+  if (sessions.length === 0) return;
+  const targets = paneChromeWindowIdsFrom(listPaneChromeWindows(), sessions);
+  for (const windowId of targets) {
+    try {
+      runTmux(["set-option", "-uw", "-t", windowId, "pane-border-status"]);
+      runTmux(["set-option", "-uw", "-t", windowId, "pane-border-format"]);
+    } catch {
+      // Same close-race as enforcement; disappearing windows are already clean.
+    }
+  }
+}
+
 /** Write a session's pre-rendered status var. */
 function writeSessionStatus(session: string, value: string): void {
   runTmux(["set-option", "-t", session, STATUS_OPTION, value]);
@@ -116,6 +224,8 @@ export interface UpdaterTickDeps {
    */
   computeProjects: (onPane: (pane: PaneDetail) => void) => TeamProject[];
   writeStatus: (session: string, value: string) => void;
+  /** Repair new/external windows onto the shared top-border chrome contract. */
+  enforcePaneChrome?: (adoptedSessions: readonly string[]) => void;
   /**
    * The shared palette threaded into {@link buildStatusline} / {@link paneChip}
    * (default {@link DEFAULT_THEME}). The loop resolves it once from the app
@@ -140,18 +250,49 @@ export interface UpdaterTickDeps {
   prevState?: Map<string, AgentStatus>;
   appendEvents?: (events: AgentEventInit[]) => void;
   /**
-   * Notification dispatch (optional). When wired alongside `prevState`, the tick
-   * turns THIS tick's transitions into user pings — toasts on attached clients
-   * and/or a macOS notification — via {@link decideNotifications}, gated on
-   * `prefs`. `lastNotified` is the persistent debounce map, mutated in place.
-   * All deps-injected so the routing is unit-tested without a live tmux.
+   * Notification dispatch (optional). When wired alongside `prevPaneState`
+   * (M25.1 — notifications are PANE-granular so a second agent blocking in an
+   * already-blocked session still pings), the tick turns THIS tick's pane
+   * transitions into user pings — toasts on attached clients and/or a macOS
+   * notification — via {@link decideNotifications}, gated on `prefs`.
+   * `lastNotified` is the persistent debounce map, mutated in place (and
+   * persisted via `persistNotified` when a ping fired, so a restart can't
+   * re-ping inside the window). All deps-injected so the routing is
+   * unit-tested without a live tmux.
    */
+  prevPaneState?: Map<string, AgentStatus>;
   listClients?: () => AttachedClient[];
   lastNotified?: Map<string, number>;
   now?: () => number;
   prefs?: NotificationPrefs;
   sendToasts?: (toasts: ToastTarget[]) => void;
   sendSystem?: (n: SystemNotification) => void;
+  /**
+   * The OS-level channel io (M25.2), both optional and deps-injected like the
+   * rest: `sendTerminal` writes OSC 9/99 + BEL bytes to client ttys
+   * ({@link writeTtys}); `playSound` fires the platform ping sound
+   * ({@link playPingSound}). Which clients/states qualify is decided purely
+   * ({@link decideTtyWrites} / {@link soundEligible}).
+   */
+  sendTerminal?: (writes: TtyWrite[]) => void;
+  playSound?: () => void;
+  /**
+   * The DELAYED RE-VERIFY queue (M25.2), loop-owned and mutated in place like
+   * `prevPaneState`. With `notifications.delaySeconds > 0`, a notify-eligible
+   * transition queues its OS-LEVEL channels here instead of firing them; each
+   * tick {@link firePendingOsPings} fires the due entries whose pane is STILL
+   * in the notified state (this tick's scan is the re-verify — no setTimeout
+   * racing the tick), so a flappy blocked→working inside the window fires
+   * nothing OS-level. Toasts never queue — the in-app note stays immediate.
+   * Omitted (tests, delay 0) → OS channels fire immediately.
+   */
+  pendingPings?: PendingOsPing[];
+  /** The unified app's focus record (see {@link AppFocus}) — pings for panes
+   *  on the app's screen are suppressed. Wired to {@link readAppFocus}. */
+  appFocus?: () => AppFocus | null;
+  /** Persist the debounce map after a tick that fired a ping. Wired to
+   *  {@link saveLastNotified}. */
+  persistNotified?: (map: ReadonlyMap<string, number>) => void;
   /**
    * Resolve a pane id to its human `session:window.pane` location for the ping
    * text (optional). Wired to the live tmux {@link paneLocation}; tests inject a
@@ -168,6 +309,14 @@ export interface UpdaterTickDeps {
    */
   maybeCheckForUpdate?: () => UpdateStatus;
   markUpdateNotified?: (version: string) => boolean;
+  /**
+   * Session-id capture (optional). When wired, receives this tick's per-pane
+   * detail so the capturer ({@link ../detect/session-id.ts}) can stamp
+   * `@agent_session_id` on codex/cursor panes that lack one — the key
+   * `restore --resume-agents` resumes from. Self-throttled and stamp-once, so
+   * a fleet with no unstamped capturable panes costs nothing.
+   */
+  captureSessionIds?: (panes: PaneDetail[]) => void;
 }
 
 /**
@@ -181,8 +330,11 @@ export function updateSegment(status: UpdateStatus, theme: AppTheme): string {
   return `#[range=user|update]#[fg=${theme.accent}]⬆ v${status.latest}#[default]#[norange]`;
 }
 
-/** Flatten the project view to a flat per-session status list for {@link diffFleet}. */
-function fleetStatuses(projects: TeamProject[]): Array<{ name: string; status: AgentStatus }> {
+/** Flatten the project view to a flat per-session status list for {@link diffFleet}.
+ *  Exported: the control server's event tick diffs the same projection. */
+export function fleetStatuses(
+  projects: TeamProject[],
+): Array<{ name: string; status: AgentStatus }> {
   return projects.flatMap((p) => p.sessions.map((s) => ({ name: s.name, status: s.status })));
 }
 
@@ -200,6 +352,7 @@ function fleetStatuses(projects: TeamProject[]): Array<{ name: string; status: A
 export function runUpdaterTick(deps: UpdaterTickDeps): void {
   const adopted = deps.listAdopted();
   if (adopted.length === 0) return;
+  deps.enforcePaneChrome?.(adopted);
   const theme = deps.theme ?? DEFAULT_THEME;
   // Collect per-pane detail during the fleet scan so chips need no second pass.
   const panes: PaneDetail[] = [];
@@ -213,15 +366,23 @@ export function runUpdaterTick(deps: UpdaterTickDeps): void {
     deps.writeStatus(session, buildStatusline(projects, session, 12, theme, extra));
   }
   writeChips(deps, adopted, panes, theme);
+  deps.captureSessionIds?.(panes);
   if (update?.updateAvailable && update.latest) dispatchUpdateToast(deps, update.latest);
   if (deps.prevState && deps.appendEvents) {
     const { events, state } = diffFleet(deps.prevState, fleetStatuses(projects));
     deps.prevState.clear();
     for (const [name, status] of state) deps.prevState.set(name, status);
-    if (events.length > 0) {
-      deps.appendEvents(events);
-      dispatchNotifications(deps, enrichEvents(events, panes, deps.locatePane));
-    }
+    if (events.length > 0) deps.appendEvents(events);
+  }
+  // Notifications ride PANE transitions (M25.1), not the session rollup — a
+  // second agent blocking in an already-blocked session is invisible at the
+  // session level but is exactly who the user needs to hear about. Due delayed
+  // pings re-verify against THIS tick's pane states before the diff mutates
+  // anything (M25.2).
+  if (deps.prevPaneState) {
+    firePendingOsPings(deps, panes);
+    const events = diffPaneTransitions(deps.prevPaneState, panes, deps.locatePane);
+    if (events.length > 0) dispatchNotifications(deps, events);
   }
 }
 
@@ -251,58 +412,72 @@ function writeChips(
 }
 
 /**
- * PURE — pick the pane to name in a session-level ping. A session rolls up many
- * panes; the ping should point at ONE. We take a pane whose status matches the
- * transition (`to`), preferring one that resolved to a real agent (so the ping
- * reads `claude blocked …`, not a bare shell). Null when no pane matches — the
- * updater then falls back to the session name / a generic label.
- */
-export function pickRepresentativePane(
-  session: string,
-  to: AgentStatus,
-  panes: PaneDetail[],
-): PaneDetail | null {
-  const matching = panes.filter((p) => p.sessionName === session && p.status === to);
-  if (matching.length === 0) return null;
-  return matching.find((p) => p.agent !== null) ?? matching[0]!;
-}
-
-/**
- * PURE — enrich session-level transitions with the pane's `agent` id and human
- * `location` so {@link notifyMessage} can name who needs the user. Only the
- * notifiable states (blocked/done) get resolved — everything else keeps the bare
- * session as its location and is filtered out downstream anyway, so `locate`
- * (a live tmux call) only fires for a real ping.
+ * PURE (given `locate`) — diff the previous per-pane states against this
+ * tick's panes into ready-to-ping {@link NotifyEvent}s: each carries its
+ * `paneId` (the debounce/visibility key), `windowIndex` (window-granular toast
+ * suppression), the pane's resolved `agent`, and — only for a notifiable
+ * blocked/done transition that isn't first-sight — the human `location`
+ * (`locate` is a live tmux call, so it only fires for a potential ping).
+ * `prev` is mutated in place to the fresh state, like the session-level
+ * `prevState`; a pane that vanished simply drops out. First sight of a pane
+ * emits `from: null`, which {@link decideNotifications} ignores — that's the
+ * restart/first-tick grace.
  */
-export function enrichEvents(
-  events: AgentEventInit[],
+export function diffPaneTransitions(
+  prev: Map<string, AgentStatus>,
   panes: PaneDetail[],
   locate?: (paneId: string) => string,
 ): NotifyEvent[] {
-  return events.map((ev) => {
-    const notifiable = ev.to === "blocked" || ev.to === "done";
-    const rep = notifiable ? pickRepresentativePane(ev.session, ev.to, panes) : null;
-    return {
-      ...ev,
-      agent: rep?.agent ?? null,
-      location: rep && locate ? locate(rep.paneId) : ev.session,
-    };
-  });
+  const events: NotifyEvent[] = [];
+  const next = new Map<string, AgentStatus>();
+  for (const pane of panes) {
+    const before = prev.has(pane.paneId) ? prev.get(pane.paneId)! : null;
+    next.set(pane.paneId, pane.status);
+    if (before === pane.status) continue;
+    const notifiable = before !== null && (pane.status === "blocked" || pane.status === "done");
+    events.push({
+      session: pane.sessionName,
+      from: before,
+      to: pane.status,
+      paneId: pane.paneId,
+      windowIndex: pane.windowIndex,
+      agent: pane.agent,
+      location: notifiable && locate ? locate(pane.paneId) : pane.sessionName,
+    });
+  }
+  prev.clear();
+  for (const [paneId, status] of next) prev.set(paneId, status);
+  return events;
+}
+
+/** A queued OS-level ping: the {@link SystemNotification} payload plus when it
+ *  becomes due. Fires only if its pane is STILL in `state` at fire time. */
+export interface PendingOsPing extends SystemNotification {
+  dueAtMs: number;
+}
+
+/** PURE — whether ANY channel beyond the master switch is on; an all-off
+ *  config costs the tick nothing. */
+function anyChannelOn(prefs: NotificationPrefs): boolean {
+  return prefs.toast || prefs.macos || prefs.terminal || prefs.sound !== "none";
 }
 
 /**
  * Ping the user about who needs them from this tick's transitions. Only runs
  * when the notification deps are wired, notifications are `enabled`, AND at
  * least one channel is on. `lastNotified` is mutated in place so the debounce
- * (the flap guard) persists across ticks. The macOS banner is additionally
- * gated on QUIET HOURS — inside the window the banner is skipped, but the event
- * has already been recorded to the log by the caller, so history stays honest.
+ * (the flap guard) persists across ticks. The in-app toast fires IMMEDIATELY
+ * (cheap, low-annoyance); the OS-LEVEL channels (banner / terminal escape /
+ * sound / BEL) either fire now (`delaySeconds` 0 or no queue wired) or queue
+ * onto `pendingPings` for the delayed re-verify (M25.2). The debounce stamp
+ * lands at DECIDE time either way — a flap that later cancels its OS ping
+ * already toasted, so it spent its debounce slot honestly.
  */
 function dispatchNotifications(deps: UpdaterTickDeps, events: NotifyEvent[]): void {
-  const { listClients, lastNotified, now, prefs, sendToasts: toast, sendSystem } = deps;
+  const { listClients, lastNotified, now, prefs, sendToasts: toast } = deps;
   if (!listClients || !lastNotified || !now || !prefs) return;
   if (!prefs.enabled) return;
-  if (!prefs.toast && !prefs.macos) return;
+  if (!anyChannelOn(prefs)) return;
   const nowMs = now();
   const decision = decideNotifications(
     events,
@@ -310,12 +485,79 @@ function dispatchNotifications(deps: UpdaterTickDeps, events: NotifyEvent[]): vo
     lastNotified,
     nowMs,
     enabledStates(prefs),
+    deps.appFocus?.() ?? null,
   );
   lastNotified.clear();
   for (const [key, ts] of decision.nextLastNotified) lastNotified.set(key, ts);
+  // A system entry exists for every event that actually fired (stamped the
+  // debounce map), so this is exactly "the map changed — persist it".
+  if (decision.system.length > 0) deps.persistNotified?.(lastNotified);
   if (prefs.toast && toast) toast(decision.toasts);
-  if (prefs.macos && sendSystem && !inQuietHours(new Date(nowMs), prefs.quietHours)) {
-    for (const n of decision.system) sendSystem(n);
+  if (decision.system.length === 0) return;
+  const delayMs = prefs.delaySeconds * 1000;
+  if (delayMs > 0 && deps.pendingPings) {
+    for (const n of decision.system) deps.pendingPings.push({ ...n, dueAtMs: nowMs + delayMs });
+  } else {
+    fireOsChannels(deps, prefs, decision.system, nowMs);
+  }
+}
+
+/**
+ * Fire the DUE queued OS pings whose transition still holds (M25.2). The
+ * re-verify is tick-native: this tick's fresh pane scan is the source of truth
+ * — a pane that flapped out of the notified state, vanished, or is now on the
+ * unified app's screen ({@link AppFocus} — the user got there on their own)
+ * fires nothing and is dropped. Prefs are the CURRENT tick's fresh read, so a
+ * config change during the delay is honored. Runs before this tick's diff so
+ * "the next tick's pane states" is literally what confirms each ping.
+ */
+function firePendingOsPings(deps: UpdaterTickDeps, panes: PaneDetail[]): void {
+  const { pendingPings: pending, now, prefs } = deps;
+  if (!pending || pending.length === 0 || !now || !prefs) return;
+  const nowMs = now();
+  const due: PendingOsPing[] = [];
+  const keep: PendingOsPing[] = [];
+  for (const p of pending) (p.dueAtMs <= nowMs ? due : keep).push(p);
+  if (due.length === 0) return;
+  pending.length = 0;
+  for (const p of keep) pending.push(p);
+  if (!prefs.enabled) return;
+  const statusByPane = new Map(panes.map((p) => [p.paneId, p.status]));
+  const focus = deps.appFocus?.() ?? null;
+  const confirmed = due.filter((p) => {
+    // A pane-less ping (session-granular caller) can't be re-verified — fire it.
+    if (p.paneId !== null && statusByPane.get(p.paneId) !== p.state) return false;
+    if (focus?.attached && p.paneId !== null && focus.panes.includes(p.paneId)) return false;
+    return true;
+  });
+  fireOsChannels(deps, prefs, confirmed, nowMs);
+}
+
+/**
+ * The OS-LEVEL fan-out (M25.2): system banner, terminal escapes + BEL to
+ * eligible client ttys, and the ping sound (at most ONE sound per batch — a
+ * fleet-wide flap must not ring a carillon). ALL of it is gated on quiet hours
+ * — inside the window nothing OS-level fires (the in-app toast and the event
+ * log have already surfaced the transition, so history stays honest).
+ */
+function fireOsChannels(
+  deps: UpdaterTickDeps,
+  prefs: NotificationPrefs,
+  entries: SystemNotification[],
+  nowMs: number,
+): void {
+  if (entries.length === 0) return;
+  if (inQuietHours(new Date(nowMs), prefs.quietHours)) return;
+  if (prefs.macos && deps.sendSystem) {
+    for (const n of entries) deps.sendSystem(n);
+  }
+  if ((prefs.terminal || prefs.sound !== "none") && deps.sendTerminal && deps.listClients) {
+    const clients = deps.listClients();
+    const writes = entries.flatMap((n) => decideTtyWrites(n, clients, prefs));
+    if (writes.length > 0) deps.sendTerminal(writes);
+  }
+  if (deps.playSound && entries.some((n) => soundEligible(n.state, prefs.sound))) {
+    deps.playSound();
   }
 }
 
@@ -381,15 +623,14 @@ export function updaterRunning(): boolean {
 
 /**
  * Ensure the background updater is running: if the `_tmux-ide-chrome` session
- * isn't up, start it detached running `tmux-ide chrome-updater`. `exec` replaces
- * the shell so the pane IS the loop; killing the session stops it. `_`-internal
+ * isn't up, start it detached running `tmux-ide chrome-updater`. `_`-internal
  * so it's hidden from the bar/switcher. Best-effort — a chrome failure must
  * never break adopt/launch.
  */
 export function startUpdaterIfNeeded(): void {
   try {
     if (updaterRunning()) return;
-    runTmux(["new-session", "-d", "-s", UPDATER_SESSION, "exec tmux-ide chrome-updater"]);
+    runTmux(updaterSpawnArgv());
   } catch {
     // best-effort — the bar still works via the last-written var
   }
@@ -441,11 +682,43 @@ function releaseUpdater(): void {
   }
 }
 
+/** Exit the loop after this many CONSECUTIVE ticks with the tmux server gone —
+ *  a dead server means nothing to watch and nobody to ping, and an immortal
+ *  interval would zombie (two were found live before M25.1). */
+export const UPDATER_UNREACHABLE_EXIT_TICKS = 5;
+
+/** PURE — a consecutive-failure counter: feed it each tick's reachability;
+ *  it answers "give up now?" after `threshold` misses in a row (any success
+ *  resets the run). */
+export function createUnreachableCounter(
+  threshold: number = UPDATER_UNREACHABLE_EXIT_TICKS,
+): (reachable: boolean) => boolean {
+  let consecutive = 0;
+  return (reachable: boolean): boolean => {
+    consecutive = reachable ? 0 : consecutive + 1;
+    return consecutive >= threshold;
+  };
+}
+
+/** io — can we still talk to the tmux server? (A server with zero sessions
+ *  exits, so `list-sessions` failing means the server itself is gone.) */
+function isServerReachable(): boolean {
+  try {
+    runTmux(["list-sessions", "-F", "#{session_name}"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Run the updater loop forever (the body of `tmux-ide chrome-updater`). Claims
  * single-ownership, then rewrites every adopted session's bar immediately and
  * every {@link TICK_MS} thereafter behind ONE persistent tracker (so `done`
- * transitions surface). Blocks — the interval keeps the event loop alive.
+ * transitions surface). Blocks — the interval keeps the event loop alive —
+ * until the tmux server has been unreachable for
+ * {@link UPDATER_UNREACHABLE_EXIT_TICKS} consecutive ticks, at which point the
+ * loop logs once and exits instead of running headless forever.
  */
 export function runUpdaterLoop(): void {
   if (!claimUpdater()) return;
@@ -456,10 +729,24 @@ export function runUpdaterLoop(): void {
   const tracker = createStatusTracker();
   // Persistent across ticks so `diffFleet` can spot working→done etc.
   const prevState = new Map<string, AgentStatus>();
-  // Persistent so the notification debounce survives across ticks.
-  const lastNotified = new Map<string, number>();
+  // Per-PANE states for the notification path (M25.1 — pane-granular pings).
+  const prevPaneState = new Map<string, AgentStatus>();
+  // The notification debounce map — restored from disk so a restart can't
+  // re-ping inside the window, persisted back on every ping.
+  const lastNotified = loadLastNotified();
+  // Queued OS-level pings awaiting their delayed re-verify (M25.2). In-memory
+  // only: the window is seconds, so a restart just drops the queue.
+  const pendingPings: PendingOsPing[] = [];
   // Persistent per-pane chip cache so we only rewrite a chip when it changed.
   const chipCache = new Map<string, string>();
+  // Session-id capture for kinds without a hook integration (codex/cursor):
+  // stamps @agent_session_id so restore --resume-agents has its key. Throttled
+  // internally; probes only unstamped panes of capturable kinds.
+  const capturer = createSessionIdCapturer({
+    // Throwing is fine here — the capturer treats a failed stamp as "retry on
+    // the next capture window".
+    stamp: (paneId, id) => runTmux(["set-option", "-p", "-t", paneId, "@agent_session_id", id]),
+  });
   // The fleet snapshotter — pulsed each tick, self-throttled, writes only on a
   // structural change so the fleet can be rebuilt after a tmux-server death.
   const snapshotter = createSnapshotter({
@@ -468,26 +755,35 @@ export function runUpdaterLoop(): void {
     write: writeSnapshot,
     every: config.updater.snapshotEvery,
   });
+  const shouldGiveUp = createUnreachableCounter();
   const tick = () => {
     try {
       runUpdaterTick({
         listAdopted: listAdoptedSessions,
         computeProjects: (onPane) => listTeamProjects(tracker, { onPane }),
         writeStatus: writeSessionStatus,
+        enforcePaneChrome: enforcePaneChromeWindows,
         theme: config.theme,
         writeChip: writePaneChip,
         chipCache,
         prevState,
         appendEvents,
+        prevPaneState,
         listClients: listAttachedClients,
         lastNotified,
         now: () => Date.now(),
         prefs: readNotificationPrefs(),
         sendToasts,
         sendSystem: sendSystemNotification,
+        sendTerminal: writeTtys,
+        playSound: playPingSound,
+        pendingPings,
         locatePane: paneLocation,
+        appFocus: () => readAppFocus(),
+        persistNotified: (map) => saveLastNotified(map),
         maybeCheckForUpdate: () => maybeCheckForUpdate({ enabled: config.updates.check }),
         markUpdateNotified,
+        captureSessionIds: (panes) => capturer.onTick(panes),
       });
     } catch {
       // never let one bad tick kill the loop
@@ -497,8 +793,14 @@ export function runUpdaterLoop(): void {
     } catch {
       // a failed snapshot just means staler disaster-recovery state
     }
+    // Self-exit when the server we exist to watch is gone (logged ONCE).
+    if (shouldGiveUp(isServerReachable())) {
+      console.error(
+        `tmux-ide chrome-updater: tmux server unreachable for ${UPDATER_UNREACHABLE_EXIT_TICKS} consecutive ticks — exiting`,
+      );
+      shutdown();
+    }
   };
-  tick();
   const timer = setInterval(tick, config.updater.tickMs);
   const shutdown = () => {
     clearInterval(timer);
@@ -507,4 +809,5 @@ export function runUpdaterLoop(): void {
   };
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
+  tick();
 }