@cairnvibe/sdk 0.2.13 → 0.4.0

package/dist/index.js

@@ -1,18 +1,25 @@
 "use strict";
 "use client";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONVERSATION_STORAGE_KEY = void 0;
 exports.Copilot = Copilot;
+exports.loadPersistedConversation = loadPersistedConversation;
+exports.savePersistedConversation = savePersistedConversation;
+exports.reconstructHistoryFromPersisted = reconstructHistoryFromPersisted;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const navigation_1 = require("next/navigation");
 const lucide_react_1 = require("lucide-react");
 const core_1 = require("@cairnvibe/core");
+const agent_loop_1 = require("./agent-loop");
 const context_collector_1 = require("./context-collector");
+const cursor_overlay_1 = require("./cursor-overlay");
 const element_ladder_1 = require("./element-ladder");
 const runtime_scan_1 = require("./runtime-scan");
 const webmcp_client_1 = require("./webmcp-client");
 const verb_executor_1 = require("./verb-executor");
-function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, reportMissesEndpoint, transcribeEndpoint, speakEndpoint, realtimeUrl, persona = "Cairn", }) {
+const vad_1 = require("./vad");
+function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, reportMissesEndpoint, transcribeEndpoint, speakEndpoint, scopeId, planEndpoint, criticEndpoint, skillsSaveEndpoint, realtimeUrl, persona = "Cairn", }) {
     const pathname = (0, navigation_1.usePathname)() ?? "/";
     // Mirrors `pathname` for use inside long-lived closures (a realtime
     // session's handlers are all created once, when the connection opens —
@@ -26,7 +33,21 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [pathname]);
     const router = (0, navigation_1.useRouter)();
+    // Starts at the same safe default on both server and client's first
+    // render — same hydration-mismatch reason `micSupported` below does this
+    // — then, once actually restored from sessionStorage post-mount (see the
+    // dedicated restore effect further down), flips to whatever a real page
+    // reload (a host app's own mutation handler, e.g. — see
+    // loadPersistedConversation's own doc comment) had showing a moment ago,
+    // so a real reload never again looks like the conversation simply ended.
     const [open, setOpen] = (0, react_1.useState)(false);
+    // Fades the synthetic cursor out once the panel closes (or the widget
+    // itself unmounts) instead of leaving it sitting visible on the page.
+    (0, react_1.useEffect)(() => {
+        if (!open)
+            (0, cursor_overlay_1.hideCursor)();
+        return () => (0, cursor_overlay_1.hideCursor)();
+    }, [open]);
     // Collapsed by default so the panel only ever shows the current exchange
     // — the full archived transcript (built up over a long conversation)
     // stays out of the way behind an explicit toggle instead of always being
@@ -34,6 +55,18 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
     const [historyExpanded, setHistoryExpanded] = (0, react_1.useState)(false);
     const [question, setQuestion] = (0, react_1.useState)("");
     const [answer, setAnswer] = (0, react_1.useState)(null);
+    // Real, live-reported gap this closes: once a continuing agent-loop step
+    // (click/fill/read/call_tool/batch) sets `answer` to its own progress
+    // text ("Typing earbuds into the search box"), that text just sat there
+    // unchanged for however long the NEXT resolveVerb call took — several
+    // real seconds, more under rate-limit retries — with nothing on screen
+    // telling the user the agent was still actually doing something. `answer`
+    // itself can't double as that signal (a terminal turn's own real,
+    // finished answer looks identical to unfinished progress text). This is
+    // a separate, explicit flag: true from the moment a continuing step's
+    // progress text is shown until the turn actually ends (a terminal verb,
+    // an error, or a give-up) — see its own setters below for exactly where.
+    const [loopWorking, setLoopWorking] = (0, react_1.useState)(false);
     const [status, setStatus] = (0, react_1.useState)("idle");
     const [caption, setCaption] = (0, react_1.useState)("");
     // The user's own last question, shown as its own floating caption bubble
@@ -106,6 +139,18 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
     const rtMicMutedRef = (0, react_1.useRef)(false);
     const rtSpeakerMutedRef = (0, react_1.useRef)(false);
     const rtStartingRef = (0, react_1.useRef)(false); // closes the click-to-first-state-update gap so a rapid double-click can't open two sessions
+    // The generation of the most recent "final" this client has processed —
+    // see ServerMessage's own doc comment in realtime-server.ts for the full
+    // real, live-found bug this closes: the client's own local barge-in can
+    // start a NEW turn (a new "final") before an EARLIER turn's own verb/
+    // audio, already in flight on the wire when the server processed that
+    // barge-in, actually arrives. WebSocket delivers messages in order, but
+    // "in order" isn't "still current" — every verb/speaking_start/
+    // audio_chunk/speaking_end/turn_complete message carries the generation
+    // it was produced under, and the handler drops it outright if it's
+    // older than this ref's value instead of applying it to whatever
+    // caption happens to be showing now.
+    const rtLastFinalGenerationRef = (0, react_1.useRef)(0);
     // Progressive PCM playback for the buffered (non-realtime) speak endpoint
     // — the same gapless AudioBufferSourceNode scheduling the realtime path
     // uses for its audio_chunk messages (see rtPlaybackCtxRef below), just fed
@@ -118,6 +163,37 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
     const typedPlaybackGainRef = (0, react_1.useRef)(null);
     const typedNextPlayTimeRef = (0, react_1.useRef)(0);
     const typedScheduledSourcesRef = (0, react_1.useRef)([]);
+    // Bumped by stopTypedPlayback() every time it runs — playPcmStream's own
+    // async reader loop checks this before scheduling each chunk, so a
+    // superseded call (two speak()/ask() replies resolving close together)
+    // actually STOPS reading and scheduling more audio once a newer call has
+    // taken over, instead of continuing to push nodes into the shared
+    // playback graph behind the newer call's back. stopTypedPlayback() on
+    // its own only ever stopped nodes that already existed at the moment it
+    // ran — it never told an in-flight stream reader to stop producing MORE
+    // of them, which is exactly what let two replies' audio genuinely
+    // overlap (one starting, then a second call's audio starting on top of
+    // it moments later) — a real, live-found race, not a guess.
+    const typedPlaybackGenerationRef = (0, react_1.useRef)(0);
+    // A DIFFERENT real gap the generation counter above doesn't close: it
+    // only protects one typed reply's audio against ANOTHER typed reply's
+    // audio. A typed ask()/speak() call already in flight — its /api/
+    // copilot/speak fetch genuinely takes several seconds under real
+    // conditions (rate-limit retries make this worse, not better) — has no
+    // way to know a realtime call started WHILE it was still waiting. Its
+    // response arrives, and normally-innocent code plays it, seconds after
+    // startRealtime() already ran — genuinely overlapping with the live
+    // call's own audio, since nothing about the realtime session's own
+    // start/mute/barge-in controls have any way to reach a typed reply
+    // that hadn't even been scheduled yet when they ran. Found live: two
+    // full agent answers, sourced entirely from separate /api/copilot/
+    // speak calls, audibly overlapping about a second apart, while a
+    // realtime call was the only thing visibly active in the UI the whole
+    // time. startRealtime() sets this; endRealtime() clears it; speak()/
+    // speakAndWait() check it AFTER their fetch resolves and drop the
+    // reply's audio entirely (never call playPcmStream at all) if a
+    // realtime call has taken over since the request was made.
+    const typedPlaybackSuspendedRef = (0, react_1.useRef)(false);
     // Watchdog for the "rt-thinking" state: started on every "final" transcript,
     // cleared the moment the server responds with anything for that turn
     // (verb/speaking_start/speaking_end/turn_complete/error). If it ever
@@ -140,6 +216,36 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
     // finished arriving, so the mic can't start sending while the agent is
     // still audibly speaking.
     const rtAudioDoneArrivingRef = (0, react_1.useRef)(true);
+    // Diagnostic only, not a functional guard — flips to true the first time
+    // a real mic packet is actually sent after transitioning to
+    // "rt-listening", logged once (not per-packet, which would flood the
+    // console). Added specifically so a "status says Listening… but nothing
+    // I say gets picked up" report can be told apart, from the log alone,
+    // between "the send gate never opened" (this never logs) and "the gate
+    // opened and sent real audio, so the problem is somewhere else entirely
+    // — Deepgram's own STT, or a real hardware/OS mic issue this app can't
+    // see or fix" (this logs once, then goes quiet as expected).
+    const micAudioSentSinceListeningRef = (0, react_1.useRef)(false);
+    // Safety net for a live realtime call outliving this component instance:
+    // without this, unmounting (a parent removing the widget, a route change
+    // that remounts it, or — the real, live-hit case — Next.js Fast Refresh
+    // remounting the component on every dev-mode source edit while a call is
+    // open) left the WebSocket, the open getUserMedia mic stream, and both
+    // AudioContexts running completely orphaned: nothing ever called
+    // rtSocketRef.current?.close() or stopped the mic tracks. The old,
+    // zombie connection then kept transcribing and replying in parallel with
+    // whatever the newly-mounted instance does next — the literal
+    // "two things running in parallel, the agent answering twice" bug found
+    // live. endRealtime() is safe to call from an unmount cleanup even
+    // though it also calls React state setters: it only reads stable refs
+    // (never a stale closure over props/state), and React 18 silently no-ops
+    // a setState call on an already-unmounted component.
+    (0, react_1.useEffect)(() => {
+        return () => {
+            if (rtSocketRef.current || rtCleanupRef.current)
+                endRealtime();
+        };
+    }, []);
     // Starts false on both server and client's first render (avoids a
     // hydration mismatch — `navigator` doesn't exist during SSR), then
     // updated after mount, once we're only ever running in the browser.
@@ -147,6 +253,36 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
     (0, react_1.useEffect)(() => {
         setMicSupported(!!navigator.mediaDevices?.getUserMedia && typeof MediaRecorder !== "undefined");
     }, []);
+    // Restores a conversation that survived a real page reload — same
+    // hydration-safety reason as `micSupported` just above: `open`/`answer`/
+    // `lastQuestion`/`transcript` all start at their normal empty defaults on
+    // both server and client's first render (matching what SSR produced), and
+    // only flip to whatever sessionStorage actually holds here, post-mount.
+    // Real, live-verified bug this closes: a host app's own mutation handler
+    // calling `window.location.reload()` (this SDK's own demo app does this
+    // after several real actions, e.g. moving a kanban card) tears down the
+    // entire React tree, this widget included — every bit of visible
+    // conversation state reset to nothing, making an in-progress conversation
+    // look like it had simply ended the instant the host page happened to
+    // reload, even though nothing about the CONVERSATION itself was over.
+    (0, react_1.useEffect)(() => {
+        const persisted = loadPersistedConversation();
+        if (!persisted)
+            return;
+        setOpen(persisted.open);
+        setAnswer(persisted.answer);
+        setLastQuestion(persisted.lastQuestion);
+        setTranscript(persisted.transcript);
+        historyRef.current = reconstructHistoryFromPersisted(persisted);
+        // Starts past the restored transcript's own highest id — otherwise the
+        // very next archived entry would reuse an id already on screen, a real
+        // duplicate-React-key bug (React silently confuses which DOM node is
+        // which when two list items share a key).
+        if (persisted.transcript.length > 0) {
+            transcriptIdRef.current = Math.max(...persisted.transcript.map((t) => t.id)) + 1;
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
     const asking = status === "asking";
     const recording = status === "recording";
     const realtimeActive = status.startsWith("rt-");
@@ -166,6 +302,25 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
     (0, react_1.useEffect)(() => {
         answerRef.current = answer;
     }, [answer]);
+    // Persists the visible conversation to sessionStorage on every change, so
+    // a host app's own `window.location.reload()` (e.g. after a board-card
+    // move — see loadPersistedConversation's own comment for the full story)
+    // doesn't make an in-progress conversation look like it simply ended.
+    // Skips its own very first (mount) invocation on purpose: that call is
+    // always tied to the initial render's plain defaults (open:false,
+    // transcript:[], ...) — captured before the restore effect above's
+    // setState calls have actually landed — so persisting it would clobber a
+    // real, just-restored conversation with empty state for one tick, right
+    // before the corrective post-restore render fixes it back. Skipping costs
+    // nothing on a genuinely fresh session (there's nothing to persist yet).
+    const skippedMountPersistRef = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        if (!skippedMountPersistRef.current) {
+            skippedMountPersistRef.current = true;
+            return;
+        }
+        savePersistedConversation({ transcript, lastQuestion, answer, open });
+    }, [transcript, lastQuestion, answer, open]);
     // Auto-scroll to the newest content whenever the transcript grows or the
     // live (not-yet-archived) bubble's text changes.
     (0, react_1.useEffect)(() => {
@@ -235,11 +390,38 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
         }
     }
     function handleVerb(raw) {
+        setLoopWorking(false); // only ever called for a genuinely terminal verb — the turn is over
         (0, verb_executor_1.executeVerbResponse)(raw, pathname, {
             onExplain: (text) => {
                 setAnswer(text);
-                if (!realtimeActive)
-                    void speak(text); // realtime mode gets audio over the socket instead
+                // A REAL, deep, long-standing bug found live — not introduced by
+                // today's other fixes, just newly diagnosed: this function is a
+                // plain closure defined fresh every render, but when a "verb" WS
+                // message arrives it's invoked through ws.onmessage — a callback
+                // assigned ONCE, inside startRealtime(), and never reassigned for
+                // the rest of that connection's life. `realtimeActive` there is
+                // therefore frozen at whatever it was AT THE MOMENT startRealtime()
+                // was called — which is BEFORE the click handler's own state
+                // updates land, so it reads `false` for literally the entire
+                // lifetime of every realtime call. `!realtimeActive` was therefore
+                // ALWAYS true here, on every single realtime turn — this ran
+                // speak() (the typed HTTP path) in addition to the correct
+                // realtime audio_chunk playback, every time. This is the actual,
+                // original root cause of "two speakers" — the earlier
+                // typedPlaybackSuspendedRef fix only ever suppressed the resulting
+                // AUDIO once this was already firing, it never stopped the
+                // firing itself (or the wasted LLM/TTS call and quota burn
+                // underneath it). rtStateRef mirrors status specifically to avoid
+                // this class of bug in a callback like this one (see its own doc
+                // comment) — using it here instead of the stale const is the
+                // actual fix.
+                if (rtStateRef.current.startsWith("rt-")) {
+                    rtLog("explain: realtime call active, letting the socket's own audio_chunk stream speak this");
+                }
+                else {
+                    rtLog("explain: no realtime call active, using the typed speak() HTTP path");
+                    void speak(text);
+                }
             },
             onNavigate: (route) => router.push(route),
             onMiss: reportMiss,
@@ -267,7 +449,16 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
      */
     async function runTour(steps) {
         const myGeneration = ++tourGenerationRef.current;
-        const wasRealtimeListening = realtimeActive;
+        // Same real stale-closure bug as onExplain's own fix above, and the
+        // reason a realtime-triggered tour spoke through the wrong pipeline
+        // (or, after that fix suppressed the wrong pipeline's audio, spoke
+        // through nothing at all — "tour did not speak anything") and could
+        // leave the mic never properly told to resume listening afterward
+        // (see the `setRtStatus("rt-listening")` call at the end of this
+        // function, fixed the same way). rtStateRef.current is always
+        // current, regardless of which render's closure this particular
+        // invocation runs inside.
+        const wasRealtimeListening = rtStateRef.current.startsWith("rt-");
         touringRef.current = true;
         if (wasRealtimeListening)
             setRtStatus("rt-speaking");
@@ -350,7 +541,31 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                 return;
             setTourStep(null);
             setCaption("");
-            if (wasRealtimeListening && realtimeActive)
+            // The most damaging half of this stale-closure bug: this used to
+            // read the stale `realtimeActive` const, which meant this call was
+            // ALWAYS skipped for a tour reached via realtime — the mic was
+            // never explicitly told to resume listening once the tour ended.
+            // rtStateRef.current.startsWith("rt-") is what actually reflects
+            // whether the connection is still live right now.
+            if (wasRealtimeListening && rtStateRef.current.startsWith("rt-"))
+                setRtStatus("rt-listening");
+        }
+        catch (err) {
+            // Real, live-found gap: this function had NO catch at all — only
+            // try/finally. Any error thrown anywhere in the loop above (a
+            // rejected speakOverRealtime/speakAndWait call, a DOM exception
+            // from el.click(), a network failure) skipped the resume-listening
+            // line above ENTIRELY, leaving the mic stuck exactly where the
+            // tour left off — matching "after this it's not listening"
+            // reported live. Every other place in this file that can fail
+            // mid-turn (ask(), handleDeepgramMessage's own server-side
+            // equivalent) already guarantees SOME recovery path; this one
+            // didn't have one at all.
+            console.error("[cairn] tour failed partway through:", err);
+            rtLog("tour failed — forcing the mic back to listening instead of leaving it stuck", { error: String(err) });
+            setTourStep(null);
+            setCaption("");
+            if (wasRealtimeListening && rtStateRef.current.startsWith("rt-"))
                 setRtStatus("rt-listening");
         }
         finally {
@@ -371,13 +586,114 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
             await runTypedAgentLoop(q);
         }
         catch {
-            setAnswer("Something went wrong reaching the help service — try again in a moment.");
+            // See typedPlaybackSuspendedRef's own doc comment — this whole
+            // fetch can still be in flight when a realtime call starts.
+            if (!typedPlaybackSuspendedRef.current)
+                setAnswer("Something went wrong reaching the help service — try again in a moment.");
         }
         finally {
-            setStatus("idle");
+            // The most damaging form of the same race: unconditionally forcing
+            // status back to "idle" here, after a realtime call has ALREADY
+            // taken over (status is some "rt-*" value), would silently kick the
+            // UI out of the live call — hiding its mic/speaker/hangup controls
+            // and showing the "start call" screen instead — while the actual
+            // WebSocket connection underneath is still fully alive and still
+            // talking, now with no visible way to manage it at all. Skipping
+            // this reset when suspended is what stops a slow, stale typed
+            // request from ever being able to do that.
+            if (!typedPlaybackSuspendedRef.current)
+                setStatus("idle");
+        }
+    }
+    /**
+     * Architecture Pillar 6 (the safety layer) — the real, working default
+     * confirmation UI: a native browser confirm dialog, naming the tool's
+     * OWN real name/description (never inventing wording), for a WebMCP
+     * tool whose registration declared `riskTier: "confirm"` (a payment, a
+     * delete, anything hard to undo). `window.confirm` blocks the calling
+     * microtask until the user actually answers — exactly the real,
+     * synchronous "get a genuine yes before this runs" behavior needed
+     * here, and simple enough to need no new UI component for this to be a
+     * real, functioning default rather than just plumbing with nothing on
+     * the other end. A host app wanting a nicer in-widget modal can still
+     * build one — this function is the only thing that would need
+     * replacing to do that.
+     */
+    function confirmToolCall(tool) {
+        if (typeof window === "undefined" || typeof window.confirm !== "function")
+            return Promise.resolve(false);
+        const message = tool.description ? `${tool.name}: ${tool.description}\n\nAllow this action?` : `Allow "${tool.name}"?`;
+        return Promise.resolve(window.confirm(message));
+    }
+    /**
+     * Architecture Pillar 4 — the typed transport's own Planner call,
+     * mirroring resolvePlan's real network shape but reached over HTTP
+     * (planEndpoint's server-side handler — createPlanHandler in server.ts
+     * — is the only place that can hold the real LLM API key). Never
+     * throws: any network/parse failure degrades to the exact same single-
+     * task fallback plan resolvePlan itself falls back to on an LLM error,
+     * so a Planner hiccup never blocks the turn.
+     */
+    async function fetchPlan(goal, version = 1) {
+        try {
+            const res = await fetch(planEndpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ goal, version }),
+            });
+            const data = await res.json();
+            if (data && typeof data === "object" && Array.isArray(data.tasks) && data.tasks.length > 0)
+                return data;
+        }
+        catch {
+            // Falls through to the same fallback plan shape below.
+        }
+        return { version, goal, facts: [], tasks: [{ id: "t1", description: goal, doneContract: "The stated goal has been achieved.", status: "in_progress" }] };
+    }
+    /** Same real-network shape as fetchPlan, for criticEndpoint's
+     * createCriticHandler — degrades to a safe "continue" verdict on any
+     * failure, same resilience discipline as resolveCritic itself. */
+    async function fetchCriticVerdict(task, goal, verb, observation) {
+        try {
+            const res = await fetch(criticEndpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ task, goal, verb, observation: observation ?? null }),
+            });
+            const data = await res.json();
+            if (data && typeof data.verdict === "string")
+                return data;
+        }
+        catch {
+            // Falls through to the safe default below.
         }
+        return { verdict: "continue", reasoning: "Critic call failed — defaulting to continue rather than blocking the turn." };
+    }
+    /**
+     * Architecture Pillar 3 (Skill half) — the typed transport's own
+     * Formulator save, mirroring realtime-server.ts's own post-turn
+     * `compileSkill`+`saveSkill` call. Fire-and-forget (never awaited by
+     * the caller, never allowed to affect what the user sees) since saving
+     * a Skill is bookkeeping for a FUTURE turn, not part of answering this
+     * one — matches the Formulator's own "cheap, runs once per turn, never
+     * blocks anything" framing. Classifies the current live page for a
+     * best-effort pattern tag the same way resolveVerb's own per-request
+     * classification does server-side.
+     */
+    function saveSkillIfLearned(goal, learnedFacts) {
+        if (!skillsSaveEndpoint || learnedFacts.length === 0)
+            return;
+        const matches = (0, core_1.classifyUiPattern)((0, core_1.deriveStructureSignals)(liveRegistryRef.current.getSnapshot().elements));
+        void fetch(skillsSaveEndpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ goal, learnedFacts, pattern: matches[0]?.pattern }),
+        }).catch(() => {
+            // A Skill that fails to save just means the next similar goal
+            // starts from scratch again, same as if nothing had been learned
+            // this turn — never worth surfacing as a user-visible error.
+        });
     }
-    const MAX_LOOP_ITERATIONS = 6; // a hard cap, not a target — see runTypedAgentLoop
     /**
      * Drives the agent loop over the stateless HTTP path: ask the server,
      * and if it comes back with a continuing step (click/fill/read/
@@ -390,58 +706,196 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
      * still knows what it was actually asked. `historyRef` (the
      * conversation's real memory) is only ever committed once, at the end —
      * a turn that hits the cap mid-loop doesn't leave partial noise in it.
+     * The loop itself (the `for`/TERMINAL_VERBS/iteration-cap shape) lives
+     * in agent-loop.ts, shared with the realtime relay's own finalizeTurn —
+     * this function owns everything transport-specific: the actual fetch,
+     * the raw/untyped response handling a stateless HTTP call needs (unlike
+     * realtime's always-valid in-process resolveVerb call), and the real
+     * historyRef commit.
      */
     async function runTypedAgentLoop(q) {
-        let loopHistory = historyRef.current;
         const webMcpTools = await (0, webmcp_client_1.discoverWebMcpTools)();
-        for (let i = 0; i < MAX_LOOP_ITERATIONS; i++) {
-            const liveScan = liveRegistryRef.current.getSnapshot();
-            liveMapRef.current = liveScan.byId;
-            const res = await fetch(endpoint, {
-                method: "POST",
-                headers: { "content-type": "application/json" },
-                body: JSON.stringify({
-                    route: pathname,
-                    question: q,
-                    visible: (0, context_collector_1.collectVisible)(),
-                    history: loopHistory,
-                    liveElements: liveScan.elements,
-                    webMcpTools,
-                }),
-            });
-            const data = await res.json().catch(() => null);
-            const parsed = (0, core_1.safeParseVerbResponse)(data);
-            if (!parsed || core_1.TERMINAL_VERBS.has(parsed.verb)) {
-                handleVerb(data);
-                // Unlike the realtime relay (one persistent connection, memory
-                // lives server-side), each of these POSTs is stateless — the
-                // widget itself is what remembers, and resends it above so the
-                // model has context for "the first one" / "do that instead" on
-                // the next question.
-                historyRef.current = [
-                    ...loopHistory,
-                    { role: "user", text: q },
-                    { role: "assistant", text: summarizeVerbForHistory(data) },
-                ].slice(-MAX_HISTORY_TURNS);
-                return;
+        let lastRawResponse = null;
+        // Architecture Pillar 4 — real Planner/Critic wiring for the typed
+        // transport, opt-in via planEndpoint/criticEndpoint (see their own
+        // doc comments on CopilotProps) — closes the gap the plan file names
+        // directly ("the typed/HTTP path has zero Planner/Critic wiring at
+        // all... today explicitly realtime-only by deferral, not by
+        // decision"). Mirrors realtime-server.ts's finalizeTurn: an eager
+        // Planner kickoff when looksMultiStep(q) already flags a probable
+        // compound goal, a lazy fallback kickoff on the first continuing step
+        // otherwise, and a genuinely separate Critic pass over each
+        // continuing step's real result. Neither endpoint set (the default)
+        // means plannerEnabled is false and this whole block is a no-op —
+        // the typed loop behaves exactly as it always has.
+        let planPromise = null;
+        let plan = null;
+        let progress = null;
+        const STALL_THRESHOLD = 3; // same bounded budget realtime's own Critic wiring uses
+        const plannerEnabled = Boolean(planEndpoint && criticEndpoint);
+        if (plannerEnabled && (0, agent_loop_1.looksMultiStep)(q))
+            planPromise = fetchPlan(q);
+        // Architecture Pillar 3 (Skill half) — every real, Critic-verified
+        // learnedFact from this turn's steps; saved once the turn concludes,
+        // below (saveSkillIfLearned). Empty is the common case, not a gap.
+        const learnedFacts = [];
+        const result = await (0, agent_loop_1.driveAgentLoop)(historyRef.current, {
+            async getNextStep(loopHistory) {
+                const liveScan = liveRegistryRef.current.getSnapshot();
+                liveMapRef.current = liveScan.byId;
+                const res = await fetch(endpoint, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({
+                        // pathnameRef, not the closed-over `pathname` — a navigate
+                        // step (now possibly continuing, see isTerminalVerb) can
+                        // change the real route mid-loop; this whole async function's
+                        // own `pathname` closure was captured once, at the render
+                        // that started this turn, and never updates again on its own.
+                        route: pathnameRef.current,
+                        question: q,
+                        visible: (0, context_collector_1.collectVisible)(),
+                        history: loopHistory,
+                        liveElements: liveScan.elements,
+                        webMcpTools,
+                        scopeId,
+                    }),
+                });
+                const data = await res.json().catch(() => null);
+                lastRawResponse = data;
+                return (0, core_1.safeParseVerbResponse)(data);
+            },
+            onStep({ verb, terminal }) {
+                // A continuing step — show it happening (execution itself
+                // happens in executeStep below). Terminal steps are handled once
+                // driveAgentLoop returns, via handleVerb — unchanged from before.
+                // Same stale-typed-reply guard as the terminal case below — a
+                // multi-step typed loop can still be mid-flight when a realtime
+                // call starts.
+                if (!terminal && !typedPlaybackSuspendedRef.current) {
+                    setAnswer(summarizeVerbForHistory(verb));
+                    setLoopWorking(true);
+                }
+                // The lazy fallback — only fires when looksMultiStep missed
+                // (planPromise is still null): a real Plan is still guaranteed
+                // before the Critic needs one, just one round trip later.
+                if (!terminal && plannerEnabled && !planPromise)
+                    planPromise = fetchPlan(q);
+                return false;
+            },
+            // Same real, live-found fix as the realtime WS "verb" handler's own
+            // executeToolStep call — a fresh scan per step, not the turn's
+            // frozen liveMapRef, so a step that reveals new DOM (a click that
+            // opens a modal) doesn't leave the NEXT step unable to find
+            // anything in it.
+            executeStep: (verb) => (0, verb_executor_1.executeToolStep)(verb, pathnameRef.current, liveRegistryRef.current.getSnapshot().byId, (route) => router.push(route), confirmToolCall).then((r) => r?.observation),
+            runCritic: plannerEnabled
+                ? async ({ verb, observation }) => {
+                    // Real state, not the Executor's self-report — see
+                    // resolveCritic's own doc comment (server.ts) for why this is
+                    // a genuinely separate pass, same precedent realtime already
+                    // established.
+                    if (!plan) {
+                        plan = planPromise ? await planPromise : await fetchPlan(q);
+                        progress = { planVersion: plan.version, currentTaskIndex: 0, stallCount: 0 };
+                    }
+                    const currentProgress = progress;
+                    const currentTask = plan.tasks[currentProgress.currentTaskIndex];
+                    const verdict = await fetchCriticVerdict(currentTask, q, verb, observation);
+                    if (verdict.learnedFact)
+                        learnedFacts.push(verdict.learnedFact);
+                    if (verdict.verdict === "task_complete") {
+                        currentTask.status = "done";
+                        if (currentProgress.currentTaskIndex < plan.tasks.length - 1) {
+                            // More tasks remain — advance and keep looping instead of
+                            // ending the turn here.
+                            currentProgress.currentTaskIndex++;
+                            plan.tasks[currentProgress.currentTaskIndex].status = "in_progress";
+                            currentProgress.stallCount = 0;
+                            return { ...verdict, verdict: "continue" };
+                        }
+                        // The last task is genuinely done — end the loop right here
+                        // instead of asking the model again and hoping it notices.
+                        return verdict;
+                    }
+                    if (verdict.verdict === "replan") {
+                        plan = await fetchPlan(q, plan.version + 1);
+                        progress = { planVersion: plan.version, currentTaskIndex: 0, stallCount: 0 };
+                        return { ...verdict, verdict: "continue" };
+                    }
+                    if (verdict.verdict === "give_up")
+                        return verdict;
+                    // "continue" — a harness-enforced fail-safe on top of the
+                    // Critic's own judgment, same Magentic-One-shaped two-tier
+                    // tolerance realtime already uses.
+                    currentProgress.stallCount++;
+                    if (currentProgress.stallCount >= STALL_THRESHOLD) {
+                        return {
+                            verdict: "give_up",
+                            reasoning: `Stuck after ${currentProgress.stallCount} steps with no confirmed progress on "${currentTask.description}" — ${verdict.reasoning}`,
+                        };
+                    }
+                    return verdict;
+                }
+                : undefined,
+        });
+        // Architecture Pillar 3 (Skill half) — the Formulator, once per turn.
+        saveSkillIfLearned(q, learnedFacts);
+        if (result.outcome === "terminal" || result.outcome === "unparseable" || result.outcome === "critic-complete") {
+            // A realtime call can start WHILE this whole typed loop (potentially
+            // several real fetches deep) was still in flight — applying this
+            // reply now would overwrite the live call's own answer with a
+            // stale, orphaned bubble that doesn't correspond to anything the
+            // realtime conversation actually said. speak()/speakAndWait() guard
+            // the AUDIO half of this same real, live-found race (see
+            // typedPlaybackSuspendedRef's own doc comment) — this is the
+            // matching guard for the TEXT half, which would otherwise still
+            // leak through even with the audio silenced.
+            // The Critic independently confirmed the last task's doneContract
+            // is satisfied even though the model's own verb never got there —
+            // real fix for the diagnosed bug (a batch succeeded and the model
+            // kept looping instead of recognizing it). No raw server response
+            // exists for this synthesized verb (it never came from `endpoint`
+            // at all), so it's built directly from the verdict's own reasoning
+            // — same shape realtime-server.ts synthesizes for the same outcome.
+            const raw = result.outcome === "critic-complete" ? { verb: "explain", text: result.verdict.reasoning } : lastRawResponse;
+            if (typedPlaybackSuspendedRef.current) {
+                rtLog("dropping stale typed reply's text — a realtime call started while it was still in flight");
             }
-            // A continuing step — show it happening, execute it for real, and
-            // go around again with the real result instead of ending the turn.
-            setAnswer(summarizeVerbForHistory(data));
-            const stepResult = await (0, verb_executor_1.executeToolStep)(data, pathname, liveMapRef.current);
-            loopHistory = [
-                ...loopHistory,
-                {
-                    role: "assistant",
-                    text: `${summarizeVerbForHistory(data)}. Result: ${stepResult?.observation ?? "no result"}`,
-                },
+            else {
+                handleVerb(raw);
+            }
+            // Unlike the realtime relay (one persistent connection, memory
+            // lives server-side), each of these POSTs is stateless — the
+            // widget itself is what remembers, and resends it above so the
+            // model has context for "the first one" / "do that instead" on
+            // the next question. Summarized from the RAW response (not
+            // driveAgentLoop's typed finalVerb) via this file's own untyped
+            // summarizeVerbForHistory — deliberately, since a response that
+            // failed schema validation (outcome "unparseable") can still carry
+            // real, usable fields (e.g. a stray extra property tripped
+            // .strict() while `text` itself was fine) that only the untyped,
+            // duck-typed summarizer sees; there is no typed finalVerb at all
+            // for that outcome.
+            historyRef.current = [
+                ...result.workingHistory,
+                { role: "user", text: q },
+                { role: "assistant", text: summarizeVerbForHistory(raw) },
             ].slice(-MAX_HISTORY_TURNS);
+            return;
         }
-        setAnswer("I wasn't able to finish that — try asking again or breaking it into smaller steps.");
+        // "gave-up" (iteration cap hit with no terminal verb) OR "critic-give-up"
+        // (the Critic/stall fail-safe decided continuing wouldn't help — its
+        // own reasoning is a genuinely better message than the generic
+        // fallback, same as realtime-server.ts's own finalizeTurn).
+        const giveUpText = result.outcome === "critic-give-up" ? result.verdict.reasoning : "I wasn't able to finish that — try asking again or breaking it into smaller steps.";
+        const gaveUpSummary = result.outcome === "critic-give-up" ? giveUpText : "(gave up after too many steps)";
+        setLoopWorking(false);
+        setAnswer(giveUpText);
         historyRef.current = [
-            ...loopHistory,
+            ...result.workingHistory,
             { role: "user", text: q },
-            { role: "assistant", text: "(gave up after too many steps)" },
+            { role: "assistant", text: gaveUpSummary },
         ].slice(-MAX_HISTORY_TURNS);
     }
     function ensureTypedPlaybackGraph() {
@@ -456,8 +910,12 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
     }
     /** Stops whatever's currently playing on the typed/mic path's playback
      * graph, so two responses (e.g. a rapid double-click, or two answers
-     * resolved close together) can never be heard overlapping. */
+     * resolved close together) can never be heard overlapping. Also bumps
+     * typedPlaybackGenerationRef — see its own doc comment for why that's
+     * required for this to actually hold when a NEW reply's audio is still
+     * arriving as a stream, not just already fully scheduled. */
     function stopTypedPlayback() {
+        typedPlaybackGenerationRef.current++;
         for (const source of typedScheduledSourcesRef.current) {
             source.onended = null;
             try {
@@ -486,6 +944,7 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
      */
     function playPcmStream(stream) {
         stopTypedPlayback();
+        const myGeneration = typedPlaybackGenerationRef.current;
         const { ctx, gain } = ensureTypedPlaybackGraph();
         void ctx.resume().catch(() => { });
         return new Promise((resolve) => {
@@ -521,7 +980,16 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                 const reader = stream.getReader();
                 try {
                     for (;;) {
+                        // A newer call already ran stopTypedPlayback() (bumping the
+                        // generation) while we were mid-read — stop here instead of
+                        // scheduling more chunks behind its back. Checked both before
+                        // AND after the await: a supersede can land at any point while
+                        // this loop is blocked waiting on the next chunk.
+                        if (typedPlaybackGenerationRef.current !== myGeneration)
+                            break;
                         const { done, value } = await reader.read();
+                        if (typedPlaybackGenerationRef.current !== myGeneration)
+                            break;
                         if (done)
                             break;
                         if (!value || value.length === 0)
@@ -556,6 +1024,13 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
             });
             if (!res.ok || !res.body)
                 return;
+            // A realtime call can start WHILE this fetch was in flight — see
+            // typedPlaybackSuspendedRef's own doc comment for why that's a real,
+            // live-found overlapping-audio case, not a hypothetical one.
+            if (typedPlaybackSuspendedRef.current) {
+                rtLog("dropping stale typed reply's audio — a realtime call started while it was still being fetched");
+                return;
+            }
             void playPcmStream(res.body);
         }
         catch {
@@ -576,6 +1051,13 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
             });
             if (!res.ok || !res.body)
                 return;
+            // See speak()'s own identical check and typedPlaybackSuspendedRef's
+            // doc comment — a realtime call can start while this fetch was in
+            // flight, same real risk here.
+            if (typedPlaybackSuspendedRef.current) {
+                rtLog("dropping stale typed reply's audio — a realtime call started while it was still being fetched");
+                return;
+            }
             await playPcmStream(res.body);
         }
         catch {
@@ -612,7 +1094,7 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
             // forever with the mic never resuming — move on instead.
             setTimeout(() => {
                 if (!settled)
-                    console.warn("[cairn] tour step audio confirmation timed out — continuing");
+                    rtLog("tour step audio confirmation timed out after 15s — continuing anyway");
                 finish();
             }, 15000);
             ws.send(JSON.stringify({ type: "speak", text }));
@@ -685,7 +1167,24 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
         // which is exactly what "hearing the agent twice, in parallel" was.
         if (!realtimeUrl || !micSupported || realtimeActive || rtStartingRef.current)
             return;
+        rtLog("starting realtime call", { url: realtimeUrl });
         rtStartingRef.current = true;
+        // A typed/mic-recorded reply's audio can still be mid-playback on its
+        // own separate graph (typedPlaybackGainRef, only ever touched by
+        // stopTypedPlayback/playPcmStream) when the user switches straight into
+        // a live call — endRealtime() already stops it on the way OUT of a
+        // call, but nothing stopped it on the way IN, so it kept playing
+        // completely unaffected by the realtime session's own mute-speaker
+        // button (which only ever touches rtPlaybackGainRef) or by barge-in —
+        // a real, live-found "two independent speakers" bug: muting or saying
+        // "stop" only ever reached the realtime pipeline, while this leftover
+        // typed audio played on regardless until it finished on its own.
+        stopTypedPlayback();
+        // Also blocks any typed reply that's still mid-fetch RIGHT NOW (not
+        // yet playing anything, so stopTypedPlayback() above has nothing to
+        // stop) from playing its audio once it finally arrives, seconds from
+        // now — see typedPlaybackSuspendedRef's own doc comment.
+        typedPlaybackSuspendedRef.current = true;
         archiveCurrentExchange(); // preserve whatever typed/mic exchange preceded switching into a live call
         setAnswer(null);
         setCaption("");
@@ -717,6 +1216,21 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
             const processor = audioCtx.createScriptProcessor(4096, 1, 1);
             const silence = audioCtx.createGain();
             silence.gain.value = 0;
+            const bargeInVad = (0, vad_1.createVadDetector)();
+            // Real, live-reported bug this closes: firing triggerBargeIn() off a
+            // SINGLE ~85-100ms VAD frame meant one cough or door-slam frame that
+            // happened to pass the energy+ZCR gate cut the agent off, permanently
+            // (no server-side "was this real" recovery exists anymore — see
+            // vad.ts's own doc comment for why that was removed instead of kept).
+            // Real research into how production voice-agent platforms solve this
+            // (Pipecat, LiveKit Agents, Vapi, Deepgram's Voice Agent API — see
+            // DEVELOPMENT.md) converges on gating the LOCAL trigger on SUSTAINED
+            // speech across a minimum duration instead — Pipecat's own production
+            // spec cites 250ms, Vapi's stopSpeakingPlan defaults to 0.2s. This
+            // gate does exactly that, entirely client-side (no network round trip
+            // or STT-transcript timing involved, so it can't reintroduce the
+            // removed server-side race).
+            const bargeInGate = (0, vad_1.createBargeInGate)();
             processor.onaudioprocess = (e) => {
                 if (ws.readyState !== WebSocket.OPEN)
                     return;
@@ -725,31 +1239,77 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                 // Barge-in: while the agent is speaking a real conversational reply,
                 // still thinking about one, OR mid-tour, keep listening to the mic
                 // locally even though it isn't being sent yet, and cut the agent
-                // off the instant the user starts talking again instead of making
-                // them wait — including during a guided tour, which now cancels the
-                // rest of the walkthrough on interruption (see triggerBargeIn)
-                // instead of being talked-over-proof by design, the way a real
-                // person giving a tour stops when you have a question. The
-                // "rt-thinking" half matters just as much as "rt-speaking": an LLM
-                // turn can easily take a couple of seconds with nothing playing
-                // yet, and without this the mic was completely deaf during that
-                // whole window — found live as "not listening while speaking... no
-                // interrupting system", not just a missed nice-to-have.
+                // off once the user has been sustainedly talking again (bargeInGate,
+                // above) instead of making them wait — including during a guided
+                // tour, which now cancels the rest of the walkthrough on
+                // interruption (see triggerBargeIn) instead of being talked-over-
+                // proof by design, the way a real person giving a tour stops when
+                // you have a question. The "rt-thinking" half matters just as much
+                // as "rt-speaking": an LLM turn can easily take a couple of seconds
+                // with nothing playing yet, and without this the mic was completely
+                // deaf during that whole window — found live as "not listening
+                // while speaking... no interrupting system", not just a missed
+                // nice-to-have.
                 if (rtStateRef.current === "rt-speaking" || rtStateRef.current === "rt-thinking") {
-                    const rms = computeRms(e.inputBuffer.getChannelData(0));
-                    if (rms > BARGE_IN_RMS_THRESHOLD)
+                    const frame = bargeInVad.process(e.inputBuffer.getChannelData(0));
+                    const frameDurationMs = (e.inputBuffer.length / audioCtx.sampleRate) * 1000;
+                    if (bargeInGate.update(frame, frameDurationMs))
                         triggerBargeIn();
                     return;
                 }
+                bargeInGate.reset(); // not currently interruptible — don't let stale progress from a moment ago carry into the next speaking/thinking phase
                 if (rtStateRef.current !== "rt-listening")
                     return; // don't send our own mic while the agent is thinking/speaking
+                if (!micAudioSentSinceListeningRef.current) {
+                    micAudioSentSinceListeningRef.current = true;
+                    rtLog("mic audio actually being sent (send gate is open)");
+                }
                 const pcm = floatTo16BitPCM(downsampleTo16k(e.inputBuffer.getChannelData(0), audioCtx.sampleRate));
                 ws.send(pcm);
             };
             source.connect(processor);
             processor.connect(silence);
             silence.connect(audioCtx.destination);
+            // Real, live-reported bug this closes: "status says Listening but
+            // nothing gets picked up" — traced to browsers deliberately
+            // suspending an AudioContext that has no active OUTPUT (a real,
+            // documented power-saving policy, not backgrounded-tab-only). This
+            // capture context has no real output at all by design (silence's
+            // gain is 0), making it exactly the shape most likely to get
+            // silently suspended — and once suspended, onaudioprocess simply
+            // stops firing, so nothing inside it can detect or recover from its
+            // own silence. A periodic external health check is the only
+            // reliable way to catch this: resume the context if the browser
+            // suspended it, and — a real, separate failure mode — detect the
+            // mic's OWN MediaStreamTrack actually ending or going muted (device
+            // unplugged, OS-level permission revoked mid-call, another app
+            // taking exclusive access) and surface a real, honest error instead
+            // of silently going deaf with the UI still claiming to listen.
+            const micHealthCheck = setInterval(() => {
+                if (audioCtx.state !== "running") {
+                    rtLog("capture AudioContext was suspended — resuming", { state: audioCtx.state });
+                    void audioCtx.resume().catch((err) => rtLog("failed to resume capture AudioContext", { error: String(err) }));
+                }
+                const track = stream.getAudioTracks()[0];
+                if (track && (track.readyState === "ended" || track.muted)) {
+                    rtLog("mic track is no longer live — ending the call", { readyState: track.readyState, muted: track.muted });
+                    setAnswer("The microphone connection was lost — try starting the call again.");
+                    endRealtime();
+                }
+            }, 2000);
+            // The track's own "ended" event is the immediate signal (fires the
+            // instant the OS/browser actually kills the track) — the poll above
+            // is the safety net for anything that doesn't fire it reliably
+            // (muted-without-ended has no dedicated event in the spec).
+            const handleMicTrackEnded = () => {
+                rtLog("mic track ended unexpectedly — ending the call");
+                setAnswer("The microphone connection was lost — try starting the call again.");
+                endRealtime();
+            };
+            stream.getAudioTracks().forEach((t) => t.addEventListener("ended", handleMicTrackEnded));
             rtCleanupRef.current = () => {
+                clearInterval(micHealthCheck);
+                stream.getAudioTracks().forEach((t) => t.removeEventListener("ended", handleMicTrackEnded));
                 processor.disconnect();
                 source.disconnect();
                 stream.getTracks().forEach((t) => t.stop());
@@ -780,6 +1340,9 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                     rtTourAudioDoneRef.current = null;
                     return;
                 }
+                rtLog("resumed listening");
+                void audioCtx.resume().catch(() => { }); // don't wait up to 2s for the periodic health check if the browser already suspended capture
+                micAudioSentSinceListeningRef.current = false;
                 setRtStatus("rt-listening");
                 setCaption("");
                 void sendFreshContext(); // refresh before the user starts talking again, not after
@@ -794,10 +1357,28 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                 disarmThinkingWatchdog();
                 rtThinkingWatchdogRef.current = setTimeout(() => {
                     rtThinkingWatchdogRef.current = null;
-                    console.warn("[cairn] realtime turn timed out waiting on the server — resuming listening");
-                    rtAudioDoneArrivingRef.current = true;
-                    setRtStatus("rt-listening");
-                    setCaption("");
+                    rtLog("thinking watchdog fired — server took over 20s, resuming listening and abandoning that turn");
+                    // Real, live-found gap: this used to only reset LOCAL state,
+                    // never telling the server anything — so a turn that was simply
+                    // SLOW (not actually stuck; e.g. retrying a rate-limited call
+                    // across every configured key, which can genuinely take longer
+                    // than this 20s watchdog) kept running server-side, and its
+                    // reply arrived LATE, after the user had already moved on and
+                    // started a new turn locally — landing on whatever was now
+                    // showing instead of being recognized as stale. triggerBargeIn()
+                    // is exactly the fix: it sends the same real barge_in signal a
+                    // genuine interruption does, bumping the server's own generation
+                    // so that late reply — whenever it finally arrives — carries an
+                    // old generation number and gets correctly dropped by the
+                    // isStaleRtMessage check above instead of confusingly resuming.
+                    triggerBargeIn();
+                    setLoopWorking(false);
+                    // triggerBargeIn() clears the caption but never touched `answer`
+                    // — without this, a timed-out turn gave the user literally
+                    // nothing: no reply, no error, just a silent reset back to
+                    // "Listening…" that reads as "it heard me and did nothing." A
+                    // real, live-found gap, not just a console.warn nobody sees.
+                    setAnswer("That's taking longer than expected — try asking again.");
                 }, 20000);
             }
             function stopScheduledRtAudio() {
@@ -818,6 +1399,7 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
             // now-stale audio_chunk/speaking_end that was already in flight, so a
             // few straggling chunks can't sneak back in and resume playback.
             function triggerBargeIn() {
+                rtLog("barge-in triggered", { wasTouring: touringRef.current, discardedAudioChunks: rtScheduledSourcesRef.current.length });
                 disarmThinkingWatchdog();
                 stopScheduledRtAudio();
                 rtAudioDoneArrivingRef.current = true;
@@ -837,13 +1419,47 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                 if (ws.readyState === WebSocket.OPEN)
                     ws.send(JSON.stringify({ type: "barge_in" }));
                 setRtStatus("rt-listening");
-                setCaption("");
+                // Real, live-found bug this fix removes: this used to also clear
+                // the caption here (setCaption("")). That's correct-looking for a
+                // REAL, VAD-triggered barge-in (the user's about to say something
+                // new) — the very next "final" already does archiveCurrentExchange()
+                // then overwrites caption with the new utterance, so clearing it
+                // here was always redundant for that path. But this function is
+                // ALSO called by the thinking watchdog on a timeout, where there is
+                // no new utterance coming — clearing the caption there wiped out
+                // the very question that just timed out, an instant before
+                // setAnswer(the timeout message) ran, leaving the live pair as
+                // {caption: "", answer: "That's taking longer..."} — a reply
+                // visibly floating with no question above it, and nothing for
+                // archiveCurrentExchange() to pair it with on the next turn either
+                // (archiveText skips empty text). Simply never clearing it here is
+                // correct for both callers: the barge-in path already gets a fresh
+                // caption from the next "final", and the watchdog path now keeps
+                // the timed-out question correctly paired with its own answer.
             }
             ws.onopen = () => {
+                rtLog("connection open");
                 sendFreshContext();
                 setRtStatus("rt-listening");
                 rtStartingRef.current = false;
             };
+            // True for a verb/speaking_start/audio_chunk/speaking_end/
+            // turn_complete message that belongs to an EARLIER turn than the
+            // most recent "final" this client has seen — see
+            // rtLastFinalGenerationRef's own doc comment for the real race this
+            // closes. A message with no generation field at all (shouldn't
+            // happen against a server running this fix, but a mismatched client/
+            // server version pair during a rolling deploy could) is treated as
+            // current rather than dropped — additive/backward-compatible, same
+            // discipline every other wire-protocol addition in this codebase
+            // follows.
+            function isStaleRtMessage(msg) {
+                const stale = typeof msg.generation === "number" && msg.generation < rtLastFinalGenerationRef.current;
+                if (stale)
+                    rtLog("dropped stale message", { type: msg.type, messageGeneration: msg.generation, currentGeneration: rtLastFinalGenerationRef.current });
+                return stale;
+            }
+            let audioChunkCount = 0;
             ws.onmessage = (event) => {
                 if (typeof event.data !== "string")
                     return; // audio now arrives as base64 inside audio_chunk, not raw binary frames
@@ -852,14 +1468,35 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                     setCaption(msg.text);
                 }
                 else if (msg.type === "final") {
+                    rtLog("final transcript", { text: msg.text, generation: msg.generation });
+                    rtLastFinalGenerationRef.current = typeof msg.generation === "number" ? msg.generation : 0;
                     archiveCurrentExchange(); // the previous turn's pair is complete — move it into history before this one starts overwriting caption/answer
                     setCaption(msg.text);
+                    // Without this, `answer` still held the PREVIOUS turn's reply
+                    // text at the moment this new turn's own reply — if it ever
+                    // arrives — would overwrite it. Usually invisible (the previous
+                    // reply lands well before the next "final"), but a barge-in can
+                    // supersede an in-flight turn before its reply ever arrives (see
+                    // realtime-server.ts's onStep generation check) — with no reply
+                    // ever coming for THIS caption, the stale previous-turn answer
+                    // sat there and got archived alongside the wrong question on the
+                    // NEXT final, showing as a mismatched or duplicated-looking
+                    // reply. Found live: two turns' worth of the same fallback error
+                    // text ("Something went wrong on my end") appearing back to back
+                    // with only one visible question between them. Clearing to null
+                    // here means an abandoned turn now correctly archives with NO
+                    // reply bubble (archiveText skips empty text) instead of someone
+                    // else's.
+                    setAnswer(null);
                     setRtStatus("rt-thinking");
                     armThinkingWatchdog();
                 }
                 else if (msg.type === "verb") {
+                    if (isStaleRtMessage(msg))
+                        return; // belongs to a turn a later "final" already superseded
+                    rtLog("verb received", { verb: msg.verb?.verb, generation: msg.generation });
                     const parsedStep = (0, core_1.safeParseVerbResponse)(msg.verb);
-                    if (parsedStep && !core_1.TERMINAL_VERBS.has(parsedStep.verb)) {
+                    if (parsedStep && !(0, core_1.isTerminalVerb)(parsedStep)) {
                         // A continuing agent-loop step (click/fill/read/call_tool) —
                         // the turn isn't over: execute it for real and report the
                         // result back so the server can decide the next step, instead
@@ -870,7 +1507,39 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                         // — the server's loop stays quiet between steps on purpose,
                         // to keep it fast.
                         setAnswer(summarizeVerbForHistory(msg.verb));
-                        void (0, verb_executor_1.executeToolStep)(msg.verb, pathnameRef.current, liveMapRef.current).then((result) => {
+                        setLoopWorking(true);
+                        // Real, live-found bug: armThinkingWatchdog() only ever fired
+                        // once, on the turn's own "final" message, giving the WHOLE
+                        // multi-step turn one shared 20s budget — Executor + Planner +
+                        // Critic for step 1, then the same again for step 2, and so
+                        // on. Directly measured live: one single non-terminal step's
+                        // own Executor+Planner+Critic chain alone took ~14s (11.5s +
+                        // 1.5s + 1.1s) — a real, multi-step goal needing two or three
+                        // such steps blows straight through 20s even though each
+                        // individual step is proof of genuine progress, not a stall.
+                        // Re-arming here — once per continuing step, not once per
+                        // turn — gives every step its own fresh budget, so the
+                        // watchdog only ever fires on a step that's ACTUALLY stuck
+                        // (no verb/final/speaking_start arriving at all), matching
+                        // what its own fallback message ("taking longer than
+                        // expected") is supposed to mean.
+                        armThinkingWatchdog();
+                        // A FRESH scan, not the turn's starting liveMapRef snapshot —
+                        // real, live-found bug: a step in THIS SAME multi-step turn
+                        // (a "click New Agent" that opens a modal) can reveal DOM a
+                        // later step (a "fill" targeting the modal's own input) needs
+                        // to find, and liveMapRef is deliberately frozen once per
+                        // turn (see its own doc comment — that freeze exists to stop
+                        // a background rescan from shifting an id mid-flight during
+                        // ONE step's own round trip, not to survive across several
+                        // sequential steps that genuinely changed the page).
+                        // runTour() already does exactly this for its own steps, for
+                        // the identical reason. Without it, "click New Agent, then
+                        // type the name" reliably failed every time with "Could not
+                        // find that element on the page" — confirmed live, repeated
+                        // 5+ times in a row without ever recovering.
+                        const freshLiveMap = liveRegistryRef.current.getSnapshot().byId;
+                        void (0, verb_executor_1.executeToolStep)(msg.verb, pathnameRef.current, freshLiveMap, (route) => router.push(route), confirmToolCall).then((result) => {
                             if (ws.readyState === WebSocket.OPEN) {
                                 ws.send(JSON.stringify({ type: "tool_result", observation: result?.observation ?? "no result" }));
                             }
@@ -881,11 +1550,18 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                     handleVerb(msg.verb);
                 }
                 else if (msg.type === "speaking_start") {
+                    if (isStaleRtMessage(msg))
+                        return;
+                    rtLog("speaking start", { generation: msg.generation });
+                    audioChunkCount = 0;
                     disarmThinkingWatchdog();
                     rtAudioDoneArrivingRef.current = false;
                     setRtStatus("rt-speaking");
                 }
                 else if (msg.type === "audio_chunk") {
+                    if (isStaleRtMessage(msg))
+                        return; // the literal "two speakers" case — a chunk from an abandoned turn, already in flight when the barge-in landed
+                    audioChunkCount++;
                     const ctx = rtPlaybackCtxRef.current;
                     const gain = rtPlaybackGainRef.current;
                     if (!ctx || !gain)
@@ -918,6 +1594,9 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                     };
                 }
                 else if (msg.type === "speaking_end" || msg.type === "turn_complete") {
+                    if (isStaleRtMessage(msg))
+                        return; // a newer turn's own speaking_end/turn_complete will arrive and resume listening correctly on its own
+                    rtLog(msg.type, { audioChunks: audioChunkCount, generation: msg.generation });
                     // turn_complete covers a verb with nothing spoken (a plain
                     // highlight/navigate/do often has no text) — no audio_chunk ever
                     // arrives for it, so rtScheduledSourcesRef is already empty and
@@ -927,10 +1606,12 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                     maybeResumeListening();
                 }
                 else if (msg.type === "error") {
+                    rtLog("server error", { message: msg.message });
                     // Must actually unstick the turn, not just show the message —
                     // otherwise the mic never resumes and the session is stuck
                     // exactly the way a silently-dropped response used to leave it.
                     disarmThinkingWatchdog();
+                    setLoopWorking(false);
                     setAnswer(msg.message ?? "Something went wrong.");
                     if (touringRef.current) {
                         // A tour step's own speakStreamed() failed server-side (see
@@ -950,10 +1631,12 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                 }
             };
             ws.onerror = () => {
+                rtLog("connection error");
                 setAnswer("Couldn't connect to the realtime voice service.");
                 endRealtime();
             };
-            ws.onclose = () => {
+            ws.onclose = (closeEvent) => {
+                rtLog("connection closed", { code: closeEvent.code, reason: closeEvent.reason, wasIdle: rtStateRef.current === "idle" });
                 if (rtStateRef.current !== "idle")
                     endRealtime();
             };
@@ -962,15 +1645,18 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
             setAnswer("Couldn't access the microphone — check your browser's permission for this site.");
             setRtStatus("idle");
             rtStartingRef.current = false;
+            typedPlaybackSuspendedRef.current = false; // the call never actually started — don't leave typed replies permanently silenced
         }
     }
     function endRealtime() {
+        rtLog("ending realtime call", { statusAtEnd: rtStateRef.current });
         if (rtThinkingWatchdogRef.current) {
             clearTimeout(rtThinkingWatchdogRef.current);
             rtThinkingWatchdogRef.current = null;
         }
         rtStartingRef.current = false;
         stopTypedPlayback();
+        typedPlaybackSuspendedRef.current = false; // typed replies work normally again once no live call can race them
         rtSocketRef.current?.close();
         rtSocketRef.current = null;
         rtCleanupRef.current?.();
@@ -979,6 +1665,7 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
         setRtSpeakerMuted(false);
         setCaption("");
         setRtStatus("idle");
+        setLoopWorking(false); // defensive — a connection dropping mid-loop must never leave the "still working" indicator stuck on
         tourGenerationRef.current++; // cancel an in-progress tour rather than leaving it stuck waiting to resume rt-listening
         touringRef.current = false;
         setTourStep(null);
@@ -1013,7 +1700,17 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
         "rt-speaking": "Speaking…",
     };
     return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("style", { suppressHydrationWarning: true, dangerouslySetInnerHTML: { __html: COPILOT_STYLES } }), (0, jsx_runtime_1.jsx)("button", { className: status === "rt-speaking" ? "cairn-fab cairn-fab-speaking" : "cairn-fab", "aria-label": open ? `Close ${persona} help` : `Open ${persona} help`, onClick: () => setOpen((v) => !v), children: open ? (0, jsx_runtime_1.jsx)(lucide_react_1.X, { size: 22 }) : (0, jsx_runtime_1.jsx)(CairnMark, {}) }), open && ((0, jsx_runtime_1.jsxs)("div", { className: "cairn-panel", role: "dialog", "aria-label": `${persona} help panel`, ref: panelRef, children: [(transcript.length > 0 || userCaption || answer || busy) && ((0, jsx_runtime_1.jsxs)("div", { className: "cairn-stack", children: [transcript.length > 0 && ((0, jsx_runtime_1.jsxs)("button", { type: "button", className: "cairn-history-toggle", onClick: () => setHistoryExpanded((v) => !v), "aria-expanded": historyExpanded, children: [historyExpanded ? (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronUp, { size: 12 }) : (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronDown, { size: 12 }), historyExpanded ? "Hide earlier" : `${transcript.length} earlier`] })), historyExpanded &&
-                                transcript.map((entry) => ((0, jsx_runtime_1.jsx)("div", { className: entry.role === "user" ? "cairn-bubble cairn-bubble-user cairn-bubble-past" : "cairn-bubble cairn-bubble-agent cairn-bubble-past", children: entry.role === "agent" ? (0, jsx_runtime_1.jsx)("span", { className: "cairn-bubble-text", children: entry.text }) : entry.text }, entry.id))), userCaption && ((0, jsx_runtime_1.jsx)("div", { className: "cairn-bubble cairn-bubble-user", children: userCaption }, `u-${userCaption}`)), (answer || busy) && ((0, jsx_runtime_1.jsxs)("div", { className: "cairn-bubble cairn-bubble-agent", children: [tourChip && (0, jsx_runtime_1.jsx)("span", { className: "cairn-chip", children: tourChip }), answer ? ((0, jsx_runtime_1.jsx)("span", { className: "cairn-bubble-text", children: renderCaptionWords(answer) })) : ((0, jsx_runtime_1.jsxs)("span", { className: "cairn-thinking", "aria-label": "Thinking", children: [(0, jsx_runtime_1.jsx)("span", { className: "cairn-thinking-dot" }), (0, jsx_runtime_1.jsx)("span", { className: "cairn-thinking-dot" }), (0, jsx_runtime_1.jsx)("span", { className: "cairn-thinking-dot" })] }))] }, `a-${answer ?? status}`))] })), realtimeActive ? ((0, jsx_runtime_1.jsxs)("div", { className: "cairn-rt-bar", children: [(0, jsx_runtime_1.jsx)("span", { className: `cairn-rt-dot cairn-rt-dot-${status}` }), (0, jsx_runtime_1.jsx)("span", { className: "cairn-rt-label", children: statusLabel[status] }), (0, jsx_runtime_1.jsxs)("div", { className: "cairn-rt-controls", children: [(0, jsx_runtime_1.jsx)("button", { type: "button", className: status === "rt-speaking" ? "cairn-icon-btn cairn-icon-btn-speaking" : "cairn-icon-btn", "aria-label": rtMicMuted ? "Unmute microphone" : "Mute microphone", onClick: toggleRtMic, children: rtMicMuted ? (0, jsx_runtime_1.jsx)(lucide_react_1.MicOff, { size: 16 }) : (0, jsx_runtime_1.jsx)(lucide_react_1.Mic, { size: 16 }) }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: status === "rt-speaking" ? "cairn-icon-btn cairn-icon-btn-speaking" : "cairn-icon-btn", "aria-label": rtSpeakerMuted ? "Unmute speaker" : "Mute speaker", onClick: toggleRtSpeaker, children: rtSpeakerMuted ? (0, jsx_runtime_1.jsx)(lucide_react_1.VolumeX, { size: 16 }) : (0, jsx_runtime_1.jsx)(lucide_react_1.Volume2, { size: 16 }) }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "cairn-icon-btn cairn-icon-btn-end", "aria-label": "End conversation", onClick: endRealtime, children: (0, jsx_runtime_1.jsx)(lucide_react_1.PhoneOff, { size: 16 }) })] })] })) : ((0, jsx_runtime_1.jsx)("form", { onSubmit: (e) => {
+                                transcript.map((entry) => ((0, jsx_runtime_1.jsx)("div", { className: entry.role === "user" ? "cairn-bubble cairn-bubble-user cairn-bubble-past" : "cairn-bubble cairn-bubble-agent cairn-bubble-past", children: entry.role === "agent" ? (0, jsx_runtime_1.jsx)("span", { className: "cairn-bubble-text", children: entry.text }) : entry.text }, entry.id))), userCaption && ((0, jsx_runtime_1.jsx)("div", { className: "cairn-bubble cairn-bubble-user", children: userCaption }, `u-${userCaption}`)), (answer || busy) && ((0, jsx_runtime_1.jsxs)("div", { className: "cairn-bubble cairn-bubble-agent", children: [tourChip && (0, jsx_runtime_1.jsx)("span", { className: "cairn-chip", children: tourChip }), answer ? ((0, jsx_runtime_1.jsxs)("span", { className: "cairn-bubble-text", children: [renderCaptionWords(answer), loopWorking && (
+                                            // Real, live-reported gap this closes: this bubble
+                                            // used to go static the instant a continuing step's
+                                            // own progress text was shown ("Typing earbuds into
+                                            // the search box"), with nothing telling the user
+                                            // the agent was still actively working for however
+                                            // long the next real LLM call took. Appended inline
+                                            // (not swapped in place of the text, which the
+                                            // no-answer-yet case below does) so the progress
+                                            // text stays legible while still showing motion.
+                                            (0, jsx_runtime_1.jsxs)("span", { className: "cairn-thinking cairn-thinking-inline", "aria-label": "Still working", children: [(0, jsx_runtime_1.jsx)("span", { className: "cairn-thinking-dot" }), (0, jsx_runtime_1.jsx)("span", { className: "cairn-thinking-dot" }), (0, jsx_runtime_1.jsx)("span", { className: "cairn-thinking-dot" })] }))] })) : ((0, jsx_runtime_1.jsxs)("span", { className: "cairn-thinking", "aria-label": "Thinking", children: [(0, jsx_runtime_1.jsx)("span", { className: "cairn-thinking-dot" }), (0, jsx_runtime_1.jsx)("span", { className: "cairn-thinking-dot" }), (0, jsx_runtime_1.jsx)("span", { className: "cairn-thinking-dot" })] }))] }, `a-${answer ?? status}`))] })), realtimeActive ? ((0, jsx_runtime_1.jsxs)("div", { className: "cairn-rt-bar", children: [(0, jsx_runtime_1.jsx)("span", { className: `cairn-rt-dot cairn-rt-dot-${status}` }), (0, jsx_runtime_1.jsx)("span", { className: "cairn-rt-label", children: statusLabel[status] }), (0, jsx_runtime_1.jsxs)("div", { className: "cairn-rt-controls", children: [(0, jsx_runtime_1.jsx)("button", { type: "button", className: status === "rt-speaking" ? "cairn-icon-btn cairn-icon-btn-speaking" : "cairn-icon-btn", "aria-label": rtMicMuted ? "Unmute microphone" : "Mute microphone", onClick: toggleRtMic, children: rtMicMuted ? (0, jsx_runtime_1.jsx)(lucide_react_1.MicOff, { size: 16 }) : (0, jsx_runtime_1.jsx)(lucide_react_1.Mic, { size: 16 }) }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: status === "rt-speaking" ? "cairn-icon-btn cairn-icon-btn-speaking" : "cairn-icon-btn", "aria-label": rtSpeakerMuted ? "Unmute speaker" : "Mute speaker", onClick: toggleRtSpeaker, children: rtSpeakerMuted ? (0, jsx_runtime_1.jsx)(lucide_react_1.VolumeX, { size: 16 }) : (0, jsx_runtime_1.jsx)(lucide_react_1.Volume2, { size: 16 }) }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "cairn-icon-btn cairn-icon-btn-end", "aria-label": "End conversation", onClick: endRealtime, children: (0, jsx_runtime_1.jsx)(lucide_react_1.PhoneOff, { size: 16 }) })] })] })) : ((0, jsx_runtime_1.jsx)("form", { onSubmit: (e) => {
                             e.preventDefault();
                             const trimmed = question.trim();
                             if (trimmed)
@@ -1021,6 +1718,75 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                         }, children: (0, jsx_runtime_1.jsxs)("div", { className: "cairn-input-row", children: [(0, jsx_runtime_1.jsx)("input", { value: question, onChange: (e) => setQuestion(e.target.value), placeholder: "What do you need help with?", "aria-label": `Ask ${persona} a question`, disabled: recording || touring, autoFocus: true }), realtimeUrl && micSupported && ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "cairn-icon-btn", "aria-label": "Start realtime conversation", onClick: () => void startRealtime(), disabled: busy || recording, children: (0, jsx_runtime_1.jsx)(lucide_react_1.PhoneCall, { size: 16 }) })), transcribeEndpoint && micSupported && ((0, jsx_runtime_1.jsx)("button", { type: "button", className: recording ? "cairn-icon-btn cairn-icon-btn-recording" : "cairn-icon-btn", "aria-label": recording ? "Stop recording" : "Ask by voice", onClick: () => (recording ? stopRecording() : void startRecording()), disabled: touring, children: recording ? (0, jsx_runtime_1.jsx)(lucide_react_1.Square, { size: 16 }) : (0, jsx_runtime_1.jsx)(lucide_react_1.Mic, { size: 16 }) })), (0, jsx_runtime_1.jsx)("button", { type: "submit", className: "cairn-send", "aria-label": "Send", disabled: !question.trim() || busy || recording, children: asking ? (0, jsx_runtime_1.jsx)(lucide_react_1.Loader2, { size: 16, className: "cairn-spin" }) : (0, jsx_runtime_1.jsx)(lucide_react_1.Send, { size: 16 }) })] }) }))] }))] }));
 }
 const MAX_HISTORY_TURNS = 8; // 4 exchanges — matches the same cap the realtime relay uses server-side
+exports.CONVERSATION_STORAGE_KEY = "cairn:conversation:v1";
+/**
+ * Real, live-reported bug this closes: a host app's own mutation handler
+ * calling a real `window.location.reload()` — a common, entirely valid
+ * pattern; this SDK's own demo app uses it after several real actions,
+ * e.g. moving a kanban card — tears down the ENTIRE React tree, this
+ * widget included. Every bit of conversation state (the visible
+ * transcript, the current exchange, even whether the panel was open)
+ * reset to nothing, making a real, in-progress conversation look like it
+ * had simply ended the instant a host page happened to reload — even
+ * though nothing about the CONVERSATION itself was actually over.
+ * `sessionStorage`, not `localStorage`, is deliberate: it survives
+ * exactly a reload/navigation within the same tab — the real scope of
+ * "this conversation" — and clears itself once the tab/window actually
+ * closes, never lingering into an unrelated later visit the way
+ * `localStorage` would.
+ */
+function loadPersistedConversation() {
+    if (typeof window === "undefined")
+        return null;
+    try {
+        const raw = window.sessionStorage.getItem(exports.CONVERSATION_STORAGE_KEY);
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        const transcript = Array.isArray(parsed.transcript)
+            ? parsed.transcript.filter((t) => !!t && typeof t === "object" && typeof t.id === "number" && typeof t.text === "string" && (t.role === "user" || t.role === "agent"))
+            : [];
+        return {
+            transcript,
+            lastQuestion: typeof parsed.lastQuestion === "string" ? parsed.lastQuestion : null,
+            answer: typeof parsed.answer === "string" ? parsed.answer : null,
+            open: Boolean(parsed.open),
+        };
+    }
+    catch {
+        return null; // private browsing, quota, or a genuinely corrupt value — never crash the widget over this
+    }
+}
+function savePersistedConversation(data) {
+    if (typeof window === "undefined")
+        return;
+    try {
+        window.sessionStorage.setItem(exports.CONVERSATION_STORAGE_KEY, JSON.stringify(data));
+    }
+    catch {
+        // Storage unavailable/full — the conversation just won't survive a reload this time, never worth crashing the widget over.
+    }
+}
+/**
+ * Rebuilds a real seed for `historyRef` (what gets sent to the model on
+ * the NEXT typed turn) from a restored transcript — deliberately derived
+ * from the same, already-persisted `transcript` rather than separately
+ * persisting `historyRef`'s own shape: one real source of truth for "what
+ * was actually said," not two that could quietly drift apart. Capped the
+ * same way every other history array in this file already is.
+ */
+function reconstructHistoryFromPersisted(persisted) {
+    if (!persisted)
+        return [];
+    const fromTranscript = persisted.transcript.map((t) => ({ role: t.role === "agent" ? "assistant" : "user", text: t.text }));
+    const live = [
+        ...(persisted.lastQuestion ? [{ role: "user", text: persisted.lastQuestion }] : []),
+        ...(persisted.answer ? [{ role: "assistant", text: persisted.answer }] : []),
+    ];
+    return [...fromTranscript, ...live].slice(-MAX_HISTORY_TURNS);
+}
 /** Best-effort text form of a raw (unvalidated) verb response for the
  * conversation-history log — not shown to the user, just fed back to the
  * model on later turns. Deliberately loose/defensive rather than a full
@@ -1051,6 +1817,12 @@ function summarizeVerbForHistory(raw) {
             return `(read ${String(v.target)})`;
         case "call_tool":
             return `(called ${String(v.name)})`;
+        case "drag":
+            return `(dragged ${String(v.target)} to ${String(v.to)})`;
+        case "select":
+            return `(selected "${String(v.value)}" in ${String(v.target)})`;
+        case "key":
+            return `(pressed ${String(v.key)}${v.target ? ` on ${String(v.target)}` : ""})`;
         case "batch":
             return Array.isArray(v.actions) ? `(${v.actions.length} steps: ${v.actions.map((a) => a.verb).join(", ")})` : "(batch)";
         default:
@@ -1070,25 +1842,32 @@ function renderCaptionWords(text) {
     const words = text.split(" ");
     return words.map((word, i) => ((0, jsx_runtime_1.jsxs)("span", { className: "cairn-word", style: { animationDelay: `${Math.min(i * 55, 2800)}ms` }, children: [word, i < words.length - 1 ? " " : ""] }, i)));
 }
+// "Waybalance" — three real, irregular stones (an ellipse plus a smaller
+// bump, not a rectangle), stacked slightly off-center the way a hiker
+// actually balances a trail cairn, instead of the perfectly centered flat
+// bars this replaced. Same mark as docs/images/logo.svg and site/index.html's
+// nav badge, just currentColor here so it inherits the button's own color.
 function CairnMark() {
-    return ((0, jsx_runtime_1.jsxs)("svg", { width: "20", height: "20", viewBox: "0 0 20 20", fill: "none", "aria-hidden": "true", children: [(0, jsx_runtime_1.jsx)("rect", { x: "7", y: "12.5", width: "6", height: "2.6", rx: "0.5", fill: "currentColor" }), (0, jsx_runtime_1.jsx)("rect", { x: "4.5", y: "8.5", width: "11", height: "2.6", rx: "0.5", fill: "currentColor", opacity: "0.75" }), (0, jsx_runtime_1.jsx)("rect", { x: "8.2", y: "4.5", width: "3.6", height: "2.6", rx: "0.5", fill: "currentColor", opacity: "0.5" })] }));
+    return ((0, jsx_runtime_1.jsxs)("svg", { width: "20", height: "20", viewBox: "0 0 20 20", fill: "none", "aria-hidden": "true", children: [(0, jsx_runtime_1.jsx)("ellipse", { cx: "10", cy: "14.6", rx: "6.1", ry: "2.3", fill: "currentColor" }), (0, jsx_runtime_1.jsx)("ellipse", { cx: "6.3", cy: "14.1", rx: "2.5", ry: "1.6", fill: "currentColor" }), (0, jsx_runtime_1.jsx)("ellipse", { cx: "9.1", cy: "10.4", rx: "4.3", ry: "2", fill: "currentColor", opacity: "0.82" }), (0, jsx_runtime_1.jsx)("ellipse", { cx: "6.2", cy: "10", rx: "1.7", ry: "1.2", fill: "currentColor", opacity: "0.82" }), (0, jsx_runtime_1.jsx)("ellipse", { cx: "11.7", cy: "6.4", rx: "2.6", ry: "1.6", fill: "currentColor", opacity: "0.6" })] }));
+}
+// Real-time lifecycle logging — every message received, every decision made
+// about it (played, spoken, dropped, and why), every state transition. Added
+// specifically so a live session's actual behavior is visible in the browser
+// console instead of only inferable from symptoms after the fact — every bug
+// found and fixed in this file today was diagnosed from screenshots and
+// terminal output because nothing like this existed before. `[cairn rt]` is
+// the tag to filter on. Deliberately excludes per-audio_chunk noise (dozens
+// of chunks per turn would flood the console) — chunk activity shows up as
+// a one-line count at speaking_end/turn_complete instead.
+function rtLog(event, details) {
+    if (details)
+        console.log("[cairn rt]", event, details);
+    else
+        console.log("[cairn rt]", event);
 }
 // ---------------------------------------------------------------------------
 // Audio helpers (real-time PCM16 capture — standard Web Audio API patterns)
 // ---------------------------------------------------------------------------
-// Heuristic energy gate for barge-in: real speech into a laptop/phone mic
-// typically sits well above this; normal room noise and the mic's own
-// noise floor typically sit below it. Not calibrated against real hardware
-// in this environment (no live mic here) — reasonable starting point, may
-// need tuning against a real device if it proves too trigger-happy or too
-// insensitive in practice.
-const BARGE_IN_RMS_THRESHOLD = 0.02;
-function computeRms(channelData) {
-    let sumSquares = 0;
-    for (let i = 0; i < channelData.length; i++)
-        sumSquares += channelData[i] * channelData[i];
-    return Math.sqrt(sumSquares / channelData.length);
-}
 function downsampleTo16k(input, inputSampleRate) {
     const targetRate = 16000;
     if (inputSampleRate === targetRate)
@@ -1130,9 +1909,13 @@ const COPILOT_STYLES = `
   0%, 100% { box-shadow: 0 0 0 0 rgba(16, 185, 129, 0.4); }
   70% { box-shadow: 0 0 0 10px rgba(16, 185, 129, 0); }
 }
-@keyframes cairn-pulse-indigo {
-  0%, 100% { box-shadow: 0 0 0 0 rgba(99, 102, 241, 0.4); }
-  70% { box-shadow: 0 0 0 10px rgba(99, 102, 241, 0); }
+@keyframes cairn-pulse-ember {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(224, 122, 63, 0.4); }
+  70% { box-shadow: 0 0 0 10px rgba(224, 122, 63, 0); }
+}
+@keyframes cairn-cursor-arrive {
+  0% { box-shadow: 0 0 0 0 rgba(224, 122, 63, 0.55); }
+  100% { box-shadow: 0 0 0 9px rgba(224, 122, 63, 0); }
 }
 @keyframes cairn-spin {
   from { transform: rotate(0deg); }
@@ -1148,7 +1931,7 @@ const COPILOT_STYLES = `
 }
 @keyframes cairn-word-sweep {
   0% { opacity: 0.35; text-shadow: none; }
-  35% { opacity: 1; color: #4f46e5; text-shadow: 0 0 10px rgba(99, 102, 241, 0.45); }
+  35% { opacity: 1; color: #E07A3F; text-shadow: 0 0 10px rgba(224, 122, 63, 0.45); }
   100% { opacity: 1; color: inherit; text-shadow: none; }
 }
 @keyframes cairn-thinking-bounce {
@@ -1156,16 +1939,19 @@ const COPILOT_STYLES = `
   40% { opacity: 0.9; transform: translateY(-3px); }
 }
 .cairn-glow {
-  animation: cairn-pulse-indigo 1.1s ease-out 2;
-  outline: 2px solid #6366f1;
+  animation: cairn-pulse-ember 1.1s ease-out 2;
+  outline: 2px solid #E07A3F;
   outline-offset: 3px;
   border-radius: 8px;
 }
+.cairn-cursor-hover {
+  animation: cairn-cursor-arrive 0.3s ease-out;
+}
 .cairn-spin {
   animation: cairn-spin 0.8s linear infinite;
 }
 @media (prefers-reduced-motion: reduce) {
-  .cairn-fab, .cairn-panel, .cairn-bubble, .cairn-word, .cairn-thinking-dot {
+  .cairn-fab, .cairn-panel, .cairn-bubble, .cairn-word, .cairn-thinking-dot, #cairn-cursor {
     animation: none !important;
     transition: none !important;
   }
@@ -1300,6 +2086,10 @@ const COPILOT_STYLES = `
   gap: 4px;
   padding: 2px 0;
 }
+.cairn-thinking-inline {
+  margin-left: 6px;
+  vertical-align: middle;
+}
 .cairn-thinking-dot {
   width: 5px;
   height: 5px;