tmux-ide 2.7.0 → 2.9.0-beta.11

package/packages/daemon/dist/tui/mirror/home-surface-model.js

@@ -0,0 +1,297 @@
+import { terminalDisplayWidth } from "./panel-host.js";
+import { clipTerminal } from "./terminal-text.js";
+import { centerPad, isFirstRun } from "./home-model.js";
+import { actionChipSpansFromRight, actionChipWidth } from "./recipes.js";
+const HEADER_ROWS = 2;
+const FOOTER_ROWS = 2;
+const WELCOME_ROWS = 6;
+const WELCOME_ACTION_ROW = 3;
+const HOME_CHIP_AGENT = "[+ agent] ";
+const HOME_CHIP_SESSION = "[± diff] ";
+const HOME_CHIP_PROJECT = "[▸ launch] ";
+const HOME_CHIP_RECENT = "[▸ open] ";
+export function homeSurfaceVariant(width, height) {
+    if (width >= 160 && height >= 45)
+        return "wide";
+    if (width >= 96 && height >= 30)
+        return "standard";
+    return "compact";
+}
+export function homeContentRows(projection) {
+    return projection.rows.length;
+}
+export function homeWelcomeOffset(projects) {
+    return isFirstRun(projects) ? WELCOME_ROWS : 0;
+}
+export function homeItemIndexAtProjection(projection, globalX, globalY, originX = 0, originY = 0) {
+    const x = globalX - originX;
+    const y = globalY - originY;
+    if (x < 0 || x >= projection.width || y < projection.body.y || y >= projection.footer.y) {
+        return -1;
+    }
+    const row = projection.rows.find((candidate) => y >= candidate.y && y < candidate.y + 1);
+    return row?.itemIndex ?? -1;
+}
+export function homeActionAtProjection(projection, globalX, globalY, originX = 0, originY = 0) {
+    const x = globalX - originX;
+    const y = globalY - originY;
+    if (projection.welcome && y === projection.welcome.action.y) {
+        const a = projection.welcome.action;
+        if (x >= a.x && x < a.x + a.width)
+            return { source: "welcome", id: "open-folder" };
+    }
+    if (y === projection.footerActionY) {
+        const actionIndex = projection.footerActionSpans.findIndex((span) => x >= span.start && x < span.start + span.width);
+        const hit = actionIndex >= 0 ? projection.footerActionSpans[actionIndex] : undefined;
+        return hit ? { source: "footer", id: hit.id, actionIndex } : null;
+    }
+    const row = projection.rows.find((candidate) => y === candidate.y);
+    if (!row)
+        return null;
+    const actionIndex = row.actionSpans.findIndex((span) => x >= span.start && x < span.start + span.width);
+    const action = actionIndex >= 0 ? row.actionSpans[actionIndex] : undefined;
+    return action ? { source: "row", id: action.id, itemIndex: row.itemIndex, actionIndex } : null;
+}
+export function projectHomeSurface(input) {
+    const width = Math.max(0, Math.floor(input.width));
+    const height = Math.max(0, Math.floor(input.height));
+    const variant = homeSurfaceVariant(width, height);
+    const firstRun = isFirstRun(input.projects);
+    const footerHeight = height >= 8 ? FOOTER_ROWS : 1;
+    const headerHeight = Math.min(HEADER_ROWS, height);
+    const footerY = Math.max(headerHeight, height - footerHeight);
+    const body = {
+        x: 0,
+        y: headerHeight,
+        width,
+        height: Math.max(0, footerY - headerHeight),
+    };
+    const title = variant === "compact" ? "Home" : "tmux-ide Home";
+    const subtitle = variant === "compact"
+        ? `${input.rollup.sessions} sessions · ${input.rollup.projects} projects`
+        : "Sessions, registered projects, and recent folders";
+    const stats = [
+        { id: "sessions", label: "sessions", count: input.rollup.sessions },
+        { id: "blocked", label: "blocked", count: input.rollup.blocked },
+        { id: "working", label: "working", count: input.rollup.working },
+        { id: "done", label: "done", count: input.rollup.done },
+        { id: "projects", label: "projects", count: input.rollup.projects },
+    ].filter((stat) => variant !== "compact" || stat.count > 0 || stat.id === "sessions");
+    const welcome = firstRun ? projectWelcome(input, width, body) : null;
+    const rowsStartY = body.y + (welcome ? WELCOME_ROWS : 0);
+    const maxRows = Math.max(0, footerY - rowsStartY);
+    const windowStart = homeWindowStart(input.items, input.selectedIndex, maxRows);
+    const visibleItems = input.items.slice(windowStart, windowStart + maxRows);
+    const rows = visibleItems.map((item, offset) => projectHomeRow({
+        item,
+        itemIndex: windowStart + offset,
+        y: rowsStartY + offset,
+        width,
+        variant,
+        selected: windowStart + offset === input.selectedIndex,
+        hovered: input.hovered,
+        overflowBefore: windowStart,
+        overflowAfter: Math.max(0, input.items.length - (windowStart + visibleItems.length)),
+    }));
+    const footerActionDefs = [
+        {
+            id: "open-folder",
+            label: variant === "compact" ? "[f folder]" : "[f open folder]",
+            description: "Open a folder",
+        },
+        {
+            id: "new-session",
+            label: variant === "compact" ? "[n session]" : "[n new session]",
+            description: "Create a session here",
+        },
+        {
+            id: "new-agent",
+            label: variant === "compact" ? "[a agent]" : "[a new agent]",
+            description: "Start an agent here",
+        },
+        { id: "open-file", label: "[o open]", description: "Open a file by path" },
+        { id: "open-diff", label: "[d diff]", description: "Open selected project diff" },
+    ];
+    const footerActions = footerActionDefs.map((action, index) => ({
+        ...action,
+        hovered: input.hovered?.region === "button" && input.hovered.index === index,
+    }));
+    const footerActionY = footerHeight > 1 ? footerY + 1 : footerY;
+    const footerActionSpans = actionChipSpansFromRight(footerActions, width, 1);
+    const prompt = input.sessionPrompt !== null
+        ? { kind: "session", label: "new session", value: input.sessionPrompt }
+        : input.pathPrompt !== null
+            ? { kind: "path", label: "open file", value: input.pathPrompt }
+            : null;
+    const footerHint = variant === "compact"
+        ? compactFooter(input.footerHint, input.quitHint, width)
+        : clipTerminal(input.footerHint, width);
+    return {
+        width,
+        height,
+        variant,
+        header: { x: 0, y: 0, width, height: headerHeight },
+        body,
+        footer: { x: 0, y: footerY, width, height: footerHeight },
+        firstRun,
+        title,
+        subtitle,
+        stats,
+        welcome,
+        rows,
+        detail: clipTerminal(input.detail, width),
+        prompt,
+        footerHint,
+        footerActions,
+        footerActionY,
+        footerActionSpans,
+    };
+}
+function homeWindowStart(items, selectedIndex, capacity) {
+    if (capacity <= 0 || items.length <= capacity)
+        return 0;
+    const selected = Math.max(0, Math.min(items.length - 1, selectedIndex));
+    if (selected < capacity)
+        return 0;
+    const maxStart = Math.max(0, items.length - capacity);
+    return Math.min(maxStart, selected - capacity + 1);
+}
+function projectWelcome(input, width, body) {
+    const line = clipTerminal(input.welcomeLine, width);
+    const action = clipTerminal(input.welcomeActionLabel, width);
+    const actionWidth = actionChipWidth(action);
+    const actionX = centerPad(width, actionWidth);
+    const hint = clipTerminal(input.welcomeTip, width);
+    return {
+        rows: [
+            { y: body.y + 1, text: line, x: centerPad(width, terminalDisplayWidth(line)), role: "title" },
+            {
+                y: body.y + WELCOME_ACTION_ROW,
+                text: action,
+                x: actionX,
+                role: "action",
+            },
+            {
+                y: body.y + 5,
+                text: hint,
+                x: centerPad(width, terminalDisplayWidth(hint)),
+                role: "hint",
+            },
+        ],
+        action: {
+            id: "open-folder",
+            label: action,
+            x: actionX,
+            y: body.y + WELCOME_ACTION_ROW,
+            width: actionWidth,
+            height: 1,
+            hovered: input.hovered?.region === "welcomeopen",
+        },
+    };
+}
+function projectHomeRow(input) {
+    const { item, itemIndex, width, variant } = input;
+    if (item.kind === "header") {
+        return {
+            id: `section:${item.label}`,
+            role: "section",
+            itemIndex,
+            x: 0,
+            y: input.y,
+            width,
+            height: 1,
+            label: item.label,
+            meta: "",
+            selected: false,
+            hovered: false,
+            disabled: true,
+            attention: false,
+            overflowBefore: input.overflowBefore,
+            overflowAfter: input.overflowAfter,
+            actions: [],
+            actionSpans: [],
+        };
+    }
+    const actions = homeRowActions(item);
+    const hoveredActionId = input.hovered?.index === itemIndex
+        ? input.hovered.region === "homeagentchip"
+            ? "new-agent"
+            : input.hovered.region === "homechip"
+                ? "primary"
+                : null
+        : null;
+    const actionsWithHover = actions.map((action) => ({
+        ...action,
+        hovered: action.id === hoveredActionId,
+    }));
+    const actionSpans = actionChipSpansFromRight(actionsWithHover, width, 0);
+    const role = item.kind;
+    const label = item.kind === "session" ? item.session : item.kind === "project" ? item.name : item.name;
+    return {
+        id: item.kind === "session"
+            ? `session:${item.session}`
+            : item.kind === "project"
+                ? `project:${item.name}`
+                : `recent:${item.dir}`,
+        role,
+        itemIndex,
+        x: 0,
+        y: input.y,
+        width,
+        height: 1,
+        label: clipTerminal(label, labelBudget(width, actions, variant)),
+        meta: homeRowMeta(item, variant),
+        status: item.kind === "session" ? item.status : undefined,
+        selected: input.selected,
+        hovered: input.hovered?.index === itemIndex &&
+            (input.hovered.region === "home" ||
+                input.hovered.region === "homechip" ||
+                input.hovered.region === "homeagentchip"),
+        disabled: false,
+        attention: item.kind === "session" && item.status === "blocked",
+        overflowBefore: input.overflowBefore,
+        overflowAfter: input.overflowAfter,
+        actions: actionsWithHover,
+        actionSpans,
+    };
+}
+function homeRowActions(item) {
+    if (item.kind === "header")
+        return [];
+    const out = [];
+    if (item.kind === "session" || item.kind === "project") {
+        out.push({ id: "new-agent", label: HOME_CHIP_AGENT, description: "Start an agent here" });
+    }
+    if (item.kind === "session") {
+        out.push({ id: "primary", label: HOME_CHIP_SESSION, description: "Open project diff" });
+    }
+    else if (item.kind === "project") {
+        out.push({ id: "primary", label: HOME_CHIP_PROJECT, description: "Launch project" });
+    }
+    else if (item.kind === "recent") {
+        out.push({ id: "primary", label: HOME_CHIP_RECENT, description: "Open recent folder" });
+    }
+    return out;
+}
+function labelBudget(width, actions, variant) {
+    const actionWidth = actions.reduce((sum, action) => sum + actionChipWidth(action.label), 0);
+    const metaReserve = variant === "compact" ? 8 : 20;
+    return Math.max(4, width - actionWidth - metaReserve - 6);
+}
+function homeRowMeta(item, variant) {
+    if (item.kind === "session") {
+        const windows = `${item.windows}w`;
+        return variant === "compact"
+            ? `${windows} · ${item.status}`
+            : `${windows}${item.project === item.session ? "" : ` · ${item.project}`} · ${item.status}`;
+    }
+    if (item.kind === "project")
+        return variant === "compact" ? "registered" : `${item.dir ?? ""}`;
+    return variant === "compact" ? "recent" : item.dir;
+}
+function compactFooter(footerHint, quitHint, width) {
+    const base = `j/k enter · f folder · ${quitHint}`;
+    if (terminalDisplayWidth(base) <= width)
+        return base;
+    return clipTerminal(footerHint, width);
+}

package/packages/daemon/dist/tui/mirror/home-surface.jsx

@@ -0,0 +1,110 @@
+/* @jsxImportSource @opentui/solid */
+import { For, Show } from "solid-js";
+import { rollupChips } from "../team/home.js";
+import { STATUS_GLYPH } from "./status-grammar.js";
+import { ActionChip, EmptyState, SectionHeader, SelectableRow } from "./recipe-components.jsx";
+import { homeActionAtProjection, } from "./home-surface-model.js";
+import { actionChipWidth, recipePalette } from "./recipes.js";
+import { clipTerminal } from "./terminal-text.js";
+export function HomeSurface(props) {
+    return (<box width={props.projection.width} height={props.projection.height} position="relative" backgroundColor={props.theme.colors.background} overflow="hidden">
+      <HomeHeader theme={props.theme} projection={props.projection} rollup={props.rollup}/>
+      <HomeWelcome theme={props.theme} projection={props.projection}/>
+      <For each={props.projection.rows}>
+        {(row) => (<box position="absolute" left={0} top={row.y} width={row.width} height={1}>
+            <Show when={row.role !== "section"} fallback={<SectionHeader theme={props.theme} title={row.label} width={row.width}/>}>
+              <HomeRow theme={props.theme} row={row}/>
+            </Show>
+          </box>)}
+      </For>
+      <box position="absolute" left={0} top={props.projection.footer.y} width={props.projection.width} height={1} paddingLeft={1}>
+        <Show when={props.projection.prompt} fallback={<Show when={props.projection.rows.length > 0 || props.projection.firstRun} fallback={<EmptyState theme={props.theme} title="No projects yet" detail="Open a folder to start." width={props.projection.width}/>}>
+              <text fg={props.theme.colors.accent}>{props.projection.detail}</text>
+            </Show>}>
+          {(prompt) => (<box flexDirection="row" overflow="hidden">
+              <text fg={props.theme.colors.accent}>{`${prompt().label}: `}</text>
+              <text fg={props.theme.colors.foreground}>{`${prompt().value}▏`}</text>
+            </box>)}
+        </Show>
+      </box>
+      <box position="absolute" left={0} top={props.projection.footerActionY} width={props.projection.width} height={1} overflow="hidden">
+        <text fg={props.theme.colors.mutedForeground}>
+          {clipTerminal(` ${props.projection.footerHint}`, props.projection.width)}
+        </text>
+        <For each={props.projection.footerActionSpans}>
+          {(action) => (<box position="absolute" left={action.start} top={0} width={action.width} height={1}>
+              <ActionChip theme={props.theme} label={action.label} width={action.width} disabled={action.disabled} hovered={action.hovered}/>
+            </box>)}
+        </For>
+      </box>
+    </box>);
+}
+function HomeHeader(props) {
+    return (<>
+      <box position="absolute" left={0} top={0} width={props.projection.width} height={1} paddingLeft={1} flexDirection="row" gap={1} overflow="hidden">
+        <text fg={props.theme.colors.accent} attributes={1}>
+          {props.projection.title}
+        </text>
+        <text fg={props.theme.colors.mutedForeground}>{`· ${props.projection.subtitle}`}</text>
+        <For each={rollupChips(props.rollup)}>
+          {(chip) => (<text fg={props.theme.colors.status[chip.status]}>
+              {`${STATUS_GLYPH[chip.status]} ${chip.count}`}
+            </text>)}
+        </For>
+      </box>
+      <box position="absolute" left={0} top={1} width={props.projection.width} height={1} overflow="hidden">
+        <text fg={props.theme.colors.mutedForeground}>
+          {"─".repeat(Math.max(0, props.projection.width))}
+        </text>
+      </box>
+    </>);
+}
+function HomeWelcome(props) {
+    return (<Show when={props.projection.welcome}>
+      {(welcome) => (<For each={welcome().rows}>
+          {(row) => (<box position="absolute" left={row.x} top={row.y} height={1}>
+              <Show when={row.role === "action"} fallback={<text fg={row.role === "hint"
+                        ? props.theme.colors.mutedForeground
+                        : props.theme.colors.foreground}>
+                    {row.text}
+                  </text>}>
+                <ActionChip theme={props.theme} label={row.text} width={welcome().action.width} hovered={welcome().action.hovered}/>
+              </Show>
+            </box>)}
+        </For>)}
+    </Show>);
+}
+function HomeRow(props) {
+    const tone = () => props.row.status === "blocked"
+        ? "blocked"
+        : props.row.status === "working"
+            ? "working"
+            : props.row.status === "done"
+                ? "done"
+                : props.row.status === "idle"
+                    ? "idle"
+                    : props.row.status === "unknown"
+                        ? "unknown"
+                        : props.row.role === "session"
+                            ? "accent"
+                            : "neutral";
+    const palette = () => recipePalette(props.theme, {
+        selected: props.row.selected,
+        hovered: props.row.hovered,
+        attention: props.row.attention,
+        status: props.row.status,
+    }, tone());
+    const labelWidth = () => Math.max(1, props.row.width - actionWidth(props.row));
+    return (<box height={1} flexDirection="row" backgroundColor={palette().background} overflow="hidden">
+      <SelectableRow theme={props.theme} label={props.row.label} meta={props.row.meta} width={labelWidth()} selected={props.row.selected} hovered={props.row.hovered} attention={props.row.attention} status={props.row.status} tone={tone()}/>
+      <For each={props.row.actionSpans}>
+        {(action) => (<box position="absolute" left={action.start} top={0} width={action.width} height={1}>
+            <ActionChip theme={props.theme} label={action.label} width={action.width} disabled={action.disabled} hovered={action.hovered}/>
+          </box>)}
+      </For>
+    </box>);
+}
+function actionWidth(row) {
+    return row.actionSpans.reduce((sum, action) => sum + actionChipWidth(action.label), 0);
+}
+export { homeActionAtProjection };

package/packages/daemon/dist/tui/mirror/host-terminal.js

@@ -0,0 +1,33 @@
+/**
+ * Host-terminal modes owned by the unified app.
+ *
+ * OpenTUI renders each changed row as ANSI runs. With DECAWM (host autowrap)
+ * enabled, a wide/right-edge run can physically wrap into column 1 of the next
+ * row while OpenTUI's shadow records the intended cells. That strands pane text
+ * over the left sidebar until an outer full repaint. The app never relies on
+ * host autowrap—it positions runs absolutely—so disable it for the app's
+ * lifetime and restore it exactly once on every exit path.
+ */
+export const HOST_AUTOWRAP_DISABLE = "\x1b[?7l";
+export const HOST_AUTOWRAP_ENABLE = "\x1b[?7h";
+/**
+ * Disable host autowrap immediately and arm an exit fallback. `restore` is
+ * idempotent and removes the fallback before writing the enable sequence, so a
+ * normal renderer teardown followed by process exit cannot double-write it.
+ *
+ * The caller supplies a synchronous writer: process `exit` listeners cannot
+ * rely on queued/asynchronous stdout writes being flushed.
+ */
+export function installHostAutowrapGuard(write, lifecycle) {
+    let restored = false;
+    const restore = () => {
+        if (restored)
+            return;
+        restored = true;
+        lifecycle.offExit(restore);
+        write(HOST_AUTOWRAP_ENABLE);
+    };
+    write(HOST_AUTOWRAP_DISABLE);
+    lifecycle.onExit(restore);
+    return { restore };
+}

package/packages/daemon/dist/tui/mirror/hosted.js

@@ -0,0 +1,239 @@
+/**
+ * The detachable cockpit (M23.2) — tmux keeps the app itself alive.
+ *
+ * `tmux-ide app --detachable` (alias `--hosted`) doesn't run the app in the
+ * invoking terminal: it ensures an internal `_tmux-ide-app` session exists
+ * running the app full-screen, then attaches the terminal to it. ^q under
+ * hosting DETACHES the client (the app keeps running); re-invocation from any
+ * terminal — including a phone over ssh — reattaches the SAME cockpit with
+ * scroll positions, dialogs, and workspace context intact. Ctrl-Q is bound at
+ * tmux's root input table so it puts away only the client which pressed it.
+ *
+ * These are the PURE pieces of that contract: the entry decision, the tmux
+ * argv builders, and the shell quoting for the host pane's command line. The
+ * io (spawning tmux, resolving bun vs the compiled binary) stays in the CLI;
+ * the app side reads {@link HOSTED_ENV} to keep direct pane-injected Ctrl-Q
+ * from destroying the resident renderer.
+ */
+/** The internal host session. `_`-prefixed so every fleet surface (team --json,
+ *  sidebar, home) and the snapshot/restore path already filter it out. */
+export const APP_HOST_SESSION = "_tmux-ide-app";
+/** The env marker the launcher sets on the hosted app process. The app consumes
+ *  renderer-delivered Ctrl-Q when it sees `=1`; real client Ctrl-Q is handled
+ *  by tmux before reaching the pane. The CLI also uses it as a recursion guard. */
+export const HOSTED_ENV = "TMUX_IDE_HOSTED";
+/** Hosted put-away is a tmux client action, never a renderer action. */
+export const HOSTED_PUT_AWAY_KEY = "C-q";
+/**
+ * PURE — should this `tmux-ide app` invocation run hosted? Flags and config
+ * both opt in; the env marker vetoes everything (the app inside the host
+ * session must launch plain, or it would try to attach to itself).
+ */
+export function wantsHostedApp(input) {
+    if (input.hostedEnv)
+        return false;
+    return input.flagDetachable || input.flagHosted || input.configDetachable;
+}
+/**
+ * PURE — POSIX single-quote a word for a tmux `new-session` shell command
+ * (tmux hands the string to `sh -c`). Single quotes pass everything literally;
+ * an embedded `'` closes, escapes, and reopens.
+ */
+export function shellQuote(word) {
+    return `'${word.replaceAll("'", `'\\''`)}'`;
+}
+/**
+ * PURE — the env vars the host pane's app process needs, assembled for the
+ * command line rather than tmux's session environment: the tmux server may
+ * have been started elsewhere with a different environment, so nothing can be
+ * assumed to inherit. PATH rides along for the same reason (the `bun` launch
+ * mode resolves the binary by name).
+ */
+export function hostedEnvVars(base) {
+    const env = {
+        [HOSTED_ENV]: "1",
+        TMUX_IDE_CWD: base.cwd,
+        TMUX_IDE_CLI: base.cli,
+        COLORTERM: "truecolor",
+    };
+    if (base.path)
+        env.PATH = base.path;
+    if (base.home)
+        env.TMUX_IDE_HOME = base.home;
+    if (base.config)
+        env.TMUX_IDE_CONFIG = base.config;
+    if (base.tuiBin)
+        env.TMUX_IDE_TUI_BIN = base.tuiBin;
+    return env;
+}
+/**
+ * PURE — the shell command the host pane runs: `exec env K=V… bin args…`,
+ * every value quoted. `exec` replaces the pane's shell with the app so a quit
+ * (the palette verb) ends the pane — and with it the single-window session.
+ */
+export function hostedCommandLine(bin, argv, env) {
+    const assigns = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`);
+    return [
+        "exec",
+        "env",
+        "-u",
+        "NO_COLOR",
+        ...assigns,
+        shellQuote(bin),
+        ...argv.map(shellQuote),
+    ].join(" ");
+}
+/** PURE — exact-match existence probe (`=` prefix: `has-session -t` would
+ *  otherwise PREFIX-match, e.g. a user session named `_tmux-ide-app-notes`). */
+export function hostExistsArgv() {
+    return ["has-session", "-t", `=${APP_HOST_SESSION}`];
+}
+/** PURE — create the detached host session running the app command line. */
+export function hostCreateArgv(opts) {
+    return ["new-session", "-d", "-s", APP_HOST_SESSION, "-c", opts.cwd, opts.commandLine];
+}
+/**
+ * The client events that re-assert `window-size latest` on the host (M25.5).
+ * Each hook's effect was MEASURED on tmux 3.7b in an isolated two-client rig
+ * (220x60 local + 120x40 ssh-sim):
+ *
+ * - `client-attached` / `client-focus-in` / `client-session-changed`: tmux
+ *   3.7b already re-adopts the event client's size natively on all of these
+ *   (attach ~8ms, focus-in ~17ms, switch-client ~17ms — window-resized hook
+ *   timestamps; detach of the latest client also re-adopts natively, ~13ms).
+ *   The hooks are NOT what makes those paths work; they are the SELF-HEAL for
+ *   the one measured way the host gets permanently stuck: any `resize-window`
+ *   against it (a stray tool or user command) flips `window-size` to manual —
+ *   after which NO client event re-adopts, ever (measured: a fresh 220x60
+ *   attach left a manually-80x24 host at 80x24). Re-asserting the option is
+ *   the heal (measured: instant re-adopt) — and it is safe to fire
+ *   redundantly: setting `window-size latest` when it is already latest just
+ *   recomputes the same size. Fire counts are bounded and linear (measured:
+ *   10 rapid focus alternations → exactly 20 focus-in fires; 10 attach cycles
+ *   → 10 attached + 10 session-changed fires — attach fires both — each a
+ *   single in-server set-option, no storm).
+ *
+ * NO `client-detached` hook: measured on 3.7b it never fires as a SESSION
+ * hook (the detaching client has already left the session when hooks are
+ * resolved — 0 fires across 10 detach cycles while the same rig's global
+ * hook logged every one), and the native detach re-adopt covers the path.
+ *
+ * Deliberately NOT `resize-window -a`: per the tmux manual, EVERY
+ * resize-window form — -a included — "will automatically set window-size to
+ * manual", i.e. it would cause the exact stuck state it is meant to fix. And
+ * no `run-shell`: these are tmux-native commands executed in-server
+ * (run-shell hooks serialize the server — prior measurement).
+ */
+export const HOST_RESIZE_HOOKS = [
+    "client-attached",
+    "client-focus-in",
+    "client-session-changed",
+];
+/**
+ * PURE — the post-create/ensure session setup: status OFF so the app owns
+ * every row (under `status on` the host steals the bottom row and the app
+ * renders one short), and `window-size latest` pinned explicitly so the most
+ * recently active client dictates the size — a smaller second client
+ * letterboxes the larger one (tmux's own dot-fill), which is the documented
+ * behavior.
+ *
+ * M25.5 additions (each measured on 3.7b — see {@link HOST_RESIZE_HOOKS}):
+ *
+ * - `focus-events on` (server option — the ONE non-session-scoped line, and
+ *   the load-bearing one): it defaults OFF, so real terminals are never asked
+ *   for focus reporting and `client-focus-in` never fires. With it on, coming
+ *   BACK to a terminal that stayed attached re-adopts that client's size on
+ *   the focus event alone (measured: focus-in → client-active →
+ *   window-resized in ~17ms) — no keystroke needed. This is the user's exact
+ *   "reopen it on my computer locally" moment when the local client never
+ *   detached. Side effect is the widely-recommended one (panes that request
+ *   focus, e.g. editors, start receiving it).
+ * - the {@link HOST_RESIZE_HOOKS} self-heal hooks, session-scoped to the host
+ *   (zero effect on user sessions).
+ *
+ * The whole list is idempotent — the CLI applies it on EVERY ensure, not just
+ * create, so upgrading tmux-ide fixes an already-running cockpit on its next
+ * `tmux-ide app` (and un-sticks a manually-resized host).
+ *
+ * No `=` exact-match prefix here: tmux (measured on 3.7b) rejects it on
+ * `set-option` session targets ("no such session") even though has-session
+ * and attach accept it. Plain names are safe in THIS builder only because
+ * setup runs right after the exists-probe/create — the exact session exists,
+ * and tmux prefers an exact match over a prefix match when one does.
+ */
+export function hostSetupArgvs() {
+    const heal = `set-option -w -t ${APP_HOST_SESSION}: window-size latest`;
+    return [
+        ["set-option", "-t", APP_HOST_SESSION, "status", "off"],
+        ["set-option", "-w", "-t", `${APP_HOST_SESSION}:`, "window-size", "latest"],
+        ["set-option", "-s", "focus-events", "on"],
+        ...HOST_RESIZE_HOOKS.map((hook) => ["set-hook", "-t", APP_HOST_SESSION, hook, heal]),
+    ];
+}
+/**
+ * PURE — how the invoking terminal reaches the cockpit: inside tmux the
+ * client is already attached to a server, so `switch-client` moves it (a
+ * nested `attach` would complain and double-render); a plain terminal
+ * attaches. Both exact-match the host name.
+ */
+export function hostAttachArgv(insideTmux) {
+    return insideTmux
+        ? ["switch-client", "-t", `=${APP_HOST_SESSION}`]
+        : ["attach-session", "-t", `=${APP_HOST_SESSION}`];
+}
+/**
+ * tmux 3.0 (the supported floor) cannot query one binding or format
+ * `list-keys`, so inspect the bounded root-table listing in-process.
+ */
+export function hostRootBindingsArgv() {
+    return ["list-keys", "-T", "root"];
+}
+/**
+ * Install Ctrl-Q at tmux's input boundary. A bound `detach-client` and
+ * `switch-client` execute with the key's exact client as their current client;
+ * a command launched by the shared renderer pane does not have that identity.
+ *
+ * The outer session guard preserves ordinary Ctrl-Q input everywhere else.
+ * A client which switched into the host returns to its own prior session; a
+ * plain attachment, which has no prior session, detaches only itself.
+ */
+export function hostPutAwayBindingArgv() {
+    return [
+        "bind-key",
+        "-T",
+        "root",
+        HOSTED_PUT_AWAY_KEY,
+        "if-shell",
+        "-F",
+        `#{==:#{session_name},${APP_HOST_SESSION}}`,
+        "if-shell -F '#{client_last_session}' 'switch-client -l' 'detach-client'",
+        `send-keys ${HOSTED_PUT_AWAY_KEY}`,
+    ];
+}
+const HOSTED_PUT_AWAY_LISTING_COMMAND = `if-shell -F "#{==:#{session_name},${APP_HOST_SESSION}}" ` +
+    `"if-shell -F '#{client_last_session}' 'switch-client -l' 'detach-client'" ` +
+    `"send-keys ${HOSTED_PUT_AWAY_KEY}"`;
+function rootCtrlQBindingCommands(rootBindings) {
+    if (typeof rootBindings !== "string" ||
+        rootBindings.includes("\0") ||
+        Buffer.byteLength(rootBindings, "utf8") > 1024 * 1024) {
+        return ["invalid-root-binding-list"];
+    }
+    return rootBindings
+        .split(/\r?\n/u)
+        .map((line) => line.match(/^\s*bind-key\s+-T\s+root\s+C-q\s+(?<command>.+?)\s*$/u)?.groups?.command)
+        .filter((command) => command !== undefined);
+}
+/**
+ * Classify the existing root Ctrl-Q binding without evaluating or embedding a
+ * user-authored tmux command. Anything other than our exact canonical shape is
+ * a conflict and must remain untouched.
+ */
+export function hostedPutAwayBindingState(rootBindings) {
+    const matches = rootCtrlQBindingCommands(rootBindings);
+    if (matches.length === 0)
+        return "absent";
+    if (matches.length !== 1)
+        return "conflict";
+    return matches[0] === HOSTED_PUT_AWAY_LISTING_COMMAND ? "owned" : "conflict";
+}