@gotcos/glasses-server 6.12.7 → 6.13.0

package/server/routes/openai-compat.ts

@@ -14,6 +14,11 @@ import {
 import { tryInstantResponse } from '../lib/response-cache.js'
 import crypto from 'node:crypto'
 import { timingSafeTokenEqual } from '../lib/token-auth.js'
+import {
+  acquireMaintenanceWork,
+  MaintenanceLifecycleError,
+  type MaintenanceWorkLease,
+} from '../lib/maintenance-lifecycle.js'
 
 export const openaiCompatRouter = Router()
 
@@ -131,6 +136,27 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
     })
   }
 
+  // Admission closes before cache lookup, dedup bookkeeping, latency logging,
+  // or provider work. Maintenance therefore has one linearization point for
+  // every OpenAI-compatible request, including instant and duplicate replies.
+  let maintenanceLease: MaintenanceWorkLease
+  try {
+    maintenanceLease = acquireMaintenanceWork('openai_query')
+  } catch (error) {
+    if (error instanceof MaintenanceLifecycleError) {
+      if (error.retryAfterSeconds != null) res.setHeader('Retry-After', String(error.retryAfterSeconds))
+      return res.status(error.status).json({
+        error: {
+          message: error.message,
+          type: 'server_error',
+          code: error.code,
+          retryable: error.retryable,
+        },
+      })
+    }
+    throw error
+  }
+
 
   // Log request entry — tells us if Even sends stream: true or false
   console.log(`[g2] Request: stream=${!!stream}, query="${query.slice(0, 50)}"`)
@@ -184,11 +210,12 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
       res.write(`data: ${JSON.stringify(finalChunk)}\n\n`)
       res.write('data: [DONE]\n\n')
       res.end()
+      maintenanceLease.release()
       return
     }
 
     // Non-streaming cache response
-    return res.json({
+    const response = res.json({
       id: completionId,
       object: 'chat.completion',
       created: timestamp,
@@ -200,6 +227,8 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
       }],
       usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
     })
+    maintenanceLease.release()
+    return response
   }
 
   // ── Dedup guard — if same query is already in-flight within 2s, reuse result ──
@@ -241,9 +270,10 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
         res.write(`data: ${JSON.stringify({ id: completionId, object: 'chat.completion.chunk', created: timestamp, model: responseModel, choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] })}\n\n`)
         res.write('data: [DONE]\n\n')
         res.end()
+        maintenanceLease.release()
         return
       }
-      return res.json({
+      const response = res.json({
         id: completionId,
         object: 'chat.completion',
         created: timestamp,
@@ -251,6 +281,8 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
         choices: [{ index: 0, message: { role: 'assistant', content: dedupResult }, finish_reason: 'stop' }],
         usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
       })
+      maintenanceLease.release()
+      return response
     } catch {
       // Original request failed — fall through to make a fresh request
     }
@@ -311,11 +343,12 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
           }
         },
         onDone: (fullText) => {
-          if (!done) {
-            done = true
-            resolveInflight!(fullText || '')
-            inflightQueries.delete(dedupKey)
-            logLatency({
+          try {
+            if (!done) {
+              done = true
+              resolveInflight!(fullText || '')
+              inflightQueries.delete(dedupKey)
+              logLatency({
               timestamp: new Date().toISOString(),
               query: query.slice(0, 50),
               ttfb_ms: actualTtfbMs,
@@ -325,35 +358,42 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
               contextInjected: /\b(schedule|calendar|meeting|task|tasks|today|tomorrow|next meeting|who do i meet|what's next)\b/i.test(query),
               cacheHit: false,
               stream_requested: true,
-            })
-            // Final chunk with finish_reason
-            const finalChunk = {
+              })
+              // Final chunk with finish_reason
+              const finalChunk = {
               id: completionId,
               object: 'chat.completion.chunk',
               created: timestamp,
               model: responseModel,
               choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
+              }
+              res.write(`data: ${JSON.stringify(finalChunk)}\n\n`)
+              res.write('data: [DONE]\n\n')
+              res.end()
             }
-            res.write(`data: ${JSON.stringify(finalChunk)}\n\n`)
-            res.write('data: [DONE]\n\n')
-            res.end()
+          } finally {
+            maintenanceLease.release()
           }
         },
         onError: (error) => {
-          if (!done) {
-            done = true
-            rejectInflight!(new Error(error))
-            inflightQueries.delete(dedupKey)
-            const errChunk = {
+          try {
+            if (!done) {
+              done = true
+              rejectInflight!(new Error(error))
+              inflightQueries.delete(dedupKey)
+              const errChunk = {
               id: completionId,
               object: 'chat.completion.chunk',
               created: timestamp,
               model: responseModel,
               choices: [{ index: 0, delta: { content: `Error: ${error}` }, finish_reason: 'stop' }],
+              }
+              res.write(`data: ${JSON.stringify(errChunk)}\n\n`)
+              res.write('data: [DONE]\n\n')
+              res.end()
             }
-            res.write(`data: ${JSON.stringify(errChunk)}\n\n`)
-            res.write('data: [DONE]\n\n')
-            res.end()
+          } finally {
+            maintenanceLease.release()
           }
         },
         onToolStatus: (status) => {
@@ -367,6 +407,7 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
       // Persist session ID for multi-turn context on subsequent G2 queries
       g2SessionId = returnedSid
     } catch (err: any) {
+      maintenanceLease.release()
       if (!done) {
         done = true
         rejectInflight!(err)
@@ -399,6 +440,7 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
       const fail = (error: unknown) => {
         if (settled) return
         settled = true
+        maintenanceLease.release()
         const err = error instanceof Error ? error : new Error(String(error))
         rejectInflight!(err)
         inflightQueries.delete(dedupKey)
@@ -412,21 +454,25 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
         onDone: (fullText) => {
           if (settled) return
           settled = true
-          const text = fullText || result
-          resolveInflight!(text)
-          inflightQueries.delete(dedupKey)
-          logLatency({
-            timestamp: new Date().toISOString(),
-            query: query.slice(0, 50),
-            ttfb_ms: nsFirstChunkMs,
-            total_ms: Date.now() - requestReceivedAt,
-            model: resolvedModel,
-            resumed: !!currentSessionIdNS,
-            contextInjected: /\b(schedule|calendar|meeting|task|tasks|today|tomorrow)\b/i.test(query),
-            cacheHit: false,
-            stream_requested: false,
-          })
-          resolve(text)
+          try {
+            const text = fullText || result
+            resolveInflight!(text)
+            inflightQueries.delete(dedupKey)
+            logLatency({
+              timestamp: new Date().toISOString(),
+              query: query.slice(0, 50),
+              ttfb_ms: nsFirstChunkMs,
+              total_ms: Date.now() - requestReceivedAt,
+              model: resolvedModel,
+              resumed: !!currentSessionIdNS,
+              contextInjected: /\b(schedule|calendar|meeting|task|tasks|today|tomorrow)\b/i.test(query),
+              cacheHit: false,
+              stream_requested: false,
+            })
+            resolve(text)
+          } finally {
+            maintenanceLease.release()
+          }
         },
         onError: (error) => {
           fail(new Error(error))

package/server/routes/prompt-drafts.ts

@@ -39,6 +39,13 @@ import { logTokenAudit } from '../lib/token-audit.js'
 import { atomicWriteFileSync } from '../lib/atomic-fs.js'
 import { dataPath } from '../lib/data-dir.js'
 import { emitDisplay } from '../lib/display-bus.js'
+import {
+  acquireMaintenanceWork,
+  maintenanceAdmissionsOpen,
+  MaintenanceLifecycleError,
+  maintenanceErrorPayload,
+  type MaintenanceWorkLease,
+} from '../lib/maintenance-lifecycle.js'
 
 export const promptDraftsRouter = Router()
 
@@ -138,6 +145,12 @@ function sanitizeTranscript(draftId: string, text: string, learnInline = true):
 }
 
 async function sendDraftError(res: Response, draftId: string, err: any): Promise<void> {
+  // Maintenance rejection is an admission result, not a draft failure. Keep
+  // the recoverable draft untouched so the phone can retry after maintenance.
+  if (err instanceof MaintenanceLifecycleError) {
+    if (err.retryAfterSeconds != null) res.setHeader('Retry-After', String(err.retryAfterSeconds))
+    return void res.status(err.status).json({ ...maintenanceErrorPayload(err), draftPreserved: true })
+  }
   if (err instanceof NoSpeechDetectedError) return void res.status(204).send()
   if (err instanceof OpenAIWhisperBudgetExhaustedError) {
     await markPromptDraftError(draftId, err.message)
@@ -211,31 +224,53 @@ async function finalizeDraft(draftId: string, mode: 'hq' | 'fast', autoClean: Au
   return { draftId, text: finalText, recovered: true, chunkCount: finalized.receivedChunkIndexes.length, missingChunks: getMissingChunkIndexes(finalized), expiresAt: finalized.expiresAt }
 }
 
-const prunedAtBoot = prunePromptDrafts()
+const prunedAtBoot = maintenanceAdmissionsOpen() ? prunePromptDrafts() : 0
 if (prunedAtBoot) console.log(`[prompt-draft] pruned ${prunedAtBoot} expired draft(s)`)
-const pruneTimer = setInterval(() => prunePromptDrafts(), 60 * 60 * 1000)
+const pruneTimer = setInterval(() => {
+  if (maintenanceAdmissionsOpen()) prunePromptDrafts()
+}, 60 * 60 * 1000)
 pruneTimer.unref?.()
 
 promptDraftsRouter.post('/prompt-drafts/start', (req, res) => {
-  const requestedId = typeof req.body?.recoveryId === 'string' ? req.body.recoveryId : undefined
-  const meta = createPromptDraft(requestedId)
-  res.json({ draftId: meta.draftId, recoveryId: requestedId ?? meta.draftId, remapped: Boolean(requestedId && requestedId !== meta.draftId), expiresAt: meta.expiresAt, status: meta.status })
+  let maintenanceLease: MaintenanceWorkLease | undefined
+  try {
+    maintenanceLease = acquireMaintenanceWork('prompt_draft_write')
+    const requestedId = typeof req.body?.recoveryId === 'string' ? req.body.recoveryId : undefined
+    const meta = createPromptDraft(requestedId)
+    res.json({ draftId: meta.draftId, recoveryId: requestedId ?? meta.draftId, remapped: Boolean(requestedId && requestedId !== meta.draftId), expiresAt: meta.expiresAt, status: meta.status })
+  } catch (err: any) {
+    if (err instanceof MaintenanceLifecycleError) {
+      if (err.retryAfterSeconds != null) res.setHeader('Retry-After', String(err.retryAfterSeconds))
+      res.status(err.status).json(maintenanceErrorPayload(err))
+      return
+    }
+    res.status(err.status ?? 500).json({ error: err.message })
+  } finally {
+    maintenanceLease?.release()
+  }
 })
 
 promptDraftsRouter.post('/prompt-drafts/:draftId/chunks', async (req, res) => {
+  let maintenanceLease: MaintenanceWorkLease | undefined
   try {
     const raw = Array.isArray(req.query.chunkIndex) ? req.query.chunkIndex[0] : req.query.chunkIndex
     const chunkIndex = Number(raw)
     if (!Number.isInteger(chunkIndex) || chunkIndex < 0 || chunkIndex >= MAX_CHUNKS) return res.status(400).json({ error: 'invalid chunkIndex' })
-    const audio = await readRawBody(req)
-    if (audio.length < 44) return res.status(400).json({ error: 'audio too short' })
     const before = loadPromptDraftMeta(req.params.draftId)
     if (!before) return res.status(404).json({ error: 'draft not found' })
+    maintenanceLease = acquireMaintenanceWork('prompt_draft_write')
+    const audio = await readRawBody(req)
+    if (audio.length < 44) return res.status(400).json({ error: 'audio too short' })
     const existingBytes = before.chunkBytes[String(chunkIndex)] ?? 0
     const nextTotal = Object.values(before.chunkBytes).reduce((sum, bytes) => sum + bytes, 0) - existingBytes + audio.length
     if (nextTotal > MAX_DRAFT_BYTES) return res.status(413).json({ error: 'prompt draft too large' })
     const meta = await savePromptDraftChunk(req.params.draftId, chunkIndex, audio)
+    const warmLease = acquireMaintenanceWork('prompt_draft_warm', {
+      allowDuringDrain: true,
+      phase: 'queued',
+    })
     warmTail = warmTail.then(async () => {
+      warmLease.setPhase('active')
       const text = await transcribeChunk(req.params.draftId, chunkIndex, audio, 'fast', 'warm')
       // The durability ACK above remains immediate. Publish the optional warm
       // transcript only after rechecking that this exact audio still owns the
@@ -247,10 +282,16 @@ promptDraftsRouter.post('/prompt-drafts/:draftId/chunks', async (req, res) => {
       })
     }).catch(err => {
       console.warn(`[prompt-draft] warm transcription failed ${req.params.draftId}/${chunkIndex}: ${err.message}`)
-    })
+    }).finally(() => warmLease.release())
     res.json({ draftId: meta.draftId, chunkIndex, acked: true, receivedChunkIndexes: meta.receivedChunkIndexes, chunkBytes: meta.chunkBytes[String(chunkIndex)] ?? audio.length, transcriptPending: true, expiresAt: meta.expiresAt })
   } catch (err: any) {
+    if (err instanceof MaintenanceLifecycleError) {
+      if (err.retryAfterSeconds != null) res.setHeader('Retry-After', String(err.retryAfterSeconds))
+      return void res.status(err.status).json(maintenanceErrorPayload(err))
+    }
     res.status(err.status ?? (err.message === 'draft not found' ? 404 : 500)).json({ error: err.message })
+  } finally {
+    maintenanceLease?.release()
   }
 })
 
@@ -262,7 +303,9 @@ async function finalizeRequest(req: any, res: Response): Promise<void> {
     const key = `${req.params.draftId}:${mode}`
     let job = finalizeJobs.get(key)
     if (!job) {
+      const finalizeLease = acquireMaintenanceWork('prompt_draft_finalize')
       job = finalizeDraft(req.params.draftId, mode, routeAutoClean(req), abort.signal)
+        .finally(() => finalizeLease.release())
       finalizeJobs.set(key, job)
       job.finally(() => finalizeJobs.delete(key)).catch(() => {})
     }

package/server/routes/query.ts

@@ -9,6 +9,11 @@ import { normalizeEffortPreference, normalizeModelPreference } from '../../share
 import { QueryAttachmentError, resolveQueryAttachments } from '../lib/query-attachments.js'
 import { getMediaStore } from '../lib/media-store.js'
 import { mergeMediaAttachmentRefs } from '../../shared/media-attachment.js'
+import {
+  acquireMaintenanceWork,
+  MaintenanceLifecycleError,
+  maintenanceErrorPayload,
+} from '../lib/maintenance-lifecycle.js'
 
 const TOOL_STATUS_MESSAGES: Record<string, string> = {
   WebSearch: 'Searching web...',
@@ -19,6 +24,16 @@ const TOOL_STATUS_MESSAGES: Record<string, string> = {
 export const queryRouter = Router()
 
 queryRouter.post('/query', async (req, res) => {
+  let maintenanceLease
+  try {
+    maintenanceLease = acquireMaintenanceWork('legacy_query')
+  } catch (error) {
+    if (error instanceof MaintenanceLifecycleError) {
+      if (error.retryAfterSeconds != null) res.setHeader('Retry-After', String(error.retryAfterSeconds))
+      return res.status(error.status).json(maintenanceErrorPayload(error))
+    }
+    throw error
+  }
   const { query, sessionId, model, effort, reference, globalMsgNum } = req.body
   const activityToolMode = req.body.activityToolMode === 'off' || req.body.activityToolMode === 'preview'
     ? req.body.activityToolMode
@@ -31,8 +46,10 @@ queryRouter.post('/query', async (req, res) => {
     resolvedAttachments = await resolveQueryAttachments(req.body)
   } catch (err) {
     if (err instanceof QueryAttachmentError) {
+      maintenanceLease.release()
       return res.status(err.status).json({ error: err.code, detail: err.message })
     }
+    maintenanceLease.release()
     return res.status(500).json({ error: errMsg(err) })
   }
   const imageInputs = resolvedAttachments.inputs.length > 0 ? resolvedAttachments.inputs : undefined
@@ -42,6 +59,7 @@ queryRouter.post('/query', async (req, res) => {
 
   // Vision queries can have an empty query (default to "describe what you see")
   if ((!resolvedQuery || typeof resolvedQuery !== 'string') && !imageInputs) {
+    maintenanceLease.release()
     return res.status(400).json({ error: 'query string or image required' })
   }
 
@@ -107,34 +125,43 @@ queryRouter.post('/query', async (req, res) => {
           }
         },
       } : {}),
-      onDone: (fullText, model, cliSessionId, metadata) => {
-        // Durable association is independent of the SSE socket. Backgrounding
-        // the phone cannot leave request media reserved until expiry.
-        if (resolvedAttachments.ids.length > 0) {
-          getMediaStore().associate(resolvedAttachments.ids, {
-            sessionId: sid,
-            ...(validGlobalMsgNum ? { globalMsgNum: validGlobalMsgNum } : {}),
-          }).catch((err) => console.error('[query] attachment association failed:', err))
-        }
-        if (!done) {
-          done = true
-          const attachments = mergeMediaAttachmentRefs(attachmentRefs, metadata?.outputAttachments)
-          const { outputAttachments: _outputAttachments, ...runMetadata } = metadata ?? {}
-          const payload = {
-            text: fullText, sessionId: sid, model, cliSessionId, ...runMetadata,
-            ...(attachments.length > 0 ? { attachments } : {}),
+      onDone: async (fullText, model, cliSessionId, metadata) => {
+        try {
+          // Durable association is independent of the SSE socket.
+          // Backgrounding the phone cannot leave request media reserved until
+          // expiry or make maintenance proof outrun the pending write.
+          if (resolvedAttachments.ids.length > 0) {
+            await getMediaStore().associate(resolvedAttachments.ids, {
+              sessionId: sid,
+              ...(validGlobalMsgNum ? { globalMsgNum: validGlobalMsgNum } : {}),
+            }).catch((err) => console.error('[query] attachment association failed:', err))
           }
-          res.write(`event: done\ndata: ${JSON.stringify(payload)}\n\n`)
-          emitDisplay({ type: 'done', data: payload })
-          res.end()
+          if (!done) {
+            done = true
+            const attachments = mergeMediaAttachmentRefs(attachmentRefs, metadata?.outputAttachments)
+            const { outputAttachments: _outputAttachments, ...runMetadata } = metadata ?? {}
+            const payload = {
+              text: fullText, sessionId: sid, model, cliSessionId, ...runMetadata,
+              ...(attachments.length > 0 ? { attachments } : {}),
+            }
+            res.write(`event: done\ndata: ${JSON.stringify(payload)}\n\n`)
+            emitDisplay({ type: 'done', data: payload })
+            res.end()
+          }
+        } finally {
+          maintenanceLease.release()
         }
       },
       onError: (error) => {
-        if (!done) {
-          done = true
-          res.write(`event: error\ndata: ${JSON.stringify({ error })}\n\n`)
-          emitDisplay({ type: 'error', data: { error } })
-          res.end()
+        try {
+          if (!done) {
+            done = true
+            res.write(`event: error\ndata: ${JSON.stringify({ error })}\n\n`)
+            emitDisplay({ type: 'error', data: { error } })
+            res.end()
+          }
+        } finally {
+          maintenanceLease.release()
         }
       },
     }, validModel, imageInputs,
@@ -146,6 +173,7 @@ queryRouter.post('/query', async (req, res) => {
       { abortSignal: abortController.signal, effort: validEffort },
     )
   } catch (err: unknown) {
+    maintenanceLease.release()
     if (!done) {
       done = true
       res.write(`event: error\ndata: ${JSON.stringify({ error: errMsg(err) })}\n\n`)

package/server/routes/transcribe-stream.ts

@@ -43,6 +43,11 @@ import {
   type IndexRange,
 } from '../lib/local-first-meetings-contract.js'
 import { getServerInstanceId } from '../lib/server-instance-id.js'
+import {
+  acquireMaintenanceWork,
+  maintenanceAdmissionsOpen,
+  type MaintenanceWorkLease,
+} from '../lib/maintenance-lifecycle.js'
 
 function ensurePrivateDirectory(path: string): void {
   if (!existsSync(path)) mkdirSync(path, { recursive: true, mode: 0o700 })
@@ -264,6 +269,12 @@ interface StreamChunkCompletionResponse {
 
 const closedSessionRecords = new Map<string, ClosedTranscriptSession>()
 
+/** Conservative lifecycle count used by the local service manager. A restart
+ * is unsafe while any live transcription session owns audio state. */
+export function getActiveTranscriptionSessionCount(): number {
+  return sessions.size
+}
+
 // Incremental chunk persistence — survive server restarts
 const CHUNK_PERSIST_DIR = dataPath('active-sessions')
 ensurePrivateDirectory(CHUNK_PERSIST_DIR)
@@ -600,12 +611,17 @@ export function isSessionDeleted(sessionId: string): boolean {
   return deletedSessions.has(sessionId)
 }
 
-// Recover any sessions from prior server instance.
-recoverClosedSessions()
-recoverSessions()
+// A committed cross-boot maintenance operation owns durable state until the
+// trusted controller adopts the candidate. Boot recovery must not mutate or
+// promote sessions while that gate is closed.
+if (maintenanceAdmissionsOpen()) {
+  recoverClosedSessions()
+  recoverSessions()
+}
 
 // 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) {
@@ -1550,10 +1566,14 @@ function sendStreamError(res: { status: (code: number) => { json: (body: unknown
 }
 
 transcribeStreamRouter.post('/transcribe-stream', async (req, res) => {
+  let maintenanceLease: MaintenanceWorkLease | undefined
   try {
     // Reject a wrong Mac before consuming or persisting any upload bytes.
     assertPinnedServerIdentity(req.get('X-COS-Server-Instance'), req.query.serverInstanceId)
     const sessionId = (req.query.sessionId as string) || `g2_${Date.now()}`
+    maintenanceLease = acquireMaintenanceWork('recording_chunk', {
+      allowDuringDrain: sessions.has(sessionId),
+    })
     const chunkIndex = parseInt((req.query.chunkIndex as string) || '0', 10)
     const clientSpeaker = (req.query.speaker as string) || 'Unknown'
     const clientElapsedRaw = Number(req.query.elapsed)
@@ -1575,15 +1595,21 @@ transcribeStreamRouter.post('/transcribe-stream', async (req, res) => {
     }))
   } catch (err: unknown) {
     sendStreamError(res, err)
+  } finally {
+    maintenanceLease?.release()
   }
 })
 
 transcribeStreamRouter.post('/transcribe-stream/offline-sessions/start', async (req, res) => {
+  let maintenanceLease: MaintenanceWorkLease | undefined
   try {
     if (!isIosAsrCandidateEnabled()) throw makeHttpError(403, 'iPhone ASR candidates disabled', 'iphone_asr_disabled')
     const body = req.body ?? {}
     const sessionId = String(body.sessionId ?? '')
     validateSessionId(sessionId)
+    maintenanceLease = acquireMaintenanceWork('recording_chunk', {
+      allowDuringDrain: sessions.has(sessionId),
+    })
     if (isSessionDeleted(sessionId)) throw makeHttpError(410, 'session is closed', 'session_closed')
     const session = getSession(sessionId)
     const startTime = typeof body.startTime === 'number' && Number.isFinite(body.startTime)
@@ -1596,14 +1622,20 @@ transcribeStreamRouter.post('/transcribe-stream/offline-sessions/start', async (
     res.json({ sessionId, startTime: session.startTime, chunks: session.chunks.filter(Boolean).length })
   } catch (err: unknown) {
     sendStreamError(res, err)
+  } finally {
+    maintenanceLease?.release()
   }
 })
 
 transcribeStreamRouter.post('/transcribe-stream/offline-sessions/:sessionId/chunks', async (req, res) => {
+  let maintenanceLease: MaintenanceWorkLease | undefined
   try {
     if (!isIosAsrCandidateEnabled()) throw makeHttpError(403, 'iPhone ASR candidates disabled', 'iphone_asr_disabled')
     const sessionId = String(req.params.sessionId ?? '')
     validateSessionId(sessionId)
+    maintenanceLease = acquireMaintenanceWork('recording_chunk', {
+      allowDuringDrain: sessions.has(sessionId),
+    })
     if (isSessionDeleted(sessionId)) throw makeHttpError(410, 'session is closed', 'session_closed')
     const body = req.body ?? {}
     const chunkIndex = Number(body.chunkIndex)
@@ -1636,14 +1668,20 @@ transcribeStreamRouter.post('/transcribe-stream/offline-sessions/:sessionId/chun
     res.json({ ...result, offlineReplay: true })
   } catch (err: unknown) {
     sendStreamError(res, err)
+  } finally {
+    maintenanceLease?.release()
   }
 })
 
 transcribeStreamRouter.post('/transcribe-stream/offline-sessions/:sessionId/finalize', async (req, res) => {
+  let maintenanceLease: MaintenanceWorkLease | undefined
   try {
     if (!isIosAsrCandidateEnabled()) throw makeHttpError(403, 'iPhone ASR candidates disabled', 'iphone_asr_disabled')
     const sessionId = String(req.params.sessionId ?? '')
     validateSessionId(sessionId)
+    maintenanceLease = acquireMaintenanceWork('recording_chunk', {
+      allowDuringDrain: sessions.has(sessionId),
+    })
     if (isSessionDeleted(sessionId)) throw makeHttpError(410, 'session is closed', 'session_closed')
     const chunks = getSessionChunks(sessionId)
     if (!chunks || chunks.length === 0) throw makeHttpError(404, 'offline session has no chunks', 'session_not_found')
@@ -1662,16 +1700,22 @@ transcribeStreamRouter.post('/transcribe-stream/offline-sessions/:sessionId/fina
     })
   } catch (err: unknown) {
     sendStreamError(res, err)
+  } finally {
+    maintenanceLease?.release()
   }
 })
 
 transcribeStreamRouter.post('/transcribe-stream/candidates', async (req, res) => {
+  let maintenanceLease: MaintenanceWorkLease | undefined
   try {
     if (!isIosAsrCandidateEnabled()) throw makeHttpError(403, 'iPhone ASR candidates disabled', 'iphone_asr_disabled')
     const body = req.body ?? {}
     const sessionId = String(body.sessionId ?? '')
     const chunkIndex = Number(body.chunkIndex)
     validateSessionId(sessionId)
+    maintenanceLease = acquireMaintenanceWork('recording_chunk', {
+      allowDuringDrain: sessions.has(sessionId),
+    })
     validateChunkIndex(chunkIndex)
     if (isSessionDeleted(sessionId)) throw makeHttpError(410, 'session is closed', 'session_closed')
     if (chunkIndex > 0 && !sessions.has(sessionId)) {
@@ -1702,6 +1746,8 @@ transcribeStreamRouter.post('/transcribe-stream/candidates', async (req, res) =>
     res.json(result)
   } catch (err: unknown) {
     sendStreamError(res, err)
+  } finally {
+    maintenanceLease?.release()
   }
 })
 

package/server/routes/transcribe.ts

@@ -11,6 +11,12 @@ import {
   OpenAIWhisperBudgetExhaustedError,
   TranscriptionUnavailableError,
 } from '../lib/transcribe-audio.js'
+import {
+  acquireMaintenanceWork,
+  MaintenanceLifecycleError,
+  maintenanceErrorPayload,
+  type MaintenanceWorkLease,
+} from '../lib/maintenance-lifecycle.js'
 
 export const transcribeRouter = Router()
 
@@ -23,7 +29,9 @@ function resolveMode(req: { body?: { mode?: string }; query?: { mode?: string |
 
 // Accept raw binary body up to 25MB (Whisper limit).
 transcribeRouter.post('/transcribe', async (req, res) => {
+  let maintenanceLease: MaintenanceWorkLease | undefined
   try {
+    maintenanceLease = acquireMaintenanceWork('one_shot_transcription')
     const chunks: Buffer[] = []
     for await (const chunk of req) {
       chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
@@ -38,6 +46,10 @@ transcribeRouter.post('/transcribe', async (req, res) => {
     console.log(`[perf] /transcribe: ${result.elapsedMs.toFixed(1)}ms | mode=${result.mode} | ${result.backend} | ${result.audioBytes}b | ${result.text.length} chars`)
     res.json({ text: result.text, backend: result.backend, mode: result.mode })
   } catch (err: any) {
+    if (err instanceof MaintenanceLifecycleError) {
+      if (err.retryAfterSeconds != null) res.setHeader('Retry-After', String(err.retryAfterSeconds))
+      return res.status(err.status).json(maintenanceErrorPayload(err))
+    }
     if (err instanceof NoSpeechDetectedError) {
       console.log(`[perf] /transcribe: DROPPED (hallucination or empty): ${err.rawText.length} chars`)
       return res.status(204).send()
@@ -60,5 +72,7 @@ transcribeRouter.post('/transcribe', async (req, res) => {
       })
     }
     res.status(500).json({ error: err.message })
+  } finally {
+    maintenanceLease?.release()
   }
 })