@ggui-ai/iframe-runtime 0.25.0 → 0.26.0

package/dist/runtime.js

@@ -28,9 +28,13 @@
 // schema-defining dependency initializes (see zod-jitless.ts).
 import './zod-jitless.js';
 import { runtimeConnectionWriter } from './connection.js';
-import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, parseMcpAppAiGguiRenderMeta, readGguiShellEnvelope, } from '@ggui-ai/protocol/integrations/mcp-apps';
+import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, parseMcpAppAiGguiRenderMeta, readGguiShellEnvelope, GGUI_SHELL_META_MARKER, } from '@ggui-ai/protocol/integrations/mcp-apps';
 import { effectiveThemeId, effectiveThemeMode, } from '@ggui-ai/protocol/integrations/theme-binding';
 import { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, READ_DOOR_REPORTERS, } from './meta-parse.js';
+import { documentViewRoots, userActivationIsActive, withViewProof } from './view-origin.js';
+import { createStreamSeqTracker } from './stream-seq.js';
+import { createLadderSet } from './ladders.js';
+import { BOOT_REFRESH_RETRIES, createCredentialController, } from './credential-controller.js';
 import { projectHostContext } from '@ggui-ai/protocol/wire';
 import { installDismissIntentListener } from './dismiss-intent.js';
 import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
@@ -39,17 +43,17 @@ import { mapHostPaletteToGguiVars } from './host-palette-bridge.js';
 import { buildRootWireConfig, StreamBus, } from './wire-config.js';
 import { createChannelTransportRouter, } from './channel-transport.js';
 import { RelayIncapableError } from './relay-incapability.js';
-import { ChannelRegistry } from '@ggui-ai/live-channel';
 import { createTelemetrySink, } from './runtime-telemetry.js';
 import { createChannelErrorHandler, createChannelPayloadHandler, createDataHandler, createDrainAckHandler, createPropsUpdateHandler, createRenderHandler, } from './channels/index.js';
-import { classifyChannelFrame, connectViaRegistry, } from './registry-subscribe.js';
-import { buildBridgePolling, buildEventsPolling, createSequenceCursor, } from './events-polling.js';
+import { connectViaRegistry, } from './registry-subscribe.js';
+import { createSequenceCursor } from './events-polling.js';
 import { unwrapCallToolResult } from './call-tool-unwrap.js';
 import { ensureStatusDom, setStatus, setConnectedStatus, retireShellLoadingIndicator, } from './status-dom.js';
 import { mergeReservedValidators, setActiveValidatorSet, } from './validation.js';
 import { loadCompiledValidatorsFromUrl } from './compiled-validators.js';
 import { mountRender, } from './render-item.js';
-import { fromBootstrapFailure, } from './protocol-error.js';
+import { createRenderFailureReporter } from './render-failure-report.js';
+import { fromBootstrapFailure, fromTransportFailure, } from './protocol-error.js';
 import { postObservabilityToParent, } from './observability.js';
 import { ACTION_TOAST_Z_INDEX, mountUiFeedbackChrome, shouldMountUiFeedbackChrome, } from './ui-feedback-chrome.js';
 import { hostCanReceiveMessages, hostCanRelayToolCalls, hostCapabilitiesCaptured, setHostCapabilities, } from './host-capabilities.js';
@@ -414,10 +418,10 @@ export async function bootSequence(opts) {
     // App handshake settles — whichever yields first wins; the listener
     // is removed on resolve.
     //
-    // Skipped entirely when `preResolvedMeta` is set (autostart caught
+    // Skipped entirely when `preResolved` is set (autostart caught
     // the toolresult or read the global early) — no listener installed,
     // no race to run.
-    const toolResultPromise = opts.preResolvedMeta !== undefined
+    const toolResultPromise = opts.preResolved !== undefined
         ? Promise.resolve(null)
         : awaitToolResultMetaFromApp(app, toolResultTimeoutMs);
     // Persistent re-mount listener — ALSO pre-connect (ggui#586). On a
@@ -427,7 +431,8 @@ export async function bootSequence(opts) {
     // notice and leaning on SDK replay for correctness. Registering here
     // covers every boot path; arrivals before a renderer publishes
     // `applyRender` no-op inside the listener.
-    installPersistentToolResultListener(app);
+    const viewRoots = opts.viewRoots ?? documentViewRoots;
+    installPersistentToolResultListener(app, viewRoots);
     // Fresh boot ⇒ the relay latch and the connection store start
     // aligned (ggui#670): a standing latch from a prior mount in a
     // re-booted document must not outlive the store it was written to.
@@ -474,7 +479,7 @@ export async function bootSequence(opts) {
     // Reading-B (retired Phase 1.19b.3 with the App-class swap; the
     // McpUiInitializeResult schema doesn't define `toolOutput`).
     //
-    //   Tier 0  preResolvedMeta — autostart-layer pre-resolution. When
+    //   Tier 0  preResolved — autostart-layer pre-resolution. When
     //           the autostart's own toolresult race or inline `__GGUI_META__`
     //           parse caught the meta before bootSequence ran, it threads
     //           the parsed slice meta here so we don't re-await the same
@@ -498,14 +503,18 @@ export async function bootSequence(opts) {
     // When both tiers fail, we surface the Tier 2 timeout/failure reason
     // (`MISSING_META_GGUI_BOOTSTRAP`) — it's the spec-canonical channel
     // and its absence is the diagnostic worth showing.
-    let parsed;
-    if (opts.preResolvedMeta !== undefined) {
-        parsed = { ok: true, meta: opts.preResolvedMeta };
+    //
+    // Every tier resolves a {@link BootMeta}: a slice whose live credential
+    // expired still boots, holding that credential for the one boot refresh
+    // below (ggui#1496 R1), instead of reading as no slice at all.
+    let resolved;
+    if (opts.preResolved !== undefined) {
+        resolved = opts.preResolved;
     }
     else {
-        const inline = parseMetaFromGlobal();
-        if (inline.ok) {
-            parsed = inline;
+        const inline = readSelfContainedMeta();
+        if (inline !== null) {
+            resolved = inline;
         }
         else {
             // Tier 1.5 — the read-plane door (ggui#537). A pre-boot tool
@@ -517,18 +526,17 @@ export async function bootSequence(opts) {
             const viaDoor = opts.preResolvedLocator !== undefined
                 ? await resolveMetaViaReadDoor(app, opts.preResolvedLocator)
                 : null;
-            const fromToolResult = viaDoor ?? (await toolResultPromise);
-            if (fromToolResult !== null) {
-                parsed = { ok: true, meta: fromToolResult };
-            }
-            else {
-                parsed = {
-                    ok: false,
-                    reason: 'MISSING_META_GGUI_BOOTSTRAP',
-                };
-            }
+            resolved = viaDoor ?? (await toolResultPromise);
         }
     }
+    // Every reader of the inline envelope copies has run by now, and no card
+    // code has loaded yet (ggui#1415).
+    forgetInlineEnvelopes(doc);
+    let parsed = resolved !== null
+        ? { ok: true, meta: resolved.meta }
+        : { ok: false, reason: 'MISSING_META_GGUI_BOOTSTRAP' };
+    const held = resolved?.held;
+    const viewRoot = resolved?.viewRoot;
     // hostContext is captured opportunistically from
     // `app.getHostContext()` — populated by App's `ui/initialize`
     // response capture + kept fresh by the `hostcontextchanged`
@@ -561,6 +569,9 @@ export async function bootSequence(opts) {
     // `ai.ggui/render` slice. The parser surfaces it directly on
     // `parsed.meta`.
     const meta = parsed.meta;
+    // The boot slice's view key root (ggui#1415), adopted only when it decodes
+    // to this slice's session.
+    viewRoots.offer(meta.sessionId, viewRoot);
     // Install the precompiled, eval-free contract validators shipped on
     // the bootstrap BEFORE any wire traffic is validated. Self-contained
     // ESM modules — no `__ggui__` dependency, so this need not wait for
@@ -574,6 +585,22 @@ export async function bootSequence(opts) {
     // is the pin; the render handler drops any frame addressed
     // elsewhere.
     const pinnedSessionId = meta.sessionId;
+    // The view's live credential (ggui#1496). One controller owns it and its
+    // one-refresh budget, over the same host `tools/call` relay the bridge
+    // rung uses; it exists when the view holds a credential and has that
+    // relay. Every subscribe frame reads the CURRENT token when it is built,
+    // so an adopted credential reaches the next subscribe payload (F5).
+    const credentialApp = getCurrentApp();
+    const initialCredential = held ?? heldCredentialOf(meta);
+    const credentialController = credentialApp !== null && initialCredential !== undefined
+        ? createCredentialController({
+            initial: initialCredential,
+            callTool: (name, args) => credentialApp.callServerTool({ name, arguments: args }),
+            ...(opts.credentialTiming?.sleep !== undefined ? { sleep: opts.credentialTiming.sleep } : {}),
+            ...(opts.credentialTiming?.random !== undefined ? { random: opts.credentialTiming.random } : {}),
+        })
+        : null;
+    let liveMeta = meta;
     // Renderer wiring — when supplied, the handler routes frames through
     // the single-render mount surface + WireConfig + StreamBus. When
     // absent, the placeholder path runs (boot.test.ts relies on the
@@ -616,20 +643,13 @@ export async function bootSequence(opts) {
         });
     }
     setStatus(refs, `Connecting to ${meta.sessionId}…`, 'connecting');
-    // Boot-without-renderer path: we still need a ChannelRegistry to
-    // receive frames, because the registry is the only dispatch
-    // surface. Build a minimal one with just the `render` placeholder
-    // handler so non-renderer consumers (boot.test.ts) can observe
-    // bootstrap-orchestration outcomes without paying React import
-    // cost. The handler logs status but does not mount React.
-    const placeholderRegistry = renderer === null
-        ? createPlaceholderRegistry({
-            meta,
-            statusRefs: refs,
-            pinnedSessionId,
-        })
-        : null;
-    const activeRegistry = renderer?.channelRegistry ?? placeholderRegistry;
+    // The handlers every ladder delivers through. Boot-without-renderer
+    // (boot.test.ts) gets just the `render` placeholder handler, so
+    // non-renderer consumers observe bootstrap-orchestration outcomes
+    // without paying React import cost; it logs status but does not mount
+    // React.
+    const channelHandlers = renderer?.channelHandlers ??
+        createPlaceholderHandlers({ statusRefs: refs, pinnedSessionId });
     /**
      * Apply an ack's render snapshot to the runtime — when the ack
      * carries a render matching `pinnedSessionId`, mount it through the
@@ -721,10 +741,9 @@ export async function bootSequence(opts) {
     // A bootstrap with NEITHER has nothing to show and nowhere to
     // subscribe.
     const hasStaticContent = hasStaticContentMeta(meta);
-    const hasLiveTrio = typeof meta.wsUrl === 'string' &&
-        meta.wsUrl.length > 0 &&
-        typeof meta.wsToken === 'string' &&
-        meta.wsToken.length > 0;
+    // A held credential counts as a pending live trio on a bridge-capable
+    // boot: the boot refresh below may make it one (ggui#1496 F7).
+    const liveTrioPending = hasLiveTrio(meta) || (held !== undefined && credentialController !== null);
     // Transport-telemetry sink — the iframe's self-report channel (see
     // runtime-telemetry.ts). Created for EVERY boot with an App bridge;
     // the first batch carries the boot-path decision so operators can
@@ -743,9 +762,14 @@ export async function bootSequence(opts) {
     mountSuperseded = false;
     telemetry?.record('boot.path', JSON.stringify({
         hasStaticContent,
-        hasLiveTrio,
+        hasLiveTrio: hasLiveTrio(meta),
+        heldCredential: held !== undefined,
         bridgeCapable: telemetryApp !== null,
     }));
+    // Set when the static fetch failed while a live trio was pending: if no
+    // live channel comes of it, the boot ends on this failure as it would
+    // have with no trio at all.
+    let staticMountFailure;
     // ── Static seed mount — zero-round-trip paint, no WS required. ──────
     // The ONLY mount path for spec-compliant MCP-Apps hosts that expose no
     // ggui live channel (claude.ai / ChatGPT / Claude Desktop), AND the
@@ -767,12 +791,13 @@ export async function bootSequence(opts) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            if (!hasLiveTrio) {
+            if (!liveTrioPending) {
                 // No WS fallback — a failed static fetch is terminal.
                 setStatus(refs, `static mount failed: ${message}`, 'error');
                 emitBootFailure('UI_INITIALIZE_FAILED', message);
                 return { ok: false, mountedRender };
             }
+            staticMountFailure = message;
             // A live trio is present — the WS ack will deliver the render.
             // The seed was best-effort; fall through to subscribe. Warn so a
             // degraded boot (slower first paint, ack-only delivery) is visible
@@ -800,8 +825,33 @@ export async function bootSequence(opts) {
     // ladder at its tail). Gating the terminal rung behind the WS
     // trio's presence disabled it on precisely the host class it was
     // built for.
-    const staticOnlyNoBridge = !hasLiveTrio && getCurrentApp() === null;
-    if (!hasLiveTrio && mountedRender === null) {
+    // ── The boot refresh (ggui#1496 R1). ─────────────────────────────────
+    // A slice whose live credential expired, on either shape, refreshes it
+    // once, now, through the host, before any ladder binds; an adopted
+    // credential makes this a live boot. A live-only slice has no other way
+    // to a live channel, so a relay error there is re-sent (F6); a slice with
+    // static content goes on with whatever the refresh answered.
+    if (held !== undefined && credentialController !== null) {
+        const outcome = await credentialController.onExpired(held, 'boot', hasStaticContent ? undefined : { retries: BOOT_REFRESH_RETRIES });
+        telemetry?.record('boot.credential_refresh', outcome.kind === 'refused' ? `refused:${outcome.code}` : outcome.kind);
+        if (outcome.kind === 'adopted')
+            liveMeta = withLiveCredential(meta, outcome.credential);
+    }
+    const live = hasLiveTrio(liveMeta);
+    const staticOnlyNoBridge = !live && getCurrentApp() === null;
+    if (!live && mountedRender === null) {
+        if (staticMountFailure !== undefined) {
+            setStatus(refs, `static mount failed: ${staticMountFailure}`, 'error');
+            emitBootFailure('UI_INITIALIZE_FAILED', staticMountFailure);
+            return { ok: false, mountedRender };
+        }
+        if (held !== undefined) {
+            const message = 'the live credential expired and was not refreshed';
+            setStatus(refs, message, 'error');
+            retireShellLoadingIndicator(doc);
+            emitBootFailure('EXPIRED_BOOTSTRAP', message);
+            return { ok: false, mountedRender };
+        }
         const message = 'bootstrap carries neither static content (codeUrl/codeB64/kind) nor a live trio (wsUrl/wsToken)';
         setStatus(refs, message, 'error');
         retireShellLoadingIndicator(doc);
@@ -837,11 +887,11 @@ export async function bootSequence(opts) {
     // `/api/sessions/<id>/stream` URL; SSE `id:` = ledger sequence = the
     // SAME cursor model as the WS `sinceSequence` replay and polling
     // ticks — switching rungs does not lose events.
-    const sseUrl = typeof meta.sseUrl === 'string' && meta.sseUrl.length > 0
-        ? meta.sseUrl
+    const sseUrl = typeof liveMeta.sseUrl === 'string' && liveMeta.sseUrl.length > 0
+        ? liveMeta.sseUrl
         : undefined;
-    const pollingBaseUrl = typeof meta.pollingUrl === 'string' && meta.pollingUrl.length > 0
-        ? meta.pollingUrl
+    const pollingBaseUrl = typeof liveMeta.pollingUrl === 'string' && liveMeta.pollingUrl.length > 0
+        ? liveMeta.pollingUrl
         : undefined;
     // One shared cursor for the whole ladder — SSE deliveries advance it
     // (via onSequence), the polling + bridge descriptors read it per
@@ -855,87 +905,111 @@ export async function bootSequence(opts) {
     const ladderCursor = sseUrl !== undefined || pollingBaseUrl !== undefined || bridgeApp !== null
         ? createSequenceCursor(meta.lastSequence ?? 0)
         : undefined;
+    // How a boot ends when its subscribe fails short of UPGRADE_REQUIRED:
+    // a transport or auth failure.
+    function endOnSubscribeFailure(message) {
+        if (mountedRender !== null) {
+            // DEGRADE — a transport/auth failure AFTER a static seed already
+            // painted. Keep the mounted content, skip live updates (props_update
+            // simply stops arriving), and do NOT tear down or surface a
+            // bootstrap failure. connectFn already emitted the typed
+            // `subscribe-failed` observability event on its own onObserve path.
+            setStatus(refs, `live updates unavailable: ${message}`, 'connecting');
+            emitCodeReadyOnce();
+            return { ok: true, mountedRender };
+        }
+        if (renderer !== null)
+            rendererHooks?.teardown?.(renderer);
+        setStatus(refs, `WS handshake failed: ${message}`, 'error');
+        emitBootFailure('WS_HANDSHAKE_FAILED', message);
+        return { ok: false, mountedRender };
+    }
+    // The ladder set (ggui#1496) owns every ladder this view binds: the boot
+    // ladder below, and each one an adopted credential builds after it. It
+    // composes a ladder's fallback rungs (WS → SSE → polling → bridge-pull)
+    // from the credential's server-stamped wsToken-gated URLs and the shared
+    // cursor seeded from `meta.lastSequence` — same cursor model as the WS
+    // `sinceSequence` replay, so switching transports loses no event. The
+    // bridge rung, the universal floor for CSP-jailed hosts (claude.ai),
+    // exists whenever the App handle is bound.
+    const ladders = createLadderSet({
+        meta,
+        handlers: channelHandlers,
+        cursor: ladderCursor,
+        streamSeq: renderer?.streamSeq,
+        controller: credentialController,
+        connectFn,
+        bridgeCallTool: bridgeApp !== null ? bridgeCallToolVia(bridgeApp) : undefined,
+        onStatus: (status) => {
+            telemetry?.record(`status.${status}`);
+            setStatus(refs, status === 'connected' ? 'Connected.' : `Connection ${status}…`, status);
+            // Propagate WS status to the per-channel transport router so
+            // it can flip WS-bound channels into polling
+            // fallback (on disconnect) and re-send `channel_subscribe`
+            // on reconnect. No-op when renderer wiring is absent.
+            if (renderer !== null) {
+                renderer.channelTransport.onWsStatusChange(status);
+            }
+        },
+        // Reconnect-with-rebootstrap — every ack after the boot's first one,
+        // from the ladder holding the data (a WS reconnect's, or a rebuilt
+        // ladder's), reapplies the server's authoritative `render` snapshot:
+        // a render or update that landed while the live channel was down
+        // restores without an agent re-prompt. The first render a refreshing
+        // boot receives this way is its code-ready.
+        onAck: (ack) => {
+            void applyAck(ack).then(() => {
+                if (mountedRender !== null)
+                    emitCodeReadyOnce();
+            });
+        },
+        // ggui#1424 — the channel door's refusal of a spent one-shot reads as done.
+        onPostAckError: (payload) => handlePostAckErrorFrame(meta.sessionId, payload),
+        onRefresh: (source, outcome) => {
+            telemetry?.record('credential.refresh', `${source}:${outcome.kind === 'refused' ? `refused:${outcome.code}` : outcome.kind}`);
+        },
+        // The server's stream counter restarted (a new epoch, or a count below
+        // this view's cursor); the cursor was forgotten so new envelopes are
+        // not dropped as repeats.
+        onStreamRestart: (streamSeq, streamEpoch) => {
+            telemetry?.record('stream.counter_restart', `${streamSeq ?? '-'}:${streamEpoch ?? '-'}`);
+        },
+        // An honest end (R4, ggui#1496): a bridge pull confirmed the live
+        // channel cannot come back — the host refuses to relay it, or the
+        // session is gone. Every ladder is already disposed; a painted card
+        // stays, under a status that says so, with one typed error and one
+        // observability event naming the confirmation.
+        isConfirmedRelayRefusalCode: (code) => CONFIRMED_RELAY_REFUSAL_CODES.has(code),
+        onEnded: (end) => {
+            const why = end.confirmation === 'relay-refusal'
+                ? `the host refused to relay the live channel (${end.code})`
+                : `the session is gone (session_not_found, ${end.after === 'a-successful-pull' ? 'after a successful pull' : 'twice in a row'})`;
+            telemetry?.record('live.ended', JSON.stringify(end));
+            setStatus(refs, `Live updates ended: ${why}.`, 'error');
+            onProtocolError?.(fromTransportFailure('DISCONNECTED', false, why));
+            onObserve?.({ kind: 'subscribe-failed', reason: 'live-channel-ended', message: why });
+        },
+        // Live-channel diagnostics tap — every channel_* event the
+        // transports emit (failover swaps, polling budget exhaustion,
+        // SSE lifecycle) lands in the telemetry buffer. Without this the
+        // ladder's story on sandboxed hosts is unobservable.
+        ...(telemetry !== null ? { logger: telemetry.channelLogger } : {}),
+        // Typed errors and observability from each subscribe, forwarded
+        // through the runtime's own emitters.
+        ...(onProtocolError !== undefined ? { onProtocolError } : {}),
+        ...(onObserve !== undefined ? { onObserve } : {}),
+    });
+    // The boot ladder carries the controller's credential object itself, so
+    // an expiry it reports is recognised as the current credential's.
+    const bootCredential = hasLiveTrio(liveMeta)
+        ? (credentialController?.current() ?? heldCredentialOf(liveMeta))
+        : undefined;
     let handle;
     try {
-        handle = await connectFn({
-            meta,
-            registry: activeRegistry,
-            // Live-channel diagnostics tap — every channel_* event the
-            // transports emit (failover swaps, polling budget exhaustion,
-            // SSE lifecycle) lands in the telemetry buffer. Without this the
-            // ladder's story on sandboxed hosts is unobservable.
-            ...(telemetry !== null ? { logger: telemetry.channelLogger } : {}),
-            onStatusChange: (status) => {
-                telemetry?.record(`status.${status}`);
-                setStatus(refs, status === 'connected' ? 'Connected.' : `Connection ${status}…`, status);
-                // Propagate WS status to the per-channel transport router so
-                // it can flip WS-bound channels into polling
-                // fallback (on disconnect) and re-send `channel_subscribe`
-                // on reconnect. No-op when renderer wiring is absent.
-                if (renderer !== null) {
-                    renderer.channelTransport.onWsStatusChange(status);
-                }
-            },
-            // Forward typed errors from subscribe through the runtime's
-            // own emitter — connectViaRegistry classifies transport + auth
-            // + version + protocol errors on its own, we just plumb them
-            // along.
-            ...(onProtocolError !== undefined ? { onProtocolError } : {}),
-            // Forward observability emissions — connectFn owns the
-            // schema-version-mismatch + subscribe-failed kinds.
-            ...(onObserve !== undefined ? { onObserve } : {}),
-            // Reconnect-with-rebootstrap — on every ack received AFTER the
-            // initial handshake settled, reapply the server's authoritative
-            // `render` snapshot. A render or update that landed during a WS
-            // dropout window restores here without an agent re-prompt.
-            onResubscribeAck: (ack) => {
-                void applyAck(ack);
-            },
-            // Failover-ladder fallback rungs (WS → SSE → polling →
-            // bridge-pull), composed once at bind time from the
-            // server-stamped wsToken-gated URLs + `meta.lastSequence`
-            // (shared cursor seed). FailoverHandle descends a rung on each
-            // 'failed'; the bridge rung is terminal (never emits 'failed').
-            //
-            // Same cursor model as the WS subscribe `sinceSequence` replay
-            // path — switching transports does not lose events.
-            ...(sseUrl !== undefined && ladderCursor !== undefined
-                ? {
-                    sse: {
-                        url: sseUrl,
-                        initialSinceSequence: ladderCursor.get(),
-                        onSequence: (seq) => {
-                            ladderCursor.advance(seq);
-                        },
-                    },
-                }
-                : {}),
-            ...(pollingBaseUrl !== undefined && ladderCursor !== undefined
-                ? {
-                    polling: buildEventsPolling({
-                        baseUrl: pollingBaseUrl,
-                        cursor: ladderCursor,
-                    }),
-                }
-                : {}),
-            // Bridge-pull terminal rung — composed whenever the App handle
-            // is bound (it always is by this point in the boot: connectApp
-            // succeeded and setCurrentApp ran above), INDEPENDENT of
-            // sseUrl/pollingUrl presence. This is the universal floor for
-            // CSP-jailed hosts (claude.ai) where the iframe has no network
-            // path at all: the ledger is pulled via `ggui_runtime_pull`
-            // `tools/call`s over the host's postMessage bridge. Shares the
-            // SAME ladder cursor — a demotion into the bridge resumes from
-            // whatever the rungs above already delivered.
-            ...(bridgeApp !== null && ladderCursor !== undefined
-                ? {
-                    bridge: buildBridgePolling({
-                        callTool: (name, args) => bridgeApp.callServerTool({ name, arguments: args }),
-                        sessionId: meta.sessionId,
-                        cursor: ladderCursor,
-                    }),
-                }
-                : {}),
+        handle = await ladders.connectBoot({
+            credential: bootCredential,
+            sseUrl,
+            pollingUrl: pollingBaseUrl,
         });
     }
     catch (err) {
@@ -954,24 +1028,21 @@ export async function bootSequence(opts) {
             emitBootFailure('UPGRADE_REQUIRED', message);
             return { ok: false, mountedRender };
         }
-        const message = err instanceof Error ? err.message : String(err);
-        if (mountedRender !== null) {
-            // DEGRADE — a transport/auth failure AFTER a static seed already
-            // painted. Keep the mounted content, skip live updates (props_update
-            // simply stops arriving), and do NOT tear down or surface a
-            // bootstrap failure. connectFn already emitted the typed
-            // `subscribe-failed` observability event on its own onObserve path.
-            setStatus(refs, `live updates unavailable: ${message}`, 'connecting');
-            emitCodeReadyOnce();
-            return { ok: true, mountedRender };
-        }
-        if (renderer !== null)
-            rendererHooks?.teardown?.(renderer);
-        setStatus(refs, `WS handshake failed: ${message}`, 'error');
-        emitBootFailure('WS_HANDSHAKE_FAILED', message);
-        return { ok: false, mountedRender };
+        return endOnSubscribeFailure(err instanceof Error ? err.message : String(err));
+    }
+    // A pre-ack auth-class refusal resolves with the ladder instead of
+    // rejecting (ggui#1496 fact 3). For an expired credential the boot
+    // ladder has already asked for a refresh; when it adopts a new one, the
+    // ladder that credential builds takes the view over, so the boot goes on
+    // wiring. A refresh that is skipped or refused, and any other refusal,
+    // end the boot as the rejection did.
+    const bootRefresh = handle.refused?.code === 'BOOTSTRAP_EXPIRED' ? await ladders.bootRefresh() : undefined;
+    const refreshing = bootRefresh?.kind === 'adopted';
+    if (handle.refused !== undefined && !refreshing) {
+        return endOnSubscribeFailure(handle.refused.message ?? handle.refused.code);
     }
-    telemetry?.record('subscribe.resolved', JSON.stringify({ kind: handle.handle.kind, hasAck: handle.ack !== undefined }));
+    // Health (#1383): booleans only; the handle's kind string stays home.
+    telemetry?.record('subscribe.resolved', JSON.stringify({ hasAck: handle.ack !== undefined }));
     // Attach the live transport handle to the renderer — flushes any
     // buffered outbound `action` frames that were queued while the
     // subscribe handshake completed. `send` narrows to the ws surface:
@@ -979,8 +1050,8 @@ export async function bootSequence(opts) {
     // ride app.callServerTool, not the transport), so its sends drop —
     // the same posture a post-swap FailoverHandle already has.
     const transportSend = (msg) => {
-        if (handle.handle.kind === 'ws')
-            handle.handle.send(msg);
+        // The active ladder's WS (ggui#1496): after a rebind, the new one's.
+        ladders.send(msg);
     };
     if (renderer !== null && rendererHooks?.attachManager !== undefined) {
         rendererHooks.attachManager(renderer, { send: transportSend });
@@ -1013,6 +1084,14 @@ export async function bootSequence(opts) {
     if (handle.ack !== undefined) {
         await applyAck(handle.ack);
     }
+    if (refreshing) {
+        // A refreshed credential was adopted and its ladder is binding; it takes
+        // the view over at its ack, which applies the render (and code-ready
+        // with it). Until then the active ladder's own status stands.
+        if (mountedRender !== null)
+            emitCodeReadyOnce();
+        return { ok: true, mountedRender };
+    }
     setConnectedStatus(refs);
     // Lifecycle `code-ready` — terminal happy state. Emitted ONCE per boot
     // (a static+live meta already fired it from the seed mount, so this is
@@ -1023,33 +1102,20 @@ export async function bootSequence(opts) {
     return { ok: true, mountedRender };
 }
 /**
- * Build a minimal `ChannelRegistry` for boot paths without renderer
- * wiring (boot.test.ts + the C7a placeholder-only spec). The registry
- * carries just the `render` handler — which logs status but does not
- * mount React — so consumers can observe bootstrap-orchestration
- * outcomes without paying React import cost. Every other frame type
- * silently drops. Production boots through `bootProduction` which
- * supplies a fully-populated renderer with the rich handler set.
+ * The handler set for boot paths without renderer wiring (boot.test.ts +
+ * the C7a placeholder-only spec): just the `render` handler — which logs
+ * status but does not mount React — so consumers can observe
+ * bootstrap-orchestration outcomes without paying React import cost.
+ * Every other frame type silently drops. Production boots through
+ * `bootProduction`, whose renderer supplies the rich handler set.
  */
-function createPlaceholderRegistry(params) {
-    const registry = new ChannelRegistry({
-        subscribeFrameBuilder: () => ({
-            type: 'subscribe',
-            payload: {
-                sessionId: params.meta.sessionId,
-                appId: params.meta.appId,
-                ...(params.meta.wsToken !== undefined
-                    ? { wsToken: params.meta.wsToken }
-                    : {}),
-            },
+function createPlaceholderHandlers(params) {
+    return [
+        createRenderHandler({
+            statusRefs: params.statusRefs,
+            pinnedSessionId: params.pinnedSessionId,
         }),
-        classifyFrame: classifyChannelFrame,
-    });
-    registry.register(createRenderHandler({
-        statusRefs: params.statusRefs,
-        pinnedSessionId: params.pinnedSessionId,
-    }));
-    return registry;
+    ];
 }
 /**
  * Frame dispatch lives inside `@ggui-ai/live-channel`'s
@@ -1082,52 +1148,58 @@ function shouldAutostart() {
         return true;
     return process.env?.GGUI_RENDERER_AUTOSTART !== 'false';
 }
-// =============================================================================
-// Self-contained bootstrap (`window.__GGUI_META__`).
-//
-// The default boot path (postMessage `ui/initialize` → parse the
-// `_meta["ai.ggui/render"]` slice → open WebSocket → subscribe →
-// render from frames) is strictly first-party: it requires the host to
-// speak ggui's custom postMessage protocol AND a reachable live-channel
-// WebSocket the renderer can subscribe against. MCP Apps hosts in the
-// wild (Claude Desktop, claude.ai web) speak only the canonical MCP
-// Apps lifecycle and have no commitment to forward the slice key back
-// through `ui/initialize`. The full first-party path stays intact for
-// callers that own both ends; this self-contained path is what makes
-// the same runtime bundle work in third-party MCP Apps hosts.
-//
-// Contract: when the embedding HTML inlines a global of shape
-//   { sessionId: string, appId: string, componentCode: string }
-// (where `componentCode` is base64-encoded compiled ES module source
-// of a React component) BEFORE this bundle's `<script type="module">`
-// executes, the runtime takes over synchronously, mounts the compiled
-// component, and never speaks postMessage / opens a WebSocket. The
-// global is read at module load — a global set later (via deferred
-// scripts, async imports) is too late and the runtime falls through
-// to the legacy postMessage path.
-//
-// `componentCode` carries base64 because the embedding HTML inlines
-// it as a JS string literal next to other `<script>` content; raw
-// JS source contains every character that breaks string-literal
-// embedding (quotes, backticks, `</script>`, newlines, backslash
-// escapes). Base64 sidesteps every escape concern with a 4/3 size
-// overhead that's negligible compared to the network/round-trip
-// savings of skipping postMessage + WS bootstrap.
-// =============================================================================
+/**
+ * The bridge rung's `tools/call` over the host relay (ggui#1415): every
+ * `ggui_runtime_pull` it sends goes through {@link withViewProof}.
+ *
+ * @internal — exported for unit tests + production reuse.
+ */
+export function bridgeCallToolVia(app) {
+    return (name, args) => app.callServerTool(withViewProof(name, args));
+}
+/**
+ * Remove the inline copies of the boot envelope the shell left behind
+ * (ggui#1415): the `__GGUI_META__` global, the pre-load tool-result buffer,
+ * and the self-contained shell's envelope `<script>`, whose text outlives
+ * the global. Called once the boot slice is resolved, after every reader and
+ * before any card code loads; the key root is already held in this module.
+ *
+ * Hygiene, not a boundary: card code runs in this realm and can still ask
+ * the host to read its own locator. This removes the free copies only.
+ */
+function forgetInlineEnvelopes(doc) {
+    Reflect.deleteProperty(globalThis, '__GGUI_META__');
+    Reflect.deleteProperty(globalThis, '__GGUI_PENDING_TOOL_RESULTS__');
+    for (const script of Array.from(doc.querySelectorAll('script:not([src])'))) {
+        if ((script.textContent ?? '').trimStart().startsWith(GGUI_SHELL_META_MARKER))
+            script.remove();
+    }
+}
+/**
+ * A parse result as a boot slice: the ok arm, or an expired live-only
+ * slice with its held credential (the boot refresh may still make it
+ * live); `null` for every other failure.
+ */
+function bootMetaOf(result) {
+    if (!result.ok && result.reason !== 'EXPIRED_BOOTSTRAP')
+        return null;
+    return {
+        meta: result.meta,
+        ...(result.held !== undefined ? { held: result.held } : {}),
+        ...(result.viewRoot !== undefined ? { viewRoot: result.viewRoot } : {}),
+    };
+}
 /**
  * Read `globalThis.__GGUI_META__` synchronously, validate against
- * the unified slice-meta shape, and return the typed meta (or null
+ * the unified slice-meta shape, and return the boot slice (or null
  * on absence / malformation).
  *
- * Thin wrapper around {@link parseMetaFromGlobal}; preserved for
- * back-compat (downstream consumers + tests). Returns `null` instead
- * of {@link McpAppAiGguiMetaParseResult} to match the historical
- * reader contract — the autostart resolver only needs the "valid
- * meta or fall through" signal.
+ * Thin wrapper around {@link parseMetaFromGlobal}. Returns `null`
+ * instead of {@link McpAppAiGguiMetaParseResult} because the autostart
+ * resolver only needs the "a slice to boot, or fall through" signal.
  */
 export function readSelfContainedMeta() {
-    const result = parseMetaFromGlobal();
-    return result.ok ? result.meta : null;
+    return bootMetaOf(parseMetaFromGlobal());
 }
 /**
  * Parse the bootstrap meta's `propsJson` string into a {@link JsonObject}.
@@ -1250,6 +1322,43 @@ export function hasStaticContentMeta(meta) {
         (typeof meta.codeB64 === 'string' && meta.codeB64.length > 0) ||
         (typeof meta.kind === 'string' && meta.kind.length > 0));
 }
+/** Whether the meta carries a live trio a ladder can subscribe with (`wsUrl` + `wsToken`). */
+function hasLiveTrio(meta) {
+    return (typeof meta.wsUrl === 'string' &&
+        meta.wsUrl.length > 0 &&
+        typeof meta.wsToken === 'string' &&
+        meta.wsToken.length > 0);
+}
+/** The live credential a meta's trio carries, as the view holds it (ggui#1496); `undefined` without a trio. */
+function heldCredentialOf(meta) {
+    if (!hasLiveTrio(meta) || meta.wsUrl === undefined || meta.wsToken === undefined)
+        return undefined;
+    return {
+        wsToken: meta.wsToken,
+        wsUrl: meta.wsUrl,
+        ...(meta.expiresAt !== undefined ? { expiresAt: meta.expiresAt } : {}),
+        ...(meta.sseUrl !== undefined ? { sseUrl: meta.sseUrl } : {}),
+        ...(meta.pollingUrl !== undefined ? { pollingUrl: meta.pollingUrl } : {}),
+        origin: 'root',
+    };
+}
+/**
+ * The meta a ladder binds with once a credential is adopted (ggui#1496):
+ * the boot meta with its live trio replaced by the credential's. A URL the
+ * credential does not carry (its token could not be re-derived) is left
+ * off, so that rung is not armed with a dead token.
+ */
+function withLiveCredential(meta, credential) {
+    const { sseUrl: _sse, pollingUrl: _polling, ...rest } = meta;
+    return {
+        ...rest,
+        wsUrl: credential.wsUrl,
+        wsToken: credential.wsToken,
+        ...(credential.expiresAt !== undefined ? { expiresAt: credential.expiresAt } : {}),
+        ...(credential.sseUrl !== undefined ? { sseUrl: credential.sseUrl } : {}),
+        ...(credential.pollingUrl !== undefined ? { pollingUrl: credential.pollingUrl } : {}),
+    };
+}
 /**
  * Decode a `codeB64` slice field to UTF-8 component source. `atob`
  * yields a byte string; routing through `TextDecoder` restores
@@ -1285,8 +1394,7 @@ function decodeCodeB64(codeB64) {
  * impossible because the shell never inspects the slice-meta shape.
  */
 export function extractMetaFromToolResult(params) {
-    const result = parseMetaFromToolResult(params);
-    return result.ok ? result.meta : null;
+    return bootMetaOf(parseMetaFromToolResult(params));
 }
 /**
  * Drain `window.__GGUI_PENDING_TOOL_RESULTS__` — the buffer the
@@ -1313,9 +1421,9 @@ export function readPendingToolResults() {
     if (!Array.isArray(raw) || raw.length === 0)
         return null;
     for (let i = raw.length - 1; i >= 0; i--) {
-        const meta = extractMetaFromToolResult(raw[i]);
-        if (meta !== null)
-            return meta;
+        const boot = extractMetaFromToolResult(raw[i]);
+        if (boot !== null)
+            return boot;
     }
     return null;
 }
@@ -1365,9 +1473,9 @@ function awaitToolResultMetaFromApp(app, timeoutMs) {
         const handler = (params) => {
             if (settled)
                 return;
-            const meta = extractMetaFromToolResult(params);
-            if (meta !== null) {
-                settle(meta);
+            const boot = extractMetaFromToolResult(params);
+            if (boot !== null) {
+                settle(boot);
                 return;
             }
             // Read-plane door (ggui#537): identity-only result → resolve the
@@ -1420,8 +1528,7 @@ export async function resolveMetaViaReadDoor(app, locator) {
     const parsed = parseMcpAppAiGguiRenderMeta(envelope, READ_DOOR_REPORTERS);
     if (!parsed.ok || parsed.meta === undefined)
         return null;
-    const validated = validateMeta(parsed.meta);
-    return validated.ok ? validated.meta : null;
+    return bootMetaOf(validateMeta(parsed.meta));
 }
 function awaitToolResultMeta(timeoutMs) {
     if (typeof window === 'undefined')
@@ -1444,9 +1551,9 @@ function awaitToolResultMeta(timeoutMs) {
                 m.method !== 'ui/notifications/tool-result') {
                 return;
             }
-            const meta = extractMetaFromToolResult(m.params);
-            if (meta !== null) {
-                settle({ kind: 'meta', meta });
+            const boot = extractMetaFromToolResult(m.params);
+            if (boot !== null) {
+                settle({ kind: 'meta', boot });
                 return;
             }
             // Identity-only result (ggui#537): settle NOW with the locator so
@@ -1595,7 +1702,8 @@ function callAppRequestDisplayMode(params) {
  *     migrated to `app.callServerTool` — see emitAudit for the same
  *     posture).
  */
-const productionContextSnapshotPoster = {
+/** @internal — exported for unit tests. */
+export const productionContextSnapshotPoster = {
     postUpdateModelContext: (params) => {
         callAppUpdateModelContext(params);
     },
@@ -1604,14 +1712,11 @@ const productionContextSnapshotPoster = {
             jsonrpc: '2.0',
             id: Math.floor(Math.random() * 1e9),
             method: 'tools/call',
-            params: {
-                name: 'ggui_runtime_sync_context',
-                arguments: {
-                    sessionId: params.sessionId,
-                    appId: params.appId,
-                    snapshot: params.snapshot,
-                },
-            },
+            params: withViewProof('ggui_runtime_sync_context', {
+                sessionId: params.sessionId,
+                appId: params.appId,
+                snapshot: params.snapshot,
+            }),
         });
     },
 };
@@ -1630,10 +1735,10 @@ const productionContextSnapshotPoster = {
  * `CallToolResult` in `{result: ...}`.
  *
  * Drops with an error envelope when no App is bound — the dispatch
- * pipeline classifies that as a transport error and routes to the
- * `ui/message` fallback.
+ * pipeline classifies that as a non-success outcome and drops the
+ * gesture with local feedback (a toast); no `ui/message` fires.
  */
-async function callServerToolSpec(toolName, args) {
+async function callServerToolSpec(toolName, args, proof) {
     const app = getCurrentApp();
     if (app === null) {
         return {
@@ -1643,10 +1748,7 @@ async function callServerToolSpec(toolName, args) {
         };
     }
     try {
-        const result = await app.callServerTool({
-            name: toolName,
-            arguments: args,
-        });
+        const result = await app.callServerTool(withViewProof(toolName, args, proof));
         return { jsonrpc: '2.0', result: result };
     }
     catch (err) {
@@ -1733,17 +1835,14 @@ export function emitAudit(args) {
         jsonrpc: '2.0',
         id: Math.floor(Math.random() * 1e9),
         method: 'tools/call',
-        params: {
-            name: args.toolName,
-            arguments: {
-                kind: args.kind,
-                payload: args.payload,
-                sessionId: args.sessionId,
-                appId: args.appId,
-                actionId: args.actionId,
-                firedAt: args.firedAt,
-            },
-        },
+        params: withViewProof(args.toolName, {
+            kind: args.kind,
+            payload: args.payload,
+            sessionId: args.sessionId,
+            appId: args.appId,
+            actionId: args.actionId,
+            firedAt: args.firedAt,
+        }),
     });
 }
 /**
@@ -2047,17 +2146,21 @@ function hideToast(el) {
 /** The single action-toast element, reused for every message. */
 const ACTION_TOAST_ID = '__ggui-action-toast__';
 /**
- * Lightweight toast UX surface for dispatched actions. Renders a
- * fixed-position element at the bottom of the iframe so the user
- * gets immediate visual feedback that their gesture was registered
- * — "→ Sending action: archive" → "✓ Queued — agent will react"
- * (or "💬 Sent to chat" on ui/message fallback).
+ * The drawn toast for a dispatched action: a fixed-position element at
+ * the bottom of the iframe, drawn only when the visitor has to know or do
+ * something (the copy is {@link GESTURE_COPY}). Two kinds reach it:
+ *   - `'error'` — the gesture did not go through: the relay refused it or
+ *     could not be reached, or the card's own contract refused it. Nothing
+ *     reached the pipe, so no `ui/message` doorbell fires (SPEC §4.7
+ *     "Failure-soft client posture");
+ *   - `'action_required'` — the gesture is queued but no consumer is
+ *     listening and this host cannot take (or refused) the wake-up, so the
+ *     visitor must send a message to continue.
+ * A tap that went through, or a wake-up the host took, is spoken, never
+ * drawn.
  *
- * Without this, the iframe is silent during dispatch. User clicks
- * and waits, with no way to distinguish "click was received but the
- * agent is busy" from "click was lost". Especially load-bearing in
- * the consume-pipe vs ui/message dual-path era — the toast tells
- * the user which path the gesture actually took.
+ * Without it, a failed gesture would be silent: the visitor could not tell
+ * "the agent is busy" from "the tap was lost".
  *
  * Direct DOM (not React-managed) because:
  *  - Works during boot before React mounts.
@@ -2123,7 +2226,110 @@ const GESTURE_COPY = {
     sentToChat: (label) => named(label, 'sent to the chat', 'Sent to the chat'),
     sendToContinue: (label) => `💬 ${named(label, 'agent not listening. Send a message to continue.', 'Agent not listening. Send a message to continue.')}`,
     chatRefused: (label) => `💬 ${named(label, 'the chat did not take the message. Send a message to continue.', 'The chat did not take the message. Send a message to continue.')}`,
+    // ggui#1536 — the card's own action contract refused what the tap would
+    // send, so nothing left the card. The visitor cannot fix that, but a tap
+    // that visibly failed is better than a dead one.
+    refused: (label) => `⚠ ${named(label, 'could not be sent', 'Could not be sent')}`,
+    // ggui#1424 — the server refused the gesture because this one-shot action
+    // already fired on this card: the honest state is "done", not an error.
+    alreadyDone: (label) => `✓ ${named(label, 'already done', 'Already done')}`,
 };
+/**
+ * ggui#1424 — the `oneShot` names the server refused as already spent, per
+ * render, so the wire guard (`refusedSpentOneShots`) reads them beside the
+ * card's persisted record and the control reads done from now on. Keyed by
+ * render id because a `ggui_update` mints a new card whose actions are
+ * re-armed, and that card has a new id.
+ */
+const refusedSpentOneShotsByRender = new Map();
+/** The mounted document's "spent inputs changed" notifier, set at mount; `null` before one. */
+let notifySpentInputsChanged = null;
+/** @internal — exported for unit tests. */
+export function isActionSpentByRefusal(renderId, actionName) {
+    return refusedSpentOneShotsByRender.get(renderId)?.has(actionName) === true;
+}
+function markSpentByRefusal(renderId, actionName) {
+    let set = refusedSpentOneShotsByRender.get(renderId);
+    if (set === undefined) {
+        set = new Set();
+        refusedSpentOneShotsByRender.set(renderId, set);
+    }
+    set.add(actionName);
+    notifySpentInputsChanged?.();
+}
+/** The mounted document's label resolver for an action name, set at mount; `null` before one. */
+let labelForAction = null;
+/**
+ * ggui#1424 — the one answer to a server refusal of a spent one-shot, from
+ * either door (the tool answer or the channel's error frame): the guard
+ * reads the action spent from now on, the host is told on the
+ * `action-refused` channel with the field (never the payload), and the
+ * visitor sees the action as already done — never "could not reach the
+ * agent". Nothing is on the pipe, so no doorbell.
+ */
+function settleOneShotRefusal(renderId, actionName, label) {
+    markSpentByRefusal(renderId, actionName);
+    postObservabilityToParent({
+        kind: 'action-refused',
+        renderId,
+        actionName,
+        violations: [{ field: `actionSpec.${actionName}.oneShot`, keyword: 'oneShot' }],
+    });
+    showActionToast(GESTURE_COPY.alreadyDone(label), 'success');
+}
+/** The action a refusal's violations name at `actionSpec.<name>.oneShot`, or `null`. */
+function oneShotRefusedAction(violations) {
+    if (!Array.isArray(violations))
+        return null;
+    for (const v of violations) {
+        const field = typeof v === 'object' && v !== null ? v.field : undefined;
+        const m = typeof field === 'string' ? /^actionSpec\.(.+)\.oneShot$/.exec(field) : null;
+        if (m?.[1] !== undefined)
+            return m[1];
+    }
+    return null;
+}
+/**
+ * ggui#1424 — a post-ack `error` frame from the live channel. The channel
+ * door refuses a second gesture on a spent one-shot with its
+ * CONTRACT_VIOLATION frame and a violation at `actionSpec.<name>.oneShot`;
+ * that one means done, the same as the tool answer. Any other error frame
+ * changes nothing here.
+ *
+ * @internal — exported for unit tests.
+ */
+export function handlePostAckErrorFrame(renderId, payload) {
+    if (payload.code !== 'CONTRACT_VIOLATION')
+        return;
+    const details = typeof payload.details === 'object' && payload.details !== null ? payload.details : undefined;
+    const actionName = oneShotRefusedAction(details?.violations);
+    if (actionName === null)
+        return;
+    settleOneShotRefusal(renderId, actionName, labelForAction?.(actionName));
+}
+/**
+ * Does a submit_action answer refuse THIS gesture because its one-shot action
+ * already fired on the card (ggui#1424)? The discriminator is the violation's
+ * `field`, `actionSpec.<name>.oneShot` — never the code alone, which a bad
+ * payload shares (`CONTRACT_VIOLATION`, ggui#1358).
+ */
+function readsOneShotRefusal(resp, actionName) {
+    if (resp === null)
+        return false;
+    const inner = submitActionPayload(resp);
+    if (inner === null || inner.ok !== false || inner.code !== 'CONTRACT_VIOLATION')
+        return false;
+    return oneShotRefusedAction(inner.violations) === actionName;
+}
+/**
+ * The toast for a tap the outbound contract check refused (ggui#1536): the
+ * ordinary error toast, named by the action's declared label.
+ *
+ * @internal — exported for unit tests + production reuse.
+ */
+export function showRefusedDispatchToast(label) {
+    showActionToast(GESTURE_COPY.refused(label), 'error');
+}
 function showActionToast(text, kind, onDismiss) {
     if (typeof document === 'undefined')
         return;
@@ -2890,16 +3096,19 @@ export function dispatchSubmitAction(args) {
     // the live session — drop the gesture rather than submit a stale
     // view's action against the current head.
     if (mountSuperseded) {
-        currentTelemetrySink?.record('gesture.dropped_superseded', args.intent);
+        currentTelemetrySink?.record('gesture.dropped_superseded');
         return;
     }
     const { toolName, intent, data, sessionId, appId, label } = args;
+    // Read at entry, inside the gesture's own task (ggui#1415): the dispatch
+    // signs it as the proof's user-activation flag, measured, never enforced.
+    const userActivation = userActivationIsActive();
     // Gesture-path telemetry — the click's own autopsy trail. #471
     // round 12 hit a frame whose channels + beacons were fully healthy
     // while clicks produced NOTHING observable; without a record at the
     // dispatch entry there is no way to tell "handler never fired" from
     // "dispatch swallowed it" on a console-less host.
-    currentTelemetrySink?.record('gesture.dispatch', JSON.stringify({ intent, toolName }));
+    currentTelemetrySink?.record('gesture.dispatch', JSON.stringify({ toolName }));
     const firedAt = new Date().toISOString();
     const actionId = fnv1aHex(`${intent}|${JSON.stringify(data ?? null)}|${firedAt}`);
     const uiContext = readLocalUiContext();
@@ -2983,7 +3192,7 @@ export function dispatchSubmitAction(args) {
                 appId,
                 actionId,
                 firedAt,
-            });
+            }, { userActivation });
         }
         catch {
             showActionToast(GESTURE_COPY.transportError(label), 'error');
@@ -2991,12 +3200,11 @@ export function dispatchSubmitAction(args) {
         }
         // Final hop of the gesture autopsy trail — what the relay
         // answered (or that it didn't).
+        // No free text (#1383): the relay's error CODE rides, never its
+        // message (a host's words), and the intent string stays home.
         currentTelemetrySink?.record('gesture.result', JSON.stringify({
-            intent,
             ok: resp !== null && resp.error === undefined,
-            ...(resp?.error?.message !== undefined
-                ? { error: resp.error.message.slice(0, 120) }
-                : {}),
+            ...(typeof resp?.error?.code === 'number' ? { code: resp.error.code } : {}),
         }));
         // Self-healing (ggui#440): a result envelope arriving at all is
         // proof this host CAN relay — `{ok:false, code:'PIPE_NOT_FOUND'}`
@@ -3084,6 +3292,17 @@ export function dispatchSubmitAction(args) {
             // listener dismisses it when ggui_consume drains the event.
             return;
         }
+        // ggui#1424 — the server refused the gesture because this one-shot
+        // action already fired on the card (a tap that got past the guard: a
+        // re-served card before its spent record arrived, a forced click). The
+        // honest state is DONE: the guard reads the action spent from now on,
+        // the host is told on the `action-refused` channel with the field, and
+        // the visitor sees the action as already done — never "could not reach
+        // the agent". Nothing is on the pipe, so no doorbell.
+        if (readsOneShotRefusal(resp, intent)) {
+            settleOneShotRefusal(sessionId, intent, label);
+            return;
+        }
         // Enqueue failed (pipe gone / transport error / host has no relay).
         // The gesture is not on any pipe, so a doorbell would point at an
         // empty queue; no `ui/message` is emitted either way.
@@ -3537,15 +3756,22 @@ export function __resetInterceptorsForTest() {
  * its event system. The App handle is passed by the boot path
  * directly (pre-connect, so `getCurrentApp()` is not yet set).
  */
-function installPersistentToolResultListener(app) {
+function installPersistentToolResultListener(app, viewRoots) {
     if (persistentToolResultListenerApps.has(app))
         return;
     persistentToolResultListenerApps.add(app);
     let lastMetaKey = null;
     app.addEventListener('toolresult', (params) => {
-        const meta = extractMetaFromToolResult(params);
-        if (meta === null)
+        // A re-mount re-applies the static seed only; the one live channel is
+        // the boot's, so a credential held here has nothing to refresh.
+        const resolved = extractMetaFromToolResult(params);
+        if (resolved === null)
             return;
+        const meta = resolved.meta;
+        // A later slice's view key root (ggui#1415) is offered whether or not it
+        // re-mounts anything: the holder keeps it only for its own session and
+        // only when it is newer, and ignores a slice that carries none.
+        viewRoots.offer(meta.sessionId, resolved.viewRoot);
         // Cheap dedupe — the host may emit the same tool-result more
         // than once (claude.ai re-broadcasts on iframe re-attach).
         // Re-mounting the same slice meta would flicker without changing
@@ -3657,7 +3883,7 @@ function readLiveBootstrapShape() {
  * fallback share one call site — keeps the WS-driven boot semantics
  * single-sourced.
  *
- * `preResolvedMeta` is threaded in from the autostart resolver when
+ * `preResolved` is threaded in from the autostart resolver when
  * it has already discovered slice meta — via inline `__GGUI_META__`
  * global, a buffered `__GGUI_PENDING_TOOL_RESULTS__` entry, or an
  * early `ui/notifications/tool-result` postMessage. Threading skips
@@ -3665,7 +3891,7 @@ function readLiveBootstrapShape() {
  * re-await the same postMessage or re-parse the same global), saving
  * up to the 30s postMessage timeout for spec-strict hosts.
  */
-function runBootProduction(preResolvedMeta, preResolvedLocator) {
+function runBootProduction(preResolved, preResolvedLocator) {
     const { app, transport } = createDefaultApp();
     void bootProduction({
         doc: document,
@@ -3680,7 +3906,7 @@ function runBootProduction(preResolvedMeta, preResolvedLocator) {
         },
         onObserve: postObservabilityToParent,
         onLifecycle: postLifecycleToParent,
-        ...(preResolvedMeta !== undefined ? { preResolvedMeta } : {}),
+        ...(preResolved !== undefined ? { preResolved } : {}),
         ...(preResolvedLocator !== undefined ? { preResolvedLocator } : {}),
     });
 }
@@ -3700,7 +3926,7 @@ if (shouldAutostart() && typeof window !== 'undefined') {
     //   3. Live `ui/notifications/tool-result` postMessage — the
     //      spec-canonical channel for spec-strict hosts (`<AppRenderer>`,
     //      ChatGPT, claude.ai). Caught meta threads through as
-    //      `preResolvedMeta` so `bootSequence` doesn't re-await it.
+    //      `preResolved` so `bootSequence` doesn't re-await it.
     //
     // `readLiveBootstrapShape` still short-circuits the 30s tool-result
     // wait when a live-channel envelope is already inlined — OSS embedded
@@ -3729,7 +3955,7 @@ if (shouldAutostart() && typeof window !== 'undefined') {
                 if (pre === null)
                     runBootProduction();
                 else if (pre.kind === 'meta')
-                    runBootProduction(pre.meta);
+                    runBootProduction(pre.boot);
                 else
                     runBootProduction(undefined, pre.locator);
             });
@@ -3908,7 +4134,30 @@ async function bootProduction(opts) {
                     renderListeners.delete(listener);
                 };
             };
+            // ggui#1424 — a server refusal marks an action spent; the guard re-reads
+            // through the same listeners a replaced render wakes.
+            notifySpentInputsChanged = () => {
+                for (const listener of renderListeners)
+                    listener();
+            };
+            labelForAction = (actionName) => declaredActionLabel(currentRender, actionName);
             let renderHandle = null;
+            // ggui#1679 — the card's render failure reaches the server once per
+            // session, in the tool's terms, over the same proof-carrying bridge
+            // every runtime tool call rides. The App handle is read when the
+            // failure happens, not now: a boot with no bridge has nowhere to
+            // report, and the reporter then spends its one report on nothing,
+            // which is the "not reported" outcome SPEC §4.9 allows.
+            const renderFailureReporter = createRenderFailureReporter({
+                sessionId: meta.sessionId,
+                appId: meta.appId,
+                callTool: (name, args) => {
+                    const bridge = getCurrentApp();
+                    if (bridge === null)
+                        return Promise.reject(new Error('no App bridge bound: the report has no relay'));
+                    return bridgeCallToolVia(bridge)(name, args);
+                },
+            });
             const dispatchToolName = resolveDispatchToolName();
             // Native-idiom interceptors — the replacement for the retired
             // openLink / requestDisplayMode wire primitives. Installed here
@@ -3955,7 +4204,15 @@ async function bootProduction(opts) {
                 sessionId: meta.sessionId,
                 appId: meta.appId,
                 getCurrentGguiSession: () => currentRender,
+                // ggui#1536 — the adapter posted `action-refused` to the host; the
+                // visitor sees the tap failed, named by its declared label.
+                onDispatchRefused: (actionName) => showRefusedDispatchToast(declaredActionLabel(currentRender, actionName)),
                 renderChanges: onRenderChange,
+                // ggui#1424 — the names the server refused as already spent on this card.
+                refusedSpentOneShots: () => {
+                    const set = currentRender === null ? undefined : refusedSpentOneShotsByRender.get(currentRender.id);
+                    return set === undefined ? undefined : [...set];
+                },
                 manager,
                 streamBus,
                 onDispatchEnvelope: (envelope) => {
@@ -4084,6 +4341,8 @@ async function bootProduction(opts) {
                         return hostPalette !== undefined ? { hostPalette } : {};
                     })(),
                     ...(wrapOuter !== undefined ? { wrapOuter } : {}),
+                    // The boundary's give-up is reported to the server (ggui#1679).
+                    onRenderFailure: renderFailureReporter.report,
                 };
             };
             /**
@@ -4198,39 +4457,28 @@ async function bootProduction(opts) {
                     }
                     : {}),
             });
-            // B3b — live-channel registry owns dispatch for every routable
-            // WS frame type. Each handler closes over the renderer state it
-            // needs. `bootSequence` calls `connectFn` (default
-            // `connectViaRegistry`) which registers the `ack` + `error`
-            // handshake handlers and binds the WS transport — frames then
-            // arrive directly through the registered handlers without an
-            // intermediate `onMessage` fan-out.
+            // B3b — the handler for every routable frame type, each closing
+            // over the renderer state it needs. The runtime's ladder set
+            // (ggui#1496) registers these same handler objects on every ladder
+            // it binds, one registry per credential; `connectViaRegistry` adds
+            // the `ack` + `error` handshake handlers and binds the transport,
+            // and frames arrive directly through them.
             //
             // CLIENT_SUPPORTED_VERSIONS handshake is enforced inside
             // `connectViaRegistry`'s ack-handler closure (NOT here).
-            const channelRegistry = new ChannelRegistry({
-                subscribeFrameBuilder: () => ({
-                    type: 'subscribe',
-                    payload: {
-                        sessionId: meta.sessionId,
-                        appId: meta.appId,
-                        ...(meta.wsToken !== undefined
-                            ? { wsToken: meta.wsToken }
-                            : {}),
-                    },
-                }),
-                classifyFrame: classifyChannelFrame,
-            });
-            channelRegistry.register(createRenderHandler({
+            const channelHandlers = [];
+            channelHandlers.push(createRenderHandler({
                 statusRefs,
                 pinnedSessionId: meta.sessionId,
                 applyRender,
                 getChannelTransport: () => channelTransport,
             }));
-            channelRegistry.register(createDataHandler({
+            const streamSeq = createStreamSeqTracker();
+            channelHandlers.push(createDataHandler({
                 getCurrentGguiSession: () => currentRender,
                 streamBus,
                 validatorCtx,
+                streamSeq,
             }));
             // Freeze latch (#483). This mount's own history epoch, read once
             // from its boot meta: render → 0, an update-minted card → its N,
@@ -4248,18 +4496,18 @@ async function bootProduction(opts) {
                 currentTelemetrySink?.record('epoch.frozen', String(selfEpoch));
                 applyFreezeCue(renderInto);
             };
-            channelRegistry.register(createPropsUpdateHandler({
+            channelHandlers.push(createPropsUpdateHandler({
                 getCurrentGguiSession: () => currentRender,
                 applyRender,
                 getSelfEpoch: () => selfEpoch,
                 onSuperseded: supersede,
                 isSuperseded: () => superseded,
             }));
-            channelRegistry.register(createDrainAckHandler({ dispatch: dispatchDrainAck }));
-            channelRegistry.register(createChannelPayloadHandler({
+            channelHandlers.push(createDrainAckHandler({ dispatch: dispatchDrainAck }));
+            channelHandlers.push(createChannelPayloadHandler({
                 getChannelTransport: () => channelTransport,
             }));
-            channelRegistry.register(createChannelErrorHandler({
+            channelHandlers.push(createChannelErrorHandler({
                 getChannelTransport: () => channelTransport,
             }));
             return {
@@ -4271,7 +4519,8 @@ async function bootProduction(opts) {
                 validatorCtx,
                 manager,
                 channelTransport,
-                channelRegistry,
+                channelHandlers,
+                streamSeq,
                 composedGadgets,
             };
         },
@@ -4302,9 +4551,7 @@ async function bootProduction(opts) {
         renderer,
         ...(opts.onObserve !== undefined ? { onObserve: opts.onObserve } : {}),
         ...(opts.onLifecycle !== undefined ? { onLifecycle: opts.onLifecycle } : {}),
-        ...(opts.preResolvedMeta !== undefined
-            ? { preResolvedMeta: opts.preResolvedMeta }
-            : {}),
+        ...(opts.preResolved !== undefined ? { preResolved: opts.preResolved } : {}),
         ...(opts.preResolvedLocator !== undefined
             ? { preResolvedLocator: opts.preResolvedLocator }
             : {}),