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

package/packages/daemon/dist/tui/mirror/open-tui-workspace-runtime-port.js

@@ -109,14 +109,18 @@ function layoutKey(frame) {
         return null;
     return `panes:${panes.join("\u0000")}`;
 }
-function layoutSnapshot(windows, currentWindowKey = null) {
+function layoutSnapshot(windows, currentWindowKey = null, windowLinks = null) {
     const selectedKey = currentWindowKey ??
         [...windows.entries()].find(([, frame]) => frame.currentWindow)?.[0] ??
         null;
     const frames = Object.freeze([...windows.entries()].map(([key, frame]) => frame.currentWindow === (key === selectedKey)
         ? frame
         : 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,
     });
@@ -144,7 +148,8 @@ function layoutFrameSemanticallyEqual(left, right) {
         }));
 }
 function layoutSnapshotsSemanticallyEqual(left, right) {
-    return (left.windows.length === right.windows.length &&
+    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];
             return candidate !== undefined && layoutFrameSemanticallyEqual(window, candidate);
@@ -702,6 +707,8 @@ export async function connectOpenTuiWorkspaceRuntimePort(options) {
         if (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))) {
             return;
@@ -866,7 +873,7 @@ export async function connectOpenTuiWorkspaceRuntimePort(options) {
                 : {}),
             signal: options.signal,
             stream: {
-                protocolVersion: 1,
+                protocolVersion: 2,
                 workspaceName: inventory.workspaceName,
                 panes: [...panes],
                 viewerMode: "interactive",
@@ -981,13 +988,16 @@ export async function connectOpenTuiWorkspaceRuntimePort(options) {
                     });
                     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)
+                if (!latestLayoutSnapshot.windowLinks && retained.currentWindow)
                     currentWindowKey = key;
-                const candidate = layoutSnapshot(layoutsByWindow, currentWindowKey);
+                const candidate = layoutSnapshot(layoutsByWindow, currentWindowKey, latestLayoutSnapshot.windowLinks ?? null);
                 if (!layoutExactlyCoversPanes(candidate, panes)) {
                     if (lastRejectedLayoutSnapshot &&
                         layoutSnapshotsSemanticallyEqual(candidate, lastRejectedLayoutSnapshot))
@@ -1023,6 +1033,9 @@ export async function connectOpenTuiWorkspaceRuntimePort(options) {
             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();
                 let replacementCurrent = null;
                 for (const frame of snapshot.layouts) {
@@ -1030,14 +1043,15 @@ export async function connectOpenTuiWorkspaceRuntimePort(options) {
                     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();
@@ -1048,6 +1062,11 @@ export async function connectOpenTuiWorkspaceRuntimePort(options) {
                 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 {
@@ -1198,7 +1217,9 @@ export async function connectOpenTuiWorkspaceRuntimePort(options) {
         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/dist/tui/mirror/runtime/application-guided-tour-integration.jsx

@@ -0,0 +1,119 @@
+/* @jsxImportSource @opentui/solid */
+import { randomUUID } from "node:crypto";
+import { createEffect, createMemo, Show } from "solid-js";
+import { createApplicationGuidedTourOwner } from "./application-guided-tour-owner.js";
+import { GuidedTourCoach } from "./guided-tour-coach.jsx";
+import { createFleetSession } from "./fleet-lifecycle-client.js";
+import { applicationMachineAuthorityManager } from "./application-machine-authority.js";
+export function createApplicationGuidedTourIntegration(options) {
+    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) => {
+        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((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((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>),
+    };
+}

package/packages/daemon/dist/tui/mirror/runtime/application-guided-tour-owner.js

@@ -0,0 +1,132 @@
+import { createSignal, onCleanup } from "solid-js";
+import { initialGuidedTourState, reduceGuidedTour, sameGuidedTourPractice, } from "./guided-tour.js";
+import { readGuidedTourState, writeGuidedTourState } from "./guided-tour-storage.js";
+/** Compare confirmed snapshots; unrelated sessions and request attempts never count. */
+export function observedGuidedTourEvent(state, previous, current) {
+    if (!state.active || !previous)
+        return null;
+    if (state.step === "commands" && current.paletteOpen && !previous.paletteOpen)
+        return { type: "commands-opened" };
+    if (state.step === "theme" && current.theme !== previous.theme)
+        return { type: "theme-changed" };
+    if (state.step === "leave" && current.surface === "home")
+        return { type: "home-opened" };
+    if (!current.practice ||
+        !sameGuidedTourPractice(state.practice, current.practice) ||
+        current.surface !== "terminals")
+        return null;
+    if (state.step === "reopen" &&
+        (previous.surface !== "terminals" ||
+            !sameGuidedTourPractice(previous.practice, current.practice)))
+        return { type: "reopened", practice: current.practice };
+    if (!previous.practice || !sameGuidedTourPractice(previous.practice, current.practice))
+        return null;
+    if (state.step === "split" &&
+        previous.panes.length > 0 &&
+        current.panes.length > previous.panes.length &&
+        previous.panes.every((old) => current.panes.some((p) => p.id === old.id)) &&
+        current.panes.some((p) => !previous.panes.some((old) => old.id === p.id)))
+        return { type: "split-confirmed", practice: current.practice };
+    if (state.step === "focus" &&
+        previous.focusedPane &&
+        current.focusedPane &&
+        previous.focusedPane !== current.focusedPane &&
+        current.panes.some((p) => p.id === current.focusedPane) &&
+        current.panes.some((p) => p.id === previous.focusedPane))
+        return { type: "focus-confirmed", practice: current.practice };
+    // A divider reallocates space between the same panes: one grows while
+    // another shrinks on the same axis. Whole-app growth/shrink is not practice.
+    const samePanes = current.panes.length >= 2 &&
+        current.panes.length === previous.panes.length &&
+        previous.panes.every((old) => current.panes.some((pane) => pane.id === old.id));
+    const reallocated = ["width", "height"].some((axis) => {
+        const changes = current.panes.map((pane) => pane[axis] - (previous.panes.find((old) => old.id === pane.id)?.[axis] ?? pane[axis]));
+        return changes.some((change) => change > 0) && changes.some((change) => change < 0);
+    });
+    if (state.step === "resize" && samePanes && reallocated)
+        return { type: "resize-confirmed", practice: current.practice };
+    return null;
+}
+export function createApplicationGuidedTourOwner(options) {
+    const [state, setState] = createSignal((options.read ?? readGuidedTourState)());
+    const [busy, setBusy] = createSignal(false);
+    const [error, setError] = createSignal(null);
+    let previous = null;
+    let disposed = false;
+    onCleanup(() => {
+        disposed = true;
+    });
+    const send = (event) => {
+        const next = reduceGuidedTour(state(), event);
+        if (next === state())
+            return;
+        setState(next);
+        if (!(options.write ?? writeGuidedTourState)(next))
+            setError("Progress could not be saved. You can still continue this tour.");
+    };
+    return {
+        state,
+        busy,
+        error,
+        label: () => state().step === "complete"
+            ? "Replay walkthrough"
+            : state().step === initialGuidedTourState().step
+                ? "Learn tmux-ide"
+                : "Resume walkthrough",
+        open() {
+            previous = null;
+            send({ type: state().step === "complete" ? "replay" : "resume" });
+        },
+        replay() {
+            previous = null;
+            send({ type: "replay" });
+        },
+        pause() {
+            send({ type: "pause" });
+        },
+        welcomeRead() {
+            send({ type: "welcome-read" });
+        },
+        observe(current) {
+            const event = observedGuidedTourEvent(state(), previous, current);
+            previous = current;
+            if (event)
+                send(event);
+        },
+        async createPractice() {
+            if (busy() || state().step !== "practice")
+                return;
+            setBusy(true);
+            setError(null);
+            try {
+                const practice = await options.createPractice();
+                if (disposed)
+                    return;
+                send({ type: "practice-created", practice });
+                if (state().active)
+                    await options.openPractice(practice);
+            }
+            catch (cause) {
+                if (!disposed)
+                    setError(cause instanceof Error ? cause.message : "Could not create the practice session.");
+            }
+            finally {
+                if (!disposed)
+                    setBusy(false);
+            }
+        },
+        async openPractice() {
+            const practice = state().practice;
+            if (!practice || busy())
+                return;
+            setError(null);
+            try {
+                if (state().active)
+                    await options.openPractice(practice);
+            }
+            catch (cause) {
+                setError(cause instanceof Error ? cause.message : "Practice session is unavailable.");
+            }
+        },
+    };
+}

package/packages/daemon/dist/tui/mirror/runtime/application-home-agent-roster.jsx

@@ -23,7 +23,8 @@ export function HomeAgentRoster(props) {
     const [hovered, setHovered] = createSignal(null);
     const width = () => Math.max(0, Math.floor(props.width));
     const height = () => Math.max(0, Math.floor(props.height));
-    const stale = (row) => (props.snapshot.refreshingSessionKeys ?? []).includes(row.sessionKey) ||
+    const stale = (row) => row.disabled ||
+        (props.snapshot.refreshingSessionKeys ?? []).includes(row.sessionKey) ||
         (props.snapshot.unavailableSessionKeys ?? []).includes(row.sessionKey);
     const showRecovery = () => Boolean(((props.snapshot.phase === "unavailable" || props.snapshot.unavailableSessions > 0) &&
         props.onRetry) ||
@@ -50,8 +51,8 @@ export function HomeAgentRoster(props) {
         if (props.snapshot.phase === "live" && props.snapshot.rows.length === 0)
             return "No agents reported";
         const count = props.snapshot.rows.length;
-        const attention = props.snapshot.rows.filter((row) => row.attention || row.activity === "waiting" || row.activity === "failed").length;
-        const working = props.snapshot.rows.filter((row) => row.activity === "running").length;
+        const attention = props.snapshot.rows.filter((row) => !stale(row) && (row.attention || row.activity === "waiting" || row.activity === "failed")).length;
+        const working = props.snapshot.rows.filter((row) => !stale(row) && row.activity === "running").length;
         return `${count} observed ${count === 1 ? "agent" : "agents"} · ${attention} ${attention === 1 ? "needs" : "need"} attention · ${working} working`;
     };
     const coverage = () => `Scope: ${props.snapshot.observedSessions} of ${props.snapshot.totalSessions} sessions observed${props.snapshot.phase === "partial" ? " · partial" : ""}${props.snapshot.loadingSessions ? ` · ${props.snapshot.loadingSessions} loading` : ""}${props.snapshot.unavailableSessions ? ` · ${props.snapshot.unavailableSessions} unavailable` : ""}${props.snapshot.truncatedSessions ? ` · ${props.snapshot.truncatedSessions} not loaded` : ""}`;
@@ -69,15 +70,22 @@ export function HomeAgentRoster(props) {
             return "Enlarge the terminal to view agents.";
         const selected = props.snapshot.rows.find((row) => row.key === props.selection.selectedKey);
         if (selected && stale(selected))
-            return `${selected.sessionName} · last observed; waiting for fresh signals`;
-        if (width() < 44 && selected)
-            return `${selected.sessionName} · Enter open`;
+            return `${[selected.machineLabel, selected.serverLabel, selected.sessionName].filter(Boolean).join(" / ")} · last observed; waiting for fresh signals`;
+        if (selected?.machineLabel || (width() < 44 && selected))
+            return `${[selected?.machineLabel, selected?.serverLabel, selected?.sessionName].filter(Boolean).join(" / ")} · Enter open`;
         return `${offset() + 1}–${Math.min(props.snapshot.rows.length, offset() + visibleCount())} of ${props.snapshot.rows.length} · ↑↓ select · Enter open`;
     };
     useKeyboardRoute((event) => {
         if (!props.inputActive || event.eventType !== "press" || event.ctrl || event.meta)
             return false;
         const key = event.name.toLowerCase();
+        const filter = key === "f" ? props.onCycleMachine : key === "a" ? props.onToggleAttention : undefined;
+        if (filter) {
+            event.preventDefault();
+            event.stopPropagation();
+            filter();
+            return true;
+        }
         const retry = key === "r" &&
             (props.snapshot.phase === "unavailable" || props.snapshot.unavailableSessions > 0) &&
             props.onRetry;
@@ -120,10 +128,12 @@ export function HomeAgentRoster(props) {
       <text width={width()} height={1} flexShrink={0} fg={props.theme.roles.text.muted}>
         {clipTerminal(coverage(), width())}
       </text>
-      <box height={1} flexShrink={0}/>
+      <text width={width()} height={1} flexShrink={0} fg={props.theme.roles.text.secondary}>
+        {clipTerminal(props.filterLabel ? `${props.filterLabel} · f machine · a attention` : "", width())}
+      </text>
       <Show when={props.snapshot.rows.length > 0} fallback={<box height={Math.max(0, visibleCount() + 1)} flexShrink={0}/>}>
         <text width={width()} height={1} flexShrink={0} fg={props.theme.roles.text.muted}>
-          {clipTerminal(`  ${padCells("AGENT", columns().agent)}${padCells("SESSION", columns().session)} ${padCells("STATUS", columns().status)}`, width())}
+          {clipTerminal(`  ${padCells("AGENT", columns().agent)}${padCells(props.filterLabel ? "MACHINE / SERVER / SESSION" : "SESSION", columns().session)} ${padCells("STATUS", columns().status)}`, width())}
         </text>
         <box height={visibleCount()} width={width()} flexShrink={0} flexDirection="column" overflow="hidden">
           <For each={keys()}>
@@ -131,7 +141,9 @@ export function HomeAgentRoster(props) {
             const row = () => byKey().get(key);
             return (<box height={1} width={width()} flexShrink={0} onMouseOver={() => setHovered(key)} onMouseMove={() => setHovered(key)}>
                   <NavigationRow theme={props.theme} id={`home-agent:${key}`} width={width()} label={padCells(row().name, columns().agent) +
-                    padCells(row().sessionName, columns().session)} detail={padCells(`${row().attention ? "! " : ""}${homeAgentStatusLabel(row().activity)}${stale(row()) ? "*" : ""}`, columns().status)} detailAlign="end" marker={props.selection.selectedKey === key ? "›" : " "} selected={props.selection.selectedKey === key} focused={props.inputActive && props.selection.selectedKey === key} hovered={hovered() === key} attention={row().attention} status={statusTone(row())} disabled={row().paneId === null || stale(row())} onActivate={(source) => {
+                    padCells([row().machineLabel, row().serverLabel, row().sessionName]
+                        .filter(Boolean)
+                        .join(" / "), columns().session)} detail={padCells(`${!stale(row()) && row().attention ? "! " : ""}${stale(row()) ? "last seen" : homeAgentStatusLabel(row().activity)}`, columns().status)} detailAlign="end" marker={props.selection.selectedKey === key ? "›" : " "} selected={props.selection.selectedKey === key} focused={props.inputActive && props.selection.selectedKey === key} hovered={hovered() === key} attention={!stale(row()) && row().attention} status={stale(row()) ? "unknown" : statusTone(row())} disabled={row().paneId === null || stale(row())} onActivate={(source) => {
                     if (!props.inputActive || row().paneId === null || stale(row()))
                         return;
                     props.onSelect(key);

package/packages/daemon/dist/tui/mirror/runtime/application-home-agent-transport.js

@@ -1,5 +1,5 @@
 import { readApplicationDaemonInfo as readCanonicalDaemonInfo } from "./application-daemon-authority.js";
-import { ApplicationShellResourceV2SchemaZ, DaemonEventClientFrameSchemaZ, DaemonEventServerFrameSchemaZ, WorkspaceCatalogResourceV3SchemaZ, } from "@tmux-ide/contracts";
+import { ApplicationShellResourceV2SchemaZ, ApplicationShellProjectionInputV2SchemaZ, TmuxServerScopeSchemaZ, DaemonEventClientFrameSchemaZ, DaemonEventServerFrameSchemaZ, WorkspaceCatalogResourceV3SchemaZ, } from "@tmux-ide/contracts";
 import WebSocket from "ws";
 import { canonicalDaemonUrl } from "../../../lib/canonical-daemon.js";
 export function sameHomeAgentDaemon(expected, actual) {
@@ -35,6 +35,21 @@ export function createApplicationHomeAgentTransport(options = {}) {
                     throw new Error(`Agent observation returned HTTP ${response.status}.`);
                 return response.json();
             };
+            if (session.server) {
+                const server = TmuxServerScopeSchemaZ.parse(session.server);
+                const base = `/api/v1/tmux-servers/${server.serverId}/${server.generation}`;
+                const raw = await get(`${base}/application-shell/${encodeURIComponent(session.workspaceName ?? session.name)}?liveSessionId=${encodeURIComponent(session.liveSessionId ?? "")}`);
+                const actual = TmuxServerScopeSchemaZ.parse(raw.server);
+                if (raw.version !== 1 ||
+                    actual.serverId !== server.serverId ||
+                    actual.generation !== server.generation)
+                    throw new Error("Agent server incarnation changed.");
+                return {
+                    version: 2,
+                    daemon,
+                    resource: ApplicationShellProjectionInputV2SchemaZ.parse(raw.resource),
+                };
+            }
             const shell = ApplicationShellResourceV2SchemaZ.parse(await get(`/api/project/${encodeURIComponent(session.name)}/application-shell?version=2`));
             if (!sameHomeAgentDaemon(daemon, shell.daemon))
                 throw new Error("Agent daemon changed.");
@@ -48,6 +63,53 @@ export function createApplicationHomeAgentTransport(options = {}) {
             return shell;
         },
         connect(daemon, sessions, handlers) {
+            const scoped = sessions.filter((session) => session.server);
+            if (scoped.length > 0) {
+                // Scoped session events currently carry topology, not agent activity.
+                // Refresh metadata with a bounded cadence; never attach terminal streams.
+                // Keep legacy observations independent from scoped owner availability.
+                const pushed = sessions.filter((session) => !session.server || session.server.generation === daemon.instanceId);
+                let closed = false;
+                let pushHealthy = false;
+                const interval = setInterval(() => {
+                    if (!closed)
+                        for (const session of scoped) {
+                            if (!pushHealthy || session.server?.generation !== daemon.instanceId)
+                                handlers.invalidate(session.id);
+                        }
+                }, 5_000);
+                interval.unref?.();
+                const connection = pushed.length
+                    ? createApplicationHomeAgentTransport(options).connect(daemon, pushed.map((session) => ({ ...session, server: undefined })), {
+                        ...handlers,
+                        // The root event stream is advisory for scoped reads. Failure must
+                        // not stall independent scoped owners or suppress their rows.
+                        ready: (unavailable) => {
+                            pushHealthy = unavailable.length === 0;
+                            if (!closed)
+                                for (const session of pushed)
+                                    handlers.invalidate(session.id);
+                        },
+                        unavailable: () => {
+                            pushHealthy = false;
+                            if (!closed)
+                                for (const session of pushed)
+                                    handlers.invalidate(session.id);
+                        },
+                    })
+                    : null;
+                queueMicrotask(() => {
+                    if (!closed)
+                        handlers.ready([]);
+                });
+                return {
+                    close() {
+                        closed = true;
+                        clearInterval(interval);
+                        connection?.close();
+                    },
+                };
+            }
             let closed = false;
             let failed = false;
             const sockets = [];

package/packages/daemon/dist/tui/mirror/runtime/application-home-agents-owner.js

@@ -159,7 +159,7 @@ export function createApplicationHomeNavigationOwner(options) {
     const paneRename = createApplicationPaneRenameOwner(options.interaction.renamePane, options.setNote);
     const homeAgents = createApplicationHomeAgentsOwner({
         catalog: options.catalog.snapshot,
-        active: () => options.activeSurface() === "home",
+        active: () => !options.fleetHome && options.activeSurface() === "home",
         inputActive: () => options.activeSurface() === "home" &&
             !paneRename.draft() &&
             !options.appearanceOpen?.() &&
@@ -225,5 +225,11 @@ export function createApplicationHomeNavigationOwner(options) {
         onNavigationIntent: homeAgents.cancel,
     });
     const paletteCommandList = paletteCommands.commands;
-    return { homeAgents, paneRename, paletteCommands, paletteCommandList, openAgent };
+    return {
+        homeAgents: options.fleetHome ? { ...homeAgents, presentation: options.fleetHome } : homeAgents,
+        paneRename,
+        paletteCommands,
+        paletteCommandList,
+        openAgent,
+    };
 }

package/packages/daemon/dist/tui/mirror/runtime/application-home-agents.js

@@ -14,11 +14,13 @@ export function projectHomeAgentRows(session, shell) {
     return shell.resource.workspace.sidebar.agents.map((agent) => ({
         key: `${session.id}\u0000${agent.id}`,
         sessionKey: session.id,
+        server: session.server,
+        serverLabel: session.serverLabel,
         sessionName: session.name,
         // Older catalog fixtures/callers retain a generation-qualified incarnation
         // key even when they do not expose the separately named wire field.
         liveSessionId: session.liveSessionId ?? session.id,
-        daemonInstanceId: shell.daemon.instanceId,
+        daemonInstanceId: session.server?.generation ?? shell.daemon.instanceId,
         agentId: agent.id,
         paneId: agent.paneId,
         windowId: shell.resource.terminalInventory?.resources.find((resource) => resource.attachability.status === "available" &&

package/packages/daemon/dist/tui/mirror/runtime/application-home-catalog-owner.js

@@ -56,8 +56,12 @@ export function createApplicationHomeCatalogOwner(options) {
         const currentSessions = next.sessions;
         if (automaticOpen && next.phase === "live") {
             automaticOpen = false;
-            if (currentSessions.length === 1)
-                void options.startGeneration(currentSessions[0].name);
+            if (currentSessions.length === 1) {
+                const session = currentSessions[0];
+                void (options.openCatalogSession
+                    ? options.openCatalogSession(session)
+                    : options.startGeneration(session.name));
+            }
         }
         if (currentSessions.length === 0) {
             if (current !== null)
@@ -93,9 +97,11 @@ export function createApplicationHomeCatalogOwner(options) {
                 return true;
             }
             if (name === "return" || name === "enter") {
-                const sessionName = sessions()[selectedSessionIndex()]?.name;
-                if (sessionName)
-                    void options.startGeneration(sessionName);
+                const session = sessions()[selectedSessionIndex()];
+                if (session)
+                    void (options.openCatalogSession
+                        ? options.openCatalogSession(session)
+                        : options.startGeneration(session.name));
                 return true;
             }
             return false;