@tea-agent/loop-agent 0.33.7-beta.0 → 0.34.0

package/dist/worker/console/static-src/operator-chat/useOverlayFocus.js

@@ -0,0 +1,84 @@
+import { useEffect, useRef } from "react";
+const FOCUSABLE = 'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
+/**
+ * Trap focus inside an open overlay root; restore focus to the prior trigger
+ * on close. Escape is handled by the caller (or optional onEscape).
+ *
+ * Restore contract: open true→false and unmount-while-open share a single
+ * restore path (cleanup). A wasOpen flag prevents double restore when the
+ * transition effect re-runs after cleanup.
+ */
+export function useOverlayFocus(options) {
+    const { open, containerRef, triggerRef, onEscape } = options;
+    const previousFocusRef = useRef(null);
+    const wasOpenRef = useRef(false);
+    useEffect(() => {
+        if (open) {
+            if (!wasOpenRef.current) {
+                const active = document.activeElement;
+                previousFocusRef.current =
+                    triggerRef?.current ??
+                        (active instanceof HTMLElement ? active : null);
+                const root = containerRef.current;
+                if (root) {
+                    const first = root.querySelector(FOCUSABLE);
+                    (first ?? root).focus?.();
+                }
+                wasOpenRef.current = true;
+            }
+            // Single restore path for true→false (cleanup before next effect)
+            // and for unmount-while-open (cleanup on unmount).
+            return () => {
+                if (!wasOpenRef.current)
+                    return;
+                const restore = triggerRef?.current ?? previousFocusRef.current;
+                if (restore && document.contains(restore)) {
+                    restore.focus();
+                }
+                previousFocusRef.current = null;
+                wasOpenRef.current = false;
+            };
+        }
+        // open === false: ensure flag is clear; restore already handled by
+        // the previous open-effect cleanup when transitioning true→false.
+        wasOpenRef.current = false;
+        return undefined;
+    }, [open, containerRef, triggerRef]);
+    useEffect(() => {
+        if (!open)
+            return;
+        const root = containerRef.current;
+        if (!root)
+            return;
+        const onKeyDown = (event) => {
+            if (event.key === "Escape") {
+                event.preventDefault();
+                onEscape?.();
+                return;
+            }
+            if (event.key !== "Tab")
+                return;
+            const nodes = Array.from(root.querySelectorAll(FOCUSABLE)).filter((el) => !el.hasAttribute("disabled") && el.tabIndex !== -1);
+            if (nodes.length === 0) {
+                event.preventDefault();
+                root.focus?.();
+                return;
+            }
+            const first = nodes[0];
+            const last = nodes[nodes.length - 1];
+            const active = document.activeElement;
+            if (event.shiftKey) {
+                if (active === first || !root.contains(active)) {
+                    event.preventDefault();
+                    last.focus();
+                }
+            }
+            else if (active === last || !root.contains(active)) {
+                event.preventDefault();
+                first.focus();
+            }
+        };
+        document.addEventListener("keydown", onKeyDown);
+        return () => document.removeEventListener("keydown", onKeyDown);
+    }, [open, containerRef, onEscape]);
+}

package/dist/worker/console/static-src/operator-chat/useRuntimeControls.js

@@ -1,19 +1,44 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { formatModelRef, mergeSessionRuntime, runtimeSelectionFromRecord, sessionRuntimeMatches, } from "../../chat/runtime-selection.js";
+import { formatModelRef, mergeSessionRuntime, sessionRuntimeMatches, } from "../../chat/runtime-selection.js";
 import { confirmationToken } from "./format.js";
+import { mergeRuntimeContextWithSnapshot, runtimeSelectionFromSnapshot, } from "./runtime-snapshot-store.js";
 import { buildToolCatalog } from "./tools-catalog.js";
+import { adoptMutationSnapshot, dispatchRuntimeSnapshot, getRuntimeSnapshotState, refreshRuntimeSnapshot, settleMutationLifecycle, useRuntimeSnapshot, } from "./useRuntimeSnapshot.js";
+/**
+ * Monotonic mutation sequence shared across switchRuntime calls (RF-04). Each
+ * mutation captures its own token; only the LATEST started token may settle
+ * mutationBusy/switching, so a slow earlier response can never clear busy
+ * while a newer mutation is still in flight.
+ */
+let mutationSeq = 0;
 /** Capabilities catalog, model / thinking-level switcher, runtime-context
  *  popover and the outside-click dismissal for both transient menus. */
 export function useRuntimeControls(params) {
     const { origin, session, setSession, refs, setError } = params;
     const [capabilities, setCapabilities] = useState(null);
     const [models, setModels] = useState([]);
+    const [modelsStatus, setModelsStatus] = useState("idle");
+    const [modelsError, setModelsError] = useState(null);
     const [thinkingLevels, setThinkingLevels] = useState([]);
     const [runtimeContext, setRuntimeContext] = useState(null);
+    const [runtimeContextError, setRuntimeContextError] = useState(null);
+    const [switching, setSwitching] = useState(false);
     const [toolsOpen, setToolsOpen] = useState(false);
     const [runtimeContextOpen, setRuntimeContextOpen] = useState(false);
     const toolsMenuRef = useRef(null);
     const runtimeContextMenuRef = useRef(null);
+    const switchTokenRef = useRef(0);
+    // RF3-02: a session switch immediately abandons the in-flight mutation
+    // lifecycle — the local token is invalidated and switching cleared, so a
+    // late response from the previous session can never settle the new
+    // session's busy/switching. (The store side is reset synchronously by
+    // attachRuntimeSnapshotController's mutation-reset.)
+    useEffect(() => {
+        switchTokenRef.current = -1;
+        setSwitching(false);
+    }, [session?.sessionId, setSwitching]);
+    const snapshotState = useRuntimeSnapshot();
+    const snapshot = snapshotState.snapshot;
     const loadCapabilities = useCallback(async () => {
         try {
             const res = await fetch(`${origin}/api/operator/v1/chat/capabilities`);
@@ -29,106 +54,202 @@ export function useRuntimeControls(params) {
     useEffect(() => {
         void loadCapabilities();
     }, [loadCapabilities]);
-    useEffect(() => {
+    // Models + thinking levels: AC-01/AC-06 — the GET may reopen a historical
+    // session server-side; a failure is a STRUCTURED error state (with retry),
+    // never silently folded into an empty list.
+    const loadModels = useCallback(async () => {
         if (!session) {
             setModels([]);
-            setRuntimeContext(null);
+            setModelsStatus("idle");
             return;
         }
         const sessionId = session.sessionId;
-        const base = `${origin}/api/operator/v1/chat/sessions/${encodeURIComponent(sessionId)}`;
-        void fetch(`${base}/models`, { credentials: "include" })
-            .then((r) => (r.ok ? r.json() : null))
-            .then((body) => {
+        setModelsStatus("loading");
+        setModelsError(null);
+        try {
+            const res = await fetch(`${origin}/api/operator/v1/chat/sessions/${encodeURIComponent(sessionId)}/models`, { credentials: "include" });
+            const body = (await res.json().catch(() => null));
             // Guard against a stale response landing after the user switched/
             // created/forked a session: only adopt models for the session we
             // actually requested them for.
-            if (!body || refs.sessionRef.current?.sessionId !== sessionId)
+            if (refs.sessionRef.current?.sessionId !== sessionId)
+                return;
+            if (!res.ok || !body) {
+                setModelsStatus("error");
+                setModelsError(body
+                    ?.error?.message ?? `模型列表读取失败（HTTP ${res.status}）`);
                 return;
+            }
             setModels(body.models ?? []);
             setThinkingLevels(body.thinkingLevels ?? []);
-        });
+            setModelsStatus("ready");
+        }
+        catch (reason) {
+            if (refs.sessionRef.current?.sessionId !== sessionId)
+                return;
+            setModelsStatus("error");
+            setModelsError(reason instanceof Error ? reason.message : String(reason));
+        }
+    }, [origin, session, refs]);
+    useEffect(() => {
+        void loadModels();
+    }, [loadModels]);
+    useEffect(() => {
+        if (!session) {
+            setRuntimeContext(null);
+            setRuntimeContextError(null);
+            return;
+        }
+        const sessionId = session.sessionId;
+        const base = `${origin}/api/operator/v1/chat/sessions/${encodeURIComponent(sessionId)}`;
+        setRuntimeContextError(null);
         void fetch(`${base}/runtime-context`, { credentials: "include" })
-            .then((r) => (r.ok ? r.json() : null))
-            .then((body) => {
+            .then(async (r) => {
+            const body = await r.json().catch(() => null);
             // Stale-response guard: a slow runtime-context reply for session A
             // must not overwrite the context/session state of the now-current
             // session B.
             if (!body?.context || refs.sessionRef.current?.sessionId !== sessionId)
                 return;
-            setRuntimeContext(body.context);
+            // RF5: the response body NEVER writes model/thinkingLevel — it
+            // carries no revision semantics, so a late reply for the same
+            // session could hold a stale selection. Selection is derived only
+            // from the LATEST adopted snapshot, read HERE at .then time (right
+            // before the setRuntimeContext functional updater runs) via the
+            // production read-only accessor getRuntimeSnapshotState() — the
+            // only immediate authority when the store has already adopted a
+            // new revision but this component has not rerendered yet. A
+            // render-synchronized value (snapshotRef) could still be the old
+            // revision in that window, so it is removed entirely.
+            // systemPrompt/resources/suffix/readOnly still come from the
+            // response. Zero session writes and zero store writes: the
+            // snapshot hydration effect never re-runs and the menu/popover
+            // selection never jumps back.
             const ctx = body.context;
-            const patch = {
-                model: ctx.model,
-                thinkingLevel: ctx.thinkingLevel,
-            };
-            setSession((current) => {
-                if (!current || current.sessionId !== sessionId)
-                    return current;
-                if (sessionRuntimeMatches(current, patch))
-                    return current;
-                const merged = mergeSessionRuntime(current, patch);
-                refs.sessionRef.current = merged;
-                return merged;
-            });
-        });
-    }, [origin, session?.sessionId, refs, setSession]);
-    const switchRuntime = useCallback(async (body) => {
-        if (!session)
-            return;
-        // Capture the target session so a slow model/thinking response cannot
-        // write its result into a different (newly created/forked/switched)
-        // session the user has since moved to.
-        const targetSessionId = session.sessionId;
-        const res = await fetch(`${origin}/api/operator/v1/chat/sessions/${encodeURIComponent(session.sessionId)}/model`, {
-            method: "POST",
-            credentials: "include",
-            headers: {
-                "content-type": "application/json",
-                "x-loop-console-confirmation": confirmationToken(),
-            },
-            body: JSON.stringify(body),
+            const adoptedSnapshot = getRuntimeSnapshotState().snapshot;
+            setRuntimeContext((current) => mergeRuntimeContextWithSnapshot(current, ctx, adoptedSnapshot, sessionId));
+        })
+            .catch(() => {
+            if (refs.sessionRef.current?.sessionId !== sessionId)
+                return;
+            setRuntimeContextError("注入上下文读取失败，请重试");
         });
-        if (!res.ok) {
-            // Only surface the failure for the session that still owns it.
-            if (refs.sessionRef.current?.sessionId === targetSessionId)
-                setError("模型或思考等级切换失败");
-            return;
-        }
-        const payload = (await res.json().catch(() => ({})));
-        if (!payload.session)
-            return;
-        // Drop the result entirely if the active session changed mid-flight.
-        if (refs.sessionRef.current?.sessionId !== targetSessionId)
+    }, [origin, session?.sessionId, refs]);
+    // AC-01/RF3-01: hydrate the Composer from the unified snapshot — real
+    // model and thinking selection; `auto` displays the Pi actual effective
+    // level. Derived session/runtimeContext state ONLY comes from a snapshot
+    // the reducer guards accepted: the mutation success branch never writes
+    // session/runtimeContext directly, so this effect re-runs on adoption and
+    // is a no-op for rejected/missing snapshots (zero derived writes).
+    useEffect(() => {
+        if (!snapshot || !session || snapshot.sessionId !== session.sessionId)
             return;
+        const patch = runtimeSelectionFromSnapshot(snapshot);
         setSession((current) => {
-            if (!current || current.sessionId !== targetSessionId)
+            if (!current || current.sessionId !== snapshot.sessionId)
                 return current;
-            const patch = runtimeSelectionFromRecord(payload.session);
             if (sessionRuntimeMatches(current, patch))
                 return current;
             const merged = mergeSessionRuntime(current, patch);
             refs.sessionRef.current = merged;
             return merged;
         });
-        setRuntimeContext((current) => current
-            ? {
+        setRuntimeContext((current) => {
+            if (!current)
+                return current;
+            const next = {
                 ...current,
-                ...(payload.session.modelProvider && payload.session.modelId
-                    ? {
-                        model: {
-                            provider: payload.session.modelProvider,
-                            modelId: payload.session.modelId,
-                        },
-                    }
+                ...(patch.model ? { model: patch.model } : {}),
+                ...(patch.thinkingLevel
+                    ? { thinkingLevel: patch.thinkingLevel }
                     : {}),
-                ...(payload.session.thinkingLevel
-                    ? { thinkingLevel: payload.session.thinkingLevel }
-                    : body.thinkingLevel
-                        ? { thinkingLevel: body.thinkingLevel }
-                        : {}),
+            };
+            if (next.model?.provider === current.model?.provider &&
+                next.model?.modelId === current.model?.modelId &&
+                next.thinkingLevel === current.thinkingLevel) {
+                return current;
+            }
+            return next;
+        });
+    }, [snapshot, session?.sessionId, refs, setSession, setRuntimeContext]);
+    const switchRuntime = useCallback(async (body) => {
+        if (!session)
+            return false;
+        // Capture the target session so a slow model/thinking response cannot
+        // write its result into a different (newly created/forked/switched)
+        // session the user has since moved to.
+        const targetSessionId = session.sessionId;
+        // RF-04: token the mutation start; only the latest token's settle
+        // clears mutationBusy/switching (stale earlier settles can't win).
+        const token = ++mutationSeq;
+        switchTokenRef.current = token;
+        dispatchRuntimeSnapshot({ type: "mutation-start", token });
+        setSwitching(true);
+        try {
+            const res = await fetch(`${origin}/api/operator/v1/chat/sessions/${encodeURIComponent(session.sessionId)}/model`, {
+                method: "POST",
+                credentials: "include",
+                headers: {
+                    "content-type": "application/json",
+                    "x-loop-console-confirmation": confirmationToken(),
+                },
+                body: JSON.stringify(body),
+            });
+            const payload = (await res.json().catch(() => ({})));
+            // RF2-02: an out-of-order response (its token is no longer the
+            // latest started mutation) is dropped ENTIRELY on BOTH the success
+            // and the failure branch: no setSession/setRuntimeContext, no
+            // mutation-adopt, no busy settle, no refresh — the newest mutation
+            // owns the UI and a slow earlier reply can never overwrite it.
+            if (switchTokenRef.current !== token)
+                return false;
+            if (!res.ok) {
+                // RF2-01: a non-2xx response (e.g. 503 PI_RUNTIME_UNAVAILABLE —
+                // the mutation already applied server-side but the snapshot
+                // projection failed) for the still-current session shows the
+                // structured error, then triggers a REAL GET
+                // /runtime-snapshot so the store converges on the server
+                // selection via the load-success revision guard. When the
+                // session switched or the response is stale: no error, no
+                // refresh, no state writes.
+                if (refs.sessionRef.current?.sessionId === targetSessionId) {
+                    setError(payload.error?.message ??
+                        `模型或思考等级切换失败（HTTP ${res.status}）`);
+                    void refreshRuntimeSnapshot();
+                }
+                return false;
             }
-            : current);
+            if (!payload.session)
+                return false;
+            // Drop the result entirely if the active session changed mid-flight.
+            if (refs.sessionRef.current?.sessionId !== targetSessionId)
+                return false;
+            // RF3-01: derived session/runtimeContext state is ONLY written from
+            // a snapshot the reducer's three guards (latest mutationToken,
+            // current sessionId, monotonic revision) accepted — no direct
+            // setSession/setRuntimeContext here. A missing snapshot returns
+            // false with zero derived writes; on adoption the hydrate effect
+            // derives session + runtimeContext from the adopted snapshot.
+            return adoptMutationSnapshot(token, targetSessionId, payload.snapshot);
+        }
+        catch (reason) {
+            // RF2-02: stale out-of-order network failures are dropped too —
+            // no error, no refresh, no state writes for an expired token.
+            if (switchTokenRef.current !== token)
+                return false;
+            if (refs.sessionRef.current?.sessionId === targetSessionId)
+                setError(reason instanceof Error ? reason.message : String(reason));
+            return false;
+        }
+        finally {
+            // RF3-02: settle only when the target session is still active and
+            // the token is still the latest — a late old-session response
+            // neither dispatches an effective settle nor clears the current
+            // busy/switching.
+            const settled = settleMutationLifecycle(token, targetSessionId, refs);
+            if (settled && switchTokenRef.current === token)
+                setSwitching(false);
+        }
     }, [origin, session, refs, setSession, setError]);
     // Close tools catalog on outside click / Escape.
     useEffect(() => {
@@ -179,18 +300,46 @@ export function useRuntimeControls(params) {
     const toolCatalog = useMemo(() => buildToolCatalog(capabilities), [
         capabilities,
     ]);
+    // Snapshot is the single source of truth when ready; the /models fetch
+    // result is the fallback (both hit the same backend, never fake-empty).
+    const effectiveModels = snapshot
+        ? (snapshot.models ?? []).map((model) => ({
+            provider: model.provider,
+            id: model.id,
+            ...(model.name ? { name: model.name } : {}),
+            ...(model.hasCredentials !== undefined
+                ? { hasCredentials: model.hasCredentials }
+                : {}),
+        }))
+        : models;
+    const effectiveThinkingLevels = snapshot?.thinkingLevels?.length
+        ? snapshot.thinkingLevels.map((option) => option.value)
+        : thinkingLevels;
     const activeModel = session?.model ?? runtimeContext?.model;
     const activeModelRef = activeModel
         ? formatModelRef(activeModel.provider, activeModel.modelId)
         : "";
-    const activeThinkingLevel = session?.thinkingLevel ?? runtimeContext?.thinkingLevel ?? "";
+    // AC-01/AC-02: thinking selection shows "auto" when no explicit override,
+    // with the Pi effective level available separately for the badge.
+    const activeThinkingLevel = snapshot?.selection?.thinkingSelection ?? session?.thinkingLevel ?? "";
+    const effectiveThinkingLevel = snapshot?.selection?.effectiveThinkingLevel ??
+        session?.thinkingLevel ??
+        undefined;
     const activeModelListed = !activeModelRef ||
-        models.some((model) => formatModelRef(model.provider, model.id) === activeModelRef);
+        effectiveModels.some((model) => formatModelRef(model.provider, model.id) === activeModelRef);
     return {
         capabilities,
-        models,
-        thinkingLevels,
+        models: effectiveModels,
+        modelsStatus,
+        modelsError,
+        onRetryModels: () => void loadModels(),
+        thinkingLevels: effectiveThinkingLevels,
         runtimeContext,
+        runtimeContextError,
+        onRetryRuntimeContext: () => {
+            setRuntimeContextError(null);
+            void refreshRuntimeSnapshot();
+        },
         toolsOpen,
         setToolsOpen,
         runtimeContextOpen,
@@ -198,10 +347,12 @@ export function useRuntimeControls(params) {
         toolsMenuRef,
         runtimeContextMenuRef,
         switchRuntime,
+        switching,
         toolCatalog,
         activeModel,
         activeModelRef,
         activeThinkingLevel,
+        effectiveThinkingLevel,
         activeModelListed,
     };
 }

package/dist/worker/console/static-src/operator-chat/useRuntimeSnapshot.js

@@ -0,0 +1,196 @@
+/**
+ * Operator Chat — runtime snapshot React binding (design §2.2 / AC-05/06).
+ *
+ * All seams that need the snapshot (ChatComposer /reload paths, resource
+ * panels, runtime-context popover) live in writable files that do NOT share a
+ * common React tree root (composer vs sidebar). This module therefore owns a
+ * single module-level store plus a controller attached by `useComposer` (which
+ * already holds origin + sessionId + refs). Components read the shared state
+ * with `useRuntimeSnapshot()` and trigger reloads with
+ * `reloadRuntimeSnapshot()` — every submit path shares the SAME state machine.
+ */
+import { useSyncExternalStore } from "react";
+import { confirmationToken } from "./format.js";
+import { createRuntimeSnapshotStore, parseRuntimeSnapshotError, } from "./runtime-snapshot-store.js";
+const store = createRuntimeSnapshotStore();
+let controller;
+function snapshotUrl(sessionId) {
+    return `/api/operator/v1/chat/sessions/${encodeURIComponent(sessionId)}`;
+}
+/**
+ * Bind the current session to the shared store. Called from `useComposer` on
+ * every session change; switching sessions reloads the snapshot, clearing the
+ * session detaches cleanly. Stale replies are dropped by the sessionId guard.
+ */
+export function attachRuntimeSnapshotController(input) {
+    const previous = controller;
+    controller = input;
+    if (previous && previous.sessionId === input.sessionId && previous.origin === input.origin) {
+        return;
+    }
+    // RF3-02: a session switch immediately resets the mutation lifecycle so the
+    // new session never inherits the old session's mutationBusy/token. Stale
+    // adopt/settle actions for the old session become no-ops via the token +
+    // sessionId guards in the reducer.
+    if (!previous || previous.sessionId !== input.sessionId) {
+        store.dispatch({ type: "mutation-reset" });
+    }
+    if (!input.sessionId) {
+        store.dispatch({ type: "reset" });
+        return;
+    }
+    store.dispatch({ type: "load-start", sessionId: input.sessionId });
+    void fetchSnapshot(input.sessionId, input.origin);
+}
+async function fetchSnapshot(sessionId, origin) {
+    try {
+        const res = await fetch(`${origin}${snapshotUrl(sessionId)}/runtime-snapshot`, { credentials: "include" });
+        const body = (await res.json().catch(() => ({})));
+        if (controller?.sessionId !== sessionId)
+            return; // stale session reply
+        if (!res.ok) {
+            store.dispatch({
+                type: "load-failure",
+                sessionId,
+                error: { ...parseRuntimeSnapshotError(body), status: res.status },
+            });
+            return;
+        }
+        if (!body.snapshot) {
+            store.dispatch({
+                type: "load-failure",
+                sessionId,
+                error: { status: res.status, message: "runtime snapshot missing in response" },
+            });
+            return;
+        }
+        store.dispatch({ type: "load-success", sessionId, snapshot: body.snapshot });
+    }
+    catch (error) {
+        if (controller?.sessionId !== sessionId)
+            return;
+        store.dispatch({
+            type: "load-failure",
+            sessionId,
+            error: { message: error instanceof Error ? error.message : String(error) },
+        });
+    }
+}
+/**
+ * POST /sessions/:id/reload (AC-05). Single-flight: a reload already in
+ * progress is NOT queued (AC-06). Returns true only on success.
+ */
+export async function reloadRuntimeSnapshot() {
+    const ctrl = controller;
+    if (!ctrl?.sessionId)
+        return false;
+    if (store.getState().reloading)
+        return false; // busy reload: no silent queue
+    const sessionId = ctrl.sessionId;
+    store.dispatch({ type: "reload-start" });
+    try {
+        const res = await fetch(`${ctrl.origin}${snapshotUrl(sessionId)}/reload`, {
+            method: "POST",
+            credentials: "include",
+            headers: {
+                "content-type": "application/json",
+                "x-loop-console-confirmation": confirmationToken(),
+            },
+            body: "{}",
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (controller?.sessionId !== sessionId)
+            return false;
+        if (!res.ok) {
+            store.dispatch({
+                type: "reload-failure",
+                error: { ...parseRuntimeSnapshotError(body), status: res.status },
+            });
+            return false;
+        }
+        if (!body.snapshot) {
+            store.dispatch({
+                type: "reload-failure",
+                error: { status: res.status, message: "reload succeeded but snapshot missing" },
+            });
+            return false;
+        }
+        store.dispatch({ type: "reload-success", snapshot: body.snapshot });
+        return true;
+    }
+    catch (error) {
+        if (controller?.sessionId !== sessionId)
+            return false;
+        store.dispatch({
+            type: "reload-failure",
+            error: { message: error instanceof Error ? error.message : String(error) },
+        });
+        return false;
+    }
+}
+/**
+ * Plain snapshot re-read (no Pi reload). Used after model/thinking mutations
+ * so the store atomically adopts the fresh revision.
+ */
+export async function refreshRuntimeSnapshot() {
+    const ctrl = controller;
+    if (!ctrl?.sessionId)
+        return false;
+    const sessionId = ctrl.sessionId;
+    store.dispatch({ type: "load-start", sessionId });
+    void fetchSnapshot(sessionId, ctrl.origin);
+    return true;
+}
+/**
+ * RF3-01: production success-branch seam — `useRuntimeControls.switchRuntime`
+ * calls this INSTEAD of writing session/runtimeContext directly. Returns true
+ * only when the reducer's three guards (latest mutationToken, current
+ * sessionId, monotonic revision) actually adopted the snapshot; a missing
+ * snapshot is rejected up-front with zero derived writes. Adoption never
+ * settles mutationBusy — `settleMutationLifecycle` owns that.
+ */
+export function adoptMutationSnapshot(token, sessionId, snapshot) {
+    if (!snapshot)
+        return false;
+    store.dispatch({ type: "mutation-adopt", token, sessionId, snapshot });
+    // The reducer adopts by atomic replacement: the current snapshot IS the
+    // proposed snapshot only when all three guards passed.
+    return store.getState().snapshot === snapshot;
+}
+/**
+ * RF3-02: production finally-branch seam — settles the mutation lifecycle only
+ * when the target session is STILL the active session AND the token is still
+ * the latest. A late response from a previous session (or a superseded token)
+ * returns false without dispatching, so it can neither clear the current
+ * busy/switching nor settle a lifecycle the session switch already reset.
+ */
+export function settleMutationLifecycle(token, targetSessionId, refs) {
+    if (refs.sessionRef.current?.sessionId !== targetSessionId)
+        return false;
+    if (store.getState().mutationToken !== token)
+        return false;
+    store.dispatch({ type: "mutation-settle", token });
+    return true;
+}
+/** Subscribe the current component to the shared snapshot state. */
+export function useRuntimeSnapshot() {
+    return useSyncExternalStore(store.subscribe, store.getState);
+}
+/**
+ * Dispatch an action into the shared snapshot store. Controller-side seams
+ * (e.g. the mutation token lifecycle in useRuntimeControls) drive the same
+ * state machine the components read, keeping every consumer consistent.
+ */
+export function dispatchRuntimeSnapshot(action) {
+    store.dispatch(action);
+}
+/**
+ * RF5: production read-only accessor for the shared store — the only
+ * immediate authority for the currently adopted snapshot inside asynchronous
+ * callbacks (e.g. the /runtime-context response .then handler), even when the
+ * subscribing component has not rerendered yet. Read-only: it never bypasses
+ * the reducer, never writes state, and never notifies subscribers.
+ */
+export function getRuntimeSnapshotState() {
+    return store.getState();
+}