super-dsh 0.1.9 → 0.1.10-e

package/superd-hub/dist/client/runtime-settings-api.d.ts

@@ -0,0 +1,76 @@
+/**
+ * runtime-settings-api.ts — the browser half of a runtime's settings panel.
+ *
+ * The panel's config belongs to the ADAPTER, so nothing here knows what an auth
+ * method is: it posts a `client-request` envelope at the runtime's own world and
+ * hands the adapter's answer to `parseAuthView` (agent-settings.ts).
+ *
+ *    POST /hub/api?agent=agy
+ *    { type:'client-request', rpcId, method:'agyAuth/get'|'agyAuth/set',
+ *      payload:{ args: {} | { request: { mode } } } }
+ *
+ * `/hub/api` is the hub family's prefix mount (`hub-route.ts`), which forwards
+ * `method` verbatim to the addressed world's `typertGateway`. The path needs no
+ * `CONTROL` exemption in fusion-transport.ts: the rewrite only touches same-origin
+ * `/api/...` paths, and `/hub/...` is never one of them.
+ *
+ * Node-safe: no DOM reach at module scope and `fetch` is injectable, so
+ * test/client-runtime-settings.test.mjs pins the envelope and every failure
+ * branch under `node --test` (the mesh-api.ts precedent).
+ *
+ * @module superd-hub/client/runtime-settings-api
+ */
+import { type RuntimeAuthView, type RuntimeProvidersView } from './agent-settings.js';
+/** Structural slice of `fetch` — the bundle uses the global, tests inject a stub. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** One rpcId for request/response correlation. `randomUUID` needs a secure context. */
+export declare function mintRpcId(): string;
+/** The wire body of one unary call. */
+export interface ClientRequestEnvelope {
+    type: 'client-request';
+    rpcId: string;
+    method: string;
+    payload: {
+        args: Record<string, unknown>;
+    };
+}
+/** Build the envelope for one panel call (exported so tests pin the exact wire shape). */
+/** The operation names the adapter Remotes accept (auth ladder + providers). */
+export type RuntimeSettingsOp = 'get' | 'set' | 'save' | 'remove';
+export declare function settingsEnvelope(namespace: string, op: RuntimeSettingsOp, args: Record<string, unknown>): ClientRequestEnvelope;
+/** What a caller can do with a failed panel call — kept structural for the tests. */
+declare function messageOf(error: unknown): string;
+/**
+ * One unary call at a runtime's world, unwrapped to the RPC's value.
+ *
+ * Every failure mode is reported as a thrown `Error` carrying the adapter's own
+ * message where one exists: a transport failure, a malformed answer, and the
+ * gateway's business error (`{ok:false,error}`) must not look alike to the panel.
+ *
+ * @param agentKey - roster key addressing the world (`?agent=`).
+ * @param namespace - the adapter's Remote namespace (`agyAuth`).
+ * @param op - the Remote method.
+ * @param args - exact named wire arguments.
+ * @param doFetch - fetch implementation (tests inject).
+ * @returns the raw RPC value.
+ * @throws {Error} on transport, framing, or gateway failure.
+ */
+export declare function callRuntimeSettings(agentKey: string, namespace: string, op: RuntimeSettingsOp, args: Record<string, unknown>, doFetch?: FetchLike): Promise<unknown>;
+/** Read one runtime's panel state, parsed. */
+export declare function fetchAuthView(agentKey: string, namespace: string, doFetch?: FetchLike): Promise<RuntimeAuthView>;
+/** Adopt one auth form (`null` clears the explicit choice). */
+export declare function setAuthMode(agentKey: string, namespace: string, mode: string | null, doFetch?: FetchLike): Promise<RuntimeAuthView>;
+/** Read the multi-provider state of one runtime. */
+export declare function fetchProvidersView(agentKey: string, namespace: string, doFetch?: FetchLike): Promise<RuntimeProvidersView>;
+/**
+ * Add or edit one provider in the adapter's list. Which provider a session runs
+ * on is DSH's own per-session model selection, so this touches no active half.
+ */
+export declare function saveProvider(agentKey: string, namespace: string, provider: unknown, doFetch?: FetchLike): Promise<RuntimeProvidersView>;
+/** Drop one provider from the list. Does not rewrite the runtime's own config. */
+export declare function removeProvider(agentKey: string, namespace: string, id: string, doFetch?: FetchLike): Promise<RuntimeProvidersView>;
+export { messageOf as settingsErrorText };

package/superd-hub/dist/client/runtime-settings-api.js

@@ -0,0 +1,137 @@
+/**
+ * runtime-settings-api.ts — the browser half of a runtime's settings panel.
+ *
+ * The panel's config belongs to the ADAPTER, so nothing here knows what an auth
+ * method is: it posts a `client-request` envelope at the runtime's own world and
+ * hands the adapter's answer to `parseAuthView` (agent-settings.ts).
+ *
+ *    POST /hub/api?agent=agy
+ *    { type:'client-request', rpcId, method:'agyAuth/get'|'agyAuth/set',
+ *      payload:{ args: {} | { request: { mode } } } }
+ *
+ * `/hub/api` is the hub family's prefix mount (`hub-route.ts`), which forwards
+ * `method` verbatim to the addressed world's `typertGateway`. The path needs no
+ * `CONTROL` exemption in fusion-transport.ts: the rewrite only touches same-origin
+ * `/api/...` paths, and `/hub/...` is never one of them.
+ *
+ * Node-safe: no DOM reach at module scope and `fetch` is injectable, so
+ * test/client-runtime-settings.test.mjs pins the envelope and every failure
+ * branch under `node --test` (the mesh-api.ts precedent).
+ *
+ * @module superd-hub/client/runtime-settings-api
+ */
+import { parseAuthView, parseProvidersView } from './agent-settings.js';
+/** One rpcId for request/response correlation. `randomUUID` needs a secure context. */
+export function mintRpcId() {
+    const webCrypto = globalThis.crypto;
+    if (webCrypto !== undefined && typeof webCrypto.randomUUID === 'function')
+        return webCrypto.randomUUID();
+    if (webCrypto !== undefined && typeof webCrypto.getRandomValues === 'function') {
+        const bytes = webCrypto.getRandomValues(new Uint8Array(16));
+        return [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+    }
+    return `rpc-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export function settingsEnvelope(namespace, op, args) {
+    return {
+        type: 'client-request',
+        rpcId: mintRpcId(),
+        method: `${namespace}/${op}`,
+        payload: { args },
+    };
+}
+/** What a caller can do with a failed panel call — kept structural for the tests. */
+function messageOf(error) {
+    if (error !== null && typeof error === 'object' && typeof error.message === 'string') {
+        return error.message;
+    }
+    return String(error);
+}
+/**
+ * One unary call at a runtime's world, unwrapped to the RPC's value.
+ *
+ * Every failure mode is reported as a thrown `Error` carrying the adapter's own
+ * message where one exists: a transport failure, a malformed answer, and the
+ * gateway's business error (`{ok:false,error}`) must not look alike to the panel.
+ *
+ * @param agentKey - roster key addressing the world (`?agent=`).
+ * @param namespace - the adapter's Remote namespace (`agyAuth`).
+ * @param op - the Remote method.
+ * @param args - exact named wire arguments.
+ * @param doFetch - fetch implementation (tests inject).
+ * @returns the raw RPC value.
+ * @throws {Error} on transport, framing, or gateway failure.
+ */
+export async function callRuntimeSettings(agentKey, namespace, op, args, doFetch) {
+    const send = doFetch ?? ((input, init) => fetch(input, init));
+    const envelope = settingsEnvelope(namespace, op, args);
+    const response = await send(`/hub/api?agent=${encodeURIComponent(agentKey)}`, {
+        method: 'POST',
+        credentials: 'same-origin',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(envelope),
+    });
+    const text = await response.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`settings ${envelope.method}: unreadable answer (HTTP ${response.status})`);
+    }
+    const result = body?.result;
+    if (result === null || typeof result !== 'object') {
+        throw new Error(`settings ${envelope.method}: malformed answer (HTTP ${response.status})`);
+    }
+    const record = result;
+    if (record.ok === true)
+        return record.value;
+    const error = record.error;
+    if (error !== undefined && typeof error.message === 'string') {
+        throw new Error(error.message);
+    }
+    throw new Error(`settings ${envelope.method}: failed (HTTP ${response.status})`);
+}
+/** Read one runtime's panel state, parsed. */
+export async function fetchAuthView(agentKey, namespace, doFetch) {
+    const value = await callRuntimeSettings(agentKey, namespace, 'get', {}, doFetch);
+    const view = parseAuthView(value);
+    if (view === undefined)
+        throw new Error('settings: the runtime returned no usable auth options');
+    return view;
+}
+/** Adopt one auth form (`null` clears the explicit choice). */
+export async function setAuthMode(agentKey, namespace, mode, doFetch) {
+    const value = await callRuntimeSettings(agentKey, namespace, 'set', { request: { mode } }, doFetch);
+    const view = parseAuthView(value);
+    if (view === undefined)
+        throw new Error('settings: the runtime returned no usable auth options');
+    return view;
+}
+// --------------------------------- the providers bodies (codex P4, claude)
+// Same transport, same namespace rule (codexProviders, claudeProviders); only
+// the operation names and the argument shapes differ. Every call re-parses the
+// adapter's answer through `parseProvidersView`, so a malformed reply is an
+// error here rather than a half-rendered panel.
+function requireProvidersView(value) {
+    const view = parseProvidersView(value);
+    if (view === undefined)
+        throw new Error('settings: the runtime returned no usable provider list');
+    return view;
+}
+/** Read the multi-provider state of one runtime. */
+export async function fetchProvidersView(agentKey, namespace, doFetch) {
+    return requireProvidersView(await callRuntimeSettings(agentKey, namespace, 'get', {}, doFetch));
+}
+/**
+ * Add or edit one provider in the adapter's list. Which provider a session runs
+ * on is DSH's own per-session model selection, so this touches no active half.
+ */
+export async function saveProvider(agentKey, namespace, provider, doFetch) {
+    return requireProvidersView(await callRuntimeSettings(agentKey, namespace, 'save', { request: { provider } }, doFetch));
+}
+/** Drop one provider from the list. Does not rewrite the runtime's own config. */
+export async function removeProvider(agentKey, namespace, id, doFetch) {
+    return requireProvidersView(await callRuntimeSettings(agentKey, namespace, 'remove', { request: { id } }, doFetch));
+}
+export { messageOf as settingsErrorText };

package/superd-hub/dist/client/switch.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Client-half switch wiring (native UI fusion, plan Task 4): turns the pure
+ * {@link createSwitchController} machine into the page's `switchAgent`.
+ *
+ * The host face is assembled from exactly the sanctioned surfaces:
+ *   - the Task-3 page atom `__SUPERD_UI_STATE__` (setAgent = state + NS swap;
+ *     every later request demuxes through the call-time patches);
+ *   - the Task-3 namespaced `Storage` for the landing read — `getItem` is
+ *     read at call time against the ACTIVE label's `'<label>:'` namespace,
+ *     so the post-`setAgent` read of `dsh.sessions.current` lands in the
+ *     target world's tree without this module ever prefixing keys itself;
+ *   - `ctx.connection` (`reconnect()` + the generation observable — the
+ *     establishment leg of `connection/reset`);
+ *   - `ctx.uiWorkspace` (`openSession(target)` / `startSession(workspaceId?)`
+ *     / `openWorkspace(workspaceId)` — the navigation face; T-F executes the
+ *     restore precedence through these public faces only);
+ *   - `ctx.workspaces` (`list` — the workspace projection; T-F also reads
+ *     `initializeDefault` to mirror upstream's default-workspace boot path);
+ *   - `ctx.sessions` (T-F: the session projection — its `list` store is the
+ *     second freshness edge the landing gate watches, and its `ids`/`byId`
+ *     are what upstream `restoreSelection` resolves the pointer against,
+ *     navigation.ts:324; watching `workspaces.list` alone was the T-A gap
+ *     that broke native's own last-visited restore);
+ *   - the control-plane roster fetch (`/api/agent-runtime`, never rewritten)
+ *     as the probe: the target must still be a live roster entry;
+ *   - a minimal self-owned toast overlay for the revert feedback (upstream
+ *     has no public toast service; the overlay reads nothing from any other
+ *     component's DOM).
+ *
+ * The client entry (`index.ts`) binds once `connection` + `uiWorkspace`
+ * exist. The Hub UI surfaces (HubPage rows + the HubPanelIcon chevron menu —
+ * the sole switch surface since the T-B RuntimeSeat retirement) run every
+ * click through {@link seatClickDecision} (switch-core): on a fusion page
+ * the left click is intercepted with NO navigation — the orchestration bound
+ * or not; on a world page the flag global is absent, the fusion arm never
+ * runs, and the real hyperlink stays in charge (spec §5 双半边).
+ *
+ * @module superd-hub/client/switch
+ */
+import { type RestoreWorkspaceView } from '../switch-core.js';
+/** The Task-3 page-level state atom the fused page boots with. */
+export interface SuperdUiState {
+    /** The active agent label: `'native'` or a runtime key. */
+    readonly activeAgent: string;
+    setAgent(label: string): void;
+    subscribe(fn: (label: string) => void): () => void;
+}
+/** Structural face of `ctx.connection` — the parts the switch machine needs. */
+export interface SwitchConnection {
+    reconnect(): void;
+    generation: {
+        getSnapshot(): unknown;
+        subscribe(listener: () => void): () => void;
+    };
+}
+/** Structural face of `ctx.uiWorkspace` — the navigation face (public only). */
+export interface SwitchUiWorkspace {
+    openSession(target: string | object): void;
+    openWorkspace(workspaceId: string): void | Promise<void>;
+    startSession(workspaceId?: string): void;
+}
+/**
+ * Structural face of `ctx.workspaces` — the workspace projection whose
+ * baseline replacement is one of the TWO freshness edges the landing gate
+ * watches, plus `initializeDefault` for the default-workspace mirror (the
+ * same public method upstream's private `initializeDefaultWorkspace`
+ * calls). Present wherever `uiWorkspace` is: upstream's ui-workspace injects
+ * `workspaces` itself (ui-workspace/src/client/index.ts).
+ */
+export interface SwitchWorkspaces {
+    readonly list: {
+        getSnapshot(): {
+            items: readonly RestoreWorkspaceView[];
+            phase: unknown;
+        };
+        subscribe(listener: () => void): () => void;
+    };
+    initializeDefault(signal?: AbortSignal): Promise<{
+        workspaceId: string;
+    } | undefined>;
+}
+/** Structural slice of one `ctx.sessions.list` `byId` row the landing reads. */
+export interface SwitchSessionSummary {
+    readonly id: string;
+    readonly blank?: boolean;
+    readonly updatedAt?: number;
+}
+/**
+ * Structural face of `ctx.sessions` (T-F) — the session projection the
+ * landing pointer resolves against (upstream `restoreSelection` reads
+ * `sessions.byId`, navigation.ts:324) and the second freshness edge of the
+ * both-lists gate (the T-A gap: without it the gate could fire while `byId`
+ * still held the previous plane's rows). T-G: its `byId` is also the gate's
+ * membership face — the list is minted incrementally post-reconnect, so the
+ * gate holds until the pointer's session joins `byId` (or the list goes
+ * quiet) instead of trusting the first partial-list edge.
+ */
+export interface SwitchSessions {
+    readonly list: {
+        getSnapshot(): {
+            ids: readonly string[];
+            byId: Readonly<Record<string, SwitchSessionSummary>>;
+            phase: unknown;
+        };
+        subscribe(listener: () => void): () => void;
+    };
+}
+/** Whether this page is a fusion page: the baked flag global is present. */
+export declare function fusionPage(): boolean;
+/** The page atom, when the page carries one (it always does on a fusion page). */
+export declare function uiState(): SuperdUiState | undefined;
+/**
+ * Build the `SwitchHost.openDefaultWorkspace` action.
+ *
+ * dsh 0.2.0-rc.2 removed the request object from the Host's
+ * `workspaces.initializeDefault` Remote: the first-use directory and stored
+ * title are fixed and language-neutral (`default-workspace` under
+ * `<Documents>/deepseek-harness`), so the caller passes only its own lifetime
+ * signal. This module shipped the pre-0.2 `{ directoryName, title }` shape for
+ * a release cycle; the Host then received a plain object where it feeds
+ * `AbortSignal.any(...)`, EVERY empty-plane landing rejected, and the browser
+ * surfaced "Unable to create default workspace". Root-caused 2026-10-02 on
+ * the Hermes world — the only world whose registry was still empty after the
+ * 0.2.0-rc.2 upgrade, hence the only one that took the default-workspace
+ * branch. Exported so the call shape is unit-testable without the
+ * module-level single-bind guard.
+ *
+ * @param deps - the workspace projection and the navigation face.
+ * @param toast - the feedback sink; a refusal is feedback, never a revert.
+ * @returns the host action.
+ */
+export declare function openDefaultWorkspaceFor(deps: {
+    workspaces: SwitchWorkspaces;
+    uiWorkspace: SwitchUiWorkspace;
+}, toast: (message: string) => void): () => void;
+/**
+ * Bind the page's switch agent from the client services. Idempotent; a no-op
+ * without the page atom (a non-fusion page never has one).
+ * @param deps - the `connection`, `uiWorkspace`, `workspaces` and `sessions`
+ *   services (structural; the stock client tree always has all four —
+ *   upstream's ui-workspace injects the same set).
+ */
+export declare function bindSwitchAgent(deps: {
+    connection: SwitchConnection;
+    uiWorkspace: SwitchUiWorkspace;
+    workspaces: SwitchWorkspaces;
+    sessions: SwitchSessions;
+}): void;
+/**
+ * The Hub switch surfaces' entry point. Attempts the in-page switch for
+ * `label`, gated on the target world's readiness (C1): a not-ready world
+ * holds the UI on native with starting feedback and a bounded poll; a
+ * failed world reports and never switches; a ready/native/unknown target
+ * runs the machine (whose roster probe stays the fallback). A not-ready
+ * FEDERATED row skips all of that — an immediate machine-error toast
+ * (I1(c), `machine-down`), never a wait loop.
+ *
+ * @returns `true` when the fusion switch took the click over; `false` when
+ *   this page is not a fusion page or the orchestration is unbound.
+ *   Informational only — the interception contract (`seatClickDecision`)
+ *   prevents navigation on every fusion-page left click regardless: a
+ *   `false` means the click is swallowed, never that the anchor navigates
+ *   the fused page away (review round 1).
+ */
+export declare function attemptSwitch(label: string): boolean;

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

@@ -0,0 +1,295 @@
+/**
+ * Client-half switch wiring (native UI fusion, plan Task 4): turns the pure
+ * {@link createSwitchController} machine into the page's `switchAgent`.
+ *
+ * The host face is assembled from exactly the sanctioned surfaces:
+ *   - the Task-3 page atom `__SUPERD_UI_STATE__` (setAgent = state + NS swap;
+ *     every later request demuxes through the call-time patches);
+ *   - the Task-3 namespaced `Storage` for the landing read — `getItem` is
+ *     read at call time against the ACTIVE label's `'<label>:'` namespace,
+ *     so the post-`setAgent` read of `dsh.sessions.current` lands in the
+ *     target world's tree without this module ever prefixing keys itself;
+ *   - `ctx.connection` (`reconnect()` + the generation observable — the
+ *     establishment leg of `connection/reset`);
+ *   - `ctx.uiWorkspace` (`openSession(target)` / `startSession(workspaceId?)`
+ *     / `openWorkspace(workspaceId)` — the navigation face; T-F executes the
+ *     restore precedence through these public faces only);
+ *   - `ctx.workspaces` (`list` — the workspace projection; T-F also reads
+ *     `initializeDefault` to mirror upstream's default-workspace boot path);
+ *   - `ctx.sessions` (T-F: the session projection — its `list` store is the
+ *     second freshness edge the landing gate watches, and its `ids`/`byId`
+ *     are what upstream `restoreSelection` resolves the pointer against,
+ *     navigation.ts:324; watching `workspaces.list` alone was the T-A gap
+ *     that broke native's own last-visited restore);
+ *   - the control-plane roster fetch (`/api/agent-runtime`, never rewritten)
+ *     as the probe: the target must still be a live roster entry;
+ *   - a minimal self-owned toast overlay for the revert feedback (upstream
+ *     has no public toast service; the overlay reads nothing from any other
+ *     component's DOM).
+ *
+ * The client entry (`index.ts`) binds once `connection` + `uiWorkspace`
+ * exist. The Hub UI surfaces (HubPage rows + the HubPanelIcon chevron menu —
+ * the sole switch surface since the T-B RuntimeSeat retirement) run every
+ * click through {@link seatClickDecision} (switch-core): on a fusion page
+ * the left click is intercepted with NO navigation — the orchestration bound
+ * or not; on a world page the flag global is absent, the fusion arm never
+ * runs, and the real hyperlink stays in charge (spec §5 双半边).
+ *
+ * @module superd-hub/client/switch
+ */
+import { createReadinessWaiter, createSwitchController, decidePreFlight, observeCachesRefreshed, runMachineDownFeedback, SESSIONS_CURRENT_KEY, } from '../switch-core.js';
+import { showSuperdToast } from '../toast-core.js';
+import { fetchMachines, reprobeMachine } from './mesh-api.js';
+import { fetchRoster } from './roster.js';
+/** Whether this page is a fusion page: the baked flag global is present. */
+export function fusionPage() {
+    return globalThis.__SUPERD_UI_FUSION__ === true;
+}
+/** The page atom, when the page carries one (it always does on a fusion page). */
+export function uiState() {
+    const state = globalThis.__SUPERD_UI_STATE__;
+    if (state === undefined)
+        return undefined;
+    if (typeof state.setAgent !== 'function')
+        return undefined;
+    if (typeof state.subscribe !== 'function' || typeof state.activeAgent !== 'string')
+        return undefined;
+    return state;
+}
+/**
+ * One transient message through the official `Toast` primitive (C1 task 4:
+ * the platform's top-center banner — dark surface in both themes, warn icon
+ * seat — rendered by the host's React tree from the Hub sidebar row's
+ * always-mounted owner; see client/toast.ts).
+ */
+function showToast(message) {
+    showSuperdToast(message);
+}
+/**
+ * I1(c) feedback + I1(b) light probe (mesh P3 Task 5a): the machine-down
+ * branch delegates to the pure {@link runMachineDownFeedback} — the
+ * machines face (already part of the client half — the Hub machines panel's
+ * own cheap same-origin GET) enriches the toast, bounded at 3s; after
+ * toasting, ONE fire-and-forget reprobe POST per failed click refreshes the
+ * hub's status table so the NEXT click can succeed without waiting for the
+ * 5-minute sweep. Nothing here blocks the UI path.
+ */
+function reportMachineDown(label, row) {
+    runMachineDownFeedback(label, row, {
+        fetchMachines,
+        reprobe: reprobeMachine,
+        toast: showToast,
+        setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
+        clearTimeout: (handle) => globalThis.clearTimeout(handle),
+    });
+}
+/**
+ * Build the `SwitchHost.openDefaultWorkspace` action.
+ *
+ * dsh 0.2.0-rc.2 removed the request object from the Host's
+ * `workspaces.initializeDefault` Remote: the first-use directory and stored
+ * title are fixed and language-neutral (`default-workspace` under
+ * `<Documents>/deepseek-harness`), so the caller passes only its own lifetime
+ * signal. This module shipped the pre-0.2 `{ directoryName, title }` shape for
+ * a release cycle; the Host then received a plain object where it feeds
+ * `AbortSignal.any(...)`, EVERY empty-plane landing rejected, and the browser
+ * surfaced "Unable to create default workspace". Root-caused 2026-10-02 on
+ * the Hermes world — the only world whose registry was still empty after the
+ * 0.2.0-rc.2 upgrade, hence the only one that took the default-workspace
+ * branch. Exported so the call shape is unit-testable without the
+ * module-level single-bind guard.
+ *
+ * @param deps - the workspace projection and the navigation face.
+ * @param toast - the feedback sink; a refusal is feedback, never a revert.
+ * @returns the host action.
+ */
+export function openDefaultWorkspaceFor(deps, toast) {
+    return () => {
+        void deps.workspaces.initializeDefault()
+            .then((prepared) => {
+            if (prepared !== undefined)
+                deps.uiWorkspace.openWorkspace(prepared.workspaceId);
+        })
+            .catch(() => { toast('Super D: unable to create the default workspace.'); });
+    };
+}
+/** The bound `switchAgent`, or `undefined` until the entry binds it. */
+let bound;
+/**
+ * Bind the page's switch agent from the client services. Idempotent; a no-op
+ * without the page atom (a non-fusion page never has one).
+ * @param deps - the `connection`, `uiWorkspace`, `workspaces` and `sessions`
+ *   services (structural; the stock client tree always has all four —
+ *   upstream's ui-workspace injects the same set).
+ */
+export function bindSwitchAgent(deps) {
+    if (bound !== undefined)
+        return;
+    const state = uiState();
+    if (state === undefined)
+        return;
+    const readRestoreCaches = () => {
+        const workspaces = deps.workspaces.list.getSnapshot();
+        const sessions = deps.sessions.list.getSnapshot();
+        return {
+            workspaces: { items: workspaces.items, phase: workspaces.phase },
+            sessions: { ids: sessions.ids, byId: sessions.byId, phase: sessions.phase },
+        };
+    };
+    // Upstream `initializeDefaultWorkspace` (navigation.ts:349-361) mirrored
+    // through the public faces; the call contract and its 2026-10-02 regression
+    // live in `openDefaultWorkspaceFor`.
+    const openDefaultWorkspace = openDefaultWorkspaceFor(deps, showToast);
+    const host = {
+        setAgent(label) { state.setAgent(label); },
+        readPersistedSelection() {
+            // The Task-3 storage patch prefixes the ACTIVE label's namespace at
+            // call time — the landing reads long after setAgent, so this read
+            // lands in the target world's `'<label>:dsh.sessions.current'`.
+            const storage = globalThis.localStorage;
+            return storage === undefined ? null : storage.getItem(SESSIONS_CURRENT_KEY);
+        },
+        openSession(target) { deps.uiWorkspace.openSession(target); },
+        startSession(workspaceId) { deps.uiWorkspace.startSession(workspaceId); },
+        openDefaultWorkspace,
+        readRestoreCaches,
+        onCachesRefreshed(listener, gate) {
+            // The T-F freshness gate over the real stores, extended T-G with the
+            // membership face: the first post-establishment baseline replacement
+            // in BOTH `workspaces.list` and `sessions.list` — upstream's
+            // watchNavigation ready gate (navigation.ts:292) — held until the
+            // persisted pointer's session JOINS the freshly (incrementally) minted
+            // list, or the list goes quiet. The sessions store adapts its
+            // projection's `ids` array to the freshness token (a fresh array is
+            // minted on every projection); membership answers from the LIVE `byId`
+            // snapshot — the face upstream's boot restore resolves the pointer
+            // against (navigation.ts:324), and the only one that can gain a row
+            // without a new `ids` identity (publishRetention, service.ts:565).
+            // The machine's gate request (pointer face, quiet window, timers)
+            // rides through structurally — it is a full LandingGateOptions.
+            const sessionsFace = {
+                getSnapshot: () => {
+                    const snapshot = deps.sessions.list.getSnapshot();
+                    return { items: snapshot.ids, phase: snapshot.phase };
+                },
+                subscribe: (fn) => deps.sessions.list.subscribe(fn),
+                contains: (id) => deps.sessions.list.getSnapshot().byId[id] !== undefined,
+            };
+            return observeCachesRefreshed(deps.workspaces.list, sessionsFace, deps.connection.generation, listener, gate);
+        },
+        reconnect() { deps.connection.reconnect(); },
+        onGenerationEstablished(listener) {
+            const generation = deps.connection.generation;
+            // The observable fires on establishment, replacement, and loss; only
+            // an existing generation settles the attempt.
+            return generation.subscribe(() => {
+                if (generation.getSnapshot() !== undefined)
+                    listener();
+            });
+        },
+        async probeTarget(label) {
+            try {
+                // Control plane, never rewritten: the roster always talks to ctx0.
+                const roster = await fetchRoster();
+                return roster.some((agent) => agent.key === label);
+            }
+            catch {
+                return false;
+            }
+        },
+        toast: showToast,
+        setTimeout(fn, ms) { return globalThis.setTimeout(fn, ms); },
+        clearTimeout(handle) { globalThis.clearTimeout(handle); },
+    };
+    const controller = createSwitchController(host);
+    bound = (label) => controller.run(label);
+}
+/**
+ * The Hub switch surfaces' entry point. Attempts the in-page switch for
+ * `label`.
+ * @returns `true` when the fusion switch took the click over; `false` when
+ *   this page is not a fusion page or the orchestration is unbound.
+ *   Informational only — the interception contract (`seatClickDecision`)
+ *   prevents navigation on every fusion-page left click regardless: a
+ *   `false` means the click is swallowed, never that the anchor navigates
+ *   the fused page away (review round 1).
+ */
+let pendingWait;
+/**
+ * The Hub switch surfaces' entry point. Attempts the in-page switch for
+ * `label`, gated on the target world's readiness (C1): a not-ready world
+ * holds the UI on native with starting feedback and a bounded poll; a
+ * failed world reports and never switches; a ready/native/unknown target
+ * runs the machine (whose roster probe stays the fallback). A not-ready
+ * FEDERATED row skips all of that — an immediate machine-error toast
+ * (I1(c), `machine-down`), never a wait loop.
+ *
+ * @returns `true` when the fusion switch took the click over; `false` when
+ *   this page is not a fusion page or the orchestration is unbound.
+ *   Informational only — the interception contract (`seatClickDecision`)
+ *   prevents navigation on every fusion-page left click regardless: a
+ *   `false` means the click is swallowed, never that the anchor navigates
+ *   the fused page away (review round 1).
+ */
+export function attemptSwitch(label) {
+    const run = bound;
+    if (run === undefined || !fusionPage())
+        return false;
+    // A newer attempt supersedes any pending readiness wait.
+    pendingWait?.cancel();
+    pendingWait = undefined;
+    void (async () => {
+        let row;
+        try {
+            row = (await fetchRoster()).find((agent) => agent.key === label);
+        }
+        catch {
+            row = undefined;
+        }
+        const decision = decidePreFlight(label, row);
+        if (decision === 'failed') {
+            showToast(`Super D: ${label} failed to start — see the service log.`);
+            return;
+        }
+        // I1(c): a degraded FEDERATED row fails fast — the hub's own probe
+        // already knows the machine is unreachable/auth-expired, so "starting…"
+        // plus the 120s wait would be a lie. Actionable toast, no wait loop, no
+        // revert (the page stays where it is, like the failed branch).
+        if (decision === 'machine-down') {
+            if (row !== undefined)
+                reportMachineDown(label, row);
+            return;
+        }
+        if (decision === 'wait') {
+            showToast(`Super D: ${label} is starting…`);
+            const waiter = createReadinessWaiter({
+                fetchRow: async () => {
+                    try {
+                        return (await fetchRoster()).find((agent) => agent.key === label);
+                    }
+                    catch {
+                        return undefined;
+                    }
+                },
+                setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
+                clearTimeout: (handle) => globalThis.clearTimeout(handle),
+            });
+            pendingWait = waiter;
+            const outcome = await waiter.wait(label);
+            if (pendingWait === waiter)
+                pendingWait = undefined;
+            if (outcome === 'ready') {
+                void run(label).catch(() => { });
+                return;
+            }
+            if (outcome === 'failed')
+                showToast(`Super D: ${label} failed to start — see the service log.`);
+            else if (outcome === 'bound')
+                showToast(`Super D: ${label} is still starting — try again in a moment.`);
+            // 'cancelled': a newer attempt owns the page — silence.
+            return;
+        }
+        void run(label).catch(() => { });
+    })();
+    return true;
+}