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

package/packages/daemon/src/tui/mirror/application-shell-server-connection.ts

@@ -0,0 +1,154 @@
+import type { DesktopApplicationShellTarget } from "@tmux-ide/contracts";
+import { createTmuxServerClient } from "@tmux-ide/daemon-client/tmux-server-client";
+import {
+  createScopedTmuxServerTransport,
+  createScopedTmuxServerCatalogPort,
+  createScopedTmuxServerOwnerActions,
+} from "@tmux-ide/daemon-client/scoped-tmux-server-transport";
+import { canonicalDaemonUrl } from "../../lib/canonical-daemon.ts";
+import type {
+  OpenTuiApplicationShellConnection,
+  OpenTuiApplicationShellConnectionDependencies,
+} from "./application-shell-daemon-connection.ts";
+import { createOpenTuiVerifiedRoutingContext } from "./open-tui-verified-routing.ts";
+import { OPEN_TUI_HOST_CLIENT_ID } from "./open-tui-workspace-runtime-port.ts";
+import { OpenTuiStartupError } from "./startup-failure.ts";
+
+/** A selected registration never falls through to a name-only/default-server route. */
+export async function prepareScopedOpenTuiConnection(
+  sessionName: string,
+  dependencies: OpenTuiApplicationShellConnectionDependencies,
+  prepareDefault: () => Promise<OpenTuiApplicationShellConnection | null>,
+): Promise<OpenTuiApplicationShellConnection | null> {
+  const scope = dependencies.server!;
+  const daemon = dependencies.readCanonicalDaemonInfo();
+  if (!daemon || !daemon.authToken || !(await dependencies.isCanonicalDaemonAlive(daemon)))
+    throw new OpenTuiStartupError({ reason: "daemon-unavailable" });
+  const clientOptions = {
+    baseUrl: canonicalDaemonUrl("http", daemon.bindHostname, daemon.port),
+    ownerToken: daemon.authToken,
+    hostClientId: OPEN_TUI_HOST_CLIENT_ID,
+    origin: "tmux-ide://opentui",
+  };
+  const client = createTmuxServerClient(clientOptions, scope);
+  try {
+    const catalog = await client.sessions();
+    const candidates = catalog.sessions.filter(
+      (session) =>
+        session.sessionName === sessionName &&
+        (!dependencies.expectedLiveSessionId ||
+          session.liveSessionId === dependencies.expectedLiveSessionId),
+    );
+    if (candidates.length !== 1) throw new OpenTuiStartupError({ reason: "session-unavailable" });
+    const liveSessionId = candidates[0]!.liveSessionId;
+    // The borrowed default owner has the daemon's original generation. Its existing
+    // transport preserves the full app surface while the scoped read proves routing.
+    if (scope.generation === daemon.instanceId) {
+      const connection = await prepareDefault();
+      if (!connection || connection.liveSessionId !== liveSessionId) {
+        connection?.dispose();
+        throw new OpenTuiStartupError({ reason: "session-unavailable" });
+      }
+      try {
+        const current = await client.sessions();
+        if (
+          !current.sessions.some(
+            (session) =>
+              session.liveSessionId === liveSessionId && session.sessionName === sessionName,
+          )
+        )
+          throw new OpenTuiStartupError({ reason: "session-unavailable" });
+        const options = {
+          clientOptions,
+          scope,
+          target: connection.target,
+          sessionName,
+          liveSessionId,
+        };
+        const routing = createOpenTuiVerifiedRoutingContext(
+          daemon,
+          connection.workspaceName,
+          sessionName,
+          undefined,
+          dependencies.readDaemonEndpoint,
+          scope,
+          liveSessionId,
+        );
+        connection.routing?.retire();
+        return {
+          ...connection,
+          server: scope,
+          routing,
+          ownerActions: createScopedTmuxServerOwnerActions(options, connection.transport),
+          dispose() {
+            routing?.retire();
+            connection.dispose();
+          },
+        };
+      } catch (error) {
+        connection.dispose();
+        throw error;
+      }
+    }
+    const opened = await client.openSession(liveSessionId);
+    if (opened.liveSessionId !== liveSessionId)
+      throw new OpenTuiStartupError({ reason: "session-unavailable" });
+    const workspaceName = opened.workspaceName;
+    const target: DesktopApplicationShellTarget = {
+      daemon: {
+        protocolVersion: daemon.protocolVersion,
+        productVersion: daemon.productVersion,
+        instanceId: scope.generation,
+        startedAt: daemon.startedAt,
+        ...(daemon.environmentId ? { environmentId: daemon.environmentId } : {}),
+      },
+      workspaceName,
+    };
+    const options = { clientOptions, scope, target, sessionName, liveSessionId };
+    const transport = createScopedTmuxServerTransport(options);
+    const routing = createOpenTuiVerifiedRoutingContext(
+      daemon,
+      workspaceName,
+      sessionName,
+      undefined,
+      dependencies.readDaemonEndpoint,
+      scope,
+      liveSessionId,
+    );
+    const controller = new AbortController();
+    let preparation: ReturnType<
+      OpenTuiApplicationShellConnection["prepareTerminalRuntimeInventory"]
+    > | null = null;
+    return {
+      workspaceName,
+      liveSessionId,
+      target,
+      server: scope,
+      transport,
+      routing,
+      catalog: createScopedTmuxServerCatalogPort(options, transport),
+      ownerActions: createScopedTmuxServerOwnerActions(options, transport),
+      prepareTerminalRuntimeInventory() {
+        preparation ??= transport
+          .prepareTerminalRuntimeInventory(
+            target,
+            AbortSignal.any([controller.signal, AbortSignal.timeout(5_000)]),
+          )
+          .catch(() => {
+            // Fallback remains inside this owner; never use the legacy default resource.
+            transport.selectApplicationShellFallback("preparation-rejected");
+            return null;
+          });
+        return preparation;
+      },
+      dispose() {
+        controller.abort(new DOMException("Selected server connection retired", "AbortError"));
+        void preparation?.then((prepared) => prepared?.dispose()).catch(() => undefined);
+        transport.disposeEventSupervisor();
+        routing?.retire();
+      },
+    };
+  } finally {
+    client.dispose();
+  }
+}

package/packages/daemon/src/tui/mirror/menu-model.ts

@@ -72,7 +72,7 @@ export const MENU_ITEMS: Record<MenuRegion, MenuItem[]> = {
   window: [
     { id: "new", label: "New window" },
     { id: "rename", label: "Rename window", input: "rename to" },
-    { id: "kill", label: "Kill window", danger: true },
+    { id: "kill", label: "Kill window and panes in all links", danger: true },
   ],
 };
 

package/packages/daemon/src/tui/mirror/open-tui-verified-routing.ts

@@ -1,10 +1,13 @@
-import type { CanonicalDaemonInfo } from "@tmux-ide/contracts";
+import type { CanonicalDaemonInfo, TmuxServerScope } from "@tmux-ide/contracts";
 import {
   openPaneStreamRuntimeClient,
+  connectIssuedPaneStreamRuntimeClient,
   type OpenPaneStreamClientOptions,
   type PaneStreamRuntimeClient,
 } from "@tmux-ide/daemon-client/pane-stream-client";
 
+import { createTmuxServerClient } from "@tmux-ide/daemon-client/tmux-server-client";
+
 import { canonicalDaemonUrl } from "../../lib/canonical-daemon.ts";
 import {
   readNativeBacking,
@@ -34,6 +37,7 @@ export type OpenTuiVerifiedPaneStreamOptions = Omit<
  * downstream render/runtime code can use the route but cannot inspect its token.
  */
 export interface OpenTuiVerifiedRoutingContext extends OpenTuiVerifiedRoutingIdentity {
+  readonly liveSessionId?: string;
   readNativeBacking?: ReadNativeBacking;
   assertCurrent(expected: OpenTuiVerifiedRoutingIdentity): void;
   openPaneStream(
@@ -49,6 +53,8 @@ export function createOpenTuiVerifiedRoutingContext(
   sessionName: string,
   openClient: typeof openPaneStreamRuntimeClient = openPaneStreamRuntimeClient,
   readEndpoint: () => ApplicationDaemonEndpoint = applicationDaemonEndpoint,
+  server?: TmuxServerScope,
+  liveSessionId?: string,
 ): OpenTuiVerifiedRoutingContext | null {
   if (!daemon.authToken) return null;
   const ownerToken = daemon.authToken;
@@ -69,7 +75,7 @@ export function createOpenTuiVerifiedRoutingContext(
   const localSocketOrigin = new URL(baseUrl);
   localSocketOrigin.protocol = "ws:";
   const identity = Object.freeze({
-    daemonInstanceId: daemon.instanceId,
+    daemonInstanceId: server?.generation ?? daemon.instanceId,
     workspaceName,
     sessionName,
   });
@@ -96,6 +102,7 @@ export function createOpenTuiVerifiedRoutingContext(
   };
   return Object.freeze({
     ...identity,
+    ...(liveSessionId ? { liveSessionId } : {}),
     assertCurrent,
     readNativeBacking: async (
       paneId: string,
@@ -105,6 +112,11 @@ export function createOpenTuiVerifiedRoutingContext(
       assertCurrent({ ...identity, daemonInstanceId: expected.generation });
       const result = await readNativeBacking({
         baseUrl,
+        ...(server
+          ? {
+              resourcePath: `/api/v1/tmux-servers/${server.serverId}/${server.generation}/native-backing/${encodeURIComponent(workspaceName)}/${encodeURIComponent(paneId)}`,
+            }
+          : {}),
         ownerToken,
         workspaceName,
         paneId,
@@ -122,7 +134,33 @@ export function createOpenTuiVerifiedRoutingContext(
       if (options.stream.workspaceName !== identity.workspaceName) {
         throw new Error("Pane-stream request escaped its verified workspace route");
       }
-      return await openClient({
+      const openScoped: typeof openClient = async (scopedOptions) => {
+        const client = createTmuxServerClient(
+          {
+            baseUrl,
+            ownerToken,
+            hostClientId: scopedOptions.hostClientId,
+            origin: scopedOptions.origin,
+            fetch: scopedOptions.fetch,
+          },
+          server!,
+        );
+        try {
+          if (scopedOptions.signal?.aborted) throw scopedOptions.signal.reason;
+          const issued = await client.issuePaneStream(
+            scopedOptions.requestId,
+            scopedOptions.stream,
+            liveSessionId,
+          );
+          assertCurrent(expected);
+          if (scopedOptions.signal?.aborted) throw scopedOptions.signal.reason;
+          if (issued.status === "error") throw new Error(issued.error.reason);
+          return await connectIssuedPaneStreamRuntimeClient(scopedOptions, issued.descriptor);
+        } finally {
+          client.dispose();
+        }
+      };
+      return await (server ? openScoped : openClient)({
         ...options,
         baseUrl,
         ownerToken,

package/packages/daemon/src/tui/mirror/open-tui-workspace-runtime-port.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type {
+  WindowLinkTopology,
   CanonicalTerminalReplicaUpdate,
   InteractionReceipt,
   PaneStreamServerFrame,
@@ -142,6 +143,8 @@ export const OPEN_TUI_HOST_CLIENT_ID = `opentui:${process.pid}`;
 export type OpenTuiWorkspaceLayout = Extract<PaneStreamServerFrame, { type: "layout" }>;
 
 export interface OpenTuiWorkspaceLayoutSnapshot {
+  /** Live link authority; absent until an atomic stream snapshot arrives. */
+  readonly windowLinks?: WindowLinkTopology | null;
   readonly current: OpenTuiWorkspaceLayout | null;
   readonly windows: readonly OpenTuiWorkspaceLayout[];
 }
@@ -233,6 +236,7 @@ function layoutKey(frame: OpenTuiWorkspaceLayout): string | null {
 function layoutSnapshot(
   windows: ReadonlyMap<string, OpenTuiWorkspaceLayout>,
   currentWindowKey: string | null = null,
+  windowLinks: WindowLinkTopology | null = null,
 ): OpenTuiWorkspaceLayoutSnapshot {
   const selectedKey =
     currentWindowKey ??
@@ -245,7 +249,10 @@ function layoutSnapshot(
         : freezeLayout({ ...frame, currentWindow: key === selectedKey }),
     ),
   );
+  const links = windowLinks?.links.map((link) => Object.freeze({ ...link }));
+  if (links) Object.freeze(links);
   return Object.freeze({
+    windowLinks: windowLinks && links ? Object.freeze({ ...windowLinks, links }) : null,
     current: frames.find((frame) => frame.currentWindow) ?? null,
     windows: frames,
   });
@@ -286,6 +293,7 @@ function layoutSnapshotsSemanticallyEqual(
   right: OpenTuiWorkspaceLayoutSnapshot,
 ): boolean {
   return (
+    JSON.stringify(left.windowLinks ?? null) === JSON.stringify(right.windowLinks ?? null) &&
     left.windows.length === right.windows.length &&
     left.windows.every((window, index) => {
       const candidate = right.windows[index];
@@ -972,6 +980,8 @@ export async function connectOpenTuiWorkspaceRuntimePort(
       coherentSettled ||
       closed ||
       !physicalReady ||
+      (routing.liveSessionId !== undefined &&
+        latestLayoutSnapshot.windowLinks?.liveSessionId !== routing.liveSessionId) ||
       !layoutExactlyCoversPanes(latestLayoutSnapshot, panes) ||
       !latestLayoutSnapshot.current?.panes.every(
         ({ pane }) => typeof pane === "string" && canonicalSeedPanes.has(pane),
@@ -1147,7 +1157,7 @@ export async function connectOpenTuiWorkspaceRuntimePort(
         : {}),
       signal: options.signal,
       stream: {
-        protocolVersion: 1,
+        protocolVersion: 2,
         workspaceName: inventory.workspaceName,
         panes: [...panes],
         viewerMode: "interactive",
@@ -1268,12 +1278,23 @@ export async function connectOpenTuiWorkspaceRuntimePort(
           });
           return;
         }
+        if (
+          latestLayoutSnapshot.windowLinks &&
+          !latestLayoutSnapshot.windowLinks.links.some(
+            (link) => link.semanticWindowId === retained.semanticWindowId,
+          )
+        )
+          return;
         layoutsByWindow.set(key, retained);
         // tmux reports a switch as incumbent=false followed by target=true.
         // Retain the incumbent through that pair and publish one unique current
         // window only when the positive target frame arrives.
-        if (retained.currentWindow) currentWindowKey = key;
-        const candidate = layoutSnapshot(layoutsByWindow, currentWindowKey);
+        if (!latestLayoutSnapshot.windowLinks && retained.currentWindow) currentWindowKey = key;
+        const candidate = layoutSnapshot(
+          layoutsByWindow,
+          currentWindowKey,
+          latestLayoutSnapshot.windowLinks ?? null,
+        );
         if (!layoutExactlyCoversPanes(candidate, panes)) {
           if (
             lastRejectedLayoutSnapshot &&
@@ -1308,6 +1329,13 @@ export async function connectOpenTuiWorkspaceRuntimePort(
       },
       onLayoutSnapshot: (snapshot) => {
         if (closed) return;
+        if (
+          routing.liveSessionId !== undefined &&
+          snapshot.windowLinks.liveSessionId !== routing.liveSessionId
+        )
+          return failConnection(
+            new Error("Selected live session was replaced before terminal activation"),
+          );
         const replacement = new Map<string, ReturnType<typeof freezeLayout>>();
         let replacementCurrent: string | null = null;
         for (const frame of snapshot.layouts) {
@@ -1315,14 +1343,18 @@ export async function connectOpenTuiWorkspaceRuntimePort(
           const key = layoutKey(retained);
           if (key === null || replacement.has(key))
             return failConnection(new Error("invalid layout snapshot"));
-          replacement.set(key, retained);
+          const previous = layoutsByWindow.get(key);
+          replacement.set(
+            key,
+            previous && layoutFrameSemanticallyEqual(previous, retained) ? previous : retained,
+          );
           if (retained.currentWindow) {
             if (replacementCurrent !== null)
               return failConnection(new Error("invalid layout snapshot current window"));
             replacementCurrent = key;
           }
         }
-        const candidate = layoutSnapshot(replacement, replacementCurrent);
+        const candidate = layoutSnapshot(replacement, replacementCurrent, snapshot.windowLinks);
         if (!layoutExactlyCoversPanes(candidate, panes))
           return failConnection(new Error("layout snapshot does not cover terminal inventory"));
         layoutsByWindow.clear();
@@ -1331,6 +1363,11 @@ export async function connectOpenTuiWorkspaceRuntimePort(
         lastRejectedLayoutSnapshot = null;
         if (layoutSnapshotsSemanticallyEqual(candidate, latestLayoutSnapshot)) return;
         latestLayoutSnapshot = candidate;
+        options.onDiagnostic?.("layout", {
+          windows: candidate.windows.length,
+          current: candidate.current !== null,
+          links: candidate.windowLinks?.links.length ?? 0,
+        });
         settleCoherent();
         for (const listener of [...layoutListeners]) {
           try {
@@ -1485,7 +1522,11 @@ export async function connectOpenTuiWorkspaceRuntimePort(
     submitIntent: async (operationId, intent) => {
       // Structural commands can affect hidden panes. Do not defer user intent
       // until a different topology may be current; fail closed during seeding.
-      if (closed || [...endpoints.values()].some((endpoint) => !endpoint.inputReady))
+      if (
+        closed ||
+        !latestLayoutSnapshot.windowLinks ||
+        [...endpoints.values()].some((endpoint) => !endpoint.inputReady)
+      )
         throw new Error("Terminal inventory is still receiving canonical state");
       return (await opened.submitIntent(operationId, intent)) ?? undefined;
     },

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

@@ -68,7 +68,7 @@ export function explicitApplicationTarget(argv: readonly string[]): string | nul
     args: [...argv],
     allowPositionals: true,
     strict: false,
-    options: { target: { type: "string" } },
+    options: { target: { type: "string" }, server: { type: "string" } },
   });
   const positional = parsed.positionals.find((value) => value !== "app") ?? null;
   const target = typeof parsed.values.target === "string" ? parsed.values.target : positional;
@@ -79,6 +79,7 @@ export function prepareExplicitApplicationTarget<Value>(
   argv: readonly string[],
   prepare: (sessionName: string) => Promise<Value>,
 ): { readonly sessionName: string; readonly prepared: Promise<Value> } | null {
+  if (argv.some((arg) => arg === "--server" || arg.startsWith("--server="))) return null;
   const sessionName = explicitApplicationTarget(argv);
   if (!sessionName) return null;
   const prepared = prepare(sessionName);

package/packages/daemon/src/tui/mirror/runtime/application-fleet-session-actions.tsx

@@ -43,6 +43,8 @@ export function ApplicationFleetSessionActions(props: {
     return command
       ? JSON.stringify([
           command.fleet!.machineId,
+          command.fleet!.server?.serverId,
+          command.fleet!.server?.generation,
           command.fleet!.daemonInstanceId,
           command.fleet!.liveSessionId,
           command.sessionName,
@@ -117,12 +119,13 @@ export function ApplicationFleetSessionActions(props: {
       )
         throw new Error("The selected host is unavailable or has restarted.");
       const epoch = handle.endpoint().epoch;
-      const routing = await ports().routing(daemon, undefined, signal);
+      const routing = target.server ? null : await ports().routing(daemon, undefined, signal);
       if (!current()) return;
       if (
         handle.endpoint().epoch !== epoch ||
         handle.read()?.instanceId !== target.daemonInstanceId ||
-        (target.liveSessionId !== "" &&
+        (routing &&
+          target.liveSessionId !== "" &&
           !routing.liveSessions.some(
             (session) =>
               session.liveSessionId === target.liveSessionId &&
@@ -132,11 +135,14 @@ export function ApplicationFleetSessionActions(props: {
         throw new Error("The selected session has changed. Select it again.");
       const result =
         action === "create"
-          ? await ports().create(handle, text)
+          ? target.server
+            ? await ports().create(handle, text, target.server)
+            : await ports().create(handle, text)
           : await ports().close(handle, {
               daemonInstanceId: target.daemonInstanceId,
               liveSessionId: target.liveSessionId,
               sessionName: command.sessionName,
+              ...(target.server ? { server: target.server } : {}),
             });
       if (!current()) return;
       if (!result)
@@ -180,7 +186,7 @@ export function ApplicationFleetSessionActions(props: {
           <TuiButton
             theme={props.theme}
             size="compact"
-            label="New on host ^N"
+            label={selected()?.fleet?.server ? "New on server ^N" : "New on host ^N"}
             disabled={!props.active || selected()?.fleet?.disabled || busy()}
             onPress={() => begin("create")}
           />

package/packages/daemon/src/tui/mirror/runtime/application-fleet-tabs.ts

@@ -1,7 +1,9 @@
+import type { TmuxServerScope } from "@tmux-ide/contracts";
 export interface FleetTabTarget {
   readonly key: string;
   readonly machineId: string;
   readonly liveSessionId: string;
+  readonly server?: TmuxServerScope;
   readonly label: string;
   readonly hostLabel: string;
 }

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

@@ -0,0 +1,199 @@
+/* @jsxImportSource @opentui/solid */
+import { randomUUID } from "node:crypto";
+import { createEffect, createMemo, Show, type Accessor } from "solid-js";
+import { createApplicationGuidedTourOwner } from "./application-guided-tour-owner.ts";
+import { GuidedTourCoach } from "./guided-tour-coach.tsx";
+import type { GuidedTourPractice } from "./guided-tour.ts";
+import { createFleetSession } from "./fleet-lifecycle-client.ts";
+import { applicationMachineAuthorityManager } from "./application-machine-authority.ts";
+import type { createApplicationMachineNavigation } from "./application-machine-navigation.ts";
+import type { ApplicationAppearanceOwner } from "./application-appearance-owner.ts";
+import type { createApplicationHomeNavigationOwner } from "./application-home-agents-owner.ts";
+import type { OpenTuiGenerationHostSnapshot } from "./open-tui-generation-host.ts";
+import type { OpenTuiWorkspaceLayoutSnapshot } from "../open-tui-workspace-runtime-port.ts";
+
+export function createApplicationGuidedTourIntegration(options: {
+  machines: ReturnType<typeof createApplicationMachineNavigation>;
+  lifecycle: { signal: AbortSignal };
+  generation: Accessor<OpenTuiGenerationHostSnapshot | null>;
+  generationMachineId: Accessor<string | null>;
+  layoutSnapshot: Accessor<OpenTuiWorkspaceLayoutSnapshot>;
+  sessionName: () => string | null;
+  focusedPane: Accessor<string | null>;
+  activeSurface: Accessor<"home" | "terminals">;
+  appearance: ApplicationAppearanceOwner;
+  paletteOpen: Accessor<boolean>;
+  paletteCommands: ReturnType<typeof createApplicationHomeNavigationOwner>["paletteCommands"];
+  dimensions: Accessor<{ width: number; height: number }>;
+  blocked: Accessor<boolean>;
+}) {
+  const {
+    machines,
+    lifecycle,
+    generation,
+    generationMachineId,
+    layoutSnapshot,
+    sessionName,
+    focusedPane,
+    activeSurface,
+    appearance,
+    paletteOpen,
+    paletteCommands,
+    dimensions,
+    blocked,
+  } = options;
+  const practiceRows = () =>
+    machines.catalog
+      .getSnapshot()
+      .groups.filter((group) => group.id === "local" || group.routeIds?.includes("local"))
+      .flatMap((group) => group.sessions)
+      .filter((row) => !row.disabled);
+  const practiceIdentity = (
+    row: ReturnType<typeof practiceRows>[number],
+  ): GuidedTourPractice | null => {
+    const daemon = applicationMachineAuthorityManager.getMachine("local")?.read();
+    if (!row.liveSessionId || !daemon) return null;
+    return {
+      machineId: "local",
+      serverId: row.server?.serverId ?? "default",
+      generation: row.server?.generation ?? daemon.instanceId,
+      sessionId: row.liveSessionId,
+      sessionName: row.name,
+    };
+  };
+  const tour = createApplicationGuidedTourOwner({
+    async createPractice() {
+      const handle = applicationMachineAuthorityManager.getMachine("local");
+      if (!handle || handle.endpoint().state !== "ready")
+        throw new Error("Connect this machine before creating a practice session.");
+      const created = await createFleetSession(
+        handle,
+        `tmux-ide-practice-${randomUUID().slice(0, 8)}`,
+        undefined,
+        { includeLiveSessionId: true },
+      );
+      if (!created || created.outcome !== "created")
+        throw new Error("Could not create a fresh practice session. Try again.");
+      if (!created.liveSessionId)
+        throw new Error(
+          "Update the local tmux-ide daemon to use the guided practice session, then restart the tour.",
+        );
+      return await new Promise<GuidedTourPractice>((resolve, reject) => {
+        let done = false;
+        let stop = () => {};
+        const abort = () => {
+          clearTimeout(timer);
+          stop();
+          reject(new Error("Tour closed."));
+        };
+        const timer = setTimeout(() => {
+          lifecycle.signal.removeEventListener("abort", abort);
+          stop();
+          reject(
+            new Error(
+              "Practice session was created but has not appeared yet. Find it in the local session list.",
+            ),
+          );
+        }, 10_000);
+        lifecycle.signal.addEventListener("abort", abort, { once: true });
+        const check = () => {
+          const rows = practiceRows().filter(
+            (row) =>
+              row.name === created.workspaceName && row.liveSessionId === created.liveSessionId,
+          );
+          const identity = rows.length === 1 ? practiceIdentity(rows[0]!) : null;
+          if (!identity || identity.generation !== created.daemonInstanceId) return;
+          done = true;
+          lifecycle.signal.removeEventListener("abort", abort);
+          clearTimeout(timer);
+          stop();
+          resolve(identity);
+        };
+        stop = machines.catalog.subscribe(check);
+        if (done) stop();
+        else if (lifecycle.signal.aborted) abort();
+        else check();
+      });
+    },
+    openPractice(practice) {
+      if (practice.machineId !== "local")
+        throw new Error("Practice sessions must belong to this machine. Restart the tour.");
+      const row = practiceRows().find((row) => {
+        const identity = practiceIdentity(row);
+        return (
+          identity &&
+          identity.serverId === practice.serverId &&
+          identity.generation === practice.generation &&
+          identity.sessionId === practice.sessionId
+        );
+      });
+      if (!row)
+        throw new Error(
+          "That practice session is unavailable or has been replaced. Replay the tour to create a new one.",
+        );
+      machines.sidebar.onOpen("local", row.name, "mouse", row.id);
+    },
+  });
+  const committedTourTheme = createMemo<string>((previous) =>
+    appearance.pickerOpen()
+      ? (previous ?? JSON.stringify(appearance.theme().canonical))
+      : JSON.stringify(appearance.theme().canonical),
+  );
+  createEffect(() => {
+    const current = generation();
+    const connection = current?.status === "live" ? current.connection : null;
+    const machineId = generationMachineId();
+    const practice =
+      connection?.liveSessionId && current?.daemonGeneration && machineId
+        ? {
+            machineId,
+            serverId: connection.server?.serverId ?? "default",
+            generation: connection.server?.generation ?? current.daemonGeneration,
+            sessionId: connection.liveSessionId,
+            sessionName: sessionName() ?? "",
+          }
+        : null;
+    tour.observe({
+      practice,
+      panes: (layoutSnapshot().current?.panes ?? []).flatMap((pane) =>
+        pane.pane ? [{ id: pane.pane, width: pane.width, height: pane.height }] : [],
+      ),
+      focusedPane: focusedPane(),
+      surface: activeSurface(),
+      paletteOpen: paletteOpen(),
+      theme: committedTourTheme(),
+    });
+  });
+  return {
+    ...tour,
+    Coach: () => (
+      <Show when={tour.state().active && !blocked()}>
+        <box
+          position="absolute"
+          right={1}
+          bottom={2}
+          width={Math.max(1, Math.min(68, dimensions().width - 2))}
+          zIndex={30}
+        >
+          <GuidedTourCoach
+            height={Math.max(4, Math.min(10, dimensions().height - 4))}
+            state={tour.state()}
+            theme={appearance.theme()}
+            width={Math.max(1, Math.min(68, dimensions().width - 2))}
+            shortcuts={{ commands: "F5", home: "F1" }}
+            error={tour.error()}
+            busy={tour.busy()}
+            onPause={tour.pause}
+            onReplay={tour.replay}
+            onWelcomeRead={tour.welcomeRead}
+            onCreatePractice={() => void tour.createPractice()}
+            onOpenCommands={() => paletteCommands.setOpen(true, "mouse")}
+            onOpenAppearance={appearance.openPicker}
+            onOpenHome={() => paletteCommands.openSurface("home", "mouse")}
+            onOpenPractice={() => void tour.openPractice()}
+          />
+        </box>
+      </Show>
+    ),
+  };
+}