tmux-ide 2.6.0 → 2.7.0

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

@@ -0,0 +1,217 @@
+/**
+ * Process-tree resolution for the snapshot-scraping fallback.
+ *
+ * A tmux pane's `pane_current_command` is only its IMMEDIATE child process —
+ * for a real agent that is usually `node`/`bun`/`sh`, never `claude`/`codex`.
+ * So the detection manifests picked purely by `pane_current_command` almost
+ * never match in practice. To fix that we walk the pane's process TREE and
+ * resolve what is actually running underneath it.
+ *
+ * Everything here is pure except the thin `readProcessTable` io wrapper, and
+ * nothing ever throws — a missing/garbled `ps` simply yields no matches, and
+ * resolution falls back to the fast `pane_current_command` path.
+ */
+import { execFileSync } from "node:child_process";
+import { pickManifest, type AgentManifest } from "./manifest.ts";
+import { getManifests } from "./manifest-loader.ts";
+
+/** One row of the process table. */
+export interface ProcEntry {
+  pid: number;
+  ppid: number;
+  /** Full command line (argv joined), as `ps` printed it. */
+  command: string;
+}
+
+/**
+ * Parse `ps -axo pid=,ppid=,command=` output. Each line is
+ * `<pid> <ppid> <command line…>` with leading padding on the numeric columns.
+ * Malformed lines are skipped; never throws.
+ */
+export function parsePsOutput(raw: string): ProcEntry[] {
+  const entries: ProcEntry[] = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.replace(/^\s+/, "");
+    if (trimmed.length === 0) continue;
+    // pid, ppid, then the rest is the command line (which may contain spaces).
+    const match = /^(\d+)\s+(\d+)\s+(.*)$/.exec(trimmed);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const ppid = Number(match[2]);
+    const command = match[3] ?? "";
+    if (!Number.isFinite(pid) || !Number.isFinite(ppid) || command.length === 0) continue;
+    entries.push({ pid, ppid, command });
+  }
+  return entries;
+}
+
+/**
+ * Collect the command lines in the subtree rooted at `rootPid`, INCLUDING the
+ * root process itself. Deeper (more specific) processes come FIRST — a DFS that
+ * emits children before their parent — so the most-specific agent command is
+ * seen before the generic `node`/`bun`/`sh` shims above it. Cycles and runaway
+ * depth are guarded.
+ */
+export function subtreeCommands(entries: ProcEntry[], rootPid: number, maxDepth = 6): string[] {
+  const childrenByParent = new Map<number, ProcEntry[]>();
+  const byPid = new Map<number, ProcEntry>();
+  for (const entry of entries) {
+    byPid.set(entry.pid, entry);
+    const siblings = childrenByParent.get(entry.ppid) ?? [];
+    siblings.push(entry);
+    childrenByParent.set(entry.ppid, siblings);
+  }
+
+  const root = byPid.get(rootPid);
+  if (!root) return [];
+
+  const commands: string[] = [];
+  const visited = new Set<number>();
+
+  const walk = (pid: number, depth: number): void => {
+    if (depth > maxDepth || visited.has(pid)) return;
+    visited.add(pid);
+    // Emit children first (deepest → shallowest) so the root lands last.
+    for (const child of childrenByParent.get(pid) ?? []) {
+      walk(child.pid, depth + 1);
+    }
+    const self = byPid.get(pid);
+    if (self) commands.push(self.command);
+  };
+
+  walk(rootPid, 0);
+  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.
+ */
+export function readProcessTable(): ProcEntry[] {
+  try {
+    const raw = execFileSync("ps", ["-axo", "pid=,ppid=,command="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+    });
+    return parsePsOutput(raw);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Extract the candidate tokens a command line should be matched against.
+ *
+ * Full argv strings can incidentally contain an agent name (a path like
+ * `/Users/x/.claude/notes.md`, or `vim ~/.codex/todo`), which would produce a
+ * false positive if we ran `pickManifest` over the raw string. Instead we test
+ * only the meaningful executable-ish tokens: the basename of argv[0] and the
+ * basename of the second token (a script/subcommand path). Query strings and
+ * flags are ignored.
+ *
+ * e.g. `node /Users/x/.nvm/versions/node/v20/bin/claude --foo` → ["node", "claude"]
+ *      `vim /Users/x/.claude/notes.md`                          → ["vim", "notes.md"]
+ */
+export function commandTokens(command: string): string[] {
+  const parts = command.trim().split(/\s+/).filter(Boolean);
+  const tokens: string[] = [];
+  const argv0 = parts[0];
+  if (argv0) tokens.push(basename(argv0));
+  const argv1 = parts[1];
+  // Only treat the second token as a script path when it is not a flag.
+  if (argv1 && !argv1.startsWith("-")) tokens.push(basename(argv1));
+  return tokens;
+}
+
+/** Path basename without the node:path import — splits on `/` and takes the tail. */
+function basename(pathLike: string): string {
+  const segments = pathLike.split("/");
+  return segments[segments.length - 1] ?? pathLike;
+}
+
+/**
+ * Resolve which agent manifest is actually running in a pane.
+ *
+ * 1. Fast path: `pane_current_command` may already BE the agent (e.g. `claude`
+ *    via a shim). Try `pickManifest(paneCmd)` directly.
+ * 2. Tree path: otherwise walk the pane's process subtree and match extracted
+ *    tokens against the manifests. Token extraction avoids the incidental-path
+ *    false positives described above.
+ *
+ * The tree walk prefers the highest-PRIORITY manifest (its index in
+ * `manifests`, which is preference-ordered: claude, codex, …, then the `shell`
+ * catch-all) over merely the deepest match — an agent that has spawned a
+ * transient shell child (a Bash tool call) must still resolve to the agent, not
+ * to `shell`. Depth (deepest first) only breaks ties within the same manifest.
+ *
+ * Resolution order:
+ *   0. HINT — `opts.hint` (the pane's `@agent_hint` option): if it names a
+ *      known manifest it WINS outright. This is the sandbox/wrapper escape
+ *      hatch, set with `tmux set-option -p @agent_hint claude`.
+ *   1. FAST — `pane_current_command` may already be the agent (a shim).
+ *   2. TREE — walk the process subtree and match extracted tokens.
+ *
+ * `manifests` defaults to the loaded set (bundled + user overrides).
+ * `matchedCommand` is the token/command that produced the hit and `source`
+ * records which path won — both surfaced by `agent explain`. Returns an
+ * undefined manifest when nothing matches.
+ */
+export type ResolveSource = "hint" | "fast" | "tree" | "none";
+
+export function resolveAgentCommand(
+  paneCmd: string,
+  panePid: number,
+  table: ProcEntry[],
+  opts: { manifests?: AgentManifest[]; hint?: string } = {},
+): { manifest: AgentManifest | undefined; matchedCommand: string; source: ResolveSource } {
+  const manifests = opts.manifests ?? getManifests();
+
+  // 0. Hint: a per-pane @agent_hint forces a manifest, bypassing resolution.
+  const hint = opts.hint?.trim();
+  if (hint) {
+    const hinted = pickManifest(hint, manifests);
+    if (hinted) return { manifest: hinted, matchedCommand: hint, source: "hint" };
+  }
+
+  const fast = pickManifest(paneCmd, manifests);
+  if (fast) return { manifest: fast, matchedCommand: paneCmd, source: "fast" };
+
+  let best: { manifest: AgentManifest; matchedCommand: string; rank: number } | undefined;
+  for (const command of subtreeCommands(table, panePid)) {
+    for (const token of commandTokens(command)) {
+      const hit = pickManifest(token, manifests);
+      if (!hit) continue;
+      const rank = manifests.indexOf(hit);
+      // Keep the first (deepest) match at a given rank; only replace when a
+      // strictly higher-priority manifest turns up.
+      if (!best || rank < best.rank) best = { manifest: hit, matchedCommand: token, rank };
+      if (best.rank === 0)
+        return { manifest: best.manifest, matchedCommand: best.matchedCommand, source: "tree" };
+    }
+  }
+
+  return best
+    ? { manifest: best.manifest, matchedCommand: best.matchedCommand, source: "tree" }
+    : { manifest: undefined, matchedCommand: "", source: "none" };
+}

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

@@ -0,0 +1,70 @@
+/**
+ * Pane snapshot reader for agent-state detection.
+ *
+ * Reads the bottom-buffer text of a tmux pane and normalizes it into a
+ * `PaneSnapshot` — the raw evidence later detectors classify into
+ * blocked/working/done/idle. The parsing (`parseSnapshot`) is pure and
+ * unit-tested; `readPaneSnapshot` is the thin tmux I/O wrapper.
+ */
+import { captureRecent } from "@tmux-ide/tmux-bridge";
+
+export interface PaneSnapshot {
+  /** Last N non-empty lines, ANSI-stripped, trailing whitespace trimmed. */
+  bottomNonEmpty: string[];
+  /** ANSI-stripped joined snapshot text. */
+  text: string;
+  /** Original raw capture, kept for ansi-format debugging. */
+  raw: string;
+}
+
+// Well-known ANSI escape matcher (ansi-regex): SGR/cursor CSI sequences plus
+// OSC strings terminated by BEL.
+/* eslint-disable no-control-regex */
+const ANSI =
+  /[›][[\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\d/#&.:=?%@~_]+)*|[a-zA-Z\d]+(?:;[-a-zA-Z\d/#&.:=?%@~_]*)*)?)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
+
+/* eslint-enable no-control-regex */
+
+/** Strip ANSI escape sequences from a string. */
+function stripAnsi(input: string): string {
+  return input.replace(ANSI, "");
+}
+
+const DEFAULT_LINES = 20;
+
+/**
+ * Normalize raw pane text into a `PaneSnapshot`. Pure — never throws.
+ *
+ * @param raw Raw pane capture (may contain ANSI escapes).
+ * @param opts.lines Number of trailing non-empty lines to keep (default 20).
+ */
+export function parseSnapshot(raw: string, opts: { lines?: number } = {}): PaneSnapshot {
+  const lines = opts.lines ?? DEFAULT_LINES;
+  const text = stripAnsi(raw ?? "");
+
+  const nonEmpty = text
+    .split("\n")
+    .map((line) => line.replace(/\s+$/, ""))
+    .filter((line) => line.length > 0);
+
+  const bottomNonEmpty = lines > 0 ? nonEmpty.slice(-lines) : [];
+
+  return { bottomNonEmpty, text, raw: raw ?? "" };
+}
+
+/**
+ * Capture a pane's recent buffer and parse it into a `PaneSnapshot`.
+ * On any tmux error, returns an empty snapshot rather than throwing.
+ *
+ * @param target tmux pane target (session, window, or pane id).
+ * @param opts.lines Number of trailing non-empty lines to keep (default 20).
+ */
+export function readPaneSnapshot(target: string, opts: { lines?: number } = {}): PaneSnapshot {
+  const lines = opts.lines ?? DEFAULT_LINES;
+  try {
+    const raw = captureRecent(target, lines);
+    return parseSnapshot(raw, { lines });
+  } catch {
+    return { bottomNonEmpty: [], text: "", raw: "" };
+  }
+}

package/packages/daemon/src/tui/integrations/claude.ts

@@ -0,0 +1,176 @@
+/**
+ * Claude Code integration — the authoritative detection layer.
+ *
+ * Claude Code has a first-class hooks system. `tmux-ide integration install
+ * claude` writes a tiny POSIX hook script and registers it in the user's
+ * `~/.claude/settings.json` for the lifecycle events we care about. Each hook
+ * invocation stamps the CURRENT tmux pane with a pane-local user option:
+ *
+ *   @agent_state       "<working|blocked|done|idle>:<unix epoch>"
+ *   @agent_session_id  the Claude session id (future: --resume on restore)
+ *
+ * The detector treats a fresh `@agent_state` as GROUND TRUTH and only falls
+ * back to screen-manifest scraping when no authority is present — the same
+ * two-layer model the best agent terminals use. Any other agent can join the
+ * authority layer by writing the same option (`tmux set-option -p
+ * @agent_state working:$(date +%s)`) — no integration required.
+ *
+ * The settings merge is surgical and reversible: entries are tagged by the
+ * hook-script path, a one-time backup is written next to settings.json, and
+ * uninstall removes exactly our entries.
+ */
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/** Marker every installed hook command contains — the removal key. */
+export const HOOK_SCRIPT_RELPATH = ".tmux-ide/hooks/claude-state.sh";
+
+export function hookScriptPath(): string {
+  return join(homedir(), HOOK_SCRIPT_RELPATH);
+}
+
+/**
+ * Absolute path to Claude Code's settings file: `TMUX_IDE_CLAUDE_SETTINGS` when
+ * set (tests / per-run overrides), else `~/.claude/settings.json`. The override
+ * lets install/offer flows be exercised against a scratch file so a test never
+ * reads or rewrites the user's real settings.
+ */
+export function claudeSettingsPath(): string {
+  return process.env.TMUX_IDE_CLAUDE_SETTINGS ?? join(homedir(), ".claude", "settings.json");
+}
+
+/**
+ * The hook script. POSIX sh, no dependencies. Claude Code passes the event
+ * payload as JSON on stdin; the state to report comes in as $1 (each settings
+ * entry passes its own state, so the script never parses the event name).
+ * Outside tmux ($TMUX_PANE unset) it exits quietly. The session id is
+ * extracted with sed — good enough for a flat JSON string field.
+ */
+export const HOOK_SCRIPT = `#!/bin/sh
+# tmux-ide agent-state hook (installed by: tmux-ide integration install claude)
+# $1 = state to report: working | blocked | done | idle
+state="\${1:-idle}"
+payload="$(cat 2>/dev/null || true)"
+[ -n "$TMUX_PANE" ] || exit 0
+tmux set-option -p -t "$TMUX_PANE" @agent_state "\${state}:$(date +%s)" 2>/dev/null || exit 0
+sid="$(printf '%s' "$payload" | sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p' | head -1)"
+[ -n "$sid" ] && tmux set-option -p -t "$TMUX_PANE" @agent_session_id "$sid" 2>/dev/null
+exit 0
+`;
+
+/** Claude Code lifecycle events → the state each reports. */
+export const EVENT_STATES: Array<{ event: string; state: string; matcher?: string }> = [
+  { event: "UserPromptSubmit", state: "working" },
+  { event: "PreToolUse", state: "working", matcher: "*" },
+  { event: "Notification", state: "blocked" },
+  { event: "Stop", state: "done" },
+  { event: "SessionEnd", state: "idle" },
+];
+
+interface HookCommand {
+  type: "command";
+  command: string;
+}
+interface HookGroup {
+  matcher?: string;
+  hooks: HookCommand[];
+}
+type HooksConfig = Record<string, HookGroup[]>;
+export type ClaudeSettings = Record<string, unknown> & { hooks?: HooksConfig };
+
+/** Does a hook group belong to us? (its command references our script) */
+function isOurs(group: HookGroup): boolean {
+  return group.hooks?.some((h) => h.command?.includes(HOOK_SCRIPT_RELPATH)) ?? false;
+}
+
+/**
+ * PURE — return a copy of `settings` with our hook entries merged in.
+ * Idempotent: existing tmux-ide entries are replaced, everything else is
+ * preserved untouched.
+ */
+export function mergeHooks(settings: ClaudeSettings, scriptPath: string): ClaudeSettings {
+  const next: ClaudeSettings = { ...settings, hooks: { ...(settings.hooks ?? {}) } };
+  const hooks = next.hooks as HooksConfig;
+  for (const { event, state, matcher } of EVENT_STATES) {
+    const existing = (hooks[event] ?? []).filter((g) => !isOurs(g));
+    const group: HookGroup = {
+      ...(matcher !== undefined ? { matcher } : {}),
+      hooks: [{ type: "command", command: `${scriptPath} ${state}` }],
+    };
+    hooks[event] = [...existing, group];
+  }
+  return next;
+}
+
+/** PURE — return a copy of `settings` with exactly our entries removed. */
+export function removeHooks(settings: ClaudeSettings): ClaudeSettings {
+  if (!settings.hooks) return { ...settings };
+  const hooks: HooksConfig = {};
+  for (const [event, groups] of Object.entries(settings.hooks)) {
+    const kept = groups.filter((g) => !isOurs(g));
+    if (kept.length > 0) hooks[event] = kept;
+  }
+  const next: ClaudeSettings = { ...settings, hooks };
+  if (Object.keys(hooks).length === 0) delete next.hooks;
+  return next;
+}
+
+/** PURE — is our integration present in these settings? */
+export function isInstalled(settings: ClaudeSettings): boolean {
+  return Object.values(settings.hooks ?? {}).some((groups) => groups.some(isOurs));
+}
+
+function readSettings(path: string): ClaudeSettings {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as ClaudeSettings;
+  } catch {
+    throw new Error(`${path} is not valid JSON — fix or move it, then retry`);
+  }
+}
+
+/**
+ * Install: write the hook script, back up settings.json once, merge our
+ * entries. Takes effect for NEW Claude Code sessions (hooks are read at
+ * session start).
+ */
+export function installClaudeIntegration(): { scriptPath: string; settingsPath: string } {
+  const script = hookScriptPath();
+  mkdirSync(dirname(script), { recursive: true });
+  writeFileSync(script, HOOK_SCRIPT, "utf8");
+  chmodSync(script, 0o755);
+
+  const settingsPath = claudeSettingsPath();
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  const settings = readSettings(settingsPath);
+  const backup = `${settingsPath}.tmux-ide.bak`;
+  if (existsSync(settingsPath) && !existsSync(backup)) copyFileSync(settingsPath, backup);
+  writeFileSync(settingsPath, `${JSON.stringify(mergeHooks(settings, script), null, 2)}\n`, "utf8");
+  return { scriptPath: script, settingsPath };
+}
+
+/** Uninstall: remove exactly our entries (script file is left, it's inert). */
+export function uninstallClaudeIntegration(): { settingsPath: string; wasInstalled: boolean } {
+  const settingsPath = claudeSettingsPath();
+  const settings = readSettings(settingsPath);
+  const wasInstalled = isInstalled(settings);
+  if (wasInstalled) {
+    writeFileSync(settingsPath, `${JSON.stringify(removeHooks(settings), null, 2)}\n`, "utf8");
+  }
+  return { settingsPath, wasInstalled };
+}
+
+export function claudeIntegrationStatus(): { installed: boolean; scriptExists: boolean } {
+  return {
+    installed: isInstalled(readSettings(claudeSettingsPath())),
+    scriptExists: existsSync(hookScriptPath()),
+  };
+}

package/packages/daemon/src/tui/integrations/offer.ts

@@ -0,0 +1,145 @@
+/**
+ * The one-time INTEGRATION OFFER — shown the first time tmux-ide adopts a
+ * session on a machine that has Claude Code but hasn't installed the lifecycle
+ * hook.
+ *
+ * The onboarding gap: the Claude Code integration turns pane state from
+ * screen-scraping guesswork into ground truth, but nothing prompts the user to
+ * install it — they'd have to read the docs. This offer notices `claude` on
+ * PATH at adopt time and asks once: install now? [y/N]. `y` installs; anything
+ * else skips. Either way a marker is written so it never asks again.
+ *
+ * "Once" is enforced by a marker file (`<home>/integration-offered`, `<home>` =
+ * `TMUX_IDE_HOME` when set — so tests and the dev box never see it), exactly
+ * like the welcome card ({@link ../chrome/welcome.ts}). The offer is ALSO gated
+ * by config (`integrations.offer`), so it can be suppressed without touching the
+ * marker. {@link shouldOfferIntegration} is the PURE decision; the marker
+ * helpers and {@link maybeOfferIntegrationPopup} wire the io. It NEVER fails an
+ * adopt — every io path is best-effort.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { getAppConfig } from "../../lib/app-config.ts";
+import { claudeIntegrationStatus } from "./claude.ts";
+
+/**
+ * Absolute path to the "already offered" marker: `<home>/integration-offered`,
+ * where `<home>` is `TMUX_IDE_HOME` when set (tests / per-run overrides), else
+ * `~/.tmux-ide`. The env override lets a live test point the marker at a scratch
+ * dir so it never touches — or is confused by — the real user's marker.
+ */
+export function integrationOfferMarkerPath(): string {
+  const home = process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+  return join(home, "integration-offered");
+}
+
+/**
+ * PURE — the first-adopt offer decision. Show the offer only when ALL hold:
+ *   - `claudeOnPath`         Claude Code is installed on this machine,
+ *   - `integrationInstalled` is false (nothing to offer if it's already hooked),
+ *   - `markerPresent`        is false (we've never offered before), and
+ *   - `offerEnabled`         config hasn't disabled the offer.
+ * Kept pure so every gate is trivially unit-tested.
+ */
+export function shouldOfferIntegration(input: {
+  claudeOnPath: boolean;
+  integrationInstalled: boolean;
+  markerPresent: boolean;
+  offerEnabled: boolean;
+}): boolean {
+  return (
+    input.claudeOnPath && !input.integrationInstalled && !input.markerPresent && input.offerEnabled
+  );
+}
+
+/**
+ * Create the marker so the offer shows only once. Best-effort — a marker we
+ * can't write means the offer may show again, but it must never crash adopt.
+ */
+export function markIntegrationOffered(): void {
+  const path = integrationOfferMarkerPath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, new Date().toISOString());
+  } catch {
+    // can't write the marker — degrade to "may offer again", never throw
+  }
+}
+
+/**
+ * PURE — the offer prompt text shown inside the popup. A single question with a
+ * one-line rationale; the `[y/N]` makes the safe default (skip) obvious.
+ */
+export function buildOfferText(): string {
+  const bold = (s: string) => `\x1b[1m${s}\x1b[22m`;
+  const dim = (s: string) => `\x1b[2m${s}\x1b[22m`;
+  const head = (s: string) => `\x1b[1;36m${s}\x1b[0m`;
+  return [
+    head(" Claude Code detected"),
+    "",
+    " Install the tmux-ide integration for ground-truth agent status?",
+    dim(" It hooks Claude Code's lifecycle so pane state is exact, not guessed."),
+    "",
+    ` ${bold("[y]")} install    ${bold("[N]")} skip (any other key)`,
+    dim(" Asked once — press a key."),
+  ].join("\n");
+}
+
+/**
+ * io — float the one-time offer popup on the CURRENT tmux client, best-effort.
+ *
+ * Called at the end of {@link ../chrome/statusline.ts adoptSession} (right after
+ * the welcome card). Gated by {@link shouldOfferIntegration} (PATH + integration
+ * status + marker + config) AND by being inside a tmux client — outside tmux
+ * there's nowhere to float the popup, so we neither show it nor burn the marker
+ * (the next in-tmux adopt still offers).
+ *
+ * The popup runs `tmux-ide integration offer`, which reads one key and installs
+ * on `y` (see bin/cli.ts). It's spawned DETACHED and unref'd so it never blocks
+ * the adopt. The marker is written immediately after the spawn attempt so a
+ * rapid `adopt --all` offers exactly once, not once per session — matching the
+ * welcome card's one-shot discipline.
+ */
+export function maybeOfferIntegrationPopup(): void {
+  let offer: boolean;
+  try {
+    const status = claudeIntegrationStatus();
+    offer = shouldOfferIntegration({
+      claudeOnPath: claudeOnPath(),
+      integrationInstalled: status.installed,
+      markerPresent: existsSync(integrationOfferMarkerPath()),
+      offerEnabled: getAppConfig().integrations.offer,
+    });
+  } catch {
+    return; // any probe failure → never risk the adopt, just don't offer
+  }
+  if (!offer) return;
+  if (!process.env.TMUX) return;
+  try {
+    const child = spawn(
+      "tmux",
+      ["display-popup", "-E", "-w", "64", "-h", "12", "tmux-ide integration offer"],
+      { stdio: "ignore", detached: true },
+    );
+    child.unref();
+  } catch {
+    // tmux missing / no client — best-effort, still mark so we don't retry forever
+  }
+  markIntegrationOffered();
+}
+
+/**
+ * io — is `claude` on PATH? A which-probe capped at 2s, swallowing every failure
+ * to false. Local (not {@link ../../lib/agent-discovery.ts}) to keep the adopt
+ * path's offer check a single cheap probe rather than the full agent sweep.
+ */
+function claudeOnPath(): boolean {
+  try {
+    execFileSync("which", ["claude"], { stdio: "ignore", timeout: 2000 });
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Dispatcher entry for the compiled `tmux-ide-tui` binary.
+ *
+ * `bun build --compile` bundles every TUI surface (the cockpit + widgets) into
+ * ONE standalone executable so the OpenTUI/Solid `.tsx` surfaces run on a clean
+ * `npm i -g tmux-ide` — no dev checkout, no `bun` runtime, no bunfig preload.
+ * The native OpenTUI dylib rides along via Bun's embedded-asset mechanism (the
+ * `import ... with { type: "file" }` in @opentui/core-*), and the Solid JSX
+ * transform happens at build time via the @opentui/solid bun plugin, so the
+ * binary carries only plain JS.
+ *
+ * Contract: `tmux-ide-tui <surface> [--flags…]`. The first positional selects
+ * the surface; the rest are the surface's own args (theme, session, dir, …),
+ * exactly as the `bun <entry> …` invocation passed them. We strip the surface
+ * token from `process.argv` before importing so each entry's top-level
+ * `parseArgs()` sees the same argv it always has.
+ *
+ * The `import()` calls use LITERAL specifiers on purpose: Bun's bundler only
+ * embeds dynamic imports it can resolve statically, and a literal switch keeps
+ * exactly one surface's top-level `render()` side effect from firing.
+ */
+
+const SURFACES = [
+  "team",
+  "app",
+  "explorer",
+  "changes",
+  "preview",
+  "config",
+  "setup",
+  "sidebar",
+] as const;
+
+type Surface = (typeof SURFACES)[number];
+
+function isSurface(value: string | undefined): value is Surface {
+  return value !== undefined && (SURFACES as readonly string[]).includes(value);
+}
+
+async function main(): Promise<void> {
+  const surface = process.argv[2];
+
+  if (!isSurface(surface)) {
+    process.stderr.write(
+      `tmux-ide-tui: unknown surface ${surface ? `"${surface}"` : "(none given)"}.\n` +
+        `Usage: tmux-ide-tui <${SURFACES.join("|")}> [flags]\n`,
+    );
+    process.exit(2);
+  }
+
+  // Drop the surface token so each entry's `parseArgs()` sees only its flags.
+  process.argv.splice(2, 1);
+
+  switch (surface) {
+    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;
+    case "changes":
+      await import("../widgets/changes/index.tsx");
+      break;
+    case "preview":
+      await import("../widgets/preview/index.tsx");
+      break;
+    case "config":
+      await import("../widgets/config/index.tsx");
+      break;
+    case "setup":
+      await import("../widgets/setup/index.tsx");
+      break;
+    case "sidebar":
+      await import("../widgets/sidebar/index.tsx");
+      break;
+  }
+}
+
+void main();