From c46109c50cddbf4f7842af8839f263536f15dd32 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=94=B0=E5=AE=87=E7=90=A8?= <tyk@MacBook-Pro.local>
Date: Fri, 31 Jul 2026 23:28:08 +0800
Subject: [PATCH 1/4] feat(spx-gui): integrate Sentry monitoring for SPX
 runtime panics

Add Sentry integration to ProjectRunner to capture and report runtime
errors from tools/ispx with structured context including file, line,
function, and column information.

Key features:
- Parse panic JSON logs from tools/ispx console output
- Report runtime panics to Sentry with SpxRuntimePanic exception type
- Add structured context (file, line, column, function) to events
- Instrument lifecycle spans for engine init, build, start, and stop
- Deduplicate errors within 5-second window to prevent duplicate reports
- Graceful degradation when Sentry is unavailable
- Async reporting to avoid interfering with WASM panic unwinding

Closes #2419

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../project/runner/ProjectRunner.vue          | 122 +++++++++++++++++-
 1 file changed, 115 insertions(+), 7 deletions(-)

diff --git a/spx-gui/src/components/project/runner/ProjectRunner.vue b/spx-gui/src/components/project/runner/ProjectRunner.vue
index d3c5497742..a15b4b0469 100644
--- a/spx-gui/src/components/project/runner/ProjectRunner.vue
+++ b/spx-gui/src/components/project/runner/ProjectRunner.vue
@@ -145,6 +145,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 +180,105 @@ 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
+
+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: 1 })
+    return result
+  } catch (err) {
+    span.setStatus({ code: 2, message: err instanceof Cancelled ? 'cancelled' : 'error' })
+    throw err
+  } finally {
+    span.end()
+  }
+}
+
+function handleRuntimePanic(error: string, functionName: string, file: string, line: number, column: number) {
+  const panic = { error, functionName, file, line, column } satisfies RuntimePanic
+  lastRuntimePanic = panic
+  lastRuntimePanicAt = Date.now()
+
+  // 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(error)
+    exception.name = 'SpxRuntimePanic'
+    try {
+      Sentry.withScope((scope) => {
+        scope.setTag('spx.runtime', 'panic')
+        scope.setContext('spx', {
+          function: functionName,
+          file,
+          line,
+          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 {
+  if (args.length !== 1 || typeof args[0] !== 'string') return null
+
+  let value: unknown
+  try {
+    value = JSON.parse(args[0])
+  } 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 <= 5000
+}
+
+function isDuplicateRuntimeError(error: string) {
+  const panic = lastRuntimePanic
+  if (panic == null || !hasRecentRuntimePanic() || panic.error === '') return false
+  return error === '' || error.includes(panic.error)
+}
 
 watch(runnerIframeRef, (iframe) => {
   if (iframe == null) return
@@ -192,6 +292,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.error, panic.functionName, panic.file, panic.line, panic.column)
     emit('console', 'log', args)
   }
   iframeWindow.console.warn = function (...args: unknown[]) {
@@ -203,17 +305,19 @@ function handleIframeWindow(iframeWindow: RunnerIframeWindow) {
     runnerIframeWindowRef.value = iframeWindow
     iframeWindow.onGameError((err: string) => {
       state.value = { type: 'failed', err }
-      capture(err, 'ProjectRunner game error')
+      if (!isDuplicateRuntimeError(err)) capture(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')
+      if (!hasRecentRuntimePanic()) capture(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')
@@ -307,6 +411,8 @@ async function runInternal(ctrl: AbortController) {
     progress: { percentage: 0, desc: null, timeLeft: null }
   } satisfies State)
   state.value = startingState
+  lastRuntimePanic = null
+  lastRuntimePanicAt = 0
   const collector = new ProgressCollector()
   collector.onProgress(throttle((progress) => (startingState.progress = progress), 100))
   try {
@@ -336,7 +442,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 +460,16 @@ 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')
+    if (!isDuplicateRuntimeError(err instanceof Error ? err.message : typeof err === 'string' ? err : '')) {
+      capture(err, 'ProjectRunner run game error')
+    }
     state.value = { type: 'failed', err }
     throw err
   }
@@ -388,7 +496,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() {

From d2108eb145a22712dcfcb20223b4a761bbaaa691 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=94=B0=E5=AE=87=E7=90=A8?= <tyk@MacBook-Pro.local>
Date: Sat, 1 Aug 2026 00:21:11 +0800
Subject: [PATCH 2/4] fix(spx-gui): defer generic runtime errors for panic
 dedupe

---
 .../project/runner/ProjectRunner.vue          | 34 +++++++++++++------
 1 file changed, 24 insertions(+), 10 deletions(-)

diff --git a/spx-gui/src/components/project/runner/ProjectRunner.vue b/spx-gui/src/components/project/runner/ProjectRunner.vue
index a15b4b0469..3fdb3e2fc8 100644
--- a/spx-gui/src/components/project/runner/ProjectRunner.vue
+++ b/spx-gui/src/components/project/runner/ProjectRunner.vue
@@ -182,6 +182,8 @@ const runnerIframeWindowRef = ref<RunnerIframeWindow | null>(null)
 let engineInitPromise: Promise<void> | null = null
 let lastRuntimePanic: RuntimePanic | null = null
 let lastRuntimePanicAt = 0
+const runtimePanicGracePeriod = 1000
+const deferredRuntimeErrorCaptures = new Set<number>()
 
 type RuntimePanic = {
   error: string
@@ -213,6 +215,7 @@ function handleRuntimePanic(error: string, functionName: string, file: string, l
   const panic = { error, functionName, file, line, column } satisfies 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.
@@ -274,10 +277,21 @@ function hasRecentRuntimePanic() {
   return panic != null && Date.now() - lastRuntimePanicAt <= 5000
 }
 
-function isDuplicateRuntimeError(error: string) {
-  const panic = lastRuntimePanic
-  if (panic == null || !hasRecentRuntimePanic() || panic.error === '') return false
-  return error === '' || error.includes(panic.error)
+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)
+  }, runtimePanicGracePeriod)
+  deferredRuntimeErrorCaptures.add(timer)
 }
 
 watch(runnerIframeRef, (iframe) => {
@@ -305,14 +319,14 @@ function handleIframeWindow(iframeWindow: RunnerIframeWindow) {
     runnerIframeWindowRef.value = iframeWindow
     iframeWindow.onGameError((err: string) => {
       state.value = { type: 'failed', err }
-      if (!isDuplicateRuntimeError(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 }
-      if (!hasRecentRuntimePanic()) 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 = traceRunnerOperation('SPX: Initialize engine', 'spx.engine.init', () =>
@@ -320,7 +334,7 @@ function handleIframeWindow(iframeWindow: RunnerIframeWindow) {
     )
     engineInitPromise.catch((err) => {
       state.value = { type: 'failed', err }
-      capture(err, 'ProjectRunner init engine error')
+      deferRuntimeErrorCapture(err, 'ProjectRunner init engine error')
     })
   }
 
@@ -403,6 +417,7 @@ function getRunCtrl() {
 
 onUnmounted(() => {
   runCtrl?.abort(new Cancelled('unmounted'))
+  clearDeferredRuntimeErrorCaptures()
 })
 
 async function runInternal(ctrl: AbortController) {
@@ -413,6 +428,7 @@ async function runInternal(ctrl: AbortController) {
   state.value = startingState
   lastRuntimePanic = null
   lastRuntimePanicAt = 0
+  clearDeferredRuntimeErrorCaptures()
   const collector = new ProgressCollector()
   collector.onProgress(throttle((progress) => (startingState.progress = progress), 100))
   try {
@@ -467,9 +483,7 @@ async function runInternal(ctrl: AbortController) {
     return hashFiles(files, ctrl.signal)
   } catch (err) {
     if (err instanceof Cancelled) throw err
-    if (!isDuplicateRuntimeError(err instanceof Error ? err.message : typeof err === 'string' ? err : '')) {
-      capture(err, 'ProjectRunner run game error')
-    }
+    deferRuntimeErrorCapture(err, 'ProjectRunner run game error')
     state.value = { type: 'failed', err }
     throw err
   }

From 67e3a5b909c45b30c9526a8d85eea595415ba769 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=94=B0=E5=AE=87=E7=90=A8?= <tyk@MacBook-Pro.local>
Date: Mon, 3 Aug 2026 10:12:03 +0800
Subject: [PATCH 3/4] perf(spx-gui): avoid parsing normal runner logs

---
 .../project/runner/ProjectRunner.vue          | 39 ++++++++++++-------
 1 file changed, 24 insertions(+), 15 deletions(-)

diff --git a/spx-gui/src/components/project/runner/ProjectRunner.vue b/spx-gui/src/components/project/runner/ProjectRunner.vue
index 3fdb3e2fc8..072e4507e8 100644
--- a/spx-gui/src/components/project/runner/ProjectRunner.vue
+++ b/spx-gui/src/components/project/runner/ProjectRunner.vue
@@ -182,8 +182,14 @@ const runnerIframeWindowRef = ref<RunnerIframeWindow | null>(null)
 let engineInitPromise: Promise<void> | null = null
 let lastRuntimePanic: RuntimePanic | null = null
 let lastRuntimePanicAt = 0
-const runtimePanicGracePeriod = 1000
+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
 
 type RuntimePanic = {
   error: string
@@ -201,18 +207,17 @@ async function traceRunnerOperation<T>(name: string, op: string, operation: () =
   })
   try {
     const result = await operation()
-    span.setStatus({ code: 1 })
+    span.setStatus({ code: sentrySpanStatus.ok })
     return result
   } catch (err) {
-    span.setStatus({ code: 2, message: err instanceof Cancelled ? 'cancelled' : 'error' })
+    span.setStatus({ code: sentrySpanStatus.error, message: err instanceof Cancelled ? 'cancelled' : 'error' })
     throw err
   } finally {
     span.end()
   }
 }
 
-function handleRuntimePanic(error: string, functionName: string, file: string, line: number, column: number) {
-  const panic = { error, functionName, file, line, column } satisfies RuntimePanic
+function handleRuntimePanic(panic: RuntimePanic) {
   lastRuntimePanic = panic
   lastRuntimePanicAt = Date.now()
   clearDeferredRuntimeErrorCaptures()
@@ -220,16 +225,16 @@ function handleRuntimePanic(error: string, functionName: string, file: string, l
   // 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(error)
+    const exception = new Error(panic.error)
     exception.name = 'SpxRuntimePanic'
     try {
       Sentry.withScope((scope) => {
         scope.setTag('spx.runtime', 'panic')
         scope.setContext('spx', {
-          function: functionName,
-          file,
-          line,
-          column
+          function: panic.functionName,
+          file: panic.file,
+          line: panic.line,
+          column: panic.column
         })
         Sentry.captureException(exception)
       })
@@ -241,11 +246,15 @@ function handleRuntimePanic(error: string, functionName: string, file: string, l
 }
 
 function parseRuntimePanic(args: unknown[]): RuntimePanic | null {
-  if (args.length !== 1 || typeof args[0] !== 'string') return 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(args[0])
+    value = JSON.parse(arg)
   } catch {
     return null
   }
@@ -274,7 +283,7 @@ function parseRuntimePanic(args: unknown[]): RuntimePanic | null {
 
 function hasRecentRuntimePanic() {
   const panic = lastRuntimePanic
-  return panic != null && Date.now() - lastRuntimePanicAt <= 5000
+  return panic != null && Date.now() - lastRuntimePanicAt <= runtimePanicDedupWindowMs
 }
 
 function clearDeferredRuntimeErrorCaptures() {
@@ -290,7 +299,7 @@ function deferRuntimeErrorCapture(err: unknown, ctx: string) {
   const timer = window.setTimeout(() => {
     deferredRuntimeErrorCaptures.delete(timer)
     if (!hasRecentRuntimePanic()) capture(err, ctx)
-  }, runtimePanicGracePeriod)
+  }, runtimePanicGracePeriodMs)
   deferredRuntimeErrorCaptures.add(timer)
 }
 
@@ -307,7 +316,7 @@ function handleIframeWindow(iframeWindow: RunnerIframeWindow) {
     // eslint-disable-next-line no-console
     console.log(...args)
     const panic = parseRuntimePanic(args)
-    if (panic != null) handleRuntimePanic(panic.error, panic.functionName, panic.file, panic.line, panic.column)
+    if (panic != null) handleRuntimePanic(panic)
     emit('console', 'log', args)
   }
   iframeWindow.console.warn = function (...args: unknown[]) {

From c103a09a8055df1bc06365d9615c9eebd1b1add4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=94=B0=E5=AE=87=E7=90=A8?= <tyk@MacBook-Pro.local>
Date: Mon, 24 Aug 2026 00:19:36 +0800
Subject: [PATCH 4/4] feat(ai): trace interactions in Sentry

Create isolated Think and Archive traces, propagate per-call trace headers, record transport and command spans, and report terminal outcomes with bounded exception context.

Consume structured backend failure metadata while keeping quota, cancellation, and exhausted 429 flows out of Sentry Issues.
---
 spx-gui/src/apps/account/.env                 |   1 +
 spx-gui/src/apps/account/env.ts               |   4 +-
 spx-gui/src/apps/xbuilder/.env                |   4 +
 spx-gui/src/apps/xbuilder/env.ts              |   4 +-
 .../project/runner/ProjectRunner.vue          | 364 ++++++++++++++++++
 spx-gui/src/setup/sentry.ts                   |   7 +-
 spx-gui/src/utils/tracing.ts                  |   4 +
 tools/ai/SENTRY_IMPLEMENTATION.md             | 207 ++++++++++
 tools/ai/SENTRY_PLAN.md                       | 276 +++++++++++++
 tools/ai/ai.go                                |  90 ++++-
 tools/ai/ai_test.go                           |  39 ++
 tools/ai/archive_finish_test.go               | 148 +++++++
 tools/ai/classify.go                          | 149 +++++++
 tools/ai/classify_test.go                     | 117 ++++++
 tools/ai/command.go                           |  29 +-
 tools/ai/command_test.go                      |   3 +-
 tools/ai/exception.go                         | 102 +++++
 tools/ai/exception_test.go                    | 154 ++++++++
 tools/ai/finish_once_test.go                  | 356 +++++++++++++++++
 tools/ai/httperr.go                           | 182 +++++++++
 tools/ai/httperr_test.go                      | 111 ++++++
 tools/ai/sentry_context.go                    |  62 +++
 tools/ai/sentry_context_test.go               |  48 +++
 tools/ai/sentry_stub.go                       |  68 ++++
 tools/ai/sentry_wasm.go                       | 181 +++++++++
 tools/ai/think_finish_test.go                 | 211 ++++++++++
 tools/ai/transport.go                         |   3 +
 tools/ai/wasmtrans/wasmtrans.go               |  35 +-
 tools/ispx/ai.go                              |  16 +
 29 files changed, 2934 insertions(+), 41 deletions(-)
 create mode 100644 tools/ai/SENTRY_IMPLEMENTATION.md
 create mode 100644 tools/ai/SENTRY_PLAN.md
 create mode 100644 tools/ai/archive_finish_test.go
 create mode 100644 tools/ai/classify.go
 create mode 100644 tools/ai/classify_test.go
 create mode 100644 tools/ai/exception.go
 create mode 100644 tools/ai/exception_test.go
 create mode 100644 tools/ai/finish_once_test.go
 create mode 100644 tools/ai/httperr.go
 create mode 100644 tools/ai/httperr_test.go
 create mode 100644 tools/ai/sentry_context.go
 create mode 100644 tools/ai/sentry_context_test.go
 create mode 100644 tools/ai/sentry_stub.go
 create mode 100644 tools/ai/sentry_wasm.go
 create mode 100644 tools/ai/think_finish_test.go

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 072e4507e8..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. */
@@ -191,6 +261,298 @@ const sentrySpanStatus = {
   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
@@ -399,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
 }
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 {