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

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

@@ -0,0 +1,162 @@
+import { createSignal, onCleanup } from "solid-js";
+import {
+  initialGuidedTourState,
+  reduceGuidedTour,
+  sameGuidedTourPractice,
+  type GuidedTourEvent,
+  type GuidedTourPractice,
+  type GuidedTourState,
+} from "./guided-tour.ts";
+import { readGuidedTourState, writeGuidedTourState } from "./guided-tour-storage.ts";
+
+export interface GuidedTourObservation {
+  readonly practice: GuidedTourPractice | null;
+  readonly panes: readonly {
+    readonly id: string;
+    readonly width: number;
+    readonly height: number;
+  }[];
+  readonly focusedPane: string | null;
+  readonly surface: "home" | "terminals";
+  readonly paletteOpen: boolean;
+  readonly theme: string;
+}
+/** Compare confirmed snapshots; unrelated sessions and request attempts never count. */
+export function observedGuidedTourEvent(
+  state: GuidedTourState,
+  previous: GuidedTourObservation | null,
+  current: GuidedTourObservation,
+): GuidedTourEvent | null {
+  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"] as const).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: {
+  createPractice(): Promise<GuidedTourPractice>;
+  openPractice(practice: GuidedTourPractice): Promise<void> | void;
+  read?: () => GuidedTourState;
+  write?: (state: GuidedTourState) => boolean;
+}) {
+  const [state, setState] = createSignal((options.read ?? readGuidedTourState)());
+  const [busy, setBusy] = createSignal(false);
+  const [error, setError] = createSignal<string | null>(null);
+  let previous: GuidedTourObservation | null = null;
+  let disposed = false;
+  onCleanup(() => {
+    disposed = true;
+  });
+  const send = (event: GuidedTourEvent) => {
+    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: GuidedTourObservation) {
+      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/src/tui/mirror/runtime/application-home-agent-roster.tsx

@@ -14,6 +14,9 @@ import {
 import type { HomeAgentSelectionSnapshot } from "./application-home-agent-selection.ts";
 
 export interface HomeAgentRosterProps {
+  readonly filterLabel?: string;
+  readonly onCycleMachine?: () => void;
+  readonly onToggleAttention?: () => void;
   readonly theme: SemanticThemeSnapshot;
   readonly width: number;
   readonly height: number;
@@ -46,6 +49,7 @@ export function HomeAgentRoster(props: HomeAgentRosterProps) {
   const width = () => Math.max(0, Math.floor(props.width));
   const height = () => Math.max(0, Math.floor(props.height));
   const stale = (row: HomeAgentRow) =>
+    row.disabled ||
     (props.snapshot.refreshingSessionKeys ?? []).includes(row.sessionKey) ||
     (props.snapshot.unavailableSessionKeys ?? []).includes(row.sessionKey);
   const showRecovery = () =>
@@ -83,9 +87,12 @@ export function HomeAgentRoster(props: HomeAgentRosterProps) {
       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",
+      (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;
-    const working = props.snapshot.rows.filter((row) => row.activity === "running").length;
     return `${count} observed ${count === 1 ? "agent" : "agents"} · ${attention} ${attention === 1 ? "needs" : "need"} attention · ${working} working`;
   };
   const coverage = () =>
@@ -102,13 +109,22 @@ export function HomeAgentRoster(props: HomeAgentRosterProps) {
     if (visibleCount() === 0) 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) &&
@@ -160,14 +176,19 @@ export function HomeAgentRoster(props: HomeAgentRosterProps) {
       <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)}`,
+            `  ${padCells("AGENT", columns().agent)}${padCells(props.filterLabel ? "MACHINE / SERVER / SESSION" : "SESSION", columns().session)} ${padCells("STATUS", columns().status)}`,
             width(),
           )}
         </text>
@@ -195,10 +216,15 @@ export function HomeAgentRoster(props: HomeAgentRosterProps) {
                     width={width()}
                     label={
                       padCells(row().name, columns().agent) +
-                      padCells(row().sessionName, columns().session)
+                      padCells(
+                        [row().machineLabel, row().serverLabel, row().sessionName]
+                          .filter(Boolean)
+                          .join(" / "),
+                        columns().session,
+                      )
                     }
                     detail={padCells(
-                      `${row().attention ? "! " : ""}${homeAgentStatusLabel(row().activity)}${stale(row()) ? "*" : ""}`,
+                      `${!stale(row()) && row().attention ? "! " : ""}${stale(row()) ? "last seen" : homeAgentStatusLabel(row().activity)}`,
                       columns().status,
                     )}
                     detailAlign="end"
@@ -206,8 +232,8 @@ export function HomeAgentRoster(props: HomeAgentRosterProps) {
                     selected={props.selection.selectedKey === key}
                     focused={props.inputActive && props.selection.selectedKey === key}
                     hovered={hovered() === key}
-                    attention={row().attention}
-                    status={statusTone(row())}
+                    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;

package/packages/daemon/src/tui/mirror/runtime/application-home-agent-transport.ts

@@ -1,6 +1,8 @@
 import { readApplicationDaemonInfo as readCanonicalDaemonInfo } from "./application-daemon-authority.ts";
 import {
   ApplicationShellResourceV2SchemaZ,
+  ApplicationShellProjectionInputV2SchemaZ,
+  TmuxServerScopeSchemaZ,
   DaemonEventClientFrameSchemaZ,
   DaemonEventServerFrameSchemaZ,
   WorkspaceCatalogResourceV3SchemaZ,
@@ -66,6 +68,25 @@ export function createApplicationHomeAgentTransport(
         if (!response.ok) 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`),
       );
@@ -87,6 +108,54 @@ export function createApplicationHomeAgentTransport(
       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: HomeAgentEventSocket[] = [];

package/packages/daemon/src/tui/mirror/runtime/application-home-agents-owner.ts

@@ -27,6 +27,9 @@ import {
 
 export type ApplicationHomeAgentPresentation = Pick<
   ApplicationHomeSurfaceProps,
+  | "agentFilterLabel"
+  | "onCycleAgentMachine"
+  | "onToggleAgentAttention"
   | "agentRoster"
   | "agentSelection"
   | "agentInputActive"
@@ -197,6 +200,7 @@ export function createApplicationHomeAgentsOwner(options: {
 
 /** Compose Home navigation with competing chrome intents; physical input stays in the root. */
 export function createApplicationHomeNavigationOwner(options: {
+  readonly fleetHome?: ApplicationHomeAgentPresentation;
   readonly fleetCommands?: () => readonly ApplicationPaletteCommand[];
   readonly openFleet?: (
     command: Exclude<ApplicationPaletteCommand, string>,
@@ -236,7 +240,7 @@ export function createApplicationHomeNavigationOwner(options: {
   );
   const homeAgents = createApplicationHomeAgentsOwner({
     catalog: options.catalog.snapshot,
-    active: () => options.activeSurface() === "home",
+    active: () => !options.fleetHome && options.activeSurface() === "home",
     inputActive: () =>
       options.activeSurface() === "home" &&
       !paneRename.draft() &&
@@ -307,5 +311,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/src/tui/mirror/runtime/application-home-agents.ts

@@ -1,10 +1,19 @@
-import type { AgentActivity, ApplicationShellResourceV2 } from "@tmux-ide/contracts";
+import type {
+  AgentActivity,
+  ApplicationShellResourceV2,
+  TmuxServerScope,
+} from "@tmux-ide/contracts";
 
 import type { ApplicationHomeCatalogSession } from "./application-home-catalog.ts";
 import { terminalAgentStatusLabel } from "./application-terminal-workspace-policy.ts";
 
 export interface HomeAgentRow {
   readonly key: string;
+  readonly machineId?: string;
+  readonly machineLabel?: string;
+  readonly server?: TmuxServerScope;
+  readonly serverLabel?: string;
+  readonly disabled?: boolean;
   readonly sessionKey: string;
   readonly sessionName: string;
   readonly liveSessionId: string;
@@ -56,11 +65,13 @@ export function projectHomeAgentRows(
   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:

package/packages/daemon/src/tui/mirror/runtime/application-home-catalog-owner.ts

@@ -6,6 +6,7 @@ import {
   moveHomeCatalogSelection,
   selectedHomeCatalogIndex,
   type ApplicationHomeCatalog,
+  type ApplicationHomeCatalogSession,
   type ApplicationHomeCatalogSnapshot,
 } from "./application-home-catalog.ts";
 import { createFleetSession } from "./fleet-lifecycle-client.ts";
@@ -26,6 +27,7 @@ export interface ApplicationHomeCatalogOwnerOptions {
   readonly lifecycle: Pick<TuiApplicationLifecycle, "registerCloser">;
   readonly automaticOpen: boolean;
   readonly automaticOpenAllowed?: () => boolean;
+  readonly openCatalogSession?: (session: ApplicationHomeCatalogSession) => Promise<unknown> | void;
   readonly startGeneration: (sessionName: string) => Promise<unknown> | void;
   readonly setNote?: (note: string | null) => void;
   readonly catalog?: ApplicationHomeCatalog;
@@ -85,7 +87,12 @@ export function createApplicationHomeCatalogOwner(
     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) setSelectedSessionId(null);
@@ -120,8 +127,11 @@ export function createApplicationHomeCatalogOwner(
         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;