super-dsh 0.1.4 → 0.1.5-a

package/superd-hub/dist/switch-core.js

@@ -0,0 +1,734 @@
+/**
+ * Switch orchestration core (native UI fusion, plan Task 4) — the pure logic
+ * behind the in-page agent switch: storage-namespace key computation, the
+ * session landing decision over the persisted `dsh.sessions.current`
+ * selection, the agent-selector click-interception decision (a fusion page
+ * never navigates on a left click — spec: 融合页 = state 切换，拦截 click，无导航;
+ * T-B: consumed by the Hub UI surfaces, the sole switch surface since the
+ * RuntimeSeat retirement), and the fallback state machine (timeout or
+ * roster-probe failure → revert to native + a visible toast, never a page
+ * lock).
+ *
+ * Host-half on purpose: plain TS with every effect injected through
+ * {@link SwitchHost} — no DOM, no client imports — so `test/client-switch.test.mjs`
+ * imports it from `dist/` like every other host module. The client half
+ * (`src/client/switch.ts`) builds the real host face from the client context:
+ * the `__SUPERD_UI_STATE__` atom (Task 3), `ctx.connection`,
+ * `ctx.uiWorkspace`, the Task-3 namespaced `Storage`, the control-plane
+ * roster fetch, and a minimal self-owned toast overlay.
+ *
+ * Orchestration sequence (spec §3.5 as amended 2026-09-26, T-A + T-F
+ * errata; user rulings 7/8 and the T-F ruling "按原生的语义去理解…把这个
+ * last visit session 也做一下"):
+ *   1. `setAgent(label)` — state + NS swap immediately; subsequent requests
+ *      demux to the target world (Task 3's call-time patches read the atom).
+ *   2. `reconnect()` — the generation re-opens against the retargeted data
+ *      plane; the gateway emits `connection/reset` on establishment, the
+ *      designed "wire-derived caches must repull" signal, so sessions /
+ *      config / theme re-derive on their own. Nothing navigates before the
+ *      repull: the chat area is never cleared and no loading skeleton is
+ *      inserted — old content stays in place awaiting the landing.
+ *   3. Session landing (T-F: NATIVE restore semantics) — upstream's
+ *      fresh-load restore is `watchNavigation`/`restoreSelection`
+ *      (navigation.ts:284-347): it fires only when BOTH `workspaces.list`
+ *      and `sessions.list` reached phase `'ready'`, and then walks
+ *      `saved.subagentAddress` → `saved.sessionId` looked up in the FRESH
+ *      `sessions.byId` (stale-proof) → recent-workspace → the fresh-boot
+ *      default workspace. The landing replicates exactly that: it fires once
+ *      when BOTH wire-derived caches have installed fresh post-establishment
+ *      baselines ({@link observeCachesRefreshed} — the T-A gate watched
+ *      `workspaces.list` alone, so a plane whose sessions list landed later
+ *      served stale rows to the decision and broke native's own
+ *      last-visited restore; T-G additionally holds the gate while a
+ *      persisted pointer has not yet joined the freshly minted INCREMENTAL
+ *      sessions list — membership via `byId` — firing on membership or on
+ *      the quiet-window ladder, {@link LANDING_QUIET_MS}, so partial-list
+ *      first edges stop laddering every switch into a brand-new session),
+ *      then reads the target NS's persisted
+ *      `dsh.sessions.current` (the NS swap has long since happened) and
+ *      executes {@link planRestoreLanding}'s precedence through the public
+ *      faces. The landing is BOUNDED: if the baselines never install within
+ *      one further fallback window after the settle, a staleness watchdog
+ *      disarms it — an armed landing never outlives its switch by more than
+ *      that window (the safe direction: no landing at all beats a late
+ *      surprise navigation).
+ *   4. Fallback: no generation within {@link SWITCH_FALLBACK_MS}, or a failed
+ *      roster probe → `setAgent('native')` + `reconnect()` back to the native
+ *      plane + toast. A revert also cancels a pending landing — a
+ *      reverted switch never lands.
+ *
+ * Upstream anchors (dsh-v0.1.7-rc.1):
+ *   - `ctx.connection.reconnect()` — `packages/client/connection/src/client/index.ts`
+ *     `ConnectionHandle.reconnect` (declared :148, wired :264-266); the
+ *     controller resets retry progression and replaces the current attempt
+ *     immediately (`connection.ts:113-121`).
+ *   - `connection/reset` — emitted by the gateway client on every generation
+ *     establishment (`packages/api/gateway/src/client/index.ts:169`),
+ *     declared as the repull signal
+ *     (`packages/client/connection/src/client/index.ts:9-17`).
+ *   - `uiWorkspace.openSession(target)` / `startSession(workspaceId?)` /
+ *     `openWorkspace(workspaceId)` — the navigation face
+ *     (`packages/client/ui-workspace/src/client/navigation.ts:34-92`);
+ *     `SessionTarget = SessionId | SubagentAddress`
+ *     (`packages/api/session-controller/src/client/contract/sessions.ts:22`).
+ *   - `watchNavigation` / `restoreSelection` — the fresh-load restore this
+ *     landing replicates (`navigation.ts:284-347`): both-lists ready gate
+ *     (:292), `subagentAddress` first (:320-323), the fresh-`byId` session
+ *     lookup with the blank-reuse nuance (:324-335), `recentWorkspace`
+ *     fallback (:337, the tie-break at :434-453), and
+ *     `initializeDefaultWorkspace` on a fresh boot (:338-342, :349-361).
+ *   - `startSession()`'s workspace resolution — `workspaceId ??
+ *     currentWorkspaceId ?? recent` over the wire-derived `workspaces.list`
+ *     / `sessions.list` snapshots (`navigation.ts:223-238`); `connectWorkspace`
+ *     → `reuseOrCreateBlank` reuses the pointer's own blank whenever the
+ *     private restore path would (:179-198).
+ *   - The wire-derived stores: `workspaces.list` installs fresh data only
+ *     through its follow-stream baseline (`packages/api/workspace-controller/src/client/model.ts`
+ *     `replaceBaseline` → `installViews`, a new items array every install);
+ *     `sessions.list` is projected with a fresh `ids` array on every manager
+ *     change (`packages/api/session-controller/src/client/sessions/service.ts:607-677`)
+ *     — array identity is the freshness token for both.
+ *   - `dsh.sessions.current` — the per-tab last-selection store
+ *     (`navigation.ts:130-131`); its restore reads `subagentAddress` first,
+ *     then `sessionId` (`navigation.ts:319-330`) — {@link parseLandingTarget}
+ *     keeps that precedence. The store hydrates once at page boot and
+ *     persists on write (`packages/client/store/src/index.ts:155-174`), so
+ *     the landing read must go through the namespaced `Storage` (Task 3
+ *     patch 5), which prefixes `'<label>:'` at call time.
+ *
+ * @module @pgmi-builds/superd-hub/switch-core
+ */
+/** The active-agent label meaning the native (ctx0) data plane. */
+export const NATIVE_AGENT = 'native';
+/** The persisted last-selection key ui-workspace owns (survey §2.6). */
+export const SESSIONS_CURRENT_KEY = 'dsh.sessions.current';
+/**
+ * The fallback window: how long a switch may wait for the target world's
+ * generation (mux re-open + repull) before reverting to native. A
+ * human-scale constant; Task 5's config face may expose it later.
+ */
+export const SWITCH_FALLBACK_MS = 10_000;
+/**
+ * The membership-wait quiet window (T-G): after both navigation caches are
+ * fresh, a persisted pointer the sessions list has not shown yet holds the
+ * landing gate — the list is minted INCREMENTALLY post-reconnect (upstream
+ * `handleSessionAdded` applies one session at a time, each application
+ * re-projecting the store with a fresh `ids` array, service.ts:677), so the
+ * first fresh edge sees a partial `byId` that legitimately lacks the
+ * pointer's session. The gate fires on membership; while the pointer is
+ * still absent, this window of list SILENCE (no `ids` identity change) is
+ * the concession point: the gate fires anyway and the plan takes the ladder
+ * — an honest miss, because a stored blank pointer legitimately never
+ * appears (matching upstream's own boot restore of a stale/absent id). An
+ * identity change during the window restarts it (the list is still growing).
+ * The machine's post-settle staleness watchdog remains the hard bound on
+ * the whole wait.
+ */
+export const LANDING_QUIET_MS = 600;
+/**
+ * The storage namespace for an active agent: native prefixes nothing
+ * (byte-identical to stock behavior), a foreign agent owns `'<label>:'`.
+ * Mirrors Task 3's storage patch (`ns()` in fusion-transport).
+ */
+export function storageNamespace(label) {
+    return typeof label === 'string' && label !== '' && label !== NATIVE_AGENT ? `${label}:` : '';
+}
+/** The full storage key for `key` while `label` is the active agent. */
+export function namespacedKey(label, key) {
+    return `${storageNamespace(label)}${key}`;
+}
+/**
+ * The persisted-selection parse feeding {@link planRestoreLanding}.
+ *
+ * A value is navigable when it parses to a ui-workspace `MainSelection`
+ * carrying a usable `SessionTarget`: a non-null `subagentAddress` object
+ * wins (upstream restore order), else a non-empty string `sessionId`.
+ * Everything else — no value, a read failure (surfaced here as `null`), a
+ * parse failure, an unusable shape — parses to `null` and the plan falls to
+ * the recent-workspace / default-workspace ladder.
+ *
+ * @returns the subagent address object, the session id string, or `null`.
+ */
+export function parseLandingTarget(raw) {
+    if (typeof raw !== 'string' || raw === '')
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const selection = parsed;
+    if (selection.subagentAddress !== undefined && selection.subagentAddress !== null
+        && typeof selection.subagentAddress === 'object') {
+        return selection.subagentAddress;
+    }
+    if (typeof selection.sessionId === 'string' && selection.sessionId !== '')
+        return selection.sessionId;
+    return null;
+}
+/**
+ * The most-recent workspace per upstream `recentWorkspace`
+ * (navigation.ts:434-453): the latest member-session `updatedAt` wins, a
+ * workspace with no listed sessions falls back to its `createdAt`.
+ */
+function recentWorkspaceId(items, byId) {
+    let selected;
+    let selectedTime = Number.NEGATIVE_INFINITY;
+    for (const workspace of items) {
+        let latest = Number.NEGATIVE_INFINITY;
+        for (const sessionId of workspace.sessionIds) {
+            const session = byId[sessionId];
+            if (session !== undefined && typeof session.updatedAt === 'number') {
+                latest = Math.max(latest, session.updatedAt);
+            }
+        }
+        if (latest === Number.NEGATIVE_INFINITY && workspace.createdAt !== undefined) {
+            latest = Date.parse(workspace.createdAt);
+        }
+        if (selected === undefined || latest > selectedTime) {
+            selected = workspace.workspaceId;
+            selectedTime = latest;
+        }
+    }
+    return selected;
+}
+/**
+ * The landing decision with NATIVE restore semantics (T-F): replicate
+ * upstream `restoreSelection` (navigation.ts:318-347) against the fresh
+ * caches and the parsed persisted selection ({@link parseLandingTarget}'s
+ * result, which already applies the `subagentAddress`-first precedence).
+ *
+ *   - `subagentAddress` → open it directly, no cache consultation
+ *     (navigation.ts:320-323).
+ *   - `sessionId` found in the FRESH `byId`: non-blank — or blank but
+ *     workspace-less — opens the id (navigation.ts:324-329); blank with a
+ *     workspace resolves to that workspace (navigation.ts:333-335's private
+ *     `reuseBlank` + :337's `workspace.workspaceId` target — the public
+ *     `startSession(workspaceId)` face covers both: its `connectWorkspace`
+ *     → `reuseOrCreateBlank` reuses the pointer's own blank whenever the
+ *     private pre-check would pass, because the eligibility scan is the
+ *     same).
+ *   - A stale id (absent from the fresh `byId`) falls through to the
+ *     no-pointer ladder exactly as upstream's `summary === undefined` does.
+ *   - No pointer / stale pointer: the recent workspace gets the new-session
+ *     flow (navigation.ts:337); both lists empty is the fresh boot and
+ *     mirrors `initializeDefaultWorkspace` (navigation.ts:338-342).
+ *   - `caches` unavailable (the host's read failed) → `undefined`: land
+ *     nothing — no landing beats a wrong one. Same for the degenerate
+ *     zero-workspaces-with-sessions shape, where upstream simply leaves the
+ *     view as it is (no target, both-empty guard false, :337-342).
+ *
+ * @param parsed - the persisted-selection parse ({@link parseLandingTarget}).
+ * @param caches - the fresh both-lists snapshots, or `undefined` unreadable.
+ * @returns the action to execute, or `undefined` to land nothing.
+ */
+export function planRestoreLanding(parsed, caches) {
+    if (caches === undefined)
+        return undefined;
+    if (parsed !== null && typeof parsed === 'object') {
+        return { kind: 'open-session', target: parsed };
+    }
+    if (typeof parsed === 'string' && parsed !== '') {
+        const summary = caches.sessions.byId[parsed];
+        if (summary !== undefined) {
+            const workspace = caches.workspaces.items.find((item) => item.sessionIds.includes(parsed));
+            if (summary.blank !== true || workspace === undefined) {
+                return { kind: 'open-session', target: parsed };
+            }
+            return { kind: 'start-session', workspaceId: workspace.workspaceId };
+        }
+    }
+    const target = recentWorkspaceId(caches.workspaces.items, caches.sessions.byId);
+    if (target !== undefined)
+        return { kind: 'start-session', workspaceId: target };
+    if (caches.workspaces.items.length === 0 && caches.sessions.ids.length === 0) {
+        return { kind: 'default-workspace' };
+    }
+    return undefined;
+}
+/**
+ * The caches-fresh gate behind the deferred landing (T-F; T-G made it
+ * pointer-membership-aware): fires `listener` AT MOST once, when BOTH
+ * navigation caches demonstrably hold the TARGET plane's data — the
+ * client-face equivalent of upstream's both-lists ready gate
+ * (`watchNavigation`, navigation.ts:292: `workspace.phase !== 'ready'
+ * || sessions.phase !== 'ready'` → return).
+ *
+ * The freshness token is each snapshot's `items` ARRAY IDENTITY: upstream's
+ * workspace model mints a new array on every baseline install
+ * (`installViews` → `[...installed.values()]`, model.ts:398) and the session
+ * list projection mints a fresh `ids` array on every manager change
+ * (service.ts:607-677), while carrier churn keeps references. The gate arms
+ * at the first generation establishment OBSERVED BY ITS OWN subscription —
+ * the anchors are retaken there, and nothing before that point can pass, so
+ * the dying old plane's last increments racing the reconnect are absorbed;
+ * the first replacements after establishment are the target plane's
+ * baselines. The `phase === 'ready'` checks ride along as a guard against a
+ * page whose first baseline never arrived. Both edges are tracked
+ * independently, in either arrival order (the T-A gap: watching workspaces
+ * alone let a late sessions baseline leave the pointer lookup reading stale
+ * `byId` rows).
+ *
+ * T-G — the pointer holds the gate. The sessions list is minted
+ * INCREMENTALLY after the reconnect (one `handleSessionAdded` per session,
+ * each re-projecting the store with a fresh `ids` array), so the first fresh
+ * edge sees a partial `byId` that legitimately lacks the pointer's session;
+ * consuming the landing there laddered every switch into a brand-new
+ * session (the browser-proven defect). When a pointer exists (the injected
+ * {@link LandingGateOptions.pointerSessionId} face, read at decision time),
+ * the gate therefore does NOT fire on the first fresh edge. It fires when:
+ *   - the sessions list CONTAINS the pointer's session — the membership
+ *     face (`byId`, consulted on EVERY sessions notification: `byId` can
+ *     gain a row without a new `ids` identity, service.ts:565), or
+ *   - the sessions list has gone QUIET — no `ids` identity change for the
+ *     configured quiet window ({@link LANDING_QUIET_MS}; an identity change
+ *     during the window restarts it) while the pointer is still absent:
+ *     the honest miss, firing with the ladder exactly like upstream's boot
+ *     restore of a stored id its fresh list does not know.
+ * No pointer → the first fresh edge fires, byte-identical to T-F (the
+ * fresh-boot path). The machine's post-settle staleness watchdog bounds the
+ * whole membership wait: it disposes this gate, which also cancels a
+ * running quiet window.
+ *
+ * Establishment strictly precedes any target-plane baseline (the follow
+ * streams re-open on top of the established generation), so a fire implies
+ * both "generation established" and "repull landed" — the two preconditions
+ * of a correct landing resolution.
+ *
+ * Host-half pure logic: the client binding composes it with the real
+ * `ctx.workspaces.list` + `ctx.sessions.list` stores and the connection
+ * generation observable; the machine consumes it through
+ * {@link SwitchHost.onCachesRefreshed}.
+ *
+ * @returns the disposer stopping all three subscriptions (and the quiet window).
+ */
+export function observeCachesRefreshed(workspaces, sessions, generation, listener, gate = {}) {
+    // Establishment is an event, not a level: a live OLD generation at arming
+    // time must not open the gate to that plane's churn. Monotonic — a later
+    // generation loss mints no arrays, a re-establishment retakes the anchors.
+    let established = false;
+    // At most once per subscription — the SwitchHost contract. (The machine
+    // also disposes its gate at fire time; this flag makes the factory honest
+    // on its own.)
+    let fired = false;
+    let workspacesAnchor = workspaces.getSnapshot().items;
+    let sessionsAnchor = sessions.getSnapshot().items;
+    let workspacesFresh = false;
+    let sessionsFresh = false;
+    // The quiet window's live handle, `undefined` while not holding.
+    let quietTimer;
+    const quietMs = gate.quietMs ?? LANDING_QUIET_MS;
+    const clearQuiet = () => {
+        if (quietTimer === undefined)
+            return;
+        if (gate.clearTimeout !== undefined)
+            gate.clearTimeout(quietTimer);
+        quietTimer = undefined;
+    };
+    const fire = () => {
+        if (fired)
+            return;
+        fired = true;
+        clearQuiet();
+        listener();
+    };
+    const pointerSessionId = () => {
+        try {
+            return gate.pointerSessionId?.();
+        }
+        catch {
+            return undefined; // a pointer read failure is the no-pointer path (same ladder)
+        }
+    };
+    /**
+     * The decision point, run on every workspaces/sessions notification once
+     * establishment happened. `sessionsIdentityChanged` distinguishes a real
+     * list growth (restarts the quiet window) from a same-identity
+     * notification like publishRetention's byId-only set (consults
+     * membership, must NOT restart the window).
+     */
+    const check = (sessionsIdentityChanged) => {
+        if (fired || !established || !workspacesFresh || !sessionsFresh)
+            return;
+        const pointer = pointerSessionId();
+        if (pointer === undefined) {
+            fire(); // no pointer: the T-F first-fresh-edge behavior (fresh-boot path)
+            return;
+        }
+        if (sessions.contains?.(pointer)) {
+            fire(); // membership: the pointer's session has arrived in the fresh list
+            return;
+        }
+        // Holding: the pointer has not shown up in the (possibly still growing)
+        // list. A real identity change restarts the window; so does arriving
+        // here with no window running (the first hold).
+        if (sessionsIdentityChanged || quietTimer === undefined) {
+            clearQuiet();
+            if (gate.setTimeout !== undefined) {
+                quietTimer = gate.setTimeout(() => {
+                    quietTimer = undefined;
+                    fire(); // quiet + still no membership → the honest miss (the ladder)
+                }, quietMs);
+            }
+            // Without a timer face the hold is membership-only; the machine's
+            // watchdog remains the bound (it disposes this gate).
+        }
+    };
+    const disposeGeneration = generation.subscribe(() => {
+        if (generation.getSnapshot() === undefined)
+            return;
+        established = true;
+        workspacesFresh = false;
+        sessionsFresh = false;
+        clearQuiet(); // a re-establishment re-anchors: the old window's silence says nothing now
+        workspacesAnchor = workspaces.getSnapshot().items;
+        sessionsAnchor = sessions.getSnapshot().items;
+    });
+    const disposeWorkspaces = workspaces.subscribe(() => {
+        if (!established)
+            return;
+        const snapshot = workspaces.getSnapshot();
+        if (snapshot.phase === 'ready' && snapshot.items !== workspacesAnchor)
+            workspacesFresh = true;
+        check(false);
+    });
+    const disposeSessions = sessions.subscribe(() => {
+        if (!established)
+            return;
+        const snapshot = sessions.getSnapshot();
+        let identityChanged = false;
+        if (snapshot.phase === 'ready' && snapshot.items !== sessionsAnchor) {
+            sessionsFresh = true;
+            identityChanged = true;
+            // Retake the anchor so the NEXT same-reference notification is not
+            // mistaken for growth (quiet-window restart discipline).
+            sessionsAnchor = snapshot.items;
+        }
+        check(identityChanged);
+    });
+    return () => {
+        clearQuiet();
+        disposeWorkspaces();
+        disposeSessions();
+        disposeGeneration();
+    };
+}
+/**
+ * The agent-selector click-interception contract as a pure table (native UI
+ * fusion; originally landed for the sidebar-bottom RuntimeSeat, which T-B
+ * retired — the Hub UI surfaces (HubPage rows + the HubPanelIcon chevron
+ * menu) are now the sole switch surface and consume this SAME table, so the
+ * contract below is inherited verbatim).
+ *
+ *   - World page (`fusion: false`): no interception, no orchestration — the
+ *     real hyperlink navigates (spec §5 双半边).
+ *   - Fusion page, active entry: intercepted, no attempt — switching to the
+ *     active agent is a no-op, and the click must never fall through to the
+ *     anchor (an `href="/"` reload would discard the in-page switch state; a
+ *     foreign `href` would abandon the fused page entirely).
+ *   - Fusion page, inactive entry: intercepted and the attempt runs. The
+ *     attempt's `false` (orchestration unbound) still keeps the page: a
+ *     swallowed click beats silent navigation away from the fusion surface.
+ *
+ * Host-half pure logic so `test/client-switch.test.mjs` pins the table from
+ * `dist/`; the Hub surfaces map `preventDefault` onto the DOM event.
+ */
+export function seatClickDecision(input) {
+    if (!input.fusion)
+        return { preventDefault: false, attempted: false };
+    if (input.active)
+        return { preventDefault: true, attempted: false };
+    const attempted = input.attempt() === true;
+    return { preventDefault: true, attempted };
+}
+/**
+ * Which Hub UI roster row shows as the active agent (T-B: the Hub surfaces —
+ * HubPage rows and the HubPanelIcon chevron menu — are the sole switch
+ * surface after the RuntimeSeat retirement).
+ *
+ *   - Fusion page: the page atom's `activeAgent` — the switch state — decides
+ *     by roster key; the URL is irrelevant on a fused page. The `native`
+ *     entry participates like any other key.
+ *   - Non-fusion page (flag off; the UI's navigation arm is retired since
+ *     T-C): the mount path is the selection — the entry whose path equals
+ *     the page's normalized mount. The pure arm survives as contract; no
+ *     served page can hit the foreign case anymore.
+ *
+ * Host-half pure logic so `test/client-switch.test.mjs` pins it from `dist/`.
+ */
+export function hubRowActive(input) {
+    if (input.fusion)
+        return input.agentKey === input.activeAgent;
+    return input.agentPath === input.mountPath;
+}
+/** The degradation hint a Hub UI surface shows while the flag is off (T-E). */
+export const FUSION_OFF_HINT = 'fusion off — no foreign entry';
+/**
+ * The flag-off shape of the Hub UI switch surfaces (path-separation Part 2
+ * T-E closeout). With the per-label URL family retired (T-C) and the world
+ * web UIs disabled (T-D), a flag-OFF ctx0 page has NO foreign entry at all —
+ * and since T-C the Hub UI ships no hyperlinks either, so the smallest honest
+ * rendering is an inert roster with a visible degradation hint instead of a
+ * silently dead control:
+ *
+ *   - `available: true` (fusion page): the affordance renders — the HubPage
+ *     `switch` action and the HubPanelIcon chevron menu.
+ *   - `available: false` (flag off): the affordance is NOT rendered; the
+ *     roster stays informational and the surface shows the degradation hint
+ *     ({@link FUSION_OFF_HINT}) once (HubPage: a single chip under the
+ *     section head, not one per row). Nothing navigates — there is
+ *     nothing to navigate to.
+ *
+ * Host-half pure logic so `test/client-switch.test.mjs` pins it from `dist/`.
+ */
+export function switchAffordance(fusion) {
+    return fusion ? { available: true, hint: '' } : { available: false, hint: FUSION_OFF_HINT };
+}
+/**
+ * The active agent's display name for the Hub row's right-edge selector: the
+ * roster label of the atom's `activeAgent` key — the name the selector's
+ * `title` carries, since the row label itself is the constant `Hub`. A key the
+ * (seeded) roster does not know degrades to the raw key. `undefined`/empty
+ * (flag off, or no atom read) means "no active agent".
+ *
+ * Host-half pure logic so `test/client-switch.test.mjs` pins it from `dist/`.
+ */
+export function activeAgentName(activeAgent, roster) {
+    if (activeAgent === undefined || activeAgent === '')
+        return undefined;
+    return roster.find((row) => row.key === activeAgent)?.label ?? activeAgent;
+}
+/** Which machine one roster row groups under: the row's own machine (parser-guaranteed). */
+export function machineGroup(row) {
+    return row.machine;
+}
+/**
+ * Group a roster by machine for the HubPanelIcon chevron menu's native
+ * workspace-list look: one group per distinct `machineGroup` key, groups in
+ * first-appearance order, members keeping the roster's order inside their
+ * group. A single-group roster (today's local-only shape) renders exactly
+ * like the old flat list minus the card border.
+ *
+ * Host-half pure logic so `test/client-switch.test.mjs` pins it from `dist/`.
+ */
+export function machineGroups(rows) {
+    const groups = [];
+    const byMachine = new Map();
+    for (const row of rows) {
+        const machine = machineGroup(row);
+        let group = byMachine.get(machine);
+        if (group === undefined) {
+            group = { machine, agents: [] };
+            byMachine.set(machine, group);
+            groups.push(group);
+        }
+        group.agents.push(row);
+    }
+    return groups;
+}
+/**
+ * Build the switch machine over an injected {@link SwitchHost}.
+ *
+ * Only one attempt is ever armed at a time: starting a new switch finishes
+ * the previous one silently (timer cleared, subscription released, promise
+ * resolved) and cancels its pending landing, so a stale attempt can never
+ * revert or land over a newer switch. The landing cancel is held at
+ * CONTROLLER scope, not reached through the current-attempt pointer: the
+ * deferred landing deliberately survives the settle — which removes the
+ * attempt from `current` — so a supersede must still kill the armed landing
+ * of a PRIOR, ALREADY-SETTLED attempt (final-review round 2: without the
+ * controller-scope handle, a settled switch's landing fired over the newer
+ * switch's pointer-restored view).
+ */
+export function createSwitchController(host, options = {}) {
+    const fallbackMs = options.fallbackMs ?? SWITCH_FALLBACK_MS;
+    const quietWindowMs = options.quietWindowMs ?? LANDING_QUIET_MS;
+    let current;
+    // The cancel closure of the latest attempt's still-armed deferred landing,
+    // surviving that attempt's settle. Every subsequent run() disarms it first
+    // (and clears it the moment the landing fires), whatever state the arming
+    // attempt is in.
+    let armedLanding;
+    return {
+        run(label) {
+            const prior = current;
+            return new Promise((resolve) => {
+                let timer;
+                // The landing staleness watchdog: armed at settle while the landing
+                // is still pending; one more fallback window later the landing is
+                // disarmed. A baseline that never installs must not leave a landing
+                // armed forever — a much-later unrelated cache replacement would
+                // otherwise fire a surprise blank chat long after the switch.
+                let watchdog;
+                let disposer = () => { };
+                let disposeLanding = () => { };
+                let landingArmed = false;
+                const cancelWatchdog = () => {
+                    if (watchdog === undefined)
+                        return;
+                    host.clearTimeout(watchdog);
+                    watchdog = undefined;
+                };
+                const attempt = {
+                    finished: false,
+                    dead: false,
+                    cancelLanding() {
+                        attempt.dead = true;
+                        landingArmed = false;
+                        disposeLanding();
+                        disposeLanding = () => { };
+                        cancelWatchdog();
+                    },
+                    /** The one exit: disarm, release, resolve — a revert only adds effects first. */
+                    finish() {
+                        if (attempt.finished)
+                            return;
+                        attempt.finished = true;
+                        host.clearTimeout(timer);
+                        disposer();
+                        if (current === attempt)
+                            current = undefined;
+                        // The landing survives the settle — but not indefinitely: while
+                        // still pending, bound it to one more fallback window.
+                        if (landingArmed)
+                            watchdog = host.setTimeout(() => { attempt.cancelLanding(); }, fallbackMs);
+                        resolve();
+                    },
+                };
+                // Supersede, landing first: the previous attempt's still-armed
+                // deferred landing dies through the controller-scope handle —
+                // INCLUDING a settled attempt, which is already out of `current`
+                // (the landing outlives the settle by design). The newer switch owns
+                // the page from here; a stale landing must never fire over it.
+                if (armedLanding !== undefined) {
+                    const cancelPriorLanding = armedLanding;
+                    armedLanding = undefined;
+                    cancelPriorLanding();
+                }
+                if (prior !== undefined && !prior.finished)
+                    prior.finish();
+                current = attempt;
+                const revert = (reason) => {
+                    if (attempt.finished || current !== attempt)
+                        return;
+                    attempt.cancelLanding();
+                    try {
+                        host.setAgent(NATIVE_AGENT);
+                    }
+                    catch { /* keep going: the fallback must land the page somewhere */ }
+                    try {
+                        host.reconnect();
+                    }
+                    catch { /* the native plane's own recovery loop stays in charge */ }
+                    try {
+                        host.toast(`Super D: switch to ${label} failed (${reason === 'timeout' ? 'no response' : 'target not reachable'}) — back to native.`);
+                    }
+                    catch { /* feedback is best-effort */ }
+                    attempt.finish();
+                };
+                // Step 1: state + NS swap — subsequent requests demux to `label`.
+                try {
+                    host.setAgent(label);
+                }
+                catch { /* the atom face is guarded; landing still reads the old NS */ }
+                // Step 2: replace the generation attempt against the retargeted plane.
+                // Nothing navigates here (T-F): every landing — the pointer included —
+                // defers to the both-lists gate, because native restore semantics
+                // resolve ONLY against fresh, plane-consistent data (the pre-reconnect
+                // pointer landing read stale sessions and broke native's own
+                // last-visited restore).
+                try {
+                    host.reconnect();
+                }
+                catch { /* fallback below still applies */ }
+                // Step 3: the fallback race — generation establishment settles, the
+                // timer and the roster probe revert.
+                timer = host.setTimeout(() => { revert('timeout'); }, fallbackMs);
+                disposer = host.onGenerationEstablished(() => {
+                    if (attempt.finished || current !== attempt)
+                        return;
+                    attempt.finish();
+                });
+                // The landing (T-F): NATIVE restore semantics. Fires once BOTH
+                // wire-derived caches are fresh, then reads the target NS's persisted
+                // selection (the NS swap happened in step 1; the active agent only
+                // changes again on a revert, which kills this landing first) and
+                // executes the restoreSelection precedence through the public faces.
+                // Deliberately NOT released by `finish()`: the baselines land after
+                // the generation, so the landing must survive the settle; a revert
+                // kills it directly and a supersede kills it through the
+                // controller-scope handle (a settled attempt included — see the
+                // run() preamble). Fires at most once; the settle arms the staleness
+                // watchdog that disarms it if the baselines never install.
+                landingArmed = true;
+                const cancelThisLanding = () => { attempt.cancelLanding(); };
+                armedLanding = cancelThisLanding;
+                // T-G: the machine's side of the membership-aware gate. The pointer
+                // face reads the SAME persisted-selection source the landing callback
+                // below reads at fire time — at gate DECISION time the NS swap has
+                // long since happened (step 1 precedes the reconnect), and the active
+                // agent only changes again on a revert/supersede, both of which kill
+                // this landing before the read could go stale. A throwing read is
+                // `undefined`: the no-pointer path, the same ladder a failed read
+                // reaches through the callback's own guard.
+                const gateRequest = {
+                    pointerSessionId: () => {
+                        let parsed;
+                        try {
+                            parsed = parseLandingTarget(host.readPersistedSelection());
+                        }
+                        catch {
+                            return undefined;
+                        }
+                        return typeof parsed === 'string' && parsed !== '' ? parsed : undefined;
+                    },
+                    quietMs: quietWindowMs,
+                    setTimeout: (fn, ms) => host.setTimeout(fn, ms),
+                    clearTimeout: (handle) => host.clearTimeout(handle),
+                };
+                disposeLanding = host.onCachesRefreshed(() => {
+                    if (attempt.dead)
+                        return;
+                    if (armedLanding === cancelThisLanding)
+                        armedLanding = undefined;
+                    landingArmed = false;
+                    cancelWatchdog();
+                    disposeLanding();
+                    disposeLanding = () => { };
+                    let caches;
+                    try {
+                        caches = host.readRestoreCaches();
+                    }
+                    catch {
+                        caches = undefined; // unreadable caches land nothing (safe direction)
+                    }
+                    let raw = null;
+                    try {
+                        raw = host.readPersistedSelection();
+                    }
+                    catch {
+                        raw = null;
+                    }
+                    const plan = planRestoreLanding(parseLandingTarget(raw), caches);
+                    if (plan === undefined)
+                        return;
+                    try {
+                        if (plan.kind === 'open-session')
+                            host.openSession(plan.target);
+                        else if (plan.kind === 'start-session')
+                            host.startSession(plan.workspaceId);
+                        else
+                            host.openDefaultWorkspace();
+                    }
+                    catch { /* landing never throws */ }
+                }, gateRequest);
+                void host.probeTarget(label).then((alive) => { if (alive !== true)
+                    revert('probe'); }, () => { revert('probe'); });
+            });
+        },
+    };
+}