tmux-ide 2.6.1 → 2.8.0

package/bin/cli.ts

@@ -9,8 +9,17 @@ import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+// The node-runnable CLI path that spawned TUI surfaces shell back to (the app's
+// async fleet poll + `detect --write`). When we're the published `bin/cli.js`
+// this file IS it; under dev (`bun bin/cli.ts`) it's the built sibling
+// `bin/cli.js`. Forwarded to surfaces as TMUX_IDE_CLI so the COMPILED TUI binary
+// — whose own `import.meta.url` is a virtual bunfs path with no real cli.js next
+// to it — can still find the CLI to run its subprocesses.
+const selfPath = fileURLToPath(import.meta.url);
+const nodeCliPath = selfPath.endsWith(".js") ? selfPath : resolve(__dirname, "cli.js");
 import { launch } from "../packages/daemon/src/launch.ts";
-import { shouldOpenCockpit } from "../packages/daemon/src/tui/team/entry.ts";
+import { resolveEntry } from "../packages/daemon/src/tui/team/entry.ts";
+import { loadAppConfig } from "../packages/daemon/src/lib/app-config.ts";
 import {
   resolveTuiLaunch,
   findCompiledTui,
@@ -31,6 +40,16 @@ import { restore } from "../packages/daemon/src/restore.ts";
 import { send } from "../packages/daemon/src/send.ts";
 import { IdeError } from "../packages/daemon/src/lib/errors.ts";
 import { printCommandError } from "../packages/daemon/src/lib/output.ts";
+import {
+  wantsHostedApp,
+  hostedEnvVars,
+  hostedCommandLine,
+  hostExistsArgv,
+  hostCreateArgv,
+  hostSetupArgvs,
+  hostAttachArgv,
+  HOSTED_ENV,
+} from "../packages/daemon/src/tui/mirror/hosted.ts";
 
 const { positionals, values } = parseArgs({
   allowPositionals: true,
@@ -83,6 +102,10 @@ const { positionals, values } = parseArgs({
     // actions menu opens at the pointer instead of centered (see `menu` case)
     x: { type: "string" },
     y: { type: "string" },
+    // app: host the cockpit in the internal `_tmux-ide-app` session and attach
+    // to it (M23.2) — `--detachable` is the primary name, `--hosted` the alias
+    detachable: { type: "boolean" },
+    hosted: { type: "boolean" },
     // worktree: base ref for a new branch, the worktree checkout dir override,
     // skip creating a session, and force-remove a dirty worktree (see `worktree`)
     from: { type: "string" },
@@ -110,6 +133,7 @@ const knownCommands = new Set([
   "send",
   "settings",
   "team",
+  "app",
   "switcher",
   "wait",
   "events",
@@ -127,6 +151,7 @@ const knownCommands = new Set([
   "worktree",
   "update",
   "skill-sync",
+  "serve",
   "command-center",
   "server",
   "help",
@@ -177,12 +202,15 @@ ${bold("Usage:")}
                               ${dim("(--resume-agents revives claude conversations via claude --resume)")}
   ${cyan("tmux-ide attach")}             ${dim("Reattach to a running session")}
   ${cyan("tmux-ide team")} [--json]      ${dim("TUI over all tmux sessions (--json prints fleet state)")}
+  ${cyan("tmux-ide app")} [session]      ${dim("Unified app: fleet home + live session mirror (bare = home)")}
+  ${cyan("tmux-ide app --detachable")}   ${dim("Host the app in tmux and attach — survives the terminal, ^q detaches")}
   ${cyan("tmux-ide switcher")}           ${dim("Compact session picker (opens in the M-p popup on adopted sessions)")}
   ${cyan("tmux-ide wait agent-status")} <session> --status <s> [--timeout <ms>]
                               ${dim("Block until a session reaches a status (exit 0 match / 1 timeout)")}
   ${cyan("tmux-ide wait output")} <pane|session> --match <regex> [--timeout <ms>]
                               ${dim("Block until a pane's output matches a regex (exit 0 match / 1 timeout)")}
-  ${cyan("tmux-ide events")} [--follow] [--json]  ${dim("Stream agent-status transitions (needs an adopted session)")}
+  ${cyan("tmux-ide events")} [--follow] [--json] [--socket]  ${dim("Stream agent-status transitions (--socket: push from a running serve)")}
+  ${cyan("tmux-ide serve")} [--socket <path>]  ${dim("Local control socket: NDJSON verbs + pushed events (~/.tmux-ide/control.sock)")}
   ${cyan("tmux-ide adopt")} <session>    ${dim("Add the live tmux-ide status bar to a session")}
   ${cyan("tmux-ide adopt --all")}        ${dim("Adopt every live (non-internal) session")}
   ${cyan("tmux-ide unadopt")} <session>  ${dim("Remove the status bar")}
@@ -202,6 +230,7 @@ ${bold("Usage:")}
   ${cyan("tmux-ide inspect")} [--json]   ${dim("Show effective config and runtime state")}
   ${cyan("tmux-ide doctor")}             ${dim("Check system requirements")}
   ${cyan("tmux-ide update")} [--dry-run] ${dim("Update tmux-ide (detects dev checkout vs npm/pnpm/bun global)")}
+  ${cyan("tmux-ide update --manifests")} ${dim("Fetch the latest agent-detection manifest pack (your overrides still win)")}
   ${cyan("tmux-ide skill-sync")}         ${dim("Refresh the bundled Claude Code skill in ~/.claude/skills/tmux-ide")}
   ${cyan("tmux-ide validate")} [--json]  ${dim("Validate ide.yml")}
   ${cyan("tmux-ide detect")} [--json]    ${dim("Detect project stack")}
@@ -269,7 +298,12 @@ function execBunWidget(
     );
   }
 
-  const env = { ...process.env, TMUX_IDE_CWD: process.cwd(), ...extraEnv };
+  const env = {
+    ...process.env,
+    TMUX_IDE_CWD: process.cwd(),
+    TMUX_IDE_CLI: nodeCliPath,
+    ...extraEnv,
+  };
   if (launch.mode === "bun") {
     // Spawn from the repo root so bun finds `bunfig.toml` (the @opentui/solid
     // JSX preload). Without this, running from any other cwd — e.g. bare
@@ -290,6 +324,63 @@ function execBunWidget(
   execFileSync(launch.bin, launch.argv, { stdio: "inherit", env });
 }
 
+// The detachable cockpit (M23.2): instead of running the app in THIS terminal,
+// ensure the internal `_tmux-ide-app` session exists running it full-screen
+// (status off, window-size latest — see hostSetupArgvs), then attach here.
+// Re-invocation from any terminal reattaches the SAME cockpit; ^q inside a
+// hosted app detaches (the HOSTED_ENV marker on the pane command flips it).
+// Inside tmux the client switch-clients instead of nesting an attach.
+function launchHostedApp(scriptPath: string, appArgs: string[]): void {
+  const launch = resolveTuiLaunch({
+    surface: "app",
+    scriptPath,
+    args: appArgs,
+    checkoutExists: existsSync(scriptPath),
+    bunAvailable: isBunAvailable(),
+    compiledBinary: findCompiledTui(),
+  });
+  if (launch.mode === "unavailable") {
+    throw new IdeError(
+      `\`tmux-ide app --detachable\` is unavailable because ${launch.reasons.join(" and ")}.\n` +
+        `Install bun (https://bun.sh) — the TUI surfaces run on it. Sources ship with the npm package since v2.6.1.`,
+      { code: "USAGE", exitCode: 1 },
+    );
+  }
+
+  let exists = true;
+  try {
+    execFileSync("tmux", hostExistsArgv(), { stdio: "ignore" });
+  } catch {
+    exists = false; // also covers "no server yet" — new-session starts one
+  }
+  if (!exists) {
+    // Same cwd rule as execBunWidget: bun needs the repo root (bunfig preload),
+    // the compiled binary must NOT run from it. The app's real env travels on
+    // the pane command line — the tmux server's environment is not ours.
+    const cwd = launch.mode === "bun" ? resolve(__dirname, "..") : process.cwd();
+    const commandLine = hostedCommandLine(
+      launch.bin,
+      launch.argv,
+      hostedEnvVars({
+        cwd: process.cwd(),
+        cli: nodeCliPath,
+        path: process.env.PATH,
+        home: process.env.TMUX_IDE_HOME,
+        config: process.env.TMUX_IDE_CONFIG,
+        tuiBin: process.env.TMUX_IDE_TUI_BIN,
+      }),
+    );
+    execFileSync("tmux", hostCreateArgv({ cwd, commandLine }), { stdio: "ignore" });
+  }
+  // Setup runs on EVERY ensure, not just create (M25.5): the list is
+  // idempotent, so this upgrades a host created by an older tmux-ide (no
+  // resize hooks yet) and re-asserts `window-size latest` on a host a stray
+  // `resize-window` flipped to manual — the measured way a cockpit gets stuck
+  // at a departed client's size.
+  for (const args of hostSetupArgvs()) execFileSync("tmux", args, { stdio: "ignore" });
+  execFileSync("tmux", hostAttachArgv(Boolean(process.env.TMUX)), { stdio: "inherit" });
+}
+
 // The scriptable control surface for the cockpit: print the fleet state as JSON
 // and exit without spawning the (bun/OpenTUI) TUI. Shared by `tmux-ide team
 // --json` and bare `tmux-ide --json` when there's no ide.yml to launch. Dynamic
@@ -301,7 +392,43 @@ async function printFleetJson(): Promise<void> {
   console.log(JSON.stringify(toFleetJson(listTeamProjects(createStatusTracker())), null, 2));
 }
 
+// The `--socket[=path]` opt-in (undeclared in parseArgs on purpose: bare
+// `--socket` parses to `true`, `--socket=/path` to the path — strict:false
+// gives optional-value semantics parseArgs can't declare). `true | string |
+// undefined`; string overrides the default socket path.
+const socketFlag = values.socket as string | boolean | undefined;
+
+// Run a `wait` on a live `tmux-ide serve` (connect once, the server holds the
+// wait — no local polling). Returns null when the flag is off, no server
+// answers, or the connection drops mid-wait — callers fall back SILENTLY to
+// the local polling implementation (same shared logic, tui/team/wait.ts).
+async function waitOverSocket(
+  params: Record<string, unknown>,
+): Promise<{ timedOut: boolean; data?: unknown } | null> {
+  if (!socketFlag) return null;
+  const { connectControl, ControlRequestError } =
+    await import("../packages/daemon/src/control/client.ts");
+  let client: Awaited<ReturnType<typeof connectControl>>;
+  try {
+    client = await connectControl({
+      socketPath: typeof socketFlag === "string" ? socketFlag : undefined,
+    });
+  } catch {
+    return null; // no server listening — poll locally instead
+  }
+  try {
+    const data = await client.request("wait", params);
+    return { timedOut: false, data };
+  } catch (err) {
+    if (err instanceof ControlRequestError && err.code === "timeout") return { timedOut: true };
+    return null; // dropped/errored mid-wait — fall back to polling
+  } finally {
+    client.close();
+  }
+}
+
 const teamScriptPath = resolve(__dirname, "../packages/daemon/src/tui/team/index.tsx");
+const appScriptPath = resolve(__dirname, "../packages/daemon/src/tui/mirror/app.tsx");
 
 // `tmux-ide team` runs the standalone full-screen cockpit (the OpenTUI app owns
 // the whole terminal). The floating switcher popup (M-p on adopted sessions)
@@ -310,6 +437,29 @@ function launchTeamCockpit(): void {
   execBunWidget("team", teamScriptPath, [], "team");
 }
 
+// The one entry for the unified app: `--detachable`/`--hosted` (or
+// `app.detachable` in config) route through the hosted launcher, everything
+// else runs the app in this terminal as before. The HOSTED_ENV guard keeps the
+// app INSIDE the host session from re-hosting itself.
+function runApp(appArgs: string[]): void {
+  const hosted = wantsHostedApp({
+    flagDetachable: values.detachable === true,
+    flagHosted: values.hosted === true,
+    configDetachable: loadAppConfig().app.detachable,
+    hostedEnv: process.env[HOSTED_ENV] === "1",
+  });
+  if (hosted) launchHostedApp(appScriptPath, appArgs);
+  else execBunWidget("app", appScriptPath, appArgs, "app");
+}
+
+// The unified app as the front door (M22.6): bare `tmux-ide` opens `tmux-ide
+// app`'s HOME panel when `app.frontDoor` is on and there's nothing else to
+// launch. Same entry as the explicit `app` command with no session positional
+// — including the hosted flip when `app.detachable` is set (M23.2).
+function launchApp(): void {
+  runApp([]);
+}
+
 try {
   switch (command) {
     case "start": {
@@ -332,13 +482,23 @@ try {
       }
       const targetDir = resolve(startTargetDir || ".");
       const hasIdeYml = existsSync(join(targetDir, "ide.yml"));
-      if (shouldOpenCockpit(hasIdeYml, values.team === true)) {
-        // No project here (or --team): the cockpit is the front door.
+      // M22.6 — the front-door decision. `--team` always means the classic
+      // cockpit; a present ide.yml still auto-launches the project; otherwise
+      // `app.frontDoor` flips the default no-project entry to the unified app.
+      const entry = resolveEntry({
+        hasIdeYml,
+        teamFlag: values.team === true,
+        frontDoor: loadAppConfig().app.frontDoor,
+      });
+      if (entry !== "project") {
+        // No project to launch here. `--json` is a scripting surface — it always
+        // prints the fleet, whichever interactive front door is configured.
         if (json) {
           await printFleetJson();
           break;
         }
-        launchTeamCockpit();
+        if (entry === "app") launchApp();
+        else launchTeamCockpit();
         break;
       }
       await launch(startTargetDir, { json });
@@ -491,6 +651,20 @@ try {
       break;
     }
 
+    case "app": {
+      // The unified app (M18.1): sidebar fleet + a live tmux-session mirror.
+      // Bare `tmux-ide app` opens the HOME panel (fleet cards); an optional
+      // session positional boots straight into that session's mirror. With
+      // `--detachable` (alias `--hosted`, or `app.detachable` in config) the
+      // app runs in the internal `_tmux-ide-app` session instead and this
+      // terminal attaches to it (M23.2) — the positional only shapes the
+      // cockpit at CREATE time; a reattach finds the app exactly as left.
+      const session = positionals[1];
+      const appArgs = session ? [`--target=${session}`] : [];
+      runApp(appArgs);
+      break;
+    }
+
     case "switcher": {
       // Runs the team app in PICKER mode inside a tmux `display-popup` (bound to
       // `M-p` on adopt). Picking a session `switch-client`s the invoking client
@@ -513,7 +687,7 @@ try {
         const pattern = values.match;
         if (!target || typeof pattern !== "string" || pattern.length === 0) {
           console.error(
-            "Usage: tmux-ide wait output <pane|session> --match <regex> [--timeout <ms>]",
+            "Usage: tmux-ide wait output <pane|session> --match <regex> [--timeout <ms>] [--socket[=path]]",
           );
           process.exit(1);
         }
@@ -523,46 +697,42 @@ try {
           console.error(`Invalid --match regex: ${(err as Error).message}`);
           process.exit(1);
         }
-        const { capturePane } = await import("../packages/tmux-bridge/src/index.ts");
         const outTimeout = Number(values.timeout ?? "60000");
-        const outStart = Date.now();
-        const nap = (ms: number) => new Promise((r) => setTimeout(r, ms));
-        while (true) {
-          let text = "";
-          try {
-            text = capturePane(target!, { lines: 200 });
-          } catch {
-            // pane/session not (yet) available — keep polling until timeout
-          }
-          const lines = text.split("\n");
-          // Fresh regex per test so a user-supplied /g flag can't carry lastIndex
-          // between calls. Report the specific matching line when we can.
-          let hit: string | null = null;
-          for (const line of lines) {
-            if (new RegExp(pattern!).test(line)) {
-              hit = line;
-              break;
-            }
-          }
-          if (hit === null && new RegExp(pattern!).test(text)) hit = lines[lines.length - 1] ?? "";
-          if (hit !== null) {
-            if (json) console.log(JSON.stringify({ matched: hit }));
-            else console.log(hit);
-            process.exit(0);
-          }
-          if (Date.now() - outStart >= outTimeout) {
+
+        // `--socket` fast path: let a running `tmux-ide serve` hold the wait
+        // (one process, no spawn-per-poll). Falls back silently when no server
+        // is listening — the polling below is exactly the same implementation.
+        const viaSocket = await waitOverSocket({
+          kind: "output",
+          target,
+          match: pattern,
+          timeoutMs: outTimeout,
+        });
+        if (viaSocket) {
+          if (viaSocket.timedOut) {
             console.error(
               `Timed out after ${outTimeout}ms waiting for ${target} output to match /${pattern}/`,
             );
             process.exit(1);
           }
-          await nap(500);
+          const hit = (viaSocket.data as { matched: string }).matched;
+          if (json) console.log(JSON.stringify({ matched: hit }));
+          else console.log(hit);
+          process.exit(0);
         }
-      }
 
-      const { createStatusTracker } = await import("../packages/daemon/src/tui/detect/classify.ts");
-      const { listTeamSessions } = await import("../packages/daemon/src/tui/team/sessions.ts");
-      const { findSessionStatus } = await import("../packages/daemon/src/tui/team/report.ts");
+        const { waitForOutputMatch } = await import("../packages/daemon/src/tui/team/wait.ts");
+        const result = await waitForOutputMatch(target!, pattern!, { timeoutMs: outTimeout });
+        if (!result.ok) {
+          console.error(
+            `Timed out after ${outTimeout}ms waiting for ${target} output to match /${pattern}/`,
+          );
+          process.exit(1);
+        }
+        if (json) console.log(JSON.stringify({ matched: result.matched }));
+        else console.log(result.matched);
+        process.exit(0);
+      }
 
       const VALID = new Set(["blocked", "working", "done", "idle", "unknown"]);
       const sessionName = positionals[2];
@@ -570,37 +740,50 @@ try {
 
       if (sub !== "agent-status" || !sessionName || typeof want !== "string" || !VALID.has(want)) {
         console.error(
-          "Usage: tmux-ide wait agent-status <session> --status <blocked|working|done|idle|unknown> [--timeout <ms>]",
+          "Usage: tmux-ide wait agent-status <session> --status <blocked|working|done|idle|unknown> [--timeout <ms>] [--socket[=path]]",
         );
         process.exit(1);
       }
 
       const timeout = Number(values.timeout ?? "60000");
-      const started = Date.now();
-      const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
-      // One tracker persists across polls so the working→idle `done` transition
-      // can be observed (it's inherently cross-tick).
-      const tracker = createStatusTracker();
-
-      while (true) {
-        const sessions = listTeamSessions(tracker);
-        const status = findSessionStatus(sessions, sessionName!);
-        if (status === want) {
-          if (json) {
-            console.log(JSON.stringify({ session: sessionName, status, ok: true }));
-          } else {
-            console.log(`${sessionName} reached status: ${status}`);
-          }
-          process.exit(0);
-        }
-        if (Date.now() - started >= timeout) {
+
+      const viaSocket = await waitOverSocket({
+        kind: "agent-status",
+        session: sessionName,
+        status: want,
+        timeoutMs: timeout,
+      });
+      if (viaSocket) {
+        if (viaSocket.timedOut) {
           console.error(
-            `Timed out after ${timeout}ms waiting for ${sessionName} to reach status "${want}" (last: ${status ?? "absent"})`,
+            `Timed out after ${timeout}ms waiting for ${sessionName} to reach status "${want}"`,
           );
           process.exit(1);
         }
-        await sleep(750);
+        if (json) console.log(JSON.stringify({ session: sessionName, status: want, ok: true }));
+        else console.log(`${sessionName} reached status: ${want}`);
+        process.exit(0);
       }
+
+      const { waitForAgentStatus } = await import("../packages/daemon/src/tui/team/wait.ts");
+      const result = await waitForAgentStatus(
+        sessionName!,
+        want as import("../packages/daemon/src/tui/detect/classify.ts").AgentStatus,
+        { timeoutMs: timeout },
+      );
+      if (!result.ok) {
+        console.error(
+          `Timed out after ${timeout}ms waiting for ${sessionName} to reach status "${want}" (last: ${result.status ?? "absent"})`,
+        );
+        process.exit(1);
+      }
+      if (json) {
+        console.log(JSON.stringify({ session: sessionName, status: result.status, ok: true }));
+      } else {
+        console.log(`${sessionName} reached status: ${result.status}`);
+      }
+      process.exit(0);
+      break;
     }
 
     case "events": {
@@ -613,10 +796,6 @@ try {
       type EventLike = { ts: string; session: string; from: Status | null; to: Status };
 
       const path = eventsPath();
-      if (!existsSync(path)) {
-        console.log("no events yet — is a session adopted? (the chrome updater writes events)");
-        break;
-      }
 
       // Status → ANSI color, matching the chrome bar's palette in spirit.
       const paintStatus = (status: Status | null, text: string): string => {
@@ -646,6 +825,40 @@ try {
         }
       };
 
+      // `--follow --socket` fast path: a running `tmux-ide serve` PUSHES
+      // transitions the moment its detection tick sees them — no file polling.
+      // The last-50 backlog still comes from the log (the server has no
+      // history); falls back silently to the polling path when no server is up.
+      if (values.follow && socketFlag) {
+        const { connectControl } = await import("../packages/daemon/src/control/client.ts");
+        const client = await connectControl({
+          socketPath: typeof socketFlag === "string" ? socketFlag : undefined,
+        }).catch(() => null);
+        if (client) {
+          if (existsSync(path)) {
+            const backlog = readFileSync(path, "utf8")
+              .split("\n")
+              .filter((l) => l.trim().length > 0);
+            for (const line of backlog.slice(-50)) printLine(line);
+          }
+          await client.subscribe((frame) => {
+            if (frame.event === "agent-status") printLine(JSON.stringify(frame.data));
+          });
+          process.on("SIGINT", () => {
+            client.close();
+            process.exit(0);
+          });
+          // Ends when the server shuts down (EOF) — exit cleanly then.
+          await client.done;
+          break;
+        }
+      }
+
+      if (!existsSync(path)) {
+        console.log("no events yet — is a session adopted? (the chrome updater writes events)");
+        break;
+      }
+
       const allLines = readFileSync(path, "utf8")
         .split("\n")
         .filter((l) => l.trim().length > 0);
@@ -769,18 +982,36 @@ try {
     case "integration": {
       const sub = positionals[1];
       const agent = positionals[2];
-      // `status` and `offer` need no agent arg; install/uninstall are claude-only.
-      const needsClaude = sub === "install" || sub === "uninstall";
-      if (!sub || (needsClaude && agent !== "claude")) {
+      // `status` and `offer` need no agent arg; install/uninstall take a kind
+      // we ship an integration for (claude hooks, opencode plugin).
+      const needsAgent = sub === "install" || sub === "uninstall";
+      const installable = agent === "claude" || agent === "opencode";
+      if (!sub || (needsAgent && !installable)) {
         console.error(
-          "Usage: tmux-ide integration <install|uninstall|status|offer> [claude]\n" +
-            "  install    hook Claude Code lifecycle events into tmux pane state\n" +
-            "  uninstall  remove exactly the tmux-ide hook entries\n" +
-            "  status     list discovered agents + integration state\n" +
+          "Usage: tmux-ide integration <install|uninstall|status|offer> [claude|opencode]\n" +
+            "  install    claude: hook lifecycle events into tmux pane state\n" +
+            "             opencode: plugin that records the session id for restore --resume-agents\n" +
+            "  uninstall  remove exactly the tmux-ide entries for that agent\n" +
+            "  status     list discovered agents + integration/capture state\n" +
             "  offer      one-time first-adopt install prompt (used by the popup)",
         );
         process.exit(1);
       }
+      if (needsAgent && agent === "opencode") {
+        const oc = await import("../packages/daemon/src/tui/integrations/opencode.ts");
+        if (sub === "install") {
+          const { pluginPath } = oc.installOpencodeIntegration();
+          console.log(`plugin: ${pluginPath}`);
+          console.log(
+            "installed — NEW opencode sessions record their session id into the pane\n" +
+              "(@agent_session_id), so `tmux-ide restore --resume-agents` can revive them.",
+          );
+        } else {
+          const { wasInstalled } = oc.uninstallOpencodeIntegration();
+          console.log(wasInstalled ? "uninstalled — plugin removed" : "was not installed");
+        }
+        break;
+      }
       const mod = await import("../packages/daemon/src/tui/integrations/claude.ts");
       if (sub === "install") {
         const { scriptPath, settingsPath } = mod.installClaudeIntegration();
@@ -796,6 +1027,51 @@ try {
           "installed — NEW Claude Code sessions now report working/blocked/done " +
             "authoritatively into the tmux-ide chrome.",
         );
+        // M25.1: this is the moment the user is wiring notifications, so offer
+        // the macOS banner channel here — one plain y/N key, same shape as the
+        // first-adopt offer. Skipped when already on, off-macOS, or when there
+        // is no TTY to ask (TMUX_IDE_NOTIFY_KEY forces an answer for tests).
+        const { getAppConfig, updateAppConfig } =
+          await import("../packages/daemon/src/lib/app-config.ts");
+        const forcedKey = process.env.TMUX_IDE_NOTIFY_KEY;
+        const canAsk = forcedKey !== undefined || process.stdin.isTTY === true;
+        if (process.platform === "darwin" && !getAppConfig().notifications.macos && canAsk) {
+          const act = (key: string): void => {
+            if (key === "y" || key === "Y") {
+              updateAppConfig({ notifications: { macos: true } });
+              console.log(
+                "macOS notifications on — native branded banners will jump to the session when clicked.",
+              );
+            } else {
+              console.log(
+                "skipped — turn banners on anytime: notifications.macos in ~/.tmux-ide/config.json.",
+              );
+            }
+          };
+          process.stdout.write("\nAlso get a macOS notification when an agent needs you? [y/N] ");
+          if (forcedKey !== undefined) {
+            console.log(forcedKey);
+            act(forcedKey);
+          } else {
+            const key = await new Promise<string>((resolve) => {
+              try {
+                process.stdin.setRawMode?.(true);
+                process.stdin.resume();
+                process.stdin.once("data", (data) => resolve(data.toString()));
+              } catch {
+                resolve(""); // no readable stdin — treat as "no"
+              }
+            });
+            try {
+              process.stdin.setRawMode?.(false);
+              process.stdin.pause();
+            } catch {
+              // best-effort terminal restore
+            }
+            console.log(/^[ -~]$/.test(key) ? key : "");
+            act(key);
+          }
+        }
       } else if (sub === "uninstall") {
         const { wasInstalled } = mod.uninstallClaudeIntegration();
         console.log(wasInstalled ? "uninstalled — hook entries removed" : "was not installed");
@@ -861,7 +1137,18 @@ try {
           else if (a.integration)
             state = a.installed ? "integration installed ✓" : "on PATH — integration not installed";
           else state = "detected (no integration)";
-          console.log(`  ${a.id.padEnd(10)} ${state}`);
+          // The resume-key story: how @agent_session_id (what `restore
+          // --resume-agents` revives from) gets captured for this kind.
+          let capture = "";
+          if (a.path !== null) {
+            if (a.capture === "probe") capture = " · session-id capture: automatic";
+            else if (a.capture !== null)
+              capture = a.captureActive
+                ? ` · session-id capture: ${a.capture} ✓`
+                : ` · session-id capture: ${a.capture} (install to enable)`;
+            else capture = " · session-id capture: none";
+          }
+          console.log(`  ${a.id.padEnd(10)} ${state}${capture}`);
         }
       }
       break;
@@ -1338,6 +1625,45 @@ try {
     }
 
     case "update": {
+      // `--manifests`: fetch the agent-detection manifest pack (versioned JSON,
+      // a GitHub release asset) into ~/.tmux-ide/agent-detection/pack/ — the
+      // loader hot-merges it under bundled<pack<user precedence. Schema-invalid
+      // packs are rejected loudly. See lib/manifest-pack.ts for the format.
+      if (values["manifests"] === true) {
+        const { updateManifestPack } = await import("../packages/daemon/src/lib/manifest-pack.ts");
+        try {
+          const r = await updateManifestPack({ log: (m) => console.error(m) });
+          if (json) {
+            console.log(JSON.stringify({ ok: true, ...r }, null, 2));
+          } else {
+            console.log(
+              `manifest pack ${r.packVersion} installed (${r.count} manifests): ${r.path}`,
+            );
+            console.log(
+              "your own agent-detection/*.json overrides still win — the pack merges beneath them",
+            );
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          if (json) console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+          else console.error(`manifest pack NOT installed: ${message}`);
+          process.exitCode = 1;
+        }
+        break;
+      }
+      // `--tui-binary`: download the per-platform TUI binary (the fallback that
+      // lets an npm install with no bun run the full cockpit). Explicit opt-in —
+      // never auto-fetched on install (it's ~70MB). See lib/tui-binary.ts.
+      if (values["tui-binary"] === true) {
+        const { downloadTuiBinary } = await import("../packages/daemon/src/lib/tui-binary.ts");
+        const { path } = await downloadTuiBinary({ log: (m) => console.error(m) });
+        if (json) {
+          console.log(JSON.stringify({ ok: true, path }, null, 2));
+        } else {
+          console.log(`TUI binary ready: ${path}`);
+        }
+        break;
+      }
       // Detect how tmux-ide was installed and act on the pending update: a dev
       // checkout prints the `git pull` hint; a global install prints (with
       // --dry-run) or runs its package manager's update command. `__dirname` is
@@ -1381,6 +1707,34 @@ try {
       break;
     }
 
+    case "serve": {
+      // The local control socket (M23.3): NDJSON verbs + pushed agent-status
+      // events over a 0600 Unix socket. Foreground on purpose — the process
+      // the user (or their agent loop) started is the process they own; see
+      // the host tradeoff in control/server.ts.
+      const { startControlServer, defaultControlSocketPath } =
+        await import("../packages/daemon/src/control/server.ts");
+      const socketPath =
+        typeof socketFlag === "string"
+          ? socketFlag
+          : (positionals[1] ?? defaultControlSocketPath());
+      const server = await startControlServer({
+        socketPath,
+        log: (m) => console.error(`[serve] ${m}`),
+      });
+      let closing = false;
+      const shutdown = () => {
+        if (closing) return;
+        closing = true;
+        // Unlinks the socket and EOFs every client before exiting.
+        void server.close().then(() => process.exit(0));
+      };
+      process.on("SIGTERM", shutdown);
+      process.on("SIGINT", shutdown);
+      await new Promise(() => {}); // the server owns the process lifetime
+      break;
+    }
+
     case "command-center": {
       const { startCommandCenter } = await import("../packages/daemon/src/command-center/index.ts");
       await startCommandCenter({ port: parseInt(values.port ?? "4000") });