@gotcos/glasses-server 6.13.0 → 6.14.1

package/server/lib/whisper-local.ts

@@ -42,9 +42,8 @@ export interface WhisperSegment {
   words?: WhisperWord[]
 }
 
-interface WhisperVerboseResponse {
-  text: string
-  segments?: WhisperSegment[]
+interface WhisperJsonResponse {
+  text?: unknown
 }
 
 // Resolve whisper.cpp binaries across Homebrew prefixes (Apple Silicon
@@ -144,6 +143,7 @@ let cliAvailable = false
 let serverAvailable = false
 let serverProcess: ReturnType<typeof spawn> | null = null
 const ownedServerChildren = new Set<ChildProcess>()
+const ownedHqChildren = new Set<ReturnType<typeof spawn>>()
 
 // Circuit breaker: track consecutive server failures to detect hung process
 let serverConsecutiveFailures = 0
@@ -389,7 +389,9 @@ async function startWhisperServerAttempt(preflightCompleted = false): Promise<vo
   console.log('[whisper-local] Starting whisper-server...')
 
   const child = spawn(WHISPER_SERVER, serverArgs, {
-    stdio: ['ignore', 'pipe', 'pipe'],
+    // whisper-server writes per-inference diagnostics. Unread pipes eventually
+    // fill and block the daemon, so the supervisor must not leave them buffered.
+    stdio: 'ignore',
     detached: false,  // Dies with parent
   })
   serverProcess = child
@@ -455,6 +457,10 @@ export function stopWhisperServer(): void {
     serverAvailable = false
     console.log('[whisper-local] whisper-server stopped')
   }
+  for (const proc of ownedHqChildren) {
+    try { proc.kill('SIGKILL') } catch { /* already exited */ }
+  }
+  ownedHqChildren.clear()
 }
 
 export function isWhisperLocalAvailable(): boolean {
@@ -523,7 +529,11 @@ async function reconcileWhisperServerHealth(): Promise<boolean> {
  * Falls back to turbo weights if large-v3 not on disk or COS_BATCH_LARGE_V3=0.
  * Falls back to transcribeLocal if whisper-cli unavailable entirely.
  */
-export async function transcribeHighQuality(audioBuffer: Buffer, context?: string): Promise<{ text: string; words?: WhisperWord[] }> {
+export async function transcribeHighQuality(
+  audioBuffer: Buffer,
+  context?: string,
+  opts: { priority?: 'interactive' | 'batch' } = {},
+): Promise<{ text: string; words?: WhisperWord[] }> {
   if (!cliAvailable) {
     // Fall back to server (no beam search available via HTTP API)
     return transcribeLocal(audioBuffer, context)
@@ -541,12 +551,13 @@ export async function transcribeHighQuality(audioBuffer: Buffer, context?: strin
     writeFileSync(tmpWav, audioBuffer)
 
     const text = await new Promise<string>((resolve, reject) => {
+      const isolateBatchFromLiveMetal = opts.priority === 'batch'
       const args = [
         '-m', modelPath,
         '-f', tmpWav,
-        '-t', '16',           // Use more threads for batch (no real-time pressure)
+        '-t', isolateBatchFromLiveMetal ? '8' : '16',
         '-l', 'en',
-        '-fa',                // Flash attention — Metal win, same flag streaming uses
+        ...(isolateBatchFromLiveMetal ? ['-ng'] : ['-fa']),
         '-bs', '5',           // Beam search width 5 (default disabled)
         '-bo', '5',           // Best-of-5 candidates (default 2)
         '--no-timestamps',
@@ -562,6 +573,7 @@ export async function transcribeHighQuality(audioBuffer: Buffer, context?: strin
       const proc = spawn(WHISPER_CLI, args, {
         stdio: ['ignore', 'pipe', 'pipe'],
       })
+      ownedHqChildren.add(proc)
 
       let stdout = ''
       let stderr = ''
@@ -573,13 +585,24 @@ export async function transcribeHighQuality(audioBuffer: Buffer, context?: strin
       // multiplier × beam-search overhead = ~240s safety ceiling for HQ.
       // Turbo retains the old 60s ceiling.
       const timeoutMs = useLargeV3 ? 240_000 : 60_000
+      let timedOut = false
+      let forceKill: ReturnType<typeof setTimeout> | null = null
       const timeout = setTimeout(() => {
-        proc.kill('SIGTERM')
-        reject(new Error(`whisper-cli HQ timeout (${timeoutMs / 1000}s, model=${useLargeV3 ? 'large-v3' : 'turbo'})`))
+        timedOut = true
+        try { proc.kill('SIGTERM') } catch { /* already exited */ }
+        forceKill = setTimeout(() => {
+          try { proc.kill('SIGKILL') } catch { /* already exited */ }
+        }, 2_000)
       }, timeoutMs)
 
       proc.on('close', (code) => {
+        ownedHqChildren.delete(proc)
         clearTimeout(timeout)
+        if (forceKill) clearTimeout(forceKill)
+        if (timedOut) {
+          reject(new Error(`whisper-cli HQ timeout (${timeoutMs / 1000}s, model=${useLargeV3 ? 'large-v3' : 'turbo'})`))
+          return
+        }
         if (code !== 0) {
           reject(new Error(`whisper-cli HQ exit ${code}: ${stderr.trim().slice(0, 200)}`))
           return
@@ -588,7 +611,9 @@ export async function transcribeHighQuality(audioBuffer: Buffer, context?: strin
       })
 
       proc.on('error', (err) => {
+        ownedHqChildren.delete(proc)
         clearTimeout(timeout)
+        if (forceKill) clearTimeout(forceKill)
         reject(new Error(`whisper-cli HQ spawn error: ${err.message}`))
       })
     })
@@ -626,14 +651,17 @@ function buildPrompt(context?: string, isQuiet?: boolean): string {
 
 /**
  * Transcribe via whisper-server (persistent daemon, ~50-100ms).
- * Returns text + optional word-level timestamps from DTW alignment.
+ *
+ * Compact JSON intentionally avoids whisper.cpp's verbose_json language field,
+ * which can receive a null C string after VAD returns no speech and crash the
+ * native server before an HTTP response exists.
  */
 async function transcribeViaServer(audioBuffer: Buffer, context?: string, isQuiet?: boolean): Promise<{ text: string; words?: WhisperWord[] }> {
   const formData = new FormData()
   // Convert Buffer to Uint8Array to satisfy Blob's BlobPart type constraint
   const blob = new Blob([new Uint8Array(audioBuffer)], { type: 'audio/wav' })
   formData.append('file', blob, 'recording.wav')
-  formData.append('response_format', 'verbose_json')  // includes segments[].words[] with DTW
+  formData.append('response_format', 'json')
   formData.append('prompt', buildPrompt(context, isQuiet))
   // Anti-hallucination handled by client-side filter + context filtering.
   // Whisper-level entropy/logprob thresholds were too aggressive — silently dropped
@@ -650,20 +678,11 @@ async function transcribeViaServer(audioBuffer: Buffer, context?: string, isQuie
     throw new Error(`whisper-server ${response.status}: ${await response.text()}`)
   }
 
-  const result = await response.json() as WhisperVerboseResponse
-  const text = result.text?.trim() || ''
-
-  // Extract word-level timestamps from DTW-aligned segments (defensive — may be absent)
-  let words: WhisperWord[] | undefined
-  if (result.segments && result.segments.length > 0) {
-    const extracted = result.segments.flatMap(s => {
-      if (!s.words || !Array.isArray(s.words)) return []
-      return s.words.filter(w => typeof w.start === 'number' && typeof w.end === 'number')
-    })
-    if (extracted.length > 0) words = extracted
+  const result = await response.json() as WhisperJsonResponse
+  if (typeof result.text !== 'string') {
+    throw new Error('whisper-server returned invalid compact JSON: missing string text')
   }
-
-  return { text, words }
+  return { text: result.text.trim() }
 }
 
 /**

package/server/routes/bookmarks.ts

@@ -0,0 +1,59 @@
+// Bookmark endpoints — save/retrieve individual messages
+import { Router } from 'express'
+import { loadBookmarks, addBookmark, deleteBookmark, getBookmark } from '../lib/bookmarks.js'
+
+export const bookmarksRouter = Router()
+
+// GET /api/bookmarks — list all bookmarks (newest first)
+bookmarksRouter.get('/bookmarks', (_req, res) => {
+  const bookmarks = loadBookmarks()
+  // Return newest first
+  res.json({ bookmarks: [...bookmarks].reverse() })
+})
+
+// GET /api/bookmarks/:id — get a single bookmark
+bookmarksRouter.get('/bookmarks/:id', (req, res) => {
+  const id = parseInt(req.params.id, 10)
+  if (isNaN(id)) {
+    res.status(400).json({ error: 'Invalid bookmark ID' })
+    return
+  }
+  const bookmark = getBookmark(id)
+  if (!bookmark) {
+    res.status(404).json({ error: 'Bookmark not found' })
+    return
+  }
+  res.json(bookmark)
+})
+
+// POST /api/bookmarks — save a new bookmark (optional attachment refs)
+bookmarksRouter.post('/bookmarks', (req, res) => {
+  const { query, text, messageIndex, originalTimestamp, attachments } = req.body
+  if (!query || !text) {
+    res.status(400).json({ error: 'query and text are required' })
+    return
+  }
+  const bookmark = addBookmark(
+    query,
+    text,
+    messageIndex ?? 0,
+    originalTimestamp ?? Date.now(),
+    attachments,
+  )
+  res.json({ bookmark })
+})
+
+// DELETE /api/bookmarks/:id — delete a bookmark
+bookmarksRouter.delete('/bookmarks/:id', (req, res) => {
+  const id = parseInt(req.params.id, 10)
+  if (isNaN(id)) {
+    res.status(400).json({ error: 'Invalid bookmark ID' })
+    return
+  }
+  const deleted = deleteBookmark(id)
+  if (!deleted) {
+    res.status(404).json({ error: 'Bookmark not found' })
+    return
+  }
+  res.json({ deleted: true })
+})

package/server/routes/glossary.ts

@@ -0,0 +1,153 @@
+// Transcription glossary — runtime-editable positive vocabulary, exact
+// corrections, and negative cleanup rules. Persists into .cos-profile.json and
+// busts the profile + decoder caches so edits take effect WITHOUT a server
+// restart. Auto token-protected by the /api middleware (server/index.ts:124).
+//
+//   GET /api/transcription-glossary → { vocabulary, corrections, negative_rules }
+//   PUT /api/transcription-glossary → same shape; PARTIAL (any omitted field is
+//     left unchanged). whisper_corrections is stored as a JSON STRING in the
+//     profile (legacy decoder contract), so the route encodes/decodes it here.
+
+import { Router } from 'express'
+import { errMsg } from '../lib/utils.js'
+import {
+  getVocabulary,
+  getNegativeRules,
+  loadProfileField,
+  updateProfileFields,
+} from '../lib/profile.js'
+import { resetDecoderCaches } from '../lib/whisper-local.js'
+import { resetVocabEchoCache } from '../lib/hallucination-filter.js'
+import { validateNegativeRule } from '../lib/hallucination-filter.js'
+
+export const glossaryRouter = Router()
+
+const MAX_TERMS = 500
+const MAX_TERM_LEN = 100
+const MAX_RULES = 500
+
+// Positive vocab is injected into the Whisper decoder prompt; URLs/emails/paths
+// there induce ".com"/handle hallucinations on quiet audio — reject them.
+function looksLikeUrlEmailPath(s: string): boolean {
+  return /(?:https?:\/\/|www\.)/i.test(s)
+    || /@[\w.-]+\.\w/.test(s)
+    || /\.(?:com|net|org|io|ai|co|gov|edu|app|dev)\b/i.test(s)
+    || /[/\\]/.test(s)
+}
+
+function readCorrections(): Record<string, string> {
+  try {
+    const raw = loadProfileField('whisper_corrections', '')
+    if (!raw) return {}
+    const parsed = JSON.parse(raw)
+    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+      ? parsed as Record<string, string>
+      : {}
+  } catch {
+    return {}
+  }
+}
+
+function currentGlossary() {
+  return {
+    vocabulary: getVocabulary(),
+    corrections: readCorrections(),
+    negative_rules: getNegativeRules(),
+  }
+}
+
+// Serialize PUTs so two writers can't clobber the read-modify-write. (The RMW in
+// updateProfileFields is synchronous today, but this guards against future async
+// drift and satisfies the write-lock contract.)
+let putChain: Promise<unknown> = Promise.resolve()
+
+glossaryRouter.get('/transcription-glossary', (_req, res) => {
+  try {
+    res.json(currentGlossary())
+  } catch (err) {
+    res.status(500).json({ error: errMsg(err) })
+  }
+})
+
+glossaryRouter.put('/transcription-glossary', async (req, res) => {
+  const body = req.body ?? {}
+  const patch: Record<string, unknown> = {}
+
+  // ── vocabulary (positive spellings → decoder prompt + fuzzy targets) ──
+  if (body.vocabulary !== undefined) {
+    if (!Array.isArray(body.vocabulary)) {
+      return res.status(400).json({ error: 'vocabulary must be an array of strings' })
+    }
+    if (body.vocabulary.length > MAX_TERMS) {
+      return res.status(400).json({ error: `too many vocabulary terms (max ${MAX_TERMS})` })
+    }
+    const vocab: string[] = []
+    for (const raw of body.vocabulary) {
+      if (typeof raw !== 'string') return res.status(400).json({ error: 'vocabulary entries must be strings' })
+      const term = raw.trim()
+      if (!term) continue
+      if (term.length > MAX_TERM_LEN) return res.status(400).json({ error: `vocabulary term too long: "${term.slice(0, 40)}…"` })
+      if (looksLikeUrlEmailPath(term)) {
+        return res.status(400).json({ error: `vocabulary cannot contain URLs/emails/paths: "${term}" — they induce hallucinations in the decoder prompt` })
+      }
+      vocab.push(term)
+    }
+    patch.vocabulary = vocab
+  }
+
+  // ── corrections (bad → good) — persisted as a JSON STRING ──
+  if (body.corrections !== undefined) {
+    if (typeof body.corrections !== 'object' || body.corrections === null || Array.isArray(body.corrections)) {
+      return res.status(400).json({ error: 'corrections must be an object { "bad": "good" }' })
+    }
+    const entries = Object.entries(body.corrections as Record<string, unknown>)
+    if (entries.length > MAX_TERMS) return res.status(400).json({ error: `too many corrections (max ${MAX_TERMS})` })
+    const map: Record<string, string> = {}
+    for (const [bad, good] of entries) {
+      const b = bad.trim()
+      if (!b) continue
+      if (typeof good !== 'string') return res.status(400).json({ error: `correction "${bad}" must map to a string` })
+      if (b.length > MAX_TERM_LEN || good.length > MAX_TERM_LEN) {
+        return res.status(400).json({ error: `correction too long near "${b.slice(0, 40)}"` })
+      }
+      map[b] = good.trim()
+    }
+    patch.whisper_corrections = JSON.stringify(map)
+  }
+
+  // ── negative rules (whole/strip/replace/flag) ──
+  if (body.negative_rules !== undefined) {
+    if (!Array.isArray(body.negative_rules)) {
+      return res.status(400).json({ error: 'negative_rules must be an array of strings' })
+    }
+    if (body.negative_rules.length > MAX_RULES) {
+      return res.status(400).json({ error: `too many negative rules (max ${MAX_RULES})` })
+    }
+    const rules: string[] = []
+    for (const raw of body.negative_rules) {
+      if (typeof raw !== 'string') return res.status(400).json({ error: 'negative_rules entries must be strings' })
+      const v = validateNegativeRule(raw)
+      if (!v.ok) return res.status(400).json({ error: `invalid rule "${raw.slice(0, 60)}": ${v.error}` })
+      rules.push(raw)
+    }
+    patch.negative_rules = rules
+  }
+
+  if (Object.keys(patch).length === 0) {
+    return res.status(400).json({ error: 'nothing to update (send vocabulary, corrections, and/or negative_rules)' })
+  }
+
+  try {
+    // Cache-bust chain: updateProfileFields() writes atomically + clears the ROOT
+    // profileCache; resetDecoderCaches() clears the two derived decoder snapshots.
+    // Both are required for an edit to reach the decoder without a restart.
+    await (putChain = putChain.catch(() => {}).then(() => {
+      updateProfileFields(patch)
+      resetDecoderCaches()
+      resetVocabEchoCache()  // vocab matcher in hallucination-filter is profile-derived too
+    }))
+    return res.json(currentGlossary())
+  } catch (err) {
+    return res.status(500).json({ error: errMsg(err) })
+  }
+})

package/server/routes/handoffs.ts

@@ -0,0 +1,101 @@
+import { Router } from 'express'
+import {
+  buildHandoffPromptContext,
+  claimHandoff,
+  createHandoff,
+  getHandoff,
+  getLatestHandoff,
+  type HandoffCreateInput,
+} from '../lib/handoff-store.js'
+import { getAvailableCliSessionId } from '../lib/claude-bridge.js'
+import { getCodexExecutionCwd, getCodexTrustMode } from '../lib/codex-run-ledger.js'
+import { normalizeHandoffCode } from '../../shared/handoff-intent.js'
+
+export const handoffsRouter = Router()
+
+function runtimeExpiresAt(): string {
+  return new Date(Date.now() + 2 * 60 * 60_000).toISOString()
+}
+
+function enrichRuntime(body: Record<string, any>): HandoffCreateInput {
+  const input: HandoffCreateInput = { ...body }
+  const runtime = body.runtime && typeof body.runtime === 'object' ? { ...body.runtime } : {}
+
+  if (runtime.codex?.codexThreadId) {
+    runtime.codex = {
+      ...runtime.codex,
+      cwd: runtime.codex.cwd ?? getCodexExecutionCwd(),
+      trustMode: runtime.codex.trustMode ?? getCodexTrustMode(),
+      expiresAt: runtime.codex.expiresAt ?? runtimeExpiresAt(),
+    }
+  }
+
+  if (runtime.claude?.cliSessionId) {
+    runtime.claude = {
+      ...runtime.claude,
+      expiresAt: runtime.claude.expiresAt ?? runtimeExpiresAt(),
+    }
+  } else if (typeof body.sessionId === 'string') {
+    const cliSessionId = getAvailableCliSessionId(body.sessionId)
+    if (cliSessionId) {
+      runtime.claude = {
+        cliSessionId,
+        model: typeof body.model === 'string' ? body.model : undefined,
+        expiresAt: runtimeExpiresAt(),
+      }
+    }
+  }
+
+  if (runtime.codex || runtime.claude) input.runtime = runtime
+  return input
+}
+
+handoffsRouter.post('/handoffs', async (req, res) => {
+  try {
+    const body = req.body && typeof req.body === 'object' ? req.body : {}
+    const handoff = await createHandoff(enrichRuntime(body))
+    res.status(201).json({ handoff, context: buildHandoffPromptContext(handoff) })
+  } catch (err: any) {
+    res.status(500).json({ error: err?.message ?? 'handoff create failed' })
+  }
+})
+
+handoffsRouter.get('/handoffs/latest', async (req, res) => {
+  try {
+    const handoff = await getLatestHandoff({
+      source: typeof req.query.source === 'string' ? req.query.source : undefined,
+      target: typeof req.query.target === 'string' ? req.query.target : undefined,
+      createdBy: typeof req.query.createdBy === 'string' ? req.query.createdBy : undefined,
+      deviceId: typeof req.query.deviceId === 'string' ? req.query.deviceId : undefined,
+    })
+    if (!handoff) return res.status(404).json({ error: 'handoff not found' })
+    res.json({ handoff, context: buildHandoffPromptContext(handoff) })
+  } catch (err: any) {
+    res.status(500).json({ error: err?.message ?? 'handoff lookup failed' })
+  }
+})
+
+handoffsRouter.get('/handoffs/:code', async (req, res) => {
+  const code = normalizeHandoffCode(req.params.code)
+  if (!code) return res.status(404).json({ error: 'handoff not found' })
+  try {
+    const handoff = await getHandoff(code)
+    if (!handoff) return res.status(404).json({ error: 'handoff not found' })
+    res.json({ handoff, context: buildHandoffPromptContext(handoff) })
+  } catch (err: any) {
+    res.status(500).json({ error: err?.message ?? 'handoff lookup failed' })
+  }
+})
+
+handoffsRouter.post('/handoffs/:code/claim', async (req, res) => {
+  const code = normalizeHandoffCode(req.params.code)
+  if (!code) return res.status(404).json({ error: 'handoff not found' })
+  try {
+    const claimedBy = typeof req.body?.claimedBy === 'string' ? req.body.claimedBy : 'unknown'
+    const handoff = await claimHandoff(code, claimedBy)
+    if (!handoff) return res.status(404).json({ error: 'handoff not found' })
+    res.json({ handoff, context: buildHandoffPromptContext(handoff) })
+  } catch (err: any) {
+    res.status(500).json({ error: err?.message ?? 'handoff claim failed' })
+  }
+})

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/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?.()
+})