tmux-ide 2.7.0 → 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,24 +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,
@@ -58,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. */
@@ -140,18 +155,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 +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;
 }
 
 /**
@@ -181,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 })));
 }
 
@@ -213,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, 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 +316,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 +389,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 +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
   }
@@ -441,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;
@@ -456,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({
@@ -468,6 +659,7 @@ export function runUpdaterLoop(): void {
     write: writeSnapshot,
     every: config.updater.snapshotEvery,
   });
+  const shouldGiveUp = createUnreachableCounter();
   const tick = () => {
     try {
       runUpdaterTick({
@@ -479,15 +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
@@ -497,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);
@@ -507,4 +712,5 @@ export function runUpdaterLoop(): void {
   };
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
+  tick();
 }

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

@@ -49,6 +49,40 @@ 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

package/packages/daemon/src/tui/detect/manifest-loader.ts

@@ -30,9 +30,20 @@ import { join } from "node:path";
 import type { AgentManifest, Rule, StateRules } from "./manifest.ts";
 import { BUNDLED_MANIFESTS } from "./manifests.ts";
 
-/** Directory scanned for user override manifests. */
+/** Directory scanned for user override manifests. Honors `TMUX_IDE_HOME` (the
+ *  state-home override every other `~/.tmux-ide` consumer respects) so tests
+ *  never read a real user's overrides. */
 export function overrideDir(): string {
-  return join(homedir(), ".tmux-ide", "agent-detection");
+  const home = process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+  return join(home, "agent-detection");
+}
+
+/** The fetched manifest-pack file (`tmux-ide update --manifests` installs it;
+ *  see `lib/manifest-pack.ts` for the format + publish contract). Lives in a
+ *  SUBDIRECTORY so {@link readOverrideManifests}'s top-level `*.json` scan
+ *  never sees it — that is what keeps user files ABOVE the pack. */
+export function packFile(dir = overrideDir()): string {
+  return join(dir, "pack", "manifest-pack.json");
 }
 
 /**
@@ -167,11 +178,49 @@ function warnOnce(path: string, reason: string): void {
 }
 
 /**
- * Load the full manifest set: bundled + user overrides, merged. Does io on
- * every call — prefer {@link getManifests} for hot paths.
+ * Read the installed manifest PACK (fetched by `tmux-ide update --manifests`),
+ * or `[]` when none is installed. Thin io — a malformed pack file is skipped
+ * with a one-time stderr warning, never a throw (the pack was schema-validated
+ * at install time; this guards a hand-edited/corrupted file). Each entry gets
+ * the same structural validation + normalization as a user override file.
+ */
+export function readPackManifests(dir = overrideDir()): AgentManifest[] {
+  const path = packFile(dir);
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    // No pack installed (the common case).
+    return [];
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    const manifests = (parsed as { manifests?: unknown })?.manifests;
+    if (!Array.isArray(manifests)) {
+      warnOnce(path, "not a manifest pack (missing manifests[])");
+      return [];
+    }
+    const valid: AgentManifest[] = [];
+    for (const entry of manifests) {
+      if (validateManifestShape(entry)) valid.push(normalizeStates(entry));
+      else warnOnce(path, "pack entry is not a valid AgentManifest — entry skipped");
+    }
+    return valid;
+  } catch (err) {
+    warnOnce(path, err instanceof Error ? err.message : String(err));
+    return [];
+  }
+}
+
+/**
+ * Load the full manifest set: bundled + pack + user overrides, merged in that
+ * PRECEDENCE order — a fetched pack refines the bundled set, and a user's own
+ * `agent-detection/*.json` file always beats both (it is merged LAST). Does io
+ * on every call — prefer {@link getManifests} for hot paths.
  */
 export function loadManifests(): AgentManifest[] {
-  return mergeManifests(BUNDLED_MANIFESTS, readOverrideManifests());
+  const withPack = mergeManifests(BUNDLED_MANIFESTS, readPackManifests());
+  return mergeManifests(withPack, readOverrideManifests());
 }
 
 /** Process-lifetime cache for the merged manifest set. */

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

@@ -175,10 +175,31 @@ export function explain(
   return { state: winner ? winner.state : null, checked };
 }
 
+/** Escape a string for literal use inside a RegExp source. */
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Does `haystack` contain `needle` as a WHOLE alphanumeric segment (delimited
+ * by start/end or any non-alphanumeric)? `grok-build` contains the segment
+ * `grok`; `pip` does NOT contain the segment `pi`. This is what keeps short
+ * manifest command tokens (pi, devin, kimi — M25.4) from substring-matching
+ * unrelated commands (`pip`, `vi`, `api-server`).
+ */
+function containsSegment(haystack: string, needle: string): boolean {
+  if (!haystack.includes(needle)) return false;
+  return new RegExp(`(^|[^a-z0-9])${escapeRegex(needle)}([^a-z0-9]|$)`).test(haystack);
+}
+
 /**
  * Pick the manifest whose `commands` best match a pane's current command.
- * Prefers an exact (case-insensitive) match, then a substring match in either
- * direction. Returns undefined when nothing applies.
+ * Prefers an exact (case-insensitive) match, then a SEGMENT match in either
+ * direction — the command contains a manifest token as a whole segment
+ * (`grok-build` → `grok`, `.kilo` → `kilo`) or vice versa (`cursor` →
+ * `cursor-agent`). Raw substring matching was retired in M25.4: it made every
+ * short token a false-positive machine (`pi` ⊂ `pip`, `vi` ⊂ `devin`).
+ * Returns undefined when nothing applies.
  */
 export function pickManifest(
   command: string,
@@ -193,7 +214,7 @@ export function pickManifest(
   return manifests.find((m) =>
     m.commands.some((c) => {
       const name = c.toLowerCase();
-      return cmd.includes(name) || name.includes(cmd);
+      return containsSegment(cmd, name) || containsSegment(name, cmd);
     }),
   );
 }