diff --git a/spx-gui/src/apps/account/.env b/spx-gui/src/apps/account/.env
index 207f5346df..b88fe54092 100644
--- a/spx-gui/src/apps/account/.env
+++ b/spx-gui/src/apps/account/.env
@@ -30,6 +30,7 @@ VITE_AVATAR_BASE_URL=""
 VITE_SENTRY_DSN=""
 VITE_SENTRY_TRACES_SAMPLE_RATE="0.8"
 VITE_SENTRY_LSP_SAMPLE_RATE="0.1"
+VITE_SENTRY_AI_SAMPLE_RATE="1"
 
 # Default language for app account, e.g. `en`, `zh`.
 VITE_DEFAULT_LANG="en"
diff --git a/spx-gui/src/apps/account/env.ts b/spx-gui/src/apps/account/env.ts
index 8f9c347f60..20cbf668dd 100644
--- a/spx-gui/src/apps/account/env.ts
+++ b/spx-gui/src/apps/account/env.ts
@@ -1,8 +1,10 @@
 export const defaultLang = (import.meta.env.VITE_DEFAULT_LANG as string) || 'en'
 const sentryTracesSampleRate = parseFloat(import.meta.env.VITE_SENTRY_TRACES_SAMPLE_RATE as string)
 const sentryLSPSampleRate = parseFloat(import.meta.env.VITE_SENTRY_LSP_SAMPLE_RATE as string)
+const sentryAISampleRate = parseFloat(import.meta.env.VITE_SENTRY_AI_SAMPLE_RATE as string)
 export const sentry = {
   dsn: (import.meta.env.VITE_SENTRY_DSN as string) || '',
   tracesSampleRate: Number.isNaN(sentryTracesSampleRate) ? 0.1 : sentryTracesSampleRate,
-  lspSampleRate: Number.isNaN(sentryLSPSampleRate) ? 0.1 : sentryLSPSampleRate
+  lspSampleRate: Number.isNaN(sentryLSPSampleRate) ? 0.1 : sentryLSPSampleRate,
+  aiSampleRate: Number.isNaN(sentryAISampleRate) ? 1 : sentryAISampleRate
 }
diff --git a/spx-gui/src/apps/xbuilder/.env b/spx-gui/src/apps/xbuilder/.env
index a1bd316221..ced0406be6 100644
--- a/spx-gui/src/apps/xbuilder/.env
+++ b/spx-gui/src/apps/xbuilder/.env
@@ -64,6 +64,10 @@ VITE_SENTRY_TRACES_SAMPLE_RATE="0.8"
 # 0.0 means no LSP events are sent, 1.0 means all LSP events are sent.
 VITE_SENTRY_LSP_SAMPLE_RATE="0.1"
 
+# Sampling rate for independent AI traces (ai.think and later ai.* roots).
+# Kept separate from pageload so Think is not all-or-none with the page.
+VITE_SENTRY_AI_SAMPLE_RATE="1"
+
 # If tutorials entry should be shown in the Navbar.
 VITE_SHOW_TUTORIALS_ENTRY="false"
 
diff --git a/spx-gui/src/apps/xbuilder/env.ts b/spx-gui/src/apps/xbuilder/env.ts
index adc1e3a52a..e51b38a84d 100644
--- a/spx-gui/src/apps/xbuilder/env.ts
+++ b/spx-gui/src/apps/xbuilder/env.ts
@@ -12,8 +12,10 @@ export const defaultFontPreferences = (import.meta.env.VITE_DEFAULT_FONT_PREFERE
 export const accountOAuthClientId = import.meta.env.VITE_ACCOUNT_OAUTH_CLIENT_ID as string
 const sentryTracesSampleRate = parseFloat(import.meta.env.VITE_SENTRY_TRACES_SAMPLE_RATE as string)
 const sentryLSPSampleRate = parseFloat(import.meta.env.VITE_SENTRY_LSP_SAMPLE_RATE as string)
+const sentryAISampleRate = parseFloat(import.meta.env.VITE_SENTRY_AI_SAMPLE_RATE as string)
 export const sentry = {
   dsn: (import.meta.env.VITE_SENTRY_DSN as string) || '',
   tracesSampleRate: Number.isNaN(sentryTracesSampleRate) ? 0.1 : sentryTracesSampleRate,
-  lspSampleRate: Number.isNaN(sentryLSPSampleRate) ? 0.1 : sentryLSPSampleRate
+  lspSampleRate: Number.isNaN(sentryLSPSampleRate) ? 0.1 : sentryLSPSampleRate,
+  aiSampleRate: Number.isNaN(sentryAISampleRate) ? 1 : sentryAISampleRate
 }
diff --git a/spx-gui/src/components/project/runner/ProjectRunner.vue b/spx-gui/src/components/project/runner/ProjectRunner.vue
index d3c5497742..f5b679cf22 100644
--- a/spx-gui/src/components/project/runner/ProjectRunner.vue
+++ b/spx-gui/src/components/project/runner/ProjectRunner.vue
@@ -52,10 +52,80 @@ type RunnerFiles = {
   [path: string]: RunnerFile
 }
 
+/** Parent-page Sentry hooks injected into the runner iframe. WASM calls these during Think / Archive. */
+type AISentryBridge = {
+  startThink: (info: { thinkId: string; startTime: number; gameSessionId: string }) => {
+    sentryTrace: string
+    baggage: string
+  }
+  endThink: (info: {
+    thinkId: string
+    endTime: number
+    outcome?: string
+    category?: string
+    reason?: string
+    turnCount?: number
+    attemptCount?: number
+    exception?: {
+      message: string
+      userMsg?: string
+      commandName?: string
+      commandArgs?: string
+      turnIndex?: number
+      attempt?: number
+      category?: string
+      reason?: string
+      gameSessionId?: string
+    }
+  }) => void
+  startAttempt: (info: { thinkId: string; startTime: number; turnIndex: number; attempt: number }) => void
+  endAttempt: (info: {
+    thinkId: string
+    endTime: number
+    ok: boolean
+    backendCategory?: string
+    backendReason?: string
+    requestId?: string
+  }) => void
+  startCommand: (info: { thinkId: string; startTime: number; turnIndex: number; commandName: string }) => void
+  endCommand: (info: { thinkId: string; endTime: number; ok: boolean; errorMessage: string }) => void
+  startArchive: (info: { archiveId: string; startTime: number; gameSessionId: string }) => {
+    sentryTrace: string
+    baggage: string
+  }
+  endArchive: (info: {
+    archiveId: string
+    endTime: number
+    ok?: boolean
+    attemptCount?: number
+    category?: string
+    reason?: string
+    exception?: {
+      message: string
+      error?: string
+      attemptCount?: number
+      category?: string
+      reason?: string
+      gameSessionId?: string
+    }
+  }) => void
+  startArchiveAttempt: (info: { archiveId: string; startTime: number; attempt: number }) => void
+  endArchiveAttempt: (info: {
+    archiveId: string
+    endTime: number
+    ok: boolean
+    backendCategory?: string
+    backendReason?: string
+    requestId?: string
+  }) => void
+}
+
 interface RunnerIframeWindow extends Window {
   xbuilder_set_ai_interaction_api_endpoint: (endpoint: string) => void
   xbuilder_set_ai_interaction_api_token_provider: (provider: () => Promise<string>) => void
   xbuilder_set_ai_description: (description: string) => void
+  xbuilder_set_game_session_id: (id: string) => void
+  xbuilder_set_sentry_bridge: (bridge: AISentryBridge) => void
   /** Set the current logged-in username, injected into the spx runtime before running. */
   xbuilder_set_username: (username: string) => void
   /** Init the engine. Can be called early; project-agnostic. */
@@ -145,6 +215,7 @@ type State =
 
 <script setup lang="ts">
 import { throttle } from 'lodash'
+import * as Sentry from '@sentry/vue'
 import { computed, onBeforeUnmount, onUnmounted, ref, shallowReactive, shallowRef, watch } from 'vue'
 import { timeout, untilNotNull } from '@/utils/utils'
 import { ProgressCollector, ProgressReporter, type Progress } from '@/utils/progress'
@@ -179,6 +250,420 @@ const state = shallowRef<State>({ type: 'initial' })
 const runnerIframeRef = ref<HTMLIFrameElement>()
 const runnerIframeWindowRef = ref<RunnerIframeWindow | null>(null)
 let engineInitPromise: Promise<void> | null = null
+let lastRuntimePanic: RuntimePanic | null = null
+let lastRuntimePanicAt = 0
+const runtimePanicGracePeriodMs = 1000
+// Generic error callbacks can follow a structured panic log later during engine shutdown.
+const runtimePanicDedupWindowMs = 5000
+const deferredRuntimeErrorCaptures = new Set<number>()
+const sentrySpanStatus = {
+  ok: 1,
+  error: 2
+} as const
+
+function createAISentryBridge(): AISentryBridge {
+  type InactiveSpan = ReturnType<typeof Sentry.startInactiveSpan>
+  type ThinkState = {
+    thinkSpan: InactiveSpan
+    attemptSpan: InactiveSpan | null
+    commandSpan: InactiveSpan | null
+    ended: boolean
+  }
+  type ArchiveState = {
+    archiveSpan: InactiveSpan
+    attemptSpan: InactiveSpan | null
+    ended: boolean
+  }
+
+  const thinks = new Map<string, ThinkState>()
+  const archives = new Map<string, ArchiveState>()
+
+  const endSpan = (span: InactiveSpan | null, endTime: number, ok?: boolean) => {
+    if (span == null) return
+    if (ok != null) {
+      span.setStatus({ code: ok ? sentrySpanStatus.ok : sentrySpanStatus.error })
+    }
+    span.end(endTime)
+  }
+
+  const traceHeaders = (span: InactiveSpan) => {
+    const traceData = Sentry.getTraceData({ span })
+    return {
+      sentryTrace: traceData['sentry-trace'] ?? '',
+      baggage: traceData['baggage'] ?? ''
+    }
+  }
+
+  // startThink / startArchive must return headers immediately. Other hooks are
+  // deferred so Sentry work does not rewrite the Go WASM panic stack.
+  const later = (fn: () => void) => {
+    setTimeout(fn, 0)
+  }
+
+  const captureThinkException = (
+    span: InactiveSpan,
+    exception: Parameters<AISentryBridge['endThink']>[0]['exception']
+  ) => {
+    if (exception?.message == null || exception.message === '') return
+    const error = new Error(exception.message)
+    error.name = 'AIThinkFailure'
+    try {
+      Sentry.withScope((scope) => {
+        if (exception.gameSessionId) scope.setTag('game_session_id', exception.gameSessionId)
+        if (exception.category) scope.setTag('category', exception.category)
+        if (exception.reason) scope.setTag('reason', exception.reason)
+        if (exception.reason === 'timeout' || exception.reason === 'network') {
+          if (exception.turnIndex != null) scope.setTag('turn_index', String(exception.turnIndex))
+          if (exception.attempt != null) scope.setTag('attempt', String(exception.attempt))
+        }
+        if (exception.reason === 'invalid_arguments' || exception.reason === 'handler_panic') {
+          if (exception.turnIndex != null) scope.setTag('turn_index', String(exception.turnIndex))
+        }
+        const detail: Record<string, unknown> = {}
+        if (exception.userMsg) detail.user_msg = exception.userMsg
+        if (exception.commandName) detail.command_name = exception.commandName
+        if (exception.commandArgs) detail.command_args = exception.commandArgs
+        detail.error = exception.message
+        scope.setContext('ai', detail)
+        const report = () => Sentry.captureException(error)
+        if (span != null) {
+          Sentry.withActiveSpan(span, report)
+        } else {
+          report()
+        }
+      })
+    } catch (captureError) {
+      console.warn('Failed to report AI think failure to Sentry', captureError)
+    }
+  }
+
+  const captureArchiveException = (
+    span: InactiveSpan,
+    exception: Parameters<AISentryBridge['endArchive']>[0]['exception']
+  ) => {
+    if (exception?.message == null || exception.message === '') return
+    const error = new Error(exception.message)
+    error.name = 'AIArchiveFailure'
+    try {
+      Sentry.withScope((scope) => {
+        if (exception.gameSessionId) scope.setTag('game_session_id', exception.gameSessionId)
+        if (exception.category) scope.setTag('category', exception.category)
+        if (exception.reason) scope.setTag('reason', exception.reason)
+        const detail: Record<string, unknown> = {}
+        if (exception.attemptCount != null) detail.attempt_count = exception.attemptCount
+        detail.error = exception.error || exception.message
+        scope.setContext('ai', detail)
+        const report = () => Sentry.captureException(error)
+        if (span != null) {
+          Sentry.withActiveSpan(span, report)
+        } else {
+          report()
+        }
+      })
+    } catch (captureError) {
+      console.warn('Failed to report AI archive failure to Sentry', captureError)
+    }
+  }
+
+  return {
+    startThink(info) {
+      const thinkSpan = Sentry.startNewTrace(() =>
+        Sentry.startInactiveSpan({
+          name: 'ai.think',
+          op: 'ai.think',
+          forceTransaction: true,
+          parentSpan: null,
+          // WASM-provided unix seconds; Think duration is not a latency signal.
+          startTime: info.startTime,
+          attributes: { game_session_id: info.gameSessionId }
+        })
+      )
+      thinks.set(info.thinkId, {
+        thinkSpan,
+        attemptSpan: null,
+        commandSpan: null,
+        ended: false
+      })
+      return traceHeaders(thinkSpan)
+    },
+    endThink(info) {
+      later(() => {
+        const state = thinks.get(info.thinkId)
+        if (state == null || state.ended) return
+        state.ended = true
+        captureThinkException(state.thinkSpan, info.exception)
+        if (info.outcome) {
+          state.thinkSpan.setAttribute('outcome', info.outcome)
+        }
+        if (info.category) {
+          state.thinkSpan.setAttribute('category', info.category)
+        }
+        if (info.reason) {
+          state.thinkSpan.setAttribute('reason', info.reason)
+        }
+        if (info.turnCount != null) {
+          state.thinkSpan.setAttribute('turn_count', info.turnCount)
+        }
+        if (info.attemptCount != null) {
+          state.thinkSpan.setAttribute('attempt_count', info.attemptCount)
+        }
+        let thinkOK: boolean | undefined
+        if (info.outcome === 'success') thinkOK = true
+        else if (info.outcome === 'failure') thinkOK = false
+        endSpan(state.commandSpan, info.endTime)
+        endSpan(state.attemptSpan, info.endTime)
+        endSpan(state.thinkSpan, info.endTime, thinkOK)
+        thinks.delete(info.thinkId)
+      })
+    },
+    startAttempt(info) {
+      later(() => {
+        const state = thinks.get(info.thinkId)
+        if (state == null || state.ended) return
+        endSpan(state.attemptSpan, info.startTime)
+        state.attemptSpan = Sentry.startInactiveSpan({
+          name: 'ai.transport.attempt',
+          op: 'ai.transport.attempt',
+          parentSpan: state.thinkSpan,
+          startTime: info.startTime,
+          attributes: {
+            turn_index: info.turnIndex,
+            attempt: info.attempt
+          }
+        })
+      })
+    },
+    endAttempt(info) {
+      later(() => {
+        const state = thinks.get(info.thinkId)
+        if (state == null || state.ended) return
+        if (info.backendCategory) {
+          state.attemptSpan?.setAttribute('backend_category', info.backendCategory)
+        }
+        if (info.backendReason) {
+          state.attemptSpan?.setAttribute('backend_reason', info.backendReason)
+        }
+        if (info.requestId) {
+          state.attemptSpan?.setAttribute('request_id', info.requestId)
+        }
+        endSpan(state.attemptSpan, info.endTime, info.ok)
+        state.attemptSpan = null
+      })
+    },
+    startCommand(info) {
+      later(() => {
+        const state = thinks.get(info.thinkId)
+        if (state == null || state.ended) return
+        endSpan(state.commandSpan, info.startTime)
+        state.commandSpan = Sentry.startInactiveSpan({
+          name: 'ai.command.execute',
+          op: 'ai.command.execute',
+          parentSpan: state.thinkSpan,
+          startTime: info.startTime,
+          attributes: {
+            turn_index: info.turnIndex,
+            command_name: info.commandName
+          }
+        })
+      })
+    },
+    endCommand(info) {
+      later(() => {
+        const state = thinks.get(info.thinkId)
+        if (state == null || state.ended) return
+        if (info.errorMessage) {
+          state.commandSpan?.setAttribute('error_message', info.errorMessage.slice(0, 1024))
+        }
+        endSpan(state.commandSpan, info.endTime, info.ok)
+        state.commandSpan = null
+      })
+    },
+    startArchive(info) {
+      const archiveSpan = Sentry.startNewTrace(() =>
+        Sentry.startInactiveSpan({
+          name: 'ai.archive',
+          op: 'ai.archive',
+          forceTransaction: true,
+          parentSpan: null,
+          startTime: info.startTime,
+          attributes: { game_session_id: info.gameSessionId }
+        })
+      )
+      archives.set(info.archiveId, {
+        archiveSpan,
+        attemptSpan: null,
+        ended: false
+      })
+      return traceHeaders(archiveSpan)
+    },
+    endArchive(info) {
+      later(() => {
+        const state = archives.get(info.archiveId)
+        if (state == null || state.ended) return
+        state.ended = true
+        captureArchiveException(state.archiveSpan, info.exception)
+        if (info.attemptCount != null) {
+          state.archiveSpan.setAttribute('attempt_count', info.attemptCount)
+        }
+        if (info.category) {
+          state.archiveSpan.setAttribute('category', info.category)
+        }
+        if (info.reason) {
+          state.archiveSpan.setAttribute('reason', info.reason)
+        }
+        let archiveOK: boolean | undefined
+        if (info.ok === true) archiveOK = true
+        else if (info.ok === false || info.exception) archiveOK = false
+        endSpan(state.attemptSpan, info.endTime)
+        endSpan(state.archiveSpan, info.endTime, archiveOK)
+        archives.delete(info.archiveId)
+      })
+    },
+    startArchiveAttempt(info) {
+      later(() => {
+        const state = archives.get(info.archiveId)
+        if (state == null || state.ended) return
+        endSpan(state.attemptSpan, info.startTime)
+        state.attemptSpan = Sentry.startInactiveSpan({
+          name: 'ai.archive.transport.attempt',
+          op: 'ai.archive.transport.attempt',
+          parentSpan: state.archiveSpan,
+          startTime: info.startTime,
+          attributes: { attempt: info.attempt }
+        })
+      })
+    },
+    endArchiveAttempt(info) {
+      later(() => {
+        const state = archives.get(info.archiveId)
+        if (state == null || state.ended) return
+        if (info.backendCategory) {
+          state.attemptSpan?.setAttribute('backend_category', info.backendCategory)
+        }
+        if (info.backendReason) {
+          state.attemptSpan?.setAttribute('backend_reason', info.backendReason)
+        }
+        if (info.requestId) {
+          state.attemptSpan?.setAttribute('request_id', info.requestId)
+        }
+        endSpan(state.attemptSpan, info.endTime, info.ok)
+        state.attemptSpan = null
+      })
+    }
+  }
+}
+
+type RuntimePanic = {
+  error: string
+  functionName: string
+  file: string
+  line: number
+  column: number
+}
+
+async function traceRunnerOperation<T>(name: string, op: string, operation: () => Promise<T>) {
+  const span = Sentry.startInactiveSpan({
+    name,
+    op,
+    attributes: { 'spx.runtime': true }
+  })
+  try {
+    const result = await operation()
+    span.setStatus({ code: sentrySpanStatus.ok })
+    return result
+  } catch (err) {
+    span.setStatus({ code: sentrySpanStatus.error, message: err instanceof Cancelled ? 'cancelled' : 'error' })
+    throw err
+  } finally {
+    span.end()
+  }
+}
+
+function handleRuntimePanic(panic: RuntimePanic) {
+  lastRuntimePanic = panic
+  lastRuntimePanicAt = Date.now()
+  clearDeferredRuntimeErrorCaptures()
+
+  // Defer Sentry work until the WASM-to-JavaScript console call has returned.
+  // Calling the SDK synchronously here can corrupt Go WASM panic unwinding.
+  window.setTimeout(() => {
+    const exception = new Error(panic.error)
+    exception.name = 'SpxRuntimePanic'
+    try {
+      Sentry.withScope((scope) => {
+        scope.setTag('spx.runtime', 'panic')
+        scope.setContext('spx', {
+          function: panic.functionName,
+          file: panic.file,
+          line: panic.line,
+          column: panic.column
+        })
+        Sentry.captureException(exception)
+      })
+    } catch (captureError) {
+      // Monitoring must never interfere with the project runtime.
+      console.warn('Failed to report SPX runtime panic to Sentry', captureError)
+    }
+  }, 0)
+}
+
+function parseRuntimePanic(args: unknown[]): RuntimePanic | null {
+  const [arg] = args
+  if (args.length !== 1 || typeof arg !== 'string') return null
+
+  // Panic logs are JSON objects produced by the ispx slog handler. Avoid JSON.parse for normal game logs.
+  if (!arg.startsWith('{') || !arg.includes('"msg"') || !arg.includes('"panic"')) return null
+
+  let value: unknown
+  try {
+    value = JSON.parse(arg)
+  } catch {
+    return null
+  }
+  if (value == null || typeof value !== 'object') return null
+
+  const record = value as Record<string, unknown>
+  if (
+    record.msg !== 'panic' ||
+    typeof record.error !== 'string' ||
+    typeof record.function !== 'string' ||
+    typeof record.file !== 'string' ||
+    typeof record.line !== 'number' ||
+    typeof record.column !== 'number'
+  ) {
+    return null
+  }
+
+  return {
+    error: record.error,
+    functionName: record.function,
+    file: record.file,
+    line: record.line,
+    column: record.column
+  }
+}
+
+function hasRecentRuntimePanic() {
+  const panic = lastRuntimePanic
+  return panic != null && Date.now() - lastRuntimePanicAt <= runtimePanicDedupWindowMs
+}
+
+function clearDeferredRuntimeErrorCaptures() {
+  deferredRuntimeErrorCaptures.forEach((timer) => window.clearTimeout(timer))
+  deferredRuntimeErrorCaptures.clear()
+}
+
+function deferRuntimeErrorCapture(err: unknown, ctx: string) {
+  if (hasRecentRuntimePanic()) return
+
+  // The runner may emit a generic game error before its structured panic log reaches the parent frame.
+  // Wait briefly so a panic can replace the generic event with source-aware diagnostics.
+  const timer = window.setTimeout(() => {
+    deferredRuntimeErrorCaptures.delete(timer)
+    if (!hasRecentRuntimePanic()) capture(err, ctx)
+  }, runtimePanicGracePeriodMs)
+  deferredRuntimeErrorCaptures.add(timer)
+}
 
 watch(runnerIframeRef, (iframe) => {
   if (iframe == null) return
@@ -192,6 +677,8 @@ function handleIframeWindow(iframeWindow: RunnerIframeWindow) {
   iframeWindow.console.log = function (...args: unknown[]) {
     // eslint-disable-next-line no-console
     console.log(...args)
+    const panic = parseRuntimePanic(args)
+    if (panic != null) handleRuntimePanic(panic)
     emit('console', 'log', args)
   }
   iframeWindow.console.warn = function (...args: unknown[]) {
@@ -203,20 +690,22 @@ function handleIframeWindow(iframeWindow: RunnerIframeWindow) {
     runnerIframeWindowRef.value = iframeWindow
     iframeWindow.onGameError((err: string) => {
       state.value = { type: 'failed', err }
-      capture(err, 'ProjectRunner game error')
+      deferRuntimeErrorCapture(err, 'ProjectRunner game error')
     })
     iframeWindow.onGameExit((code: number) => {
       emit('exit', code)
     })
     iframeWindow.onEngineCrash((err: string) => {
       state.value = { type: 'failed', err }
-      capture(err, 'ProjectRunner engine crash')
+      deferRuntimeErrorCapture(err, 'ProjectRunner engine crash')
       reloadIframe() // The engine crashed and failed to recover by itself, so we reload the iframe.
     })
-    engineInitPromise = iframeWindow.initEngine(assetURLs, { logLevel: logLevels.LOG_LEVEL_ERROR, useProfiler: false })
+    engineInitPromise = traceRunnerOperation('SPX: Initialize engine', 'spx.engine.init', () =>
+      iframeWindow.initEngine(assetURLs, { logLevel: logLevels.LOG_LEVEL_ERROR, useProfiler: false })
+    )
     engineInitPromise.catch((err) => {
       state.value = { type: 'failed', err }
-      capture(err, 'ProjectRunner init engine error')
+      deferRuntimeErrorCapture(err, 'ProjectRunner init engine error')
     })
   }
 
@@ -272,6 +761,8 @@ async function prepareAIInteraction(
   iframeWindow.xbuilder_set_ai_description(aiDescription)
   iframeWindow.xbuilder_set_ai_interaction_api_endpoint(aiInteractionEndpoint)
   iframeWindow.xbuilder_set_ai_interaction_api_token_provider(async () => (await ensureAccessToken()) ?? '')
+  iframeWindow.xbuilder_set_game_session_id(crypto.randomUUID())
+  iframeWindow.xbuilder_set_sentry_bridge(createAISentryBridge())
   reporter.report(1)
   return
 }
@@ -299,6 +790,7 @@ function getRunCtrl() {
 
 onUnmounted(() => {
   runCtrl?.abort(new Cancelled('unmounted'))
+  clearDeferredRuntimeErrorCaptures()
 })
 
 async function runInternal(ctrl: AbortController) {
@@ -307,6 +799,9 @@ async function runInternal(ctrl: AbortController) {
     progress: { percentage: 0, desc: null, timeLeft: null }
   } satisfies State)
   state.value = startingState
+  lastRuntimePanic = null
+  lastRuntimePanicAt = 0
+  clearDeferredRuntimeErrorCaptures()
   const collector = new ProgressCollector()
   collector.onProgress(throttle((progress) => (startingState.progress = progress), 100))
   try {
@@ -336,7 +831,7 @@ async function runInternal(ctrl: AbortController) {
         loadFiles(files, getProjectDataReporter, ctrl.signal)
       ]).then(async ([_, runnerFiles]) => {
         await uiUpdated(ctrl.signal)
-        await iframeWindow.initGame(runnerFiles)
+        await traceRunnerOperation('SPX: Build project', 'spx.build', () => iframeWindow.initGame(runnerFiles))
         ctrl.signal.throwIfAborted()
         initGameReporter.report(1)
       }),
@@ -354,14 +849,14 @@ async function runInternal(ctrl: AbortController) {
 
     // TODO: get progress for engine-loading, which is now included in `startGame`
     startGameReporter.startAutoReport(10_000)
-    await iframeWindow.startGame()
+    await traceRunnerOperation('SPX: Start project', 'spx.start', () => iframeWindow.startGame())
     ctrl.signal.throwIfAborted()
     startGameReporter.report(1)
     state.value = { type: 'running' }
     return hashFiles(files, ctrl.signal)
   } catch (err) {
     if (err instanceof Cancelled) throw err
-    capture(err, 'ProjectRunner run game error')
+    deferRuntimeErrorCapture(err, 'ProjectRunner run game error')
     state.value = { type: 'failed', err }
     throw err
   }
@@ -388,7 +883,7 @@ defineExpose({
 
     const iframeWindow = runnerIframeWindowRef.value
     if (iframeWindow == null) return
-    await iframeWindow.stopGame()
+    await traceRunnerOperation('SPX: Stop project', 'spx.stop', () => iframeWindow.stopGame())
     state.value = { type: 'initial' }
   },
   async rerun() {
diff --git a/spx-gui/src/setup/sentry.ts b/spx-gui/src/setup/sentry.ts
index 78399e7d85..faa650cdf6 100644
--- a/spx-gui/src/setup/sentry.ts
+++ b/spx-gui/src/setup/sentry.ts
@@ -2,7 +2,7 @@ import type { App as VueApp } from 'vue'
 import * as Sentry from '@sentry/vue'
 import type { Router } from 'vue-router'
 
-import { isCodeEditorOperation, isLSPOperation } from '@/utils/tracing'
+import { isAIOperation, isCodeEditorOperation, isLSPOperation } from '@/utils/tracing'
 
 const ignoreErrorTypes = [
   'AbortError',
@@ -17,6 +17,7 @@ export type SentryConfig = {
   dsn: string
   tracesSampleRate: number
   lspSampleRate: number
+  aiSampleRate: number
 }
 
 export function initSentry(app: VueApp<Element>, router: Router | undefined, config: SentryConfig) {
@@ -41,6 +42,10 @@ export function initSentry(app: VueApp<Element>, router: Router | undefined, con
     environment: process.env.NODE_ENV,
     tracesSampler: (samplingContext) => {
       const { name, inheritOrSampleWith } = samplingContext
+      // Independent AI roots must not inherit pageload sampling (#1826).
+      if (isAIOperation(name)) {
+        return config.aiSampleRate
+      }
       if (isLSPOperation(name) || isCodeEditorOperation(name)) {
         return config.lspSampleRate
       }
diff --git a/spx-gui/src/utils/tracing.ts b/spx-gui/src/utils/tracing.ts
index 743d1696d8..4a677ee2af 100644
--- a/spx-gui/src/utils/tracing.ts
+++ b/spx-gui/src/utils/tracing.ts
@@ -46,6 +46,10 @@ export function isCodeEditorOperation(name: string): boolean {
   return name.startsWith(CODE_EDITOR_IDENTIFIER)
 }
 
+export function isAIOperation(name: string): boolean {
+  return name.startsWith('ai.')
+}
+
 type IdleSpanOptions = NonNullable<Parameters<typeof SentryCore.startIdleSpan>[1]>
 
 /**
diff --git a/tools/ai/SENTRY_IMPLEMENTATION.md b/tools/ai/SENTRY_IMPLEMENTATION.md
new file mode 100644
index 0000000000..29dcfd83b4
--- /dev/null
+++ b/tools/ai/SENTRY_IMPLEMENTATION.md
@@ -0,0 +1,207 @@
+# AI Interaction Sentry：实现对照
+
+对照方案 [`SENTRY_PLAN.md`](./SENTRY_PLAN.md)。方案是合同，这份是「改了什么、为什么、去哪核对」。
+
+仓库：
+
+- 前端 `builder`，分支 `feat/issue-2419-sentry-spx-runtime`
+- 后端 `builder-backend`，分支 `feat/aiinteraction-stream-ttft`
+
+切片 1–4 已落地。切片 5（上线后调 `ai.*` 采样率、精灵名）未做。
+
+---
+
+## 怎么核对
+
+1. 打开方案对应章节，再按下表进代码。
+2. 先看终态和分类，再看 span 树。exception 规则和 span 树是两件事。
+3. Sentry Explore 默认不索引自定义 attribute。搜 `span.op:ai.think` / `ai.upstream`，点根 span 看 Attributes。SDK 自动打的 `category: ai` 不是方案里的 `transport_failure`。
+
+---
+
+## 切片总览
+
+| 方案切片 | 目标 | 达成 | 核对入口 |
+|---|---|---|---|
+| 1 桥和 Think trace | 独立 root、同步 Trace 头、`game_session_id`、attempt / command span | 是 | `ProjectRunner.vue` 桥；`sentry_wasm.go`；`sentry_context.go` |
+| 2 后端 upstream | `ai.upstream`、TTFT、`ai.detail`、错误体带分类 | 是 | `aiinteraction.go`；`detail.go`；`util.go` `replyWithInnerError` |
+| 3 终态 / exception | `failure` 才打一条；429 / 额度 / 取消只记 outcome | 是 | `classify.go`；`httperr.go`；`exception.go`；`ai.go` |
+| 4 合同对齐 | 细 reason、`empty_archive`、quota 不改合同 | 是 | `failure.go`；`responseFromChoice`；`classifyArchiveChoice` |
+| 5 采样 | 上线后按量调 `ai.*` | 否 | 挂钩已有，`aiSampleRate` 缺省仍是 `1` |
+
+真机只稳定验过成功 Think。failure / 429 / 空归档主要靠单测。
+
+---
+
+## 对照方案正文
+
+### 链路（方案「链路」）
+
+**设计：** Think / Archive 各开独立 root，不挂在页面 pageload 上，避免页面采样把整次交互吃掉。SDK 留在父页面；WASM 只通知起止，并带上 WASM 侧时间戳。`startThink` / `startArchive` 必须同步返回 `Sentry-Trace` / `Baggage`，fetch 才能续到同一棵树。其余桥方法 `setTimeout(0)`，避免同步调 Sentry 破坏 Go WASM 的 panic 栈展开。多 Player 时 header 进 `context`，不用全局。
+
+**做了什么：**
+
+| 文件 | 工作 |
+|---|---|
+| `spx-gui/.../ProjectRunner.vue` | JS 桥：`startThink` / `startArchive` 同步 `getTraceData()`；其余 `later()` → `setTimeout(0)`；开局 `xbuilder_set_game_session_id` |
+| `tools/ispx/ai.go` | 注入 `setGameSessionID` / `setSentryBridge` |
+| `tools/ai/sentry_wasm.go` | WASM 调桥；`startRoot` 把 header 写入 ctx |
+| `tools/ai/sentry_stub.go` | 非 wasm 空实现，单测可编 |
+| `tools/ai/sentry_context.go` | `TraceHeadersFromContext` |
+| `tools/ai/wasmtrans/wasmtrans.go` | fetch 带 `Sentry-Trace` / `Baggage` |
+| `tools/ai/command.go` | `ai.command.execute` |
+| `spx-gui/src/utils/tracing.ts` | `isAIOperation`（`ai.` 前缀） |
+| `spx-gui/src/setup/sentry.ts` | `tracesSampler` 对 `ai.*` 走 `aiSampleRate`，不继承 pageload |
+| `spx-gui/src/apps/*/env.ts` | 读 `VITE_SENTRY_AI_SAMPLE_RATE`，缺省 `1` |
+
+**达成：** 是。成功 Think 真机已连到后端 `http.server`，和页面 trace 分开。
+
+**核对：** `startRoot` 是否同步返回 header；`later()` 是否包住 `endThink` / attempt / command；两个 ctx 的 `TraceHeadersFromContext` 是否互不串（`sentry_context_test.go`）。
+
+---
+
+### 什么时候打 exception（方案「什么时候打 exception」）
+
+**设计：** span 记每一步；exception 只在**这条流程停掉**时打一条，由停掉的那一侧上报。后端 retry 可消化的失败只标 span error，避免前端 retry 3 次打出 3 条 Issue。因此后端 **不** `CaptureException`（含 `empty_archive`）。429 用尽、额度、取消是预期结束，进 `outcome`，不进 Issues。
+
+**做了什么：**
+
+| 文件 | 工作 |
+|---|---|
+| `tools/ai/exception.go` | `shouldCaptureException`：Think 仅 `outcome=failure`；Archive 仅 `captureException` |
+| `tools/ai/classify.go` | 429 → `rate_limited`；403+40301 → `quota_exhausted`；timeout / network 才 `failure` |
+| `tools/ai/httperr.go` | 只把 `403 && code===40301` 当成额度；其它 403 不是 |
+| `tools/ai/ai.go` | Think / Archive 各 `endThink` / `endArchive` **一次**收口 |
+| `ProjectRunner.vue` | `AIThinkFailure` / `AIArchiveFailure`；`endThink` 同一 `setTimeout(0)` 里 capture → attributes → finish → `Map.delete` |
+| 后端 `startUpstreamSpan` | 失败只 `span.Status=error` + tag，不 CaptureException |
+
+**达成：** 是。和更早「后端上报 empty_archive exception」的草案不同，以方案现口径为准。
+
+**核对：** `exception_test.go`、`finish_once_test.go`、`think_finish_test.go`、`archive_finish_test.go`。429 / quota / cancel 不得带 exception payload。
+
+---
+
+### Span（方案「Span」）
+
+**`ai.think`** — `endThink` 写入 `outcome` / `turn_count` / `attempt_count`；`failure` 时加 `category`。中途 command 被拒、后面仍结束的，outcome 仍是 `success`（`finish_once_test.go`）。
+
+**`ai.transport.attempt`** — 每次 Interact。失败标 error，后端 `{category,reason,request_id}` 打成 `backend_*`（`httperr.go` 注释；桥 `endAttempt`）。这是后端命名空间，不当 Think 的 category。
+
+**`ai.command.execute`** — `command.go` `callCommandHandler`。`Break` 正常结束；其它 error 标 span error，Think 继续。`invalid_arguments` / `handler_panic` 在出口分流后**停 Think**。
+
+**`ai.upstream`** — 后端每次调模型。`request_id` 用 chunk id。`first_meaningful_delta_ms`：**成功或失败，只要测到 meaningful delta 都写**（半截流也能看卡在首包前还是后）。没测到就没有这个字段。
+
+**Archive** — 独立 root，不从 Think 继承 header（`scheduleHistoryManagement` 新 ctx）。没有 `ai.archive.outcome`。取消 / 额度结束 span、不打 exception。非取消 retry 用尽 → 前端 `archive_failure` / `retries_exhausted`。
+
+**达成：** 是。TTFT 曾与「成功才写」的旧措辞不一致，方案已改为与代码一致。
+
+**核对：** 后端 `TestInteractRecordsUpstreamSpan` / `TestArchiveRecordsUpstreamSpan`；前端 `think_finish_test.go`。
+
+---
+
+### 分类（方案「分类」）
+
+两套 category，不要混：
+
+- Think exception：`transport_failure` / `model_quality_failure` / `runtime_failure` / `archive_failure`
+- 后端错误体：`upstream_failure` / `model_response_invalid` / `archive_failure`（`empty_archive`）
+
+前端 `rate_limited` **不是** exception category，只是 Think `outcome`。
+
+后端细 reason 先匹配先生效，没有 `other` 兜底：
+
+1. `blocked`（Refusal / `content_filter`）
+2. `truncated`（`length`，即使带着半截 tool call）
+3. `no_choices`
+4. `missing_required_tool_call`（首轮，或 history 末项 command 失败的续轮）
+5. `invalid_tool_call`（多 call、空 args、`null`、坏 JSON、尾随数据）
+6. `unexpected_finish_reason`（空 / 未知 / 与 tool_calls 不匹配；流提前结束）
+
+尾随 JSON：第一次 Decode 成功后必须再 Decode 一次得到 `io.EOF`。只看 `Decoder.More()` 会把 `{"x":1}}` 当合法。见 `decodeToolCallArgs`。
+
+Archive 没有 tool call，正常结束必须 `stop`。`stop` 且内容空 → `empty_archive`。缺失 / 未知 / `tool_calls` → `unexpected_finish_reason`（content 非空也不当成功）。
+
+**达成：** 是。
+
+**核对：** `failure.go` 的 `classifyChoice` / `classifyArchiveChoice` / `decodeToolCallArgs`；`failure_test.go`。
+
+---
+
+### 截断（方案「截断」）
+
+**设计：** `ai.detail` ≤ 32KB；先收辅助字段，最后才动 `output` 和当前 `user_msg`。被收掉的写入 `_dropped`。
+
+**做了什么：** `builder-backend/internal/aiinteraction/detail.go`。空归档仍写出空的 `content` / `archive_content`，方便在 detail 里看到空结果。
+
+**达成：** 是。核对 `detail_test.go`。
+
+---
+
+## 切片 4 对照（方案「切片 4」）
+
+方案里「现状缺口」是改之前的旧描述，下面是改完后的状态。
+
+### 1. `empty_archive`
+
+| 方案 | 代码 |
+|---|---|
+| `stop` + 空 / 空白 → HTTP 失败 | `classifyArchiveChoice` |
+| `archive_failure` / `empty_archive` | 同函数；错误体经 `Failure` → `replyWithInnerError` |
+| upstream span error，detail 仍在 | `Archive` 先 `setArchiveAIDetail` 再 `finish(err)` |
+| 不改 Think outcome | Archive 独立 root |
+| 后端不 CaptureException | `startUpstreamSpan` |
+| 前端照常 retry，用尽 `retries_exhausted` | 切片 3 已有，切片 4 不改前端 |
+
+`no turns to archive` 仍是入参错误，不是 `empty_archive`。
+
+### 2. 细 reason
+
+`Interact`：`requiresToolCall(request) && len(tools) > 0` 传给 `callOpenAI` 和 `responseFromChoice`。失败续轮设 `tool_choice=required`。成功续轮可以只回文本。
+
+`callOpenAI` 不再把空 `finish_reason` 当传输错误；交给 `classifyChoice` 落 `unexpected_finish_reason`。
+
+### 3. Quota
+
+**未改合同。** 仍是 `ensureQuotaRemaining` → `HTTP 403` + `code=40301`，body 无 `category`。短窗仍是 `429` + `42901`。不给额度开 `ai.upstream`。其它 403（`40300`）前端不当额度。补了 `TestEnsureQuotaRemainingAIInteractionContract` / `TestQuotaErrorCodes`。
+
+---
+
+## 文件清单（只含方案相关）
+
+前端 `builder`：
+
+- 改：`ProjectRunner.vue`、`tracing.ts`、`sentry.ts`、`env.ts`、`.env` 示例项、`ai.go`、`command.go`、`transport.go`、`wasmtrans.go`、`ispx/ai.go`
+- 新：`SENTRY_PLAN.md`、本文件、`sentry_wasm.go`、`sentry_stub.go`、`sentry_context.go`、`classify.go`、`httperr.go`、`exception.go` 及对应 `*_test.go`
+
+后端 `builder-backend`：
+
+- 改：`aiinteraction.go`、`util.go`（错误体抄 Failure）及测试
+- 新：`failure.go`、`detail.go` 及测试
+
+---
+
+## 未做 / 不要当成缺口
+
+- 切片 5：生产采样率仍缺省 `1`；后端仍是全局 `SENTRY_SAMPLE_RATE`，未按 `/api/ai-interaction/*` 拆。
+- 精灵名未进 tag。
+- `sentry.ts` 的 development 早退保持原样（本地测过又还原了）。不要再注释掉提交。
+
+---
+
+## 建议怎么跑
+
+```text
+# 前端 WASM 侧
+cd builder/tools/ai && go test ./...
+
+# 后端
+cd builder-backend
+go test ./internal/aiinteraction/ ./cmd/xbuilder-backend/
+
+# 真机
+Sentry environment 选实际上报环境；搜 span.op:ai.think
+点根 span 看 outcome / category / reason
+Issues 搜 AIThinkFailure / AIArchiveFailure
+```
+
+改了 `tools/ai` 或 `tools/ispx` 后需要重编 wasm 再拷进 `spx-gui` 的 wasm 资源，否则父页面桥和 WASM 对不上。
diff --git a/tools/ai/SENTRY_PLAN.md b/tools/ai/SENTRY_PLAN.md
new file mode 100644
index 0000000000..381607a65d
--- /dev/null
+++ b/tools/ai/SENTRY_PLAN.md
@@ -0,0 +1,276 @@
+# AI Interaction Sentry 方案
+
+把 `Player.think`、传输、命令执行、归档和后端调模型接到 Sentry。
+
+看稳定性、慢在哪：靠 span 耗时，后端再加 `first_meaningful_delta_ms`。
+看质量差在哪：靠 `category` / `reason`；前端留命令现场，后端留模型 input/output。
+
+短字段进 tag，原始报错进 message，复现现场进 `ai.detail`。
+
+合同：[builder#3407](https://github.com/goplus/builder/pull/3407)、[builder-backend#326](https://github.com/goplus/builder-backend/pull/326)。实现对照（改了什么、去哪核对）：[SENTRY_IMPLEMENTATION.md](./SENTRY_IMPLEMENTATION.md)。
+
+已有基础：后端 HTTP 中间件会对请求 `ContinueTrace`；`callOpenAI` 已是流式拼阻塞，有意义 delta 的耗时已经能算；`llmsentry` 的上报模式可复用。切片 1–3（WASM 桥、Think / Archive 独立 root、终态 / exception）已落地。切片 4 对齐后端合同：细 reason、`empty_archive`、quota 边界。
+
+---
+
+## 链路
+
+```text
+Player.think → 多个 turn → 每 turn 多次 attempt
+  attempt = fetch = 后端 HTTP = 一次调模型
+Archive 独立进行，结果不改变 Think 的 outcome
+```
+
+每次 Think 自己开一条 root trace，和页面 pageload 分开。attempt 的 fetch 带上这条 Think 的 `Sentry-Trace` / `Baggage`，后端续在同一棵树上。Think 按 `ai.*` 自己采样，寿命跟这次交互走。
+
+```text
+ai.think                         # 独立 root，父页面 JS 创建
+  ├─ ai.transport.attempt        # 一次 Interact
+  │    └─ http.server            # 后端中间件（已有）
+  │         └─ ai.upstream
+  └─ ai.command.execute          # 填参数 → 调 handler → 返回
+
+ai.archive                       # 独立 root，不复用 Think 的 ctx header
+  └─ ai.archive.transport.attempt
+       └─ http.server
+            └─ ai.archive.upstream
+```
+
+SDK 在父页面。WASM 经桥通知 span 起止（带上 WASM 侧取好的时间戳）。`startThink` / `startArchive` 必须同步返回 `Sentry-Trace` / `Baggage`；其余桥方法 `setTimeout(0)`，避免同步调 Sentry 破坏 Go WASM 的 panic 栈。多 Player 并发时，trace 头放在对应 `context` 里（`TraceHeadersFromContext`），不要用全局变量。`game_session_id` 由 runner 开局注入，用来把同一局里多次 Think / Archive 收拢到一起。
+
+`reason` 在对应代码分支写入（`errors.As` / `errors.Is`），排查动作相同就共用一个。`model_response_invalid` 按下面优先级落到细 reason，不再用 `other` 当兜底。`upstream_failure` 仍只有 `timeout` / `provider_error`。
+
+---
+
+## 什么时候打 exception
+
+span 记录每一步做了什么、花了多久；失败的步骤标 `status=error`。
+exception 只在**这条流程停掉**时打一条，由停掉的那一侧上报，message 用原始 `err.Error()`。
+
+前端停 Think 时上报：timeout / network 重试用尽、缺初始 command、`turn_limit`、`handler_panic`、`invalid_arguments`。429 用尽和额度、取消不打 exception。
+前端停 Archive 时上报：非取消且 retry 用尽（`retries_exhausted`）。空归档是后端这一跳 HTTP 失败，前端仍按普通 Archive retry；用尽后还是这一条前端 exception。
+
+后端失败只把 span 标 error，并把 `{category, reason, request_id}` 放进 HTTP 错误体。后端 **不** `CaptureException`（含 `empty_archive`），避免前端 retry 打出多条 Issue。
+
+额度用完、用户取消、429 用尽，是预期结束，记在 `ai.think` 的 `outcome` 上。handler 返回普通 error（还能下一 turn）只体现在 command span 上。
+
+exception 带 `game_session_id`、`category`、`reason`。exception 全量保留；trace 按 `ai.*` / `/api/ai-interaction/*` 单独采样。
+
+后端把失败分类放进错误响应 `{category, reason, request_id}`，前端 transport span 打成 `backend_*` tag，同一条 Think 里就能看到失败落在哪一层。
+
+---
+
+## Span
+
+### `ai.think`
+
+tags：`game_session_id`、`outcome`、`turn_count`、`attempt_count`；`outcome=failure` 时加 `category`。
+
+| `outcome` | 含义 |
+|---|---|
+| `success` | 模型不再给 command，或 handler 返回 `Break` |
+| `cancelled` | 停游戏 / 中断（`ctx` 取消） |
+| `quota_exhausted` | 额度用完：HTTP `403` 且 JSON `code=40301` |
+| `rate_limited` | 429 重试用尽（attempt 标 error，不打 exception） |
+| `failure` | 失败终点，伴随一条 exception |
+
+`outcome` 只描述整次 Think 的结束方式。中途 command 被拒绝、后面仍正常结束的，仍是 `success`。`quota_exhausted` 发生在进入 `AIInteraction` 之前，没有 `ai.upstream`；attempt 上 `backend_reason` 为空。
+
+### `ai.transport.attempt`
+
+每次 `Transport.Interact`。tags：`turn_index`、`attempt`。失败标 span error，并把后端带回的 `backend_*` / `request_id` 打上。
+
+### `ai.command.execute`
+
+已注册的 command 进入 `callCommandHandler` 时创建，覆盖填参数到 handler 返回。tags：`command_name`、`turn_index`。
+
+handler 返回 `Break`：span 正常结束。
+handler 返回其它 error：span 标 error，`ErrorMessage` 进 detail；Think 继续。游戏里业务拒绝和模型胡来目前是同一种返回值，这一层只记执行结果。
+未注册的 command 没有 handler，结果写进 history，随下一轮 `ai.detail` 一起看。
+
+### `ai.upstream`
+
+每次调模型。tags：`request_id`。
+
+measurement：`first_meaningful_delta_ms`，从发出请求到第一个带 content 或 tool_call 的 delta。成功或失败，只要测到了都写；没测到这条 span 上就没有这个值。失败流若已经出过 meaningful delta，保留 TTFT 方便看卡在首包之后还是之前。
+
+`ai.detail`（context）成功失败都记：
+
+```text
+input:  user_msg, user_context, role, role_context,
+        knowledge_base, archived_history, history, command_specs
+output: finish_reason, content
+        解析成功：command_name, command_args
+        解析失败：tool_calls
+```
+
+`request_id` 放在 tag 上筛。`role` / `role_context` 放在 input 顶层，history 里只留各轮自己的消息和执行结果。`history` 末项的 `ExecutedCommandResult` 是上一 turn 的执行结果。
+
+### Archive
+
+独立 root `ai.archive`，包住整段 retry；每次 `Transport.Archive` 是 `ai.archive.transport.attempt`。`scheduleHistoryManagement` 开的是新 `spx.Go` ctx，`manageHistory` 里 `startArchive`，不从 Think 继承 header。
+
+前端 span 记耗时。没有 `ai.archive.outcome`。取消 / 额度结束 span、不打 exception。非取消 retry 用尽打一条 `archive_failure` / `retries_exhausted`。
+
+后端 `ai.archive.upstream` 同样有 `request_id` 和 `first_meaningful_delta_ms`。Archive 没有 tool call，正常结束必须是 `finish_reason=stop`。`stop` 但内容为空 / 空白归一化后为空：`empty_archive`。缺失、未知、或 `tool_calls`：`unexpected_finish_reason`，即使 content 非空也不当成功。detail：
+
+```text
+input:  existing_archive, turns
+output: archive_content, finish_reason, content
+```
+
+---
+
+## 分类
+
+前端 exception（`outcome=failure` 才打）：
+
+```text
+transport_failure        timeout | network
+model_quality_failure    missing_initial_command | invalid_arguments
+                         | turn_limit
+runtime_failure          handler_panic
+archive_failure          retries_exhausted
+```
+
+| reason | 判定 | 载体 | 额外 tags | detail |
+|---|---|---|---|---|
+| `timeout` | 超时包装错误且重试用尽 | exception | `turn_index`, `attempt` | `user_msg` |
+| `network` | 其余 transport 错误且重试用尽 | exception | `turn_index`, `attempt` | `user_msg` |
+| `missing_initial_command` | 空 command 且本 Think 从未执行过 command | exception | | `user_msg` |
+| `invalid_arguments` | 参数填充失败，Think 结束 | exception | `turn_index` | `command_name`, `command_args`, `user_msg` |
+| `turn_limit` | 跑满 maxTurns | exception | | `user_msg` |
+| `handler_panic` | handler panic（非 AbortThread） | exception | `turn_index` | `command_name`, `command_args` |
+| `retries_exhausted` | 归档重试用尽（含后端 `empty_archive` 被前端消化完） | exception | | `attempt_count`, `error` |
+
+不打 exception 的 Think 终点：`cancelled`、`quota_exhausted`（`403` 且 `code=40301`）、`rate_limited`（429 用尽）。后两者的 attempt 仍标 error。`rate_limited` 不是 Think 的 exception category。
+
+`unknown_command` 写入 history，随后续 turn 的 detail 排查。
+`invalid_arguments` 和 `handler_panic` 已在 command 出口分流。
+
+后端 span 带 `request_id` 和 `ai.detail`。失败走 HTTP 错误体 `{category, reason, request_id}`，**不** `CaptureException`。attempt 上的 `backend_*` 是后端原样，不当 Think 的 category。
+
+```text
+upstream_failure         timeout | provider_error
+model_response_invalid   见下表（HTTP 成功但 completion 按合同不能用）
+archive_failure          empty_archive
+```
+
+`upstream_failure` 只用于真正的传输 / API 错。`model_response_invalid` 按优先级落到细 reason，不再用 `other` 兜底。
+
+| 优先级 | reason | 判定 | 排查看 |
+|---|---|---|---|
+| 1 | `blocked` | Refusal 或 `finish_reason=content_filter` | 提示词 / 安全策略 |
+| 2 | `truncated` | `finish_reason=length` | maxTokens / prompt 过长 |
+| 3 | `no_choices` | choices 为空 | provider 空包 |
+| 4 | `missing_required_tool_call` | 本跳必须有 function call，但没有 | tool_choice / 提示 |
+| 5 | `invalid_tool_call` | 多 call、空 args、`null`、坏 JSON、尾随数据（第二次 Decode 必须 `io.EOF`，不能只看 `More()`） | `output.tool_calls` |
+| 6 | `unexpected_finish_reason` | finish_reason 未知 / 缺失 / 与 tool_calls 不匹配；流提前结束也归这里 | `output.finish_reason` |
+
+必须有 tool call 的跳：`ContinuationTurn == 0`（首轮），以及 history 末项 command 执行失败的续轮。成功续轮可以没有 tool call（模型收工，前端当 Think `success`）。现码 `callOpenAI(..., requiredToolCall)` 只在首轮为 true，切片 4 要补失败续轮。
+
+`empty_archive` 不属于 `model_response_invalid`，见切片 4。
+
+---
+
+## 截断
+
+整份 `ai.detail` ≤ 32KB。超出时先收 `knowledge_base`、`command_specs`、更早的 `history` / `turns`、`archived_history`，最后才动 `output` 和当前 `user_msg`。被收掉的字段写入 `_dropped`（带原始字节数）。
+
+| 字段 | 上限 |
+|---|---|
+| `user_msg` | 全文 |
+| `output` 单字段 | 16KB，解析失败时优先留 `tool_calls` |
+| `history` / `turns` | 16KB，从最近往前 |
+| `knowledge_base` / `role_context` / `user_context` / `archived_history` / `existing_archive` / `command_specs` | 各 4KB |
+| 前端 command + args | 合计 4KB |
+| `error` | 1KB |
+
+---
+
+## 切片
+
+1. **桥和 Think trace**（已落地）：桥函数、`game_session_id`、从 Think 取 Trace 头；`ai.think` / `ai.transport.attempt` / `ai.command.execute`。验收：Think 能连到后端 `http.server`，和页面 trace 分开。
+2. **后端 upstream**（已落地）：`ai.upstream` / `ai.archive.upstream`、`request_id`、`first_meaningful_delta_ms`、`ai.detail`；错误响应带粗分类。验收：同一次调模型的 input/output 能在这条 trace 上对上。
+3. **终态**（已落地）：按上表接 exception 和 `outcome`；`invalid_arguments` / `handler_panic` 分流。验收：`failure` 才打一条 exception；429 用尽 / 额度 / 取消不进 Issues。`outcome` 是自定义 span attribute，Explore 默认不索引，搜 `span.op:ai.think` 再点根 span 看 Attributes。SDK 自动打的 `category: ai` 不是切片 3 的 `transport_failure` 等。
+4. **合同对齐**（builder-backend#326，已落地）：细 reason、`empty_archive` 闭环、quota 边界。前端 `backend_*` 已能抄 attempt，切片 4 **不改前端**。切片 5 的采样、精灵名、还原 `sentry.ts` 早退仍不做。
+5. **采样**：上线后按量定 `ai.*` 采样率。
+
+---
+
+## 切片 4
+
+范围在 `builder-backend/internal/aiinteraction`。HTTP 层 `replyWithInnerError` 已经会把 `Failure.{Category,Reason,RequestID}` 抄进错误体，前端 attempt 已经打 `backend_*`。判定已按下列合同落地。
+
+### 现状缺口
+
+- `failure.go`：`no_choices` / 流提前结束落到 `model_response_invalid` + `other`；解析失败一律 `other`。没有 `blocked` / `truncated` / `invalid_tool_call` 等常量。
+- `responseFromChoice`：多 tool call 只取第一个；空 args 当成功；`json.Unmarshal` 不拒尾随数据，`"null"` 能解成 nil map。
+- `Interact`：`requiredToolCall` 仅 `ContinuationTurn == 0`。失败续轮模型可以只回文本，后端当成功。
+- `Archive`：空字符串 / 空白归一化后为空仍当成功返回。
+- quota 已在 `ensureQuotaRemaining`（进 `AIInteraction` 之前）回 `HTTP 403` + JSON `code=40301`，body 只有 `code` / `msg`。其它 403 不是额度。这是现合同，前端已按此识别。
+
+### 1. `empty_archive` 闭环
+
+`finish_reason=stop` 且内容为空字符串、或 `strings.TrimSpace` 后为空 → 不当成功。缺失 / 未知 / `tool_calls` 先走 `unexpected_finish_reason`，不落到 `empty_archive`。
+
+- HTTP 失败；`category=archive_failure`，`reason=empty_archive`。
+- `ai.archive.upstream` 标 error；`ai.detail` 仍写（能看到空 `content` / `finish_reason`）。
+- 错误体带 `{category, reason, request_id}`。
+- **不改** Think 的 `outcome`。Archive 本来就是独立 root。
+- 后端 **不** `CaptureException`（与切片 3「停掉才打、attempt 不打」一致；否则前端 retry 3 次会多条 Issue）。提交只保留这套约定，不要再写「后端上报 empty_archive exception」。
+- 前端仍按普通 Archive 失败 retry；用尽后还是一条 `archive_failure` / `retries_exhausted`。
+
+`no turns to archive` 仍是入参错误，不是 `empty_archive`。
+
+### 2. 细 reason：先匹配先生效
+
+在 `classifyCallError` / `responseFromChoice`（或并列的 completion 校验）里按分类表优先级判定，命中即停。不要再落到 `other`。
+
+`upstream_failure` 仍只有：
+
+- `timeout`：`context.DeadlineExceeded`、`net.Error.Timeout()`、上游 408 / 504。
+- `provider_error`：其余传输 / API 错（含上游 4xx/5xx、chunk id 不一致）。
+
+`model_response_invalid` 补全：
+
+- `blocked`：message Refusal，或 `finish_reason=content_filter`。
+- `truncated`：`finish_reason=length`（即使同时带着半截 tool call，也优先 `truncated`）。
+- `no_choices`：accumulator 无 choices。
+- `missing_required_tool_call`：本跳要求 function call 但 `ToolCalls` 为空。要求条件：首轮，或 history 末项 `ExecutedCommandResult != nil && !Success`。给这些跳设 `tool_choice=required`。
+- `invalid_tool_call`：多于一个 call；args 为空字符串；JSON `null`；无法解析；第一次 Decode 成功后第二次必须 `io.EOF`（`{"x":1}}` 这类 `More()` 看不出来的尾巴也算）。
+- `unexpected_finish_reason`：`finish_reason` 为空（流提前结束，现 `errStreamEndedEarly`）、未识别值、或与是否有 tool_calls 不匹配（例如 `stop` 却带 call、`tool_calls` 却没有 call）。Archive 没有 tool call，正常结束只能是 `stop`。不要再用 `other`。
+
+校验写在 span `finish(err)` 之前，这样 `ai.upstream` / `ai.archive.upstream` 的 status 和错误体一致。detail 成功失败都留。
+
+### 3. Quota 边界（不改合同）
+
+维持：`HTTP 403` + `code=40301`。短窗限流仍是 `429` + `42901`，前端走 `rate_limited`，不是额度。
+
+切片 4 **不** 给 quota 加 `category` / `reason` / `request_id`，**不** 改前端识别，**不** 给 quota 开 `ai.upstream`（根本没进 `AIInteraction`）。attempt 上可能有失败 fetch，但 `backend_reason` 为空。其它 403（例如 `40300`）不是额度，前端不当 `quota_exhausted`。
+
+只补测试和文档，把这条边界钉死。
+
+### 验收
+
+- 空归档：`stop` 且内容空 → 错误体 `archive_failure` / `empty_archive`，upstream span error，detail 在，无 Issue；Think 的 `outcome` 不变。
+- Archive 缺失 / 未知 / `tool_calls` 的 finish_reason → `unexpected_finish_reason`，即使 content 非空。
+- 各细 reason 有单测；错误体和 span tag 一致；不再出现 `reason=other`。
+- 流提前结束 → `unexpected_finish_reason`，不是 `other`。
+- 失败续轮无 tool call → `missing_required_tool_call`；成功续轮无 tool call → HTTP 成功。
+- 多 call / 空 args / `null` / 坏 JSON / 尾随数据（含 `{"x":1}}`）→ `invalid_tool_call`。
+- quota：`403` + `40301`，无 `category`；其它 403 不是额度。后端无 `CaptureException`。
+- 搜 Sentry 用 `span.op:ai.upstream` / `span.op:ai.archive.upstream`，点 Attributes 看 `reason`；不要用 Explore 默认字段搜自定义 attribute。
+
+---
+
+## 附录：实现锚点
+
+- 后端 Sentry：`cmd/xbuilder-backend/main.yap`；`ContinueTrace` 在 `cmd/xbuilder-backend/middleware.go`；上报模式见 `internal/tracer/llmsentry/sentry.go`。后端失败不 `CaptureException`。
+- 调模型：`internal/aiinteraction/aiinteraction.go` 的 `callOpenAI`；`request_id` 用 chunk id；有意义 delta 见 `chunkHasMeaningfulDelta`（成功失败只要测到都写 TTFT）。切片 4：`responseFromChoice` 改为校验而非「取第一个 call」；`Interact` 的 `requiredToolCall` 覆盖失败续轮；`Archive` 正常结束必须 `stop`，空内容走 `empty_archive`。
+- 分类：`internal/aiinteraction/failure.go`。删掉 `ReasonOther` 在 completion 校验上的兜底。quota 不经过这里，见 `cmd/xbuilder-backend/util.go` 的 `ensureQuotaRemaining`（`errorQuotaExceeded=40301`）。
+- 错误体：`cmd/xbuilder-backend/util.go` 的 `replyWithInnerError` 已抄 `Failure`；切片 4 不用改 HTTP 层。
+- 前端桥：`spx-gui/src/components/project/runner/ProjectRunner.vue`；`startThink` / `startArchive` 同步取 header，其余 `setTimeout(0)`（同文件 `handleRuntimePanic`）。Think / Archive 各自独立 root（可参考 LSP 按 operation 采样，页面 trace 继续自己结束）。
+- Trace 头：`startThink` / `startArchive` 把 `Sentry.getTraceData()` 写进 Go `context`；fetch 用 `TraceHeadersFromContext(ctx)`。写法参考 `spx-gui/src/apis/common/client.ts`。
+- 采样：前端 `spx-gui/src/setup/sentry.ts` 的 `tracesSampler`；后端按路由。切片 4 不改采样、不还原 development 早退。
+- 前端写入：`tools/ai/ai.go`（取消 → `cancelled`；quota → `quota_exhausted`；429 用尽 → `rate_limited`；timeout / network 用尽才 exception；缺初始 command；未知命令写 history；`invalid_arguments`；command span；`turn_limit`）；`tools/ai/command.go`（`ai.command.execute`、`handler_panic`）；`manageHistory` 重试用尽。切片 4 不改这些。
diff --git a/tools/ai/ai.go b/tools/ai/ai.go
index 5775eebf80..97333c2a89 100644
--- a/tools/ai/ai.go
+++ b/tools/ai/ai.go
@@ -126,21 +126,28 @@ func (p *Player) think(ctx stdContext.Context, owner any, msg string, context ma
 	)
 
 	p.beginInteraction()
+	thinkCtx := ctx
+	var finish thinkFinish
 	defer func() {
+		endThink(thinkCtx, finish)
 		p.endInteraction()
 		if ctx.Err() != nil {
 			return
 		}
 		p.scheduleHistoryManagement(owner)
 	}()
+	thinkCtx = startThink(ctx)
 
 	var (
 		currentMsg     = msg
 		currentContext = context
 
 		hasExecutedAtLeastOneCommandInThisCall bool
+		attemptCount                           int
+		lastAttempt                            int
 	)
 	for i := range maxTurns {
+		turnCount := i + 1
 		// Prepare request.
 		p.mu.RLock()
 		currentRole := p.role
@@ -176,29 +183,45 @@ func (p *Player) think(ctx stdContext.Context, owner any, msg string, context ma
 			lastErr  error
 			rateGate rateLimitGate
 		)
-		for range backoffAttempts(ctx, maxTransportAttempts, backoffBase, backoffCap) {
+		for attempt := range backoffAttempts(ctx, maxTransportAttempts, backoffBase, backoffCap) {
 			waitCtx, waitCancel := stdContext.WithTimeout(ctx, rateLimitWaitTimeout)
 			waitErr := rateGate.Wait(waitCtx)
 			waitCancel()
 			if waitErr != nil {
-				lastErr = fmt.Errorf("aborted due to excessive rate limit wait time (%s)", rateLimitWaitTimeout)
+				if ctx.Err() != nil {
+					lastErr = waitErr
+				} else {
+					lastErr = &TooManyRequestsError{
+						Err: fmt.Errorf("aborted due to excessive rate limit wait time (%s)", rateLimitWaitTimeout),
+					}
+				}
 				break
 			}
 
-			timeoutCtx, cancel := stdContext.WithTimeout(ctx, transportTimeout)
+			timeoutCtx, cancel := stdContext.WithTimeout(thinkCtx, transportTimeout)
+			startAttempt(timeoutCtx, i, attempt)
+			attemptCount++
+			lastAttempt = attempt
 			resp, lastErr = currentTransport.Interact(timeoutCtx, request)
+			lastErr = AnnotateTransportError(timeoutCtx, lastErr)
+			endAttempt(timeoutCtx, lastErr == nil, lastErr)
 			cancel()
 			if lastErr == nil {
 				break
 			}
+			if isQuotaExceeded(lastErr) {
+				break
+			}
 
 			rateGate.Observe(lastErr)
 		}
 		if err := ctx.Err(); err != nil {
+			finish = thinkFinish{outcome: outcomeCancelled}.withCounts(turnCount, attemptCount)
 			p.handleError(owner, fmt.Errorf("ai interaction canceled: %w", err))
 			return
 		}
 		if lastErr != nil {
+			finish = classifyTransportStop(lastErr).withCounts(turnCount, attemptCount).withException(msg, lastErr.Error(), i, lastAttempt, "", nil)
 			p.handleError(owner, fmt.Errorf("ai interaction failed after %d transport attempts: %w", maxTransportAttempts, lastErr))
 			return
 		}
@@ -216,7 +239,14 @@ func (p *Player) think(ctx stdContext.Context, owner any, msg string, context ma
 			p.appendHistory(noCmdTurn)
 
 			if !hasExecutedAtLeastOneCommandInThisCall {
+				finish = thinkFinish{
+					outcome:  outcomeFailure,
+					category: categoryModelQualityFailure,
+					reason:   reasonMissingInitialCommand,
+				}.withCounts(turnCount, attemptCount).withException(msg, "ai did not provide an initial command or any command during the interaction", i, lastAttempt, "", nil)
 				p.handleError(owner, errors.New("ai did not provide an initial command or any command during the interaction"))
+			} else {
+				finish = thinkFinish{outcome: outcomeSuccess}.withCounts(turnCount, attemptCount)
 			}
 			return
 		}
@@ -228,8 +258,9 @@ func (p *Player) think(ctx stdContext.Context, owner any, msg string, context ma
 		p.mu.RUnlock()
 		if ok {
 			var err error
-			executedResult, err = callCommandHandler(owner, cmdInfo, resp.CommandArgs)
+			executedResult, err = callCommandHandler(thinkCtx, owner, cmdInfo, resp.CommandArgs, i)
 			if err != nil {
+				finish = classifyCommandStopFinish(err).withCounts(turnCount, attemptCount).withException(msg, err.Error(), i, lastAttempt, commandNameFromError(err), resp.CommandArgs)
 				p.handleError(owner, fmt.Errorf("failed to execute command %s: %w", resp.CommandName, err))
 				return
 			}
@@ -257,6 +288,7 @@ func (p *Player) think(ctx stdContext.Context, owner any, msg string, context ma
 
 		// Check for [Break].
 		if executedResult.IsBreak {
+			finish = thinkFinish{outcome: outcomeSuccess}.withCounts(turnCount, attemptCount)
 			return
 		}
 
@@ -266,6 +298,11 @@ func (p *Player) think(ctx stdContext.Context, owner any, msg string, context ma
 		currentContext = nil
 	}
 
+	finish = thinkFinish{
+		outcome:  outcomeFailure,
+		category: categoryModelQualityFailure,
+		reason:   reasonTurnLimit,
+	}.withCounts(maxTurns, attemptCount).withException(msg, fmt.Sprintf("ai interaction did not complete within %d turns", maxTurns), maxTurns-1, lastAttempt, "", nil)
 	p.handleError(owner, fmt.Errorf("ai interaction did not complete within %d turns", maxTurns))
 }
 
@@ -359,41 +396,70 @@ func (p *Player) manageHistory(ctx stdContext.Context) {
 
 	// Perform archive with retries.
 	transport := p.transport()
+	archiveCtx := startArchive(ctx)
+	var finish archiveFinish
+	defer func() { endArchive(archiveCtx, finish) }()
 	var (
-		archived ArchivedHistory
-		lastErr  error
-		rateGate rateLimitGate
+		archived     ArchivedHistory
+		lastErr      error
+		rateGate     rateLimitGate
+		attemptCount int
 	)
-	for range backoffAttempts(ctx, maxArchiveAttempts, backoffBase, backoffCap) {
+	for attempt := range backoffAttempts(ctx, maxArchiveAttempts, backoffBase, backoffCap) {
 		waitCtx, waitCancel := stdContext.WithTimeout(ctx, rateLimitWaitTimeout)
 		waitErr := rateGate.Wait(waitCtx)
 		waitCancel()
 		if waitErr != nil {
-			lastErr = fmt.Errorf("aborted due to excessive rate limit wait time (%s)", rateLimitWaitTimeout)
+			if ctx.Err() != nil {
+				lastErr = waitErr
+			} else {
+				lastErr = &TooManyRequestsError{
+					Err: fmt.Errorf("aborted due to excessive rate limit wait time (%s)", rateLimitWaitTimeout),
+				}
+			}
 			break
 		}
 
-		archiveCtx, cancel := stdContext.WithTimeout(ctx, archiveTimeout)
-		archived, lastErr = transport.Archive(archiveCtx, turnsToArchive, existingArchive)
+		attemptCtx, cancel := stdContext.WithTimeout(archiveCtx, archiveTimeout)
+		startArchiveAttempt(attemptCtx, attempt)
+		attemptCount++
+		archived, lastErr = transport.Archive(attemptCtx, turnsToArchive, existingArchive)
+		lastErr = AnnotateTransportError(attemptCtx, lastErr)
+		endArchiveAttempt(attemptCtx, lastErr == nil, lastErr)
 		cancel()
 		if lastErr == nil {
 			break
 		}
+		if isQuotaExceeded(lastErr) {
+			break
+		}
 
 		rateGate.Observe(lastErr)
 	}
 	if err := ctx.Err(); err != nil {
+		finish = archiveFinish{attemptCount: attemptCount}
 		log.Printf("archive history canceled: %v", err)
 		p.cancelArchive()
 		return
 	}
+	if isQuotaExceeded(lastErr) {
+		finish = archiveFinish{attemptCount: attemptCount}
+		log.Printf("archive history stopped: %v", lastErr)
+		p.cancelArchive()
+		return
+	}
 	if lastErr != nil {
+		finish = archiveFinish{
+			captureException: true,
+			attemptCount:     attemptCount,
+			errMessage:       lastErr.Error(),
+		}
 		log.Printf("failed to archive history after %d attempts: %v", maxArchiveAttempts, lastErr)
 		p.cancelArchive()
 		return
 	}
 
-	// Apply the archive result.
+	finish = archiveFinish{ok: true, attemptCount: attemptCount}
 	p.applyArchive(archived.Content, len(turnsToArchive))
 }
 
diff --git a/tools/ai/ai_test.go b/tools/ai/ai_test.go
index 90a15b8a78..8e8fe65f34 100644
--- a/tools/ai/ai_test.go
+++ b/tools/ai/ai_test.go
@@ -2,6 +2,7 @@ package ai
 
 import (
 	"context"
+	"errors"
 	"reflect"
 	"slices"
 	"sync"
@@ -117,6 +118,44 @@ func TestPlayerThinkReportsTurnLimit(t *testing.T) {
 	}
 }
 
+func TestPlayerThinkQuotaExceededDoesNotRetry(t *testing.T) {
+	originalTransport := DefaultTransport()
+	t.Cleanup(func() { SetDefaultTransport(originalTransport) })
+
+	interactCalls := 0
+	SetDefaultTransport(&mockTransport{
+		InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+			interactCalls++
+			return Response{}, ErrorFromHTTPResponse(403, 0, `{"code":40301,"msg":"Quota exceeded"}`, errors.New("quota exceeded"))
+		},
+	})
+
+	errorCh := make(chan error, 1)
+	p := &Player{errorHandler: func(err error) { errorCh <- err }}
+	p.think(t.Context(), nil, "hello", nil)
+
+	if interactCalls != 1 {
+		t.Fatalf("got %d interact calls, want 1 (quota must not retry)", interactCalls)
+	}
+	select {
+	case err := <-errorCh:
+		if !isQuotaExceeded(err) {
+			t.Fatalf("error handler got %v, want quota exceeded", err)
+		}
+	default:
+		t.Fatal("quota did not trigger error handler")
+	}
+	if lastThinkFinish.outcome != outcomeQuotaExhausted {
+		t.Fatalf("outcome = %q, want %s", lastThinkFinish.outcome, outcomeQuotaExhausted)
+	}
+	if lastThinkFinish.attemptCount != 1 {
+		t.Fatalf("attemptCount = %d, want 1", lastThinkFinish.attemptCount)
+	}
+	if lastThinkFinish.shouldCaptureException() || lastThinkFinish.bridgeException("s") != nil {
+		t.Fatal("quota must not capture exception")
+	}
+}
+
 func TestPlayerAppendHistory(t *testing.T) {
 	for _, tt := range []struct {
 		name           string
diff --git a/tools/ai/archive_finish_test.go b/tools/ai/archive_finish_test.go
new file mode 100644
index 0000000000..2075020323
--- /dev/null
+++ b/tools/ai/archive_finish_test.go
@@ -0,0 +1,148 @@
+package ai
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+)
+
+func playerReadyToArchive() *Player {
+	history := make([]Turn, 30)
+	for i := range history {
+		history[i].IsInitial = i%10 == 0
+	}
+	return &Player{
+		errorHandler: func(error) {},
+		history:      history,
+	}
+}
+
+func TestPlayerArchiveFinish(t *testing.T) {
+	originalTransport := DefaultTransport()
+	t.Cleanup(func() { SetDefaultTransport(originalTransport) })
+
+	t.Run("Success", func(t *testing.T) {
+		lastArchiveFinish = archiveFinish{}
+		archiveCalls := 0
+		SetDefaultTransport(&mockTransport{
+			ArchiveFunc: func(_ context.Context, _ []Turn, _ string) (ArchivedHistory, error) {
+				archiveCalls++
+				return ArchivedHistory{Content: "ok"}, nil
+			},
+		})
+		p := playerReadyToArchive()
+		p.manageHistory(t.Context())
+		if archiveCalls != 1 {
+			t.Fatalf("archive calls = %d, want 1", archiveCalls)
+		}
+		if !lastArchiveFinish.ok || lastArchiveFinish.shouldCaptureException() {
+			t.Fatalf("got %+v", lastArchiveFinish)
+		}
+		if lastArchiveFinish.attemptCount != 1 {
+			t.Fatalf("attemptCount = %d", lastArchiveFinish.attemptCount)
+		}
+		if p.archivedHistory != "ok" {
+			t.Fatalf("archivedHistory = %q", p.archivedHistory)
+		}
+	})
+
+	t.Run("RetriesExhaustedCapturesOnce", func(t *testing.T) {
+		lastArchiveFinish = archiveFinish{}
+		archiveCalls := 0
+		SetDefaultTransport(&mockTransport{
+			ArchiveFunc: func(_ context.Context, _ []Turn, _ string) (ArchivedHistory, error) {
+				archiveCalls++
+				return ArchivedHistory{}, errors.New("archive boom")
+			},
+		})
+		p := playerReadyToArchive()
+		p.manageHistory(t.Context())
+		if archiveCalls != 3 {
+			t.Fatalf("archive calls = %d, want 3", archiveCalls)
+		}
+		if lastArchiveFinish.ok || !lastArchiveFinish.shouldCaptureException() {
+			t.Fatalf("got %+v", lastArchiveFinish)
+		}
+		if lastArchiveFinish.attemptCount != 3 {
+			t.Fatalf("attemptCount = %d", lastArchiveFinish.attemptCount)
+		}
+		payload := lastArchiveFinish.bridgeException("s")
+		if payload == nil {
+			t.Fatal("expected exception payload")
+		}
+		if payload["category"] != categoryArchiveFailure || payload["reason"] != reasonRetriesExhausted {
+			t.Fatalf("payload = %#v", payload)
+		}
+		if p.archiveInProgress {
+			t.Fatal("archiveInProgress should be cleared")
+		}
+	})
+
+	t.Run("QuotaNoException", func(t *testing.T) {
+		lastArchiveFinish = archiveFinish{}
+		archiveCalls := 0
+		SetDefaultTransport(&mockTransport{
+			ArchiveFunc: func(_ context.Context, _ []Turn, _ string) (ArchivedHistory, error) {
+				archiveCalls++
+				return ArchivedHistory{}, &QuotaExceededError{Err: errors.New("quota exceeded")}
+			},
+		})
+		p := playerReadyToArchive()
+		p.manageHistory(t.Context())
+		if archiveCalls != 1 {
+			t.Fatalf("archive calls = %d, want 1", archiveCalls)
+		}
+		if lastArchiveFinish.ok || lastArchiveFinish.shouldCaptureException() {
+			t.Fatalf("quota must not capture, got %+v", lastArchiveFinish)
+		}
+		if lastArchiveFinish.bridgeException("s") != nil {
+			t.Fatal("quota must not have exception payload")
+		}
+		if lastArchiveFinish.attemptCount != 1 {
+			t.Fatalf("attemptCount = %d", lastArchiveFinish.attemptCount)
+		}
+	})
+
+	t.Run("CancelledNoException", func(t *testing.T) {
+		lastArchiveFinish = archiveFinish{}
+		SetDefaultTransport(&mockTransport{
+			ArchiveFunc: func(_ context.Context, _ []Turn, _ string) (ArchivedHistory, error) {
+				t.Fatal("Archive should not run on cancelled context")
+				return ArchivedHistory{}, nil
+			},
+		})
+		ctx, cancel := context.WithCancel(t.Context())
+		cancel()
+		p := playerReadyToArchive()
+		p.manageHistory(ctx)
+		if lastArchiveFinish.ok || lastArchiveFinish.shouldCaptureException() {
+			t.Fatalf("cancel must not capture, got %+v", lastArchiveFinish)
+		}
+		if lastArchiveFinish.bridgeException("s") != nil {
+			t.Fatal("cancel must not have exception payload")
+		}
+	})
+
+	t.Run("RateLimitedRetriesExhaustedCaptures", func(t *testing.T) {
+		lastArchiveFinish = archiveFinish{}
+		archiveCalls := 0
+		SetDefaultTransport(&mockTransport{
+			ArchiveFunc: func(_ context.Context, _ []Turn, _ string) (ArchivedHistory, error) {
+				archiveCalls++
+				return ArchivedHistory{}, &TooManyRequestsError{RetryAfter: time.Millisecond, Err: errors.New("429")}
+			},
+		})
+		p := playerReadyToArchive()
+		p.manageHistory(t.Context())
+		if archiveCalls != 3 {
+			t.Fatalf("archive calls = %d, want 3", archiveCalls)
+		}
+		if !lastArchiveFinish.shouldCaptureException() {
+			t.Fatal("archive 429 exhausted must capture")
+		}
+		if lastArchiveFinish.attemptCount != 3 {
+			t.Fatalf("attemptCount = %d", lastArchiveFinish.attemptCount)
+		}
+	})
+}
diff --git a/tools/ai/classify.go b/tools/ai/classify.go
new file mode 100644
index 0000000000..a85a5e09a7
--- /dev/null
+++ b/tools/ai/classify.go
@@ -0,0 +1,149 @@
+package ai
+
+import "errors"
+
+// Frontend exception category / reason values from SENTRY_PLAN.
+// backend_category on transport attempts is a separate namespace.
+const (
+	categoryTransportFailure    = "transport_failure"
+	categoryModelQualityFailure = "model_quality_failure"
+	categoryRuntimeFailure      = "runtime_failure"
+	categoryArchiveFailure      = "archive_failure"
+
+	outcomeSuccess        = "success"
+	outcomeCancelled      = "cancelled"
+	outcomeQuotaExhausted = "quota_exhausted"
+	outcomeRateLimited    = "rate_limited"
+	outcomeFailure        = "failure"
+
+	reasonInvalidArguments      = "invalid_arguments"
+	reasonHandlerPanic          = "handler_panic"
+	reasonTimeout               = "timeout"
+	reasonNetwork               = "network"
+	reasonMissingInitialCommand = "missing_initial_command"
+	reasonTurnLimit             = "turn_limit"
+	reasonOther                 = "other"
+	reasonRetriesExhausted      = "retries_exhausted"
+)
+
+// thinkFinish is the terminal state sent once through endThink.
+type thinkFinish struct {
+	outcome      string
+	category     string
+	reason       string
+	turnCount    int
+	attemptCount int
+	turnIndex    int
+	lastAttempt  int
+	userMsg      string
+	commandName  string
+	commandArgs  map[string]any
+	errMessage   string
+}
+
+func (f thinkFinish) withCounts(turnCount, attemptCount int) thinkFinish {
+	f.turnCount = turnCount
+	f.attemptCount = attemptCount
+	return f
+}
+
+// invalidArgumentsError is returned when command args cannot populate the
+// handler struct. Think stops; Sentry reason is invalid_arguments.
+type invalidArgumentsError struct {
+	command string
+	err     error
+}
+
+func (e *invalidArgumentsError) Error() string {
+	if e == nil || e.err == nil {
+		return ""
+	}
+	return e.err.Error()
+}
+
+func (e *invalidArgumentsError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.err
+}
+
+// handlerPanicError is returned when a command handler panics (other than
+// AbortThread). Think stops; Sentry reason is handler_panic.
+type handlerPanicError struct {
+	command string
+	err     error
+}
+
+func (e *handlerPanicError) Error() string {
+	if e == nil || e.err == nil {
+		return ""
+	}
+	return e.err.Error()
+}
+
+func (e *handlerPanicError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.err
+}
+
+func isInvalidArguments(err error) bool {
+	var typed *invalidArgumentsError
+	return errors.As(err, &typed)
+}
+
+func isHandlerPanic(err error) bool {
+	var typed *handlerPanicError
+	return errors.As(err, &typed)
+}
+
+func commandNameFromError(err error) string {
+	var argsErr *invalidArgumentsError
+	if errors.As(err, &argsErr) {
+		return argsErr.command
+	}
+	var panicErr *handlerPanicError
+	if errors.As(err, &panicErr) {
+		return panicErr.command
+	}
+	return ""
+}
+
+func classifyCommandStop(err error) (category, reason string, ok bool) {
+	switch {
+	case isInvalidArguments(err):
+		return categoryModelQualityFailure, reasonInvalidArguments, true
+	case isHandlerPanic(err):
+		return categoryRuntimeFailure, reasonHandlerPanic, true
+	default:
+		return "", "", false
+	}
+}
+
+func isTooManyRequests(err error) bool {
+	var typed *TooManyRequestsError
+	return errors.As(err, &typed)
+}
+
+func classifyTransportStop(err error) thinkFinish {
+	switch {
+	case isQuotaExceeded(err):
+		return thinkFinish{outcome: outcomeQuotaExhausted}
+	case isTooManyRequests(err):
+		return thinkFinish{outcome: outcomeRateLimited}
+	case isTransportTimeout(err):
+		return thinkFinish{outcome: outcomeFailure, category: categoryTransportFailure, reason: reasonTimeout}
+	default:
+		return thinkFinish{outcome: outcomeFailure, category: categoryTransportFailure, reason: reasonNetwork}
+	}
+}
+
+func classifyCommandStopFinish(err error) thinkFinish {
+	category, reason, ok := classifyCommandStop(err)
+	if !ok {
+		return thinkFinish{outcome: outcomeFailure, category: categoryRuntimeFailure, reason: reasonOther}
+	}
+	return thinkFinish{outcome: outcomeFailure, category: category, reason: reason}
+}
diff --git a/tools/ai/classify_test.go b/tools/ai/classify_test.go
new file mode 100644
index 0000000000..40d9c116e0
--- /dev/null
+++ b/tools/ai/classify_test.go
@@ -0,0 +1,117 @@
+package ai
+
+import (
+	"errors"
+	"fmt"
+	"reflect"
+	"testing"
+)
+
+type classifyMoveCmd struct {
+	Direction string
+	Steps     int
+	Speed     float64
+}
+
+func classifyMoveInfo(handler any) commandInfo {
+	typ := reflect.TypeOf(classifyMoveCmd{})
+	if handler == nil {
+		handler = func(classifyMoveCmd) error { return nil }
+	}
+	return commandInfo{
+		typ:     typ,
+		handler: handler,
+		spec:    extractCommandSpec(typ),
+	}
+}
+
+func TestClassifyCommandStopFromHandler(t *testing.T) {
+	t.Run("InvalidArguments", func(t *testing.T) {
+		_, err := callCommandHandler(t.Context(), nil, classifyMoveInfo(nil), map[string]any{
+			"Direction": "up",
+			"Steps":     "1",
+			"Speed":     1.0,
+		}, 0)
+		if err == nil {
+			t.Fatal("expected error")
+		}
+		if !isInvalidArguments(err) {
+			t.Fatalf("isInvalidArguments() = false, err=%v", err)
+		}
+		if isHandlerPanic(err) {
+			t.Fatal("typed as handler panic")
+		}
+		if got := commandNameFromError(err); got != "classifyMoveCmd" {
+			t.Fatalf("commandNameFromError() = %q", got)
+		}
+		category, reason, ok := classifyCommandStop(err)
+		if !ok || category != categoryModelQualityFailure || reason != reasonInvalidArguments {
+			t.Fatalf("classifyCommandStop() = %q, %q, %v", category, reason, ok)
+		}
+	})
+
+	t.Run("HandlerPanic", func(t *testing.T) {
+		info := classifyMoveInfo(func(classifyMoveCmd) error {
+			panic("intentional panic in test")
+		})
+		_, err := callCommandHandler(t.Context(), nil, info, map[string]any{
+			"Direction": "up",
+			"Steps":     1,
+			"Speed":     1.0,
+		}, 0)
+		if err == nil {
+			t.Fatal("expected error")
+		}
+		if !isHandlerPanic(err) {
+			t.Fatalf("isHandlerPanic() = false, err=%v", err)
+		}
+		if isInvalidArguments(err) {
+			t.Fatal("typed as invalid arguments")
+		}
+		if got := commandNameFromError(err); got != "classifyMoveCmd" {
+			t.Fatalf("commandNameFromError() = %q", got)
+		}
+		category, reason, ok := classifyCommandStop(err)
+		if !ok || category != categoryRuntimeFailure || reason != reasonHandlerPanic {
+			t.Fatalf("classifyCommandStop() = %q, %q, %v", category, reason, ok)
+		}
+	})
+
+	t.Run("HandlerErrorIsNotAStopType", func(t *testing.T) {
+		info := classifyMoveInfo(func(classifyMoveCmd) error {
+			return errors.New("test handler error")
+		})
+		result, err := callCommandHandler(t.Context(), nil, info, map[string]any{
+			"Direction": "up",
+			"Steps":     1,
+			"Speed":     1.0,
+		}, 0)
+		if err != nil {
+			t.Fatalf("unexpected error %v", err)
+		}
+		if result == nil || result.Success {
+			t.Fatalf("want unsuccessful result, got %#v", result)
+		}
+		if _, _, ok := classifyCommandStop(err); ok {
+			t.Fatal("handler error must not classify as a Think stop")
+		}
+	})
+}
+
+func TestClassifyCommandStopUnwraps(t *testing.T) {
+	inner := &invalidArgumentsError{
+		command: "GoTo",
+		err:     errors.New("failed to populate command fields for GoTo: type mismatch"),
+	}
+	wrapped := fmt.Errorf("failed to execute command GoTo: %w", inner)
+	if !isInvalidArguments(wrapped) {
+		t.Fatal("isInvalidArguments() must see through fmt.Errorf %%w")
+	}
+	category, reason, ok := classifyCommandStop(wrapped)
+	if !ok || category != categoryModelQualityFailure || reason != reasonInvalidArguments {
+		t.Fatalf("classifyCommandStop() = %q, %q, %v", category, reason, ok)
+	}
+	if got := commandNameFromError(wrapped); got != "GoTo" {
+		t.Fatalf("commandNameFromError() = %q", got)
+	}
+}
diff --git a/tools/ai/command.go b/tools/ai/command.go
index 5c3b548b34..791bdbb9c7 100644
--- a/tools/ai/command.go
+++ b/tools/ai/command.go
@@ -90,15 +90,30 @@ func extractCommandSpec(cmdType reflect.Type) CommandSpec {
 // callCommandHandler handles the overall logic for executing a command
 // handler. It creates the command struct, populates its fields, calls the
 // handler, and processes the result.
-func callCommandHandler(owner any, info commandInfo, args map[string]any) (*CommandResult, error) {
+func callCommandHandler(ctx context.Context, owner any, info commandInfo, args map[string]any, turnIndex int) (result *CommandResult, err error) {
+	startCommand(ctx, turnIndex, info.spec.Name)
+	spanOK := false
+	defer func() {
+		errText := ""
+		if err != nil {
+			errText = err.Error()
+		} else if result != nil && result.ErrorMessage != "" {
+			errText = result.ErrorMessage
+		}
+		endCommand(ctx, spanOK, errText)
+	}()
+
 	// Create a new zero value of the command struct type (T).
 	cmdType := info.typ
 	cmdPtrVal := reflect.New(cmdType)
 	cmdVal := cmdPtrVal.Elem()
 
 	// Populate struct fields from args.
-	if err := populateCommandFields(cmdVal, args); err != nil {
-		return nil, fmt.Errorf("failed to populate command fields for %s: %w", info.spec.Name, err)
+	if popErr := populateCommandFields(cmdVal, args); popErr != nil {
+		return nil, &invalidArgumentsError{
+			command: info.spec.Name,
+			err:     fmt.Errorf("failed to populate command fields for %s: %w", info.spec.Name, popErr),
+		}
 	}
 
 	// Call the actual handler function.
@@ -119,7 +134,10 @@ func callCommandHandler(owner any, info commandInfo, args map[string]any) (*Comm
 		}(reflect.ValueOf(info.handler))
 	})
 	if handlerCallErr != nil {
-		return nil, fmt.Errorf("failed to call command handler for %s: %w", info.spec.Name, handlerCallErr)
+		return nil, &handlerPanicError{
+			command: info.spec.Name,
+			err:     fmt.Errorf("failed to call command handler for %s: %w", info.spec.Name, handlerCallErr),
+		}
 	}
 
 	// Process handler results.
@@ -135,7 +153,7 @@ func callCommandHandler(owner any, info commandInfo, args map[string]any) (*Comm
 	}
 
 	// Construct [CommandResult] based on handlerErr.
-	result := &CommandResult{}
+	result = &CommandResult{}
 	if handlerErr == nil {
 		result.Success = true
 	} else if errors.Is(handlerErr, Break) {
@@ -145,6 +163,7 @@ func callCommandHandler(owner any, info commandInfo, args map[string]any) (*Comm
 		result.Success = false
 		result.ErrorMessage = handlerErr.Error()
 	}
+	spanOK = result.Success
 	return result, nil
 }
 
diff --git a/tools/ai/command_test.go b/tools/ai/command_test.go
index 66d82a0844..761fe03349 100644
--- a/tools/ai/command_test.go
+++ b/tools/ai/command_test.go
@@ -1,6 +1,7 @@
 package ai
 
 import (
+	"context"
 	"errors"
 	"math"
 	"reflect"
@@ -250,7 +251,7 @@ func TestCallCommandHandler(t *testing.T) {
 			if tt.handlerFunc != nil {
 				info.handler = tt.handlerFunc
 			}
-			result, err := callCommandHandler(nil, info, tt.args)
+			result, err := callCommandHandler(context.Background(), nil, info, tt.args, 0)
 			if tt.wantErr {
 				if err == nil {
 					t.Fatal("expected error")
diff --git a/tools/ai/exception.go b/tools/ai/exception.go
new file mode 100644
index 0000000000..358e89002f
--- /dev/null
+++ b/tools/ai/exception.go
@@ -0,0 +1,102 @@
+package ai
+
+import (
+	"encoding/json"
+	"unicode/utf8"
+)
+
+const (
+	maxExceptionErrorBytes = 1024
+	maxCommandDetailBytes  = 4096
+)
+
+func (f thinkFinish) shouldCaptureException() bool {
+	return f.outcome == outcomeFailure
+}
+
+func (f thinkFinish) withException(userMsg, errMessage string, turnIndex, lastAttempt int, commandName string, commandArgs map[string]any) thinkFinish {
+	f.userMsg = userMsg
+	f.errMessage = errMessage
+	f.turnIndex = turnIndex
+	f.lastAttempt = lastAttempt
+	f.commandName = commandName
+	f.commandArgs = commandArgs
+	return f
+}
+
+func (f thinkFinish) bridgeException(gameSessionID string) map[string]any {
+	if !f.shouldCaptureException() {
+		return nil
+	}
+	commandName, argsJSON := commandDetail(f.commandName, f.commandArgs)
+	return map[string]any{
+		"message":       truncateBytes(f.errMessage, maxExceptionErrorBytes),
+		"userMsg":       f.userMsg,
+		"commandName":   commandName,
+		"commandArgs":   argsJSON,
+		"turnIndex":     f.turnIndex,
+		"attempt":       f.lastAttempt,
+		"category":      f.category,
+		"reason":        f.reason,
+		"gameSessionId": gameSessionID,
+	}
+}
+
+func truncateBytes(s string, max int) string {
+	if max <= 0 || len(s) <= max {
+		return s
+	}
+	s = s[:max]
+	for len(s) > 0 && !utf8.ValidString(s) {
+		s = s[:len(s)-1]
+	}
+	return s
+}
+
+func commandDetail(name string, args map[string]any) (string, string) {
+	var argsJSON string
+	if args != nil {
+		raw, err := json.Marshal(args)
+		if err != nil {
+			argsJSON = "{}"
+		} else {
+			argsJSON = string(raw)
+		}
+	}
+	if len(name)+len(argsJSON) <= maxCommandDetailBytes {
+		return name, argsJSON
+	}
+	room := maxCommandDetailBytes - len(name)
+	if room < 0 {
+		return truncateBytes(name, maxCommandDetailBytes), ""
+	}
+	return name, truncateBytes(argsJSON, room)
+}
+
+// archiveFinish is the terminal state sent once through endArchive.
+// Archive has no outcome field.
+type archiveFinish struct {
+	ok               bool
+	captureException bool
+	attemptCount     int
+	errMessage       string
+}
+
+func (f archiveFinish) shouldCaptureException() bool {
+	return f.captureException
+}
+
+func (f archiveFinish) bridgeException(gameSessionID string) map[string]any {
+	if !f.shouldCaptureException() {
+		return nil
+	}
+	errText := truncateBytes(f.errMessage, maxExceptionErrorBytes)
+	return map[string]any{
+		"message":       errText,
+		"error":         errText,
+		"attemptCount":  f.attemptCount,
+		"category":      categoryArchiveFailure,
+		"reason":        reasonRetriesExhausted,
+		"gameSessionId": gameSessionID,
+	}
+}
diff --git a/tools/ai/exception_test.go b/tools/ai/exception_test.go
new file mode 100644
index 0000000000..e5c51da0b2
--- /dev/null
+++ b/tools/ai/exception_test.go
@@ -0,0 +1,154 @@
+package ai
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestThinkFinishShouldCaptureException(t *testing.T) {
+	if (thinkFinish{outcome: outcomeFailure}).shouldCaptureException() != true {
+		t.Fatal("failure must capture")
+	}
+	for _, outcome := range []string{outcomeSuccess, outcomeCancelled, outcomeQuotaExhausted, outcomeRateLimited} {
+		if (thinkFinish{outcome: outcome}).shouldCaptureException() {
+			t.Fatalf("%s must not capture", outcome)
+		}
+	}
+}
+
+func TestBridgeExceptionNilWhenNotFailure(t *testing.T) {
+	finish := thinkFinish{outcome: outcomeRateLimited, errMessage: "429"}
+	if payload := finish.bridgeException("sess"); payload != nil {
+		t.Fatalf("got %#v", payload)
+	}
+}
+
+func TestBridgeExceptionPayload(t *testing.T) {
+	finish := thinkFinish{
+		outcome:     outcomeFailure,
+		category:    categoryTransportFailure,
+		reason:      reasonTimeout,
+		userMsg:     "hello",
+		errMessage:  strings.Repeat("x", maxExceptionErrorBytes+50),
+		turnIndex:   2,
+		lastAttempt: 1,
+	}
+	payload := finish.bridgeException("game-1")
+	if payload == nil {
+		t.Fatal("expected payload")
+	}
+	if payload["gameSessionId"] != "game-1" {
+		t.Fatalf("gameSessionId = %v", payload["gameSessionId"])
+	}
+	if payload["reason"] != reasonTimeout {
+		t.Fatalf("reason = %v", payload["reason"])
+	}
+	msg, _ := payload["message"].(string)
+	if len(msg) != maxExceptionErrorBytes {
+		t.Fatalf("message len = %d, want %d", len(msg), maxExceptionErrorBytes)
+	}
+	if payload["userMsg"] != "hello" {
+		t.Fatalf("userMsg = %v", payload["userMsg"])
+	}
+}
+
+func TestArchiveFinishShouldCaptureException(t *testing.T) {
+	if !(archiveFinish{captureException: true}).shouldCaptureException() {
+		t.Fatal("retries exhausted must capture")
+	}
+	if (archiveFinish{}).shouldCaptureException() {
+		t.Fatal("success / cancel / quota must not capture")
+	}
+	if (archiveFinish{ok: true, attemptCount: 1}).shouldCaptureException() {
+		t.Fatal("success must not capture")
+	}
+}
+
+func TestArchiveBridgeExceptionPayload(t *testing.T) {
+	if payload := (archiveFinish{errMessage: "boom"}).bridgeException("sess"); payload != nil {
+		t.Fatalf("non-failure got %#v", payload)
+	}
+	finish := archiveFinish{
+		captureException: true,
+		attemptCount:     3,
+		errMessage:       strings.Repeat("y", maxExceptionErrorBytes+20),
+	}
+	payload := finish.bridgeException("game-2")
+	if payload == nil {
+		t.Fatal("expected payload")
+	}
+	if payload["category"] != categoryArchiveFailure {
+		t.Fatalf("category = %v", payload["category"])
+	}
+	if payload["reason"] != reasonRetriesExhausted {
+		t.Fatalf("reason = %v", payload["reason"])
+	}
+	if payload["attemptCount"] != 3 {
+		t.Fatalf("attemptCount = %v", payload["attemptCount"])
+	}
+	if payload["gameSessionId"] != "game-2" {
+		t.Fatalf("gameSessionId = %v", payload["gameSessionId"])
+	}
+	msg, _ := payload["message"].(string)
+	if len(msg) != maxExceptionErrorBytes {
+		t.Fatalf("message len = %d, want %d", len(msg), maxExceptionErrorBytes)
+	}
+	if payload["error"] != msg {
+		t.Fatalf("error = %v, want same as message", payload["error"])
+	}
+}
+
+func TestCommandDetailTruncation(t *testing.T) {
+	args := map[string]any{"note": strings.Repeat("n", maxCommandDetailBytes)}
+	name, encoded := commandDetail("GoTo", args)
+	if name != "GoTo" {
+		t.Fatalf("name = %q", name)
+	}
+	if len(name)+len(encoded) > maxCommandDetailBytes {
+		t.Fatalf("command+args = %d, want <= %d", len(name)+len(encoded), maxCommandDetailBytes)
+	}
+}
+
+func TestPlayerThinkFailureCapturesAndExpectedDoesNot(t *testing.T) {
+	originalTransport := DefaultTransport()
+	t.Cleanup(func() { SetDefaultTransport(originalTransport) })
+
+	t.Run("MissingCommand", func(t *testing.T) {
+		lastThinkFinish = thinkFinish{}
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{Text: "hi"}, nil
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		p.think(t.Context(), nil, "user says hi", nil)
+		if !lastThinkFinish.shouldCaptureException() {
+			t.Fatal("missing command should capture")
+		}
+		if lastThinkFinish.userMsg != "user says hi" {
+			t.Fatalf("userMsg = %q", lastThinkFinish.userMsg)
+		}
+		if lastThinkFinish.bridgeException("s") == nil {
+			t.Fatal("expected exception payload")
+		}
+	})
+
+	t.Run("RateLimited", func(t *testing.T) {
+		lastThinkFinish = thinkFinish{}
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{}, &TooManyRequestsError{Err: errors.New("429")}
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		p.think(t.Context(), nil, "hello", nil)
+		if lastThinkFinish.shouldCaptureException() {
+			t.Fatal("429 must not capture")
+		}
+		if lastThinkFinish.bridgeException("s") != nil {
+			t.Fatal("429 must not have exception payload")
+		}
+	})
+}
diff --git a/tools/ai/finish_once_test.go b/tools/ai/finish_once_test.go
new file mode 100644
index 0000000000..1f8ad35f0f
--- /dev/null
+++ b/tools/ai/finish_once_test.go
@@ -0,0 +1,356 @@
+package ai
+
+import (
+	"context"
+	"errors"
+	"reflect"
+	"testing"
+	"time"
+)
+
+func assertOneThinkFinish(t *testing.T, capture bool) {
+	t.Helper()
+	if thinkFinishCount != 1 {
+		t.Fatalf("endThink calls = %d, want 1", thinkFinishCount)
+	}
+	if lastThinkFinish.shouldCaptureException() != capture {
+		t.Fatalf("capture = %v, want %v, finish=%+v", lastThinkFinish.shouldCaptureException(), capture, lastThinkFinish)
+	}
+	payload := lastThinkFinish.bridgeException("sess")
+	if capture && payload == nil {
+		t.Fatal("expected one exception payload")
+	}
+	if !capture && payload != nil {
+		t.Fatalf("unexpected exception payload %#v", payload)
+	}
+}
+
+func assertOneArchiveFinish(t *testing.T, capture bool) {
+	t.Helper()
+	if archiveFinishCount != 1 {
+		t.Fatalf("endArchive calls = %d, want 1", archiveFinishCount)
+	}
+	if lastArchiveFinish.shouldCaptureException() != capture {
+		t.Fatalf("archive capture = %v, want %v, finish=%+v", lastArchiveFinish.shouldCaptureException(), capture, lastArchiveFinish)
+	}
+	payload := lastArchiveFinish.bridgeException("sess")
+	if capture && payload == nil {
+		t.Fatal("expected one archive exception payload")
+	}
+	if !capture && payload != nil {
+		t.Fatalf("unexpected archive exception payload %#v", payload)
+	}
+}
+
+func TestSlice3FinishOnce(t *testing.T) {
+	originalTransport := DefaultTransport()
+	t.Cleanup(func() { SetDefaultTransport(originalTransport) })
+
+	t.Run("Quota40301NoRetryNoException", func(t *testing.T) {
+		resetSentryStub()
+		interactCalls := 0
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				interactCalls++
+				return Response{}, ErrorFromHTTPResponse(403, 0, `{"code":40301,"msg":"Quota exceeded","request_id":"q-1"}`, errors.New("quota exceeded"))
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		p.think(t.Context(), nil, "hello", nil)
+		if interactCalls != 1 {
+			t.Fatalf("interact calls = %d, want 1", interactCalls)
+		}
+		if lastThinkFinish.outcome != outcomeQuotaExhausted {
+			t.Fatalf("outcome = %q", lastThinkFinish.outcome)
+		}
+		if lastThinkFinish.category != "" || lastThinkFinish.reason != "" {
+			t.Fatalf("quota must not set failure category, got %+v", lastThinkFinish)
+		}
+		assertOneThinkFinish(t, false)
+		if len(lastAttempts) != 1 {
+			t.Fatalf("attempts = %d, want 1", len(lastAttempts))
+		}
+		if lastAttempts[0].ok {
+			t.Fatal("quota attempt should be marked error")
+		}
+	})
+
+	t.Run("Other403RetriesAsNetworkFailure", func(t *testing.T) {
+		resetSentryStub()
+		interactCalls := 0
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				interactCalls++
+				return Response{}, ErrorFromHTTPResponse(403, 0, `{"code":40300,"msg":"Forbidden"}`, errors.New("forbidden"))
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		p.think(t.Context(), nil, "hello", nil)
+		if interactCalls != 3 {
+			t.Fatalf("interact calls = %d, want 3", interactCalls)
+		}
+		if lastThinkFinish.outcome != outcomeFailure || lastThinkFinish.reason != reasonNetwork {
+			t.Fatalf("got %+v", lastThinkFinish)
+		}
+		if isQuotaExceeded(ErrorFromHTTPResponse(403, 0, `{"code":40300,"msg":"Forbidden"}`, errors.New("forbidden"))) {
+			t.Fatal("40300 must not be quota")
+		}
+		assertOneThinkFinish(t, true)
+	})
+
+	t.Run("BackendTagsStayOnAttempt", func(t *testing.T) {
+		resetSentryStub()
+		body := `{"code":50000,"msg":"Internal","category":"upstream_failure","reason":"timeout","request_id":"req-xyz"}`
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{}, ErrorFromHTTPResponse(500, 0, body, errors.New("upstream"))
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		p.think(t.Context(), nil, "hello", nil)
+		if len(lastAttempts) != 3 {
+			t.Fatalf("attempts = %d, want 3", len(lastAttempts))
+		}
+		for i, attempt := range lastAttempts {
+			if attempt.ok {
+				t.Fatalf("attempt %d unexpectedly ok", i)
+			}
+			if attempt.category != "upstream_failure" || attempt.reason != "timeout" || attempt.requestID != "req-xyz" {
+				t.Fatalf("attempt %d backend tags = %+v", i, attempt)
+			}
+		}
+		if lastThinkFinish.category != categoryTransportFailure || lastThinkFinish.reason != reasonNetwork {
+			t.Fatalf("Think must use frontend category, got %+v", lastThinkFinish)
+		}
+		payload := lastThinkFinish.bridgeException("sess")
+		if payload["category"] != categoryTransportFailure {
+			t.Fatalf("exception category = %v", payload["category"])
+		}
+		assertOneThinkFinish(t, true)
+	})
+
+	t.Run("HandlerErrorContinuesThenSucceeds", func(t *testing.T) {
+		type workCmd struct{}
+		type stopCmd struct{}
+		resetSentryStub()
+		calls := 0
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				calls++
+				if calls == 1 {
+					return Response{CommandName: reflect.TypeOf(workCmd{}).Name()}, nil
+				}
+				return Response{CommandName: reflect.TypeOf(stopCmd{}).Name()}, nil
+			},
+		})
+		p := &Player{errorHandler: func(err error) { t.Errorf("unexpected error: %v", err) }}
+		PlayerOnCmd_(p, workCmd{}, func(workCmd) error { return errors.New("game handler failed") })
+		PlayerOnCmd_(p, stopCmd{}, func(stopCmd) error { return Break })
+		p.think(t.Context(), nil, "hello", nil)
+		if calls != 2 {
+			t.Fatalf("interact calls = %d, want 2", calls)
+		}
+		if lastThinkFinish.outcome != outcomeSuccess {
+			t.Fatalf("outcome = %q, want success after handler error", lastThinkFinish.outcome)
+		}
+		assertOneThinkFinish(t, false)
+	})
+
+	t.Run("UnknownCommandContinuesThenSucceeds", func(t *testing.T) {
+		type stopCmd struct{}
+		resetSentryStub()
+		calls := 0
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				calls++
+				if calls == 1 {
+					return Response{CommandName: "NotRegistered"}, nil
+				}
+				return Response{CommandName: reflect.TypeOf(stopCmd{}).Name()}, nil
+			},
+		})
+		p := &Player{errorHandler: func(err error) { t.Errorf("unexpected error: %v", err) }}
+		PlayerOnCmd_(p, stopCmd{}, func(stopCmd) error { return Break })
+		p.think(t.Context(), nil, "hello", nil)
+		if lastThinkFinish.outcome != outcomeSuccess {
+			t.Fatalf("outcome = %q", lastThinkFinish.outcome)
+		}
+		assertOneThinkFinish(t, false)
+	})
+
+	t.Run("TurnLimitOneException", func(t *testing.T) {
+		type loopCmd struct{}
+		resetSentryStub()
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{CommandName: reflect.TypeOf(loopCmd{}).Name()}, nil
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		PlayerOnCmd_(p, loopCmd{}, func(loopCmd) error { return nil })
+		p.think(t.Context(), nil, "loop", nil)
+		if lastThinkFinish.reason != reasonTurnLimit || lastThinkFinish.category != categoryModelQualityFailure {
+			t.Fatalf("got %+v", lastThinkFinish)
+		}
+		assertOneThinkFinish(t, true)
+	})
+
+	t.Run("TimeoutOneException", func(t *testing.T) {
+		resetSentryStub()
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{}, &TimeoutError{Err: errors.New("deadline")}
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		p.think(t.Context(), nil, "hello", nil)
+		if lastThinkFinish.reason != reasonTimeout {
+			t.Fatalf("got %+v", lastThinkFinish)
+		}
+		assertOneThinkFinish(t, true)
+	})
+
+	t.Run("RateLimitedOneFinishNoException", func(t *testing.T) {
+		resetSentryStub()
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{}, &TooManyRequestsError{RetryAfter: time.Millisecond, Err: errors.New("429")}
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		p.think(t.Context(), nil, "hello", nil)
+		if lastThinkFinish.outcome != outcomeRateLimited {
+			t.Fatalf("outcome = %q", lastThinkFinish.outcome)
+		}
+		assertOneThinkFinish(t, false)
+		if len(lastAttempts) != 3 {
+			t.Fatalf("attempts = %d, want 3", len(lastAttempts))
+		}
+	})
+
+	t.Run("CancelledOneFinishNoException", func(t *testing.T) {
+		resetSentryStub()
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(context.Context, Request) (Response, error) {
+				t.Fatal("Interact should not run")
+				return Response{}, nil
+			},
+		})
+		ctx, cancel := context.WithCancel(t.Context())
+		cancel()
+		p := &Player{errorHandler: func(error) {}}
+		p.think(ctx, nil, "hello", nil)
+		if lastThinkFinish.outcome != outcomeCancelled {
+			t.Fatalf("outcome = %q", lastThinkFinish.outcome)
+		}
+		assertOneThinkFinish(t, false)
+	})
+
+	t.Run("InvalidArgumentsOneException", func(t *testing.T) {
+		type typedCmd struct {
+			Steps int
+		}
+		resetSentryStub()
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{
+					CommandName: reflect.TypeOf(typedCmd{}).Name(),
+					CommandArgs: map[string]any{"Steps": "nope"},
+				}, nil
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		PlayerOnCmd_(p, typedCmd{}, func(typedCmd) error { return nil })
+		p.think(t.Context(), nil, "hello", nil)
+		if lastThinkFinish.reason != reasonInvalidArguments {
+			t.Fatalf("got %+v", lastThinkFinish)
+		}
+		assertOneThinkFinish(t, true)
+	})
+
+	t.Run("HandlerPanicOneException", func(t *testing.T) {
+		type panicCmd struct{}
+		resetSentryStub()
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{CommandName: reflect.TypeOf(panicCmd{}).Name()}, nil
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		PlayerOnCmd_(p, panicCmd{}, func(panicCmd) error { panic("boom") })
+		p.think(t.Context(), nil, "hello", nil)
+		if lastThinkFinish.reason != reasonHandlerPanic {
+			t.Fatalf("got %+v", lastThinkFinish)
+		}
+		assertOneThinkFinish(t, true)
+	})
+
+	t.Run("ArchiveRetriesExhaustedOneException", func(t *testing.T) {
+		resetSentryStub()
+		SetDefaultTransport(&mockTransport{
+			ArchiveFunc: func(_ context.Context, _ []Turn, _ string) (ArchivedHistory, error) {
+				return ArchivedHistory{}, errors.New("archive boom")
+			},
+		})
+		playerReadyToArchive().manageHistory(t.Context())
+		assertOneArchiveFinish(t, true)
+		if lastArchiveAttempts[0].ok {
+			t.Fatal("failed archive attempt should be marked error")
+		}
+		if thinkFinishCount != 0 {
+			t.Fatalf("archive must not call endThink, got %d", thinkFinishCount)
+		}
+	})
+
+	t.Run("ArchiveQuotaNoException", func(t *testing.T) {
+		resetSentryStub()
+		archiveCalls := 0
+		SetDefaultTransport(&mockTransport{
+			ArchiveFunc: func(_ context.Context, _ []Turn, _ string) (ArchivedHistory, error) {
+				archiveCalls++
+				return ArchivedHistory{}, &QuotaExceededError{Err: errors.New("quota exceeded")}
+			},
+		})
+		playerReadyToArchive().manageHistory(t.Context())
+		if archiveCalls != 1 {
+			t.Fatalf("archive calls = %d, want 1", archiveCalls)
+		}
+		assertOneArchiveFinish(t, false)
+	})
+
+	t.Run("ArchiveCancelNoException", func(t *testing.T) {
+		resetSentryStub()
+		SetDefaultTransport(&mockTransport{
+			ArchiveFunc: func(context.Context, []Turn, string) (ArchivedHistory, error) {
+				t.Fatal("Archive should not run")
+				return ArchivedHistory{}, nil
+			},
+		})
+		ctx, cancel := context.WithCancel(t.Context())
+		cancel()
+		playerReadyToArchive().manageHistory(ctx)
+		assertOneArchiveFinish(t, false)
+	})
+
+	t.Run("ArchiveDoesNotChangeThinkFinish", func(t *testing.T) {
+		resetSentryStub()
+		lastThinkFinish = thinkFinish{outcome: outcomeSuccess, turnCount: 2}
+		thinkFinishCount = 1
+		SetDefaultTransport(&mockTransport{
+			ArchiveFunc: func(_ context.Context, _ []Turn, _ string) (ArchivedHistory, error) {
+				return ArchivedHistory{}, &QuotaExceededError{Err: errors.New("quota exceeded")}
+			},
+		})
+		playerReadyToArchive().manageHistory(t.Context())
+		if lastThinkFinish.outcome != outcomeSuccess || lastThinkFinish.turnCount != 2 {
+			t.Fatalf("Think finish mutated by archive: %+v", lastThinkFinish)
+		}
+		if lastThinkFinish.shouldCaptureException() {
+			t.Fatal("archive quota must not make Think capture")
+		}
+		assertOneArchiveFinish(t, false)
+		if thinkFinishCount != 1 {
+			t.Fatalf("endThink calls = %d, want unchanged 1", thinkFinishCount)
+		}
+	})
+}
diff --git a/tools/ai/httperr.go b/tools/ai/httperr.go
new file mode 100644
index 0000000000..1bb402055b
--- /dev/null
+++ b/tools/ai/httperr.go
@@ -0,0 +1,182 @@
+package ai
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+)
+
+// quotaExceededCode is the existing backend errorPayload code for long-window
+// quota exhaustion (HTTP 403). This client consumes that contract as-is.
+const quotaExceededCode = 40301
+
+// httpErrorPayload is the JSON body returned by the AI interaction API on failure.
+type httpErrorPayload struct {
+	Code      int    `json:"code"`
+	Msg       string `json:"msg"`
+	Category  string `json:"category"`
+	Reason    string `json:"reason"`
+	RequestID string `json:"request_id"`
+}
+
+// QuotaExceededError is HTTP 403 with JSON code 40301. Think/Archive must stop
+// retrying immediately. Other 403s are not quota.
+type QuotaExceededError struct {
+	Category  string
+	Reason    string
+	RequestID string
+	Err       error
+}
+
+func (e *QuotaExceededError) Error() string {
+	if e == nil {
+		return ""
+	}
+	if e.Err != nil {
+		return e.Err.Error()
+	}
+	return "quota exceeded"
+}
+
+func (e *QuotaExceededError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Err
+}
+
+// HTTPError is a non-429, non-quota HTTP failure. Backend classification is
+// copied onto transport attempt spans as backend_* tags.
+type HTTPError struct {
+	Status    int
+	Code      int
+	Category  string
+	Reason    string
+	RequestID string
+	Err       error
+}
+
+func (e *HTTPError) Error() string {
+	if e == nil {
+		return ""
+	}
+	if e.Err != nil {
+		return e.Err.Error()
+	}
+	return fmt.Sprintf("http %d", e.Status)
+}
+
+func (e *HTTPError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Err
+}
+
+// TimeoutError marks a transport call that hit its attempt deadline. Prefer
+// context.DeadlineExceeded over AbortError strings.
+type TimeoutError struct {
+	Err error
+}
+
+func (e *TimeoutError) Error() string {
+	if e == nil {
+		return ""
+	}
+	if e.Err != nil {
+		return e.Err.Error()
+	}
+	return "transport timeout"
+}
+
+func (e *TimeoutError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Err
+}
+
+func isQuotaExceeded(err error) bool {
+	var typed *QuotaExceededError
+	return errors.As(err, &typed)
+}
+
+func isTransportTimeout(err error) bool {
+	var typed *TimeoutError
+	return errors.As(err, &typed)
+}
+
+func parseHTTPErrorPayload(body string) httpErrorPayload {
+	var payload httpErrorPayload
+	if body == "" {
+		return payload
+	}
+	_ = json.Unmarshal([]byte(body), &payload)
+	return payload
+}
+
+// ErrorFromHTTPResponse classifies a failed AI interaction HTTP response.
+// Only status 403 with JSON code 40301 is quota; 429 stays TooManyRequestsError.
+func ErrorFromHTTPResponse(status int, retryAfter time.Duration, body string, fallback error) error {
+	if fallback == nil {
+		fallback = fmt.Errorf("failed to fetch with status %d", status)
+	}
+	payload := parseHTTPErrorPayload(body)
+	switch {
+	case status == 403 && payload.Code == quotaExceededCode:
+		return &QuotaExceededError{
+			Category:  payload.Category,
+			Reason:    payload.Reason,
+			RequestID: payload.RequestID,
+			Err:       fallback,
+		}
+	case status == 429:
+		return &TooManyRequestsError{
+			RetryAfter: retryAfter,
+			Category:   payload.Category,
+			Reason:     payload.Reason,
+			RequestID:  payload.RequestID,
+			Err:        fallback,
+		}
+	default:
+		return &HTTPError{
+			Status:    status,
+			Code:      payload.Code,
+			Category:  payload.Category,
+			Reason:    payload.Reason,
+			RequestID: payload.RequestID,
+			Err:       fallback,
+		}
+	}
+}
+
+func AnnotateTransportError(ctx context.Context, err error) error {
+	if err == nil {
+		return nil
+	}
+	if isTransportTimeout(err) || isQuotaExceeded(err) {
+		return err
+	}
+	if errors.Is(ctx.Err(), context.DeadlineExceeded) {
+		return &TimeoutError{Err: err}
+	}
+	return err
+}
+
+func backendTagsFromError(err error) (category, reason, requestID string) {
+	var quotaErr *QuotaExceededError
+	if errors.As(err, &quotaErr) {
+		return quotaErr.Category, quotaErr.Reason, quotaErr.RequestID
+	}
+	var tmrErr *TooManyRequestsError
+	if errors.As(err, &tmrErr) {
+		return tmrErr.Category, tmrErr.Reason, tmrErr.RequestID
+	}
+	var httpErr *HTTPError
+	if errors.As(err, &httpErr) {
+		return httpErr.Category, httpErr.Reason, httpErr.RequestID
+	}
+	return "", "", ""
+}
diff --git a/tools/ai/httperr_test.go b/tools/ai/httperr_test.go
new file mode 100644
index 0000000000..e5b818b503
--- /dev/null
+++ b/tools/ai/httperr_test.go
@@ -0,0 +1,111 @@
+package ai
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+)
+
+func TestErrorFromHTTPResponseQuotaExceeded(t *testing.T) {
+	err := ErrorFromHTTPResponse(403, 0, `{"code":40301,"msg":"Quota exceeded"}`, errors.New("forbidden"))
+	if !isQuotaExceeded(err) {
+		t.Fatalf("403/40301 should be quota, got %T %v", err, err)
+	}
+	var tmr *TooManyRequestsError
+	if errors.As(err, &tmr) {
+		t.Fatal("quota must not be TooManyRequestsError")
+	}
+}
+
+func TestErrorFromHTTPResponseOther403IsNotQuota(t *testing.T) {
+	err := ErrorFromHTTPResponse(403, 0, `{"code":40300,"msg":"Forbidden"}`, errors.New("forbidden"))
+	if isQuotaExceeded(err) {
+		t.Fatal("403/40300 must not be quota")
+	}
+	var httpErr *HTTPError
+	if !errors.As(err, &httpErr) {
+		t.Fatalf("got %T, want *HTTPError", err)
+	}
+}
+
+func TestErrorFromHTTPResponseEmpty403IsNotQuota(t *testing.T) {
+	err := ErrorFromHTTPResponse(403, 0, "nope", errors.New("forbidden"))
+	if isQuotaExceeded(err) {
+		t.Fatal("403 without code 40301 must not be quota")
+	}
+}
+
+func TestErrorFromHTTPResponse429(t *testing.T) {
+	err := ErrorFromHTTPResponse(429, 2*time.Second, `{"code":42901,"msg":"Too many requests"}`, errors.New("rate limited"))
+	if isQuotaExceeded(err) {
+		t.Fatal("429 must not be quota")
+	}
+	var tmr *TooManyRequestsError
+	if !errors.As(err, &tmr) {
+		t.Fatalf("got %T, want *TooManyRequestsError", err)
+	}
+	if tmr.RetryAfter != 2*time.Second {
+		t.Fatalf("RetryAfter = %s", tmr.RetryAfter)
+	}
+}
+
+func TestErrorFromHTTPResponseBackendTags(t *testing.T) {
+	body := `{"code":50000,"msg":"Internal server error","category":"upstream_failure","reason":"timeout","request_id":"req-1"}`
+	err := ErrorFromHTTPResponse(500, 0, body, errors.New("upstream"))
+	category, reason, requestID := backendTagsFromError(err)
+	if category != "upstream_failure" || reason != "timeout" || requestID != "req-1" {
+		t.Fatalf("backend tags = %q %q %q", category, reason, requestID)
+	}
+	wrapped := fmt.Errorf("ai interaction failed: %w", err)
+	category, reason, requestID = backendTagsFromError(wrapped)
+	if category != "upstream_failure" || reason != "timeout" || requestID != "req-1" {
+		t.Fatalf("wrapped backend tags = %q %q %q", category, reason, requestID)
+	}
+}
+
+func TestAnnotateTransportErrorTimeout(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), time.Nanosecond)
+	defer cancel()
+	<-ctx.Done()
+
+	err := AnnotateTransportError(ctx, errors.New("promise rejected: AbortError"))
+	if !isTransportTimeout(err) {
+		t.Fatalf("got %T %v, want TimeoutError", err, err)
+	}
+}
+
+func TestAnnotateTransportErrorCanceledIsNotTimeout(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	err := AnnotateTransportError(ctx, errors.New("promise rejected: AbortError"))
+	if isTransportTimeout(err) {
+		t.Fatal("canceled context must not become TimeoutError")
+	}
+}
+
+func TestAnnotateTransportErrorPreservesQuota(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), time.Nanosecond)
+	defer cancel()
+	<-ctx.Done()
+	quotaErr := &QuotaExceededError{Err: errors.New("quota exceeded")}
+	if got := AnnotateTransportError(ctx, quotaErr); !isQuotaExceeded(got) {
+		t.Fatalf("quota must not be rewritten as timeout, got %T", got)
+	}
+}
+
+func TestBackendTagsFromTimeoutWrappedHTTPError(t *testing.T) {
+	httpErr := ErrorFromHTTPResponse(500, 0, `{"category":"upstream_failure","reason":"provider_error","request_id":"abc"}`, errors.New("upstream"))
+	ctx, cancel := context.WithTimeout(context.Background(), time.Nanosecond)
+	defer cancel()
+	<-ctx.Done()
+	err := AnnotateTransportError(ctx, httpErr)
+	if !isTransportTimeout(err) {
+		t.Fatalf("got %T", err)
+	}
+	category, reason, requestID := backendTagsFromError(err)
+	if category != "upstream_failure" || reason != "provider_error" || requestID != "abc" {
+		t.Fatalf("backend tags = %q %q %q", category, reason, requestID)
+	}
+}
diff --git a/tools/ai/sentry_context.go b/tools/ai/sentry_context.go
new file mode 100644
index 0000000000..99c19017be
--- /dev/null
+++ b/tools/ai/sentry_context.go
@@ -0,0 +1,62 @@
+package ai
+
+import (
+	"context"
+	"fmt"
+	"sync/atomic"
+	"time"
+)
+
+type sentryTraceContextKey struct{}
+
+type sentryTraceContext struct {
+	id      string
+	trace   string
+	baggage string
+}
+
+var sentryTraceSeq atomic.Uint64
+
+func newSentryTraceID() string {
+	return fmt.Sprintf("%d-%d", time.Now().UnixMilli(), sentryTraceSeq.Add(1))
+}
+
+func withSentryTrace(ctx context.Context, id, trace, baggage string) context.Context {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if id == "" && trace == "" && baggage == "" {
+		return ctx
+	}
+	return context.WithValue(ctx, sentryTraceContextKey{}, sentryTraceContext{
+		id:      id,
+		trace:   trace,
+		baggage: baggage,
+	})
+}
+
+func sentryTraceFromContext(ctx context.Context) (sentryTraceContext, bool) {
+	if ctx == nil {
+		return sentryTraceContext{}, false
+	}
+	value, ok := ctx.Value(sentryTraceContextKey{}).(sentryTraceContext)
+	return value, ok
+}
+
+// TraceHeadersFromContext returns the Sentry-Trace and Baggage values bound to
+// ctx by startThink or startArchive. Missing values yield empty strings.
+func TraceHeadersFromContext(ctx context.Context) (string, string) {
+	value, ok := sentryTraceFromContext(ctx)
+	if !ok {
+		return "", ""
+	}
+	return value.trace, value.baggage
+}
+
+func sentryTraceIDFromContext(ctx context.Context) string {
+	value, ok := sentryTraceFromContext(ctx)
+	if !ok {
+		return ""
+	}
+	return value.id
+}
diff --git a/tools/ai/sentry_context_test.go b/tools/ai/sentry_context_test.go
new file mode 100644
index 0000000000..14dce6e365
--- /dev/null
+++ b/tools/ai/sentry_context_test.go
@@ -0,0 +1,48 @@
+package ai
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestTraceHeadersFromContextInheritsToChild(t *testing.T) {
+	ctx := withSentryTrace(context.Background(), "id-1", "trace-1", "baggage-1")
+	child, cancel := context.WithTimeout(ctx, time.Second)
+	defer cancel()
+
+	trace, baggage := TraceHeadersFromContext(child)
+	if trace != "trace-1" || baggage != "baggage-1" {
+		t.Fatalf("TraceHeadersFromContext(child) = %q, %q; want trace-1, baggage-1", trace, baggage)
+	}
+	if got := sentryTraceIDFromContext(child); got != "id-1" {
+		t.Fatalf("sentryTraceIDFromContext(child) = %q; want id-1", got)
+	}
+}
+
+func TestTraceHeadersFromContextEmpty(t *testing.T) {
+	trace, baggage := TraceHeadersFromContext(context.Background())
+	if trace != "" || baggage != "" {
+		t.Fatalf("TraceHeadersFromContext(background) = %q, %q; want empty", trace, baggage)
+	}
+	if got := sentryTraceIDFromContext(nil); got != "" {
+		t.Fatalf("sentryTraceIDFromContext(nil) = %q; want empty", got)
+	}
+}
+
+func TestTraceHeadersFromContextIsolated(t *testing.T) {
+	thinkCtx := withSentryTrace(context.Background(), "think", "think-trace", "think-baggage")
+	archiveCtx := withSentryTrace(context.Background(), "archive", "archive-trace", "archive-baggage")
+
+	thinkTrace, thinkBaggage := TraceHeadersFromContext(thinkCtx)
+	archiveTrace, archiveBaggage := TraceHeadersFromContext(archiveCtx)
+	if thinkTrace != "think-trace" || thinkBaggage != "think-baggage" {
+		t.Fatalf("think headers = %q, %q", thinkTrace, thinkBaggage)
+	}
+	if archiveTrace != "archive-trace" || archiveBaggage != "archive-baggage" {
+		t.Fatalf("archive headers = %q, %q", archiveTrace, archiveBaggage)
+	}
+	if sentryTraceIDFromContext(thinkCtx) == sentryTraceIDFromContext(archiveCtx) {
+		t.Fatal("think and archive should not share the same id")
+	}
+}
diff --git a/tools/ai/sentry_stub.go b/tools/ai/sentry_stub.go
new file mode 100644
index 0000000000..d0fc2ae840
--- /dev/null
+++ b/tools/ai/sentry_stub.go
@@ -0,0 +1,68 @@
+//go:build !js || !wasm
+
+package ai
+
+import "context"
+
+// SetGameSessionID is a no-op outside the WASM runner.
+func SetGameSessionID(string) {}
+
+type recordedAttempt struct {
+	ok        bool
+	category  string
+	reason    string
+	requestID string
+}
+
+var (
+	lastThinkFinish     thinkFinish
+	thinkFinishCount    int
+	lastArchiveFinish   archiveFinish
+	archiveFinishCount  int
+	lastAttempts        []recordedAttempt
+	lastArchiveAttempts []recordedAttempt
+)
+
+func resetSentryStub() {
+	lastThinkFinish = thinkFinish{}
+	thinkFinishCount = 0
+	lastArchiveFinish = archiveFinish{}
+	archiveFinishCount = 0
+	lastAttempts = nil
+	lastArchiveAttempts = nil
+}
+
+func recordAttempt(ok bool, err error) recordedAttempt {
+	category, reason, requestID := backendTagsFromError(err)
+	return recordedAttempt{ok: ok, category: category, reason: reason, requestID: requestID}
+}
+
+func startThink(ctx context.Context) context.Context { return ctx }
+
+func endThink(_ context.Context, finish thinkFinish) {
+	thinkFinishCount++
+	lastThinkFinish = finish
+}
+
+func startAttempt(context.Context, int, int) {}
+
+func endAttempt(_ context.Context, ok bool, err error) {
+	lastAttempts = append(lastAttempts, recordAttempt(ok, err))
+}
+
+func startCommand(context.Context, int, string) {}
+
+func endCommand(context.Context, bool, string) {}
+
+func startArchive(ctx context.Context) context.Context { return ctx }
+
+func endArchive(_ context.Context, finish archiveFinish) {
+	archiveFinishCount++
+	lastArchiveFinish = finish
+}
+
+func startArchiveAttempt(context.Context, int) {}
+
+func endArchiveAttempt(_ context.Context, ok bool, err error) {
+	lastArchiveAttempts = append(lastArchiveAttempts, recordAttempt(ok, err))
+}
diff --git a/tools/ai/sentry_wasm.go b/tools/ai/sentry_wasm.go
new file mode 100644
index 0000000000..f4ad41e4ba
--- /dev/null
+++ b/tools/ai/sentry_wasm.go
@@ -0,0 +1,181 @@
+//go:build js && wasm
+
+package ai
+
+import (
+	"context"
+	"syscall/js"
+	"time"
+)
+
+var (
+	gameSessionID string
+	sentryBridge  js.Value
+)
+
+// SetGameSessionID stores the current game run id injected by the parent page.
+func SetGameSessionID(id string) {
+	gameSessionID = id
+}
+
+// SetSentryBridge stores the parent-page Sentry hook object.
+func SetSentryBridge(bridge js.Value) {
+	sentryBridge = bridge
+}
+
+func startThink(ctx context.Context) context.Context {
+	return startRoot(ctx, "startThink", "thinkId", gameSessionID)
+}
+
+func endThink(ctx context.Context, finish thinkFinish) {
+	id := sentryTraceIDFromContext(ctx)
+	if id == "" {
+		return
+	}
+	callArgs := map[string]any{
+		"thinkId":      id,
+		"endTime":      unixSeconds(),
+		"outcome":      finish.outcome,
+		"category":     finish.category,
+		"reason":       finish.reason,
+		"turnCount":    finish.turnCount,
+		"attemptCount": finish.attemptCount,
+	}
+	if payload := finish.bridgeException(gameSessionID); payload != nil {
+		callArgs["exception"] = payload
+	}
+	callBridge("endThink", callArgs)
+}
+
+func startAttempt(ctx context.Context, turnIndex, attempt int) {
+	callBridge("startAttempt", map[string]any{
+		"thinkId":   sentryTraceIDFromContext(ctx),
+		"startTime": unixSeconds(),
+		"turnIndex": turnIndex,
+		"attempt":   attempt,
+	})
+}
+
+func endAttempt(ctx context.Context, ok bool, err error) {
+	category, reason, requestID := backendTagsFromError(err)
+	callBridge("endAttempt", map[string]any{
+		"thinkId":         sentryTraceIDFromContext(ctx),
+		"endTime":         unixSeconds(),
+		"ok":              ok,
+		"backendCategory": category,
+		"backendReason":   reason,
+		"requestId":       requestID,
+	})
+}
+
+func startCommand(ctx context.Context, turnIndex int, commandName string) {
+	callBridge("startCommand", map[string]any{
+		"thinkId":     sentryTraceIDFromContext(ctx),
+		"startTime":   unixSeconds(),
+		"turnIndex":   turnIndex,
+		"commandName": commandName,
+	})
+}
+
+func endCommand(ctx context.Context, ok bool, errorMessage string) {
+	callBridge("endCommand", map[string]any{
+		"thinkId":      sentryTraceIDFromContext(ctx),
+		"endTime":      unixSeconds(),
+		"ok":           ok,
+		"errorMessage": errorMessage,
+	})
+}
+
+func startArchive(ctx context.Context) context.Context {
+	return startRoot(ctx, "startArchive", "archiveId", gameSessionID)
+}
+
+func endArchive(ctx context.Context, finish archiveFinish) {
+	id := sentryTraceIDFromContext(ctx)
+	if id == "" {
+		return
+	}
+	callArgs := map[string]any{
+		"archiveId":    id,
+		"endTime":      unixSeconds(),
+		"attemptCount": finish.attemptCount,
+	}
+	if finish.ok {
+		callArgs["ok"] = true
+	}
+	if payload := finish.bridgeException(gameSessionID); payload != nil {
+		callArgs["exception"] = payload
+		callArgs["category"] = categoryArchiveFailure
+		callArgs["reason"] = reasonRetriesExhausted
+		callArgs["ok"] = false
+	}
+	callBridge("endArchive", callArgs)
+}
+
+func startArchiveAttempt(ctx context.Context, attempt int) {
+	callBridge("startArchiveAttempt", map[string]any{
+		"archiveId": sentryTraceIDFromContext(ctx),
+		"startTime": unixSeconds(),
+		"attempt":   attempt,
+	})
+}
+
+func endArchiveAttempt(ctx context.Context, ok bool, err error) {
+	category, reason, requestID := backendTagsFromError(err)
+	callBridge("endArchiveAttempt", map[string]any{
+		"archiveId":       sentryTraceIDFromContext(ctx),
+		"endTime":         unixSeconds(),
+		"ok":              ok,
+		"backendCategory": category,
+		"backendReason":   reason,
+		"requestId":       requestID,
+	})
+}
+
+func startRoot(ctx context.Context, method, idKey, gameSessionId string) (out context.Context) {
+	out = ctx
+	if !sentryBridge.Truthy() {
+		return ctx
+	}
+	defer func() {
+		if recover() != nil {
+			out = ctx
+		}
+	}()
+	id := newSentryTraceID()
+	result := sentryBridge.Call(method, map[string]any{
+		idKey:           id,
+		"startTime":     unixSeconds(),
+		"gameSessionId": gameSessionId,
+	})
+	if !result.Truthy() {
+		return ctx
+	}
+	trace := result.Get("sentryTrace").String()
+	baggage := result.Get("baggage").String()
+	if trace == "" {
+		return ctx
+	}
+	return withSentryTrace(ctx, id, trace, baggage)
+}
+
+func callBridge(method string, args map[string]any) {
+	if !sentryBridge.Truthy() {
+		return
+	}
+	id := ""
+	if raw, ok := args["thinkId"]; ok {
+		id, _ = raw.(string)
+	} else if raw, ok := args["archiveId"]; ok {
+		id, _ = raw.(string)
+	}
+	if id == "" {
+		return
+	}
+	defer func() { recover() }()
+	sentryBridge.Call(method, args)
+}
+
+func unixSeconds() float64 {
+	return float64(time.Now().UnixMilli()) / 1000
+}
diff --git a/tools/ai/think_finish_test.go b/tools/ai/think_finish_test.go
new file mode 100644
index 0000000000..bec18ae6b1
--- /dev/null
+++ b/tools/ai/think_finish_test.go
@@ -0,0 +1,211 @@
+package ai
+
+import (
+	"context"
+	"errors"
+	"reflect"
+	"testing"
+	"time"
+)
+
+func TestClassifyTransportStop(t *testing.T) {
+	tests := []struct {
+		name         string
+		err          error
+		wantOutcome  string
+		wantCategory string
+		wantReason   string
+	}{
+		{
+			name:        "Quota",
+			err:         &QuotaExceededError{Err: errors.New("quota exceeded")},
+			wantOutcome: outcomeQuotaExhausted,
+		},
+		{
+			name:        "RateLimited",
+			err:         &TooManyRequestsError{Err: errors.New("too many requests")},
+			wantOutcome: outcomeRateLimited,
+		},
+		{
+			name:         "Timeout",
+			err:          &TimeoutError{Err: errors.New("deadline")},
+			wantOutcome:  outcomeFailure,
+			wantCategory: categoryTransportFailure,
+			wantReason:   reasonTimeout,
+		},
+		{
+			name:         "Network",
+			err:          errors.New("failed to fetch"),
+			wantOutcome:  outcomeFailure,
+			wantCategory: categoryTransportFailure,
+			wantReason:   reasonNetwork,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := classifyTransportStop(tt.err)
+			if got.outcome != tt.wantOutcome || got.category != tt.wantCategory || got.reason != tt.wantReason {
+				t.Fatalf("got %+v, want outcome=%s category=%s reason=%s", got, tt.wantOutcome, tt.wantCategory, tt.wantReason)
+			}
+		})
+	}
+}
+
+func TestPlayerThinkFinishOutcomes(t *testing.T) {
+	type breakCmd struct{}
+
+	originalTransport := DefaultTransport()
+	t.Cleanup(func() { SetDefaultTransport(originalTransport) })
+
+	t.Run("SuccessBreak", func(t *testing.T) {
+		lastThinkFinish = thinkFinish{}
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{CommandName: reflect.TypeOf(breakCmd{}).Name()}, nil
+			},
+		})
+		p := &Player{errorHandler: func(err error) { t.Errorf("unexpected error: %v", err) }}
+		PlayerOnCmd_(p, breakCmd{}, func(breakCmd) error { return Break })
+		p.think(t.Context(), nil, "hi", nil)
+		if lastThinkFinish.outcome != outcomeSuccess {
+			t.Fatalf("outcome = %q, want %s", lastThinkFinish.outcome, outcomeSuccess)
+		}
+		if lastThinkFinish.turnCount != 1 || lastThinkFinish.attemptCount != 1 {
+			t.Fatalf("counts = turn %d attempt %d", lastThinkFinish.turnCount, lastThinkFinish.attemptCount)
+		}
+	})
+
+	t.Run("MissingInitialCommand", func(t *testing.T) {
+		lastThinkFinish = thinkFinish{}
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{Text: "hello"}, nil
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		p.think(t.Context(), nil, "hi", nil)
+		if lastThinkFinish.outcome != outcomeFailure || lastThinkFinish.reason != reasonMissingInitialCommand {
+			t.Fatalf("got %+v", lastThinkFinish)
+		}
+		if lastThinkFinish.category != categoryModelQualityFailure {
+			t.Fatalf("category = %q", lastThinkFinish.category)
+		}
+	})
+
+	t.Run("Cancelled", func(t *testing.T) {
+		lastThinkFinish = thinkFinish{}
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(ctx context.Context, _ Request) (Response, error) {
+				t.Fatal("Interact should not run on cancelled context")
+				return Response{}, nil
+			},
+		})
+		ctx, cancel := context.WithCancel(t.Context())
+		cancel()
+		p := &Player{errorHandler: func(error) {}}
+		p.think(ctx, nil, "hi", nil)
+		if lastThinkFinish.outcome != outcomeCancelled {
+			t.Fatalf("outcome = %q, want %s", lastThinkFinish.outcome, outcomeCancelled)
+		}
+	})
+
+	t.Run("RateLimitedNoRetryExhaustedAsFailure", func(t *testing.T) {
+		lastThinkFinish = thinkFinish{}
+		interactCalls := 0
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				interactCalls++
+				return Response{}, &TooManyRequestsError{RetryAfter: time.Millisecond, Err: errors.New("429")}
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		p.think(t.Context(), nil, "hi", nil)
+		if interactCalls != 3 {
+			t.Fatalf("got %d attempts, want 3", interactCalls)
+		}
+		if lastThinkFinish.outcome != outcomeRateLimited {
+			t.Fatalf("outcome = %q, want %s", lastThinkFinish.outcome, outcomeRateLimited)
+		}
+		if lastThinkFinish.category != "" || lastThinkFinish.reason != "" {
+			t.Fatalf("rate limited must not set failure category, got %+v", lastThinkFinish)
+		}
+		if lastThinkFinish.attemptCount != 3 {
+			t.Fatalf("attemptCount = %d", lastThinkFinish.attemptCount)
+		}
+	})
+
+	t.Run("Timeout", func(t *testing.T) {
+		lastThinkFinish = thinkFinish{}
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{}, &TimeoutError{Err: errors.New("deadline")}
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		p.think(t.Context(), nil, "hi", nil)
+		if lastThinkFinish.outcome != outcomeFailure || lastThinkFinish.reason != reasonTimeout {
+			t.Fatalf("got %+v", lastThinkFinish)
+		}
+	})
+
+	t.Run("InvalidArguments", func(t *testing.T) {
+		type typedCmd struct {
+			Steps int
+		}
+		lastThinkFinish = thinkFinish{}
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{
+					CommandName: reflect.TypeOf(typedCmd{}).Name(),
+					CommandArgs: map[string]any{"Steps": "nope"},
+				}, nil
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		PlayerOnCmd_(p, typedCmd{}, func(typedCmd) error { return nil })
+		p.think(t.Context(), nil, "hi", nil)
+		if lastThinkFinish.outcome != outcomeFailure || lastThinkFinish.reason != reasonInvalidArguments {
+			t.Fatalf("got %+v", lastThinkFinish)
+		}
+	})
+
+	t.Run("HandlerPanic", func(t *testing.T) {
+		type panicCmd struct{}
+		lastThinkFinish = thinkFinish{}
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				return Response{CommandName: reflect.TypeOf(panicCmd{}).Name()}, nil
+			},
+		})
+		p := &Player{errorHandler: func(error) {}}
+		PlayerOnCmd_(p, panicCmd{}, func(panicCmd) error {
+			panic("boom")
+		})
+		p.think(t.Context(), nil, "hi", nil)
+		if lastThinkFinish.outcome != outcomeFailure || lastThinkFinish.reason != reasonHandlerPanic {
+			t.Fatalf("got %+v", lastThinkFinish)
+		}
+	})
+
+	t.Run("UnknownCommandContinuesThenSucceeds", func(t *testing.T) {
+		lastThinkFinish = thinkFinish{}
+		calls := 0
+		SetDefaultTransport(&mockTransport{
+			InteractFunc: func(_ context.Context, _ Request) (Response, error) {
+				calls++
+				if calls == 1 {
+					return Response{CommandName: "NotRegistered"}, nil
+				}
+				return Response{Text: "done"}, nil
+			},
+		})
+		p := &Player{errorHandler: func(err error) { t.Errorf("unexpected error: %v", err) }}
+		p.think(t.Context(), nil, "hi", nil)
+		if lastThinkFinish.outcome != outcomeSuccess {
+			t.Fatalf("outcome = %q, want success after unknown command then stop", lastThinkFinish.outcome)
+		}
+		if lastThinkFinish.turnCount != 2 {
+			t.Fatalf("turnCount = %d, want 2", lastThinkFinish.turnCount)
+		}
+	})
+}
diff --git a/tools/ai/transport.go b/tools/ai/transport.go
index 4ab1c7c78d..067178aa30 100644
--- a/tools/ai/transport.go
+++ b/tools/ai/transport.go
@@ -144,6 +144,9 @@ func SetDefaultTransport(t Transport) {
 // TooManyRequestsError represents a transport-level HTTP 429 error.
 type TooManyRequestsError struct {
 	RetryAfter time.Duration
+	Category   string
+	Reason     string
+	RequestID  string
 	Err        error
 }
 
diff --git a/tools/ai/wasmtrans/wasmtrans.go b/tools/ai/wasmtrans/wasmtrans.go
index 728fe7c24a..2b9b609f0a 100644
--- a/tools/ai/wasmtrans/wasmtrans.go
+++ b/tools/ai/wasmtrans/wasmtrans.go
@@ -89,8 +89,8 @@ func (t *wasmTransport) Archive(ctx context.Context, turns []ai.Turn, existingAr
 	return resp, nil
 }
 
-// buildHeaders creates request headers with proper authentication.
-func (t *wasmTransport) buildHeaders() map[string]any {
+// buildHeaders creates request headers with proper authentication and Sentry trace context.
+func (t *wasmTransport) buildHeaders(ctx context.Context) map[string]any {
 	headers := map[string]any{
 		"Content-Type": "application/json",
 	}
@@ -99,12 +99,18 @@ func (t *wasmTransport) buildHeaders() map[string]any {
 			headers["Authorization"] = "Bearer " + token
 		}
 	}
+	if sentryTrace, baggage := ai.TraceHeadersFromContext(ctx); sentryTrace != "" {
+		headers["Sentry-Trace"] = sentryTrace
+		if baggage != "" {
+			headers["Baggage"] = baggage
+		}
+	}
 	return headers
 }
 
 // fetchAndParse performs a fetch request and parses the JSON response into the target.
 func (t *wasmTransport) fetchAndParse(ctx context.Context, path string, body []byte, result any) error {
-	headers := t.buildHeaders()
+	headers := t.buildHeaders(ctx)
 
 	jsAbortController := js.Global().Get("AbortController").New()
 	defer context.AfterFunc(ctx, func() {
@@ -119,7 +125,7 @@ func (t *wasmTransport) fetchAndParse(ctx context.Context, path string, body []b
 		"signal":  jsAbortSignal,
 	}))
 	if err != nil {
-		return fmt.Errorf("failed to fetch: %w", err)
+		return ai.AnnotateTransportError(ctx, fmt.Errorf("failed to fetch: %w", err))
 	}
 
 	if !jsResp.Get("ok").Bool() {
@@ -136,29 +142,18 @@ func (t *wasmTransport) fetchAndParse(ctx context.Context, path string, body []b
 		bodyPromise := jsResp.Call("text")
 		bodyTextVal, bodyErr := awaitPromise(ctx, bodyPromise)
 		if bodyErr != nil {
-			err := fmt.Errorf("failed to fetch with status %d %s (and failed to read error body: %w)", status, statusText, bodyErr)
-			if status == 429 {
-				return &ai.TooManyRequestsError{
-					RetryAfter: retryAfter,
-					Err:        err,
-				}
-			}
-			return err
+			fallback := fmt.Errorf("failed to fetch with status %d %s (and failed to read error body: %w)", status, statusText, bodyErr)
+			return ai.AnnotateTransportError(ctx, ai.ErrorFromHTTPResponse(status, retryAfter, "", fallback))
 		}
 
 		bodyText := bodyTextVal.String()
-		if status == 429 {
-			return &ai.TooManyRequestsError{
-				RetryAfter: retryAfter,
-				Err:        fmt.Errorf("failed to fetch with status %d %s: %s", status, statusText, bodyText),
-			}
-		}
-		return fmt.Errorf("failed to fetch with status %d %s: %s", status, statusText, bodyText)
+		fallback := fmt.Errorf("failed to fetch with status %d %s: %s", status, statusText, bodyText)
+		return ai.AnnotateTransportError(ctx, ai.ErrorFromHTTPResponse(status, retryAfter, bodyText, fallback))
 	}
 
 	jsJSON, err := awaitPromise(ctx, jsResp.Call("json"))
 	if err != nil {
-		return fmt.Errorf("failed to process json response: %w", err)
+		return ai.AnnotateTransportError(ctx, fmt.Errorf("failed to process json response: %w", err))
 	}
 	jsonString := js.Global().Get("JSON").Call("stringify", jsJSON).String()
 
diff --git a/tools/ispx/ai.go b/tools/ispx/ai.go
index b238b35048..d89985c465 100644
--- a/tools/ispx/ai.go
+++ b/tools/ispx/ai.go
@@ -17,6 +17,8 @@ func init() {
 	js.Global().Set("xbuilder_set_ai_description", js.FuncOf(setAIDescription))
 	js.Global().Set("xbuilder_set_ai_interaction_api_endpoint", js.FuncOf(setAIInteractionAPIEndpoint))
 	js.Global().Set("xbuilder_set_ai_interaction_api_token_provider", js.FuncOf(setAIInteractionAPITokenProvider))
+	js.Global().Set("xbuilder_set_game_session_id", js.FuncOf(setGameSessionID))
+	js.Global().Set("xbuilder_set_sentry_bridge", js.FuncOf(setSentryBridge))
 }
 
 // initAI initializes AI integration for the ispx interpreter.
@@ -54,6 +56,20 @@ func setAIDescription(this js.Value, args []js.Value) any {
 // aiInteractionAPIEndpoint holds the endpoint URL for AI Interaction API.
 var aiInteractionAPIEndpoint string
 
+func setGameSessionID(this js.Value, args []js.Value) any {
+	if len(args) > 0 {
+		ai.SetGameSessionID(args[0].String())
+	}
+	return nil
+}
+
+func setSentryBridge(this js.Value, args []js.Value) any {
+	if len(args) > 0 {
+		ai.SetSentryBridge(args[0])
+	}
+	return nil
+}
+
 // setAIInteractionAPIEndpoint sets [aiInteractionAPIEndpoint] from JavaScript.
 func setAIInteractionAPIEndpoint(this js.Value, args []js.Value) any {
 	if len(args) > 0 {