@gotcos/glasses-server 6.22.1 → 6.23.0

package/CHANGELOG.md

@@ -1,3 +1,57 @@
+## 6.23.0
+
+A recording whose phone goes away now becomes a meeting on its own. Miles: "we end
+up with a meeting that is orphaned that we have no ability to keep."
+
+Found live while writing this: two sessions stranded for 184 and 24 minutes, holding
+the restart lock, while `GET /api/meeting/orphans` answered `count: 0`. Both saved at
+100% transfer integrity (529/529 and 23/23 chunks). Nothing had been lost — but
+nothing was going to turn them into meetings either.
+
+- **The audio was never the problem.** A stranded capture stays live in memory for 4
+  hours, then closes as `expired` and its chunks move to quarantine for 72 more. A
+  76-hour window in which the audio exists and NOTHING converts it into a meeting
+  unless a human notices. Expiry produced preserved evidence, not a meeting.
+- **The 60-second sweeper already existed and already detected these.** It called
+  `closeTranscriptSession(id, 'expired')`. The change is the disposition at the
+  cutoff, not new scheduling: it now finalizes through `POST /api/meeting/save`,
+  which keeps the live ASR transcript and its speaker labels. The quarantine recover
+  route was the wrong tool here — its output labels every speaker Unknown, because no
+  live ASR ever ran on it.
+- **Staleness never closes a session early, and it must not.** The companion buffers
+  to IndexedDB while iOS suspends the WebView and drains on foreground, and it
+  restores `restoredSessionId` across a relaunch — so a phone silent for 30 minutes
+  can still deliver its tail into the same session id. Close it and `isSessionDeleted`
+  answers 410 Gone: a truncated meeting AND a second orphan. At the stale threshold a
+  readable draft is written and the session stays open.
+- **`/api/meeting/orphans` and `/api/health` were blind to the state that matters.**
+  Both listed only QUARANTINED directories, and a stranded session is not quarantined
+  for four hours. New `stranded` / `stranded_captures` report idle minutes, captured
+  minutes, chunk count, when the sweeper will save it, and whether a draft exists.
+- **Quiet is not failure.** A heartbeat carrying `audioState` is now kept per session
+  and can VETO a stale verdict — a phone that says it is recording is alive even with
+  no chunk arriving, because its uploads may merely be blocked. A BACKGROUNDED phone
+  counts as capturing; requiring `visibilityState: visible` would reap exactly the
+  sessions the drain path exists to rescue. Absence proves nothing in the other
+  direction: `clientLog` is fire-and-forget and lossy, so a missing heartbeat can
+  never itself mark a session dead. Chunk arrival decides.
+- **One definition of stale.** `RECORDING_SESSION_STALE_MS` is now derived from
+  `STRANDED_STALE_MS` rather than being a second literal. Two subsystems disagreeing
+  about what a live recording is, is precisely how the panel could read "2
+  recording(s) active" while the orphan endpoint reported none.
+- A failed auto-save does not throw away a savable capture: `no_token` and 5xx and
+  transport failures retry on the next sweep, 409 yields to the save that already owns
+  the session, and only a terminal 4xx (or an 8-hour backstop) falls back to the old
+  close-and-quarantine.
+
+Coverage: 59 tests over the new modules, 23 mutations all caught. Three of those
+initially SURVIVED — the whole stale branch deleted, the token gate deleted, and the
+terminal draft cleanup deleted — because the loop lived inside a `setInterval` in a
+module no test can import without executing boot recovery, a timer, and writes to the
+real data home. It was extracted with injected dependencies rather than covered by
+source-shape assertions. Full suite green serially (1411 tests); two unrelated files
+flake under file parallelism, which is a pre-existing isolation bug.
+
 ## 6.22.1
 
 Notes attached from somewhere else by a symlink are now read properly. Found by

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.22.1",
-  "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
+  "version": "6.23.0",
+  "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
   "type": "module",
   "bin": {
     "glasses-server": "bin/cli.cjs",

package/server/lib/session-heartbeats.ts

@@ -0,0 +1,62 @@
+// Last-known companion state per recording session.
+//
+// The stranded-session sweeper needs POSITIVE evidence that a phone is still
+// capturing before it declares a quiet session stale. That evidence already
+// arrives on POST /api/diag/client as a heartbeat carrying `audioState` and
+// `visibilityState`, but it was only ever appended to client-diagnostics.jsonl —
+// a file the sweeper would have to parse on every 60s tick. This keeps the newest
+// heartbeat per session in memory instead.
+//
+// DELIBERATELY LOSSY, and safe to be. `clientLog` is fire-and-forget with a 3s
+// abort and a silent catch: 63% of heartbeats were measured missing during one
+// 2026-07-27 session. So an ABSENT heartbeat proves nothing and must never by
+// itself mark a session dead — the sweeper's staleness signal is chunk arrival,
+// and a heartbeat can only ever VETO a stale verdict, never cause one.
+
+import type { SessionHeartbeat } from './stranded-sessions.js'
+
+/**
+ * Bounded so a burst of zombie clients cannot grow this without limit. Well above
+ * any real fleet: a session is one phone, and the sweeper deletes entries as
+ * sessions close.
+ */
+const MAX_TRACKED_SESSIONS = 64
+
+const heartbeats = new Map<string, SessionHeartbeat>()
+
+/** Record the newest heartbeat for a session. Older timestamps are ignored. */
+export function recordSessionHeartbeat(
+  sessionId: string,
+  heartbeat: SessionHeartbeat,
+): void {
+  if (!sessionId) return
+  if (!Number.isFinite(heartbeat.at)) return
+  const existing = heartbeats.get(sessionId)
+  if (existing && existing.at > heartbeat.at) return
+  heartbeats.set(sessionId, heartbeat)
+  if (heartbeats.size <= MAX_TRACKED_SESSIONS) return
+  // Evict oldest-first so the entries that matter (recent, therefore capable of
+  // vetoing a stale verdict) are the ones retained.
+  const ordered = [...heartbeats.entries()].sort((a, b) => a[1].at - b[1].at)
+  for (const [id] of ordered.slice(0, heartbeats.size - MAX_TRACKED_SESSIONS)) {
+    heartbeats.delete(id)
+  }
+}
+
+export function getSessionHeartbeat(sessionId: string): SessionHeartbeat | null {
+  return heartbeats.get(sessionId) ?? null
+}
+
+/** Called when a session reaches any terminal state. */
+export function forgetSessionHeartbeat(sessionId: string): void {
+  heartbeats.delete(sessionId)
+}
+
+/** Test seam only. */
+export function resetSessionHeartbeats(): void {
+  heartbeats.clear()
+}
+
+export function trackedHeartbeatCount(): number {
+  return heartbeats.size
+}

package/server/lib/stranded-session-actions.ts

@@ -0,0 +1,302 @@
+// What the sweeper DOES about a stranded session: draft it, then promote it.
+//
+// Two actions, deliberately asymmetric.
+//
+// DRAFT (at the stale threshold) is additive and reversible. It writes the
+// transcript the session already holds to a file and touches nothing else — no
+// store write, no audio move, no session close. That matters because a phone that
+// has been silent for 25 minutes can still drain its IndexedDB buffer into the
+// same session id, and closing early would answer that drain with 410 Gone. A
+// draft cannot truncate anything; it only makes the capture readable and visible
+// while the session stays open for the tail.
+//
+// It also stays OUT of the meetings store on purpose. `POST /api/meeting/save` is
+// idempotent by session id — a second save replays the first receipt. If a draft
+// occupied that id, the real save arriving later with the drained tail would find
+// `alreadySaved` and return the SHORTER checkpoint forever. The draft is a
+// sidecar, never a meeting.
+//
+// PROMOTE (at the retention cutoff) goes through POST /api/meeting/save over
+// loopback rather than calling the store directly. That route owns the maintenance
+// lease, the save-in-progress lock, the receipt contract, domain inference and the
+// two-phase finalization job; reimplementing any of it here would fork the most
+// load-bearing path in the product. The session is still in memory at this point,
+// so the save keeps the live ASR transcript and its speaker labels — which is why
+// promote must not use the quarantine recover route, whose output labels every
+// speaker Unknown because no live ASR ever ran on it.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { atomicWriteFileSync } from './atomic-fs.js'
+import { forgetSessionHeartbeat } from './session-heartbeats.js'
+import { classifyStrandedSession, type SessionHeartbeat } from './stranded-sessions.js'
+
+/** Title given to a capture the sweeper saves on the user's behalf. */
+export const STRANDED_PROMOTE_TITLE = 'Auto-saved capture'
+
+const DRAFT_SUFFIX = '.draft.md'
+/** A draft is a safety net, not an archive. Bounded so it cannot grow unwatched. */
+const MAX_DRAFT_CHARS = 400_000
+
+export interface StrandedDraftInput {
+  sessionId: string
+  transcript: string
+  chunkCount: number
+  startedAt: number
+  lastActivityAt: number
+  /** Injected for deterministic tests. */
+  now?: number
+}
+
+export interface StrandedDraft {
+  sessionId: string
+  path: string
+  bytes: number
+  chunkCount: number
+  updatedAt: string
+}
+
+function draftPath(dir: string, sessionId: string): string {
+  return resolve(dir, `${sessionId}${DRAFT_SUFFIX}`)
+}
+
+/**
+ * Write (or refresh) the draft for a stranded session.
+ *
+ * Returns null when there is nothing worth drafting, so an empty session cannot
+ * litter the directory with contentless files.
+ */
+export function writeStrandedDraft(dir: string, input: StrandedDraftInput): string | null {
+  const transcript = input.transcript.trim()
+  if (!transcript) return null
+  if (!input.sessionId) return null
+  const now = input.now ?? Date.now()
+  const idleMin = Math.round(Math.max(0, now - input.lastActivityAt) / 60_000)
+  const capturedMin = Math.round(Math.max(0, input.lastActivityAt - input.startedAt) / 60_000)
+  const body = transcript.length > MAX_DRAFT_CHARS
+    ? `${transcript.slice(0, MAX_DRAFT_CHARS)}\n\n[draft truncated at ${MAX_DRAFT_CHARS} characters]`
+    : transcript
+  const doc = [
+    '---',
+    `session_id: ${input.sessionId}`,
+    `state: stranded_draft`,
+    `chunks_received: ${input.chunkCount}`,
+    `captured_minutes: ${capturedMin}`,
+    `idle_minutes: ${idleMin}`,
+    `drafted_at: ${new Date(now).toISOString()}`,
+    '---',
+    '',
+    '> Draft only. This capture stopped receiving audio and has not been saved as a',
+    '> meeting yet. The session is still open, so if the phone reconnects the rest of',
+    '> the audio will still arrive. It becomes a real meeting automatically at the',
+    `> retention cutoff, or immediately via POST /api/meeting/save.`,
+    '',
+    body,
+    '',
+  ].join('\n')
+  try {
+    mkdirSync(dir, { recursive: true })
+    atomicWriteFileSync(draftPath(dir, input.sessionId), doc, { mode: 0o600 })
+    return draftPath(dir, input.sessionId)
+  } catch {
+    return null
+  }
+}
+
+/** Every draft currently on disk, newest first. */
+export function listStrandedDrafts(dir: string): StrandedDraft[] {
+  if (!existsSync(dir)) return []
+  const out: StrandedDraft[] = []
+  let entries: string[]
+  try { entries = readdirSync(dir) } catch { return [] }
+  for (const name of entries) {
+    if (!name.endsWith(DRAFT_SUFFIX)) continue
+    const full = resolve(dir, name)
+    try {
+      const st = statSync(full)
+      if (!st.isFile()) continue
+      const head = readFileSync(full, 'utf8').slice(0, 800)
+      const chunks = /^chunks_received: (\d+)$/m.exec(head)
+      out.push({
+        sessionId: name.slice(0, -DRAFT_SUFFIX.length),
+        path: full,
+        bytes: st.size,
+        chunkCount: chunks ? Number(chunks[1]) : 0,
+        updatedAt: new Date(st.mtimeMs).toISOString(),
+      })
+    } catch { /* a draft we cannot stat is not worth failing the sweep over */ }
+  }
+  return out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+}
+
+/** Called once a session reaches a real terminal state. Never throws. */
+export function clearStrandedDraft(dir: string, sessionId: string): void {
+  try { rmSync(draftPath(dir, sessionId), { force: true }) } catch {}
+}
+
+/**
+ * Drop every trace of stranded-state for a session that reached ANY terminal state.
+ *
+ * One function because the two halves must never diverge. A retained draft would
+ * keep /api/meeting/orphans advertising an unsaved capture that is now saved — the
+ * false alarm that trains a user to ignore the one channel built to report real
+ * losses. A retained heartbeat would let a dead session's last breath veto a stale
+ * verdict for a session id that no longer exists.
+ */
+export function releaseStrandedState(dir: string, sessionId: string): void {
+  clearStrandedDraft(dir, sessionId)
+  forgetSessionHeartbeat(sessionId)
+}
+
+export interface SweepableSession {
+  lastActivityAt: number
+  startTime: number
+  chunkCount: number
+}
+
+export interface StrandedSweepInput {
+  now: number
+  /** Empty means this process does not own the API — see the guard below. */
+  token: string
+  draftDir: string
+  sessions: Iterable<[string, SweepableSession]>
+  getHeartbeat: (sessionId: string) => SessionHeartbeat | null
+  getTranscript: (sessionId: string) => string | null
+  /** Fire-and-forget: a promote can run for minutes and must not block the tick. */
+  onPromote: (sessionId: string, lastActivityAt: number) => void
+}
+
+export interface StrandedSweepResult {
+  drafted: string[]
+  promoted: string[]
+  /** Sessions the sweep deliberately left alone. */
+  live: string[]
+}
+
+/**
+ * One pass over the live sessions: draft what has gone quiet, promote what is done.
+ *
+ * EXTRACTED FROM THE INTERVAL ON PURPOSE. While this loop lived inside the
+ * `setInterval` in routes/transcribe-stream.ts no test could reach it, because
+ * importing that module executes boot recovery, a 60s timer, and reads and writes
+ * against the real data home. Two mutations proved the cost: deleting the entire
+ * stale branch, and deleting the token gate, both SURVIVED the whole suite. A loop
+ * that decides whether a recording ever becomes a meeting cannot be covered by
+ * source-shape assertions alone.
+ */
+export function sweepStrandedSessions(input: StrandedSweepInput): StrandedSweepResult {
+  const result: StrandedSweepResult = { drafted: [], promoted: [], live: [] }
+  // Only the process that owns the API can save anything, and only it should be
+  // writing into the data home. No token means a test worker or a tool that
+  // imported the module, so the pass does nothing rather than half-acting.
+  if (!input.token) return result
+  for (const [sessionId, session] of input.sessions) {
+    const verdict = classifyStrandedSession(
+      { lastActivityAt: session.lastActivityAt, heartbeat: input.getHeartbeat(sessionId) },
+      input.now,
+    )
+    if (verdict === 'live') { result.live.push(sessionId); continue }
+    if (verdict === 'stale') {
+      // Draft only. The session stays OPEN so a phone that reconnects can still
+      // drain its buffered tail into this same id.
+      const written = writeStrandedDraft(input.draftDir, {
+        sessionId,
+        transcript: input.getTranscript(sessionId) ?? '',
+        chunkCount: session.chunkCount,
+        startedAt: session.startTime,
+        lastActivityAt: session.lastActivityAt,
+        now: input.now,
+      })
+      if (written) result.drafted.push(sessionId)
+      continue
+    }
+    input.onPromote(sessionId, session.lastActivityAt)
+    result.promoted.push(sessionId)
+  }
+  return result
+}
+
+export interface PromoteResult {
+  ok: boolean
+  status: number
+  filename?: string
+  reason?: string
+}
+
+/**
+ * After a failed auto-save, does the session close (quarantining its audio) or wait
+ * for the next sweep?
+ *
+ * Extracted from the sweeper because it is the decision with the real consequence:
+ * closing means the capture becomes quarantined audio and NOT a meeting, which is
+ * the exact outcome this release exists to prevent. Inside the route it was
+ * untestable without importing and therefore executing the whole module.
+ *
+ * @param idleForMs how long the session has been without a chunk
+ * @param giveUpAfterMs backstop so a permanently-failing save cannot keep a
+ *   session in memory forever
+ */
+export function shouldCloseAfterFailedPromote(
+  result: PromoteResult,
+  idleForMs: number,
+  giveUpAfterMs: number,
+): boolean {
+  if (result.ok) return false
+  // Never reached the server, so nothing was learned about whether it could be
+  // saved. Closing here would destroy a savable capture.
+  if (result.reason === 'no_token') return false
+  // Another save already owns this session. That one wins.
+  if (result.status === 409) return idleForMs >= giveUpAfterMs
+  // A transport failure, a timeout, or a 5xx is transient: retry next sweep.
+  const terminal = result.status >= 400 && result.status < 500
+  return terminal || idleForMs >= giveUpAfterMs
+}
+
+export interface PromoteOptions {
+  port: number
+  token: string
+  /** Injected in tests; defaults to global fetch. */
+  fetchImpl?: typeof fetch
+  timeoutMs?: number
+}
+
+/**
+ * Finalize a stranded session into a meeting through the real save route.
+ *
+ * Omits `domain` deliberately so the route's own keyword inference files it,
+ * rather than dumping every unattended capture into one folder.
+ */
+export async function promoteStrandedSession(
+  sessionId: string,
+  options: PromoteOptions,
+): Promise<PromoteResult> {
+  // No token means this process is not the server that owns the API — a unit test
+  // worker, a tool importing the module. Refusing here matters because an
+  // unauthenticated POST returns 401, the caller would read a 4xx as terminal, and
+  // it would then close a session it could perfectly well have saved. `no_token`
+  // is deliberately NOT terminal.
+  if (!options.token) return { ok: false, status: 0, reason: 'no_token' }
+  const doFetch = options.fetchImpl ?? fetch
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 600_000)
+  try {
+    const res = await doFetch(`http://127.0.0.1:${options.port}/api/meeting/save`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Cos-Token': options.token },
+      body: JSON.stringify({ sessionId, title: STRANDED_PROMOTE_TITLE }),
+      signal: controller.signal,
+    })
+    let payload: Record<string, unknown> = {}
+    try { payload = await res.json() as Record<string, unknown> } catch {}
+    return {
+      ok: res.ok,
+      status: res.status,
+      filename: typeof payload.filename === 'string' ? payload.filename : undefined,
+      reason: typeof payload.reason === 'string' ? payload.reason : undefined,
+    }
+  } catch (error: any) {
+    return { ok: false, status: 0, reason: error?.name === 'AbortError' ? 'timeout' : 'request_failed' }
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/server/lib/stranded-sessions.ts

@@ -0,0 +1,125 @@
+// A recording whose phone went away must still become a meeting.
+//
+// THE DEFECT THIS FIXES. When the companion quits, the bridge drops, or the G2
+// disconnects mid-meeting, the server keeps the session in memory and keeps its
+// ACK'd chunks on disk. Nothing then converts them into a meeting. At the 4-hour
+// retention cutoff the session was closed as 'expired' and its audio moved to
+// quarantine — preserved for 72 more hours, but still not a meeting, and visible
+// only to whoever thought to look. Two sessions sat stranded for 184 and 24
+// minutes on 2026-08-09 holding the restart lock while /api/meeting/orphans
+// reported nothing at all, because that endpoint lists only QUARANTINED dirs and
+// a stranded session is not quarantined for four hours.
+//
+// WHY THE OBVIOUS FIX IS WRONG. "Close idle sessions sooner" loses data. The
+// companion buffers capture to IndexedDB while iOS suspends the WebView and
+// drains on foreground (local-first-meeting-uploader.ts keeps a retry queue), and
+// it restores `restoredSessionId` across a relaunch — so a phone that has been
+// silent for 25 minutes can still deliver its tail into the SAME session id. Once
+// the session is closed, `isSessionDeleted` answers 410 Gone and that tail is
+// gone, leaving a truncated meeting AND a second orphan. So staleness must never
+// close a session early. It may only make the state visible and durable.
+//
+// QUIET IS NOT FAILURE. `lastActivityAt` is bumped in exactly one place —
+// `processStreamChunk` — so it is a pure chunk-ARRIVAL signal and a zombie
+// client's heartbeats cannot mask a dead session. The inverse also has to hold:
+// a phone that reports it is recording right now is alive even with no chunk
+// arriving, because its uploads may merely be blocked. That is why a fresh
+// heartbeat suppresses the stale verdict, and why a BACKGROUNDED phone is not
+// treated as dead — buffering while suspended is designed behavior, not a fault.
+
+import { LOCAL_FIRST_MEETING_IDLE_RETENTION_MS } from './local-first-meetings-contract.js'
+
+/**
+ * No ACK'd chunk for this long and the session is worth telling the user about.
+ *
+ * MUST equal `RECORDING_SESSION_STALE_MS` in routes/transcribe-stream.ts, which
+ * already defines staleness for the maintenance drain gate and for aborting batch
+ * work while a recording is live. A second, different threshold is exactly the bug
+ * this release fixes: the session counter said "2 recordings active" while
+ * /api/meeting/orphans said nothing, because two subsystems disagreed about what
+ * counts as a real recording. One definition, or the disagreement comes back.
+ * `stranded-sessions.test.ts` imports both and fails if they drift.
+ *
+ * It lives here rather than being imported from the route because lib must not
+ * depend on routes; the test is what keeps them married.
+ *
+ * Chunk cadence is roughly 10s, so 30 minutes is ~180 missed chunks: decisively
+ * not a hiccup. It is deliberately NOT a close — see the header. Nothing is
+ * destroyed at this threshold; a draft is written and the session stays open so a
+ * late drain still lands.
+ */
+export const STRANDED_STALE_MS = 30 * 60_000
+
+/**
+ * The session is finished and becomes a meeting.
+ *
+ * Identical to the cutoff that already closed sessions as 'expired', so this
+ * changes the DISPOSITION (save instead of quarantine) and not the timing. Do not
+ * shorten it without re-reading the drain discussion above.
+ */
+export const STRANDED_PROMOTE_MS = LOCAL_FIRST_MEETING_IDLE_RETENTION_MS
+
+/** A heartbeat older than this proves nothing about the phone's state now. */
+export const LIVENESS_GRACE_MS = 3 * 60_000
+
+/**
+ * Pipeline states that mean audio is being captured this moment.
+ *
+ * Sourced from the companion's audio pipeline, whose recording state is
+ * `recording_continuous` for a meeting; `recording` covers the dictation path.
+ */
+const CAPTURING_AUDIO_STATES = new Set(['recording_continuous', 'recording'])
+
+export type StrandedVerdict = 'live' | 'stale' | 'promote'
+
+export interface SessionHeartbeat {
+  /** ms since epoch when the heartbeat arrived. */
+  at: number
+  audioState?: string | null
+  visibilityState?: string | null
+}
+
+export interface SessionActivity {
+  /** ms since epoch of the last ACK'd chunk. NOT bumped by heartbeats. */
+  lastActivityAt: number
+  /** Most recent heartbeat for this session, when one has ever arrived. */
+  heartbeat?: SessionHeartbeat | null
+}
+
+/** How long this session has been without an ACK'd chunk. Never negative. */
+export function strandedForMs(activity: SessionActivity, now: number): number {
+  return Math.max(0, now - activity.lastActivityAt)
+}
+
+/**
+ * Is the phone capturing audio right now?
+ *
+ * Deliberately does NOT require `visibilityState === 'visible'`. A backgrounded
+ * companion buffering to IndexedDB is the single most common legitimate reason
+ * for quiet, and demanding visibility here would reap exactly the sessions the
+ * drain path exists to rescue.
+ */
+export function capturingNow(heartbeat: SessionHeartbeat | null | undefined, now: number): boolean {
+  if (!heartbeat) return false
+  if (!Number.isFinite(heartbeat.at)) return false
+  if (now - heartbeat.at > LIVENESS_GRACE_MS) return false
+  // A heartbeat from the future is a clock artifact, not evidence of capture.
+  if (heartbeat.at - now > LIVENESS_GRACE_MS) return false
+  return CAPTURING_AUDIO_STATES.has((heartbeat.audioState ?? '').trim())
+}
+
+/**
+ * What should the sweeper do with this session?
+ *
+ * `promote` is unconditional at the retention cutoff, matching the close it
+ * replaces — a session that has been silent for four hours becomes a meeting even
+ * if something is still heartbeating, because that is already the behavior today
+ * and weakening it would strand audio for longer than the old code did.
+ */
+export function classifyStrandedSession(activity: SessionActivity, now: number): StrandedVerdict {
+  const idleFor = strandedForMs(activity, now)
+  if (idleFor >= STRANDED_PROMOTE_MS) return 'promote'
+  if (capturingNow(activity.heartbeat, now)) return 'live'
+  if (idleFor >= STRANDED_STALE_MS) return 'stale'
+  return 'live'
+}

package/server/routes/diag.ts

@@ -18,6 +18,7 @@ import { fileURLToPath } from 'node:url'
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url))
 import { dataPath } from '../lib/data-dir.js'
+import { recordSessionHeartbeat } from '../lib/session-heartbeats.js'
 const DIAG_DIR = dataPath()
 const DIAG_FILE = resolve(DIAG_DIR, 'client-diagnostics.jsonl')
 const MAX_FILE_BYTES = 10 * 1024 * 1024  // 10 MB cap
@@ -75,6 +76,19 @@ diagRouter.post('/diag/client', async (req, res) => {
         return res.status(410).json({ error: 'session_deleted', sessionId })
       }
     } catch { /* import failure: fall through to normal logging */ }
+    // Positive liveness for the stranded-session sweeper. A phone can be capturing
+    // while its uploads are blocked, so chunk silence alone must not mark a
+    // session stale — this is the only signal that can say "still recording".
+    // Lossy by nature (fire-and-forget, 3s abort, silent catch), which is why it
+    // may only VETO a stale verdict and never cause one.
+    const heartbeatData = data as Record<string, unknown>
+    recordSessionHeartbeat(sessionId, {
+      at: ts,
+      audioState: typeof heartbeatData.audioState === 'string' ? heartbeatData.audioState : null,
+      visibilityState: typeof heartbeatData.visibilityState === 'string'
+        ? heartbeatData.visibilityState
+        : null,
+    })
   }
 
   // Rate limit per sessionId (or remote address as fallback)

package/server/routes/health.ts

@@ -41,6 +41,7 @@ import { getLocalTtsHealth, refreshLocalTtsHealth } from '../lib/tts-local.js'
 import { liveCuesCapability } from '../lib/live-cues-capability.js'
 import { getMeetingSyncSnapshot } from '../lib/meeting-batch-progress.js'
 import { listUnsavedCaptures } from '../lib/unsaved-audio-quarantine.js'
+import { getStrandedCaptures } from './transcribe-stream.js'
 import { getWhisperPreviewCapability } from '../lib/whisper-preview.js'
 import { getTranscriptionProfileStatus } from '../lib/profile.js'
 import { getHealthStaticProbes } from '../lib/health-static-probes.js'
@@ -235,6 +236,23 @@ healthRouter.get('/health', async (_req, res) => {
       recovered: item.recovered,
     })),
   }
+  // Captures that stopped receiving audio but are NOT yet quarantined, so they do
+  // not appear in unsaved_captures for up to four hours. This is the state COS
+  // Control could not see on 2026-08-09: its panel read "2 recording(s) active.
+  // Restart is locked." while both had been silent for 184 and 24 minutes. Compact
+  // here; full detail on the authenticated orphans route.
+  const strandedList = getStrandedCaptures()
+  const stranded_captures = {
+    count: strandedList.length,
+    items: strandedList.slice(0, 10).map(item => ({
+      sessionId: item.sessionId,
+      idleMinutes: item.idleMinutes,
+      capturedMinutes: item.capturedMinutes,
+      chunks: item.chunks,
+      promotesAt: item.promotesAt,
+      hasDraft: item.draftPath != null,
+    })),
+  }
   const meetingLibrary = resolveMeetingLibrary()
   res.json({
     ...checks,
@@ -257,6 +275,7 @@ healthRouter.get('/health', async (_req, res) => {
       warningCount: meetingLibrary.warnings.length,
     },
     unsaved_captures,
+    stranded_captures,
     chunk_embeddings: chunkEmbeddings,
     speaker_corrections: speakerCorrections,
     review_audio: reviewAudio,

package/server/routes/meeting.ts

@@ -101,6 +101,7 @@ import {
   getSessionStartTime,
   getSessionTranscript,
   getMeetingSessionStatus,
+  getStrandedCaptures,
   getTranscriptionSessionLiveness,
   hasSessionAudio,
   moveSessionAudioToPending,
@@ -1664,8 +1665,16 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
         ? { segmentsDone: progress.segmentsDone, segmentsTotal: progress.segmentsTotal }
         : null
     }
+    // `stranded` is the state this endpoint used to be blind to: a capture whose
+    // phone went away, still live in memory, audio intact, NOT yet quarantined and
+    // therefore absent from `items` for a full four hours. That blindness is why
+    // two stranded sessions could hold the restart lock on 2026-08-09 while this
+    // route answered count: 0.
+    const stranded = getStrandedCaptures()
     res.json({
       count: items.filter(item => !item.recovered).length,
+      strandedCount: stranded.length,
+      stranded,
       recovering: [...recoveringOrphans],
       recoveringProgress,
       items,

package/server/routes/transcribe-stream.ts

@@ -12,6 +12,17 @@ import { fileURLToPath } from 'node:url'
 import { getVocabulary, getOwnerName } from '../lib/profile.js'
 import { getOpenAIKey } from '../lib/openai-key.js'
 import { getTranscriptionPolicySnapshot, isOpenAIWhisperFallbackReady } from '../lib/transcription-policy.js'
+import { STRANDED_STALE_MS } from '../lib/stranded-sessions.js'
+import {
+  clearStrandedDraft,
+  listStrandedDrafts,
+  releaseStrandedState,
+  shouldCloseAfterFailedPromote,
+  sweepStrandedSessions,
+  promoteStrandedSession,
+  writeStrandedDraft,
+} from '../lib/stranded-session-actions.js'
+import { getSessionHeartbeat } from '../lib/session-heartbeats.js'
 import { TranscriptionUnavailableError } from '../lib/transcribe-audio.js'
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url))
@@ -168,6 +179,9 @@ const _unused_hallucination_constants_placeholder = 0 as const
 const SESSION_AUDIO_DIR = dataPath('session-audio')
 ensurePrivateDirectory(SESSION_AUDIO_DIR)
 const PENDING_BATCH_DIR = dataPath('pending-batch')
+// Readable text for a capture that stopped receiving audio. A sidecar, never a
+// meeting — see lib/stranded-session-actions.ts for why it stays out of the store.
+const STRANDED_DRAFT_DIR = dataPath('stranded-drafts')
 ensurePrivateDirectory(PENDING_BATCH_DIR)
 const MAX_SESSION_AUDIO_BYTES = 500 * 1024 * 1024  // 500MB cap per session (~2hr meeting ≈ 260MB)
 const PRESERVED_SESSION_AUDIO_MARKER = '_meeting_save_preserved.marker'
@@ -354,8 +368,15 @@ export function getActiveTranscriptionSessionCount(): number {
  * run to minutes. It sits deliberately far below
  * LOCAL_FIRST_MEETING_IDLE_RETENTION_MS (4h), which governs how long chunks stay
  * recoverable and is far too long to hold a restart on.
+ *
+ * DERIVED, never a second literal. `STRANDED_STALE_MS` is the one definition of
+ * "this recording has gone quiet", and the stranded sweeper, the drain gate and
+ * the batch-abort check must all mean the same thing by it. Two independent
+ * numbers here is exactly the defect this release fixes: on 2026-08-09 the
+ * session counter reported two active recordings while /api/meeting/orphans
+ * reported none, because two subsystems disagreed on what a live recording is.
  */
-export const RECORDING_SESSION_STALE_MS = 30 * 60 * 1000
+export const RECORDING_SESSION_STALE_MS = STRANDED_STALE_MS
 
 export interface TranscriptionSessionLiveness {
   /** Sessions still plausibly recording. These block a restart. */
@@ -397,6 +418,53 @@ export interface TranscriptionSessionLiveness {
  */
 export const __sessionsForTests = sessions
 
+export interface StrandedCapture {
+  sessionId: string
+  /** Minutes since the last ACK'd chunk. */
+  idleMinutes: number
+  /** Minutes of audio actually captured before it went quiet. */
+  capturedMinutes: number
+  chunks: number
+  /** When the sweeper will save this on the user's behalf. */
+  promotesAt: string
+  /** Readable draft on disk, once the capture has been stale long enough. */
+  draftPath: string | null
+  draftBytes: number | null
+}
+
+/**
+ * Captures that stopped receiving audio but have NOT been saved yet.
+ *
+ * This is the row that was missing. `/api/meeting/orphans` listed only
+ * QUARANTINED directories, and a stranded session is not quarantined until the
+ * 4-hour cutoff — so on 2026-08-09 it answered `count: 0` while two sessions sat
+ * stranded for 184 and 24 minutes holding the restart lock. Nothing is wrong with
+ * the quarantine list; it was simply blind to the state that matters most, the one
+ * where the audio is still live and still rescuable.
+ *
+ * Reuses `getTranscriptionSessionLiveness().staleSessions` rather than re-deriving
+ * staleness, so this view and the maintenance drain gate can never disagree.
+ */
+export function getStrandedCaptures(now = Date.now()): StrandedCapture[] {
+  const drafts = new Map(listStrandedDrafts(STRANDED_DRAFT_DIR).map(d => [d.sessionId, d]))
+  return getTranscriptionSessionLiveness(now).staleSessions.map(stale => {
+    const session = sessions.get(stale.sessionId)
+    const lastActivityAt = session?.lastActivityAt ?? now - stale.silentForMs
+    const draft = drafts.get(stale.sessionId) ?? null
+    return {
+      sessionId: stale.sessionId,
+      idleMinutes: Math.round(stale.silentForMs / 60_000),
+      capturedMinutes: Math.round(
+        Math.max(0, lastActivityAt - (session?.startTime ?? lastActivityAt)) / 60_000,
+      ),
+      chunks: stale.chunks,
+      promotesAt: new Date(lastActivityAt + LOCAL_FIRST_MEETING_IDLE_RETENTION_MS).toISOString(),
+      draftPath: draft?.path ?? null,
+      draftBytes: draft?.bytes ?? null,
+    }
+  })
+}
+
 export function getTranscriptionSessionLiveness(now = Date.now()): TranscriptionSessionLiveness {
   let live = 0
   const staleSessions: TranscriptionSessionLiveness['staleSessions'] = []
@@ -768,15 +836,83 @@ if (maintenanceAdmissionsOpen()) {
   recoverSessions()
 }
 
+/** Sessions with an auto-save in flight, so a later tick cannot start a second. */
+const promotingStranded = new Set<string>()
+
+/**
+ * Hard backstop for a capture whose save keeps failing.
+ *
+ * Without it a session that the save route refuses transiently, forever, would
+ * live in memory forever. At twice the cutoff it takes the historical disposition
+ * — close and quarantine — so the audio is at least preserved on the unsaved-audio
+ * clock rather than held hostage by a retry loop.
+ */
+const STRANDED_PROMOTE_GIVE_UP_MS = 2 * LOCAL_FIRST_MEETING_IDLE_RETENTION_MS
+
+/**
+ * Turn an unattended capture into a meeting, and fall back to the old behavior if
+ * that proves impossible.
+ *
+ * Fire-and-forget on purpose: the sweep tick must not await an HQ finalization
+ * that can run for minutes. `promotingStranded` is what keeps the next tick from
+ * starting a duplicate.
+ */
+function promoteStrandedCapture(sessionId: string, lastActivityAt: number): void {
+  if (promotingStranded.has(sessionId)) return
+  promotingStranded.add(sessionId)
+  void promoteStrandedSession(sessionId, {
+    port: parseInt(process.env.PORT ?? '3141', 10),
+    token: process.env.COS_API_TOKEN ?? '',
+  })
+    .then(result => {
+      if (result.ok) {
+        console.warn(
+          `[stranded] Auto-saved unattended capture ${sessionId} \u2192 ${result.filename ?? 'saved'}`,
+        )
+        clearStrandedDraft(STRANDED_DRAFT_DIR, sessionId)
+        return
+      }
+      // Delegated, not restated: closing means the capture becomes quarantined
+      // audio instead of a meeting, which is the outcome this release exists to
+      // prevent, so the rule lives in a module a test can reach.
+      const idleForMs = Date.now() - lastActivityAt
+      if (!shouldCloseAfterFailedPromote(result, idleForMs, STRANDED_PROMOTE_GIVE_UP_MS)) {
+        console.warn(
+          `[stranded] Auto-save deferred for ${sessionId} `
+          + `(${result.status} ${result.reason ?? ''}); retrying next sweep`,
+        )
+        return
+      }
+      console.error(
+        `[stranded] Auto-save failed for ${sessionId} (${result.status} ${result.reason ?? ''}); `
+        + 'closing as expired so the audio reaches quarantine',
+      )
+      if (sessions.has(sessionId)) closeTranscriptSession(sessionId, 'expired')
+    })
+    .finally(() => promotingStranded.delete(sessionId))
+}
+
 // Auto-cleanup sessions idle for the advertised retention horizon.
 setInterval(() => {
   if (!maintenanceAdmissionsOpen()) return
-  const cutoff = Date.now() - LOCAL_FIRST_MEETING_IDLE_RETENTION_MS
-  for (const [id, session] of sessions) {
-    if (session.lastActivityAt < cutoff) {
-      closeTranscriptSession(id, 'expired')
-    }
-  }
+  // A capture whose phone went away must still become a meeting. This loop used
+  // to close every idle session as 'expired', which quarantined its audio and
+  // produced NO meeting — recoverable for 72h, but only by whoever thought to
+  // look. See lib/stranded-sessions.ts for why staleness may not close a session
+  // early and why the cutoff is unchanged.
+  sweepStrandedSessions({
+    now: Date.now(),
+    token: process.env.COS_API_TOKEN ?? '',
+    draftDir: STRANDED_DRAFT_DIR,
+    sessions: [...sessions].map(([id, session]) => [id, {
+      lastActivityAt: session.lastActivityAt,
+      startTime: session.startTime,
+      chunkCount: session.chunks.filter(Boolean).length,
+    }] as const),
+    getHeartbeat: getSessionHeartbeat,
+    getTranscript: id => getSessionTranscript(id),
+    onPromote: promoteStrandedCapture,
+  })
   // Orphaned session-audio dirs (no matching active session): quarantine any
   // dir still holding chunk audio; delete only chunk-less dirs. Quarantine
   // itself expires on the unsaved-audio retention clock, the ONLY place
@@ -1307,6 +1443,10 @@ function finishClosingTranscriptSession(
   clearSessionHallucinationState(sessionId)
   // Track as deleted so orphan heartbeats get 410 Gone (prevents zombie client spam)
   rememberDeletedSession(sessionId)
+  // A session that reached ANY terminal state keeps neither a liveness veto nor a
+  // draft. Leaving the draft would advertise an unsaved capture that is now saved,
+  // which is the false-alarm that trains the user to ignore the channel.
+  releaseStrandedState(STRANDED_DRAFT_DIR, sessionId)
   persistClosedSessions()
   // Clean up persisted file
   try { unlinkSync(resolve(CHUNK_PERSIST_DIR, `${sessionId}.json`)) } catch {}