@cairnvibe/sdk 0.2.13 → 0.3.0

package/src/index.tsx

@@ -16,12 +16,14 @@ import {
   VolumeX,
   X,
 } from "lucide-react";
-import { TERMINAL_VERBS, safeParseVerbResponse, type HistoryTurn as HistoryEntry, type TourStep } from "@cairnvibe/core";
+import { classifyUiPattern, deriveStructureSignals, isTerminalVerb, safeParseVerbResponse, type CriticVerdict, type HistoryTurn as HistoryEntry, type Plan, type ProgressLedger, type Task, type TourStep, type VerbResponse } from "@cairnvibe/core";
+import { driveAgentLoop, looksMultiStep } from "./agent-loop";
 import { collectVisible } from "./context-collector";
 import { findElement, highlightElement, logMiss, type MissContext } from "./element-ladder";
 import { createLiveElementRegistry } from "./runtime-scan";
 import { discoverWebMcpTools } from "./webmcp-client";
 import { executeToolStep, executeVerbResponse } from "./verb-executor";
+import { createBargeInGate, createVadDetector } from "./vad";
 
 export interface CopilotProps {
   /** Reserved for a future client-side manifest fetch. Not required — the server handler owns the manifest. */
@@ -42,6 +44,45 @@ export interface CopilotProps {
   transcribeEndpoint?: string;
   /** If set, the widget speaks each explain/highlight answer aloud (Deepgram TTS via `@cairnvibe/sdk/speak-server`). */
   speakEndpoint?: string;
+  /**
+   * Phase 5 step 4 — whatever opaque id the CUSTOMER's own app already
+   * has for this end user (their own login id, or any other stable
+   * string they choose) — this SDK invents no identity of its own, same
+   * discipline as the realtime relay's own "context" message scopeId.
+   * Sent on every typed-transport request when set; the server only ever
+   * seeds/records real cross-session memory when BOTH this and a
+   * `memory` store are configured (`createCopilotHandler`'s own
+   * `memory` option) — omitting this keeps every request exactly as
+   * memory-less as before this existed, regardless of server config.
+   */
+  scopeId?: string;
+  /**
+   * Architecture Pillar 4 — if set (alongside `criticEndpoint`), the typed/
+   * HTTP loop gets the same real Planner the realtime relay already has:
+   * a task breakdown for a compound goal, and a genuinely separate Critic
+   * pass over each continuing step's real result (packages/sdk/src/
+   * server.ts's `createPlanHandler`/`createCriticHandler`). Omitting
+   * either endpoint keeps the typed loop exactly as it was — click/fill/
+   * read/call_tool executed and folded into history, ended by a terminal
+   * verb or the iteration cap — with zero Planner/Critic overhead, same
+   * opt-in discipline as speakEndpoint/transcribeEndpoint.
+   */
+  planEndpoint?: string;
+  /** See `planEndpoint` — both must be set for the typed loop's Planner/Critic wiring to activate. */
+  criticEndpoint?: string;
+  /**
+   * Architecture Pillar 3 (Skill half) — if set (alongside `planEndpoint`/
+   * `criticEndpoint`), the typed loop saves whatever real, Critic-
+   * verified facts a turn collects (`packages/sdk/src/server.ts`'s
+   * `createSkillSaveHandler`) once the turn concludes — the same
+   * Formulator mechanism the realtime relay already has. Retrieval (a
+   * matching Skill's full instructions surfacing to the Planner) needs no
+   * separate client wiring — it's already part of what `planEndpoint`'s
+   * own server-side handler does once a `SkillStore` is configured there.
+   * Omitting this keeps the typed loop exactly as it was — no Skills are
+   * ever saved, zero overhead.
+   */
+  skillsSaveEndpoint?: string;
   /**
    * If set, shows a "start conversation" control that opens a live
    * WebSocket to a `@cairnvibe/sdk/realtime-server` relay (run via
@@ -63,6 +104,10 @@ export function Copilot({
   reportMissesEndpoint,
   transcribeEndpoint,
   speakEndpoint,
+  scopeId,
+  planEndpoint,
+  criticEndpoint,
+  skillsSaveEndpoint,
   realtimeUrl,
   persona = "Cairn",
 }: CopilotProps) {
@@ -79,6 +124,13 @@ export function Copilot({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [pathname]);
   const router = 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] = useState(false);
   // Collapsed by default so the panel only ever shows the current exchange
   // — the full archived transcript (built up over a long conversation)
@@ -87,6 +139,18 @@ export function Copilot({
   const [historyExpanded, setHistoryExpanded] = useState(false);
   const [question, setQuestion] = useState("");
   const [answer, setAnswer] = useState<string | null>(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] = useState(false);
   const [status, setStatus] = useState<Status>("idle");
   const [caption, setCaption] = useState("");
   // The user's own last question, shown as its own floating caption bubble
@@ -161,6 +225,18 @@ export function Copilot({
   const rtMicMutedRef = useRef(false);
   const rtSpeakerMutedRef = useRef(false);
   const rtStartingRef = 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 = 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
@@ -173,6 +249,37 @@ export function Copilot({
   const typedPlaybackGainRef = useRef<GainNode | null>(null);
   const typedNextPlayTimeRef = useRef(0);
   const typedScheduledSourcesRef = useRef<AudioBufferSourceNode[]>([]);
+  // 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 = 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 = 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
@@ -196,6 +303,36 @@ export function Copilot({
   // finished arriving, so the mic can't start sending while the agent is
   // still audibly speaking.
   const rtAudioDoneArrivingRef = 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 = 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.
+  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
@@ -205,6 +342,36 @@ export function Copilot({
     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.
+  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-");
@@ -227,6 +394,26 @@ export function Copilot({
     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 = useRef(false);
+  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.
   useEffect(() => {
@@ -300,10 +487,37 @@ export function Copilot({
   }
 
   function handleVerb(raw: unknown) {
+    setLoopWorking(false); // only ever called for a genuinely terminal verb — the turn is over
     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,
@@ -332,7 +546,16 @@ export function Copilot({
    */
   async function runTour(steps: TourStep[]) {
     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");
     // No archiveCurrentExchange() here: whatever triggered this tour (a typed
@@ -410,7 +633,29 @@ export function Copilot({
       if (tourGenerationRef.current !== myGeneration) return;
       setTourStep(null);
       setCaption("");
-      if (wasRealtimeListening && realtimeActive) setRtStatus("rt-listening");
+      // 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 {
       if (tourGenerationRef.current === myGeneration) touringRef.current = false;
     }
@@ -429,13 +674,109 @@ export function Copilot({
     try {
       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");
     }
   }
 
-  const MAX_LOOP_ITERATIONS = 6; // a hard cap, not a target — see runTypedAgentLoop
+  /**
+   * 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: { name: string; description: string }): Promise<boolean> {
+    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: string, version = 1): Promise<Plan> {
+    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 as Plan).tasks) && (data as Plan).tasks.length > 0) return data as Plan;
+    } 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: Task, goal: string, verb: VerbResponse, observation: string | null | undefined): Promise<CriticVerdict> {
+    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 as CriticVerdict).verdict === "string") return data as CriticVerdict;
+    } 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: string, learnedFacts: string[]): void {
+    if (!skillsSaveEndpoint || learnedFacts.length === 0) return;
+    const matches = classifyUiPattern(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.
+    });
+  }
 
   /**
    * Drives the agent loop over the stateless HTTP path: ask the server,
@@ -449,62 +790,201 @@ export function Copilot({
    * 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: string): Promise<void> {
-    let loopHistory = historyRef.current;
     const webMcpTools = await discoverWebMcpTools();
+    let lastRawResponse: unknown = 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: Promise<Plan> | null = null;
+    let plan: Plan | null = null;
+    let progress: ProgressLedger | null = null;
+    const STALL_THRESHOLD = 3; // same bounded budget realtime's own Critic wiring uses
+    const plannerEnabled = Boolean(planEndpoint && criticEndpoint);
+    if (plannerEnabled && 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: string[] = [];
+
+    const result = await 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: collectVisible(),
+            history: loopHistory,
+            liveElements: liveScan.elements,
+            webMcpTools,
+            scopeId,
+          }),
+        });
+        const data = await res.json().catch(() => null);
+        lastRawResponse = data;
+        return 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) => 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;
+            }
 
-    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: collectVisible(),
-          history: loopHistory,
-          liveElements: liveScan.elements,
-          webMcpTools,
-        }),
-      });
-      const data = await res.json().catch(() => null);
-      const parsed = safeParseVerbResponse(data);
-
-      if (!parsed || 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 } satisfies HistoryEntry,
-          { role: "assistant", text: summarizeVerbForHistory(data) } satisfies HistoryEntry,
-        ].slice(-MAX_HISTORY_TURNS);
-        return;
-      }
+            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,
+    });
 
-      // 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 executeToolStep(data, pathname, liveMapRef.current);
-      loopHistory = [
-        ...loopHistory,
-        {
-          role: "assistant",
-          text: `${summarizeVerbForHistory(data)}. Result: ${stepResult?.observation ?? "no result"}`,
-        } satisfies HistoryEntry,
+    // 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: unknown = 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");
+      } 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 } satisfies HistoryEntry,
+        { role: "assistant", text: summarizeVerbForHistory(raw) } satisfies HistoryEntry,
       ].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 } satisfies HistoryEntry,
-      { role: "assistant", text: "(gave up after too many steps)" } satisfies HistoryEntry,
+      { role: "assistant", text: gaveUpSummary } satisfies HistoryEntry,
     ].slice(-MAX_HISTORY_TURNS);
   }
 
@@ -521,8 +1001,12 @@ export function Copilot({
 
   /** 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 {
@@ -552,6 +1036,7 @@ export function Copilot({
    */
   function playPcmStream(stream: ReadableStream<Uint8Array>): Promise<void> {
     stopTypedPlayback();
+    const myGeneration = typedPlaybackGenerationRef.current;
     const { ctx, gain } = ensureTypedPlaybackGraph();
     void ctx.resume().catch(() => {});
 
@@ -592,7 +1077,14 @@ export function Copilot({
         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) continue;
             // PCM16 samples are 2 bytes each — a chunk boundary can split a
@@ -622,6 +1114,13 @@ export function Copilot({
         body: JSON.stringify({ text }),
       });
       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 {
       // Best-effort — never let speech playback break the widget.
@@ -640,6 +1139,13 @@ export function Copilot({
         body: JSON.stringify({ text }),
       });
       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 {
       // Best-effort — never let a synthesis failure hang the tour forever.
@@ -674,7 +1180,7 @@ export function Copilot({
       // closed connection mid-turn), don't let the tour hang on this step
       // forever with the mic never resuming — move on instead.
       setTimeout(() => {
-        if (!settled) console.warn("[cairn] tour step audio confirmation timed out — continuing");
+        if (!settled) rtLog("tour step audio confirmation timed out after 15s — continuing anyway");
         finish();
       }, 15000);
       ws.send(JSON.stringify({ type: "speak", text }));
@@ -742,7 +1248,24 @@ export function Copilot({
     // race past the `realtimeActive` check twice and open two sessions,
     // 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("");
@@ -777,6 +1300,21 @@ export function Copilot({
       const processor = audioCtx.createScriptProcessor(4096, 1, 1);
       const silence = audioCtx.createGain();
       silence.gain.value = 0;
+      const bargeInVad = 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 = createBargeInGate();
 
       processor.onaudioprocess = (e) => {
         if (ws.readyState !== WebSocket.OPEN) return;
@@ -785,23 +1323,30 @@ export function Copilot({
         // 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) triggerBargeIn();
+          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);
       };
@@ -809,7 +1354,48 @@ export function Copilot({
       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());
@@ -839,6 +1425,9 @@ export function Copilot({
           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
@@ -855,10 +1444,28 @@ export function Copilot({
         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);
       }
 
@@ -880,6 +1487,7 @@ export function Copilot({
       // 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;
@@ -898,28 +1506,83 @@ export function Copilot({
         }
         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: { generation?: unknown }): boolean {
+        const stale = typeof msg.generation === "number" && msg.generation < rtLastFinalGenerationRef.current;
+        if (stale) rtLog("dropped stale message", { type: (msg as { type?: unknown }).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
         const msg = JSON.parse(event.data);
         if (msg.type === "interim") {
           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 = safeParseVerbResponse(msg.verb);
-          if (parsedStep && !TERMINAL_VERBS.has(parsedStep.verb)) {
+          if (parsedStep && !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
@@ -930,7 +1593,39 @@ export function Copilot({
             // — the server's loop stays quiet between steps on purpose,
             // to keep it fast.
             setAnswer(summarizeVerbForHistory(msg.verb));
-            void 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 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" }));
               }
@@ -940,10 +1635,15 @@ export function Copilot({
           disarmThinkingWatchdog();
           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) return;
@@ -978,6 +1678,8 @@ export function Copilot({
             maybeResumeListening();
           };
         } 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
@@ -986,10 +1688,12 @@ export function Copilot({
           rtAudioDoneArrivingRef.current = true;
           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
@@ -1009,26 +1713,31 @@ export function Copilot({
       };
 
       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();
       };
     } catch {
       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?.();
@@ -1037,6 +1746,7 @@ export function Copilot({
     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);
@@ -1118,7 +1828,25 @@ export function Copilot({
                 <div className="cairn-bubble cairn-bubble-agent" key={`a-${answer ?? status}`}>
                   {tourChip && <span className="cairn-chip">{tourChip}</span>}
                   {answer ? (
-                    <span className="cairn-bubble-text">{renderCaptionWords(answer)}</span>
+                    <span className="cairn-bubble-text">
+                      {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.
+                        <span className="cairn-thinking cairn-thinking-inline" aria-label="Still working">
+                          <span className="cairn-thinking-dot" />
+                          <span className="cairn-thinking-dot" />
+                          <span className="cairn-thinking-dot" />
+                        </span>
+                      )}
+                    </span>
                   ) : (
                     <span className="cairn-thinking" aria-label="Thinking">
                       <span className="cairn-thinking-dot" />
@@ -1219,6 +1947,82 @@ export function Copilot({
 
 const MAX_HISTORY_TURNS = 8; // 4 exchanges — matches the same cap the realtime relay uses server-side
 
+export const CONVERSATION_STORAGE_KEY = "cairn:conversation:v1";
+
+export interface PersistedConversation {
+  transcript: { id: number; role: "user" | "agent"; text: string }[];
+  lastQuestion: string | null;
+  answer: string | null;
+  open: boolean;
+}
+
+/**
+ * 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.
+ */
+export function loadPersistedConversation(): PersistedConversation | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.sessionStorage.getItem(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: unknown): t is { id: number; role: "user" | "agent"; text: string } =>
+            !!t && typeof t === "object" && typeof (t as { id?: unknown }).id === "number" && typeof (t as { text?: unknown }).text === "string" && ((t as { role?: unknown }).role === "user" || (t as { role?: unknown }).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
+  }
+}
+
+export function savePersistedConversation(data: PersistedConversation): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.sessionStorage.setItem(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.
+ */
+export function reconstructHistoryFromPersisted(persisted: PersistedConversation | null): HistoryEntry[] {
+  if (!persisted) return [];
+  const fromTranscript: HistoryEntry[] = persisted.transcript.map((t) => ({ role: t.role === "agent" ? "assistant" : "user", text: t.text }));
+  const live: HistoryEntry[] = [
+    ...(persisted.lastQuestion ? [{ role: "user" as const, text: persisted.lastQuestion }] : []),
+    ...(persisted.answer ? [{ role: "assistant" as const, 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
@@ -1247,6 +2051,12 @@ function summarizeVerbForHistory(raw: unknown): string {
       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: { verb?: string }) => a.verb).join(", ")})` : "(batch)";
     default:
@@ -1273,34 +2083,41 @@ function renderCaptionWords(text: string) {
   ));
 }
 
+// "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 (
     <svg width="20" height="20" viewBox="0 0 20 20" fill="none" aria-hidden="true">
-      <rect x="7" y="12.5" width="6" height="2.6" rx="0.5" fill="currentColor" />
-      <rect x="4.5" y="8.5" width="11" height="2.6" rx="0.5" fill="currentColor" opacity="0.75" />
-      <rect x="8.2" y="4.5" width="3.6" height="2.6" rx="0.5" fill="currentColor" opacity="0.5" />
+      <ellipse cx="10" cy="14.6" rx="6.1" ry="2.3" fill="currentColor" />
+      <ellipse cx="6.3" cy="14.1" rx="2.5" ry="1.6" fill="currentColor" />
+      <ellipse cx="9.1" cy="10.4" rx="4.3" ry="2" fill="currentColor" opacity="0.82" />
+      <ellipse cx="6.2" cy="10" rx="1.7" ry="1.2" fill="currentColor" opacity="0.82" />
+      <ellipse cx="11.7" cy="6.4" rx="2.6" ry="1.6" fill="currentColor" opacity="0.6" />
     </svg>
   );
 }
 
+// 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: string, details?: Record<string, unknown>): void {
+  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: Float32Array): number {
-  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: Float32Array, inputSampleRate: number): Float32Array {
   const targetRate = 16000;
   if (inputSampleRate === targetRate) return input;
@@ -1513,6 +2330,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;