@gotcos/glasses-server 6.36.27 → 6.36.28

package/CHANGELOG.md

@@ -1,3 +1,60 @@
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.36.27",
+  "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/routes/tts.ts

@@ -28,6 +28,7 @@ import {
   completeEntry,
   abortEntry,
   createSession,
+  initialGraceMs,
   peekSession,
   rebindSessionHash,
   reapExpiredSessions,
@@ -868,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 {
@@ -917,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({
@@ -926,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
@@ -1076,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' })
   }