@gotcos/glasses-server 6.9.0 → 6.10.0

package/.env.example

@@ -28,6 +28,14 @@ BIND_HOST=0.0.0.0
 # server after Wi-Fi/Tailscale changes and process restarts.
 # COS_SERVER_INSTANCE_ID_PATH=/path/to/server-instance-id
 
+# Build 204+ can opt into server-owned durable query jobs. The server fsyncs an
+# accepted prompt before returning 202, then keeps provider work running if the
+# phone backgrounds, reloads, or changes networks. Reopening COS reattaches to
+# the same job. Set to 0 (or remove) to send NEW prompts through the legacy
+# streaming route; already accepted durable jobs remain readable/cancellable
+# and drain safely.
+# COS_DURABLE_QUERY_JOBS=1
+
 # ── THE LLM (chat) ──────────────────────────────────────────────────────
 # Chat runs through your LOCAL agent CLI — NOT an API key:
 #   Opus / Fable / Sonnet  ->  Claude Code CLI  (https://claude.ai/download, then `claude login`)

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 6.10.0
+
+Opt-in server-owned durable query jobs for COS Glasses build 204+.
+
+- **Accepted means durable.** With `COS_DURABLE_QUERY_JOBS=1`, the server
+  appends and fsyncs an immutable job before returning 202. Provider execution
+  is no longer owned by the phone's current request, WebView, or SSE subscriber.
+- **Reconnect without duplication.** The client can recover an ambiguous
+  admission by its stable client job ID, replay ordered bounded events, and
+  acknowledge one terminal projection idempotently after message, queue,
+  counter, and session state are durable on the phone.
+- **Crash and cancellation fences.** Provider ownership is persisted before
+  input, session-scoped leases prevent overlapping orphan continuations after a
+  restart, cancellation is durable, and answer-ready ownership gates
+  conversation, image, notification, and Done side effects.
+- **Private bounded storage.** The append-only journal uses private directory
+  and file modes, repairs torn tails, bounds progress/activity payloads, and
+  retains terminal jobs for exactly seven days.
+- **Safe rollout and rollback.** The health capability advertises exact protocol
+  version 1 only when configured and the store is ready. Removing the flag
+  blocks new durable admissions but leaves GET/events/cancel/ack available so
+  accepted jobs drain; legacy queries, first turns, handoffs, and older clients
+  remain unchanged.
+
 ## 6.9.0
 
 Live recoverable prompt transcription for COS Glasses builds 200+.

package/README.md

@@ -56,6 +56,10 @@ The built-in IP allowlist blocks public-internet traffic regardless.
 ## What it does
 
 - Ask anything, get a streamed answer on the lens (`/api/query`, `/v1/chat/completions`)
+- With COS Glasses build 204+, opt into server-owned durable queries with
+  `COS_DURABLE_QUERY_JOBS=1`: accepted work survives phone backgrounding,
+  WebView reloads, and network handoffs, then reattaches without duplicate work
+  or duplicate replies
 - Choose Opus, Fable, Sonnet, GPT Frontier, or GPT Balanced plus High, Extra
   High, Max, or Ultracode effort; optional redacted tool activity streams only
   to the authenticated query that requested it
@@ -78,7 +82,8 @@ The built-in IP allowlist blocks public-internet traffic regardless.
 Config lives at `~/.cos-glasses/.env` (created on first run). Every key is
 optional except an installed CLI. Highlights: `BIND_HOST`, `PORT`,
 `COS_API_TOKEN` (auto if unset), `OPENAI_API_KEY` (cloud voice fallback),
-`COS_SCRIPTS_DIR` (full pipeline), and `COS_MEDIA_ROOT` (optional image-store
+`COS_SCRIPTS_DIR` (full pipeline), `COS_DURABLE_QUERY_JOBS=1` (build 204+
+server-owned query recovery), and `COS_MEDIA_ROOT` (optional image-store
 location; default `~/.cos-glasses/data/media`). Your name + transcription vocabulary live in
 `~/.cos-glasses/.cos-profile.json` (see `.cos-profile.example.json`).
 
@@ -99,6 +104,10 @@ BIND_HOST=0.0.0.0 npm run start:server
 - *Voice getting billed?* — install `whisper-cpp` for free local transcription.
 - *Photos unavailable?* — install `ffmpeg`, restart the server, and confirm `/api/health` reports `features.mediaProcessingReady: true`.
 - *Prompt recovery unavailable?* — update with `npx @gotcos/glasses-server@latest`, then confirm `/api/health` reports `features.promptRecovery: true`.
+- *Durable query recovery unavailable?* — build 204+ requires server 6.10.0+ and
+  `COS_DURABLE_QUERY_JOBS=1`. Restart once, then confirm `/api/health` reports
+  `features.durableQueryJobs: true`, protocol `1`, and state `ready`. To roll
+  back, remove the flag; accepted jobs still drain while new prompts use legacy streaming.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.9.0",
+  "version": "6.10.0",
   "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by your local Claude Code or Codex CLI",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -43,6 +43,13 @@ import { getMediaStore } from './lib/media-store.js'
 import { listenRequiredServers, type RequiredListener } from './lib/listener-startup.js'
 import { serverMetrics } from './lib/server-metrics.js'
 import { initializeServerInstanceId } from './lib/server-instance-id.js'
+import { createQueryJobsRouter } from './routes/query-jobs.js'
+import {
+  initQueryJobRuntime,
+  preparePublicDurableQueryAdmission,
+  queryJobCoordinator,
+  shutdownQueryJobRuntime,
+} from './lib/query-job-runtime.js'
 
 const app = express()
 const PORT = parseInt(process.env.PORT ?? '3141', 10)
@@ -139,6 +146,9 @@ app.use((_req, _res, next) => {
 // API routes
 app.use('/api', healthRouter)
 app.use('/api', diagRouter)
+app.use('/api', createQueryJobsRouter(queryJobCoordinator, {
+  prepareAdmission: preparePublicDurableQueryAdmission,
+}))
 app.use('/api', queryRouter)
 app.use('/api', transcribeRouter)
 app.use('/api', displayRouter)
@@ -173,21 +183,28 @@ app.get('/', (_req, res) => {
   )
 })
 
-// Graceful shutdown — stop whisper-server child process
-process.on('SIGTERM', () => {
-  // Production stops (kill, service managers) send SIGTERM — flush session logs
-  // exactly like SIGINT so active conversations aren't lost on shutdown.
+// Graceful shutdown persists an interrupted terminal before provider abort.
+// The bounded force-exit keeps service managers from hanging forever on a
+// broken disk while retaining the previous session/catalog/Whisper cleanup.
+let gracefulShutdownStarted = false
+async function gracefulShutdown(): Promise<void> {
+  if (gracefulShutdownStarted) return
+  gracefulShutdownStarted = true
+  const forceExit = setTimeout(() => process.exit(1), 8_000)
+  forceExit.unref?.()
+  try {
+    await shutdownQueryJobRuntime('server_shutdown')
+  } catch (error) {
+    console.error('[query-jobs] graceful interruption failed:', error)
+  }
   try { logActiveSessionsOnShutdown() } catch { /* best-effort flush */ }
   stopCodexModelCatalogRefresh()
   stopWhisperServer()
+  clearTimeout(forceExit)
   process.exit(0)
-})
-process.on('SIGINT', () => {
-  logActiveSessionsOnShutdown()
-  stopCodexModelCatalogRefresh()
-  stopWhisperServer()
-  process.exit(0)
-})
+}
+process.on('SIGTERM', () => { void gracefulShutdown() })
+process.on('SIGINT', () => { void gracefulShutdown() })
 
 // Crash protection for runtime work. Listener failures are handled separately
 // and exit immediately so a supervisor can restart a clean, unified process.
@@ -228,6 +245,18 @@ listenRequiredServers(listeners).then(() => {
   console.log(`[COS API] Server instance: ${serverInstanceId}`)
   console.log(`[COS API] Mode: ${COS_MODE ? 'COS pipeline' : 'standalone'}`)
 
+  void initQueryJobRuntime().then(health => {
+    if (process.env.COS_DURABLE_QUERY_JOBS === '1') {
+      console.log(`[COS API] Durable query jobs: ${health.store.state} · ${health.store.retainedIdentities} retained`)
+    } else {
+      console.log('[COS API] Durable query jobs: disabled (set COS_DURABLE_QUERY_JOBS=1 to enable)')
+    }
+  }).catch(error => {
+    // The store remains degraded and rejects admission. Legacy /api/query is
+    // still mounted, so disabling the feature flag is an immediate rollback.
+    console.error('[COS API] Durable query-job store unavailable:', error)
+  })
+
   // Print ADDRESSES THE PHONE CAN ACTUALLY REACH. The bind address (0.0.0.0) is
   // not paste-able — enumerate real interfaces and label the Tailscale one.
   try {

package/server/lib/claude-bridge.ts

@@ -38,6 +38,7 @@ import {
   type ActivityPreviewLine,
 } from './activity-preview.js'
 import {
+  collectRunOutputImagesBounded,
   createRunOutputImagePublisher,
   isRunOutputImagePublisherCommand,
   type RunOutputImageCollectionStats,
@@ -291,19 +292,34 @@ function isExtendedQuery(query: string): boolean {
 }
 
 export interface ModelRunMetadata {
+  claudeRunId?: string
+  clientJobId?: string
+  generation?: number
   codexRunId?: string
   codexThreadId?: string
   outputAttachments?: MediaAttachmentRef[]
   outputImageStats?: RunOutputImageCollectionStats
 }
 
+/** Public-safe provider launch metadata for durable job coordination. It
+ * deliberately exposes no ChildProcess object, kill handle, paths, or env. */
+export interface ProviderProcessMetadata {
+  provider: 'claude' | 'codex'
+  runId: string
+  pid?: number
+  clientJobId?: string
+  generation?: number
+}
+
 export interface StreamCallbacks {
   onChunk: (text: string) => void
-  onDone: (fullText: string, model: ModelPreference, cliSessionId?: string, metadata?: ModelRunMetadata) => void
-  onError: (error: string) => void
+  onAnswerReady?: (fullText: string) => boolean | void | Promise<boolean | void>
+  onDone: (fullText: string, model: ModelPreference, cliSessionId?: string, metadata?: ModelRunMetadata) => boolean | void | Promise<boolean | void>
+  onError: (error: string) => void | Promise<void>
   onToolStatus?: (toolName: string) => void
   onActivityLine?: (line: ActivityPreviewLine) => void
   onStart?: (model: ModelPreference, sessionId: string, cliSessionId?: string, metadata?: ModelRunMetadata) => void
+  onProviderProcess?: (metadata: ProviderProcessMetadata) => boolean | void | Promise<boolean | void>
 }
 
 /** Claude CLI can emit `subtype: success` with `is_error: true`; the boolean
@@ -336,6 +352,10 @@ export interface CallOptions {
   lightweight?: boolean  // Skip async context fetch — use cached context instantly (G2 speed path)
   abortSignal?: AbortSignal
   effort?: EffortPreference
+  clientJobId?: string
+  generation?: number
+  /** Durable coordinator already owns the per-session provider lease. */
+  sessionLockHeld?: boolean
 }
 
 export async function callClaudeStreaming(
@@ -367,7 +387,10 @@ export async function callClaudeStreaming(
   // Pass existing CLI session ID if resuming (new sessions get it after first result)
   const resolvedCliKey = cliSessionKey(sid, resolvedModel)
   let existingCliSession = cliSessionMap.get(resolvedCliKey)
-  callbacks.onStart?.(resolvedModel, sid, existingCliSession)
+  callbacks.onStart?.(resolvedModel, sid, existingCliSession, {
+    clientJobId: options?.clientJobId,
+    generation: options?.generation,
+  })
 
   // Phase: context loading (skipped in lightweight mode)
   let phase: Phase = 'context'
@@ -414,7 +437,18 @@ export async function callClaudeStreaming(
   // Record user message (with [Photo]/[N Photos] prefix for vision queries)
   const photoPrefix = imagePaths.length === 1 ? '[Photo]' : imagePaths.length > 1 ? `[${imagePaths.length} Photos]` : ''
   const historyQuery = photoPrefix ? `${photoPrefix} ${query || 'What do you see?'}` : query
-  const pendingUserExchange = addExchange(sid, 'user', historyQuery, globalMsgNum)
+  const exchangeProvenance = {
+    clientJobId: options?.clientJobId,
+    generation: options?.generation,
+  }
+  const pendingUserExchange = addExchange(
+    sid,
+    'user',
+    historyQuery,
+    globalMsgNum,
+    undefined,
+    exchangeProvenance,
+  )
 
   // Vision queries need the Read tool to see the image files
   const baseTools = imagePaths.length > 0 ? 'WebSearch,WebFetch,Read' : 'WebSearch,WebFetch'
@@ -519,15 +553,62 @@ export async function callClaudeStreaming(
     cleanupModelImageInputs(imageInputs)
   }
 
+  function abandonLostDurableOwnership(message: string) {
+    finalized = true
+    cleanup()
+    cleanupImages()
+    outputImagePublisher?.cleanup()
+    removeExchange(sid, pendingUserExchange)
+    if (cliSessionMap.delete(resolvedCliKey)) scheduleCliSessionSave()
+    finishClaudeRun(run.runId, {
+      status: 'failed',
+      startedAtMs: startTime,
+      error: message,
+      exitCode: null,
+    })
+  }
+
   async function finalize(text: string) {
     if (finalized) return
     finalized = true
     cleanup()
     cleanupImages()
 
-    // Persist text before output-image normalization. A daemon crash during
-    // finalization cannot erase an otherwise successful answer.
-    const assistantExchange = addExchange(sid, 'assistant', text, globalMsgNum)
+    // The coordinator persists the final provider text before conversation
+    // mutation, condensation, or output-image normalization can stall/crash.
+    try {
+      const answerOwned = await callbacks.onAnswerReady?.(text)
+      if (answerOwned === false) {
+        abandonLostDurableOwnership('claude-bridge: durable answer ownership was lost.')
+        return
+      }
+    } catch (error) {
+      console.error('[claude-bridge] durable answer barrier failed:', error)
+      outputImagePublisher?.cleanup()
+      removeExchange(sid, pendingUserExchange)
+      if (cliSessionMap.delete(resolvedCliKey)) scheduleCliSessionSave()
+      finishClaudeRun(run.runId, {
+        status: 'failed',
+        startedAtMs: startTime,
+        error: 'claude-bridge: durable answer persistence failed.',
+        exitCode: null,
+      })
+      try {
+        await callbacks.onError('claude-bridge: durable answer persistence failed.')
+      } catch (callbackError) {
+        console.error('[claude-bridge] durable barrier error callback failed:', callbackError)
+      }
+      return
+    }
+
+    const assistantExchange = addExchange(
+      sid,
+      'assistant',
+      text,
+      globalMsgNum,
+      undefined,
+      exchangeProvenance,
+    )
     if (imagePaths.length > 0) {
       replaceLastExchangeWithSummary(sid, query, text, imagePaths.length)
     }
@@ -539,7 +620,9 @@ export async function callClaudeStreaming(
       const preparingHeartbeat = setInterval(() => callbacks.onToolStatus?.('Preparing images...'), HEARTBEAT_INTERVAL_MS)
       preparingHeartbeat.unref?.()
       try {
-        outputAttachments = await outputImagePublisher.collect()
+        outputAttachments = await collectRunOutputImagesBounded(outputImagePublisher, {
+          signal: options?.abortSignal,
+        })
       } catch (err) {
         console.error('[claude-bridge] output image collection failed:', err)
       } finally {
@@ -576,10 +659,14 @@ export async function callClaudeStreaming(
       exitCode: 0,
     })
 
-    callbacks.onDone(text, resolvedModel, cliSessionMap.get(resolvedCliKey), {
+    const terminalOwned = await callbacks.onDone(text, resolvedModel, cliSessionMap.get(resolvedCliKey), {
+      claudeRunId: run.runId,
+      clientJobId: options?.clientJobId,
+      generation: options?.generation,
       ...(outputAttachments.length > 0 ? { outputAttachments } : {}),
       ...(outputImageStats && outputImageStats.published > 0 ? { outputImageStats } : {}),
     })
+    if (terminalOwned === false) return
 
     // Telegram notifications — fire and forget
     if (isFirstQuery) {
@@ -589,7 +676,7 @@ export async function callClaudeStreaming(
     notifyExchange(sid, query, text)
   }
 
-  function finalizeError(
+  async function finalizeError(
     msg: string,
     exitCode?: number | null,
     status: Exclude<ClaudeRunStatus, 'running'> = 'failed',
@@ -610,7 +697,7 @@ export async function callClaudeStreaming(
       error: msg,
       exitCode,
     })
-    callbacks.onError(msg)
+    await callbacks.onError(msg)
   }
 
   function handleAbort() {
@@ -827,11 +914,27 @@ export async function callClaudeStreaming(
     ? `${fullQuery}\n\n${ULTRACODE_KEYWORD}`
     : fullQuery
   try {
+    const providerOwned = await callbacks.onProviderProcess?.({
+      provider: 'claude',
+      runId: run.runId,
+      pid: proc.pid,
+      clientJobId: options?.clientJobId,
+      generation: options?.generation,
+    })
+    if (providerOwned === false) {
+      proc.kill('SIGTERM')
+      abandonLostDurableOwnership('claude-bridge: durable provider ownership was lost.')
+      return sid
+    }
+    if (finalized) return sid
     proc.stdin.write(cliQuery)
     proc.stdin.end()
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err)
-    finalizeError(`claude-bridge: stdin failed — ${message}`, null)
+    if (!finalized) {
+      proc.kill('SIGTERM')
+      await finalizeError(`claude-bridge: provider start failed — ${message}`, null)
+    }
   }
 
   return sid

package/server/lib/codex-bridge.ts

@@ -51,6 +51,7 @@ import {
 } from './codex-run-ledger.js'
 import { codexActivityPreviewLines } from './activity-preview.js'
 import {
+  collectRunOutputImagesBounded,
   createRunOutputImagePublisher,
   isRunOutputImagePublisherCommand,
   type RunOutputImageCollectionStats,
@@ -283,7 +284,12 @@ export async function callCodexStreaming(
     }
   }
   let codexThreadId: string | undefined = engineSession?.codexThreadId
-  callbacks.onStart?.(model, sid, undefined, { codexRunId: run.runId, codexThreadId })
+  callbacks.onStart?.(model, sid, undefined, {
+    codexRunId: run.runId,
+    codexThreadId,
+    clientJobId: options?.clientJobId,
+    generation: options?.generation,
+  })
 
   let phase: Phase = 'context'
   let systemPrompt: string
@@ -312,7 +318,18 @@ export async function callCodexStreaming(
   const isFirstQuery = isNewSession(sid)
   const photoPrefix = imagePaths.length === 1 ? '[Photo]' : imagePaths.length > 1 ? `[${imagePaths.length} Photos]` : ''
   const historyQuery = photoPrefix ? `${photoPrefix} ${query || 'What do you see?'}` : query
-  const pendingUserExchange = addExchange(sid, 'user', historyQuery, globalMsgNum)
+  const exchangeProvenance = {
+    clientJobId: options?.clientJobId,
+    generation: options?.generation,
+  }
+  const pendingUserExchange = addExchange(
+    sid,
+    'user',
+    historyQuery,
+    globalMsgNum,
+    undefined,
+    exchangeProvenance,
+  )
 
   let fullQuery: string
   if (imagePaths.length === 1) {
@@ -363,6 +380,41 @@ export async function callCodexStreaming(
     options?.abortSignal?.removeEventListener('abort', handleAbort)
   }
 
+  function clearEngineSessionBestEffort(reason: string) {
+    if (!engineSession) return
+    try {
+      clearCodexEngineSession(sid, model)
+    } catch (error) {
+      console.error(`[codex-bridge] engine session clear failed (${reason}):`, error)
+    }
+  }
+
+  function saveEngineSessionBestEffort() {
+    if (!persistentCodexSession || !codexThreadId) return
+    try {
+      const saved = saveCodexEngineSession({
+        cosSessionId: sid,
+        model,
+        codexThreadId,
+        cwd: codexCwd,
+        trustMode: codexTrustMode,
+      })
+      updateCodexRun(run.runId, { codexThreadId, expiresAt: saved.expiresAt })
+    } catch (error) {
+      // The resumable-thread cache is an optimization. Its filesystem failure
+      // must never suppress the durable query terminal callback.
+      console.error('[codex-bridge] engine session save failed:', error)
+    }
+  }
+
+  function finishRunBestEffort(input: Parameters<typeof finishCodexRun>[1]) {
+    try {
+      finishCodexRun(run.runId, input)
+    } catch (error) {
+      console.error('[codex-bridge] run ledger finalization failed:', error)
+    }
+  }
+
   function emitText(text: string) {
     if (!text || emittedBlocks.has(text)) return
     emittedBlocks.add(text)
@@ -377,7 +429,49 @@ export async function callCodexStreaming(
     cleanup()
     cleanupImages()
 
-    const assistantExchange = addExchange(sid, 'assistant', text, globalMsgNum)
+    // The coordinator persists the final provider text before conversation
+    // mutation, condensation, or output-image normalization can stall/crash.
+    try {
+      const answerOwned = await callbacks.onAnswerReady?.(text)
+      if (answerOwned === false) {
+        outputImagePublisher?.cleanup()
+        removeExchange(sid, pendingUserExchange)
+        clearEngineSessionBestEffort('answer_ownership_lost')
+        finishRunBestEffort({
+          status: 'failed',
+          startedAtMs: startTime,
+          error: 'codex-bridge: durable answer ownership was lost.',
+          exitCode: null,
+        })
+        return
+      }
+    } catch (error) {
+      console.error('[codex-bridge] durable answer barrier failed:', error)
+      outputImagePublisher?.cleanup()
+      removeExchange(sid, pendingUserExchange)
+      clearEngineSessionBestEffort('answer_barrier')
+      finishRunBestEffort({
+        status: 'failed',
+        startedAtMs: startTime,
+        error: 'codex-bridge: durable answer persistence failed.',
+        exitCode: null,
+      })
+      try {
+        await callbacks.onError('codex-bridge: durable answer persistence failed.')
+      } catch (callbackError) {
+        console.error('[codex-bridge] durable barrier error callback failed:', callbackError)
+      }
+      return
+    }
+
+    const assistantExchange = addExchange(
+      sid,
+      'assistant',
+      text,
+      globalMsgNum,
+      undefined,
+      exchangeProvenance,
+    )
     if (imagePaths.length > 0) {
       replaceLastExchangeWithSummary(sid, query, text, imagePaths.length)
     }
@@ -389,7 +483,9 @@ export async function callCodexStreaming(
       const preparingHeartbeat = setInterval(() => callbacks.onToolStatus?.('Preparing images...'), HEARTBEAT_INTERVAL_MS)
       preparingHeartbeat.unref?.()
       try {
-        outputAttachments = await outputImagePublisher.collect()
+        outputAttachments = await collectRunOutputImagesBounded(outputImagePublisher, {
+          signal: options?.abortSignal,
+        })
       } catch (err) {
         console.error('[codex-bridge] output image collection failed:', err)
       } finally {
@@ -416,29 +512,27 @@ export async function callCodexStreaming(
       durationMs: totalMs,
       caller: options?.lightweight ? 'voice_query' : 'full_query',
     })
-    if (persistentCodexSession && codexThreadId) {
-      const saved = saveCodexEngineSession({
-        cosSessionId: sid,
-        model,
-        codexThreadId,
-        cwd: codexCwd,
-        trustMode: codexTrustMode,
-      })
-      updateCodexRun(run.runId, { codexThreadId, expiresAt: saved.expiresAt })
-    }
+    saveEngineSessionBestEffort()
 
-    finishCodexRun(run.runId, {
+    finishRunBestEffort({
       status: 'completed',
       startedAtMs: startTime,
       output: text,
       exitCode: 0,
     })
-    callbacks.onDone(text, model, undefined, {
-      codexRunId: run.runId,
-      codexThreadId,
-      ...(outputAttachments.length > 0 ? { outputAttachments } : {}),
-      ...(outputImageStats && outputImageStats.published > 0 ? { outputImageStats } : {}),
-    })
+    try {
+      const terminalOwned = await callbacks.onDone(text, model, undefined, {
+        codexRunId: run.runId,
+        codexThreadId,
+        clientJobId: options?.clientJobId,
+        generation: options?.generation,
+        ...(outputAttachments.length > 0 ? { outputAttachments } : {}),
+        ...(outputImageStats && outputImageStats.published > 0 ? { outputImageStats } : {}),
+      })
+      if (terminalOwned === false) return
+    } catch (error) {
+      console.error('[codex-bridge] terminal completion callback failed:', error)
+    }
 
     if (isFirstQuery) {
       notifySessionStart(sid, query)
@@ -447,23 +541,25 @@ export async function callCodexStreaming(
     notifyExchange(sid, query, text)
   }
 
-  function finalizeError(msg: string, exitCode?: number | null, status: Exclude<CodexRunStatus, 'running'> = 'failed') {
+  async function finalizeError(msg: string, exitCode?: number | null, status: Exclude<CodexRunStatus, 'running'> = 'failed') {
     if (finalized) return
     finalized = true
     cleanup()
     cleanupImages()
     outputImagePublisher?.cleanup()
     removeExchange(sid, pendingUserExchange)
-    if (engineSession) {
-      clearCodexEngineSession(sid, model)
-    }
-    finishCodexRun(run.runId, {
+    clearEngineSessionBestEffort('provider_error')
+    finishRunBestEffort({
       status,
       startedAtMs: startTime,
       error: msg,
       exitCode,
     })
-    callbacks.onError(safeCodexUserError(msg))
+    try {
+      await callbacks.onError(safeCodexUserError(msg))
+    } catch (error) {
+      console.error('[codex-bridge] terminal error callback failed:', error)
+    }
   }
 
   function handleAbort() {
@@ -580,11 +676,38 @@ export async function callCodexStreaming(
   }
 
   try {
+    const providerOwned = await callbacks.onProviderProcess?.({
+      provider: 'codex',
+      runId: run.runId,
+      pid: proc.pid,
+      clientJobId: options?.clientJobId,
+      generation: options?.generation,
+    })
+    if (providerOwned === false) {
+      proc.kill('SIGTERM')
+      finalized = true
+      cleanup()
+      cleanupImages()
+      outputImagePublisher?.cleanup()
+      removeExchange(sid, pendingUserExchange)
+      clearEngineSessionBestEffort('provider_ownership_lost')
+      finishRunBestEffort({
+        status: 'failed',
+        startedAtMs: startTime,
+        error: 'codex-bridge: durable provider ownership was lost.',
+        exitCode: null,
+      })
+      return sid
+    }
+    if (finalized) return sid
     proc.stdin.write(prompt)
     proc.stdin.end()
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err)
-    finalizeError(`codex-bridge: stdin failed — ${message}`)
+    if (!finalized) {
+      proc.kill('SIGTERM')
+      await finalizeError(`codex-bridge: provider start failed — ${message}`)
+    }
   }
 
   return sid