@olares/lares-core 0.15.31 → 0.15.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olares/lares-core",
-  "version": "0.15.31",
+  "version": "0.15.33",
   "description": "Lares 共享业务核心：Router、workspace、文件/媒体、Olares 身份（无 UI、无平台壳）",
   "type": "module",
   "repository": {

package/voice/browser-capture.js

@@ -49,7 +49,22 @@ export function prepareBrowserCapture({ media, onTrace = () => {}, now = Date.no
   })();
   // Permission may fail while other initialization is still pending.
   void ready.catch(() => {});
+  const live = async () => {
+    let next;
+    try { next = await ready; }
+    catch (err) {
+      if (err instanceof Error && err.message.startsWith("voice_")) throw err;
+      throw new Error(micFailure(err));
+    }
+    if (consumed || cancelled || !next) throw new Error("voice_cancelled");
+    if (next.getTracks().every((track) => track.readyState === "ended")) throw new Error("voice_device_lost");
+    return next;
+  };
   return {
+    /** Resolves once the microphone is open. Does not take the stream. */
+    opened: live,
+    /** Another take of the same voice session. Does not open a second microphone. */
+    borrow: live,
     recording() {
       try { onTrace("ready", { durationMs: now() - started }); } catch { /* Telemetry is optional. */ }
     },
@@ -79,6 +94,7 @@ export function createVoiceCapture({
   now = Date.now,
   media,
   preparation,
+  retainStream = false,
 }) {
   const mediaDevices = media?.mediaDevices ?? globalThis.navigator?.mediaDevices;
   const Recorder = media?.MediaRecorder ?? globalThis.MediaRecorder;
@@ -122,7 +138,9 @@ export function createVoiceCapture({
   const release = () => {
     detector?.stop?.();
     detector = null;
-    stream?.getTracks().forEach((track) => track.stop());
+    // A session microphone stays open for the next hold. Only a take that
+    // opened its own stream stops the tracks when the take ends.
+    if (!retainStream) stream?.getTracks().forEach((track) => track.stop());
     stream = null;
     recorder = null;
   };
@@ -241,7 +259,7 @@ export function createVoiceCapture({
     async start() {
       if (dead || phase === "preparing" || phase === "recording" || phase === "transcribing") return;
       if (typeof Recorder === "undefined" || !mediaDevices?.getUserMedia) {
-        preparation?.cancel();
+        if (!retainStream) preparation?.cancel();
         fail("voice_unsupported");
         return;
       }
@@ -253,9 +271,9 @@ export function createVoiceCapture({
       emit("preparing", { elapsed: 0, error: "" });
       let next;
       try {
-        next = await (preparation ? preparation.consume() : openDeviceMic(mediaDevices));
+        next = await (retainStream ? preparation.borrow() : preparation ? preparation.consume() : openDeviceMic(mediaDevices));
       } catch (err) {
-        preparation?.cancel();
+        if (!retainStream) preparation?.cancel();
         const code = micFailure(err);
         trace("mic-fail", { code, name: err?.name || "" });
         if (!dead) fail(code);
@@ -351,7 +369,7 @@ export function createVoiceCapture({
       }
     },
     dispose() {
-      preparation?.cancel();
+      if (!retainStream) preparation?.cancel();
       inputAbort?.abort();
       dead = true;
       cancel = true;

package/voice/device-input.js

@@ -32,8 +32,8 @@ export function createDeviceInput({ transcribe, onPhase = () => {}, endpoint = d
         let ready = false;
         settle = resolve;
         const done = (text) => { clearTimeout(timer); signal?.removeEventListener("abort", cancel); settle = null; resolve(text); };
-        const prepared = preparation; preparation = null;
-        recorder = createVoiceCapture({ media, streamInput, preparation: prepared, transcribe, submit: done, onStream: (stream) => {
+        const retainStream = continuous && typeof preparation?.borrow === "function";
+        recorder = createVoiceCapture({ media, streamInput, preparation, retainStream, transcribe, submit: done, onStream: (stream) => {
           for (const track of stream.getTracks()) track.addEventListener?.("ended", () => { settle = null; cancel(); reject(new Error("voice_device_lost")); }, { once: true });
           if (!automatic) return createInputMeter(stream, onLevel);
           return endpoint(stream, (heard = true) => { if (heard) recorder?.stop(); else { cancel(); done(""); } }, onSpeech, onLevel, { silenceMs: endpointSilenceMs, interruptionMs: echoTested ? 500 : 0 });

package/voice/lares-realtime-gateway.js

@@ -3,6 +3,7 @@ import { WebSocketServer } from "ws";
 import { validateConfigPatch } from "./config.js";
 import { createSpeechEndpoint, frameRms } from "./endpoint.js";
 import { pcmSamples } from "./realtime-audio.js";
+import { createPlayoutClock, PLAYOUT_LEAD_MS, SOCKET_FUSE_BYTES } from "./playout-clock.js";
 import { speechSegments } from "./script.js";
 import { bindRouterSession } from "../router/session-alias.js";
 
@@ -16,13 +17,6 @@ const SPEECH_RMS = 0.004;
 // and a suspected interruption that never resolves stops the reply.
 const BARGE_IN_MS = 500;
 const BARGE_IN_LIMIT_MS = 10_000;
-// How far ahead of the client's actual playout the Host may send. The client's
-// AudioWorklet keeps a bounded queue; sending a whole answer at network speed
-// overflowed it and dropped audio.
-const PLAY_AHEAD_MS = 2_000;
-// A temporarily interrupted AudioContext (device switch, lock screen) must not
-// end a reply; only a client that stays silent this long is treated as stuck.
-const PLAYOUT_STALL_MS = 30_000;
 const TICKET_MS = 30_000;
 // Usage lives in the child ASR/LLM/TTS requests; the OpenAI shape stays parseable (Router ADR-83).
 const ZERO_USAGE = Object.freeze({ total_tokens: 0, input_tokens: 0, output_tokens: 0, input_token_details: { text_tokens: 0, audio_tokens: 0, cached_tokens: 0 }, output_token_details: { text_tokens: 0, audio_tokens: 0 } });
@@ -44,6 +38,9 @@ const ticketOf = (req) => String(req.headers["sec-websocket-protocol"] || "").sp
 const CJK_END = /[　-〿㐀-鿿＀-￯]$/;
 const CJK_START = /^[　-〿㐀-鿿＀-￯]/;
 const separator = (before, after) => !before || CJK_END.test(before) || CJK_START.test(after) ? "" : " ";
+// `done === false` is a live partial. A finished utterance sets done, and a caller
+// that never reports it (tests, a one-shot reply) is spoken as-is.
+const speakableUtterance = (utterance) => Boolean(utterance?.text) && utterance.done !== false && !utterance.silent;
 /** Spoken segments are cleaned clauses; rejoin them without inventing spaces inside CJK text. */
 export function joinSpoken(parts) {
   return parts.reduce((text, part) => `${text}${separator(text, part)}${part}`, "");
@@ -161,29 +158,23 @@ export function createLaresRealtimeGateway({ service, config, transcribe, synthe
         return hostOutput;
       }
       if (acknowledges) { awaitingPlayback = true; watchAck(); }
-      // A long reply is several seconds of PCM. Dumping it in one burst fills the
-      // socket and used to close the call, which cut the readout off and made the
-      // client's next progress tick throw voice_disconnected. Wait for the buffer
-      // the way the speech stream does; a stuck client fails this reply only.
-      const OUTPUT_BUFFER = 128 * 1024;
+      // A client that announces playback acknowledgement used to stop after two
+      // seconds unless later ticks kept arriving. Those ticks are observations.
+      // The reply keeps moving with the clock; the socket fuse is only for a
+      // client that has stopped reading.
+      if (!current.clock) current.clock = createPlayoutClock({ leadMs: PLAYOUT_LEAD_MS });
+      const clock = current.clock;
       let sentAt = Date.now();
-      let lastPlayed = played.get(current.itemId) ?? 0;
-      let playedAt = Date.now();
       for (let offset = 0; offset < audio.length; offset += CHUNK_BYTES) {
-        while (client.bufferedAmount > OUTPUT_BUFFER) {
+        clock.start();
+        clock.heard(played.get(current.itemId) ?? 0);
+        while ((acknowledges && clock.blocked(current.outputMs)) || client.bufferedAmount > SOCKET_FUSE_BYTES) {
           if (current.abort.signal.aborted || current.done || closed || client.readyState !== 1) return;
-          if (Date.now() - sentAt > 10_000) throw new Error("voice_audio_backpressure");
-          await new Promise((resolve) => setTimeout(resolve, 20));
-        }
-        // Playout credit: never get more than two seconds ahead of what the
-        // client has actually rendered. Progress advances in real time, so a
-        // long answer waits here instead of filling the worklet queue.
-        while (acknowledges && current.outputMs - lastPlayed > PLAY_AHEAD_MS) {
-          if (current.abort.signal.aborted || current.done || closed || client.readyState !== 1) return;
-          const heard = played.get(current.itemId) ?? 0;
-          if (heard > lastPlayed) { lastPlayed = heard; playedAt = Date.now(); }
-          if (Date.now() - playedAt > PLAYOUT_STALL_MS) throw new Error("voice_audio_backpressure");
-          await new Promise((resolve) => setTimeout(resolve, 20));
+          clock.heard(played.get(current.itemId) ?? 0);
+          if (client.bufferedAmount > SOCKET_FUSE_BYTES && Date.now() - sentAt > 10_000) throw new Error("voice_audio_backpressure");
+          if (!((acknowledges && clock.blocked(current.outputMs)) || client.bufferedAmount > SOCKET_FUSE_BYTES)) break;
+          const delay = client.bufferedAmount > SOCKET_FUSE_BYTES ? 20 : Math.max(20, Math.min(200, clock.wait(current.outputMs)));
+          await new Promise((resolve) => setTimeout(resolve, delay));
         }
         if (current.abort.signal.aborted || current.done || closed || client.readyState !== 1) return;
         const chunk = audio.subarray(offset, offset + CHUNK_BYTES);
@@ -213,6 +204,8 @@ export function createLaresRealtimeGateway({ service, config, transcribe, synthe
           if (current.suspended && await current.suspended.wait === "stop") return;
           if (current.abort.signal.aborted || closed) return;
           send({ type: "response.output_audio_transcript.delta", ...part, delta: `${separator(current.sentences.at(-1)?.text, sentence)}${sentence}` });
+          // A slice has to reach the player before synthesize continues, so a
+          // caller that pauses after the first slice can still be interrupted.
           const audio = await synthesize(sentence, scope, (pcm) => playOut(current, pcm));
           if (current.abort.signal.aborted || closed) return;
           if (audio) await playOut(current, audio);
@@ -260,7 +253,9 @@ export function createLaresRealtimeGateway({ service, config, transcribe, synthe
         if (!turn.accepted) await service.withdraw?.(scope, requestId).catch(() => {});
         return;
       }
-      if (state.utterance?.text && !state.utterance.silent) { lastReply = state.utterance.key; speak(state.utterance.text, "turn", state.utterance.key, input); }
+      // A snapshot taken while the answer is still streaming only has the first
+      // sentence. Speaking that and remembering the key drops the rest.
+      if (speakableUtterance(state.utterance)) { lastReply = state.utterance.key; speak(state.utterance.text, "turn", state.utterance.key, input); }
     };
     const userItem = (id, content) => send({ type: "conversation.item.done", item: { id, object: "realtime.item", type: "message", role: "user", status: "completed", content: [content] } });
     const commit = async () => {
@@ -512,7 +507,7 @@ export function createLaresRealtimeGateway({ service, config, transcribe, synthe
         observeTasks();
         if (busy || speaking || awaitingPlayback || response) return;
         const state = service.state(scope);
-        if (!state.utterance?.text || state.utterance.key === lastReply || state.utterance.silent) return;
+        if (!speakableUtterance(state.utterance) || state.utterance.key === lastReply) return;
         lastReply = state.utterance.key;
         speak(state.utterance.text, String(state.utterance.key).startsWith("task:") ? "task" : "turn", state.utterance.key, 0);
       } catch { close(); }

package/voice/panel.js

@@ -168,9 +168,25 @@ export function createVoicePanel({ create, complete, loadConfig = async () => ({
       if (state.busy) return Promise.resolve();
       cancelPreparation();
       const snapshot = configSnapshot ? structuredClone(configSnapshot) : null;
-      if (mode === "single" && snapshot && !(sessionId === state.sessionId ? state.raw : drafts.get(sessionId)?.raw)) inputPreparation = prepareInput(snapshot);
-      const token = ++intent; emit({ visible: true });
+      const held = sessionId === state.sessionId ? state.raw : drafts.get(sessionId)?.raw;
+      if (!(mode === "single" && held)) inputPreparation = prepareInput(snapshot || {});
+      const mic = inputPreparation;
+      const token = ++intent;
+      // The composer stays on text until the microphone is actually open.
+      if (!mic) emit({ visible: true });
       return enqueue(async () => {
+        if (mic) {
+          try { await mic.opened(); }
+          catch (error) {
+            if (inputPreparation === mic) cancelPreparation();
+            if (token !== intent) return;
+            const code = error.code || error.message || "voice_failed";
+            if (code !== "voice_cancelled") emit({ visible: false, error: code });
+            return;
+          }
+          if (token !== intent) return;
+          emit({ visible: true, error: null });
+        }
         if (sessionId !== state.sessionId || mode !== state.mode) {
           try { await pause(); } finally { await end(); save(); const held = drafts.get(sessionId); config = held?.config || null; emit({ sessionId, mode, raw: mode === "single" ? held?.raw || "" : "", draft: mode === "single" ? held?.draft || "" : "", edited: mode === "single" && (held?.edited || false), preset: held?.preset || "raw", stage: mode === "single" && held?.raw ? "preview" : "idle" }); }
         }
@@ -188,7 +204,7 @@ export function createVoicePanel({ create, complete, loadConfig = async () => ({
       return enqueue(async () => { try { await pause(); } finally { await end(); save(); const held = drafts.get(sessionId); config = held?.config || null; emit({ sessionId, raw: held?.raw || "", draft: held?.draft || "", edited: held?.edited || false, preset: held?.preset || "raw", stage: held?.raw ? "preview" : "idle" }); } });
     },
     close() { intent++; cancelPreparation(); cancelProcessing(); emit({ visible: false, holding: false, cancelArmed: false }); if (state.mode === "continuous") void call?.controller.cancelRecording(); return enqueue(pause); },
-    pause() { intent++; cancelPreparation(); cancelProcessing(); emit({ holding: false, cancelArmed: false }); if (state.mode === "continuous") void call?.controller.cancelRecording(); return enqueue(pause); },
+    pause() { intent++; if (!state.inputActive) cancelPreparation(); cancelProcessing(); emit({ holding: false, cancelArmed: false }); if (state.mode === "continuous") void call?.controller.cancelRecording(); return enqueue(pause); },
     start() { armOutput(); const token = ++intent; return enqueue(() => prepare(token)); },
     openReadout() {
       if (state.mode !== "continuous") return Promise.resolve();
@@ -219,6 +235,17 @@ export function createVoicePanel({ create, complete, loadConfig = async () => ({
       if (state.busy || state.holding || state.snapshot?.capture === "transcribing") return Promise.resolve();
       const token = ++intent; emit({ holding: true, cancelArmed: false });
       return enqueue(async () => {
+        if (inputPreparation?.borrow) {
+          try { await inputPreparation.borrow(); }
+          catch (error) {
+            cancelPreparation();
+            if (token !== intent) return;
+            const code = error.code || error.message || "voice_failed";
+            if (code !== "voice_cancelled") emit({ visible: false, holding: false, cancelArmed: false, error: code });
+            else emit({ visible: false, holding: false, cancelArmed: false });
+            return;
+          }
+        }
         await prepare(token);
         if (token !== intent || !state.holding || !state.visible) return;
         await call?.controller.stopPlayback();

package/voice/playout-clock.js

@@ -0,0 +1,53 @@
+/**
+ * How far ahead of playout a reply may be sent, and the socket buffer that
+ * means the client has stopped reading. Both gates share this so a dropped
+ * progress tick cannot freeze one path while the other keeps going.
+ *
+ * The client's queue holds about four seconds. This lead stays inside that
+ * queue: a chunk past the lead is still under the cap.
+ */
+export const PLAYOUT_LEAD_MS = 2_000;
+export const SOCKET_FUSE_BYTES = 1024 * 1024;
+
+/**
+ * Credit for one reply. The playhead moves at 1x and stops when it catches
+ * the audio already handed to the client. A gap while the next sentence is
+ * synthesized does not pre-pay a burst, and a missing progress tick does not
+ * hold the rest: time keeps the playhead moving up to what was sent. Pause
+ * freezes it.
+ */
+export function createPlayoutClock({ leadMs = PLAYOUT_LEAD_MS, now = Date.now } = {}) {
+  let heard = 0, heldAt = 0, playhead = 0, markedAt = 0, sent = 0;
+  const stamp = () => heldAt || now();
+  const advance = (sentMs) => {
+    if (Number.isFinite(sentMs) && sentMs > sent) sent = sentMs;
+    const t = stamp();
+    if (!markedAt) { markedAt = t; return; }
+    playhead = Math.min(sent, playhead + Math.max(0, t - markedAt));
+    markedAt = t;
+  };
+  return {
+    heard(ms) { if (Number.isFinite(ms) && ms > heard) heard = ms; },
+    pause() {
+      if (heldAt) return;
+      advance(sent);
+      heldAt = now();
+    },
+    resume() {
+      if (!heldAt) return;
+      heldAt = 0;
+      markedAt = now();
+    },
+    get paused() { return heldAt !== 0; },
+    start() { if (!markedAt) markedAt = now(); },
+    credit(sentMs) {
+      advance(sentMs);
+      return Math.max(heard, playhead);
+    },
+    blocked(sentMs) { return sentMs - this.credit(sentMs) > leadMs; },
+    wait(sentMs) {
+      const delay = sentMs - leadMs - this.credit(sentMs);
+      return delay > 0 ? delay : 0;
+    },
+  };
+}

package/voice/presentation.js

@@ -39,9 +39,10 @@ export function voiceCallFailure(view) {
 }
 
 /**
- * A voice call that is still playing keeps one strip at the composer until it
- * ends: status plus the control that stops it. The hold button is not that
- * strip. A chat readout stays on the assistant row that is being read.
+ * A voice call that is still playing keeps one strip until it ends: status
+ * plus the control that stops it. The hold button is not that strip. Clients
+ * render it under the assistant reply that owns playback. A chat readout stays
+ * on that same reply and is not this strip.
  */
 export function voicePlaybackChrome(view) {
   const playback = view?.snapshot?.playback;

package/voice/speech.js

@@ -134,19 +134,24 @@ export function matchSpeechEvent(event) {
 export function createReplySpeaker() {
   let armed = false;
   let skipKey = null;
+  // The answer that was already on screen when a turn opened is history. A new
+  // turn can deliver its first text in the same snapshot that reports the turn,
+  // and that text must still be read: the old code skipped it by its own key.
+  let lastKey = null;
   return {
     /** @returns {Utterance | null} the utterance to follow now, or null */
     observe({ sessionChanged, wasRunning, running, utterance }) {
       if (sessionChanged) {
         armed = Boolean(running);
-        skipKey = utterance?.key ?? null;
+        skipKey = lastKey = utterance?.key ?? null;
         return null;
       }
       if (!wasRunning && running) {
         armed = true;
-        skipKey = utterance?.key ?? null;
+        skipKey = lastKey;
       }
       const follow = armed && utterance && utterance.key !== skipKey ? utterance : null;
+      if (utterance?.key) lastKey = utterance.key;
       if (!running) armed = false;
       return follow;
     },
@@ -324,6 +329,26 @@ export function createSentencePlayer({ send, play, halt, silence, fail = () => {
     get canPause() { return current?.controls?.canPause === true; },
     pause() { if (!current?.controls?.canPause) return false; current.controls.pause(); emitOutput({ key: current.key, status: "confirming" }); return true; },
     resume() { if (!current?.controls?.canPause) return false; current.controls.resume(); emitOutput({ key: current.key, status: "playing" }); return true; },
+    /**
+     * Stop the current audio without marking the answer read. A voice take
+     * that is cancelled must be able to bring the same answer back; a take
+     * that is submitted consumes it instead.
+     */
+    suspend() {
+      if (!current) return null;
+      const key = current.key;
+      const source = current.source;
+      // `follow` marks a key as read when it starts. A cancelled voice take
+      // must be able to follow the same key again, so undo that mark here.
+      if (key != null) consumed.delete(key);
+      stop();
+      silence(source);
+      return key;
+    },
+    /** Mark an answer read without playing it (a voice take owns it now). */
+    consume(key) {
+      mark(consumed, key);
+    },
     stop() {
       if (!current) return;
       mark(consumed, current.key);

package/voice/stream-client.js

@@ -45,98 +45,180 @@ function clientFacts() {
   };
 }
 
+const RECONNECT_ATTEMPTS = 3;
+const RECONNECT_DELAY_MS = 400;
+
+/** A phone can lose the socket (lock screen, app switch, Wi-Fi/cellular) mid-answer. */
+function reconnectable(error) {
+  const code = error?.message;
+  return code === "voice_disconnected";
+}
+
 export async function playAudioStream(options) {
   const started = Date.now();
-  const connection = await openAudioStream({ ...options, operation: "tts" });
-  if (!connection) throw new Error("voice_stream_failed");
-  const file = createBrowserPlayer();
-  let progressNoted = false, progressBlocked = false;
-  // A phone that suspends the WebView stops the worklet without closing the
-  // socket, so the host waits for frames that will never come. Report that gap
-  // with the page/context state instead of leaving the next test guessing.
-  let lastProgressAt = Date.now(), gapReported = false, gapAt = 0, formatNoted = false;
-  const player = createPcmStreamPlayer({ onProgress: (frames) => {
-    lastProgressAt = Date.now();
-    if (gapReported) { gapReported = false; streamMetric(options, { stage: "playback_gap_end", frames, gapMs: Date.now() - gapAt, ...clientFacts(), context: player.contextState() }); }
-    if (connection.readyState !== 1) {
-      if (!progressBlocked) { progressBlocked = true; streamMetric(options, { stage: "playback_progress_blocked", readyState: connection.readyState, frames }); }
-      return;
-    }
-    try { connection.send(JSON.stringify({ type: "progress", frames })); }
-    catch (error) {
-      if (!progressBlocked) { progressBlocked = true; streamMetric(options, { stage: "playback_progress_blocked", code: error?.message || "send_failed", frames }); }
-      return;
-    }
-    if (!progressNoted) { progressNoted = true; streamMetric(options, { stage: "playback_progress_sent", frames }); }
-  },
-    onMetric: (event) => { if (event.stage === "playback_started") options.onStatus?.("playing"); streamMetric(options, { ...event, durationMs: Date.now() - started }); } });
-  let chain = Promise.resolve(), complete = false, ending = false, firstReceived = false, ready = false, paused = false, segmentIndex = -1;
-  const gapWatch = setInterval(() => {
-    if (!ready || paused || complete || gapReported || Date.now() - lastProgressAt < 4000) return;
-    gapReported = true;
-    gapAt = lastProgressAt;
-    streamMetric(options, { stage: "playback_gap", gapMs: Date.now() - lastProgressAt, frames: player.playedFrames(), ...clientFacts(), context: player.contextState(), sampleRate: player.sampleRate() });
-  }, 1000);
-  gapWatch.unref?.();
-  const noteVisibility = () => {
-    if (ready && !complete) streamMetric(options, { stage: "playback_visibility", frames: player.playedFrames(), paused, ...clientFacts(), context: player.contextState() });
-  };
-  if (typeof document !== "undefined" && document.addEventListener) document.addEventListener("visibilitychange", noteVisibility);
+  const attempts = Math.max(1, Number(options.reconnectAttempts) || RECONNECT_ATTEMPTS);
+  const reconnectDelay = Number.isFinite(options.reconnectDelayMs) ? Math.max(0, options.reconnectDelayMs) : RECONNECT_DELAY_MS;
+  // Frames already rendered before the current socket. A reconnected socket
+  // replays the answer from its first segment; dropping this prefix keeps the
+  // listener where the dropped connection left off.
+  let skipFrames = 0;
+  let lastError = null;
+  let paused = false;
+  const controls = { player: null, connection: null, file: null, ready: false };
   options.controls?.({
-    get canPause() { return ready; },
-    pause() { if (!ready || paused) return; paused = true; player.pause(); file.pause(); if (connection.readyState === 1) connection.send(JSON.stringify({ type: "pause" })); },
-    resume() { if (!ready || !paused) return; paused = false; player.resume(); void file.resume()?.catch(() => connection.close()); if (connection.readyState === 1) connection.send(JSON.stringify({ type: "resume" })); },
+    get canPause() { return controls.ready; },
+    pause() {
+      if (!controls.ready || paused) return;
+      paused = true; controls.player?.pause(); controls.file?.pause();
+      if (controls.connection?.readyState === 1) controls.connection.send(JSON.stringify({ type: "pause" }));
+    },
+    resume() {
+      if (!controls.ready || !paused) return;
+      paused = false; controls.player?.resume();
+      void controls.file?.resume()?.catch?.(() => controls.connection?.close());
+      if (controls.connection?.readyState === 1) controls.connection.send(JSON.stringify({ type: "resume" }));
+    },
   });
-  try {
-    await new Promise((resolve, reject) => {
-      let failureLogged = false;
-      const noteFailure = (error) => {
-        const code = error?.message || "voice_playback_failed";
-        if (failureLogged || code === "voice_cancelled") return;
-        failureLogged = true;
-        streamMetric(options, { stage: "playback_failed", code, durationMs: Date.now() - started });
-      };
-      const fail = (error) => { noteFailure(error); reject(error); connection.close(); };
-      const cancelled = () => { player.stop(); file.stop(); fail(new Error("voice_cancelled")); };
-      options.signal?.addEventListener("abort", cancelled, { once: true });
-      connection.addEventListener("message", ({ data }) => {
-        if (typeof data !== "string" && !firstReceived) { firstReceived = true; streamMetric(options, { stage: "playback_first_received", durationMs: Date.now() - started }); }
-        let event = null;
-        if (typeof data === "string") {
-          try { event = JSON.parse(data); } catch (error) { chain = chain.then(() => { throw error; }).catch(fail); return; }
-          if (event?.type === "done") ending = true;
-        }
-        chain = chain.then(async () => {
-          if (options.signal?.aborted) throw new Error("voice_cancelled");
-          if (typeof data !== "string") { player.write(new Uint8Array(data)); return; }
-          if (event.type === "segment") {
-            if (event.index !== segmentIndex + 1) throw new Error("voice_reply_sequence");
-            segmentIndex = event.index;
-          }
-          else if (event.type === "segment.end") options.onSegment?.(event);
-          else if (event.type === "format") {
-            await player.start(event); ready = true; lastProgressAt = Date.now(); if (paused) player.pause();
-            if (!formatNoted) { formatNoted = true; streamMetric(options, { stage: "playback_client", sampleRate: event.sampleRate, context: player.contextState(), ...clientFacts() }); }
+
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (attempt > 0) {
+      if (options.signal?.aborted) throw new Error("voice_cancelled");
+      streamMetric(options, { stage: "playback_reconnect", attempt, skipFrames, code: lastError?.message || "voice_disconnected", ...clientFacts() });
+      await new Promise((resolve) => setTimeout(resolve, reconnectDelay));
+      if (options.signal?.aborted) throw new Error("voice_cancelled");
+    }
+    const connection = await openAudioStream({ ...options, operation: "tts" });
+    if (!connection) throw new Error("voice_stream_failed");
+    const file = createBrowserPlayer();
+    let progressNoted = false, progressBlocked = false;
+    let lastProgressAt = Date.now(), gapReported = false, gapAt = 0, formatNoted = false;
+    let chain = Promise.resolve(), complete = false, ending = false, firstReceived = false, ready = false, segmentIndex = -1;
+    // The skipped prefix belongs to this new socket and is acknowledged as it
+    // arrives, so the host keeps sending it without waiting for a playhead
+    // that only starts after the skip.
+    let skipBytes = skipFrames * 2;
+    let skippedFrames = 0;
+    let skipAckAt = 0;
+    const player = createPcmStreamPlayer({
+      onProgress: (frames) => {
+        lastProgressAt = Date.now();
+        if (gapReported) { gapReported = false; streamMetric(options, { stage: "playback_gap_end", frames: skipFrames + frames, gapMs: Date.now() - gapAt, ...clientFacts(), context: player.contextState() }); }
+        ack(skipFrames + frames);
+      },
+      onMetric: (event) => {
+        if (event.stage === "playback_started") options.onStatus?.("playing");
+        streamMetric(options, { ...event, durationMs: Date.now() - started });
+      },
+    });
+    controls.player = player;
+    controls.connection = connection;
+    controls.file = file;
+    controls.ready = false;
+    const ack = (frames) => {
+      if (connection.readyState !== 1) {
+        if (!progressBlocked) { progressBlocked = true; streamMetric(options, { stage: "playback_progress_blocked", readyState: connection.readyState, frames }); }
+        return;
+      }
+      try { connection.send(JSON.stringify({ type: "progress", frames })); }
+      catch (error) {
+        if (!progressBlocked) { progressBlocked = true; streamMetric(options, { stage: "playback_progress_blocked", code: error?.message || "send_failed", frames }); }
+        return;
+      }
+      if (!progressNoted) { progressNoted = true; streamMetric(options, { stage: "playback_progress_sent", frames }); }
+    };
+    const writeAudio = (bytes) => {
+      let chunk = bytes;
+      if (skipBytes > 0) {
+        const drop = Math.min(skipBytes, chunk.length);
+        skipBytes -= drop;
+        skippedFrames += drop / 2;
+        if (Date.now() - skipAckAt >= 40) { skipAckAt = Date.now(); ack(skippedFrames); }
+        chunk = chunk.subarray(drop);
+        if (!chunk.length) return;
+      }
+      player.write(chunk);
+    };
+    const gapWatch = setInterval(() => {
+      if (!ready || paused || complete || gapReported || Date.now() - lastProgressAt < 4000) return;
+      gapReported = true;
+      gapAt = lastProgressAt;
+      streamMetric(options, { stage: "playback_gap", gapMs: Date.now() - lastProgressAt, frames: skipFrames + player.playedFrames(), ...clientFacts(), context: player.contextState(), sampleRate: player.sampleRate() });
+    }, 1000);
+    gapWatch.unref?.();
+    const noteVisibility = () => {
+      if (ready && !complete) streamMetric(options, { stage: "playback_visibility", frames: skipFrames + player.playedFrames(), paused, ...clientFacts(), context: player.contextState() });
+    };
+    if (typeof document !== "undefined" && document.addEventListener) document.addEventListener("visibilitychange", noteVisibility);
+    try {
+      await new Promise((resolve, reject) => {
+        let logged = false;
+        const fail = (error) => {
+          if (logged) return;
+          logged = true;
+          reject(error);
+        };
+        const cancelled = () => { player.stop(); file.stop(); fail(new Error("voice_cancelled")); };
+        options.signal?.addEventListener("abort", cancelled, { once: true });
+        connection.addEventListener("message", ({ data }) => {
+          if (typeof data !== "string" && !firstReceived) { firstReceived = true; streamMetric(options, { stage: "playback_first_received", durationMs: Date.now() - started }); }
+          let event = null;
+          if (typeof data === "string") {
+            try { event = JSON.parse(data); } catch (error) { chain = chain.then(() => { throw error; }).catch(fail); return; }
+            if (event?.type === "done") ending = true;
           }
-          else if (event.type === "file") { ready = true; options.onStatus?.("playing"); await file.play(wavBlob(event.audio)); if (connection.readyState === 1) connection.send(JSON.stringify({ type: "file.done" })); }
-          else if (event.type === "error") throw new Error(event.code || "voice_stream_failed");
-          else if (event.type === "done") { await player.finish(); complete = true; resolve(); }
-        }).catch(fail);
+          chain = chain.then(async () => {
+            if (options.signal?.aborted) throw new Error("voice_cancelled");
+            if (typeof data !== "string") { writeAudio(new Uint8Array(data)); return; }
+            if (event.type === "segment") {
+              if (event.index !== segmentIndex + 1) throw new Error("voice_reply_sequence");
+              segmentIndex = event.index;
+            }
+            else if (event.type === "segment.end") options.onSegment?.(event);
+            else if (event.type === "format") {
+              await player.start(event); ready = controls.ready = true; lastProgressAt = Date.now();
+              if (paused) {
+                player.pause();
+                if (connection.readyState === 1) connection.send(JSON.stringify({ type: "pause" }));
+              }
+              if (!formatNoted) { formatNoted = true; streamMetric(options, { stage: "playback_client", sampleRate: event.sampleRate, context: player.contextState(), ...clientFacts() }); }
+            }
+            else if (event.type === "file") {
+              // A whole-file answer cannot be offset-skipped; a reconnect plays it again.
+              ready = controls.ready = true; options.onStatus?.("playing");
+              await file.play(wavBlob(event.audio));
+              if (connection.readyState === 1) connection.send(JSON.stringify({ type: "file.done" }));
+            }
+            else if (event.type === "error") throw new Error(event.code || "voice_stream_failed");
+            else if (event.type === "done") { await player.finish(); complete = true; resolve(); }
+          }).catch(fail);
+        });
+        const dropped = () => new Error(options.signal?.aborted ? "voice_cancelled" : "voice_disconnected");
+        connection.addEventListener("error", () => fail(dropped()), { once: true });
+        connection.addEventListener("close", () => {
+          options.signal?.removeEventListener("abort", cancelled);
+          if (!complete && !ending) fail(dropped());
+        }, { once: true });
+        if (options.signal?.aborted) cancelled();
       });
-      const dropped = () => new Error(options.signal?.aborted ? "voice_cancelled" : "voice_disconnected");
-      connection.addEventListener("error", () => fail(dropped()), { once: true });
-      connection.addEventListener("close", () => {
-        options.signal?.removeEventListener("abort", cancelled);
-        if (!complete && !ending) { const error = dropped(); noteFailure(error); reject(error); }
-      }, { once: true });
-      if (options.signal?.aborted) cancelled();
-    });
-    return true;
-  } finally {
-    clearInterval(gapWatch);
-    if (typeof document !== "undefined" && document.removeEventListener) document.removeEventListener("visibilitychange", noteVisibility);
-    player.stop(); file.stop(); connection.close();
+      return true;
+    } catch (error) {
+      lastError = error;
+      if (reconnectable(error) && attempt < attempts - 1) {
+        skipFrames += player.playedFrames();
+        continue;
+      }
+      if (error?.message !== "voice_cancelled") {
+        streamMetric(options, { stage: "playback_failed", code: error?.message || "voice_playback_failed", durationMs: Date.now() - started });
+      }
+      throw error;
+    } finally {
+      clearInterval(gapWatch);
+      if (typeof document !== "undefined" && document.removeEventListener) document.removeEventListener("visibilitychange", noteVisibility);
+      if (controls.player === player) { controls.player = null; controls.connection = null; controls.file = null; controls.ready = false; }
+      player.stop(); file.stop(); connection.close();
+    }
   }
+  throw lastError || new Error("voice_disconnected");
 }
 
 /** A single final ASR result; partials never submit a task or replace the draft. */

package/voice/stream-gateway.js

@@ -1,5 +1,6 @@
 import { ttsVoiceForModel } from "./tts-voice.js";
 import { speechSegments } from "./script.js";
+import { createPlayoutClock, SOCKET_FUSE_BYTES } from "./playout-clock.js";
 import { createSynthesisRuns, utteranceKey } from "./synthesis-run.js";
 import { randomUUID } from "node:crypto";
 import { WebSocket, WebSocketServer } from "ws";
@@ -48,14 +49,15 @@ export function createAudioStreamGateway({ config, models, replies, synthesize =
       server.handleUpgrade(req, socket, head, (client) => {
         clients.add(client);
         const abort = new AbortController();
-        let upstream = null, sentFrames = 0, playedFrames = 0, rate = 0, waiter = null, outputFormat = null;
+        let upstream = null, sentFrames = 0, playedFrames = 0, rate = 0, eventWaiter = null, creditWaiter = null, outputFormat = null;
+        const clock = createPlayoutClock();
         let fileDone = null, pausedAt = 0, closing = false, ttsKey = null;
         let received = 0, committed = false, outputStarted = false;
         const started = Date.now();
         const send = (value) => { if (client.readyState === 1) client.send(JSON.stringify(value)); };
         const close = () => {
           if (closing) return;
-          closing = true; abort.abort(); waiter?.(); fileDone?.(); clearTimeout(lifetime); upstream?.terminate();
+          closing = true; abort.abort(); eventWaiter?.(); creditWaiter?.(); eventWaiter = creditWaiter = null; fileDone?.(); clearTimeout(lifetime); upstream?.terminate();
           // A consumer that disappeared stops its synthesis instead of leaving
           // the whole answer to be rendered with nobody listening.
           if (ttsKey) synthesis.release(ttsKey);
@@ -84,12 +86,14 @@ export function createAudioStreamGateway({ config, models, replies, synthesize =
             } else {
               if (binary) throw fault("voice_stream_state");
               const frame = JSON.parse(String(raw));
-              if (frame.type === "pause") { if (!pausedAt) pausedAt = Date.now(); waiter?.(); waiter = null; return; }
-              if (frame.type === "resume") { pausedAt = 0; waiter?.(); waiter = null; return; }
+              if (frame.type === "pause") { clock.pause(); if (!pausedAt) pausedAt = Date.now(); creditWaiter?.(); creditWaiter = null; return; }
+              if (frame.type === "resume") { clock.resume(); pausedAt = 0; creditWaiter?.(); creditWaiter = null; return; }
               if (frame.type === "file.done" && fileDone) { fileDone(); fileDone = null; return; }
               if (frame.type !== "progress" || !Number.isSafeInteger(frame.frames) || frame.frames < playedFrames || frame.frames > sentFrames) throw fault("voice_stream_state");
               const firstProgress = playedFrames === 0 && frame.frames > 0;
-              playedFrames = frame.frames; waiter?.(); waiter = null;
+              playedFrames = frame.frames;
+              if (rate) clock.heard(frame.frames * 1000 / rate);
+              creditWaiter?.(); creditWaiter = null;
               if (firstProgress) metric({ stage: "playback_progress", voiceId: grant.scope.id, frames: playedFrames });
             }
           } catch (cause) { error(cause); }
@@ -117,11 +121,16 @@ export function createAudioStreamGateway({ config, models, replies, synthesize =
             for (let index = 0; index < parts.length; index += 1) yield { text: parts[index], index };
           })(), { model: grant.model, voice: ttsVoiceForModel(grant.config, grant.model), voiceId: grant.scope.id });
           let cursor = 0;
-          const unsub = run.subscribe(() => { waiter?.(); waiter = null; });
+          const wakeEvent = () => { const fn = eventWaiter; eventWaiter = null; fn?.(); };
+          // New PCM must not clear the playout timer. A long answer keeps
+          // producing chunks; waking the credit wait on each one restarted the
+          // stall deadline, so a phone that had already played its buffer never
+          // received the rest and never got an error either.
+          const unsub = run.subscribe(wakeEvent);
           const waitFor = () => new Promise((resolve, reject) => {
             if (abort.signal.aborted) { reject(fault("voice_cancelled")); return; }
-            const wake = () => { abort.signal.removeEventListener("abort", wake); waiter = null; if (abort.signal.aborted) reject(fault("voice_cancelled")); else resolve(); };
-            waiter = wake;
+            const wake = () => { abort.signal.removeEventListener("abort", wake); eventWaiter = null; if (abort.signal.aborted) reject(fault("voice_cancelled")); else resolve(); };
+            eventWaiter = wake;
             abort.signal.addEventListener("abort", wake, { once: true });
           });
           let reportedWait = false;
@@ -143,21 +152,23 @@ export function createAudioStreamGateway({ config, models, replies, synthesize =
               } else if (event.type === "audio") {
                 if (!rate) throw fault("voice_audio_format", 502);
                 for (let offset = 0; offset < event.chunk.length; offset += 16384) {
-                  while (pausedAt || sentFrames - playedFrames > rate * 2 || client.bufferedAmount > 128 * 1024) {
-                    if (!reportedWait) { reportedWait = true; metric({ stage: "playback_wait", voiceId: grant.scope.id, sentFrames, playedFrames, paused: Boolean(pausedAt) }); }
-                    // A device switch or a locked screen can stop playout for a
-                    // while without the client being gone. Wait for it to come
-                    // back instead of ending the answer after ten seconds.
+                  // Stay a short lead ahead of playout. Reported frames move
+                  // the playhead; if those ticks stop, the reply still advances
+                  // with the clock. The socket buffer is only a fuse for a
+                  // client that has stopped reading.
+                  const sentMs = () => sentFrames * 1000 / rate;
+                  while (clock.paused || clock.blocked(sentMs()) || client.bufferedAmount > SOCKET_FUSE_BYTES) {
+                    if (!reportedWait) { reportedWait = true; metric({ stage: "playback_wait", voiceId: grant.scope.id, sentFrames, playedFrames, paused: clock.paused }); }
                     await new Promise((resolve, reject) => {
-                      // A locked screen or a device switch is a pause, not a
-                      // lost client: hold the answer long enough for the page
-                      // to come back before failing it.
-                      const limit = pausedAt ? Math.max(1, pauseHoldMs - (Date.now() - pausedAt)) : playbackStallMs;
-                      const timer = setTimeout(() => { waiter = null; reject(fault(pausedAt ? "voice_interruption_timeout" : "voice_audio_backpressure")); }, limit);
-                      waiter = () => { clearTimeout(timer); resolve(); };
+                      const reading = !clock.paused && client.bufferedAmount <= SOCKET_FUSE_BYTES;
+                      const limit = clock.paused ? Math.max(1, pauseHoldMs - (Date.now() - pausedAt)) : reading ? Math.max(15, Math.min(250, clock.wait(sentMs()) || 15)) : playbackStallMs;
+                      const timer = setTimeout(() => { creditWaiter = null; if (reading) resolve(); else reject(fault(clock.paused ? "voice_interruption_timeout" : "voice_audio_backpressure")); }, limit);
+                      creditWaiter = () => { clearTimeout(timer); resolve(); };
+                      if (!(clock.paused || clock.blocked(sentMs()) || client.bufferedAmount > SOCKET_FUSE_BYTES)) { clearTimeout(timer); creditWaiter = null; resolve(); }
                     });
                     if (abort.signal.aborted || client.readyState !== 1) throw fault("voice_cancelled");
                   }
+                  clock.start();
                   if (client.readyState !== 1) throw fault("voice_cancelled");
                   const part = event.chunk.subarray(offset, offset + 16384);
                   sentFrames += part.length / 2;

package/voice/unified-conversation.js

@@ -274,7 +274,9 @@ export function createUnifiedConversation({ request, socket: openSocket = browse
     lastSessionId = state.sessionId;
     if (lastSessionId) controller.bindSession(lastSessionId);
     if (state.error && state.error !== "voice_cancelled") throw new Error(state.error);
-    controller.observeAgent(Boolean(state.running) || Boolean(reply), Boolean(reply?.audio));
+    // A finished reply is not a running agent: keeping it "running" left the
+    // panel on Working forever and blocked the next continuous turn.
+    controller.observeAgent(Boolean(state.running), Boolean(reply?.audio));
   };
   const watch = async () => {
     if (disposed || controller.getSnapshot().connection === "closed") return;