tmux-ide 2.7.0 → 2.9.0-beta.5

package/bin/cli.ts

@@ -5,7 +5,7 @@
 import { parseArgs } from "node:util";
 import { resolve, dirname, join } from "node:path";
 import { execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -20,10 +20,15 @@ const nodeCliPath = selfPath.endsWith(".js") ? selfPath : resolve(__dirname, "cl
 import { launch } from "../packages/daemon/src/launch.ts";
 import { resolveEntry } from "../packages/daemon/src/tui/team/entry.ts";
 import { loadAppConfig } from "../packages/daemon/src/lib/app-config.ts";
+import { resolveConfig } from "../packages/daemon/src/lib/resolved-config.ts";
+import { resolveProjectConfigContext } from "../packages/daemon/src/lib/config-context.ts";
 import {
+  ensureCompiledTuiRuntimeDir,
+  ensureTuiLaunchAvailable,
   resolveTuiLaunch,
   findCompiledTui,
   isBunAvailable,
+  openTuiLaunchEnvironment,
 } from "../packages/daemon/src/tui/compiled.ts";
 import { init } from "../packages/daemon/src/init.ts";
 import { stop } from "../packages/daemon/src/stop.ts";
@@ -35,17 +40,35 @@ import { inspect } from "../packages/daemon/src/inspect.ts";
 import { validate } from "../packages/daemon/src/validate.ts";
 import { detect } from "../packages/daemon/src/detect.ts";
 import { config } from "../packages/daemon/src/config.ts";
+import { migrate } from "../packages/daemon/src/migrate.ts";
 import { restart } from "../packages/daemon/src/restart.ts";
 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 { runHeadlessDaemon } from "../packages/daemon/src/lib/headless-daemon.ts";
+import { ensureCanonicalDaemon } from "../packages/daemon/src/lib/canonical-daemon-bootstrap.ts";
+import { stateHome } from "../packages/daemon/src/lib/state-home.ts";
+import {
+  wantsHostedApp,
+  hostedEnvVars,
+  hostedCommandLine,
+  hostExistsArgv,
+  hostCreateArgv,
+  hostSetupArgvs,
+  hostAttachArgv,
+  hostRootBindingsArgv,
+  hostPutAwayBindingArgv,
+  hostedPutAwayBindingState,
+  HOSTED_ENV,
+} from "../packages/daemon/src/tui/mirror/hosted.ts";
 
 const { positionals, values } = parseArgs({
   allowPositionals: true,
   strict: false,
   options: {
     json: { type: "boolean" },
+    headless: { type: "boolean" },
     row: { type: "string" },
     pane: { type: "string" },
     title: { type: "string" },
@@ -92,6 +115,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" },
@@ -114,6 +141,7 @@ const knownCommands = new Set([
   "inspect",
   "validate",
   "detect",
+  "migrate",
   "config",
   "setup",
   "send",
@@ -132,11 +160,15 @@ const knownCommands = new Set([
   "cheatsheet",
   "welcome",
   "menu",
+  "show",
   "popup",
   "sidebar-toggle",
   "worktree",
   "update",
   "skill-sync",
+  "widget",
+  "web",
+  "serve",
   "command-center",
   "server",
   "help",
@@ -174,12 +206,14 @@ function printHelp() {
   console.log(`${bold("tmux-ide")} — Terminal IDE powered by tmux
 
 ${bold("Usage:")}
-  ${cyan("tmux-ide")}                    ${dim("Launch ide.yml, or open the team cockpit if none")}
-  ${cyan("tmux-ide <path>")}             ${dim("Launch from a specific directory (cockpit if no ide.yml)")}
+  ${cyan("tmux-ide")}                    ${dim("Open the visual tmux app (workspace config is optional)")}
+  ${cyan("tmux-ide start")} [path]       ${dim("Explicitly launch the declarative project layout")}
+  ${cyan("tmux-ide --headless")}         ${dim("Run the canonical daemon in this foreground process")}
+  ${cyan("tmux-ide <path>")}             ${dim("Open a configured workspace, or visually manage tmux from that folder")}
   ${cyan("tmux-ide setup")}              ${dim("Interactive TUI setup wizard")}
   ${cyan("tmux-ide setup --edit")}       ${dim("Open config tree editor")}
   ${cyan("tmux-ide settings")}           ${dim("Interactive TUI config manager")}
-  ${cyan("tmux-ide init")} [--template]  ${dim("Scaffold a new ide.yml (auto-detects stack)")}
+  ${cyan("tmux-ide init")} [--template]  ${dim("Scaffold .tmux-ide/workspace.yml (auto-detects stack)")}
   ${cyan("tmux-ide stop")}               ${dim("Kill the current IDE session")}
   ${cyan("tmux-ide restart")}            ${dim("Stop and relaunch the IDE session")}
   ${cyan("tmux-ide restore")} [--dry-run] [--run-commands] [--resume-agents] [--json]
@@ -188,20 +222,28 @@ ${bold("Usage:")}
   ${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 app --hosted")}       ${dim("Alias for --detachable")}
   ${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")}
-  ${cyan("tmux-ide integration install claude")}  ${dim("Authoritative agent status via Claude Code hooks")}
+  ${cyan("tmux-ide integration install claude")}  ${dim("Claude Code lifecycle hooks + managed tmux-ide skill")}
+  ${cyan("tmux-ide integration install opencode")} ${dim("Capture opencode session ids for restore --resume-agents")}
+  ${cyan("tmux-ide integration uninstall")} <claude|opencode> ${dim("Remove tmux-ide's integration entries")}
+  ${cyan("tmux-ide integration status")} [--json]  ${dim("Show discovered agents, integration state, and resume-id capture")}
   ${cyan("tmux-ide agent explain")} <pane> [--json]  ${dim("Debug how a pane's agent state is detected")}
   ${cyan("tmux-ide cheatsheet")}         ${dim("Print the key cheat sheet (⌥k / [ ? keys ] popup)")}
   ${cyan("tmux-ide menu")} [--client N]  ${dim("Open the right-click actions menu (⌥m / right-click any pane or the bar)")}
   ${cyan("tmux-ide popup")} <widget>     ${dim("Open a widget as a floating panel (explorer/changes/config; ⌥e/⌥g/⌥,)")}
+  ${cyan("tmux-ide widget")} <markdown|image|card> [file]  ${dim("Render rich live content in the current pane")}
+  ${cyan("tmux-ide show")} <file>          ${dim("Show Markdown, images, GIFs, or cards by file type")}
   ${cyan("tmux-ide sidebar-toggle")} [--session S]  ${dim("Toggle the app nav column (⌥b on adopted sessions)")}
   ${cyan("tmux-ide worktree create")} <branch> [--from <ref>] [--dir <path>] [--no-session]
                               ${dim("Add a git worktree (new branch) + open a session in it")}
@@ -213,17 +255,19 @@ ${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 --tui-binary")} ${dim("Download and verify this version's compiled OpenTUI runtime")}
+  ${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 validate")} [--json]  ${dim("Validate workspace config")}
   ${cyan("tmux-ide detect")} [--json]    ${dim("Detect project stack")}
-  ${cyan("tmux-ide detect --write")}     ${dim("Detect and write ide.yml")}
+  ${cyan("tmux-ide detect --write")}     ${dim("Detect and write .tmux-ide/workspace.yml")}
+  ${cyan("tmux-ide migrate --dry-run")} [--json]  ${dim("Preview ide.yml migration")}
+  ${cyan("tmux-ide migrate --write")} [--json]    ${dim("Create .tmux-ide/workspace.yml")}
   ${cyan("tmux-ide config")} [--json]    ${dim("Dump config as JSON")}
   ${cyan("tmux-ide config set")} <path> <value>
   ${cyan("tmux-ide config add-pane")} --row <N> --title <T> [--command <C>]
   ${cyan("tmux-ide config remove-pane")} --row <N> --pane <M>
   ${cyan("tmux-ide config add-row")} [--size <percent>]
-  ${cyan("tmux-ide config enable-team")} [--name <N>]   ${dim("Enable agent teams")}
-  ${cyan("tmux-ide config disable-team")}               ${dim("Disable agent teams")}
 
 ${bold("Pane Messaging:")}
   ${cyan("tmux-ide send")} <target> <message>     ${dim("Send message to a pane")}
@@ -231,11 +275,12 @@ ${bold("Pane Messaging:")}
   ${cyan("tmux-ide send")} <target> --no-enter msg  ${dim("Send text without pressing Enter")}
 
 ${bold("Server:")}
+  ${cyan("tmux-ide serve")} [socket-path]         ${dim("Foreground owner-only local NDJSON control socket")}
   ${cyan("tmux-ide command-center")} [--port N]    ${dim("Start the command-center HTTP API")}
   ${cyan("tmux-ide server")} [--port N]            ${dim("Start HTTP + PTY WebSocket server")}
 
 ${bold("Discover (in the TUI):")}
-  ${dim("Bare")} ${cyan("tmux-ide")} ${dim("with no ide.yml opens the HOME cockpit — the fleet home screen.")}
+  ${dim("Bare")} ${cyan("tmux-ide")} ${dim("with no project config opens the HOME cockpit — the fleet home screen.")}
   ${dim("Once a session is adopted, the whole UI is one keystroke away:")}
   ${cyan("⌥h")}  ${dim("home cockpit from anywhere    ")}${cyan("⌥p")}  ${dim("switch session")}
   ${cyan("⌥k")}  ${dim("cheat sheet (all keys)        ")}${cyan("⌥m")}  ${dim("actions menu (or right-click any pane / the bar)")}
@@ -243,9 +288,11 @@ ${bold("Discover (in the TUI):")}
   ${dim("A first-run welcome card names these keys once. Run")} ${cyan("tmux-ide cheatsheet")} ${dim("to see the full sheet.")}
 
 ${bold("Flags:")}
-  ${cyan("--json")}                      ${dim("Output as JSON (all commands)")}
+  ${cyan("--json")}                      ${dim("Structured output on commands that advertise JSON support")}
+  ${cyan("--headless")}                  ${dim("Canonical daemon only; no tmux workspace or TUI")}
   ${cyan("--template <name>")}           ${dim("Use specific template for init")}
-  ${cyan("--write")}                     ${dim("Write detected config to ide.yml")}
+  ${cyan("--write")}                     ${dim("Write detected config to .tmux-ide/workspace.yml")}
+  ${cyan("--dry-run")}                   ${dim("Preview migration/restore without writing")}
   ${cyan("--verbose")}                   ${dim("Log all tmux commands (or set TMUX_IDE_DEBUG=1)")}
   ${cyan("-h, --help")}                  ${dim("Show usage")}
   ${cyan("-v, --version")}               ${dim("Show version number")}`);
@@ -270,6 +317,7 @@ function execBunWidget(
     checkoutExists: existsSync(scriptPath),
     bunAvailable: isBunAvailable(),
     compiledBinary: findCompiledTui(),
+    preferSource: process.env.TMUX_IDE_TUI_SOURCE === "1",
   });
 
   if (launch.mode === "unavailable") {
@@ -280,35 +328,188 @@ function execBunWidget(
     );
   }
 
-  const env = {
-    ...process.env,
+  const launchEpochMs = Date.now();
+  let automaticDiagnosticLog: string | undefined;
+  if (surface === "app" && !process.env.TMUX_IDE_TUI_PERF_LOG) {
+    try {
+      const logDirectory = join(stateHome(), "logs");
+      mkdirSync(logDirectory, { recursive: true, mode: 0o700 });
+      automaticDiagnosticLog = join(logDirectory, "tui-latest.jsonl");
+      writeFileSync(
+        automaticDiagnosticLog,
+        `${JSON.stringify({
+          phase: "launcher-start",
+          elapsedMs: 0,
+          at: new Date(launchEpochMs).toISOString(),
+          surface,
+          launchMode: launch.mode,
+        })}\n`,
+        { mode: 0o600 },
+      );
+    } catch {
+      // Diagnostics must never prevent the product from launching.
+      automaticDiagnosticLog = undefined;
+    }
+  }
+  const env = openTuiLaunchEnvironment(process.env, {
     TMUX_IDE_CWD: process.cwd(),
     TMUX_IDE_CLI: nodeCliPath,
+    ...(automaticDiagnosticLog
+      ? {
+          TMUX_IDE_TUI_PERF_LOG: automaticDiagnosticLog,
+          TMUX_IDE_TUI_LAUNCH_EPOCH_MS: String(launchEpochMs),
+        }
+      : {}),
     ...extraEnv,
+  });
+  const markChildExited = () => {
+    if (!automaticDiagnosticLog) return;
+    try {
+      appendFileSync(
+        automaticDiagnosticLog,
+        `${JSON.stringify({
+          phase: "launcher-child-exited",
+          elapsedMs: Date.now() - launchEpochMs,
+          at: new Date().toISOString(),
+          status: 0,
+          signal: null,
+        })}\n`,
+      );
+    } catch {
+      // Diagnostics must never change successful process semantics.
+    }
   };
-  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
-    // `tmux-ide` in a project dir — falls back to the React JSX runtime and the
-    // widget fails to load. The real invocation dir rides in env so in-widget
-    // prompts (register / new session) still default to where the user is.
+  try {
+    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
+      // `tmux-ide` in a project dir — falls back to the React JSX runtime and the
+      // widget fails to load. The real invocation dir rides in env so in-widget
+      // prompts (register / new session) still default to where the user is.
+      execFileSync(launch.bin, launch.argv, {
+        stdio: "inherit",
+        cwd: resolve(__dirname, ".."),
+        env,
+      });
+      markChildExited();
+      return;
+    }
+
+    // A compiled Bun executable still reads bunfig.toml from its cwd before the
+    // embedded app starts. Isolate it from the project checkout; TMUX_IDE_CWD
+    // preserves the user's real project directory for every app action.
     execFileSync(launch.bin, launch.argv, {
       stdio: "inherit",
-      cwd: resolve(__dirname, ".."),
+      cwd: ensureCompiledTuiRuntimeDir(),
       env,
     });
-    return;
+    markChildExited();
+  } catch (error) {
+    if (automaticDiagnosticLog) {
+      try {
+        const childError = error as { status?: unknown; signal?: unknown };
+        appendFileSync(
+          automaticDiagnosticLog,
+          `${JSON.stringify({
+            phase: "launcher-child-failed",
+            elapsedMs: Date.now() - launchEpochMs,
+            at: new Date().toISOString(),
+            status: childError.status ?? null,
+            signal: childError.signal ?? null,
+          })}\n`,
+        );
+      } catch {
+        // Preserve the original child failure.
+      }
+    }
+    throw error;
   }
+}
 
-  // Compiled binary: the JSX transform and native dylib are already baked in,
-  // so there is no bunfig to find — run from the user's actual cwd (also avoids
-  // a stray repo-root bunfig.toml preload the standalone binary can't resolve).
-  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; tmux handles ^q
+// with the exact invoking client as context while the resident app stays alive.
+// 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(),
+    preferSource: process.env.TMUX_IDE_TUI_SOURCE === "1",
+  });
+  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, "..") : ensureCompiledTuiRuntimeDir();
+    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" });
+  // Ctrl-Q must be resolved by tmux while the exact input client is still the
+  // command context. The shared renderer pane cannot identify which of several
+  // attached terminals supplied a key. Never replace a user-owned root bind:
+  // tmux 3.0 has no single-key/formatted list-keys query, so classify its
+  // bounded canonical root-table listing in-process.
+  const rootBindings = execFileSync("tmux", hostRootBindingsArgv(), {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 1_500,
+    maxBuffer: 1024 * 1024,
+  });
+  const putAwayBinding = hostedPutAwayBindingState(rootBindings);
+  if (putAwayBinding === "conflict") {
+    throw new IdeError(
+      "Cannot enable hosted Ctrl-Q because tmux's root C-q key is already user-bound. " +
+        "tmux-ide left that binding unchanged. Unbind or remap it, then run the app again; " +
+        "tmux prefix+d remains available for detaching.",
+      { code: "USAGE", exitCode: 1 },
+    );
+  }
+  if (putAwayBinding === "absent") {
+    execFileSync("tmux", hostPutAwayBindingArgv(), { 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
+// --json` and bare `tmux-ide --json` when there's no project config to launch. Dynamic
 // imports keep the interactive path free of the data-layer modules.
 async function printFleetJson(): Promise<void> {
   const { createStatusTracker } = await import("../packages/daemon/src/tui/detect/classify.ts");
@@ -317,6 +518,41 @@ 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");
 
@@ -327,14 +563,71 @@ 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.
+async function runApp(appArgs: string[]): Promise<void> {
+  // A clean npm install has neither a checkout runtime nor Bun. Acquire the
+  // exact-version OpenTUI release artifact on the first explicit app launch so
+  // users never need a hidden setup command. This must complete before daemon
+  // election: a failed/offline download must not leave a persistent background
+  // process behind. Existing binaries and Bun-backed development checkouts
+  // return without network work.
+  await ensureTuiLaunchAvailable(
+    {
+      surface: "app",
+      scriptPath: appScriptPath,
+      args: appArgs,
+      checkoutExists: existsSync(appScriptPath),
+      bunAvailable: isBunAvailable(),
+      compiledBinary: findCompiledTui(),
+      preferSource: process.env.TMUX_IDE_TUI_SOURCE === "1",
+    },
+    { log: (message) => process.stderr.write(`[tmux-ide] ${message}\n`) },
+  );
+  // The app is a thin client. Establish the one persistent daemon generation
+  // only after its renderer is known-runnable, then mount against that owner.
+  await ensureCanonicalDaemon({ entryPath: nodeCliPath });
+  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.
-function launchApp(): void {
-  execBunWidget("app", appScriptPath, [], "app");
+// 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(): Promise<void> {
+  return runApp([]);
 }
 
 try {
+  if (values.headless) {
+    if (positionals.length > 0) {
+      throw new IdeError("--headless cannot be combined with a command or project path", {
+        code: "USAGE",
+        exitCode: 2,
+      });
+    }
+    const pkg = await import("../package.json");
+    await runHeadlessDaemon({
+      port: values.port,
+      json,
+      expectedVersion: pkg.version,
+    });
+    // The daemon cleanup is complete here. Exit explicitly because stores and
+    // native adapters may retain harmless timers/handles that must not turn a
+    // stopped desktop-owned daemon into a zombie process.
+    // Flush a piped JSON/human status before the explicit owner exit.
+    await new Promise<void>((resolveFlush) => process.stdout.write("", resolveFlush));
+    process.exit(0);
+  }
   switch (command) {
     case "start": {
       // npm-style staleness nudge: one dim stderr line when a newer version is
@@ -355,12 +648,21 @@ try {
         }
       }
       const targetDir = resolve(startTargetDir || ".");
-      const hasIdeYml = existsSync(join(targetDir, "ide.yml"));
+      if (startTargetDir && !existsSync(targetDir)) {
+        throw new IdeError(
+          `No workspace config found in ${targetDir}. Run "tmux-ide init" or "tmux-ide detect --write" to create one.`,
+          { code: "CONFIG_NOT_FOUND", exitCode: 1 },
+        );
+      }
+      const configContext = await resolveProjectConfigContext(targetDir);
       // M22.6 — the front-door decision. `--team` always means the classic
-      // cockpit; a present ide.yml still auto-launches the project; otherwise
+      // cockpit; a present project config still auto-launches the project; otherwise
       // `app.frontDoor` flips the default no-project entry to the unified app.
       const entry = resolveEntry({
-        hasIdeYml,
+        bareInvocation: firstPositional === undefined,
+        configKind: configContext.configKind,
+        hasWorkspaceConfig: configContext.hasWorkspaceConfig,
+        hasIdeYml: configContext.hasIdeYml,
         teamFlag: values.team === true,
         frontDoor: loadAppConfig().app.frontDoor,
       });
@@ -371,7 +673,7 @@ try {
           await printFleetJson();
           break;
         }
-        if (entry === "app") launchApp();
+        if (entry === "app") await launchApp();
         else launchTeamCockpit();
         break;
       }
@@ -428,6 +730,10 @@ try {
       await detect(positionals[1], { json, write: values.write });
       break;
 
+    case "migrate":
+      await migrate(positionals[1], { json, dryRun: values["dry-run"], write: values.write });
+      break;
+
     case "config": {
       const sub = positionals[1];
       let action = "dump";
@@ -528,10 +834,14 @@ try {
     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.
+      // 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}`] : [];
-      execBunWidget("app", appScriptPath, appArgs, "app");
+      await runApp(appArgs);
       break;
     }
 
@@ -557,7 +867,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);
         }
@@ -567,46 +877,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];
@@ -614,37 +920,81 @@ 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);
+
+      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}"`,
+          );
+          process.exit(1);
         }
-        if (Date.now() - started >= timeout) {
+        if (json) console.log(JSON.stringify({ session: sessionName, status: want, ok: true }));
+        else console.log(`${sessionName} reached status: ${want}`);
+        process.exit(0);
+      }
+
+      // Receipt fast path: a running daemon pushes a typed `agent.turn-completed`
+      // receipt on /ws/events the moment its watcher observes the transition —
+      // one idle socket instead of re-scraping the fleet every poll. Only
+      // `done`/`idle` are receipt-covered; anything it cannot answer (no
+      // daemon, connect failure, socket drop, other target status) returns
+      // null and the polling below takes over. A receipt-path timeout is a
+      // real timeout, not a fallback.
+      const { waitForAgentStatusViaReceipts } =
+        await import("../packages/daemon/src/tui/team/wait-receipts.ts");
+      const viaReceipts = await waitForAgentStatusViaReceipts(
+        sessionName!,
+        want as import("../packages/daemon/src/tui/detect/classify.ts").AgentStatus,
+        { timeoutMs: timeout },
+      );
+      if (viaReceipts) {
+        if (!viaReceipts.ok) {
           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}" (last: ${viaReceipts.status ?? "absent"})`,
           );
           process.exit(1);
         }
-        await sleep(750);
+        if (json) {
+          console.log(
+            JSON.stringify({ session: sessionName, status: viaReceipts.status, ok: true }),
+          );
+        } else {
+          console.log(`${sessionName} reached status: ${viaReceipts.status}`);
+        }
+        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": {
@@ -657,10 +1007,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 => {
@@ -690,6 +1036,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);
@@ -813,18 +1193,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();
@@ -840,6 +1238,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");
@@ -905,7 +1348,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;
@@ -1138,7 +1592,7 @@ try {
           break;
         }
         // Opening: resolve the session's cwd + best-effort sidebar width/theme
-        // from an ide.yml there (any adopted session may have none → defaults).
+        // from the resolved project config there (any adopted session may have none → defaults).
         const { getSessionCwd } = await import("../packages/tmux-bridge/src/index.ts");
         let dir = process.cwd();
         try {
@@ -1149,13 +1603,13 @@ try {
         let width = DEFAULT_SIDEBAR_WIDTH;
         let theme = null;
         try {
-          const { readConfig } = await import("../packages/daemon/src/lib/yaml-io.ts");
-          const { config } = readConfig(dir);
-          theme = config.theme ?? null;
-          const sb = resolveSidebarConfig(config.sidebar);
+          const resolved = await resolveConfig(dir);
+          const config = resolved.launchConfig;
+          theme = config?.theme ?? null;
+          const sb = resolveSidebarConfig(config?.sidebar);
           if (sb.enabled) width = sb.width;
         } catch {
-          // no/invalid ide.yml — defaults are fine
+          // no/invalid project config — defaults are fine
         }
         openSidebarPane(session, dir, width, theme);
       } catch {
@@ -1186,7 +1640,6 @@ try {
         removeWorktree,
         WorktreeError,
       } = await import("../packages/daemon/src/lib/worktree.ts");
-      const { getSessionName } = await import("../packages/daemon/src/lib/yaml-io.ts");
       const { getSessionCwd, hasSession, killSession, createDetachedSession } =
         await import("../packages/tmux-bridge/src/index.ts");
 
@@ -1204,19 +1657,20 @@ try {
         }
       }
 
-      // The project identity for session names: the MAIN worktree's ide.yml name
+      // The project identity for session names: the MAIN worktree's config name
       // (or its dir basename). `git worktree list` returns the main checkout first.
       const worktrees = listWorktrees(repoDir);
       const mainPath = worktrees[0]?.path ?? repoDir;
-      const projectName = getSessionName(mainPath).name;
+      const projectName = (await resolveProjectConfigContext(mainPath)).sessionName;
 
-      // Start a session in a worktree checkout: full IDE layout when it has an
-      // ide.yml (launch under the worktree's own session name so it never
+      // Start a session in a worktree checkout: full IDE layout when it has a
+      // workspace config (launch under the worktree's own session name so it never
       // collides with the parent repo's session), else a plain adopted session.
       // Never auto-attaches — the caller may be inside tmux (the menu) — it prints
       // how to switch instead.
       async function openWorktreeSession(wtPath: string, name: string): Promise<void> {
-        if (existsSync(join(wtPath, "ide.yml"))) {
+        const worktreeContext = await resolveProjectConfigContext(wtPath);
+        if (worktreeContext.configKind !== "none") {
           await launch(wtPath, { attach: false, sessionName: name });
         } else {
           if (!hasSession(name)) createDetachedSession(name, wtPath);
@@ -1382,6 +1836,32 @@ 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.
@@ -1438,6 +1918,184 @@ try {
       break;
     }
 
+    case "show":
+    case "widget": {
+      /*
+       * Opt this pane into rich rendering (m49.7).
+       *
+       *   tmux-ide widget markdown [file]     # or stdin; files live-refresh
+       *   tmux-ide widget image <file>        # PNG/JPEG/GIF/WebP/AVIF
+       *   tmux-ide widget card [file]         # or JSON on stdin
+       *
+       * The marker line carries inline content or a content-addressed asset id,
+       * so the helper prints ONE line and then holds the pane. File-backed
+       * widgets publish a new id whenever the file changes. Ctrl-C
+       * clears the screen, which is what takes the widget down — the renderer
+       * shows one for exactly as long as the marker is in the grid.
+       *
+       * Outside a tmux-ide window this prints a concealed line and waits, which
+       * is why the marker is wrapped in SGR 8 rather than left bare.
+       */
+      const {
+        PaneWidgetRefusal,
+        PANE_WIDGET_RESTORE_SEQUENCE,
+        buildCardAnnouncement,
+        buildImageAssetAnnouncement,
+        buildMarkdownAnnouncement,
+        buildMarkdownAssetAnnouncement,
+        imageMediaTypeFor,
+        paneWidgetId,
+        paneWidgetIdForFile,
+      } = await import("../packages/daemon/src/lib/pane-widget.ts");
+      const { publishWidgetAsset, WidgetAssetStoreError } =
+        await import("../packages/daemon/src/lib/widget-asset-store.ts");
+      const { readFileSync, watchFile, unwatchFile } = await import("node:fs");
+      const { basename } = await import("node:path");
+
+      const readStdin = async (): Promise<string> => {
+        const chunks: Buffer[] = [];
+        for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+        return Buffer.concat(chunks).toString("utf8");
+      };
+
+      let announcement: string;
+      let watchedFile: string | null = null;
+      let refreshAnnouncement: (() => string) | null = null;
+      try {
+        const friendlyShow = command === "show";
+        const file = friendlyShow ? positionals[1] : positionals[2];
+        if (friendlyShow && !file) {
+          throw new PaneWidgetRefusal("empty", "Usage: tmux-ide show <file>");
+        }
+        const id = friendlyShow
+          ? paneWidgetIdForFile(file ?? "")
+          : paneWidgetId(positionals[1] ?? "");
+        if (id === "markdown") {
+          if (file) {
+            const publish = (): string => {
+              const asset = publishWidgetAsset(readFileSync(file), {
+                media: "text/markdown",
+                name: basename(file),
+              });
+              return buildMarkdownAssetAnnouncement(asset.assetId, basename(file));
+            };
+            announcement = publish();
+            watchedFile = file;
+            refreshAnnouncement = publish;
+          } else {
+            announcement = buildMarkdownAnnouncement(await readStdin());
+          }
+        } else if (id === "image") {
+          if (!file) throw new PaneWidgetRefusal("empty", "The image widget needs a file path.");
+          const publish = (): string => {
+            const media = imageMediaTypeFor(file);
+            if (!media) {
+              throw new PaneWidgetRefusal(
+                "unsupported-media",
+                `"${basename(file)}" is not a supported raster image.`,
+              );
+            }
+            const asset = publishWidgetAsset(readFileSync(file), {
+              media: media as
+                | "image/png"
+                | "image/jpeg"
+                | "image/gif"
+                | "image/webp"
+                | "image/avif",
+              name: basename(file),
+            });
+            return buildImageAssetAnnouncement(asset.assetId, { name: basename(file) });
+          };
+          announcement = publish();
+          watchedFile = file;
+          refreshAnnouncement = publish;
+        } else {
+          const source = file ? readFileSync(file, "utf8") : await readStdin();
+          announcement = buildCardAnnouncement(JSON.parse(source) as unknown);
+        }
+      } catch (error) {
+        const message =
+          error instanceof PaneWidgetRefusal || error instanceof WidgetAssetStoreError
+            ? error.message
+            : `The widget input could not be read: ${(error as Error).message}`;
+        if (json) {
+          console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+        } else {
+          console.error(message);
+        }
+        process.exit(1);
+      }
+
+      if (json) {
+        // Machine callers want the line to emit themselves, not a held pane.
+        console.log(JSON.stringify({ ok: true, announcement }, null, 2));
+        break;
+      }
+
+      process.stdout.write(announcement);
+      if (watchedFile && refreshAnnouncement) {
+        const source = watchedFile;
+        const refresh = refreshAnnouncement;
+        watchFile(source, { interval: 750 }, (current, previous) => {
+          if (current.mtimeMs === previous.mtimeMs && current.size === previous.size) return;
+          try {
+            process.stdout.write(PANE_WIDGET_RESTORE_SEQUENCE + refresh());
+          } catch (error) {
+            process.stderr.write(
+              `tmux-ide ${command} could not refresh: ${(error as Error).message}\n`,
+            );
+          }
+        });
+      }
+      // Hold the pane. The process is doing nothing, but it is what Ctrl-C has
+      // to reach for the restore to be the user's own action rather than ours.
+      const hold = setInterval(() => undefined, 1 << 30);
+      const restore = (): void => {
+        clearInterval(hold);
+        if (watchedFile) unwatchFile(watchedFile);
+        process.stdout.write(PANE_WIDGET_RESTORE_SEQUENCE);
+        process.exit(0);
+      };
+      process.on("SIGINT", restore);
+      process.on("SIGTERM", restore);
+      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 "web": {
+      throw new IdeError(
+        "The Web GUI is not included in the OpenTUI beta. Run `tmux-ide app` for the supported interface.",
+        { code: "WEB_GUI_NOT_INCLUDED", exitCode: 1 },
+      );
+    }
+
     case "command-center": {
       const { startCommandCenter } = await import("../packages/daemon/src/command-center/index.ts");
       await startCommandCenter({ port: parseInt(values.port ?? "4000") });