@gotcos/glasses-server 6.36.26 → 6.36.28

package/CHANGELOG.md

@@ -1,3 +1,98 @@
+## 6.36.28
+
+THE bug. Three earlier fixes tonight were each real and none was this one.
+
+Every segment of a reply is minted at /prepare with a 120s idle deadline that
+starts AT MINT. But the client only touches segment k when segment k-1 starts
+playing. Measured on device, 6,781 chars at 1.25x:
+
+    seg 4   first touched t+101s   played
+    seg 5   first touched t+147s   FAILED
+    seg 6   first touched t+215s   FAILED
+    seg 7   never reached          FAILED
+
+Segment 5 was deleted 27s before the client first asked for it. Reproduced with
+curl against the running server, replaying the exact timeline: HTTP 404 at
+segment 5, t+216s. The 404 reaches the audio element as NotSupportedError at
+readyState 0 -- identical to every other media failure, which is why a char cap,
+a wider idle window and a render gate all left playback stopping at segment 5.
+
+WHAT CHANGED
+
+- An unread session gets a grace window DERIVED from how long the whole reply
+  takes to speak, plus one segment of margin (the last segment is first touched
+  when the second-to-last starts playing).
+- A read may only ever EXTEND a deadline, never shorten one. This is not
+  cosmetic: the client warms segment k one whole segment before playing it, so
+  collapsing the grace on that first read SPENT it. At 0.5x a 900-char segment
+  is 170s of wall time against a 120s window, and the reply lost segment 1 while
+  holding a 1,476s grace. Found by QA, after the first version of this fix.
+- SESSION_IDLE_MS and SESSION_MAX_LIFETIME_MS are now COMPUTED from shared
+  constants rather than written down. Both were derived from ~19 chars/sec, the
+  FAST voice, and this release is the one that measured the slow voice at 10.
+  Leaving them meant the file asserted two contradictory worst cases:
+    idle     900 / 10 / 0.5  =  180s   against a 120s window
+    ceiling  40,000 / 10 / 0.5 = 133 min against a 90 min ceiling
+  The ceiling had also started silently truncating the grace for any reply over
+  ~26,400 chars, relocating the same failure to roughly segment 31 of 46.
+- MAX_LOCAL_TTS_CHARS, LATER_CHUNK_CHARS, the speech rate and the minimum
+  playback rate now live in one place and are imported by the tests that used to
+  restate them. That duplication is why the contradiction above was invisible.
+- /play now logs the 404 it produces. The server held this fact all evening and
+  recorded nothing, so the only reporter was a fire-and-forget client call.
+- CORS exposes Content-Range and Accept-Ranges, without which the client's
+  failure probe reads them as null from the null-origin companion WebView.
+
+SECURITY, stated plainly rather than buried
+
+An unread capability now lives far longer than 120 seconds -- up to the ceiling,
+which is 136 minutes. That is a real widening and it is the price of playing a
+40,000-character reply, which genuinely takes over two hours at 0.5x. What is
+unchanged: the ceiling is absolute, reading cannot extend a capability past the
+grace it was minted with, and an unread capability still expires on its own.
+Both properties are pinned and both mutate red.
+
+216 files, 3047 tests in scope (218 / 3053 including a parallel session's two
+files, which are not part of this release).
+
+## 6.36.27
+
+The sidecar renders one request at a time. The server finally acts like it.
+
+WHAT BROKE. Chunking (6.36.25) split a reply into 9 segments and /prepare
+pre-warmed all 9 at once. The synthesis timeout was armed when a request was
+ISSUED, so it ran while that request sat in the sidecar's queue. Measured on a
+6,781-character reply: renders took ~2.6s each, but segment 5 spent 11.5s of its
+12,000ms budget waiting for a turn. On device it tipped over, the pre-warm
+returned 502, and iOS surfaced it as NotSupportedError. Five of nine segments
+played.
+
+The 12,000ms constant was not wrong when it was written -- its own comment says
+it exists to "bound hung sidecar so local_first can fall back before session TTL
+(~60s)", from an era when a reply was ONE render. Chunking changed the input and
+nothing re-derived the limit.
+
+- New render gate in tts-local.ts. One render reaches the sidecar at a time, so
+  the synthesis timeout now bounds RENDER, which is what it always claimed to
+  bound. Queue wait is governed separately.
+- Queue wait has its own DERIVED ceiling: one synthesis budget per render ahead,
+  plus one budget of headroom. The headroom is not slack -- without it the first
+  waiter's ceiling expires in a dead heat with the holder's own timeout, and a
+  request that was about to be served is rejected in the same tick. Found by the
+  test, not by reasoning.
+- /play outranks /prepare pre-warm. A user is waiting on the first and nobody is
+  waiting on the second; without priority, segment 5's playback request queues
+  behind pre-warms for 6, 7 and 8 -- work not needed for minutes. Priority never
+  reorders playback against itself.
+- /api/health tts_local now reports renderQueueDepth. This was not observable on
+  2026-08-23 and that cost an evening.
+
+Every guard mutation-verified, including one that only counting could catch:
+dropping the waiter's detach left all ten behaviour tests green while leaking an
+abort listener per queued render (45 of them on a 46-segment reply).
+
+217 files, 3042 tests.
+
 ## 6.36.26
 
 Deadline hardening for the segmented TTS path shipped in 6.36.25. Three constants

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.36.26",
+  "version": "6.36.28",
   "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -172,6 +172,12 @@ app.use(cors({
     if (isAllowedNetworkOrigin(origin)) return cb(null, true)
     cb(new Error('CORS blocked'))
   },
+  // Without this, a cross-origin reader sees only the CORS-safelisted response
+  // headers. The companion's origin is `null` (a file:// WebView), so it is
+  // cross-origin by definition, and the TTS failure probe would log
+  // contentRange/acceptRanges as null on every single call -- leading the next
+  // reader to conclude the server had stopped sending Range headers.
+  exposedHeaders: ['Content-Range', 'Accept-Ranges'],
 }))
 // Auth middleware — always active (token is auto-generated if not set).
 // Mounted before body parsers so rejected uploads cannot consume parse memory.

package/server/lib/tts-cache.ts

@@ -101,25 +101,68 @@ const MAX_TOTAL_BYTES = 100 * 1024 * 1024 // 100 MB — in-memory cap
  * practical exposure window is unchanged". That was true, and it is also what
  * left the ceiling in place.
  */
+/**
+ * SHARED PHYSICAL CONSTANTS for every TTS deadline in this file.
+ *
+ * These sit at the top because three separate deadlines are derived from them,
+ * and on 2026-08-23 two of those deadlines were derived from a DIFFERENT
+ * speech rate than the third. Both cannot be right, and the tests could not see
+ * the contradiction because each restated its own copy of the rate.
+ */
+
+/** The longest a single chunk can be. Mirrors the chunker in routes/tts.ts. */
+export const LATER_CHUNK_CHARS = 900
+
+/** The most text one reply can be asked to speak locally. */
+export const MAX_LOCAL_TTS_CHARS = 40_000
+
+/**
+ * Characters spoken per second by the SLOWEST voice, not the average.
+ *
+ * Measured on device 2026-08-23: am_echo ~19 chars/sec, bm_george as low as
+ * 10.6 on one segment. Every deadline below uses 10, because a window sized on
+ * the fast voice does not cover the slow one -- which is the entire class of
+ * bug these constants exist to end.
+ *
+ * CAVEAT, stated because it is load-bearing: this is one segment of one voice
+ * out of 28 shipped Kokoro voices. It errs safe for a WINDOW (too slow means
+ * too generous) but it has not been censused, and a voice slower than 10 would
+ * undersize every deadline here at once.
+ */
+export const SLOWEST_SPEECH_CHARS_PER_SEC = 10
+
+/**
+ * The slowest rate playback can actually run at.
+ *
+ * NOT the slowest option the picker offers -- that is 0.75x. This is the clamp
+ * floor in the client's getPreferredSpeed(), which exists so a poisoned
+ * localStorage value cannot produce an absurd rate. Deadlines must survive the
+ * clamp, not just the menu.
+ */
+export const MIN_PLAYBACK_RATE = 0.5
+
+/** Wall-clock ms to speak `chars` at the slowest voice and slowest rate. */
+export function worstCaseSpeechMs(chars: number): number {
+  return (chars / SLOWEST_SPEECH_CHARS_PER_SEC / MIN_PLAYBACK_RATE) * 1000
+}
+
 export const SESSION_IDLE_MS = (() => {
-  // DERIVED, like the ceiling below, and for the same reason: a window that does
-  // not cover its own inputs is the bug this replaced.
+  // COMPUTED from the shared constants, not written down.
+  //
+  // A session that is being read must outlast the gap between two reads. The
+  // client warms segment i+1 at the START of segment i and does not touch it
+  // again until segment i FINISHES, so that gap is one full segment:
   //
-  // Every segment's session is minted at /prepare. The client warms segment i+1
-  // at the START of segment i, so the gap between that touch and the real request
-  // is ONE FULL SEGMENT of playback. The window has to outlast that gap at the
-  // slowest speed the client offers:
+  //   worstCaseSpeechMs(LATER_CHUNK_CHARS)  =  900 / 10 / 0.5  =  180s
   //
-  //   LATER_CHUNK_CHARS  900 chars
-  //   speech rate        ~19 chars/sec (measured)
-  //   MIN_SPEED          0.5x (voice-output.ts clamps here)
-  //   => 900 / 19 / 0.5 = 94.7s
+  // The previous value, 120s, was derived from ~19 chars/sec -- the FAST voice.
+  // Once bm_george was measured at 10.6 the derivation was stale, and 900 chars
+  // at 0.5x is 180s against a 120s window. That is the same defect this file
+  // has now hit three times, so the value is computed here rather than chosen.
   //
-  // 60s covered 1x (47.4s) and 1.25x (37.9s) but NOT 0.75x (63.2s) -- a shipped
-  // option in the Settings picker. At 0.75x every other segment would 404, and
-  // because onError resolves rather than rejects, playback would skip on and
-  // sound complete while dropping half the reply. 120s covers 0.5x with margin.
-  return 120_000
+  // x1.5 of margin absorbs a stalled segment or a slow refill without letting an
+  // abandoned capability linger: 4.5 minutes, not 90.
+  return Math.ceil(worstCaseSpeechMs(LATER_CHUNK_CHARS) * 1.5)
 })()
 
 /**
@@ -129,24 +172,32 @@ export const SESSION_IDLE_MS = (() => {
  * sliding window could be kept alive indefinitely by polling. This bounds the
  * exposure of a leaked URL.
  *
- * DERIVED, not picked. Every segment of a reply is minted at prepare time, so
- * the ceiling has to outlast the WHOLE reply played at the SLOWEST speed the
- * client offers -- otherwise the last segments expire before playback reaches
- * them, which is the same class of bug as the 60s deadline this replaced:
+ * COMPUTED from the largest reply the system can be asked to speak, at the
+ * slowest voice and slowest rate, plus one segment of margin -- which is exactly
+ * what initialGraceMs computes, so the ceiling is defined as "the largest grace
+ * that can legally be issued":
  *
- *   MAX_LOCAL_TTS_CHARS   40,000 chars
- *   speech rate           ~19 chars per second (measured)
- *   MIN_SPEED             0.5x  (voice-output.ts clamps here)
- *   => 40000 / 19 / 0.5  = 70.2 minutes of audio
+ *   worstCaseSpeechMs(40,000) + worstCaseSpeechMs(900)
+ *     = 40000/10/0.5 + 900/10/0.5  =  8000s + 180s  =  136.3 minutes
  *
- * 30 minutes was shorter than both that and the 1x case (35.1 min), so a maximal
- * reply would have cut off near the end. 90 minutes covers the worst case with
- * margin and is still a bounded window.
+ * The previous 90 minutes was derived from ~19 chars/sec. After the slow voice
+ * was measured at 10.6 that stopped covering its own input: initialGraceMs
+ * exceeded the ceiling for any reply over ~26,400 characters, so the ceiling
+ * silently truncated the grace and a maximal reply's last segments died before
+ * playback reached them -- the segment-5 failure relocated to segment 31 of 46.
  *
- * If MAX_LOCAL_TTS_CHARS or MIN_SPEED changes, re-derive this. A ceiling that
- * silently stops covering its own inputs is exactly what went wrong before.
+ * This is a long-lived bearer capability and that is a real trade, stated rather
+ * than buried: a 40,000-character reply genuinely takes over two hours to speak
+ * at 0.5x, and the capability must outlive the audio it serves. The bound is
+ * still absolute and still unextendable by reading.
+ *
+ * There is no separate arithmetic to keep in sync. Change a shared constant and
+ * both this and the grace move together, and the test below asserts the ceiling
+ * covers the largest grace.
  */
-export const SESSION_MAX_LIFETIME_MS = 90 * 60_000
+export const SESSION_MAX_LIFETIME_MS = Math.ceil(
+  worstCaseSpeechMs(MAX_LOCAL_TTS_CHARS) + worstCaseSpeechMs(LATER_CHUNK_CHARS),
+)
 
 /** Disk cache configuration (env-overridable). Defaults sized for "I run this
  *  on my laptop and forget about it for months" rather than a service tier.
@@ -562,12 +613,60 @@ function sweepStaleByAge(): void {
  *  (hash, text, voice, format) bundle. The play route may reread it for native
  *  Range refills during the 60-second TTL; expired sessions are rejected and
  *  reaped by the periodic sweeper below. */
-export function createSession(s: Omit<SessionEntry, 'expiresAt' | 'hardExpiresAt'>): string {
+/**
+ * How long a session that has NEVER been read stays alive.
+ *
+ * WHY THIS IS NOT SESSION_IDLE_MS. Every segment of a reply is minted at
+ * /prepare, but the client only touches segment k when segment k-1 STARTS
+ * playing. For a 9-segment reply that first touch can be minutes away:
+ *
+ *   measured on device, 6,781 chars at 1.25x
+ *     seg 4  first touched at t+101s   played
+ *     seg 5  first touched at t+147s   FAILED
+ *     seg 6  first touched at t+215s   FAILED
+ *     seg 7  never reached             FAILED
+ *
+ * With a flat 120s idle deadline running from MINT, segment 5 was already dead
+ * when the client first asked for it, and the 404 arrived as
+ * NotSupportedError. Playback stopped at exactly segment 5 on every run.
+ *
+ * So the idle clock must not start before anyone could reasonably read it. An
+ * unread session gets a grace window derived from how long the WHOLE reply takes
+ * to speak at the slowest voice and slowest rate; the 120s idle window applies
+ * from the first read onward, when it means what it says.
+ */
+export function initialGraceMs(totalChars: number): number {
+  // The margin is ONE SEGMENT, not one idle window. The last segment is first
+  // touched when the second-to-last STARTS playing, so the window has to reach
+  // one segment past the end of the reply. An earlier version added
+  // SESSION_IDLE_MS here and described it as covering that gap -- which it does
+  // not, since a segment can be 180s at this file's own slowest rate.
+  const lastSegmentMs = worstCaseSpeechMs(LATER_CHUNK_CHARS)
+  return Math.max(SESSION_IDLE_MS, worstCaseSpeechMs(totalChars) + lastSegmentMs)
+}
+
+export function createSession(
+  s: Omit<SessionEntry, 'expiresAt' | 'hardExpiresAt'>,
+  opts: { graceMs?: number } = {},
+): string {
   const uuid = randomUUID()
   const now = Date.now()
+  // Number.isFinite, not just ??. Math.max(120000, NaN) is NaN, and NaN fails
+  // every comparison in peekSession, so a NaN grace would leave the session
+  // governed only by the ceiling. Cheap to close, silent if left open.
+  const requested = opts.graceMs
+  const grace = Number.isFinite(requested)
+    ? Math.max(SESSION_IDLE_MS, requested as number)
+    : SESSION_IDLE_MS
   sessions.set(uuid, {
     ...s,
-    expiresAt: now + SESSION_IDLE_MS,
+    // Belt and braces, NOT the thing that enforces the ceiling. Mutation shows
+    // removing this Math.min changes nothing observable: peekSession and
+    // reapExpiredSessions both test hardExpiresAt independently, so a grace
+    // beyond the ceiling is already unreachable. Kept because a stored deadline
+    // that lies about its own limit invites a future reader to trust it -- but
+    // do not mistake it for the guard.
+    expiresAt: Math.min(now + grace, now + SESSION_MAX_LIFETIME_MS),
     hardExpiresAt: now + SESSION_MAX_LIFETIME_MS,
   })
   return uuid
@@ -594,10 +693,27 @@ export function peekSession(uuid: string): SessionEntry | null {
     sessions.delete(uuid)
     return null
   }
-  // SLIDING. Every Range refill during playback pushes the idle deadline out, so
-  // a session lives as long as audio is actively being played and dies a minute
-  // after it stops -- never past the hard ceiling.
-  s.expiresAt = Math.min(now + SESSION_IDLE_MS, s.hardExpiresAt)
+  // SLIDING, and it may only ever EXTEND a deadline -- never shorten one.
+  //
+  // The Math.max is the whole point, and its absence was a defect that survived
+  // into review. `warmNext(i)` reads segment i+1 at the START of segment i, and
+  // then nothing touches it again until segment i FINISHES, one full segment
+  // later. If that first read collapsed the derived grace to SESSION_IDLE_MS,
+  // the warm would SPEND the grace instead of using it, and any segment whose
+  // playback exceeds 120s would expire before its turn:
+  //
+  //   900 chars at 10.6 chars/sec = 85s of audio
+  //   at 0.5x                     = 170s of wall time   >  120s
+  //
+  // Verified by replaying the real warm pattern: with a plain assignment the
+  // 6,781-char reply lost segment 1 at t+170s while holding a 1,476s grace.
+  //
+  // Every security property is unchanged. The ceiling still binds independently
+  // below. Reading still buys nothing back -- for a session with a long grace,
+  // max() returns the grace deadline it already had, so a read cannot extend a
+  // capability's life by even a millisecond. Once now + SESSION_IDLE_MS passes
+  // the original grace, this becomes an ordinary sliding window again.
+  s.expiresAt = Math.min(Math.max(s.expiresAt, now + SESSION_IDLE_MS), s.hardExpiresAt)
   return s
 }
 

package/server/lib/tts-local.ts

@@ -269,6 +269,11 @@ export function getLocalTtsHealth(): {
   starting: boolean
   error: string | null
   lastFallbackToOpenAI: { at: string; reason: string } | null
+  /** Renders in flight plus queued. A reply is chunked into up to MAX_CHUNKS
+   *  segments that all pre-warm at once, and the sidecar renders one at a time,
+   *  so this is the number that explains a slow or failing segment. It was not
+   *  observable on 2026-08-23 and that cost an evening. */
+  renderQueueDepth: number
 } {
   return {
     ready: serverAvailable,
@@ -282,6 +287,7 @@ export function getLocalTtsHealth(): {
     starting: serverStarting,
     error: lastError,
     lastFallbackToOpenAI,
+    renderQueueDepth: localRenderQueueDepth(),
   }
 }
 
@@ -390,15 +396,170 @@ export function stopLocalTtsServer(): void {
 }
 
 /** Synthesize via local OpenAI-shaped speech endpoint. Returns full audio Buffer. */
+
+// ── render gate ──────────────────────────────────────────────────────────────
+//
+// The Kokoro sidecar renders ONE request at a time behind its own lock. Issuing
+// N requests concurrently therefore does not make them finish any sooner; it
+// only makes each one's timeout run while it waits its turn.
+//
+// That is what broke playback on 2026-08-23. Chunking turned a reply into 9
+// renders, all fired at once by /prepare's pre-warm. Measured on a 6,781-char
+// reply: each render took ~2.6s, but segment 5's request spent 11.5s of its
+// 12,000ms budget QUEUED. On a slightly busier machine it tipped over, returned
+// 502, and iOS surfaced it as NotSupportedError. Five of nine segments played.
+//
+// The gate makes that queue explicit on our side, which buys two things:
+//
+//   1. The synthesis timeout starts when a request ACQUIRES the gate, so it
+//      bounds RENDER time -- what it was always described as bounding. Waiting
+//      for a turn is governed separately, by a derived ceiling (below).
+//   2. Playback jumps ahead of pre-warm. A /play request has a user waiting on
+//      it; a /prepare pre-warm does not. Without priority, segment 5's playback
+//      request queues behind the pre-warms for 6, 7 and 8 -- work that is not
+//      needed until minutes later.
+//
+// Priority never reorders playback against itself: a priority waiter is placed
+// after other priority waiters and before every background one.
+
+type RenderWaiter = {
+  priority: boolean
+  resolve: () => void
+  reject: (err: Error) => void
+  signal?: AbortSignal
+  detach?: () => void
+}
+
+let gateBusy = false
+const gateWaiters: RenderWaiter[] = []
+
+/** In-flight plus queued renders. Exposed for /api/health and tests. */
+export function localRenderQueueDepth(): number {
+  return gateWaiters.length + (gateBusy ? 1 : 0)
+}
+
+/** Test-only: drop all queued waiters and free the gate. */
+export function __resetRenderGate(): void {
+  for (const w of gateWaiters.splice(0)) {
+    w.detach?.()
+    w.reject(makeAbortError('render gate reset'))
+  }
+  gateBusy = false
+}
+
+function makeAbortError(message: string): Error {
+  const err = new Error(message)
+  err.name = 'AbortError'
+  return err
+}
+
+function releaseRenderGate(): void {
+  const next = gateWaiters.shift()
+  if (!next) {
+    gateBusy = false
+    return
+  }
+  // The gate stays held; ownership passes straight to `next`. Setting
+  // gateBusy = false here would let a later arrival barge in ahead of a
+  // waiter that has already been promised the slot.
+  next.detach?.()
+  next.resolve()
+}
+
+function acquireRenderGate(priority: boolean, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.reject(makeAbortError('local TTS request aborted'))
+  if (!gateBusy) {
+    gateBusy = true
+    return Promise.resolve()
+  }
+  return new Promise<void>((resolve, reject) => {
+    const waiter: RenderWaiter = { priority, resolve, reject, signal }
+
+    // DERIVED ceiling on queue wait, so a wedged sidecar cannot hang callers
+    // forever. Everyone ahead of us is individually bounded by the synthesis
+    // timeout, so the longest legitimate wait is that timeout once per render
+    // ahead of us -- the one in flight plus everyone already queued.
+    //
+    // The +1 is not slack, it is a race fix found by the test below. Without it
+    // the first waiter's ceiling is exactly one render budget, which expires in
+    // a dead heat with the holder's OWN timeout: the holder times out, releases
+    // the gate, and the waiter that was about to be served is rejected in the
+    // same tick. One extra budget of headroom means the queue always outlives
+    // the thing it is waiting for.
+    const ahead = gateWaiters.length + 1
+    const waitCeilingMs = (ahead + 1) * effectiveSynthTimeoutMs()
+    const timer = setTimeout(() => {
+      const at = gateWaiters.indexOf(waiter)
+      if (at >= 0) gateWaiters.splice(at, 1)
+      waiter.detach?.()
+      const err = new Error(
+        `local TTS queue wait exceeded ${waitCeilingMs}ms behind ${ahead} render(s)`,
+      )
+      err.name = 'TimeoutError'
+      reject(err)
+    }, waitCeilingMs)
+    if (typeof timer === 'object' && timer && 'unref' in timer) {
+      ;(timer as { unref: () => void }).unref()
+    }
+
+    const onAbort = () => {
+      const at = gateWaiters.indexOf(waiter)
+      if (at >= 0) gateWaiters.splice(at, 1)
+      waiter.detach?.()
+      reject(makeAbortError('local TTS request aborted'))
+    }
+    waiter.detach = () => {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+
+    if (priority) {
+      const firstBackground = gateWaiters.findIndex((w) => !w.priority)
+      if (firstBackground < 0) gateWaiters.push(waiter)
+      else gateWaiters.splice(firstBackground, 0, waiter)
+    } else {
+      gateWaiters.push(waiter)
+    }
+  })
+}
+
+function effectiveSynthTimeoutMs(): number {
+  return Number.isFinite(LOCAL_TTS_SYNTH_TIMEOUT_MS) && LOCAL_TTS_SYNTH_TIMEOUT_MS > 0
+    ? LOCAL_TTS_SYNTH_TIMEOUT_MS
+    : 12_000
+}
+
 export async function synthesizeLocalTts(opts: {
   text: string
   voice: string
   format: string
   signal?: AbortSignal
+  /** True for a request a user is waiting on (/play). False/undefined for
+   *  background pre-warm, which yields the sidecar to playback. */
+  priority?: boolean
 }): Promise<Buffer> {
-  const timeoutMs = Number.isFinite(LOCAL_TTS_SYNTH_TIMEOUT_MS) && LOCAL_TTS_SYNTH_TIMEOUT_MS > 0
-    ? LOCAL_TTS_SYNTH_TIMEOUT_MS
-    : 12_000
+  // Wait for the sidecar BEFORE starting the synthesis clock. The timeout
+  // below is a render budget; it was previously charged for queue time too,
+  // which is the whole reason segment 5 of 9 died at 12s while rendering in
+  // 2.6s. See the render gate above.
+  await acquireRenderGate(opts.priority === true, opts.signal)
+  try {
+    return await synthesizeLocalTtsRender(opts)
+  } finally {
+    releaseRenderGate()
+  }
+}
+
+/** The actual sidecar call. Never invoke directly -- it assumes the caller
+ *  holds the render gate, and the timeout it starts is a RENDER budget. */
+async function synthesizeLocalTtsRender(opts: {
+  text: string
+  voice: string
+  format: string
+  signal?: AbortSignal
+}): Promise<Buffer> {
+  const timeoutMs = effectiveSynthTimeoutMs()
   const timeoutSignal = AbortSignal.timeout(timeoutMs)
   const signal =
     opts.signal && typeof AbortSignal.any === 'function'

package/server/routes/tts.ts

@@ -28,6 +28,7 @@ import {
   completeEntry,
   abortEntry,
   createSession,
+  initialGraceMs,
   peekSession,
   rebindSessionHash,
   reapExpiredSessions,
@@ -454,6 +455,9 @@ async function generateLocalIntoCache(
   voice: string,
   format: string,
   signal?: AbortSignal,
+  // A user is waiting on a /play render; nobody is waiting on a pre-warm.
+  // Defaults to background so a new caller cannot accidentally starve playback.
+  priority = false,
 ): Promise<{ ok: true } | { ok: false; status: number; message: string }> {
   // A memory/latency bound, NOT OpenAI's 4096. Kokoro reads what it is handed;
   // the old shared cap truncated local speech at ~3-4 pages for no reason that
@@ -471,7 +475,7 @@ async function generateLocalIntoCache(
   }
   try {
     // Local path ignores COS_VOICE_INSTRUCTIONS / per-request instructions.
-    const bytes = await synthesizeLocalTts({ text: spoken, voice, format, signal })
+    const bytes = await synthesizeLocalTts({ text: spoken, voice, format, signal, priority })
     if (!bytes.length) {
       abortEntry(hash)
       return { ok: false, status: 502, message: 'local TTS returned empty body' }
@@ -496,10 +500,11 @@ async function generateIntoCache(
   format: string,
   instructions: string,
   signal?: AbortSignal,
+  priority = false,
 ): Promise<{ ok: true } | { ok: false; status: number; message: string }> {
   if (getCached(hash)) return { ok: true }
   if (decision.backend === 'local') {
-    return generateLocalIntoCache(hash, text, decision.backendVoice, format, signal)
+    return generateLocalIntoCache(hash, text, decision.backendVoice, format, signal, priority)
   }
   return generateOpenAIIntoCache(
     hash,
@@ -520,6 +525,9 @@ async function generateWithFallback(opts: {
   enginePreference?: TtsEnginePreference | null
   signal?: AbortSignal
   sessionId?: string
+  /** True when a user is waiting (a /play cold miss). Background pre-warm
+   *  leaves it false so playback can take the sidecar ahead of it. */
+  priority?: boolean
 }): Promise<{ ok: true; hash: string } | { ok: false; status: number; message: string }> {
   const enginePreference = opts.enginePreference ?? null
   const preferOpenAI = enginePreference === 'openai'
@@ -553,6 +561,7 @@ async function generateWithFallback(opts: {
     opts.format,
     opts.instructions,
     opts.signal,
+    opts.priority === true,
   )
   if (primary.ok) {
     if (softEscapedToOpenAI) {
@@ -586,6 +595,7 @@ async function generateWithFallback(opts: {
       opts.format,
       opts.instructions,
       opts.signal,
+      opts.priority === true,
     )
     if (localResult.ok) {
       if (opts.sessionId) rebindSessionHash(opts.sessionId, localHash)
@@ -616,6 +626,7 @@ async function generateWithFallback(opts: {
       opts.format,
       opts.instructions,
       opts.signal,
+      opts.priority === true,
     )
     if (openaiResult.ok) {
       announceKokoroFallbackToOpenAI(failReason)
@@ -803,6 +814,7 @@ ttsRouter.post('/tts/stream', async (req, res) => {
         voice: decision.backendVoice,
         format: requestedFormat,
         signal: upstreamController.signal,
+        priority: true,
       })
       if (upstreamController.signal.aborted) return
       res.writeHead(200, {
@@ -857,12 +869,12 @@ ttsRouter.post('/tts/stream', async (req, res) => {
 //      hash the (text, voice, format) tuple, and return a session URL.
 //   2. Client sets audio.src = `${apiBase}${sessionUrl}` and calls .play().
 //   3. The browser GETs /api/tts/play/:session using the session as a bearer
-//      capability. Range refills may reuse it during its 60-second lifetime;
+//      capability. Range refills may reuse it throughout its lifetime (see SESSION_IDLE_MS / initialGraceMs);
 //      the route serves cached bytes or starts live generation on a cold miss.
 //
 // The two-step pattern is required because authentication on the play route
 // would force XHR (no Range support, no progressive decoding). The session
-// UUID IS the auth — cryptographically random, short-lived (60s), and scoped
+// UUID IS the auth — cryptographically random, bounded by SESSION_MAX_LIFETIME_MS, and scoped
 // to one prepared audio item. It is re-readable only for native Range refills.
 ttsRouter.post('/tts/prepare', async (req, res) => {
   try {
@@ -906,6 +918,13 @@ ttsRouter.post('/tts/prepare', async (req, res) => {
     const preferOpenAI = enginePreference === 'openai'
     const forceLocal = enginePreference === 'local'
 
+    // Every segment is minted here, but the client only touches segment k when
+    // segment k-1 starts playing -- minutes later for a long reply. So each
+    // session's first deadline is derived from the WHOLE reply's speaking time,
+    // not from a flat idle window that starts before anyone could read it. See
+    // initialGraceMs; this is the bug that stopped playback at segment 5 of 9.
+    const graceMs = initialGraceMs(capped.length)
+
     const mintAndWarm = (chunk: string) => {
       const hash = hashForDecision(decision, requestedFormat, chunk, requestedInstructions)
       const uuid = createSession({
@@ -915,7 +934,7 @@ ttsRouter.post('/tts/prepare', async (req, res) => {
         format: requestedFormat,
         preferOpenAI,
         forceLocal,
-      })
+      }, { graceMs })
       // Detached preparation is deliberately local-only. It must never retain
       // authority to spend cloud budget after the client cancels or closes.
       // OpenAI generation (including Kokoro fallback) begins only from the
@@ -1065,9 +1084,14 @@ function serveCachedBody(
 ttsRouter.get('/tts/play/:session', async (req, res) => {
   // peekSession (v5.9.4) — non-destructive lookup so iOS WKWebView can issue
   // its routine HTTP Range requests for audio buffer refill without 404ing
-  // halfway through a long playback. Sessions still TTL out at 60s.
+  // halfway through a long playback. Sessions TTL out on the idle window, or on their derived grace if never read.
   const session = peekSession(req.params.session)
   if (!session) {
+    // LOG IT. The server produced this 404 and recorded nothing, so the only
+    // reporter was the client -- whose report is fire-and-forget, 3s-aborted and
+    // error-deduped. Four builds on 2026-08-23 were spent inferring a fact the
+    // server held the whole time.
+    console.warn('[tts/play] 404 session expired or unknown:', req.params.session)
     return res.status(404).json({ error: 'session expired or unknown' })
   }
 
@@ -1112,6 +1136,8 @@ ttsRouter.get('/tts/play/:session', async (req, res) => {
     enginePreference,
     signal: upstreamController.signal,
     sessionId: req.params.session,
+    // /play cold miss: the listener is waiting on this render right now.
+    priority: true,
   })
 
   if (!result.ok) {