tmux-ide 2.8.0 → 2.9.0-beta.6

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,11 +40,15 @@ 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,
@@ -48,6 +57,9 @@ import {
   hostCreateArgv,
   hostSetupArgvs,
   hostAttachArgv,
+  hostRootBindingsArgv,
+  hostPutAwayBindingArgv,
+  hostedPutAwayBindingState,
   HOSTED_ENV,
 } from "../packages/daemon/src/tui/mirror/hosted.ts";
 
@@ -56,6 +68,7 @@ const { positionals, values } = parseArgs({
   strict: false,
   options: {
     json: { type: "boolean" },
+    headless: { type: "boolean" },
     row: { type: "string" },
     pane: { type: "string" },
     title: { type: "string" },
@@ -128,6 +141,7 @@ const knownCommands = new Set([
   "inspect",
   "validate",
   "detect",
+  "migrate",
   "config",
   "setup",
   "send",
@@ -146,11 +160,14 @@ const knownCommands = new Set([
   "cheatsheet",
   "welcome",
   "menu",
+  "show",
   "popup",
   "sidebar-toggle",
   "worktree",
   "update",
   "skill-sync",
+  "widget",
+  "web",
   "serve",
   "command-center",
   "server",
@@ -189,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]
@@ -204,6 +223,7 @@ ${bold("Usage:")}
   ${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)")}
@@ -214,11 +234,16 @@ ${bold("Usage:")}
   ${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")}
@@ -230,18 +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")}
@@ -249,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)")}
@@ -261,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")}`);
@@ -288,6 +317,7 @@ function execBunWidget(
     checkoutExists: existsSync(scriptPath),
     bunAvailable: isBunAvailable(),
     compiledBinary: findCompiledTui(),
+    preferSource: process.env.TMUX_IDE_TUI_SOURCE === "1",
   });
 
   if (launch.mode === "unavailable") {
@@ -298,37 +328,109 @@ 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; ^q inside a
-// hosted app detaches (the HOSTED_ENV marker on the pane command flips it).
+// 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({
@@ -338,6 +440,7 @@ function launchHostedApp(scriptPath: string, appArgs: string[]): void {
     checkoutExists: existsSync(scriptPath),
     bunAvailable: isBunAvailable(),
     compiledBinary: findCompiledTui(),
+    preferSource: process.env.TMUX_IDE_TUI_SOURCE === "1",
   });
   if (launch.mode === "unavailable") {
     throw new IdeError(
@@ -357,7 +460,7 @@ function launchHostedApp(scriptPath: string, appArgs: string[]): void {
     // 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 cwd = launch.mode === "bun" ? resolve(__dirname, "..") : ensureCompiledTuiRuntimeDir();
     const commandLine = hostedCommandLine(
       launch.bin,
       launch.argv,
@@ -378,12 +481,35 @@ function launchHostedApp(scriptPath: string, appArgs: string[]): void {
   // `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");
@@ -441,7 +567,28 @@ function launchTeamCockpit(): void {
 // `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 {
+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,
@@ -456,11 +603,31 @@ function runApp(appArgs: string[]): void {
 // 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([]);
+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
@@ -481,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,
       });
@@ -497,7 +673,7 @@ try {
           await printFleetJson();
           break;
         }
-        if (entry === "app") launchApp();
+        if (entry === "app") await launchApp();
         else launchTeamCockpit();
         break;
       }
@@ -554,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";
@@ -661,7 +841,7 @@ try {
       // cockpit at CREATE time; a reattach finds the app exactly as left.
       const session = positionals[1];
       const appArgs = session ? [`--target=${session}`] : [];
-      runApp(appArgs);
+      await runApp(appArgs);
       break;
     }
 
@@ -765,6 +945,37 @@ try {
         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: ${viaReceipts.status ?? "absent"})`,
+          );
+          process.exit(1);
+        }
+        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!,
@@ -1381,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 {
@@ -1392,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 {
@@ -1429,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");
 
@@ -1447,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);
@@ -1707,6 +1918,149 @@ 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
@@ -1735,6 +2089,13 @@ try {
       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") });