tmux-ide 2.6.1 → 2.7.0

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

@@ -34,6 +34,8 @@ import { paneChip } from "./chip.ts";
 import { appendEvents, diffFleet, type AgentEventInit } from "./events.ts";
 import {
   decideNotifications,
+  enabledStates,
+  inQuietHours,
   listAttachedClients,
   readNotificationPrefs,
   sendSystemNotification,
@@ -41,6 +43,7 @@ import {
   type AttachedClient,
   type NotificationPrefs,
   type NotifyEvent,
+  type SystemNotification,
   type ToastTarget,
 } from "./notify.ts";
 import {
@@ -148,7 +151,13 @@ export interface UpdaterTickDeps {
   now?: () => number;
   prefs?: NotificationPrefs;
   sendToasts?: (toasts: ToastTarget[]) => void;
-  sendSystem?: (message: string) => void;
+  sendSystem?: (n: SystemNotification) => 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
@@ -211,7 +220,7 @@ export function runUpdaterTick(deps: UpdaterTickDeps): void {
     for (const [name, status] of state) deps.prevState.set(name, status);
     if (events.length > 0) {
       deps.appendEvents(events);
-      dispatchNotifications(deps, events);
+      dispatchNotifications(deps, enrichEvents(events, panes, deps.locatePane));
     }
   }
 }
@@ -241,21 +250,93 @@ 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.
+ */
+export function enrichEvents(
+  events: AgentEventInit[],
+  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,
+    };
+  });
+}
+
 /**
  * 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 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.
  */
 function dispatchNotifications(deps: UpdaterTickDeps, events: NotifyEvent[]): void {
   const { listClients, lastNotified, now, prefs, sendToasts: toast, sendSystem } = deps;
   if (!listClients || !lastNotified || !now || !prefs) return;
+  if (!prefs.enabled) return;
   if (!prefs.toast && !prefs.macos) return;
-  const decision = decideNotifications(events, listClients(), lastNotified, now());
+  const nowMs = now();
+  const decision = decideNotifications(
+    events,
+    listClients(),
+    lastNotified,
+    nowMs,
+    enabledStates(prefs),
+  );
   lastNotified.clear();
   for (const [key, ts] of decision.nextLastNotified) lastNotified.set(key, ts);
   if (prefs.toast && toast) toast(decision.toasts);
-  if (prefs.macos && sendSystem) {
-    for (const { message } of decision.system) sendSystem(message);
+  if (prefs.macos && sendSystem && !inQuietHours(new Date(nowMs), prefs.quietHours)) {
+    for (const n of decision.system) sendSystem(n);
+  }
+}
+
+/**
+ * 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;
   }
 }
 
@@ -404,6 +485,7 @@ export function runUpdaterLoop(): void {
         prefs: readNotificationPrefs(),
         sendToasts,
         sendSystem: sendSystemNotification,
+        locatePane: paneLocation,
         maybeCheckForUpdate: () => maybeCheckForUpdate({ enabled: config.updates.check }),
         markUpdateNotified,
       });

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,21 @@ export function parseAuthority(raw: string | undefined, nowSec: number): AgentSt
   return state as AgentStatus;
 }
 
+/**
+ * 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.
  *

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

@@ -156,7 +156,8 @@ function normalizeStates(m: AgentManifest): AgentManifest {
   if (m.states.blocked) states.blocked = m.states.blocked;
   if (m.states.working) states.working = m.states.working;
   if (m.states.done) states.done = m.states.done;
-  return { id: m.id, commands: m.commands, states };
+  const confidence = m.confidence === "tuned" ? "tuned" : "conservative";
+  return { id: m.id, commands: m.commands, states, confidence };
 }
 
 function warnOnce(path: string, reason: string): void {

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

@@ -40,6 +40,15 @@ export interface StateRules {
   done?: Rule;
 }
 
+/**
+ * How much trust the manifest's rules earn.
+ * - `tuned`: built from REAL captured screens (or the agent's own source
+ *   strings) — the markers are verbatim, not guessed.
+ * - `conservative`: best-effort from public knowledge; high-precision only, so
+ *   it can never false-positive on a plain prompt, but it may miss real states.
+ */
+export type ManifestConfidence = "tuned" | "conservative";
+
 /** A detection manifest for one or more pane commands. */
 export interface AgentManifest {
   /** Stable manifest id. */
@@ -48,6 +57,12 @@ export interface AgentManifest {
   commands: string[];
   /** Evidence rules per detectable state. */
   states: StateRules;
+  /**
+   * Evidence confidence (default `conservative` when omitted). Surfaced by
+   * `agent explain` so a user can see whether a verdict rests on real evidence
+   * or a best-effort heuristic. Purely informational — never affects matching.
+   */
+  confidence?: ManifestConfidence;
 }
 
 /** The states a manifest can positively detect (idle is inferred elsewhere). */

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

@@ -8,14 +8,22 @@
  * stay minimal. Treat every matcher below as a heuristic to tune, not a
  * contract — edit freely as agent UIs change.
  *
- * EVIDENCE PROVENANCE. The `claude` and `codex` manifests are tuned against
- * REAL captured screens (see `manifest-corpus.test.ts` for the sanitized
- * fixtures). Each matcher cites the invariant it was built from ("seen: …").
- * The remaining manifests (`opencode`, `gemini`, `aider`, `copilot`) are
- * best-effort from public docs/common knowledge — every one of their matchers
- * is marked "untuned — needs real captures" and kept HIGH-PRECISION
- * (esc-to-interrupt / spinner / explicit y-n) so they can never false-positive
- * on a plain prompt. Users can override any of these with a JSON file in
+ * EVIDENCE PROVENANCE (per-manifest `confidence`):
+ *   - `tuned` — built from REAL captured screens or the agent's own source
+ *     strings. `claude`, `codex`, and `aider` are tuned: codex from live
+ *     `tmux capture-pane` frames driven through a real turn (idle / working /
+ *     command-approval / trust prompt), aider from the verbatim prompt strings
+ *     in its installed source (`io.py` confirm_ask, `waiting.py` spinner).
+ *     Each matcher cites the invariant it was built from ("seen: …").
+ *   - `conservative` — best-effort from public docs/common knowledge
+ *     (`opencode`, `gemini`, `copilot`, `cursor`, `goose`, `amp`). Every
+ *     matcher is HIGH-PRECISION (esc-to-interrupt / spinner / explicit y-n /
+ *     "Do you want") so it can never false-positive on a plain prompt, but it
+ *     may miss real states until a live capture upgrades it. `opencode` was
+ *     attempted live but its local auth DB errored and the TUI rendered blank,
+ *     so it stays conservative.
+ *
+ * Users can override any of these with a JSON file in
  * `~/.tmux-ide/agent-detection/` (see `manifest-loader.ts`).
  */
 import type { AgentManifest } from "./manifest.ts";
@@ -27,6 +35,7 @@ const BRAILLE_SPINNER = "[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]";
 const CLAUDE: AgentManifest = {
   id: "claude",
   commands: ["claude"],
+  confidence: "tuned",
   states: {
     // Approval / confirmation prompts — Claude is waiting on the user.
     // Claude's approval UI is a bordered box asking a "Do you want …?" question
@@ -74,41 +83,57 @@ const CLAUDE: AgentManifest = {
 
 const CODEX: AgentManifest = {
   id: "codex",
-  commands: ["codex"],
+  commands: ["codex", "codex.exe"],
+  confidence: "tuned",
   states: {
+    // TUNED against real captures (codex-cli v0.142.5, driven through a turn).
+    // The command-approval dialog and the directory-trust prompt are the two
+    // "blocked" screens. Codex's approval menu uses a "› 1." numbered arrow —
+    // note the arrow is "›" (U+203A), NOT claude's "❯".
     blocked: {
       any: [
-        // untuned — needs real captures. Codex approval prompts (docs/common
-        // knowledge): a command-approval question before running a shell
-        // command. Kept high-precision so it can't fire on the idle "›" box.
-        { region: "bottom", contains: "Allow command", caseInsensitive: true },
-        { region: "bottom", contains: "Do you want" },
-        { region: "bottom", contains: "approve", caseInsensitive: true },
-        { region: "bottom", contains: "(y/n)", caseInsensitive: true },
+        // seen (command approval): "Would you like to run the following
+        // command?" above a "$ <cmd>" preview and the numbered menu.
+        { region: "bottom", contains: "Would you like to run", caseInsensitive: true },
+        // seen: the highlighted approval option "› 1. Yes, proceed".
+        { region: "bottom", contains: "Yes, proceed" },
+        // seen: "3. No, and tell Codex what to do differently (esc)".
+        { region: "bottom", contains: "No, and tell Codex" },
+        // seen: the confirm footer under the approval menu.
+        { region: "bottom", contains: "Press enter to confirm", caseInsensitive: true },
+        // seen (directory-trust prompt on first launch in an untrusted dir):
+        // "Do you trust the contents of this directory?" + "1. Yes, continue".
+        { region: "bottom", contains: "Do you trust the contents", caseInsensitive: true },
       ],
     },
     working: {
       any: [
-        // untuned for the exact string — Codex shows an elapsed-time working
-        // line with an interrupt hint while a turn runs. "esc to interrupt" is
-        // the shared CLI-TUI invariant; the spinner is the fallback.
+        // seen (verbatim): the working status line is
+        //   "• Working (6s • esc to interrupt)".
+        // Both the "Working (" prefix and the shared "esc to interrupt" hint
+        // are present for the whole turn.
+        { region: "bottom", regex: "Working \\(\\d" },
         { region: "bottom", contains: "esc to interrupt", caseInsensitive: true },
         { region: "bottom", regex: BRAILLE_SPINNER },
         { region: "title", regex: BRAILLE_SPINNER },
       ],
     },
-    // done: omitted. NOTE (seen, NOT used): idle Codex shows a "›" input prompt
-    // and a "gpt-5.5 high · <cwd>            Goal achieved (5m)" status line —
-    // "Goal achieved" is a finished/idle marker, not "working", so it is left
-    // out (a done rule would collapse to idle in the instant classifier anyway).
+    // done: omitted. NOTE (seen, NOT used): a finished turn leaves the agent's
+    // answer above the idle "›" input box (placeholder "Find and fix a bug in
+    // @filename") and a "gpt-5.5 xhigh · <cwd>" status line; older builds also
+    // showed "Goal achieved (5m)". None are working/blocked evidence, so codex
+    // correctly falls through to idle and the classifier infers done.
   },
 };
 
 const OPENCODE: AgentManifest = {
   id: "opencode",
-  commands: ["opencode"],
+  commands: ["opencode", "opencode.exe"],
+  confidence: "conservative",
   states: {
-    // untuned — needs real captures. High-precision only.
+    // conservative — a live capture was attempted (opencode v1.17.10) but its
+    // local auth DB errored ("no such column: name") and the TUI rendered
+    // blank, so these stay best-effort. High-precision only.
     blocked: {
       any: [
         { region: "bottom", contains: "(y/n)", caseInsensitive: true },
@@ -129,8 +154,10 @@ const OPENCODE: AgentManifest = {
 const GEMINI: AgentManifest = {
   id: "gemini",
   commands: ["gemini"],
+  confidence: "conservative",
   states: {
-    // untuned — needs real captures. gemini-cli. High-precision only.
+    // conservative — gemini-cli needs a Google account/API key to reach a
+    // working state, so no live capture was taken. High-precision only.
     blocked: {
       any: [
         { region: "bottom", contains: "(y/n)", caseInsensitive: true },
@@ -153,20 +180,33 @@ const GEMINI: AgentManifest = {
 const AIDER: AgentManifest = {
   id: "aider",
   commands: ["aider"],
+  confidence: "tuned",
   states: {
-    // untuned — needs real captures. aider uses "(Y)es/(N)o" confirmation
-    // prompts, which are its most reliable blocked signal.
+    // TUNED from aider's installed source (v0.86.2). Every confirmation renders
+    // through `io.confirm_ask` (io.py), which appends the literal option string
+    // " (Y)es/(N)o" (plus "/(A)ll/(S)kip all" or "/(D)on't ask again") and a
+    // "[Yes]:"/"[No]:" default — so "(Y)es/(N)o" is aider's exact, universal
+    // blocked marker. The specific questions below are verbatim from
+    // base_coder.py / commands.py.
     blocked: {
       any: [
         { region: "bottom", contains: "(Y)es/(N)o", caseInsensitive: true },
-        { region: "bottom", contains: "? [Yes]", caseInsensitive: true },
         { region: "bottom", contains: "Add file to the chat", caseInsensitive: true },
+        { region: "bottom", contains: "Allow edits to file", caseInsensitive: true },
+        { region: "bottom", contains: "Add command output to the chat", caseInsensitive: true },
+        { region: "bottom", contains: "Run pip install", caseInsensitive: true },
       ],
     },
-    // working: aider streams tokens without a stable status line, so we leave
-    // it to idle-by-default rather than risk a false positive.
+    // TUNED: while a turn runs aider shows a `WaitingSpinner` (waiting.py)
+    // rendered as "[░█   ] Waiting for <model>" — the text is literally
+    // "Waiting for LLM" or "Waiting for " + the model name (base_coder.py:1440).
+    // aider's spinner uses a "░█" scanner, NOT braille, so "Waiting for " is the
+    // real invariant; the braille probe is kept only as a harmless fallback.
     working: {
-      any: [{ region: "bottom", regex: BRAILLE_SPINNER }],
+      any: [
+        { region: "bottom", contains: "Waiting for ", caseInsensitive: false },
+        { region: "bottom", regex: BRAILLE_SPINNER },
+      ],
     },
   },
 };
@@ -174,8 +214,10 @@ const AIDER: AgentManifest = {
 const COPILOT: AgentManifest = {
   id: "copilot",
   commands: ["copilot", "github-copilot", "github-copilot-cli"],
+  confidence: "conservative",
   states: {
-    // untuned — needs real captures. github-copilot-cli. High-precision only.
+    // conservative — github-copilot-cli needs a GitHub account, so no live
+    // capture was taken. High-precision only.
     blocked: {
       any: [
         { region: "bottom", contains: "(y/n)", caseInsensitive: true },
@@ -193,9 +235,92 @@ const COPILOT: AgentManifest = {
   },
 };
 
+const CURSOR: AgentManifest = {
+  id: "cursor",
+  commands: ["cursor-agent", "cursor"],
+  confidence: "conservative",
+  states: {
+    // conservative — cursor-agent (Cursor CLI) was launched live but sits on a
+    // "Press any key to log in…" pre-auth screen without an account, so no
+    // working/blocked turn could be captured. The pre-auth splash ("Cursor
+    // Agent" / "Press any key to log in") is idle chrome and deliberately NOT
+    // matched here. Markers below are high-precision guesses from public
+    // knowledge of its approval/streaming UI. NOTE: cursor-agent runs under
+    // `node`, so it resolves via the process-tree (argv0 basename), not the
+    // pane's `current_command`.
+    blocked: {
+      any: [
+        { region: "bottom", contains: "Do you want", caseInsensitive: false },
+        { region: "bottom", contains: "Run this command", caseInsensitive: true },
+        { region: "bottom", contains: "Apply this edit", caseInsensitive: true },
+        { region: "bottom", contains: "(y/n)", caseInsensitive: true },
+      ],
+    },
+    working: {
+      any: [
+        { region: "bottom", contains: "esc to interrupt", caseInsensitive: true },
+        { region: "bottom", regex: BRAILLE_SPINNER },
+        { region: "title", regex: BRAILLE_SPINNER },
+      ],
+    },
+  },
+};
+
+const GOOSE: AgentManifest = {
+  id: "goose",
+  commands: ["goose"],
+  confidence: "conservative",
+  states: {
+    // conservative — Block's goose CLI needs a configured provider, so no live
+    // capture was taken. High-precision only; markers are best-effort from
+    // public knowledge of its confirmation/streaming UI.
+    blocked: {
+      any: [
+        { region: "bottom", contains: "Do you want", caseInsensitive: false },
+        { region: "bottom", contains: "Allow this tool", caseInsensitive: true },
+        { region: "bottom", contains: "(y/n)", caseInsensitive: true },
+        { region: "bottom", contains: "[y/n]", caseInsensitive: true },
+      ],
+    },
+    working: {
+      any: [
+        { region: "bottom", contains: "esc to interrupt", caseInsensitive: true },
+        { region: "bottom", regex: BRAILLE_SPINNER },
+        { region: "title", regex: BRAILLE_SPINNER },
+      ],
+    },
+  },
+};
+
+const AMP: AgentManifest = {
+  id: "amp",
+  commands: ["amp"],
+  confidence: "conservative",
+  states: {
+    // conservative — Sourcegraph's amp CLI needs an account, so no live capture
+    // was taken. High-precision only; markers are best-effort from public
+    // knowledge of its approval/streaming UI.
+    blocked: {
+      any: [
+        { region: "bottom", contains: "Do you want", caseInsensitive: false },
+        { region: "bottom", contains: "Allow", caseInsensitive: false },
+        { region: "bottom", contains: "(y/n)", caseInsensitive: true },
+      ],
+    },
+    working: {
+      any: [
+        { region: "bottom", contains: "esc to interrupt", caseInsensitive: true },
+        { region: "bottom", regex: BRAILLE_SPINNER },
+        { region: "title", regex: BRAILLE_SPINNER },
+      ],
+    },
+  },
+};
+
 const SHELL: AgentManifest = {
   id: "shell",
   commands: ["bash", "zsh", "sh", "fish", "nu"],
+  confidence: "conservative",
   states: {
     // Catch-all: a raw shell is almost always idle. We only flag an explicit
     // interactive confirmation as blocked; "working" is unreliable to read
@@ -222,5 +347,8 @@ export const BUNDLED_MANIFESTS: AgentManifest[] = [
   GEMINI,
   AIDER,
   COPILOT,
+  CURSOR,
+  GOOSE,
+  AMP,
   SHELL,
 ];

package/packages/daemon/src/tui/detect/process-tree.ts

@@ -83,6 +83,26 @@ export function subtreeCommands(entries: ProcEntry[], rootPid: number, maxDepth
   return commands;
 }
 
+/**
+ * Summarize the executable-ish tokens seen in a pane's process subtree, in the
+ * order the tree-walk visits them (deepest first), de-duplicated. Pure.
+ *
+ * This is a DIAGNOSTIC for `agent explain`: when no manifest resolves, showing
+ * "process-tree saw: node, sleep" tells the user WHY nothing matched and what
+ * to point an `@agent_hint` at. Tokens are the same basenames
+ * `resolveAgentCommand` matches against, so the report reflects reality.
+ */
+export function describeSubtree(entries: ProcEntry[], rootPid: number, limit = 8): string[] {
+  const seen: string[] = [];
+  for (const command of subtreeCommands(entries, rootPid)) {
+    for (const token of commandTokens(command)) {
+      if (!seen.includes(token)) seen.push(token);
+      if (seen.length >= limit) return seen;
+    }
+  }
+  return seen;
+}
+
 /**
  * Read the live process table. Thin io wrapper — on any failure returns `[]`
  * so callers degrade to the fast path rather than throwing.

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

@@ -20,7 +20,16 @@
  * exactly one surface's top-level `render()` side effect from firing.
  */
 
-const SURFACES = ["team", "explorer", "changes", "preview", "config", "setup", "sidebar"] as const;
+const SURFACES = [
+  "team",
+  "app",
+  "explorer",
+  "changes",
+  "preview",
+  "config",
+  "setup",
+  "sidebar",
+] as const;
 
 type Surface = (typeof SURFACES)[number];
 
@@ -46,6 +55,9 @@ async function main(): Promise<void> {
     case "team":
       await import("./team/index.tsx");
       break;
+    case "app":
+      await import("./mirror/app.tsx");
+      break;
     case "explorer":
       await import("../widgets/explorer/index.tsx");
       break;

package/packages/daemon/src/tui/mirror/ack-writer.ts

@@ -0,0 +1,77 @@
+/**
+ * AckWriter — ack-paced, coalescing writes into an async sink (M21.5).
+ *
+ * xterm-headless's `write()` is asynchronous: bytes queue in its WriteBuffer
+ * and parse on its own schedule, with a completion callback per write. Feeding
+ * every control-mode `%output` chunk straight in piles up unbounded entries in
+ * that internal queue during a flood. This writer paces instead: chunks
+ * arriving while a write is in flight buffer HERE, and the completion callback
+ * triggers exactly one follow-up write of everything buffered, joined. At most
+ * ONE sink write is ever outstanding, order and content are preserved
+ * byte-for-byte, and the caller (the control-channel reader loop) never waits.
+ *
+ * Pure core: the sink is injected (`term.write(data, done)` in production, a
+ * recording stub in tests); no timers, no io.
+ */
+export class AckWriter {
+  private queue: Uint8Array[] = [];
+  private inFlight = false;
+
+  /** `onAck` fires after EACH sink write completes — i.e. when those bytes are
+   *  actually visible in the sink (parsed, for xterm). Consumers that gate
+   *  rendering on "content changed" must re-arm on this, not on enqueue: with
+   *  pacing, an enqueue-time signal can be consumed before the parse lands and
+   *  the final frame would never render. */
+  constructor(
+    private readonly sink: (data: Uint8Array, done: () => void) => void,
+    private readonly onAck?: () => void,
+  ) {}
+
+  /** Enqueue bytes; writes through immediately when the sink is idle. */
+  write(data: Uint8Array): void {
+    if (data.length === 0) return;
+    this.queue.push(data);
+    this.pump();
+  }
+
+  /** Bytes buffered here awaiting the in-flight write's ack (tests only). */
+  pendingBytes(): number {
+    let n = 0;
+    for (const c of this.queue) n += c.length;
+    return n;
+  }
+
+  /** A sink write is currently outstanding (tests only). */
+  busy(): boolean {
+    return this.inFlight;
+  }
+
+  private pump(): void {
+    if (this.inFlight || this.queue.length === 0) return;
+    const chunks = this.queue;
+    this.queue = [];
+    const data = chunks.length === 1 ? chunks[0]! : concatBytes(chunks);
+    this.inFlight = true;
+    let acked = false;
+    this.sink(data, () => {
+      if (acked) return; // a double-fired callback must not unleash overlap
+      acked = true;
+      this.inFlight = false;
+      this.onAck?.();
+      this.pump();
+    });
+  }
+}
+
+/** Join byte chunks into one contiguous array (exported for tests). */
+export function concatBytes(chunks: readonly Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const c of chunks) total += c.length;
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const c of chunks) {
+    out.set(c, off);
+    off += c.length;
+  }
+  return out;
+}