tmux-ide 2.9.0-beta.21 → 2.9.0-beta.26

package/packages/daemon/src/tui/mirror/runtime/application-terminal-workspace.tsx

@@ -1,3 +1,6 @@
+import { Menu } from "../ui/index.ts";
+import type { WindowLinkTarget } from "@tmux-ide/contracts";
+import { windowLinkTarget } from "./application-terminal-workspace-policy.ts";
 import type { PaneInteractionProjection } from "@tmux-ide/core";
 /* @jsxImportSource @opentui/solid */
 import {
@@ -61,7 +64,6 @@ import {
   type TerminalSelectionRange,
 } from "./terminal-selection.ts";
 import {
-  retainedTerminalWindowKey,
   terminalAgentStatusLabel,
   terminalPaneDisplayTitle,
   terminalPaneResizePreview,
@@ -168,6 +170,8 @@ export interface ApplicationTerminalWorkspaceProps {
   /** Daemon-authored semantic agent state, keyed by durable pane identity. */
   readonly agentIndicators?: Accessor<ReadonlyMap<string, ApplicationTerminalAgentIndicator>>;
   readonly onSelectPane: (paneId: string) => void;
+  readonly onSelectWindowLink?: (target: WindowLinkTarget) => void;
+  readonly onUnlinkWindowLink?: (target: WindowLinkTarget) => void;
   readonly onCreateWindow?: () => void;
   readonly onPaneContextAction?: (
     paneId: string,
@@ -332,37 +336,56 @@ export function ApplicationTerminalWorkspace(props: ApplicationTerminalWorkspace
     ),
   );
   const visibleFrames = createMemo(() => projectedFrames().filter((frame) => frame.visible));
-  const retainedWindowIds = createMemo(
-    () =>
-      Object.freeze(
-        layout()
-          .windows.map(retainedTerminalWindowKey)
-          .filter((id): id is string => id !== null),
-      ),
-    undefined,
-    {
-      equals: (previous, next) =>
-        previous.length === next.length && previous.every((id, index) => id === next[index]),
-    },
-  );
-  const terminalWindowTabs = createMemo<readonly TerminalWindowTab[]>(() =>
-    retainedWindowIds().map((windowId, index) => {
-      const window = layout().windows.find(
-        (candidate) => retainedTerminalWindowKey(candidate) === windowId,
-      )!;
-      const indicator = terminalWindowAgentIndicator(window, agentIndicators());
-      return {
+  const [windowLinkMenu, setWindowLinkMenu] = createSignal<WindowLinkTarget | null>(null);
+  const unlinkWindowTab = () => {
+    const target = windowLinkMenu();
+    setWindowLinkMenu(null);
+    if (target) props.onUnlinkWindowLink?.(target);
+  };
+  createEffect(() => {
+    const target = windowLinkMenu();
+    const observed = target && windowLinkTarget(layout(), target.linkId);
+    if (
+      target &&
+      (!observed ||
+        observed.liveSessionId !== target.liveSessionId ||
+        observed.linkRevision !== target.linkRevision)
+    )
+      setWindowLinkMenu(null);
+  });
+  const terminalWindowTabs = createMemo<readonly TerminalWindowTab[]>(() => {
+    const snapshot = layout();
+    if (!snapshot.windowLinks)
+      return snapshot.windows.map((window, index) => ({
         index,
         name: terminalWindowTitle(window),
         active: window.currentWindow,
         sync: false,
         semanticWindowId: window.semanticWindowId,
         activePaneId: terminalWindowPane(window),
-        status: indicator ? terminalAgentStatusLabel(indicator.activity) : undefined,
-        attention: indicator?.attention,
-      };
-    }),
-  );
+        disabled: true,
+      }));
+    return snapshot.windowLinks.links.flatMap((link) => {
+      const window = snapshot.windows.find(
+        (candidate) => candidate.semanticWindowId === link.semanticWindowId,
+      );
+      if (!window) return [];
+      const indicator = terminalWindowAgentIndicator(window, agentIndicators());
+      return [
+        {
+          linkId: link.linkId,
+          index: link.displayIndex,
+          name: terminalWindowTitle(window),
+          active: snapshot.windowLinks?.activeLinkId === link.linkId,
+          sync: false,
+          semanticWindowId: window.semanticWindowId,
+          activePaneId: terminalWindowPane(window),
+          status: indicator ? terminalAgentStatusLabel(indicator.activity) : undefined,
+          attention: indicator?.attention,
+        },
+      ];
+    });
+  });
   if (props.onWindowPresented)
     createRenderEffect(() => {
       const current = layout().current;
@@ -911,6 +934,12 @@ export function ApplicationTerminalWorkspace(props: ApplicationTerminalWorkspace
   props.onSelectionCopyOwner?.(copySelection);
   const handlePaneMenuKey: PaneMenuKeyHandler = (name, event) => {
     if (props.interactive === false) return false;
+    if (windowLinkMenu()) {
+      if (event?.eventType === "release") return true;
+      if (name === "escape") setWindowLinkMenu(null);
+      else if (name === "return" || name === "enter" || name === "u") unlinkWindowTab();
+      return true;
+    }
     if (paneMenu.handleKey(name, event)) return true;
     const focused = props.focusedPane;
     const keyboard = keyboardCopy();
@@ -1097,7 +1126,10 @@ export function ApplicationTerminalWorkspace(props: ApplicationTerminalWorkspace
     },
     () =>
       props.interactive !== false &&
-      (drag !== null || paneMenu.ownsInput() || keyboardCopy() !== null),
+      (drag !== null ||
+        windowLinkMenu() !== null ||
+        paneMenu.ownsInput() ||
+        keyboardCopy() !== null),
     () => {
       // Called only after global shortcuts, copy, and local navigation decline
       // the event, immediately before terminal key or paste delivery.
@@ -1116,7 +1148,7 @@ export function ApplicationTerminalWorkspace(props: ApplicationTerminalWorkspace
   // listener and the typed listener on a target, even after stopPropagation.
   const routePointer = (event: WorkspaceMouseEvent): void => {
     if (event.type === "down") wheelGesture.reset();
-    if (paneMenu.ownsInput()) {
+    if (windowLinkMenu() || paneMenu.ownsInput()) {
       event.stopPropagation?.();
       return;
     }
@@ -1649,9 +1681,18 @@ export function ApplicationTerminalWorkspace(props: ApplicationTerminalWorkspace
             tabs={terminalWindowTabs}
             hoveredIndex={null}
             onActivate={(index) => {
-              const pane = terminalWindowTabs()[index]?.activePaneId;
-              if (pane) props.onSelectPane(pane);
+              const tab = terminalWindowTabs().find((candidate) => candidate.index === index);
+              const target = tab?.linkId ? windowLinkTarget(layout(), tab.linkId) : null;
+              if (target) props.onSelectWindowLink?.(target);
             }}
+            onWindowActions={
+              props.onUnlinkWindowLink
+                ? (index) => {
+                    const tab = terminalWindowTabs().find((candidate) => candidate.index === index);
+                    if (tab?.linkId) setWindowLinkMenu(windowLinkTarget(layout(), tab.linkId));
+                  }
+                : undefined
+            }
             onNewWindow={() => props.onCreateWindow?.()}
           />
         </Show>
@@ -1805,6 +1846,22 @@ export function ApplicationTerminalWorkspace(props: ApplicationTerminalWorkspace
           </box>
         )}
       </For>
+      <Show when={windowLinkMenu()}>
+        <Menu
+          theme={props.theme}
+          title="Window link"
+          left={0}
+          top={1}
+          width={Math.min(36, props.width)}
+          viewportWidth={props.width}
+          viewportHeight={props.height}
+          selectedId="unlink"
+          items={[{ id: "unlink", label: "Unlink this tab", shortcut: "U" }]}
+          footer="Other links keep their panes"
+          onDismiss={() => setWindowLinkMenu(null)}
+          onSelect={unlinkWindowTab}
+        />
+      </Show>
       <Show when={paneContextMenu()}>
         {(menu) => (
           <PaneActionMenu

package/packages/daemon/src/tui/mirror/runtime/application-theme-repaint.ts

@@ -1,3 +1,5 @@
+import { createEffect } from "solid-js";
+import type { ApplicationAppearanceOwner } from "./application-appearance-owner.ts";
 import type { createCliRenderer } from "@opentui/core";
 import type { SemanticThemeSnapshot } from "../theme.ts";
 
@@ -43,3 +45,20 @@ export function applyApplicationAppearanceToRenderer(
     requestApplicationThemeRepaint(renderer);
   return generation;
 }
+
+/** Bind the complete appearance publication to one renderer transaction. */
+export function createApplicationAppearanceRendererBinding(
+  renderer: Renderer,
+  appearance: Pick<ApplicationAppearanceOwner, "appearance">,
+): void {
+  let paintedGeneration: number | null = null;
+  createEffect(() => {
+    const next = appearance.appearance();
+    paintedGeneration = applyApplicationAppearanceToRenderer(
+      renderer,
+      next.theme,
+      next.generation,
+      paintedGeneration,
+    );
+  });
+}

package/packages/daemon/src/tui/mirror/runtime/fleet-lifecycle-client.ts

@@ -1,3 +1,5 @@
+import { createTmuxServerClient } from "@tmux-ide/daemon-client/tmux-server-client";
+import type { TmuxServerScope } from "@tmux-ide/contracts";
 import type { ApplicationMachineAuthorityHandle } from "./application-machine-authority.ts";
 import type { ActionResult, WorkspaceSessionKillArguments } from "@tmux-ide/contracts";
 import {
@@ -52,6 +54,7 @@ async function dispatch<
 
 type FleetHandle = Pick<ApplicationMachineAuthorityHandle, "read" | "endpoint">;
 export interface FleetSessionCloseTarget {
+  readonly server?: TmuxServerScope;
   readonly daemonInstanceId: string;
   readonly liveSessionId: string;
   readonly sessionName: string;
@@ -91,12 +94,36 @@ async function dispatchOnHandle<Name extends "workspace.session.create" | "works
 export function createFleetSession(
   input: WorkspaceSessionCreateArguments | FleetHandle,
   name?: string,
+  server?: TmuxServerScope,
+  options?: Pick<WorkspaceSessionCreateArguments, "includeLiveSessionId">,
 ): Promise<WorkspaceSessionCreateResult | null> {
   if ("read" in input) {
     const daemon = input.read();
     if (!daemon || !name) return Promise.resolve(null);
+    if (server) {
+      if (!daemon.authToken || input.endpoint().state !== "ready") return Promise.resolve(null);
+      const epoch = input.endpoint().epoch;
+      const baseUrl = canonicalDaemonUrl("http", daemon.bindHostname, daemon.port);
+      const client = createTmuxServerClient(
+        { baseUrl, ownerToken: daemon.authToken, hostClientId: HOST_CLIENT_ID, origin: baseUrl },
+        server,
+      );
+      return client
+        .createSession(randomUUID(), {
+          displayName: name,
+          ...(options?.includeLiveSessionId ? { includeLiveSessionId: true } : {}),
+          expectedDaemonInstanceId: server.generation,
+        })
+        .then((result) =>
+          input.endpoint().epoch === epoch && input.read()?.instanceId === daemon.instanceId
+            ? result
+            : null,
+        )
+        .finally(() => client.dispose());
+    }
     return dispatchOnHandle(input, "workspace.session.create", {
       displayName: name,
+      ...(options?.includeLiveSessionId ? { includeLiveSessionId: true } : {}),
       expectedDaemonInstanceId: daemon.instanceId,
     });
   }
@@ -109,6 +136,34 @@ export function closeFleetSession(
   target: FleetSessionCloseTarget,
 ): Promise<ActionResult<"workspace.session.kill"> | null> {
   if (handle.read()?.instanceId !== target.daemonInstanceId) return Promise.resolve(null);
+  if (target.server) {
+    const daemon = handle.read();
+    if (!daemon?.authToken || handle.endpoint().state !== "ready") return Promise.resolve(null);
+    const epoch = handle.endpoint().epoch;
+    const baseUrl = canonicalDaemonUrl("http", daemon.bindHostname, daemon.port);
+    const client = createTmuxServerClient(
+      { baseUrl, ownerToken: daemon.authToken, hostClientId: HOST_CLIENT_ID, origin: baseUrl },
+      target.server,
+    );
+    return client
+      .mutate(randomUUID(), {
+        verb: "workspace.session.kill",
+        workspaceName: target.workspaceName ?? target.sessionName,
+        fleetTarget: {
+          daemonInstanceId: target.server.generation,
+          liveSessionId: target.liveSessionId,
+          sessionName: target.sessionName,
+        },
+      })
+      .then((result) =>
+        handle.endpoint().epoch === epoch &&
+        handle.read()?.instanceId === target.daemonInstanceId &&
+        result.verb === "workspace.session.kill"
+          ? result
+          : null,
+      )
+      .finally(() => client.dispose());
+  }
   return dispatchOnHandle(handle, "workspace.session.kill", {
     workspaceName: target.workspaceName ?? target.sessionName,
     fleetTarget: {

package/packages/daemon/src/tui/mirror/runtime/guided-tour-coach.tsx

@@ -0,0 +1,118 @@
+/* @jsxImportSource @opentui/solid */
+import { Show } from "solid-js";
+import type { SemanticThemeSnapshot } from "../theme.ts";
+import { TuiButton } from "../ui/button.tsx";
+import { clipTerminal } from "../terminal-text.ts";
+import {
+  GUIDED_TOUR_STEPS,
+  guidedTourCopy,
+  type GuidedTourState,
+  type GuidedTourShortcuts,
+} from "./guided-tour.ts";
+
+export interface GuidedTourCoachProps {
+  readonly state: GuidedTourState;
+  readonly theme: SemanticThemeSnapshot;
+  readonly width: number;
+  readonly height?: number;
+  readonly shortcuts?: GuidedTourShortcuts;
+  readonly error?: string | null;
+  readonly busy?: boolean;
+  readonly onReplay?: () => void;
+  readonly onPause: () => void;
+  readonly onWelcomeRead: () => void;
+  readonly onCreatePractice: () => void;
+  readonly onOpenCommands: () => void;
+  readonly onOpenAppearance: () => void;
+  readonly onOpenHome: () => void;
+  readonly onOpenPractice: () => void;
+}
+/** Non-modal coach: terminal interaction stays available throughout the tour. */
+export function GuidedTourCoach(props: GuidedTourCoachProps) {
+  const copy = () => guidedTourCopy(props.state.step, props.shortcuts);
+  const width = () => Math.max(1, props.width);
+  const primary = () => {
+    switch (props.state.step) {
+      case "welcome":
+        return { label: "Let's try it", run: props.onWelcomeRead };
+      case "practice":
+        return { label: "Create practice session", run: props.onCreatePractice };
+      case "split":
+      case "commands":
+        return { label: "Open commands", run: props.onOpenCommands };
+      case "theme":
+        return { label: "Choose theme", run: props.onOpenAppearance };
+      case "leave":
+        return { label: "Open Home", run: props.onOpenHome };
+      case "reopen":
+        return { label: "Reopen practice", run: props.onOpenPractice };
+      default:
+        return null;
+    }
+  };
+  return (
+    <box
+      id="guided-tour-coach"
+      width={width()}
+      height={props.height ?? 10}
+      overflow="hidden"
+      flexShrink={0}
+      flexDirection="column"
+      paddingX={1}
+      backgroundColor={props.theme.roles.surfaces.panel}
+    >
+      <text height={1} fg={props.theme.roles.text.primary}>
+        <strong>
+          {clipTerminal(
+            `Learn tmux-ide · ${GUIDED_TOUR_STEPS.indexOf(props.state.step) + 1}/${GUIDED_TOUR_STEPS.length} · ${copy().title}`,
+            Math.max(0, width() - 2),
+          )}
+        </strong>
+      </text>
+      <scrollbox flexGrow={1} width="100%">
+        <text fg={props.theme.roles.text.secondary}>{copy().body}</text>
+      </scrollbox>
+      <Show when={props.error}>
+        <text fg={props.theme.roles.text.primary}>{props.error}</text>
+      </Show>
+      <box flexDirection="row" flexWrap="wrap" flexShrink={0} gap={1}>
+        <Show
+          when={props.state.practice && ["split", "focus", "resize"].includes(props.state.step)}
+        >
+          <TuiButton
+            theme={props.theme}
+            label="Open practice"
+            onPress={props.onOpenPractice}
+            width={Math.min(Math.max(1, width() - 2), 17)}
+          />
+        </Show>
+        <Show when={props.onReplay && props.error}>
+          <TuiButton
+            theme={props.theme}
+            label="Restart tour"
+            onPress={props.onReplay}
+            width={Math.min(Math.max(1, width() - 2), 16)}
+          />
+        </Show>
+        <Show when={primary()}>
+          {(action) => (
+            <TuiButton
+              theme={props.theme}
+              label={action().label}
+              width={Math.min(Math.max(1, width() - 2), action().label.length + 4)}
+              loading={props.busy}
+              onPress={action().run}
+            />
+          )}
+        </Show>
+        <TuiButton
+          theme={props.theme}
+          label={props.state.step === "complete" ? "Done" : "Pause tour"}
+          width={Math.min(Math.max(1, width() - 2), 14)}
+          variant="ghost"
+          onPress={props.onPause}
+        />
+      </box>
+    </box>
+  );
+}

package/packages/daemon/src/tui/mirror/runtime/guided-tour-storage.ts

@@ -0,0 +1,72 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { runtimeOwnedPath } from "../../../lib/runtime-namespace.ts";
+import { stateHome } from "../../../lib/state-home.ts";
+import { GUIDED_TOUR_STEPS, initialGuidedTourState, type GuidedTourState } from "./guided-tour.ts";
+
+export function guidedTourStatePath(): string {
+  return runtimeOwnedPath(join(stateHome(), "guided-tour.json"));
+}
+export function parseGuidedTourState(value: unknown): GuidedTourState {
+  if (!value || typeof value !== "object") return initialGuidedTourState();
+  const raw = value as Record<string, unknown>;
+  if (
+    raw.version !== 1 ||
+    !GUIDED_TOUR_STEPS.includes(raw.step as GuidedTourState["step"]) ||
+    typeof raw.active !== "boolean"
+  )
+    return initialGuidedTourState();
+  let practice: GuidedTourState["practice"] = null;
+  if (raw.practice && typeof raw.practice === "object") {
+    const p = raw.practice as Record<string, unknown>;
+    if (
+      [p.machineId, p.serverId, p.generation, p.sessionId, p.sessionName].every(
+        (v) => typeof v === "string" && v.length > 0,
+      )
+    ) {
+      practice = {
+        machineId: p.machineId as string,
+        serverId: p.serverId as string,
+        generation: p.generation as string,
+        sessionId: p.sessionId as string,
+        sessionName: p.sessionName as string,
+      };
+    }
+  }
+  const step = raw.step as GuidedTourState["step"];
+  return {
+    version: 1,
+    step: !practice && !["welcome", "practice", "complete"].includes(step) ? "practice" : step,
+    active: raw.active,
+    practice,
+  };
+}
+export function readGuidedTourState(path = guidedTourStatePath()): GuidedTourState {
+  try {
+    return parseGuidedTourState(JSON.parse(readFileSync(path, "utf8")));
+  } catch {
+    return initialGuidedTourState();
+  }
+}
+/** Atomic, best-effort persistence; failure must not prevent using terminals. */
+export function writeGuidedTourState(
+  state: GuidedTourState,
+  path = guidedTourStatePath(),
+): boolean {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(temporary, JSON.stringify(state), { mode: 0o600 });
+    renameSync(temporary, path);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    try {
+      rmSync(temporary, { force: true });
+    } catch {
+      /* Best effort. */
+    }
+  }
+}

package/packages/daemon/src/tui/mirror/runtime/guided-tour.ts

@@ -0,0 +1,147 @@
+/** A small, action-driven tour. No timers and no mutations of terminal sessions. */
+export const GUIDED_TOUR_STEPS = [
+  "welcome",
+  "practice",
+  "split",
+  "focus",
+  "resize",
+  "commands",
+  "theme",
+  "leave",
+  "reopen",
+  "complete",
+] as const;
+export type GuidedTourStep = (typeof GUIDED_TOUR_STEPS)[number];
+export interface GuidedTourPractice {
+  readonly machineId: string;
+  readonly serverId: string;
+  readonly generation: string;
+  readonly sessionId: string;
+  readonly sessionName: string;
+}
+export interface GuidedTourState {
+  readonly version: 1;
+  readonly step: GuidedTourStep;
+  readonly active: boolean;
+  readonly practice: GuidedTourPractice | null;
+}
+export type GuidedTourEvent =
+  | { readonly type: "start" | "pause" | "resume" | "replay" | "welcome-read" }
+  | { readonly type: "practice-created"; readonly practice: GuidedTourPractice }
+  | { readonly type: "practice-missing" }
+  | {
+      readonly type: "split-confirmed" | "focus-confirmed" | "resize-confirmed" | "reopened";
+      readonly practice: GuidedTourPractice;
+    }
+  | { readonly type: "commands-opened" | "theme-changed" | "home-opened" };
+
+export function initialGuidedTourState(): GuidedTourState {
+  return { version: 1, step: "welcome", active: false, practice: null };
+}
+export function sameGuidedTourPractice(
+  a: GuidedTourPractice | null,
+  b: GuidedTourPractice,
+): boolean {
+  return (
+    a !== null &&
+    a.machineId === b.machineId &&
+    a.serverId === b.serverId &&
+    a.generation === b.generation &&
+    a.sessionId === b.sessionId
+  );
+}
+/** Call confirmation events only after an observed change, never on request dispatch. */
+export function reduceGuidedTour(state: GuidedTourState, event: GuidedTourEvent): GuidedTourState {
+  if (event.type === "replay") return { ...initialGuidedTourState(), active: true };
+  if (event.type === "pause") return state.active ? { ...state, active: false } : state;
+  if (event.type === "start" || event.type === "resume") {
+    return state.step === "complete" ? state : { ...state, active: true };
+  }
+  if (event.type === "practice-created" && state.step === "practice") {
+    return { ...state, step: "split", practice: event.practice };
+  }
+  if (!state.active) return state;
+  if (event.type === "practice-missing" && state.practice && state.step !== "complete") {
+    return { ...state, step: "practice", practice: null };
+  }
+  if (event.type === "welcome-read" && state.step === "welcome")
+    return { ...state, step: "practice" };
+  if ("practice" in event && !sameGuidedTourPractice(state.practice, event.practice)) return state;
+  const expected: Partial<Record<GuidedTourStep, GuidedTourEvent["type"]>> = {
+    split: "split-confirmed",
+    focus: "focus-confirmed",
+    resize: "resize-confirmed",
+    commands: "commands-opened",
+    theme: "theme-changed",
+    leave: "home-opened",
+    reopen: "reopened",
+  };
+  if (expected[state.step] !== event.type) return state;
+  const step = GUIDED_TOUR_STEPS[GUIDED_TOUR_STEPS.indexOf(state.step) + 1]!;
+  return { ...state, step };
+}
+
+export interface GuidedTourShortcuts {
+  readonly commands?: string;
+  readonly home?: string;
+  readonly split?: string;
+  readonly focus?: string;
+}
+export function guidedTourCopy(
+  step: GuidedTourStep,
+  keys: GuidedTourShortcuts = {},
+): { title: string; body: string } {
+  const shortcut = (key: string | undefined) => (key ? ` (${key})` : "");
+  switch (step) {
+    case "welcome":
+      return {
+        title: "Meet tmux-ide",
+        body: "A machine can run several tmux servers. Each server has sessions; sessions contain windows, and windows contain terminal panes. Home brings agents across connected machines together.",
+      };
+    case "practice":
+      return {
+        title: "Your practice space",
+        body: "Create a separate local practice session. The tour leaves your existing sessions alone. You can pause now and resume from Home.",
+      };
+    case "split":
+      return {
+        title: "Make room",
+        body: `Split the practice pane${shortcut(keys.split)}. You can also find Split right in Commands${shortcut(keys.commands)}. The next step unlocks when the new pane appears.`,
+      };
+    case "focus":
+      return {
+        title: "Move between panes",
+        body: `Select the other practice pane by clicking it or using your pane navigation shortcut${shortcut(keys.focus)}. Each pane is an independent terminal.`,
+      };
+    case "resize":
+      return {
+        title: "Find a comfortable layout",
+        body: "Drag the divider between the practice panes. Continue working while tmux updates the layout; the tour advances after the changed dimensions arrive.",
+      };
+    case "commands":
+      return {
+        title: "Find an action",
+        body: `Open Commands${shortcut(keys.commands)} to discover actions and their current shortcuts. Close the palette when you are ready to continue.`,
+      };
+    case "theme":
+      return {
+        title: "Make it yours",
+        body: "Choose a different theme from Home. Automatic contrast correction improves hard-to-read terminal colors; you can turn it off in settings.",
+      };
+    case "leave":
+      return {
+        title: "Leave without losing work",
+        body: `Open Home${shortcut(keys.home)}. Your practice terminals keep running in tmux while you look at agents or other sessions.`,
+      };
+    case "reopen":
+      return {
+        title: "Pick up where you left off",
+        body: "Reopen your practice session. tmux keeps your terminals alive independently of which page or session you are viewing.",
+      };
+    case "complete":
+      return {
+        title: "Ready to explore",
+        body: "You have split, focused and resized panes, found commands, changed theme and returned to a running session. Your practice session remains available; close it when you are finished. Replay this tour from Home.",
+      };
+  }
+}

package/packages/daemon/src/tui/mirror/runtime/open-tui-generation-host.ts

@@ -316,7 +316,7 @@ function buildProductionBundle(
       requestTerminalRuntimeInventoryRefresh: () => {
         connection.transport.refreshTerminalRuntimeInventory();
       },
-      actions: productionOwnerActions(readDaemon),
+      actions: connection.ownerActions ?? productionOwnerActions(readDaemon),
     },
   });
   fastLane = createOpenTuiWorkspaceTerminalFastLane(

package/packages/daemon/src/tui/mirror/runtime/resize-terminal-pane.ts

@@ -75,6 +75,9 @@ export async function resizeTerminalPane(
     });
   };
   try {
+    // Geometry acquisition is itself a mutation of the ownership lease. A stale
+    // gesture must not take it from another client even when resize is refused.
+    if (!isCurrent()) return fail({ stage: "pre-dispatch", reason: "generation-replaced" });
     if (expected.client.ownsRuntimeAuthority?.("geometry") !== true) {
       let lease;
       try {

package/packages/daemon/src/tui/mirror/runtime/select-terminal-pane.ts

@@ -1,3 +1,4 @@
+import type { WindowLinkTarget } from "@tmux-ide/contracts";
 import type { WorkspaceClientDispatch } from "@tmux-ide/daemon-client/workspace-client-types";
 
 interface PaneSelectionClient {
@@ -40,6 +41,7 @@ export async function selectTerminalPane(
   semanticPaneId: string,
   operationId?: string,
   onFailure?: (failure: PaneSelectionFailure) => void,
+  windowLink?: WindowLinkTarget,
 ): Promise<PaneSelectionReceipt | null> {
   const fail = (failure: PaneSelectionFailure): null => {
     try {
@@ -95,6 +97,7 @@ export async function selectTerminalPane(
           verb: "workspace.pane.select",
           workspaceName: expected.workspaceName,
           semanticPaneId,
+          ...(windowLink ? { windowLink } : {}),
         },
       });
     } catch (error) {