tmux-ide 2.6.1 → 2.8.0

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

@@ -21,6 +21,7 @@
  * without a live tmux; `adoptedSessionsFrom` is a pure parser.
  */
 import { hasSession, isProcessAlive, runTmux } from "@tmux-ide/tmux-bridge";
+import { ADOPTED_OPTION, UPDATER_SESSION, updaterSpawnArgv } from "./front-door.ts";
 import { DEFAULT_THEME, getAppConfig, type AppTheme } from "../../lib/app-config.ts";
 import {
   maybeCheckForUpdate,
@@ -28,21 +29,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,
@@ -55,10 +68,15 @@ import { buildStatusline } from "./statusline.ts";
 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,
+  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. */
@@ -137,18 +155,55 @@ 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?: (message: string) => 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
+   * pure stub. Only ever called for the pane behind a blocked/done transition.
+   */
+  locatePane?: (paneId: string) => string;
   /**
    * Update-flow surfacing (optional). When wired, the tick calls this cheap,
    * cache-backed check each tick (throttled internally to 24h; it kicks off a
@@ -159,6 +214,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;
 }
 
 /**
@@ -172,8 +235,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 })));
 }
 
@@ -204,15 +270,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, events);
-    }
+    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);
   }
 }
 
@@ -241,21 +315,174 @@ function writeChips(
   }
 }
 
+/**
+ * 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 diffPaneTransitions(
+  prev: Map<string, AgentStatus>,
+  panes: PaneDetail[],
+  locate?: (paneId: string) => string,
+): NotifyEvent[] {
+  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 AND at least one channel is enabled;
- * `lastNotified` is mutated in place so the debounce persists across ticks.
+ * 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 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.toast && !prefs.macos) return;
-  const decision = decideNotifications(events, listClients(), lastNotified, now());
+  if (!prefs.enabled) return;
+  if (!anyChannelOn(prefs)) return;
+  const nowMs = now();
+  const decision = decideNotifications(
+    events,
+    listClients(),
+    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) {
-    for (const { message } of decision.system) sendSystem(message);
+  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();
+  }
+}
+
+/**
+ * io — resolve a pane id to `session:window.pane` (e.g. `myproj:1.2`) for the
+ * ping text. Best-effort: a gone pane / failed call degrades to the raw pane id.
+ */
+export function paneLocation(paneId: string): string {
+  try {
+    const raw = runTmux([
+      "display-message",
+      "-p",
+      "-t",
+      paneId,
+      "#{session_name}:#{window_index}.#{pane_index}",
+    ])
+      .toString()
+      .trim();
+    return raw || paneId;
+  } catch {
+    return paneId;
   }
 }
 
@@ -300,15 +527,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
   }
@@ -360,11 +586,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;
@@ -375,10 +633,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({
@@ -387,6 +659,7 @@ export function runUpdaterLoop(): void {
     write: writeSnapshot,
     every: config.updater.snapshotEvery,
   });
+  const shouldGiveUp = createUnreachableCounter();
   const tick = () => {
     try {
       runUpdaterTick({
@@ -398,14 +671,22 @@ export function runUpdaterLoop(): void {
         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
@@ -415,8 +696,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);
@@ -425,4 +712,5 @@ export function runUpdaterLoop(): void {
   };
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
+  tick();
 }

package/packages/daemon/src/tui/compiled.ts

@@ -9,7 +9,9 @@
  *
  * Order is "checkout first, binary second": a dev machine that happens to have
  * built the binary still uses its live `.tsx` sources. The binary is consulted
- * only when the checkout sources or `bun` are missing.
+ * only when the checkout sources or `bun` are missing. {@link findCompiledTui}
+ * probes the shipped/local compiled binary first, then a per-platform binary
+ * downloaded at runtime into `~/.tmux-ide/bin/` (see lib/tui-binary.ts).
  *
  * {@link resolveTuiLaunch} is a PURE decision (unit-tested); {@link findCompiledTui}
  * and {@link isBunAvailable} are the thin io probes that feed it.
@@ -18,6 +20,7 @@ import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
+import { findDownloadedTui } from "../lib/tui-binary.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -63,7 +66,7 @@ export function resolveTuiLaunch(input: TuiResolveInput): TuiLaunch {
     reasons.push("the `bun` runtime is not installed (https://bun.sh)");
   }
   reasons.push(
-    "no compiled `tmux-ide-tui` binary was found (build one with `pnpm build:tui`, or reinstall a release that ships it)",
+    "no compiled `tmux-ide-tui` binary was found (build one with `pnpm build:tui`, download it with `tmux-ide update --tui-binary`, or reinstall a release that ships it)",
   );
   return { mode: "unavailable", reasons };
 }
@@ -99,7 +102,12 @@ export function findCompiledTui(): string | null {
       if (existsSync(candidate)) return candidate;
     }
   }
-  return null;
+
+  // Last: a per-platform binary fetched at runtime by `tmux-ide update
+  // --tui-binary` into `~/.tmux-ide/bin/` — the fallback for an npm install with
+  // no bun and no shipped compiled binary. Version-stamped, so it only matches
+  // the running version (see lib/tui-binary.ts).
+  return findDownloadedTui();
 }
 
 /** io — is the `bun` runtime callable? */

package/packages/daemon/src/tui/detect/classify.ts

@@ -49,6 +49,55 @@ export function parseAuthority(raw: string | undefined, nowSec: number): AgentSt
   return state as AgentStatus;
 }
 
+/** Display-metadata budget — `@agent_status_text` / `@agent_display_name`
+ *  values are clamped to this many characters (ellipsis included). */
+export const AGENT_TEXT_MAX = 32;
+
+/**
+ * Sanitize a self-reported display-metadata pane option
+ * (`@agent_status_text` / `@agent_display_name`) — PURE, never throws.
+ *
+ * ANSI escape sequences are stripped, remaining control characters become
+ * spaces, runs of whitespace collapse to one space, and the result is clamped
+ * to {@link AGENT_TEXT_MAX} characters (with a trailing ellipsis when cut).
+ * Returns undefined for an absent or effectively-empty value, so callers can
+ * spread the field additively (`...(text ? { statusText: text } : {})`).
+ *
+ * Freshness is NOT judged here: the metadata options carry no epoch of their
+ * own — they ride the pane's `@agent_state` stamp, and the caller surfaces
+ * them only while {@link parseAuthority} reports that stamp fresh.
+ */
+export function sanitizeAgentText(raw: string | undefined): string | undefined {
+  if (!raw) return undefined;
+  const cleaned = raw
+    // CSI escape sequences (colors, cursor moves) — drop entirely.
+    // eslint-disable-next-line no-control-regex
+    .replace(/\x1b\[[0-9;?]*[ -/]*[\x40-\x7e]/g, "")
+    // Any remaining C0 control chars (incl. bare ESC, tabs, newlines) + DEL.
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f\x7f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (cleaned.length === 0) return undefined;
+  if (cleaned.length <= AGENT_TEXT_MAX) return cleaned;
+  return cleaned.slice(0, AGENT_TEXT_MAX - 1) + "…";
+}
+
+/**
+ * Extract the epoch STAMP from an `@agent_state` value (`"<state>:<epoch>"`) —
+ * the "since" timestamp of the reported state. PURE — returns the epoch, or
+ * null when the value is absent or its stamp isn't a finite number. Staleness
+ * is NOT considered here (that's {@link parseAuthority}'s job); callers pair
+ * this with a fresh `parseAuthority` result to surface a state's `since`.
+ */
+export function parseAuthorityEpoch(raw: string | undefined): number | null {
+  if (!raw) return null;
+  const sep = raw.lastIndexOf(":");
+  if (sep === -1) return null;
+  const epoch = Number(raw.slice(sep + 1));
+  return Number.isFinite(epoch) ? epoch : null;
+}
+
 /**
  * Classify a single snapshot against a manifest — PURE, never throws.
  *