@gotcos/glasses-server 6.12.7 → 6.14.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/prompt-edit.ts

@@ -0,0 +1,33 @@
+import { Router } from 'express'
+import {
+  PromptEditValidationError,
+  applyPromptEdit,
+  normalizePromptEditInput,
+} from '../lib/prompt-edit.js'
+import { errMsg } from '../lib/utils.js'
+
+export const promptEditRouter = Router()
+
+promptEditRouter.post('/prompt-edit', async (req, res) => {
+  const abort = new AbortController()
+  // Abort the model spawn ONLY if the client disconnects before we respond.
+  // Must listen on `res`, not `req`: express.json() fully drains the request
+  // body stream before this handler runs, so `req` emits 'close' on the next
+  // tick and would abort EVERY edit mid-flight (instant 500 "Prompt edit
+  // aborted"). `res` 'close' + !writableEnded fires only on a genuine premature
+  // disconnect. (House pattern: see routes/query.ts.)
+  res.on('close', () => {
+    if (!res.writableEnded) abort.abort()
+  })
+  try {
+    const input = normalizePromptEditInput(req.body)
+    const revisedText = await applyPromptEdit(input, abort.signal)
+    res.json({ revisedText })
+  } catch (err) {
+    if (err instanceof PromptEditValidationError) {
+      res.status(err.status).json({ error: err.message })
+      return
+    }
+    res.status(500).json({ error: errMsg(err) })
+  }
+})

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/recovery.ts

@@ -0,0 +1,76 @@
+import { Router } from 'express'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { atomicWriteFileSync } from '../lib/atomic-fs.js'
+import { acquireMaintenance, getRecoveryActivityStatus } from '../lib/recovery-activity.js'
+import { getWhisperHealth, restartWhisperServer } from '../lib/whisper-local.js'
+import { serverMetrics } from '../lib/server-metrics.js'
+
+export const recoveryRouter = Router()
+const COOLDOWN_MS = 60_000
+const cooldownPath = resolve(import.meta.dirname, '../data/.recovery_restart.json')
+
+function lastRestartAt(): number {
+  try { return Number(JSON.parse(readFileSync(cooldownPath, 'utf8'))?.at) || 0 } catch { return 0 }
+}
+
+recoveryRouter.get('/live', (_req, res) => {
+  res.setHeader('Cache-Control', 'no-store')
+  res.json({
+    status: 'ok', bootId: serverMetrics.bootId, pid: process.pid,
+    uptimeSeconds: Math.round((Date.now() - serverMetrics.startedAt) / 1000),
+    managed: process.env.COS_HARNESS === 'daemon',
+  })
+})
+
+recoveryRouter.get('/recovery/status', (_req, res) => {
+  res.json({
+    bootId: serverMetrics.bootId,
+    managed: process.env.COS_HARNESS === 'daemon',
+    whisper: getWhisperHealth(),
+    asr: { hqActive: false, hqQueued: 0, fastRestarting: false }, // public build: no HQ/fast ASR scheduler in this server
+    activity: getRecoveryActivityStatus(),
+  })
+})
+
+recoveryRouter.post('/recovery/whisper/restart', async (_req, res) => {
+  const gate = acquireMaintenance()
+  if (!gate.ok) {
+    gate.release()
+    return res.status(409).json({ error: 'Recovery blocked by active work', reason: 'recovery_busy', busy: gate.busy })
+  }
+  try {
+    const result = await restartWhisperServer()
+    res.status(result.status === 'failed' ? 503 : 200).json(result)
+  } finally { gate.release() }
+})
+
+recoveryRouter.post('/recovery/server/restart', (_req, res) => {
+  if (process.env.COS_HARNESS !== 'daemon') {
+    return res.status(409).json({ error: 'Server is not managed by the COS LaunchAgent', reason: 'restart_unmanaged' })
+  }
+  const elapsed = Date.now() - lastRestartAt()
+  if (elapsed < COOLDOWN_MS) {
+    return res.status(429).json({ error: 'Restart cooldown active', reason: 'restart_cooldown', retryAfterMs: COOLDOWN_MS - elapsed })
+  }
+  const gate = acquireMaintenance()
+  if (!gate.ok) {
+    gate.release()
+    return res.status(409).json({ error: 'Restart blocked by active work', reason: 'recovery_busy', busy: gate.busy })
+  }
+  atomicWriteFileSync(cooldownPath, JSON.stringify({ at: Date.now(), bootId: serverMetrics.bootId }))
+  res.status(202).json({ accepted: true, oldBootId: serverMetrics.bootId })
+  // Schedule independently of the response socket. The phone may change
+  // network/close the sheet immediately after receiving 202; that must not
+  // cancel an accepted restart or strand maintenance forever.
+  const timer = setTimeout(() => {
+    if (process.env.COS_DISABLE_SELF_RESTART === '1') { gate.release(); return }
+    try {
+      process.kill(process.pid, 'SIGTERM')
+    } catch (error) {
+      gate.release()
+      console.error('[recovery] Failed to signal managed server restart:', error)
+    }
+  }, 350)
+  timer.unref?.()
+})