diff --git a/ITBench b/ITBench
new file mode 160000
index 00000000..29544a54
--- /dev/null
+++ b/ITBench
@@ -0,0 +1 @@
+Subproject commit 29544a547e77e862dbc450e0f3c1ec8b3935674a
diff --git a/package.json b/package.json
index 95d8172d..53395d2f 100644
--- a/package.json
+++ b/package.json
@@ -94,7 +94,7 @@
     "copy:web": "node -e \"const fs=require('fs');const p=require('path');const s=p.join('src','gateway','web','dist');const d=p.join('dist','gateway','web','dist');if(fs.existsSync(s)){fs.cpSync(s,d,{recursive:true});console.log('Copied web UI to '+d)}\"",
     "prepublishOnly": "npm run build:web && npm run build",
     "dev": "tsx src/cli-main.ts",
-    "dev:gateway": "npm run build:web && tsx src/gateway-main.ts",
+    "dev:gateway": "[ -f .siclaw/trace-env.sh ] && . .siclaw/trace-env.sh; npm run build:web && tsx src/gateway-main.ts",
     "dev:agentbox": "tsx src/agentbox-main.ts",
     "start": "node siclaw-tui.mjs",
     "start:gateway": "node siclaw-gateway.mjs",
diff --git a/siclaw-trace-db-full.yaml b/siclaw-trace-db-full.yaml
new file mode 100644
index 00000000..43fdd8f0
--- /dev/null
+++ b/siclaw-trace-db-full.yaml
@@ -0,0 +1,114 @@
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: siclaw-trace-db-pvc
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 10Gi
+  storageClassName: local-hostpath
+  volumeName: siclaw-trace-db-pv
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: siclaw-trace-db
+  labels:
+    app: siclaw-trace-db
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: siclaw-trace-db
+  template:
+    metadata:
+      labels:
+        app: siclaw-trace-db
+    spec:
+      nodeName: cpu-10-208-55-85
+      initContainers:
+      - name: init-mkdir
+        image: busybox
+        command: ["sh", "-c", "mkdir -p /data/siclaw-trace-db && chmod 777 /data/siclaw-trace-db"]
+        volumeMounts:
+        - name: host-data
+          mountPath: /data
+        securityContext:
+          privileged: true
+      containers:
+      - name: siclaw-trace-db
+        image: mysql:8.0
+        ports:
+        - containerPort: 3306
+        env:
+        - name: MYSQL_ROOT_PASSWORD
+          valueFrom:
+            secretKeyRef:
+              name: siclaw-trace-db-secret
+              key: mysql-root-password
+        - name: MYSQL_DATABASE
+          valueFrom:
+            secretKeyRef:
+              name: siclaw-trace-db-secret
+              key: mysql-database
+        - name: MYSQL_USER
+          valueFrom:
+            secretKeyRef:
+              name: siclaw-trace-db-secret
+              key: mysql-user
+        - name: MYSQL_PASSWORD
+          valueFrom:
+            secretKeyRef:
+              name: siclaw-trace-db-secret
+              key: mysql-password
+        resources:
+          requests:
+            memory: "512Mi"
+            cpu: "250m"
+          limits:
+            memory: "1Gi"
+            cpu: "500m"
+        volumeMounts:
+        - name: mysql-storage
+          mountPath: /var/lib/mysql
+        livenessProbe:
+          exec:
+            command:
+            - mysqladmin
+            - ping
+            - -h
+            - localhost
+          initialDelaySeconds: 30
+          periodSeconds: 10
+        readinessProbe:
+          exec:
+            command:
+            - mysqladmin
+            - ping
+            - -h
+            - localhost
+          initialDelaySeconds: 15
+          periodSeconds: 5
+      volumes:
+      - name: mysql-storage
+        persistentVolumeClaim:
+          claimName: siclaw-trace-db-pvc
+      - name: host-data
+        hostPath:
+          path: /data
+          type: DirectoryOrCreate
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: siclaw-trace-db
+spec:
+  selector:
+    app: siclaw-trace-db
+  ports:
+  - protocol: TCP
+    port: 3306
+    targetPort: 3306
+  type: ClusterIP
diff --git a/siclaw-trace-db-pv.yaml b/siclaw-trace-db-pv.yaml
new file mode 100644
index 00000000..11841ee3
--- /dev/null
+++ b/siclaw-trace-db-pv.yaml
@@ -0,0 +1,21 @@
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: siclaw-trace-db-pv
+spec:
+  capacity:
+    storage: 10Gi
+  accessModes:
+    - ReadWriteOnce
+  persistentVolumeReclaimPolicy: Retain
+  storageClassName: local-hostpath
+  local:
+    path: /data/siclaw-trace-db
+  nodeAffinity:
+    required:
+      nodeSelectorTerms:
+      - matchExpressions:
+        - key: kubernetes.io/hostname
+          operator: In
+          values:
+          - cpu-10-208-55-85
diff --git a/src/agentbox/http-server.ts b/src/agentbox/http-server.ts
index 22553c16..a37afd3c 100644
--- a/src/agentbox/http-server.ts
+++ b/src/agentbox/http-server.ts
@@ -241,7 +241,7 @@ export function createHttpServer(sessionManager: AgentBoxSessionManager): http.S
    * The message is sent to the Agent, and responses are returned via SSE stream.
    */
   addRoute("POST", "/api/prompt", async (req, res) => {
-    const body = (await parseJsonBody(req)) as { sessionId?: string; text?: string; mode?: SessionMode; modelProvider?: string; modelId?: string; brainType?: BrainType; systemPromptTemplate?: string; modelConfig?: Record<string, unknown>; credentials?: { manifest: Array<Record<string, unknown>>; files: Array<{ name: string; content: string; mode?: number }> } };
+    const body = (await parseJsonBody(req)) as { sessionId?: string; text?: string; mode?: SessionMode; modelProvider?: string; modelId?: string; brainType?: BrainType; systemPromptTemplate?: string; modelConfig?: Record<string, unknown>; credentials?: { manifest: Array<Record<string, unknown>>; files: Array<{ name: string; content: string; mode?: number }> }; username?: string };
 
     if (!body.text) {
       sendJson(res, 400, { error: "Missing 'text' field" });
@@ -321,7 +321,11 @@ export function createHttpServer(sessionManager: AgentBoxSessionManager): http.S
     // Subscribe to buffer events so SSE can replay them even if it connects late
     const brainUnsub = managed.brain.subscribe((event) => {
       if (!managed._promptDone) {
-        managed._eventBuffer.push(event);
+        // Stamp with server time when emitted so replayed events have accurate timestamps
+        const tsEvent = typeof event === "object" && event !== null
+          ? { ...(event as object), ts: Date.now() }
+          : event;
+        managed._eventBuffer.push(tsEvent);
       }
       // Null dpState.checklist when deep_search completes — this is the exit signal
       // for the SDK brain's auto-continue loop in claude-sdk-brain.ts.
@@ -343,6 +347,7 @@ export function createHttpServer(sessionManager: AgentBoxSessionManager): http.S
           type: "tool_progress",
           toolName: "deep_search",
           progress: event,
+          ts: Date.now(),
         });
       }
       // Sync phase events to SDK brain's dpState so the auto-continue loop
@@ -436,6 +441,19 @@ export function createHttpServer(sessionManager: AgentBoxSessionManager): http.S
       } catch { /* best-effort, don't block prompt */ }
     }
 
+    // Mark the explicit trace boundary: ONE user prompt = ONE trace file, even
+    // if pi-agent internally fires multiple agent_start/end cycles (retry or
+    // auto-compaction). beginPrompt is the start, endPrompt is called below in
+    // actuallyFinish() after the whole prompt (including any retries) settles.
+    // Also forward the displayable username so filenames use "admin" instead of
+    // the internal hex userId.
+    if (managed._traceRecorder) {
+      try {
+        if (typeof body.username === "string" && body.username) managed._traceRecorder.setUsername(body.username);
+        if (typeof body.text === "string") await managed._traceRecorder.beginPrompt(body.text);
+      } catch (err) { console.warn("[agentbox-http] trace-recorder beginPrompt failed:", err); }
+    }
+
     // Execute prompt asynchronously; notify SSE to close on completion
     console.log(`[agentbox-http] Starting prompt for session ${managed.id} [lang=${detectedLang}]`);
 
@@ -461,6 +479,18 @@ export function createHttpServer(sessionManager: AgentBoxSessionManager): http.S
         userId: sessionManager.userId,
       });
 
+      // Flush the explicit trace — fires ONCE per user prompt, even if pi-agent
+      // internally executed multiple agent_start/end cycles (retry, compaction).
+      // actuallyFinish() is the definitive "prompt is truly done" point (it waits
+      // for auto_compaction_end / auto_retry_end before firing).
+      if (managed._traceRecorder) {
+        // Fire-and-forget: actuallyFinish() is a sync callback, and we don't
+        // want to block the SSE stream close on DB flush. Failures are warned.
+        managed._traceRecorder.endPrompt(promptOutcome).catch((err) => {
+          console.warn("[agentbox-http] trace-recorder endPrompt failed:", err);
+        });
+      }
+
       // Stop buffering
       if (managed._bufferUnsub) {
         managed._bufferUnsub();
@@ -551,7 +581,11 @@ export function createHttpServer(sessionManager: AgentBoxSessionManager): http.S
       if (closed || res.writableEnded) return;
       try {
         sseEventCount++;
-        const data = JSON.stringify(event);
+        // Add server timestamp if not already present (buffered events carry their original ts)
+        const out = typeof event === "object" && event !== null && !("ts" in (event as object))
+          ? { ...(event as object), ts: Date.now() }
+          : event;
+        const data = JSON.stringify(out);
         res.write(`data: ${data}\n\n`);
       } catch (err) {
         console.warn(`[agentbox-http] SSE write error for session ${sessionId}:`, err);
@@ -674,6 +708,14 @@ export function createHttpServer(sessionManager: AgentBoxSessionManager): http.S
     }
 
     console.log(`[agentbox-http] Steering session ${sessionId}: ${body.text.slice(0, 80)}`);
+    // Record a standalone trace row for this steer BEFORE the brain consumes
+    // it. Steer messages bypass the /api/prompt path that normally triggers
+    // beginPrompt(), so without this the DP button clicks ([DP_CONFIRM],
+    // [DP_ADJUST], [DP_SKIP], [DP_REINVESTIGATE]) leave zero audit trail.
+    if (managed._traceRecorder) {
+      try { await managed._traceRecorder.recordSteerEvent(body.text); }
+      catch (err) { console.warn("[agentbox-http] recordSteerEvent failed:", err); }
+    }
     try {
       await managed.brain.steer(body.text);
       sendJson(res, 200, { ok: true });
@@ -993,6 +1035,11 @@ export function createHttpServer(sessionManager: AgentBoxSessionManager): http.S
     }
   });
 
+  // NOTE: /api/traces routes are intentionally NOT registered here.
+  // They live on the Gateway (src/gateway/server.ts) because querying the
+  // trace DB is a pure read that must not depend on the lazy-spawned
+  // AgentBox — you shouldn't have to send a prompt before you can query.
+
   // ==================== Server ====================
 
   /** Main request handler shared by HTTP and HTTPS servers */
diff --git a/src/agentbox/session.ts b/src/agentbox/session.ts
index d4d939a4..3198a1e0 100644
--- a/src/agentbox/session.ts
+++ b/src/agentbox/session.ts
@@ -24,6 +24,7 @@ import { saveSessionKnowledge } from "../memory/session-summarizer.js";
 import type { DpState } from "../tools/workflow/dp-tools.js";
 import { loadConfig, getEmbeddingConfig } from "../core/config.js";
 import { emitDiagnostic } from "../shared/diagnostic-events.js";
+import { maybeCreateTraceRecorder, type TraceRecorder } from "../core/trace-recorder.js";
 // topic-consolidator import removed — consolidation disabled
 
 export interface ManagedSession {
@@ -70,6 +71,10 @@ export interface ManagedSession {
   _lastSavedMessageCount: number;
   /** Pending release timer (cleared when a new prompt arrives before TTL expires) */
   _releaseTimer: ReturnType<typeof setTimeout> | null;
+  /** Trace recorder — writes per-prompt JSON to .siclaw/traces. null when disabled. */
+  _traceRecorder?: TraceRecorder | null;
+  /** Unsubscribe fn for trace recorder's brain subscription. */
+  _traceUnsub?: (() => void) | null;
 }
 
 export interface PersistedDpStateSnapshot {
@@ -262,6 +267,27 @@ export class AgentBoxSessionManager {
     this.sessions.set(id, managed);
     emitDiagnostic({ type: "session_created", sessionId: id });
 
+    // Trace recorder — writes per-prompt JSON traces to .siclaw/traces for
+    // offline retrospective. Filesystem only, not exposed via HTTP/SSE/WS.
+    // Disable with SICLAW_TRACE_DISABLE=1; override path with SICLAW_TRACE_DIR.
+    try {
+      const recorder = await maybeCreateTraceRecorder({
+        sessionId: id,
+        userId: this.userId,
+        mode: effectiveMode,
+        brainType: effectiveBrainType,
+        getSessionStats: () => managed!.brain.getSessionStats(),
+        getModel: () => managed!.brain.getModel(),
+        dpStateRef: result.dpStateRef,
+      });
+      if (recorder) {
+        managed._traceRecorder = recorder;
+        managed._traceUnsub = recorder.attach(managed.brain);
+      }
+    } catch (err) {
+      console.warn(`[agentbox-session] Trace recorder setup failed for ${id}:`, err);
+    }
+
     // Tool execution timing (for tool_call diagnostic events).
     // NOTE: tool_execution_start/end events depend on the brain implementation.
     // claude-sdk brain emits them reliably; pi-agent brain depends on the SDK's
@@ -491,6 +517,18 @@ export class AgentBoxSessionManager {
       console.warn(`[agentbox-session] Memory auto-save failed for ${sessionId}:`, err);
     }
 
+    // 1b. Close trace recorder — flushes any in-flight trace to disk.
+    if (managed._traceUnsub) {
+      try { managed._traceUnsub(); } catch { /* ignore */ }
+      managed._traceUnsub = null;
+    }
+    if (managed._traceRecorder) {
+      try { await managed._traceRecorder.close(); } catch (err) {
+        console.warn(`[agentbox-session] Trace recorder close failed for ${sessionId}:`, err);
+      }
+      managed._traceRecorder = null;
+    }
+
     // 2. Shutdown per-session MCP connections
     if (managed.mcpManager) {
       try {
diff --git a/src/cli-main.ts b/src/cli-main.ts
index d1f8f316..bd9b649f 100644
--- a/src/cli-main.ts
+++ b/src/cli-main.ts
@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import {
   InteractiveMode,
@@ -13,6 +14,7 @@ import { saveSessionKnowledge } from "./memory/session-summarizer.js";
 // topic-consolidator import removed — consolidation disabled
 import type { BrainType } from "./core/brain-session.js";
 import { debugPodGC, debugPodCache } from "./tools/infra/debug-pod.js";
+import { maybeCreateTraceRecorder } from "./core/trace-recorder.js";
 
 
 // Parse arguments
@@ -116,6 +118,41 @@ if (memoryIndexer) {
     .catch(err => console.warn("[siclaw] Startup maintenance failed:", err));
 }
 
+// Trace recorder — writes per-prompt JSON traces to .siclaw/traces for offline
+// retrospective. Not exposed via HTTP/SSE. Disable with SICLAW_TRACE_DISABLE=1.
+const osUsername = (() => { try { return os.userInfo().username; } catch { return process.env.USER ?? "unknown"; } })();
+const traceRecorder = await maybeCreateTraceRecorder({
+  sessionId: sessionManager.getSessionId?.() ?? `cli-${Date.now()}`,
+  userId: osUsername,
+  username: osUsername,
+  mode: "cli",
+  brainType: brain.brainType,
+  getSessionStats: () => brain.getSessionStats(),
+  getModel: () => brain.getModel(),
+});
+if (traceRecorder) {
+  traceRecorder.attach(brain);
+  const traceDir = process.env.SICLAW_TRACE_DIR ?? path.join(process.cwd(), ".siclaw", "traces");
+  console.log(`[siclaw] Trace recording → ${path.relative(process.cwd(), traceDir) || traceDir}`);
+
+  // Wrap session.prompt (what InteractiveMode calls) so each user-initiated
+  // prompt yields exactly ONE trace file, even if pi-agent internally runs
+  // multiple agent_start/end cycles (empty-response retry, auto-compaction).
+  const origSessionPrompt = session.prompt.bind(session);
+  (session as unknown as { prompt: (text: string) => Promise<void> }).prompt = async (text: string) => {
+    await traceRecorder.beginPrompt(text);
+    let outcome: "completed" | "error" = "completed";
+    try {
+      await origSessionPrompt(text);
+    } catch (err) {
+      outcome = "error";
+      throw err;
+    } finally {
+      await traceRecorder.endPrompt(outcome);
+    }
+  };
+}
+
 // Debug: subscribe to all session events and write to log file
 if (debugMode) {
   const logFile = path.join(process.cwd(), "siclaw-debug.log");
@@ -228,6 +265,10 @@ if (session.sessionFile) {
   }
 }
 
+// Close trace recorder — flushes any in-flight trace.
+if (traceRecorder) {
+  try { await traceRecorder.close(); } catch { /* ignore */ }
+}
 // Clean up cached debug pods
 try { await debugPodCache.evictAll(); } catch { /* ignore */ }
 // Shutdown MCP connections
diff --git a/src/core/trace-recorder.test.ts b/src/core/trace-recorder.test.ts
new file mode 100644
index 00000000..aff24c55
--- /dev/null
+++ b/src/core/trace-recorder.test.ts
@@ -0,0 +1,529 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { TraceRecorder } from "./trace-recorder.js";
+import { emitDiagnostic } from "../shared/diagnostic-events.js";
+
+describe("TraceRecorder", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "trace-rec-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function makeRecorder(sessionId = "sess-1") {
+    return new TraceRecorder({
+      traceDir: tmpDir,
+      sessionId,
+      userId: "u1",
+      mode: "cli",
+      brainType: "pi-agent",
+      getSessionStats: () => ({
+        tokens: { input: 100, output: 50, cacheRead: 10, cacheWrite: 5, total: 165 },
+        cost: 0.01,
+      }),
+      getModel: () => ({
+        id: "test-model",
+        name: "Test",
+        provider: "fake",
+        contextWindow: 8000,
+        maxTokens: 2000,
+        reasoning: false,
+      }),
+    });
+  }
+
+  function readTraces(): Array<Record<string, unknown>> {
+    return fs
+      .readdirSync(tmpDir)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => JSON.parse(fs.readFileSync(path.join(tmpDir, f), "utf-8")));
+  }
+
+  it("writes a JSON trace on agent_start → agent_end with tool calls", () => {
+    const rec = makeRecorder();
+    const listeners: Array<(e: unknown) => void> = [];
+    const fakeBrain = {
+      brainType: "pi-agent" as const,
+      subscribe(fn: (e: unknown) => void) {
+        listeners.push(fn);
+        return () => {
+          const i = listeners.indexOf(fn);
+          if (i >= 0) listeners.splice(i, 1);
+        };
+      },
+    } as any;
+
+    rec.attach(fakeBrain);
+    const emit = (e: unknown) => listeners.forEach((fn) => fn(e));
+
+    emit({ type: "message_end", message: { role: "user", content: "check pods" } });
+    emit({ type: "agent_start" });
+    emit({ type: "turn_start" });
+    emit({
+      type: "tool_execution_start",
+      toolName: "restricted_bash",
+      toolCallId: "tc1",
+      args: { command: "kubectl get pods" },
+    });
+    emit({
+      type: "tool_execution_end",
+      toolName: "restricted_bash",
+      toolCallId: "tc1",
+      result: { content: [{ type: "text", text: "pod1 Running" }] },
+    });
+    emit({
+      type: "message_end",
+      message: {
+        role: "assistant",
+        stopReason: "end_turn",
+        content: [{ type: "text", text: "All pods healthy." }],
+      },
+    });
+    emit({ type: "turn_end" });
+    emit({ type: "agent_end" });
+
+    const traces = readTraces();
+    expect(traces).toHaveLength(1);
+    const t = traces[0] as any;
+    expect(t.sessionId).toBe("sess-1");
+    expect(t.userMessage).toBe("check pods");
+    expect(t.outcome).toBe("completed");
+    expect(t.mode).toBe("cli");
+    expect(t.brainType).toBe("pi-agent");
+
+    const toolCallSteps = t.steps.filter((s: any) => s.kind === "tool_call");
+    expect(toolCallSteps).toHaveLength(1);
+    expect(toolCallSteps[0].name).toBe("restricted_bash");
+    expect(toolCallSteps[0].args).toEqual({ command: "kubectl get pods" });
+    expect(toolCallSteps[0].output).toBe("pod1 Running");
+    expect(toolCallSteps[0].isError).toBe(false);
+    expect(typeof toolCallSteps[0].durationMs).toBe("number");
+    // Beijing-time strings: "YYYY-MM-DD HH:mm:ss.SSS"
+    expect(toolCallSteps[0].startedAt).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}$/);
+    expect(toolCallSteps[0].endedAt).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}$/);
+
+    const msgSteps = t.steps.filter((s: any) => s.kind === "message");
+    expect(msgSteps[0].text).toBe("All pods healthy.");
+    expect(msgSteps[0].role).toBe("assistant");
+    expect(msgSteps[0].ts).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}$/);
+
+    expect(t.startedAt).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}$/);
+    expect(t.endedAt).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}$/);
+
+    expect(t.stats.tokensDelta).toBeDefined();
+    // schemaVersion 1.2 since isInjectedPrompt + dpStatusEnd were added.
+    expect(t.schemaVersion).toBe("1.2");
+    expect(typeof t.isInjectedPrompt).toBe("boolean");
+    expect(t.dpStatusEnd).toBe("idle");
+    // Redundant fields removed.
+    expect(t.traceId).toBeUndefined();
+    expect(t.eventCount).toBeUndefined();
+    expect(t.stats.before).toBeUndefined();
+    expect(t.stats.after).toBeUndefined();
+  });
+
+  it("records skill via local_script (Path B)", () => {
+    const rec = makeRecorder();
+    const listeners: Array<(e: unknown) => void> = [];
+    const fakeBrain = {
+      brainType: "pi-agent" as const,
+      subscribe(fn: (e: unknown) => void) { listeners.push(fn); return () => {}; },
+    } as any;
+    rec.attach(fakeBrain);
+    const emit = (e: unknown) => listeners.forEach((fn) => fn(e));
+
+    emit({ type: "agent_start" });
+    emit({
+      type: "tool_execution_start",
+      toolName: "local_script",
+      toolCallId: "tc1",
+      args: { skill: "pod-diagnosis", script: "check.sh" },
+    });
+    emit({
+      type: "tool_execution_end",
+      toolName: "local_script",
+      toolCallId: "tc1",
+      result: { content: [{ type: "text", text: "ok" }] },
+    });
+    emit({ type: "agent_end" });
+
+    const t = readTraces()[0] as any;
+    const toolCall = t.steps.find((s: any) => s.kind === "tool_call");
+    expect(toolCall.skill).toEqual({ skillName: "pod-diagnosis", scriptName: "check.sh", via: "local_script" });
+    expect(t.skillsUsed).toHaveLength(1);
+    expect(t.skillsUsed[0]).toMatchObject({ skillName: "pod-diagnosis", via: "local_script" });
+  });
+
+  it("records skill via read(SKILL.md) (Path A)", () => {
+    const rec = makeRecorder();
+    const listeners: Array<(e: unknown) => void> = [];
+    const fakeBrain = {
+      brainType: "pi-agent" as const,
+      subscribe(fn: (e: unknown) => void) { listeners.push(fn); return () => {}; },
+    } as any;
+    rec.attach(fakeBrain);
+    const emit = (e: unknown) => listeners.forEach((fn) => fn(e));
+
+    emit({ type: "agent_start" });
+    emit({
+      type: "tool_execution_start",
+      toolName: "read",
+      toolCallId: "r1",
+      args: { path: "/home/yye/siclaw/skills/core/cluster-events/SKILL.md" },
+    });
+    emit({
+      type: "tool_execution_end",
+      toolName: "read",
+      toolCallId: "r1",
+      result: { content: [{ type: "text", text: "# Cluster Events\n..." }] },
+    });
+    emit({
+      type: "tool_execution_start",
+      toolName: "read",
+      toolCallId: "r2",
+      args: { path: "/home/yye/siclaw/skills/user/yye/my-skill/SKILL.md" },
+    });
+    emit({
+      type: "tool_execution_end",
+      toolName: "read",
+      toolCallId: "r2",
+      result: { content: [{ type: "text", text: "..." }] },
+    });
+    emit({
+      type: "tool_execution_start",
+      toolName: "read",
+      toolCallId: "r3",
+      args: { path: "/home/yye/siclaw/src/core/agent-factory.ts" },  // non-skill, should be ignored
+    });
+    emit({
+      type: "tool_execution_end",
+      toolName: "read",
+      toolCallId: "r3",
+      result: { content: [{ type: "text", text: "..." }] },
+    });
+    emit({ type: "agent_end" });
+
+    const t = readTraces()[0] as any;
+    expect(t.skillsUsed).toHaveLength(2);
+    expect(t.skillsUsed[0]).toEqual(expect.objectContaining({
+      skillName: "cluster-events", scope: "core", via: "read",
+    }));
+    expect(t.skillsUsed[1]).toEqual(expect.objectContaining({
+      skillName: "my-skill", scope: "user", via: "read",
+    }));
+    // Non-SKILL.md read should have no skill field.
+    const tcs = t.steps.filter((s: any) => s.kind === "tool_call");
+    expect(tcs[2].skill).toBeUndefined();
+  });
+
+  it("drops redundant toolResult and user role messages from steps", () => {
+    const rec = makeRecorder();
+    const listeners: Array<(e: unknown) => void> = [];
+    const fakeBrain = {
+      brainType: "pi-agent" as const,
+      subscribe(fn: (e: unknown) => void) { listeners.push(fn); return () => {}; },
+    } as any;
+    rec.attach(fakeBrain);
+    const emit = (e: unknown) => listeners.forEach((fn) => fn(e));
+
+    emit({ type: "message_end", message: { role: "user", content: "hi" } });
+    emit({ type: "agent_start" });
+    emit({ type: "message_end", message: { role: "toolResult", content: "duplicate of tool output" } });
+    emit({ type: "message_end", message: { role: "assistant", content: [{ type: "text", text: "reply" }] } });
+    emit({ type: "agent_end" });
+
+    const t = readTraces()[0] as any;
+    const messages = t.steps.filter((s: any) => s.kind === "message");
+    expect(messages).toHaveLength(1);
+    expect(messages[0].role).toBe("assistant");
+  });
+
+  it("enriches local_script scope when diagnostic event fires BEFORE tool_execution_end", () => {
+    const rec = makeRecorder();
+    const listeners: Array<(e: unknown) => void> = [];
+    const fakeBrain = {
+      brainType: "pi-agent" as const,
+      subscribe(fn: (e: unknown) => void) { listeners.push(fn); return () => {}; },
+    } as any;
+    rec.attach(fakeBrain);
+    const emit = (e: unknown) => listeners.forEach((fn) => fn(e));
+
+    // Simulate the real order observed in local-script.ts:
+    // diagnostic fires *inside* the tool's execute(), before the brain dispatches tool_execution_end.
+    emit({ type: "agent_start" });
+    emit({ type: "tool_execution_start", toolName: "local_script", toolCallId: "tc1",
+           args: { skill: "volcano-diagnose-pod", script: "diagnose-pod.sh" } });
+    emitDiagnostic({
+      type: "skill_call",
+      skillName: "volcano-diagnose-pod",
+      scriptName: "diagnose-pod.sh",
+      scope: "personal",
+      outcome: "success",
+      durationMs: 123,
+      sessionId: "sess-1",
+    });
+    emit({ type: "tool_execution_end", toolName: "local_script", toolCallId: "tc1",
+           result: { content: [{ type: "text", text: "done" }] } });
+    emit({ type: "agent_end" });
+
+    const t = readTraces()[0] as any;
+    const toolCall = t.steps.find((s: any) => s.kind === "tool_call");
+    expect(toolCall.skill.scope).toBe("personal");
+  });
+
+  it("marks outcome as error when assistant stopReason=error", () => {
+    const rec = makeRecorder();
+    const listeners: Array<(e: unknown) => void> = [];
+    const fakeBrain = {
+      brainType: "pi-agent" as const,
+      subscribe(fn: (e: unknown) => void) {
+        listeners.push(fn);
+        return () => {};
+      },
+    } as any;
+    rec.attach(fakeBrain);
+    const emit = (e: unknown) => listeners.forEach((fn) => fn(e));
+
+    emit({ type: "agent_start" });
+    emit({
+      type: "message_end",
+      message: {
+        role: "assistant",
+        stopReason: "error",
+        errorMessage: "rate limit",
+        content: [],
+      },
+    });
+    emit({ type: "agent_end" });
+
+    const t = readTraces()[0] as any;
+    expect(t.outcome).toBe("error");
+  });
+
+  it("writes filename as trace-<date>-<time>-<user>.json", () => {
+    const rec = makeRecorder("sess-abc");
+    const listeners: Array<(e: unknown) => void> = [];
+    const fakeBrain = {
+      brainType: "pi-agent" as const,
+      subscribe(fn: (e: unknown) => void) { listeners.push(fn); return () => {}; },
+    } as any;
+    rec.attach(fakeBrain);
+    const emit = (e: unknown) => listeners.forEach((fn) => fn(e));
+    emit({ type: "agent_start" });
+    emit({ type: "agent_end" });
+
+    const files = fs.readdirSync(tmpDir).filter((f) => f.endsWith(".json"));
+    expect(files).toHaveLength(1);
+    // trace-YYYYMMDD-HH-mm-ss-<user>.json
+    expect(files[0]).toMatch(/^trace-\d{8}-\d{2}-\d{2}-\d{2}-u1\.json$/);
+  });
+
+  it("writes separate files for separate agent_start/agent_end cycles", () => {
+    const rec = makeRecorder();
+    const listeners: Array<(e: unknown) => void> = [];
+    const fakeBrain = {
+      brainType: "pi-agent" as const,
+      subscribe(fn: (e: unknown) => void) {
+        listeners.push(fn);
+        return () => {};
+      },
+    } as any;
+    rec.attach(fakeBrain);
+    const emit = (e: unknown) => listeners.forEach((fn) => fn(e));
+
+    emit({ type: "message_end", message: { role: "user", content: "first" } });
+    emit({ type: "agent_start" });
+    emit({ type: "agent_end" });
+
+    emit({ type: "message_end", message: { role: "user", content: "second" } });
+    emit({ type: "agent_start" });
+    emit({ type: "agent_end" });
+
+    const traces = readTraces();
+    expect(traces).toHaveLength(2);
+    const userMsgs = traces.map((t: any) => t.userMessage).sort();
+    expect(userMsgs).toEqual(["first", "second"]);
+  });
+
+  it("setUserMessage() captures user input when message_end{role:user} is absent (web/agentbox path)", () => {
+    const rec = makeRecorder();
+    const listeners: Array<(e: unknown) => void> = [];
+    const fakeBrain = {
+      brainType: "pi-agent" as const,
+      subscribe(fn: (e: unknown) => void) { listeners.push(fn); return () => {}; },
+    } as any;
+    rec.attach(fakeBrain);
+    const emit = (e: unknown) => listeners.forEach((fn) => fn(e));
+
+    // Web-mode flow: caller hands the raw prompt to the recorder, then the
+    // brain emits agent_start directly (NO preceding user message_end event).
+    rec.setUserMessage("当前的集群有多少pod");
+    emit({ type: "agent_start" });
+    emit({
+      type: "message_end",
+      message: { role: "assistant", stopReason: "end_turn", content: [{ type: "text", text: "753 pods" }] },
+    });
+    emit({ type: "agent_end" });
+
+    const t = readTraces()[0] as any;
+    expect(t.userMessage).toBe("当前的集群有多少pod");
+  });
+
+  it("explicit mode merges multiple internal agent_start/end cycles into ONE trace (retry/compaction case)", () => {
+    // This is the real-world regression: ONE user prompt ("检查集群硬件问题...")
+    // caused pi-agent to fire TWO agent_start/agent_end cycles internally (due
+    // to empty-response retry or auto-compaction), which previously produced two
+    // trace files. With explicit boundaries via beginPrompt/endPrompt, both
+    // cycles must be merged into a single trace file.
+    const rec = makeRecorder();
+    const listeners: Array<(e: unknown) => void> = [];
+    const fakeBrain = {
+      brainType: "pi-agent" as const,
+      subscribe(fn: (e: unknown) => void) { listeners.push(fn); return () => {}; },
+    } as any;
+    rec.attach(fakeBrain);
+    const emit = (e: unknown) => listeners.forEach((fn) => fn(e));
+
+    rec.beginPrompt("检查当前的这个集群里面有哪些硬件问题？");
+
+    // Internal cycle #1 — initial run with tool calls
+    emit({ type: "agent_start" });
+    emit({ type: "turn_start" });
+    emit({ type: "tool_execution_start", toolName: "bash", toolCallId: "t1",
+           args: { command: "kubectl get nodes -o wide" } });
+    emit({ type: "tool_execution_end", toolName: "bash", toolCallId: "t1",
+           result: { content: [{ type: "text", text: "Ready nodes..." }] } });
+    emit({ type: "turn_end" });
+    emit({ type: "agent_end" });
+
+    // Pi-agent re-emits the user message verbatim (with language prefix) when
+    // it retries — this must NOT overwrite our authoritative userMessage.
+    emit({
+      type: "message_end",
+      message: { role: "user", content: "[System: respond in Chinese]\n检查当前的这个集群里面有哪些硬件问题？" },
+    });
+
+    // Internal cycle #2 — retry / continuation with more tool calls
+    emit({ type: "agent_start" });
+    emit({ type: "turn_start" });
+    emit({ type: "tool_execution_start", toolName: "bash", toolCallId: "t2",
+           args: { command: "kubectl top nodes" } });
+    emit({ type: "tool_execution_end", toolName: "bash", toolCallId: "t2",
+           result: { content: [{ type: "text", text: "cpu/mem..." }] } });
+    emit({
+      type: "message_end",
+      message: { role: "assistant", stopReason: "end_turn",
+                 content: [{ type: "text", text: "报告完成" }] },
+    });
+    emit({ type: "turn_end" });
+    emit({ type: "agent_end" });
+
+    rec.endPrompt("completed");
+
+    const traces = readTraces();
+    expect(traces).toHaveLength(1);                                // ← 关键断言：只有 1 份文件
+    const t = traces[0] as any;
+    expect(t.userMessage).toBe("检查当前的这个集群里面有哪些硬件问题？"); // ← 不被 retry 时的 pi-agent 回放污染
+    const toolCalls = t.steps.filter((s: any) => s.kind === "tool_call");
+    expect(toolCalls).toHaveLength(2);                             // ← 两个周期的工具调用都在
+    expect((toolCalls[0].args as any).command).toBe("kubectl get nodes -o wide");
+    expect((toolCalls[1].args as any).command).toBe("kubectl top nodes");
+    expect(t.outcome).toBe("completed");
+  });
+
+  it("auto mode (no beginPrompt) still works via agent_start/end as fallback", () => {
+    // If external code never calls beginPrompt, we fall back to auto-detect.
+    // This path must keep working for non-wrapped callers.
+    const rec = makeRecorder();
+    const listeners: Array<(e: unknown) => void> = [];
+    const fakeBrain = {
+      brainType: "pi-agent" as const,
+      subscribe(fn: (e: unknown) => void) { listeners.push(fn); return () => {}; },
+    } as any;
+    rec.attach(fakeBrain);
+    const emit = (e: unknown) => listeners.forEach((fn) => fn(e));
+
+    emit({ type: "message_end", message: { role: "user", content: "hello" } });
+    emit({ type: "agent_start" });
+    emit({ type: "tool_execution_start", toolName: "bash", toolCallId: "tc1", args: { command: "ls" } });
+    emit({ type: "tool_execution_end", toolName: "bash", toolCallId: "tc1",
+           result: { content: [{ type: "text", text: "ok" }] } });
+    emit({ type: "agent_end" });
+
+    const t = readTraces()[0] as any;
+    expect(t.userMessage).toBe("hello");
+    expect(t.steps.filter((s: any) => s.kind === "tool_call")).toHaveLength(1);
+  });
+
+  it("close() flushes an in-flight trace", () => {
+    const rec = makeRecorder();
+    const listeners: Array<(e: unknown) => void> = [];
+    const fakeBrain = {
+      brainType: "pi-agent" as const,
+      subscribe(fn: (e: unknown) => void) {
+        listeners.push(fn);
+        return () => {};
+      },
+    } as any;
+    rec.attach(fakeBrain);
+    const emit = (e: unknown) => listeners.forEach((fn) => fn(e));
+
+    emit({ type: "agent_start" });
+    emit({ type: "turn_start" });
+    rec.close();
+
+    expect(readTraces()).toHaveLength(1);
+  });
+
+  // ── isInjectedPrompt classification ─────────────────────
+  // Rule: injected = TRUE only when the prompt body is 100% machine-generated
+  // by a UI button click. If the user typed any of the content (even with a
+  // marker prefix like "[Deep Investigation]\n..."), it's NOT injected.
+  describe("isInjectedPrompt classification", () => {
+    async function flushAndRead(userMessage: string): Promise<boolean> {
+      const rec = makeRecorder(`sess-inj-${Math.random().toString(36).slice(2, 8)}`);
+      await rec.beginPrompt(userMessage);
+      await rec.endPrompt("completed");
+      await rec.close();
+      const files = fs.readdirSync(tmpDir).filter((f) => f.startsWith("trace-"));
+      const body = JSON.parse(fs.readFileSync(path.join(tmpDir, files[files.length - 1]), "utf-8"));
+      return body.isInjectedPrompt as boolean;
+    }
+
+    // ── should be TRUE (pure canned button clicks) ───────
+    it.each([
+      ["[DP_CONFIRM]\nThe user has confirmed hypotheses.",              "DP_CONFIRM button"],
+      ["[DP_SKIP]\nSkip validation and present conclusion.",            "DP_SKIP button"],
+      ["[DP_REINVESTIGATE]\nRe-investigate from a different angle.",    "DP_REINVESTIGATE default (blank hint)"],
+      ["[Feedback]",                                                     "Feedback button"],
+      ["[investigation feedback: confirmed] investigationId=inv-abc",    "verdict-only, no comment"],
+      ["[investigation feedback: corrected] investigationId=inv-abc",    "corrected verdict, no comment"],
+      ["[investigation feedback: rejected] investigationId=inv-abc",     "rejected verdict, no comment"],
+      ["Your conclusion may not be the root cause. Please dig deeper — trace where the problematic values, configurations, or states come from.",
+                                                                         "dig-deeper button"],
+    ])("classifies %j (%s) as injected", async (msg) => {
+      expect(await flushAndRead(msg)).toBe(true);
+    });
+
+    // ── should be FALSE (user-typed content, even with marker prefix) ──
+    it.each([
+      ["[Deep Investigation]\n当前集群有没有网络超时问题？",               "Deep Investigation toggle + user question"],
+      ["[DP_ADJUST]\n把第 2 个假设权重调低一点",                           "DP_ADJUST with user adjustment"],
+      ["[DP_REINVESTIGATE]\n从调度器日志角度再查一遍",                     "DP_REINVESTIGATE with custom hint"],
+      ["[investigation feedback: corrected] investigationId=inv-abc 其实根因是 DNS 不是 CNI",
+                                                                         "corrected verdict + user comment"],
+      ["[investigation feedback: rejected] investigationId=inv-abc 这些都不对",
+                                                                         "rejected verdict + user comment"],
+      ["帮我查一下 nginx pod 为什么 crash",                                "plain user prompt"],
+      ["",                                                                "empty string"],
+    ])("classifies %j (%s) as NOT injected", async (msg) => {
+      expect(await flushAndRead(msg)).toBe(false);
+    });
+  });
+});
diff --git a/src/core/trace-recorder.ts b/src/core/trace-recorder.ts
new file mode 100644
index 00000000..16920dbb
--- /dev/null
+++ b/src/core/trace-recorder.ts
@@ -0,0 +1,896 @@
+/**
+ * Trace Recorder — writes per-prompt JSON traces to disk for offline retrospective.
+ *
+ * Hooks into BrainSession.subscribe() + diagnostic event bus. One JSON file per
+ * agent run (bounded by agent_start/agent_end events). Filesystem only, never
+ * exposed through HTTP/SSE/WebSocket.
+ *
+ * Default output: <cwd>/.siclaw/traces/trace-<sessionId>-<idx>-<ts>.json
+ * Override: env SICLAW_TRACE_DIR=/path
+ * Disable:  env SICLAW_TRACE_DISABLE=1
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { onDiagnostic, type DiagnosticEvent } from "../shared/diagnostic-events.js";
+import type { BrainSession, BrainSessionStats, BrainModelInfo } from "./brain-session.js";
+import { getTraceStore, type TraceStore } from "./trace-store.js";
+import type { DpStateRef } from "./types.js";
+
+// ── Types ──────────────────────────────────────────────
+
+export interface TraceRecorderOpts {
+  traceDir: string;
+  sessionId: string;
+  /** Internal user identifier (hex ID in web mode, OS username in CLI). Used as the
+   *  machine-readable field in the JSON body; also used as the filename fallback
+   *  when no displayable username is available. */
+  userId?: string;
+  /** Displayable username (e.g. "admin") — set via constructor for CLI or later via
+   *  setUsername() for web mode. Preferred over userId in filenames. */
+  username?: string;
+  mode: string;
+  brainType?: string;
+  getSessionStats?: () => BrainSessionStats | undefined;
+  getModel?: () => BrainModelInfo | undefined;
+  /** Persistent store; when provided, each flush also inserts a DB row. */
+  store?: TraceStore | null;
+  /** Readonly view of the session's DP workflow state. Sampled at flush() to
+   *  populate trace.dpStatusEnd. null/undefined → recorded as "idle". */
+  dpStateRef?: DpStateRef;
+}
+
+/**
+ * Classification rule for `isInjectedPrompt`:
+ *
+ *   TRUE  — the prompt body is 100% machine-generated by a UI button click,
+ *           the user did not type any of the content.
+ *   FALSE — the prompt contains user-typed content, even if it carries a
+ *           marker prefix (e.g. `[Deep Investigation]\n<user question>` or
+ *           `[DP_ADJUST]\n<user adjustment>`). Those markers are *mode
+ *           flags*, not content replacements — analytics that want
+ *           "real user intent" still want to see these prompts.
+ *
+ * Three matching strategies, in order:
+ *   1. EXACT string match — canned button bodies (DP_CONFIRM / DP_SKIP / …)
+ *   2. PREFIX match       — full canned long-form texts (dig-deeper)
+ *   3. REGEX match        — structured template with no trailing user text
+ *                           (investigation feedback verdicts without comment)
+ */
+const CANNED_INJECTED_STRINGS: readonly string[] = [
+  "[DP_CONFIRM]\nThe user has confirmed hypotheses.",
+  "[DP_SKIP]\nSkip validation and present conclusion.",
+  "[DP_REINVESTIGATE]\nRe-investigate from a different angle.",  // default when user leaves hint blank
+  "[Feedback]",
+];
+
+const CANNED_INJECTED_PREFIXES: readonly string[] = [
+  "Your conclusion may not be the root cause. Please dig deeper",  // dig-deeper button, long canned paragraph
+];
+
+const CANNED_INJECTED_PATTERNS: readonly RegExp[] = [
+  // [investigation feedback: (confirmed|corrected|rejected)] investigationId=<id>
+  // with NO trailing user comment — verdict-only click. If the user adds a
+  // comment after the id, the regex deliberately fails to match → false.
+  /^\[investigation feedback: (?:confirmed|corrected|rejected)\] investigationId=\S+$/,
+];
+
+function isInjectedPromptText(text: string): boolean {
+  if (!text) return false;
+  const trimmed = text.trim();
+  if (CANNED_INJECTED_STRINGS.includes(trimmed)) return true;
+  if (CANNED_INJECTED_PREFIXES.some((p) => trimmed.startsWith(p))) return true;
+  if (CANNED_INJECTED_PATTERNS.some((re) => re.test(trimmed))) return true;
+  return false;
+}
+
+/**
+ * How a skill was referenced in a single tool call.
+ *   - "read"         = agent read the SKILL.md documentation (Path A; the dominant path
+ *                      since most siclaw skills are pure markdown instructions).
+ *   - "local_script" = agent invoked a bundled script under the skill (Path B).
+ */
+type SkillVia = "read" | "local_script";
+
+interface SkillRef {
+  skillName: string;
+  scope?: string;           // core | extension | global | personal | user | ...
+  scriptName?: string;      // only for via === "local_script"
+  via: SkillVia;
+}
+
+interface ToolCallStep {
+  kind: "tool_call";
+  name: string;
+  toolCallId?: string;
+  args: unknown;
+  output: string;
+  isError: boolean;
+  startedAt: string;   // Beijing time (UTC+8), format: YYYY-MM-DD HH:mm:ss.SSS
+  endedAt: string;
+  durationMs: number;  // Duration — kept as number for easy arithmetic
+  skill?: SkillRef;
+}
+
+interface MessageStep {
+  kind: "message";
+  role: "assistant";   // user/toolResult messages dropped as redundant
+  stopReason?: string;
+  ts: string;
+  text: string;
+  toolCalls?: Array<{ name: string; args?: unknown; toolCallId?: string }>;
+}
+
+interface LifecycleStep {
+  kind: "turn_start" | "turn_end" | "auto_compaction" | "auto_retry" | "model_error";
+  ts: string;
+  detail?: unknown;
+}
+
+type TraceStep = ToolCallStep | MessageStep | LifecycleStep;
+
+interface SkillUsageRecord extends SkillRef {
+  ts: string;                         // when the usage happened (Beijing time)
+  outcome?: "success" | "error";      // only populated for local_script via diagnostic bus
+  durationMs?: number;                // only populated for local_script via diagnostic bus
+}
+
+// ── Recorder ───────────────────────────────────────────
+
+export class TraceRecorder {
+  private pendingTools = new Map<string, { name: string; args: unknown; startedAtMs: number; toolCallId?: string }>();
+  private steps: TraceStep[] = [];
+  private skillsUsed: SkillUsageRecord[] = [];
+  /**
+   * Buffer for `skill_call` diagnostic events that arrive BEFORE their corresponding
+   * tool_execution_end (because `local_script.ts` emits the diagnostic synchronously
+   * during execute(), whereas the brain emits tool_execution_end afterwards). When
+   * the tool_call step is later constructed, we drain the matching buffered entry to
+   * populate `scope` on the step's `skill` field. Fixes the empirical mismatch where
+   * `skillsUsed[]` had scope but the tool_call step did not.
+   */
+  private pendingSkillMeta: Array<{ skillName: string; scriptName: string; scope: string; outcome: "success" | "error"; durationMs: number; ts: string }> = [];
+  private active = false;
+  private promptIdx = 0;
+  private userMessage = "";
+  private lastUserMessageBuffered = "";
+  private startedAtMs = 0;
+  private prevStats: BrainSessionStats | undefined;
+  private unsubscribeDiag: (() => void) | null = null;
+  private outcome: "completed" | "error" = "completed";
+  /** Computed once at startTrace(): does userMessage start with a UI-button
+   *  injection prefix? Stored alongside the trace for analytics filtering. */
+  private isInjectedPrompt = false;
+  /** Business id (trace_key) assigned at startTrace() — reused across the
+   *  in-flight stub insert and the final flush upsert so they refer to the
+   *  same row. Format matches the filename stem: `trace-YYYYMMDD-HH-MM-SS-<user>`. */
+  private currentTraceKey: string | null = null;
+  /** Live username — may be updated mid-session via setUsername() (web mode). */
+  private username: string | undefined;
+  /**
+   * Explicit-boundary mode. Once beginPrompt() is called by external code
+   * (http-server `/api/prompt`, cli-main's session.prompt wrapper, …), we stop
+   * treating internal agent_start/agent_end events as trace boundaries. This
+   * keeps ONE user prompt = ONE trace file even when pi-agent internally fires
+   * multiple agent cycles (empty-response retry, auto-compaction, continuation).
+   * Once set to true, stays true — mixing modes mid-session is not supported.
+   */
+  private explicitMode = false;
+
+  constructor(private readonly opts: TraceRecorderOpts) {
+    try {
+      fs.mkdirSync(opts.traceDir, { recursive: true });
+    } catch (err) {
+      console.warn(`[trace-recorder] Failed to create trace dir ${opts.traceDir}:`, err);
+    }
+    this.username = opts.username;
+    this.unsubscribeDiag = onDiagnostic((evt) => this.onDiagnosticEvent(evt));
+  }
+
+  /**
+   * Set (or update) the displayable username. Used by the web/agentbox path
+   * where username isn't known at session-creation time but arrives later in
+   * the prompt body. Applies to all subsequent trace flushes for this session
+   * — filenames use it, and the JSON body records it alongside userId.
+   */
+  setUsername(username: string): void {
+    if (username && username.trim()) this.username = username;
+  }
+
+  /** Subscribe to a brain's events. Returns unsubscribe fn. */
+  attach(brain: BrainSession): () => void {
+    return brain.subscribe((event) => this.onBrainEvent(event));
+  }
+
+  /**
+   * Explicitly record the user's raw prompt text.
+   *
+   * This is needed for the web/agentbox path because the pi-agent framework
+   * does not reliably emit a `message_end { role: "user" }` event before
+   * `agent_start` fires in that mode (events are raised inside brain.prompt()
+   * after the fact). Callers that have direct access to the user input
+   * (e.g. the HTTP /api/prompt handler) should call this before invoking
+   * `brain.prompt()` so the upcoming agent_start picks it up.
+   *
+   * If a trace is already in-flight (rare edge case), the current trace's
+   * userMessage is also updated so it's not lost.
+   */
+  setUserMessage(text: string): void {
+    this.lastUserMessageBuffered = text;
+    if (this.active && !this.userMessage) {
+      this.userMessage = text;
+    }
+  }
+
+  /**
+   * Start collecting a new trace. When called externally (http-server,
+   * cli-main's session.prompt wrapper), switches the recorder into
+   * explicit-boundary mode: subsequent internal agent_start/agent_end events
+   * will NOT split the trace into multiple files.
+   */
+  async beginPrompt(userMessage: string): Promise<void> {
+    this.explicitMode = true;
+    await this.startTrace(userMessage);
+  }
+
+  /** Shared trace-reset logic used by both explicit beginPrompt() and the
+   *  internal auto-detect path (agent_start in auto mode). */
+  private async startTrace(userMessage: string): Promise<void> {
+    if (this.active) await this.flush();
+    this.active = true;
+    this.promptIdx += 1;
+    this.userMessage = userMessage;
+    this.isInjectedPrompt = isInjectedPromptText(userMessage);
+    this.startedAtMs = Date.now();
+    this.steps = [];
+    this.skillsUsed = [];
+    this.pendingSkillMeta = [];
+    this.pendingTools.clear();
+    this.outcome = "completed";
+    this.prevStats = safeCall(this.opts.getSessionStats);
+    this.currentTraceKey = this.computeTraceKey();
+    // Two-phase persistence: stub the row NOW, so even if the prompt later
+    // hangs (e.g. propose_hypotheses infinite loop) the injected prompt /
+    // session / DP-status-at-start are preserved in the DB. flush() will
+    // later UPSERT the same trace_key with complete data.
+    await this.persistInFlightStub();
+  }
+
+  /** Finalize the current trace. Usually auto-invoked on agent_end. */
+  async endPrompt(outcome?: "completed" | "error"): Promise<string | null> {
+    if (!this.active) return null;
+    if (outcome) this.outcome = outcome;
+    return await this.flush();
+  }
+
+  /**
+   * One-shot record for a "steer" message — the frontend sends these via
+   * `chat.steer` RPC → `POST /api/sessions/:id/steer` when the agent is
+   * mid-run (HypothesesCard [DP_CONFIRM] / [DP_ADJUST] / [DP_SKIP] /
+   * [DP_REINVESTIGATE] / feedback injections / etc.).
+   *
+   * Why this method exists (why not reuse beginPrompt/flush):
+   *   - A steer has no paired "end" event (it's inserted into the currently
+   *     running agent, not a new agent cycle). begin+flush's two-phase model
+   *     doesn't fit.
+   *   - Calling beginPrompt() mid-run would reset `this.active` and prematurely
+   *     flush the main in-flight trace (cutting it in half).
+   *
+   * So we write a fully-formed standalone row atomically, with its own unique
+   * trace_key (suffixed `-steer-<rand>` to guarantee no collision with main
+   * traces). `outcome='completed'` and `duration_ms=0` because the steer itself
+   * is instantaneous from the user's perspective; what happens afterwards
+   * (resumed agent work) lands in the main trace's final flush.
+   */
+  async recordSteerEvent(text: string): Promise<void> {
+    if (!this.opts.store) return;
+    try {
+      const nowMs = Date.now();
+      const raw = (this.username && this.username.trim())
+        ? this.username
+        : (this.opts.userId && this.opts.userId.trim() ? this.opts.userId : "unknown");
+      const user = raw.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 32);
+      const stamp = formatBeijingFilename(nowMs);
+      const rand = Math.random().toString(36).slice(2, 8);
+      const traceKey = `trace-${stamp}-${user}-steer-${rand}`;
+      const startedAtStr = formatBeijing(nowMs);
+      const model = safeCall(this.opts.getModel);
+      const dpStatus = this.opts.dpStateRef?.status ?? "idle";
+      const injected = isInjectedPromptText(text);
+      const body = {
+        schemaVersion: "1.2",
+        kind: "steer",   // distinguishes from "prompt" traces in the body
+        sessionId: this.opts.sessionId,
+        username: this.username,
+        userId: this.opts.userId,
+        mode: this.opts.mode,
+        brainType: this.opts.brainType,
+        model,
+        userMessage: text,
+        isInjectedPrompt: injected,
+        dpStatusEnd: dpStatus,
+        startedAt: startedAtStr,
+        endedAt: startedAtStr,
+        durationMs: 0,
+        outcome: "completed",
+        skillsUsed: [],
+        stats: {},
+        steps: [],
+      };
+      await this.opts.store.upsert({
+        id: traceKey,
+        sessionId: this.opts.sessionId,
+        promptIdx: 0,        // steer is not a top-level prompt — 0 signals "n/a"
+        userId: this.opts.userId ?? null,
+        username: this.username ?? null,
+        mode: this.opts.mode,
+        brainType: this.opts.brainType ?? null,
+        modelName: model?.id ?? null,
+        userMessage: text,
+        outcome: "completed",
+        startedAt: startedAtStr,
+        endedAt: startedAtStr,
+        durationMs: 0,
+        stepCount: 0,
+        toolCallCount: 0,
+        tokensTotal: null,
+        costUsd: null,
+        schemaVersion: "1.2",
+        isInjectedPrompt: injected,
+        dpStatusEnd: dpStatus,
+        bodyJson: JSON.stringify(body, null, 2),
+      });
+    } catch (err) {
+      console.warn(`[trace-recorder] recordSteerEvent failed:`, err);
+    }
+  }
+
+  /** Release all resources. Writes any in-flight trace first. */
+  async close(): Promise<void> {
+    if (this.active) await this.flush();
+    if (this.unsubscribeDiag) {
+      this.unsubscribeDiag();
+      this.unsubscribeDiag = null;
+    }
+  }
+
+  /**
+   * Derive the trace_key (= filename stem) from username + startedAtMs.
+   * Called once per prompt in startTrace(). Reused later by persistInFlightStub()
+   * and flush() so the stub and final rows hit the same row via UPSERT.
+   *
+   * NOTE: collision-suffix (`-002`, `-003`) is decided at flush() time based on
+   * filesystem existence — at startTrace() we don't yet know about disk state.
+   * In practice collisions only happen when two traces share the same second,
+   * which is rare; flush() will write to a suffixed *file* when it hits one,
+   * while the DB row still uses the un-suffixed trace_key. That is an accepted
+   * minor inconsistency in exchange for being able to write the stub upfront.
+   */
+  private computeTraceKey(): string {
+    const raw = (this.username && this.username.trim())
+      ? this.username
+      : (this.opts.userId && this.opts.userId.trim() ? this.opts.userId : "unknown");
+    const user = raw.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 32);
+    const stamp = formatBeijingFilename(this.startedAtMs);
+    return `trace-${stamp}-${user}`;
+  }
+
+  /**
+   * Write a minimal "in-progress" row to the DB immediately after the prompt
+   * boundary opens. Guarantees that a stuck prompt still leaves evidence:
+   *   - the injected-prompt text + classification
+   *   - session / user / model metadata
+   *   - DP status at the moment the prompt arrived
+   *
+   * Best-effort: any error is warned but does not break the live trace flow.
+   */
+  private async persistInFlightStub(): Promise<void> {
+    if (!this.opts.store || !this.currentTraceKey) return;
+    try {
+      const startedAtStr = formatBeijing(this.startedAtMs);
+      const model = safeCall(this.opts.getModel);
+      const dpStatus = this.opts.dpStateRef?.status ?? "idle";
+      const stubBody = {
+        schemaVersion: "1.2",
+        sessionId: this.opts.sessionId,
+        username: this.username,
+        userId: this.opts.userId,
+        mode: this.opts.mode,
+        brainType: this.opts.brainType,
+        model,
+        userMessage: this.userMessage,
+        isInjectedPrompt: this.isInjectedPrompt,
+        dpStatusEnd: dpStatus,
+        startedAt: startedAtStr,
+        outcome: "in_progress",
+        pending: true,
+        note: "Partial trace — the prompt has not yet finished. A completed row will overwrite this via UPSERT once endPrompt() fires. If this note survives, the agent hung or the process died mid-prompt.",
+      };
+      await this.opts.store.upsert({
+        id: this.currentTraceKey,
+        sessionId: this.opts.sessionId,
+        promptIdx: this.promptIdx,
+        userId: this.opts.userId ?? null,
+        username: this.username ?? null,
+        mode: this.opts.mode,
+        brainType: this.opts.brainType ?? null,
+        modelName: model?.id ?? null,
+        userMessage: this.userMessage,
+        outcome: "in_progress",
+        startedAt: startedAtStr,
+        endedAt: startedAtStr,      // placeholder — flush() overwrites
+        durationMs: 0,              // placeholder — flush() overwrites
+        stepCount: 0,
+        toolCallCount: 0,
+        tokensTotal: null,
+        costUsd: null,
+        schemaVersion: "1.2",
+        isInjectedPrompt: this.isInjectedPrompt,
+        dpStatusEnd: dpStatus,
+        bodyJson: JSON.stringify(stubBody, null, 2),
+      });
+    } catch (err) {
+      console.warn(`[trace-recorder] in-flight stub upsert failed:`, err);
+    }
+  }
+
+  // ── Event handlers ──────────────────────────────────
+
+  private onBrainEvent(event: unknown): void {
+    const ev = event as Record<string, unknown> | null;
+    if (!ev || typeof ev !== "object") return;
+    const type = ev.type as string | undefined;
+    if (!type) return;
+    const now = Date.now();
+
+    // User message: capture for use when next agent_start fires (auto mode only).
+    // In EXPLICIT mode, pi-agent may re-emit the prompt verbatim during retry —
+    // don't let that overwrite the authoritative userMessage from beginPrompt().
+    if (type === "message_end") {
+      const msg = ev.message as Record<string, unknown> | undefined;
+      if (msg?.role === "user" && !this.explicitMode) {
+        this.lastUserMessageBuffered = extractText(msg.content);
+      }
+    }
+
+    // agent_start: in AUTO mode, opens a new trace. In EXPLICIT mode, internal
+    // cycles (empty-response retry / auto-compaction continuation) are merged
+    // into the current trace by external beginPrompt — do nothing here.
+    //
+    // Fire-and-forget the async startTrace/flush from sync event handlers:
+    // brain.subscribe() callbacks don't await, and we don't want to block
+    // event processing on DB writes. Unhandled rejections must be caught.
+    if (type === "agent_start") {
+      if (!this.explicitMode) {
+        this.startTrace(this.lastUserMessageBuffered).catch((err) =>
+          console.warn("[trace-recorder] auto startTrace failed:", err));
+      }
+      return;
+    }
+
+    if (!this.active) return;
+
+    switch (type) {
+      case "agent_end":
+        // In EXPLICIT mode, external endPrompt drives the flush; ignore.
+        if (this.explicitMode) return;
+        this.flush().catch((err) =>
+          console.warn("[trace-recorder] auto flush failed:", err));
+        return;
+
+      case "turn_start":
+      case "turn_end":
+        this.steps.push({ kind: type, ts: formatBeijing(now) });
+        return;
+
+      case "message_end": {
+        const msg = ev.message as Record<string, unknown> | undefined;
+        if (!msg) return;
+        const role = (msg.role as string) ?? "";
+        // Drop role="user" (== top-level userMessage) and role="toolResult"
+        // (== tool_call.output) — pure duplicates.
+        if (role !== "assistant") return;
+        const content = Array.isArray(msg.content) ? (msg.content as Array<Record<string, unknown>>) : [];
+        const text = content
+          .filter((c) => c.type === "text")
+          .map((c) => (c.text as string | undefined) ?? "")
+          .join("");
+        const toolCalls = content
+          .filter((c) => c.type === "toolCall")
+          .map((c) => ({
+            name: c.name as string,
+            args: c.input ?? c.arguments,
+            toolCallId: c.id as string | undefined,
+          }));
+        this.steps.push({
+          kind: "message",
+          role: "assistant",
+          stopReason: msg.stopReason as string | undefined,
+          ts: formatBeijing(now),
+          text,
+          toolCalls: toolCalls.length ? toolCalls : undefined,
+        });
+        if (msg.stopReason === "error") {
+          this.outcome = "error";
+          this.steps.push({
+            kind: "model_error",
+            ts: formatBeijing(now),
+            detail: { errorMessage: msg.errorMessage },
+          });
+        }
+        return;
+      }
+
+      case "tool_execution_start": {
+        const name = (ev.toolName as string) ?? (ev.name as string) ?? "tool";
+        const toolCallId = ev.toolCallId as string | undefined;
+        this.pendingTools.set(pendingKey(name, toolCallId), {
+          name,
+          args: ev.args,
+          startedAtMs: now,
+          toolCallId,
+        });
+        return;
+      }
+
+      case "tool_execution_end": {
+        const name = (ev.toolName as string) ?? (ev.name as string) ?? "tool";
+        const toolCallId = ev.toolCallId as string | undefined;
+        const key = pendingKey(name, toolCallId);
+        const pending = this.pendingTools.get(key);
+        this.pendingTools.delete(key);
+
+        const result = ev.result as Record<string, unknown> | undefined;
+        const output = Array.isArray(result?.content)
+          ? (result!.content as Array<Record<string, unknown>>)
+              .filter((c) => c.type === "text")
+              .map((c) => (c.text as string | undefined) ?? "")
+              .join("")
+          : "";
+        const details = result?.details as Record<string, unknown> | undefined;
+        const isError = Boolean(ev.isError || details?.error || details?.blocked);
+
+        const startMs = pending?.startedAtMs ?? now;
+        const startedAtStr = formatBeijing(startMs);
+        const step: ToolCallStep = {
+          kind: "tool_call",
+          name,
+          toolCallId: pending?.toolCallId ?? toolCallId,
+          args: pending?.args,
+          output,
+          isError,
+          startedAt: startedAtStr,
+          endedAt: formatBeijing(now),
+          durationMs: pending ? now - pending.startedAtMs : 0,
+        };
+        this.enrichWithSkill(step, startedAtStr);
+        this.steps.push(step);
+        return;
+      }
+
+      case "auto_compaction_start":
+      case "auto_compaction_end":
+        this.steps.push({ kind: "auto_compaction", ts: formatBeijing(now), detail: ev });
+        return;
+
+      case "auto_retry_start":
+      case "auto_retry_end":
+        this.steps.push({ kind: "auto_retry", ts: formatBeijing(now), detail: ev });
+        return;
+
+      // message_update / tool_execution_update are high-volume streaming deltas; drop.
+      default:
+        return;
+    }
+  }
+
+  /**
+   * Enrich a freshly-built tool_call step with skill information by detecting:
+   *  - Path A: read/Read/file_read with args.path ending in "/SKILL.md"
+   *  - Path B: local_script with args.skill
+   * Also merges any pending skill_call diagnostic metadata (scope, outcome,
+   * durationMs) that arrived before the corresponding tool_execution_end.
+   */
+  private enrichWithSkill(step: ToolCallStep, ts: string): void {
+    const args = step.args as Record<string, unknown> | undefined;
+    let ref: SkillRef | null = null;
+
+    // Path B: local_script
+    if (args && typeof args === "object") {
+      const skillName = (args.skill ?? args.skillName) as string | undefined;
+      if (skillName) {
+        ref = {
+          skillName,
+          scriptName: ((args.script ?? args.scriptName) as string | undefined) ?? "",
+          via: "local_script",
+        };
+      }
+    }
+
+    // Path A: reading SKILL.md
+    if (!ref && args && typeof args === "object") {
+      const filePath = (args.path ?? args.file_path ?? args.filePath) as string | undefined;
+      const parsed = filePath ? parseSkillPath(filePath) : null;
+      if (parsed) {
+        ref = { skillName: parsed.skillName, scope: parsed.scope, via: "read" };
+      }
+    }
+
+    if (!ref) return;
+
+    // Merge any buffered diagnostic metadata for Path B (carries authoritative scope).
+    if (ref.via === "local_script") {
+      const idx = this.pendingSkillMeta.findIndex(
+        (m) => m.skillName === ref!.skillName && (!ref!.scriptName || m.scriptName === ref!.scriptName),
+      );
+      if (idx >= 0) {
+        const meta = this.pendingSkillMeta[idx];
+        ref.scope = meta.scope;
+        this.pendingSkillMeta.splice(idx, 1);
+      }
+    }
+
+    step.skill = ref;
+    this.skillsUsed.push({
+      skillName: ref.skillName,
+      scope: ref.scope,
+      scriptName: ref.scriptName,
+      via: ref.via,
+      ts,
+    });
+  }
+
+  private onDiagnosticEvent(evt: DiagnosticEvent): void {
+    if (evt.type !== "skill_call") return;
+    if (evt.sessionId && evt.sessionId !== this.opts.sessionId) return;
+
+    // Try to find a tool_call step already recorded (the local_script event arrives
+    // AFTER the brain's tool_execution_end — correct flow). Enrich scope/outcome/duration.
+    for (let i = this.steps.length - 1; i >= 0; i--) {
+      const s = this.steps[i];
+      if (s.kind === "tool_call" && s.skill && s.skill.via === "local_script" && s.skill.skillName === evt.skillName) {
+        if (!s.skill.scope) s.skill.scope = evt.scope;
+        // Also enrich the latest matching aggregate record.
+        for (let j = this.skillsUsed.length - 1; j >= 0; j--) {
+          const u = this.skillsUsed[j];
+          if (u.via === "local_script" && u.skillName === evt.skillName && !u.scope) {
+            u.scope = evt.scope;
+            u.outcome = evt.outcome;
+            u.durationMs = evt.durationMs;
+            break;
+          }
+        }
+        return;
+      }
+    }
+
+    // No matching step yet — the diagnostic fired BEFORE tool_execution_end.
+    // Buffer it so enrichWithSkill() can pick it up when the step is built.
+    this.pendingSkillMeta.push({
+      skillName: evt.skillName,
+      scriptName: evt.scriptName,
+      scope: evt.scope,
+      outcome: evt.outcome,
+      durationMs: evt.durationMs,
+      ts: formatBeijing(Date.now()),
+    });
+  }
+
+  // ── Flush ───────────────────────────────────────────
+
+  private async flush(): Promise<string | null> {
+    if (!this.active) return null;
+    this.active = false;
+    const endedAtMs = Date.now();
+    const currStats = safeCall(this.opts.getSessionStats);
+    const model = safeCall(this.opts.getModel);
+
+    const tokensDelta =
+      this.prevStats && currStats
+        ? {
+            input: currStats.tokens.input - this.prevStats.tokens.input,
+            output: currStats.tokens.output - this.prevStats.tokens.output,
+            cacheRead: currStats.tokens.cacheRead - this.prevStats.tokens.cacheRead,
+            cacheWrite: currStats.tokens.cacheWrite - this.prevStats.tokens.cacheWrite,
+            total: currStats.tokens.total - this.prevStats.tokens.total,
+          }
+        : undefined;
+    const costDelta =
+      this.prevStats && currStats ? currStats.cost - this.prevStats.cost : undefined;
+
+    // Sample DP status at the exact moment the prompt finishes — this is the
+    // authoritative "where did this prompt leave the workflow" signal.
+    const dpStatusEnd: string = this.opts.dpStateRef?.status ?? "idle";
+
+    const trace = {
+      // Body schema bumped 1.1 → 1.2 for the new top-level fields
+      // (isInjectedPrompt, dpStatusEnd). Readers pinned to older JSON can
+      // detect & upgrade via this field.
+      schemaVersion: "1.2",
+      sessionId: this.opts.sessionId,
+      username: this.username,
+      userId: this.opts.userId,
+      mode: this.opts.mode,
+      brainType: this.opts.brainType,
+      model,
+      userMessage: this.userMessage,
+      isInjectedPrompt: this.isInjectedPrompt,
+      dpStatusEnd,
+      startedAt: formatBeijing(this.startedAtMs),
+      endedAt: formatBeijing(endedAtMs),
+      durationMs: endedAtMs - this.startedAtMs,
+      outcome: this.outcome,
+      skillsUsed: this.skillsUsed,
+      stats: { tokensDelta, costDelta },
+      steps: this.steps,
+    };
+
+    // Filename prefers the displayable username ("admin") over the internal
+    // hex userId ("3e3a85bf..."), falls back to "unknown" if neither.
+    const raw = (this.username && this.username.trim())
+      ? this.username
+      : (this.opts.userId && this.opts.userId.trim() ? this.opts.userId : "unknown");
+    const user = raw.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 32);
+    const stamp = formatBeijingFilename(this.startedAtMs); // YYYYMMDD-HHmmssSSS
+    const baseName = `trace-${stamp}-${user}`;
+    // If two traces fall in the exact same millisecond, append -002, -003, ...
+    let fname = `${baseName}.json`;
+    let suffix = 1;
+    while (fs.existsSync(path.join(this.opts.traceDir, fname))) {
+      suffix += 1;
+      fname = `${baseName}-${String(suffix).padStart(3, "0")}.json`;
+    }
+    const fpath = path.join(this.opts.traceDir, fname);
+    const bodyJson = JSON.stringify(trace, null, 2);
+    let written: string | null = null;
+    try {
+      fs.writeFileSync(fpath, bodyJson, "utf-8");
+      written = fpath;
+    } catch (err) {
+      console.warn(`[trace-recorder] write failed: ${fpath}`, err);
+    }
+
+    // Persist to SQLite (same JSON body, plus indexed columns for API queries).
+    // UPSERT overwrites the in-flight stub row written by startTrace(). Best-
+    // effort: DB failures must not break the trace contract on disk.
+    if (this.opts.store) {
+      try {
+        // Re-use the trace_key assigned at startTrace() to hit the same row
+        // written by persistInFlightStub(). If the filesystem collision path
+        // in `fname` ended up with a -NNN suffix (same-second clash), prefer
+        // the already-stamped currentTraceKey — the *DB* row is keyed there.
+        const traceId = this.currentTraceKey ?? fname.replace(/\.json$/, "");
+        const toolCallCount = this.steps.reduce((n, s) => n + (s.kind === "tool_call" ? 1 : 0), 0);
+        await this.opts.store.upsert({
+          id: traceId,
+          sessionId: this.opts.sessionId,
+          promptIdx: this.promptIdx,
+          userId: this.opts.userId ?? null,
+          username: this.username ?? null,
+          mode: this.opts.mode,
+          brainType: this.opts.brainType ?? null,
+          modelName: model?.id ?? null,
+          userMessage: this.userMessage,
+          outcome: this.outcome,
+          startedAt: formatBeijing(this.startedAtMs),
+          endedAt: formatBeijing(endedAtMs),
+          durationMs: endedAtMs - this.startedAtMs,
+          stepCount: this.steps.length,
+          toolCallCount,
+          tokensTotal: tokensDelta?.total ?? null,
+          costUsd: costDelta ?? null,
+          schemaVersion: trace.schemaVersion,
+          bodyJson,
+          isInjectedPrompt: this.isInjectedPrompt,
+          dpStatusEnd,
+        });
+      } catch (err) {
+        console.warn(`[trace-recorder] DB insert failed:`, err);
+      }
+    }
+
+    return written;
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────
+
+const BEIJING_OFFSET_MS = 8 * 60 * 60 * 1000; // UTC+8
+
+function pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}
+function pad3(n: number): string {
+  return n < 10 ? `00${n}` : n < 100 ? `0${n}` : String(n);
+}
+
+/**
+ * Format a Unix ms timestamp as Beijing time (UTC+8).
+ * Output: "YYYY-MM-DD HH:mm:ss.SSS" — no timezone suffix since all values are fixed to +08:00.
+ */
+function formatBeijing(ms: number): string {
+  const d = new Date(ms + BEIJING_OFFSET_MS);
+  return (
+    `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())} ` +
+    `${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())}:${pad2(d.getUTCSeconds())}.${pad3(d.getUTCMilliseconds())}`
+  );
+}
+
+/** Filename-safe variant: YYYYMMDD-HH-mm-ss (no milliseconds; same-second collisions handled by suffix). */
+function formatBeijingFilename(ms: number): string {
+  const d = new Date(ms + BEIJING_OFFSET_MS);
+  return (
+    `${d.getUTCFullYear()}${pad2(d.getUTCMonth() + 1)}${pad2(d.getUTCDate())}-` +
+    `${pad2(d.getUTCHours())}-${pad2(d.getUTCMinutes())}-${pad2(d.getUTCSeconds())}`
+  );
+}
+
+function pendingKey(name: string, toolCallId: string | undefined): string {
+  return toolCallId ? `${name}#${toolCallId}` : name;
+}
+
+/**
+ * Parse a filesystem path pointing at a SKILL.md file into { skillName, scope }.
+ * Handles the siclaw skill layout:
+ *   .../skills/core/<name>/SKILL.md                → scope=core,      name=<name>
+ *   .../skills/extension/<name>/SKILL.md           → scope=extension, name=<name>
+ *   .../skills/global/<name>/SKILL.md              → scope=global,    name=<name>
+ *   .../skills/personal/<name>/SKILL.md            → scope=personal,  name=<name>
+ *   .../skills/user/<userId>/<name>/SKILL.md       → scope=user,      name=<name>
+ * Returns null if the path does not look like a siclaw SKILL.md reference.
+ */
+function parseSkillPath(p: string): { skillName: string; scope: string } | null {
+  if (!p || !/\/SKILL\.md$/i.test(p)) return null;
+  const idx = p.lastIndexOf("/skills/");
+  if (idx < 0) return null;
+  const tail = p.slice(idx + "/skills/".length).replace(/\/SKILL\.md$/i, "");
+  const segs = tail.split("/").filter(Boolean);
+  if (segs.length < 2) return null;
+  // user/<userId>/<name> → 3 segments
+  if (segs[0] === "user" && segs.length >= 3) {
+    return { scope: "user", skillName: segs[segs.length - 1] };
+  }
+  // <scope>/<name> → 2 segments
+  return { scope: segs[0], skillName: segs[segs.length - 1] };
+}
+
+function extractText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return (content as Array<Record<string, unknown>>)
+    .filter((c) => c.type === "text")
+    .map((c) => (c.text as string | undefined) ?? "")
+    .join("");
+}
+
+function safeCall<T>(fn: (() => T | undefined) | undefined): T | undefined {
+  if (!fn) return undefined;
+  try {
+    return fn();
+  } catch {
+    return undefined;
+  }
+}
+
+// ── Env-var gated factory ──────────────────────────────
+
+/**
+ * Create a TraceRecorder unless SICLAW_TRACE_DISABLE=1.
+ * Default trace dir: <cwd>/.siclaw/traces (override with SICLAW_TRACE_DIR).
+ *
+ * Async because the default store factory (`getTraceStore`) performs MySQL
+ * schema init on first use. Callers typically `await` this once at session
+ * setup, so the cost is amortized.
+ */
+export async function maybeCreateTraceRecorder(
+  opts: Omit<TraceRecorderOpts, "traceDir"> & { traceDir?: string },
+): Promise<TraceRecorder | null> {
+  if (process.env.SICLAW_TRACE_DISABLE === "1") return null;
+  const traceDir =
+    opts.traceDir ??
+    process.env.SICLAW_TRACE_DIR ??
+    path.join(process.cwd(), ".siclaw", "traces");
+  // Auto-attach the process-level trace store unless caller already supplied one.
+  const store = opts.store !== undefined ? opts.store : await getTraceStore();
+  return new TraceRecorder({ ...opts, traceDir, store });
+}
diff --git a/src/core/trace-store-composite.ts b/src/core/trace-store-composite.ts
new file mode 100644
index 00000000..fab4bc68
--- /dev/null
+++ b/src/core/trace-store-composite.ts
@@ -0,0 +1,102 @@
+/**
+ * CompositeTraceStore — fan-out writes to multiple TraceStore backends,
+ * preferring the first one (primary) for reads.
+ *
+ * Used when the operator enables both SQLite and MySQL in config. Each write
+ * is attempted against every backend; the composite succeeds as long as at
+ * least one backend succeeded. Failed backends log a warning but don't block
+ * the call — this preserves data on whichever sink survives (e.g. MySQL pod
+ * restarts → local SQLite still captures the rows; SQLite fs goes read-only
+ * → MySQL still takes the writes).
+ *
+ * Read strategy (list / getById): always hit stores[0] (the primary). If it
+ * misses getById, fall through to the remaining stores so a locally-only
+ * stored trace is still reachable via API after a MySQL outage.
+ */
+
+import type {
+  TraceStore,
+  TraceRow,
+  TraceListOpts,
+  TraceListResult,
+  TraceRecord,
+} from "./trace-store-types.js";
+
+export interface NamedStore {
+  name: string;
+  store: TraceStore;
+}
+
+export class CompositeTraceStore implements TraceStore {
+  constructor(private readonly stores: readonly NamedStore[]) {
+    if (stores.length === 0) {
+      throw new Error("CompositeTraceStore requires at least one backing store");
+    }
+  }
+
+  async insert(row: TraceRow & { bodyJson: string }): Promise<void> {
+    await this.fanOut("insert", row.id, (s) => s.insert(row));
+  }
+
+  async upsert(row: TraceRow & { bodyJson: string }): Promise<void> {
+    await this.fanOut("upsert", row.id, (s) => s.upsert(row));
+  }
+
+  /** Primary-only read. Users expect a single consistent page, not a merge. */
+  async list(opts: TraceListOpts): Promise<TraceListResult> {
+    return await this.stores[0].store.list(opts);
+  }
+
+  /** Primary first, then fall through (recovers rows stranded on a secondary). */
+  async getById(id: string): Promise<TraceRecord | null> {
+    for (const { store } of this.stores) {
+      try {
+        const rec = await store.getById(id);
+        if (rec) return rec;
+      } catch (err) {
+        console.warn(`[trace-store-composite] getById(${id}) failed on a backend:`, err);
+      }
+    }
+    return null;
+  }
+
+  async close(): Promise<void> {
+    // Close every backend even if one throws — don't leak connections.
+    await Promise.allSettled(this.stores.map(({ store }) => store.close()));
+  }
+
+  /**
+   * Execute `op` against every backend in parallel. If at least one succeeds,
+   * this returns normally after logging warnings for the failed ones. If ALL
+   * fail, throws an aggregated error — callers (the recorder) can decide
+   * whether to surface or swallow.
+   */
+  private async fanOut(
+    opName: string,
+    traceKey: string,
+    op: (store: TraceStore) => Promise<void>,
+  ): Promise<void> {
+    const results = await Promise.all(
+      this.stores.map(async ({ name, store }) => {
+        try {
+          await op(store);
+          return { name, ok: true as const };
+        } catch (err) {
+          return { name, ok: false as const, err };
+        }
+      }),
+    );
+    const failed = results.filter((r): r is { name: string; ok: false; err: unknown } => !r.ok);
+    if (failed.length === results.length) {
+      const msg = failed.map((f) => `${f.name}: ${String(f.err)}`).join(" | ");
+      throw new Error(`[trace-store-composite] all ${results.length} backends failed ${opName} for ${traceKey}: ${msg}`);
+    }
+    for (const f of failed) {
+      console.warn(
+        `[trace-store-composite] ${opName} failed on backend "${f.name}" for trace_key=${traceKey}; ` +
+        `other backends succeeded. Error:`,
+        f.err,
+      );
+    }
+  }
+}
diff --git a/src/core/trace-store-mysql.ts b/src/core/trace-store-mysql.ts
new file mode 100644
index 00000000..78aa1ce8
--- /dev/null
+++ b/src/core/trace-store-mysql.ts
@@ -0,0 +1,318 @@
+/**
+ * MysqlTraceStore — `TraceStore` backed by a MySQL server (mysql2/promise).
+ *
+ * Intended for production / K8s use — a trace-mysql StatefulSet with a PVC
+ * survives pod restarts (solves the SQLite "pod ephemeral → data lost" gap).
+ *
+ * Schema is kept functionally identical to the SQLite variant (same column
+ * names / semantics). Differences dictated by MySQL dialect:
+ *   - BIGINT AUTO_INCREMENT PRIMARY KEY   (vs INTEGER PRIMARY KEY AUTOINCREMENT)
+ *   - LONGTEXT for body_json / user_message (up to 4 GB)
+ *   - VARCHAR(32) for Beijing-time strings (zero-padded, known length)
+ *   - schema_migrations table (MySQL has no PRAGMA user_version)
+ *   - INSERT ... ON DUPLICATE KEY UPDATE ...  (vs ON CONFLICT DO UPDATE)
+ */
+
+import mysql from "mysql2/promise";
+import type {
+  TraceStore,
+  TraceRow,
+  TraceListOpts,
+  TraceListResult,
+  TraceRecord,
+} from "./trace-store-types.js";
+
+const SCHEMA_VERSION = 4;
+
+const DDL_V4_TABLE = `
+  CREATE TABLE IF NOT EXISTS agent_traces (
+    id                  BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    trace_key           VARCHAR(255) NOT NULL,
+    session_id          VARCHAR(255) NOT NULL,
+    prompt_idx          INT NOT NULL,
+    user_id             VARCHAR(255),
+    username            VARCHAR(255),
+    mode                VARCHAR(64) NOT NULL,
+    brain_type          VARCHAR(64),
+    model_name          VARCHAR(255),
+    user_message        LONGTEXT,
+    outcome             VARCHAR(32) NOT NULL,
+    started_at          VARCHAR(32) NOT NULL,
+    ended_at            VARCHAR(32) NOT NULL,
+    duration_ms         BIGINT NOT NULL,
+    step_count          INT NOT NULL DEFAULT 0,
+    tool_call_count     INT NOT NULL DEFAULT 0,
+    tokens_total        BIGINT,
+    cost_usd            DOUBLE,
+    schema_version      VARCHAR(16) NOT NULL,
+    body_json           LONGTEXT NOT NULL,
+    body_bytes          INT NOT NULL,
+    created_at          VARCHAR(32) NOT NULL,
+    is_injected_prompt  TINYINT NOT NULL DEFAULT 0,
+    dp_status_end       VARCHAR(64) NOT NULL DEFAULT 'idle',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_trace_key (trace_key),
+    KEY idx_traces_user_time (user_id, started_at),
+    KEY idx_traces_time      (started_at),
+    KEY idx_traces_session   (session_id, prompt_idx)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+`;
+
+const DDL_SCHEMA_MIGRATIONS = `
+  CREATE TABLE IF NOT EXISTS agent_traces_meta (
+    meta_key   VARCHAR(64) NOT NULL PRIMARY KEY,
+    meta_value VARCHAR(255) NOT NULL
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+`;
+
+const INSERT_COLS = `
+  trace_key, session_id, prompt_idx, user_id, username, mode, brain_type, model_name,
+  user_message, outcome, started_at, ended_at, duration_ms,
+  step_count, tool_call_count, tokens_total, cost_usd,
+  schema_version, body_json, body_bytes,
+  is_injected_prompt, dp_status_end, created_at
+`;
+
+const INSERT_PLACEHOLDERS = `?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?`;
+
+const UPDATE_ON_DUP = `
+  session_id         = VALUES(session_id),
+  prompt_idx         = VALUES(prompt_idx),
+  user_id            = VALUES(user_id),
+  username           = VALUES(username),
+  mode               = VALUES(mode),
+  brain_type         = VALUES(brain_type),
+  model_name         = VALUES(model_name),
+  user_message       = VALUES(user_message),
+  outcome            = VALUES(outcome),
+  started_at         = VALUES(started_at),
+  ended_at           = VALUES(ended_at),
+  duration_ms        = VALUES(duration_ms),
+  step_count         = VALUES(step_count),
+  tool_call_count    = VALUES(tool_call_count),
+  tokens_total       = VALUES(tokens_total),
+  cost_usd           = VALUES(cost_usd),
+  schema_version     = VALUES(schema_version),
+  body_json          = VALUES(body_json),
+  body_bytes         = VALUES(body_bytes),
+  is_injected_prompt = VALUES(is_injected_prompt),
+  dp_status_end      = VALUES(dp_status_end)
+`;
+
+// ── Implementation ──────────────────────────────────────────────────────────
+
+export class MysqlTraceStore implements TraceStore {
+  private pool: mysql.Pool;
+  private schemaReady: Promise<void> | null = null;
+
+  constructor(url: string, poolOptions?: Partial<mysql.PoolOptions>) {
+    this.pool = mysql.createPool({
+      uri: url,
+      waitForConnections: true,
+      connectionLimit: 10,
+      enableKeepAlive: true,
+      keepAliveInitialDelay: 30_000,
+      timezone: "+00:00", // we never store TIMESTAMP values — all time columns
+                          // are pre-formatted VARCHAR in Beijing time
+      ...poolOptions,
+    });
+  }
+
+  /** First call runs DDL + migrations. Subsequent calls are instant. */
+  async ensureSchema(): Promise<void> {
+    if (!this.schemaReady) this.schemaReady = this.runSchemaInit();
+    return this.schemaReady;
+  }
+
+  private async runSchemaInit(): Promise<void> {
+    const conn = await this.pool.getConnection();
+    try {
+      await conn.query(DDL_SCHEMA_MIGRATIONS);
+      await conn.query(DDL_V4_TABLE);
+      // Record the version. Not used for branching yet — CREATE TABLE IF NOT
+      // EXISTS already handles idempotency — but pins the expected version for
+      // future additive migrations (v4 → v5).
+      await conn.query(
+        `INSERT INTO agent_traces_meta (meta_key, meta_value) VALUES ('schema_version', ?)
+         ON DUPLICATE KEY UPDATE meta_value = VALUES(meta_value)`,
+        [String(SCHEMA_VERSION)],
+      );
+    } finally {
+      conn.release();
+    }
+  }
+
+  async insert(row: TraceRow & { bodyJson: string }): Promise<void> {
+    await this.ensureSchema();
+    await this.pool.execute(
+      `INSERT INTO agent_traces (${INSERT_COLS}) VALUES (${INSERT_PLACEHOLDERS})`,
+      this.rowToParams(row),
+    );
+  }
+
+  async upsert(row: TraceRow & { bodyJson: string }): Promise<void> {
+    await this.ensureSchema();
+    await this.pool.execute(
+      `INSERT INTO agent_traces (${INSERT_COLS}) VALUES (${INSERT_PLACEHOLDERS})
+       ON DUPLICATE KEY UPDATE ${UPDATE_ON_DUP}`,
+      this.rowToParams(row),
+    );
+  }
+
+  async list(opts: TraceListOpts): Promise<TraceListResult> {
+    await this.ensureSchema();
+    const limit = Math.max(1, Math.min(opts.limit ?? 50, 500));
+    const where: string[] = [];
+    const params: Array<string | number> = [];
+
+    if (opts.userId) {
+      where.push("user_id = ?");
+      params.push(opts.userId);
+    }
+    if (opts.username) {
+      where.push("username = ?");
+      params.push(opts.username);
+    }
+    if (typeof opts.from === "string" && opts.from) {
+      where.push("started_at >= ?");
+      params.push(opts.from);
+    }
+    if (typeof opts.to === "string" && opts.to) {
+      where.push("started_at <= ?");
+      params.push(opts.to);
+    }
+    if (typeof opts.minDurationMs === "number") {
+      where.push("duration_ms >= ?");
+      params.push(opts.minDurationMs);
+    }
+    if (opts.outcome) {
+      where.push("outcome = ?");
+      params.push(opts.outcome);
+    }
+    if (typeof opts.cursorStartedAt === "string" && opts.cursorStartedAt && opts.cursorId) {
+      where.push("(started_at < ? OR (started_at = ? AND trace_key < ?))");
+      params.push(opts.cursorStartedAt, opts.cursorStartedAt, opts.cursorId);
+    }
+
+    const whereSql = where.length ? `WHERE ${where.join(" AND ")}` : "";
+    // LIMIT is inlined (not parameterized) because mysql2's prepared-statement
+    // protocol does not accept a numeric parameter for LIMIT — it throws
+    // ER_WRONG_ARGUMENTS ("Incorrect arguments to mysqld_stmt_execute").
+    // Safe to inline: `limit` is clamped to integer [1, 500] above, no
+    // injection surface.
+    const sql = `
+      SELECT trace_key AS id, session_id, prompt_idx, user_id, username, mode, brain_type, model_name,
+             user_message, outcome, started_at, ended_at, duration_ms,
+             step_count, tool_call_count, tokens_total, cost_usd, schema_version, created_at,
+             is_injected_prompt, dp_status_end
+        FROM agent_traces
+        ${whereSql}
+       ORDER BY started_at DESC, trace_key DESC
+       LIMIT ${limit}
+    `;
+    const [rows] = await this.pool.execute(sql, params);
+    const items = (rows as Array<Record<string, unknown>>).map(rowToTraceRow);
+    const nextCursor = items.length === limit
+      ? { startedAt: items[items.length - 1].startedAt, id: items[items.length - 1].id }
+      : null;
+    return { items, nextCursor };
+  }
+
+  async getById(id: string): Promise<TraceRecord | null> {
+    await this.ensureSchema();
+    const [rows] = await this.pool.execute(
+      `SELECT trace_key AS id, session_id, prompt_idx, user_id, username, mode, brain_type, model_name,
+              user_message, outcome, started_at, ended_at, duration_ms,
+              step_count, tool_call_count, tokens_total, cost_usd, schema_version,
+              created_at, is_injected_prompt, dp_status_end, body_json
+         FROM agent_traces WHERE trace_key = ? LIMIT 1`,
+      [id],
+    );
+    const arr = rows as Array<Record<string, unknown>>;
+    if (arr.length === 0) return null;
+    const r = arr[0];
+    return { ...rowToTraceRow(r), bodyJson: r.body_json as string };
+  }
+
+  async close(): Promise<void> {
+    try { await this.pool.end(); } catch { /* best-effort */ }
+  }
+
+  private rowToParams(row: TraceRow & { bodyJson: string }): Array<string | number | null> {
+    // Order must match INSERT_COLS exactly.
+    return [
+      row.id,
+      row.sessionId,
+      row.promptIdx,
+      row.userId,
+      row.username,
+      row.mode,
+      row.brainType,
+      row.modelName,
+      row.userMessage,
+      row.outcome,
+      row.startedAt,
+      row.endedAt,
+      row.durationMs,
+      row.stepCount,
+      row.toolCallCount,
+      row.tokensTotal,
+      row.costUsd,
+      row.schemaVersion,
+      row.bodyJson,
+      Buffer.byteLength(row.bodyJson, "utf8"),
+      row.isInjectedPrompt ? 1 : 0,
+      row.dpStatusEnd,
+      // created_at — MySQL has no cheap Beijing-time default; fill from
+      // application clock. Matches the strftime default used by SQLite.
+      formatBeijingNow(),
+    ];
+  }
+}
+
+// ── Shared helpers ──────────────────────────────────────────────────────────
+
+function rowToTraceRow(r: Record<string, unknown>): TraceRow {
+  const durationMs = Number(r.duration_ms);
+  return {
+    id: r.id as string,
+    sessionId: r.session_id as string,
+    promptIdx: Number(r.prompt_idx),
+    userId: (r.user_id as string | null) ?? null,
+    username: (r.username as string | null) ?? null,
+    mode: r.mode as string,
+    brainType: (r.brain_type as string | null) ?? null,
+    modelName: (r.model_name as string | null) ?? null,
+    userMessage: (r.user_message as string | null) ?? null,
+    outcome: r.outcome as string,
+    startedAt: r.started_at as string,
+    endedAt: r.ended_at as string,
+    durationMs,
+    duration: formatDuration(durationMs),
+    stepCount: Number(r.step_count),
+    toolCallCount: Number(r.tool_call_count),
+    tokensTotal: r.tokens_total != null ? Number(r.tokens_total) : null,
+    costUsd: r.cost_usd != null ? Number(r.cost_usd) : null,
+    schemaVersion: r.schema_version as string,
+    createdAt: r.created_at as string,
+    isInjectedPrompt: Number(r.is_injected_prompt) === 1,
+    dpStatusEnd: (r.dp_status_end as string | null) ?? "idle",
+  };
+}
+
+function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return "00:00:00.000";
+  const hh = Math.floor(ms / 3600_000);
+  const mm = Math.floor((ms / 60_000) % 60);
+  const ss = Math.floor((ms / 1000) % 60);
+  const sss = Math.floor(ms % 1000);
+  return `${String(hh).padStart(2, "0")}:${String(mm).padStart(2, "0")}:${String(ss).padStart(2, "0")}.${String(sss).padStart(3, "0")}`;
+}
+
+function formatBeijingNow(): string {
+  const d = new Date(Date.now() + 8 * 3600_000);
+  const p2 = (n: number) => (n < 10 ? `0${n}` : String(n));
+  const p3 = (n: number) => (n < 10 ? `00${n}` : n < 100 ? `0${n}` : String(n));
+  return `${d.getUTCFullYear()}-${p2(d.getUTCMonth() + 1)}-${p2(d.getUTCDate())} ` +
+         `${p2(d.getUTCHours())}:${p2(d.getUTCMinutes())}:${p2(d.getUTCSeconds())}.${p3(d.getUTCMilliseconds())}`;
+}
diff --git a/src/core/trace-store-sqlite.ts b/src/core/trace-store-sqlite.ts
new file mode 100644
index 00000000..e86dee0d
--- /dev/null
+++ b/src/core/trace-store-sqlite.ts
@@ -0,0 +1,423 @@
+/**
+ * SqliteTraceStore — default `TraceStore` implementation backed by a local
+ * node:sqlite file (default: <cwd>/.siclaw/traces.sqlite).
+ *
+ * Interface methods are async even though node:sqlite is synchronous — this
+ * keeps the contract uniform across sqlite / mysql / composite implementations
+ * so TraceRecorder can await uniformly.
+ */
+
+import type { DatabaseSync, StatementSync } from "node:sqlite";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import type {
+  TraceStore,
+  TraceRow,
+  TraceListOpts,
+  TraceListResult,
+  TraceRecord,
+} from "./trace-store-types.js";
+
+// ── Lazy loader for node:sqlite (stable only in Node ≥22.13) ────────────────
+
+type SqliteCtor = new (path: string) => DatabaseSync;
+let _sqliteLoad: { ctor: SqliteCtor } | { error: string } | null = null;
+
+export function loadSqlite(): SqliteCtor | null {
+  if (!_sqliteLoad) {
+    try {
+      const req = createRequire(import.meta.url);
+      const mod = req("node:sqlite") as { DatabaseSync: SqliteCtor };
+      _sqliteLoad = { ctor: mod.DatabaseSync };
+    } catch (err) {
+      const code = (err as { code?: string })?.code ?? "";
+      _sqliteLoad = { error: code || String(err) };
+      console.warn(
+        `[trace-store-sqlite] node:sqlite unavailable (${code || "load failed"}). ` +
+        `Fix: upgrade Node to ≥22.13 (or run with NODE_OPTIONS=--experimental-sqlite on 22.12).`,
+      );
+    }
+  }
+  return "ctor" in _sqliteLoad ? _sqliteLoad.ctor : null;
+}
+
+// ── Implementation ──────────────────────────────────────────────────────────
+
+export class SqliteTraceStore implements TraceStore {
+  private db: DatabaseSync;
+  private insertStmt: StatementSync;
+  private upsertStmt: StatementSync;
+  private getBodyStmt: StatementSync;
+
+  constructor(dbPath: string) {
+    const DbCtor = loadSqlite();
+    if (!DbCtor) throw new Error("node:sqlite not available");
+    fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+    this.db = new DbCtor(dbPath);
+    this.db.exec("PRAGMA journal_mode=WAL");
+    this.db.exec("PRAGMA synchronous=NORMAL");
+
+    // Schema management — v1 TEXT PK; v2 INTEGER PK + UNIQUE trace_key;
+    // v3 TEXT Beijing timestamps; v4 adds is_injected_prompt + dp_status_end.
+    ensureSchema(this.db);
+
+    // INSERT — hard fails on UNIQUE(trace_key) collision.
+    this.insertStmt = this.db.prepare(`
+      INSERT INTO agent_traces (
+        trace_key, session_id, prompt_idx, user_id, username, mode, brain_type, model_name,
+        user_message, outcome, started_at, ended_at, duration_ms,
+        step_count, tool_call_count, tokens_total, cost_usd,
+        schema_version, body_json, body_bytes,
+        is_injected_prompt, dp_status_end
+      ) VALUES (
+        ?, ?, ?, ?, ?, ?, ?, ?,
+        ?, ?, ?, ?, ?,
+        ?, ?, ?, ?,
+        ?, ?, ?,
+        ?, ?
+      )
+    `);
+
+    // UPSERT — two-phase persistence: stub at beginPrompt → full row at flush.
+    // created_at excluded from UPDATE so it reflects FIRST-seen time.
+    this.upsertStmt = this.db.prepare(`
+      INSERT INTO agent_traces (
+        trace_key, session_id, prompt_idx, user_id, username, mode, brain_type, model_name,
+        user_message, outcome, started_at, ended_at, duration_ms,
+        step_count, tool_call_count, tokens_total, cost_usd,
+        schema_version, body_json, body_bytes,
+        is_injected_prompt, dp_status_end
+      ) VALUES (
+        ?, ?, ?, ?, ?, ?, ?, ?,
+        ?, ?, ?, ?, ?,
+        ?, ?, ?, ?,
+        ?, ?, ?,
+        ?, ?
+      )
+      ON CONFLICT(trace_key) DO UPDATE SET
+        session_id         = excluded.session_id,
+        prompt_idx         = excluded.prompt_idx,
+        user_id            = excluded.user_id,
+        username           = excluded.username,
+        mode               = excluded.mode,
+        brain_type         = excluded.brain_type,
+        model_name         = excluded.model_name,
+        user_message       = excluded.user_message,
+        outcome            = excluded.outcome,
+        started_at         = excluded.started_at,
+        ended_at           = excluded.ended_at,
+        duration_ms        = excluded.duration_ms,
+        step_count         = excluded.step_count,
+        tool_call_count    = excluded.tool_call_count,
+        tokens_total       = excluded.tokens_total,
+        cost_usd           = excluded.cost_usd,
+        schema_version     = excluded.schema_version,
+        body_json          = excluded.body_json,
+        body_bytes         = excluded.body_bytes,
+        is_injected_prompt = excluded.is_injected_prompt,
+        dp_status_end      = excluded.dp_status_end
+    `);
+
+    this.getBodyStmt = this.db.prepare(
+      `SELECT trace_key AS id, session_id, prompt_idx, user_id, username, mode, brain_type, model_name,
+              user_message, outcome, started_at, ended_at, duration_ms,
+              step_count, tool_call_count, tokens_total, cost_usd, schema_version,
+              created_at, is_injected_prompt, dp_status_end, body_json
+         FROM agent_traces WHERE trace_key = ?`,
+    );
+  }
+
+  async insert(row: TraceRow & { bodyJson: string }): Promise<void> {
+    this.insertStmt.run(...rowToParams(row));
+  }
+
+  async upsert(row: TraceRow & { bodyJson: string }): Promise<void> {
+    this.upsertStmt.run(...rowToParams(row));
+  }
+
+  async list(opts: TraceListOpts): Promise<TraceListResult> {
+    const limit = Math.max(1, Math.min(opts.limit ?? 50, 500));
+    const where: string[] = [];
+    const params: Array<string | number | null> = [];
+
+    if (opts.userId) {
+      where.push("user_id = ?");
+      params.push(opts.userId);
+    }
+    if (opts.username) {
+      where.push("username = ?");
+      params.push(opts.username);
+    }
+    if (typeof opts.from === "string" && opts.from) {
+      where.push("started_at >= ?");
+      params.push(opts.from);
+    }
+    if (typeof opts.to === "string" && opts.to) {
+      where.push("started_at <= ?");
+      params.push(opts.to);
+    }
+    if (typeof opts.minDurationMs === "number") {
+      where.push("duration_ms >= ?");
+      params.push(opts.minDurationMs);
+    }
+    if (opts.outcome) {
+      where.push("outcome = ?");
+      params.push(opts.outcome);
+    }
+    // Keyset cursor: strictly older than (cursorStartedAt, cursorId). Lex sort
+    // is safe because YYYY-MM-DD HH:mm:ss.SSS is zero-padded and monotonic.
+    if (typeof opts.cursorStartedAt === "string" && opts.cursorStartedAt && opts.cursorId) {
+      where.push("(started_at < ? OR (started_at = ? AND trace_key < ?))");
+      params.push(opts.cursorStartedAt, opts.cursorStartedAt, opts.cursorId);
+    }
+
+    const whereSql = where.length ? `WHERE ${where.join(" AND ")}` : "";
+    const sql = `
+      SELECT trace_key AS id, session_id, prompt_idx, user_id, username, mode, brain_type, model_name,
+             user_message, outcome, started_at, ended_at, duration_ms,
+             step_count, tool_call_count, tokens_total, cost_usd, schema_version, created_at,
+             is_injected_prompt, dp_status_end
+        FROM agent_traces
+        ${whereSql}
+       ORDER BY started_at DESC, trace_key DESC
+       LIMIT ?
+    `;
+    const rows = this.db.prepare(sql).all(...params, limit) as Array<Record<string, unknown>>;
+    const items = rows.map(rowToTraceRow);
+    const nextCursor = items.length === limit
+      ? { startedAt: items[items.length - 1].startedAt, id: items[items.length - 1].id }
+      : null;
+    return { items, nextCursor };
+  }
+
+  async getById(id: string): Promise<TraceRecord | null> {
+    const row = this.getBodyStmt.get(id) as Record<string, unknown> | undefined;
+    if (!row) return null;
+    return { ...rowToTraceRow(row), bodyJson: row.body_json as string };
+  }
+
+  async close(): Promise<void> {
+    try { this.db.close(); } catch { /* best-effort */ }
+  }
+}
+
+// ── Shared helpers ──────────────────────────────────────────────────────────
+
+function rowToParams(row: TraceRow & { bodyJson: string }): Array<string | number | null> {
+  return [
+    row.id,
+    row.sessionId,
+    row.promptIdx,
+    row.userId,
+    row.username,
+    row.mode,
+    row.brainType,
+    row.modelName,
+    row.userMessage,
+    row.outcome,
+    row.startedAt,
+    row.endedAt,
+    row.durationMs,
+    row.stepCount,
+    row.toolCallCount,
+    row.tokensTotal,
+    row.costUsd,
+    row.schemaVersion,
+    row.bodyJson,
+    Buffer.byteLength(row.bodyJson, "utf8"),
+    row.isInjectedPrompt ? 1 : 0,
+    row.dpStatusEnd,
+  ];
+}
+
+function rowToTraceRow(r: Record<string, unknown>): TraceRow {
+  const durationMs = r.duration_ms as number;
+  return {
+    id: r.id as string,
+    sessionId: r.session_id as string,
+    promptIdx: r.prompt_idx as number,
+    userId: (r.user_id as string | null) ?? null,
+    username: (r.username as string | null) ?? null,
+    mode: r.mode as string,
+    brainType: (r.brain_type as string | null) ?? null,
+    modelName: (r.model_name as string | null) ?? null,
+    userMessage: (r.user_message as string | null) ?? null,
+    outcome: r.outcome as string,
+    startedAt: r.started_at as string,
+    endedAt: r.ended_at as string,
+    durationMs,
+    duration: formatDuration(durationMs),
+    stepCount: r.step_count as number,
+    toolCallCount: r.tool_call_count as number,
+    tokensTotal: (r.tokens_total as number | null) ?? null,
+    costUsd: (r.cost_usd as number | null) ?? null,
+    schemaVersion: r.schema_version as string,
+    createdAt: r.created_at as string,
+    isInjectedPrompt: Boolean(r.is_injected_prompt),
+    dpStatusEnd: (r.dp_status_end as string | null) ?? "idle",
+  };
+}
+
+/** HH:mm:ss.SSS zero-padded. Wraps past 24h. */
+function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return "00:00:00.000";
+  const hh = Math.floor(ms / 3600_000);
+  const mm = Math.floor((ms / 60_000) % 60);
+  const ss = Math.floor((ms / 1000) % 60);
+  const sss = Math.floor(ms % 1000);
+  return `${String(hh).padStart(2, "0")}:${String(mm).padStart(2, "0")}:${String(ss).padStart(2, "0")}.${String(sss).padStart(3, "0")}`;
+}
+
+// ── Schema management + migration ───────────────────────────────────────────
+
+const SCHEMA_VERSION = 4;
+
+const DDL_V4_TABLE = `
+  CREATE TABLE IF NOT EXISTS agent_traces (
+    id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+    trace_key           TEXT NOT NULL UNIQUE,
+    session_id          TEXT NOT NULL,
+    prompt_idx          INTEGER NOT NULL,
+    user_id             TEXT,
+    username            TEXT,
+    mode                TEXT NOT NULL,
+    brain_type          TEXT,
+    model_name          TEXT,
+    user_message        TEXT,
+    outcome             TEXT NOT NULL,
+    started_at          TEXT NOT NULL,
+    ended_at            TEXT NOT NULL,
+    duration_ms         INTEGER NOT NULL,
+    step_count          INTEGER NOT NULL DEFAULT 0,
+    tool_call_count     INTEGER NOT NULL DEFAULT 0,
+    tokens_total        INTEGER,
+    cost_usd            REAL,
+    schema_version      TEXT NOT NULL,
+    body_json           TEXT NOT NULL,
+    body_bytes          INTEGER NOT NULL,
+    created_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now', '+8 hours')),
+    is_injected_prompt  INTEGER NOT NULL DEFAULT 0,
+    dp_status_end       TEXT NOT NULL DEFAULT 'idle'
+  );
+`;
+
+const DDL_V4_INDEXES = `
+  CREATE INDEX IF NOT EXISTS idx_traces_user_time ON agent_traces(user_id, started_at DESC);
+  CREATE INDEX IF NOT EXISTS idx_traces_time      ON agent_traces(started_at DESC);
+  CREATE INDEX IF NOT EXISTS idx_traces_session   ON agent_traces(session_id, prompt_idx);
+`;
+
+/**
+ * Create or migrate the schema to v4.
+ *   fresh DB                              → create v4 directly
+ *   v1 / v2 legacy (integer ms columns)   → full rebuild via rebuildFromLegacy
+ *   v3 (no new columns)                   → additive ALTER TABLE ADD COLUMN
+ *   v4                                    → no-op (idempotent index reassert)
+ */
+function ensureSchema(db: DatabaseSync): void {
+  const currentVersion =
+    (db.prepare("PRAGMA user_version").get() as { user_version: number } | undefined)?.user_version ?? 0;
+  if (currentVersion >= SCHEMA_VERSION) {
+    db.exec(DDL_V4_INDEXES);
+    return;
+  }
+
+  const tableExists = db
+    .prepare(`SELECT 1 AS one FROM sqlite_master WHERE type='table' AND name='agent_traces'`)
+    .get() !== undefined;
+
+  if (!tableExists) {
+    db.exec(DDL_V4_TABLE);
+    db.exec(DDL_V4_INDEXES);
+    db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+    return;
+  }
+
+  const cols = db.prepare(`PRAGMA table_info(agent_traces)`).all() as Array<{ name: string }>;
+  const hasTraceKey = cols.some((c) => c.name === "trace_key");
+  const hasStartedAt = cols.some((c) => c.name === "started_at");
+  const hasStartedAtMs = cols.some((c) => c.name === "started_at_ms");
+  const hasIsInjected = cols.some((c) => c.name === "is_injected_prompt");
+  const hasDpStatusEnd = cols.some((c) => c.name === "dp_status_end");
+
+  if (!hasTraceKey && hasStartedAtMs) {
+    console.log("[trace-store-sqlite] Migrating agent_traces v1 → v4...");
+    rebuildFromLegacy(db, "v1");
+    return;
+  }
+
+  if (hasTraceKey && hasStartedAtMs && !hasStartedAt) {
+    console.log("[trace-store-sqlite] Migrating agent_traces v2 → v4...");
+    rebuildFromLegacy(db, "v2");
+    return;
+  }
+
+  if (hasTraceKey && hasStartedAt && (!hasIsInjected || !hasDpStatusEnd)) {
+    console.log("[trace-store-sqlite] Migrating agent_traces v3 → v4 (adding is_injected_prompt + dp_status_end)...");
+    db.exec("BEGIN");
+    try {
+      if (!hasIsInjected) {
+        db.exec(`ALTER TABLE agent_traces ADD COLUMN is_injected_prompt INTEGER NOT NULL DEFAULT 0`);
+      }
+      if (!hasDpStatusEnd) {
+        db.exec(`ALTER TABLE agent_traces ADD COLUMN dp_status_end TEXT NOT NULL DEFAULT 'idle'`);
+      }
+      db.exec(DDL_V4_INDEXES);
+      db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+      db.exec("COMMIT");
+      const count = (db.prepare("SELECT COUNT(*) AS n FROM agent_traces").get() as { n: number }).n;
+      console.log(`[trace-store-sqlite] Migration complete. ${count} existing row(s) kept, new columns defaulted.`);
+    } catch (err) {
+      db.exec("ROLLBACK");
+      throw err;
+    }
+    return;
+  }
+
+  if (hasTraceKey && hasStartedAt && hasIsInjected && hasDpStatusEnd) {
+    db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+    db.exec(DDL_V4_INDEXES);
+    return;
+  }
+
+  throw new Error("[trace-store-sqlite] Unrecognized agent_traces schema — refusing to migrate blindly.");
+}
+
+function rebuildFromLegacy(db: DatabaseSync, legacy: "v1" | "v2"): void {
+  db.exec("BEGIN");
+  try {
+    db.exec(`ALTER TABLE agent_traces RENAME TO agent_traces_legacy`);
+    db.exec(DDL_V4_TABLE);
+
+    const traceKeyCol = legacy === "v1" ? "id" : "trace_key";
+
+    db.exec(`
+      INSERT INTO agent_traces (
+        trace_key, session_id, prompt_idx, user_id, username, mode, brain_type, model_name,
+        user_message, outcome, started_at, ended_at, duration_ms,
+        step_count, tool_call_count, tokens_total, cost_usd,
+        schema_version, body_json, body_bytes, created_at
+      )
+      SELECT ${traceKeyCol}, session_id, prompt_idx, user_id, username, mode, brain_type, model_name,
+             user_message, outcome,
+             strftime('%Y-%m-%d %H:%M:%f', started_at_ms / 1000.0, 'unixepoch', '+8 hours'),
+             strftime('%Y-%m-%d %H:%M:%f', ended_at_ms   / 1000.0, 'unixepoch', '+8 hours'),
+             duration_ms,
+             step_count, tool_call_count, tokens_total, cost_usd,
+             schema_version, body_json, body_bytes,
+             strftime('%Y-%m-%d %H:%M:%f', created_at, 'unixepoch', '+8 hours')
+        FROM agent_traces_legacy
+       ORDER BY started_at_ms ASC, rowid ASC
+    `);
+    db.exec(`DROP TABLE agent_traces_legacy`);
+    db.exec(DDL_V4_INDEXES);
+    db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+    db.exec("COMMIT");
+    const count = (db.prepare("SELECT COUNT(*) AS n FROM agent_traces").get() as { n: number }).n;
+    console.log(`[trace-store-sqlite] Migration complete. ${count} row(s) carried over.`);
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+}
diff --git a/src/core/trace-store-types.ts b/src/core/trace-store-types.ts
new file mode 100644
index 00000000..33a66d9e
--- /dev/null
+++ b/src/core/trace-store-types.ts
@@ -0,0 +1,94 @@
+/**
+ * TraceStore — storage contract for persisted per-prompt traces.
+ *
+ * This file is the *interface* layer. Concrete implementations live in:
+ *   - trace-store-sqlite.ts      — SqliteTraceStore    (local, default in dev)
+ *   - trace-store-mysql.ts       — MysqlTraceStore     (cluster-hosted prod DB)
+ *   - trace-store-composite.ts   — CompositeTraceStore (dual-writes to several)
+ *
+ * TraceRecorder only depends on this interface — it does not know whether the
+ * backing store is SQLite, MySQL, or a composite fan-out. This lets the
+ * recorder run unchanged under ephemeral K8s pods (where local SQLite data
+ * would be lost when the pod restarts) by swapping in a remote store.
+ */
+
+export interface TraceRow {
+  /** Business id (human-readable, globally unique, matches trace-*.json filename stem). */
+  id: string;
+  sessionId: string;
+  promptIdx: number;
+  userId: string | null;
+  username: string | null;
+  mode: string;
+  brainType: string | null;
+  modelName: string | null;
+  userMessage: string | null;
+  outcome: string;
+  /** Beijing time, "YYYY-MM-DD HH:mm:ss.SSS". Zero-padded → safe for lex sort. */
+  startedAt: string;
+  endedAt: string;
+  /** Interval kept as integer ms for filtering/sorting; exposed as `duration`
+   *  (formatted HH:mm:ss.SSS) in API responses. */
+  durationMs: number;
+  /** Formatted duration, HH:mm:ss.SSS. Derived from durationMs on read.
+   *  Optional because insert() callers don't supply it — rowToTraceRow fills it. */
+  duration?: string;
+  stepCount: number;
+  toolCallCount: number;
+  tokensTotal: number | null;
+  costUsd: number | null;
+  schemaVersion: string;
+  /** Beijing time string. Set by DB DEFAULT on insert, populated on read. */
+  createdAt?: string;
+  /** True when userMessage is a UI-button-generated canned string (DP_CONFIRM
+   *  full body, dig-deeper, etc.). See trace-recorder's INJECTED_PROMPT
+   *  classification. */
+  isInjectedPrompt: boolean;
+  /** DP (Deep Probe) workflow status at the moment the trace was persisted.
+   *  One of: idle / investigating / awaiting_confirmation / validating /
+   *  concluding / completed. */
+  dpStatusEnd: string;
+}
+
+export interface TraceListOpts {
+  userId?: string;
+  username?: string;
+  /** Inclusive lower bound, Beijing "YYYY-MM-DD HH:mm:ss.SSS". */
+  from?: string;
+  /** Inclusive upper bound, Beijing "YYYY-MM-DD HH:mm:ss.SSS". */
+  to?: string;
+  minDurationMs?: number;
+  outcome?: string;
+  limit?: number;
+  /** Keyset cursor: last row's (startedAt, id). Next page is strictly older. */
+  cursorStartedAt?: string;
+  cursorId?: string;
+}
+
+export interface TraceListResult {
+  items: TraceRow[];
+  nextCursor: { startedAt: string; id: string } | null;
+}
+
+export interface TraceRecord extends TraceRow {
+  bodyJson: string;
+}
+
+/**
+ * The storage contract. All methods are async so implementations over the
+ * network (MySQL, HTTP) are first-class — local synchronous implementations
+ * just return resolved promises.
+ */
+export interface TraceStore {
+  /** INSERT, fails loud on UNIQUE(trace_key) collision. */
+  insert(row: TraceRow & { bodyJson: string }): Promise<void>;
+  /** INSERT or UPDATE (same trace_key). Used by the recorder's two-phase
+   *  persistence (stub at beginPrompt → full row at flush). */
+  upsert(row: TraceRow & { bodyJson: string }): Promise<void>;
+  /** Paginated list with filters. Keyset cursor in opts. */
+  list(opts: TraceListOpts): Promise<TraceListResult>;
+  /** Fetch one trace (with body JSON) by business key. */
+  getById(id: string): Promise<TraceRecord | null>;
+  /** Release resources (DB connections, file handles). Idempotent. */
+  close(): Promise<void>;
+}
diff --git a/src/core/trace-store.ts b/src/core/trace-store.ts
new file mode 100644
index 00000000..86e7d00f
--- /dev/null
+++ b/src/core/trace-store.ts
@@ -0,0 +1,149 @@
+/**
+ * TraceStore — public entry point.
+ *
+ * Re-exports the interface + concrete implementations and provides the async
+ * factory `getTraceStore()` that inspects env-var config and returns a ready
+ * store (or null if tracing is fully disabled).
+ *
+ * Config (environment variables):
+ *   SICLAW_TRACE_DISABLE=1           → master kill switch; factory returns null
+ *   SICLAW_TRACE_SQLITE_ENABLED=1    → enable SQLite sink (DEFAULT OFF)
+ *   SICLAW_TRACE_MYSQL_ENABLED=0     → disable MySQL sink (DEFAULT ON)
+ *   SICLAW_TRACE_MYSQL_URL=mysql://user:pass@host:3306/db
+ *                                    → required when MySQL is enabled
+ *   SICLAW_TRACE_DB=/path/to/file    → override SQLite path (default
+ *                                      <cwd>/.siclaw/traces.sqlite)
+ *
+ * Enablement matrix:
+ *   sqlite=0 mysql=0 → null (no tracing)
+ *   sqlite=1 mysql=0 → SqliteTraceStore
+ *   sqlite=0 mysql=1 → MysqlTraceStore (default)
+ *   sqlite=1 mysql=1 → CompositeTraceStore([mysql, sqlite])  — MySQL primary,
+ *                       dual-write, warn-on-partial-failure
+ *
+ * If MySQL is enabled but SICLAW_TRACE_MYSQL_URL is missing, MySQL is skipped
+ * with a warning; if SQLite is also disabled, factory returns null.
+ */
+
+import path from "node:path";
+import type { TraceStore } from "./trace-store-types.js";
+import { SqliteTraceStore } from "./trace-store-sqlite.js";
+import { MysqlTraceStore } from "./trace-store-mysql.js";
+import { CompositeTraceStore, type NamedStore } from "./trace-store-composite.js";
+
+// Re-exports — consumers should import everything from this barrel.
+export type {
+  TraceStore,
+  TraceRow,
+  TraceListOpts,
+  TraceListResult,
+  TraceRecord,
+} from "./trace-store-types.js";
+export { SqliteTraceStore } from "./trace-store-sqlite.js";
+export { MysqlTraceStore } from "./trace-store-mysql.js";
+export { CompositeTraceStore } from "./trace-store-composite.js";
+
+// ── Factory ─────────────────────────────────────────────────────────────────
+
+let _storePromise: Promise<TraceStore | null> | null = null;
+
+/**
+ * Return the process-level TraceStore, constructing it lazily. Memoized —
+ * subsequent calls return the same promise (which resolves to the same
+ * instance). Async because MySQL schema init happens on first use.
+ */
+export function getTraceStore(): Promise<TraceStore | null> {
+  if (!_storePromise) _storePromise = buildStore();
+  return _storePromise;
+}
+
+/** Close any open store. Idempotent. */
+export async function closeTraceStore(): Promise<void> {
+  if (!_storePromise) return;
+  const p = _storePromise;
+  _storePromise = null;
+  const store = await p;
+  if (store) {
+    try { await store.close(); }
+    catch (err) { console.warn("[trace-store] close failed:", err); }
+  }
+}
+
+/** Internal: resolve config → named stores → single / composite. */
+async function buildStore(): Promise<TraceStore | null> {
+  if (process.env.SICLAW_TRACE_DISABLE === "1") {
+    console.log("[trace-store] SICLAW_TRACE_DISABLE=1 — tracing disabled");
+    return null;
+  }
+
+  // Explicit flags: default SQLite OFF, default MySQL ON (per product
+  // decision — production is K8s with a MySQL pod; local SQLite is opt-in).
+  const sqliteEnabled = readBool("SICLAW_TRACE_SQLITE_ENABLED", false);
+  const mysqlEnabled = readBool("SICLAW_TRACE_MYSQL_ENABLED", true);
+
+  const stores: NamedStore[] = [];
+
+  // MySQL first so it becomes the composite's primary (reads go here).
+  if (mysqlEnabled) {
+    const url = process.env.SICLAW_TRACE_MYSQL_URL?.trim();
+    if (!url) {
+      console.warn(
+        "[trace-store] SICLAW_TRACE_MYSQL_ENABLED is on but SICLAW_TRACE_MYSQL_URL is unset — skipping MySQL sink. " +
+        "Set the URL or SICLAW_TRACE_MYSQL_ENABLED=0 to silence this warning.",
+      );
+    } else {
+      try {
+        const store = new MysqlTraceStore(url);
+        await store.ensureSchema();
+        stores.push({ name: "mysql", store });
+        console.log(`[trace-store] MySQL sink ready: ${redactUrl(url)}`);
+      } catch (err) {
+        console.warn("[trace-store] MySQL sink init failed, continuing without it:", err);
+      }
+    }
+  }
+
+  if (sqliteEnabled) {
+    try {
+      const dbPath =
+        process.env.SICLAW_TRACE_DB ??
+        path.join(process.cwd(), ".siclaw", "traces.sqlite");
+      stores.push({ name: "sqlite", store: new SqliteTraceStore(dbPath) });
+      console.log(`[trace-store] SQLite sink ready: ${dbPath}`);
+    } catch (err) {
+      console.warn("[trace-store] SQLite sink init failed, continuing without it:", err);
+    }
+  }
+
+  if (stores.length === 0) {
+    console.warn(
+      "[trace-store] No trace sinks enabled. Traces will NOT be persisted. " +
+      "Enable MySQL (SICLAW_TRACE_MYSQL_URL=...) or SQLite (SICLAW_TRACE_SQLITE_ENABLED=1).",
+    );
+    return null;
+  }
+
+  if (stores.length === 1) {
+    return stores[0].store;
+  }
+
+  return new CompositeTraceStore(stores);
+}
+
+/** Parse an env var as boolean, with an explicit default for unset/empty. */
+function readBool(name: string, defaultValue: boolean): boolean {
+  const raw = process.env[name];
+  if (raw === undefined || raw === "") return defaultValue;
+  return raw === "1" || raw.toLowerCase() === "true" || raw.toLowerCase() === "yes";
+}
+
+/** Mask the password segment when logging a MySQL URL. */
+function redactUrl(url: string): string {
+  try {
+    const u = new URL(url);
+    if (u.password) u.password = "***";
+    return u.toString();
+  } catch {
+    return url.replace(/(:\/\/[^:]+:)[^@]+(@)/, "$1***$2");
+  }
+}
diff --git a/src/gateway/agentbox/client.ts b/src/gateway/agentbox/client.ts
index 3ad009ee..079fc101 100644
--- a/src/gateway/agentbox/client.ts
+++ b/src/gateway/agentbox/client.ts
@@ -29,6 +29,8 @@ export interface PromptOptions {
   brainType?: string;
   /** Workspace ID (for logging/context) */
   workspaceId?: string;
+  /** Displayable username of the caller (for human-readable trace filenames). */
+  username?: string;
   /** Credential payload — agentbox materializes files locally from this data */
   credentials?: {
     manifest: Array<{ name: string; type: string; description?: string | null; files: string[]; metadata?: Record<string, unknown> }>;
diff --git a/src/gateway/config.ts b/src/gateway/config.ts
index 7eae3cbc..f619add4 100644
--- a/src/gateway/config.ts
+++ b/src/gateway/config.ts
@@ -1,3 +1,6 @@
+import fs from "node:fs";
+import path from "node:path";
+
 export interface ChannelConfig {
   enabled: boolean;
   [key: string]: unknown;
@@ -23,5 +26,15 @@ const DEFAULT_CONFIG: GatewayConfig = {
 };
 
 export function loadGatewayConfig(): GatewayConfig {
+  try {
+    // Read port from shared settings.json so one file controls everything
+    const configPath = process.env.SICLAW_CONFIG_DIR
+      ? path.resolve(process.env.SICLAW_CONFIG_DIR, "settings.json")
+      : path.resolve(process.cwd(), ".siclaw", "config", "settings.json");
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf-8")) as { server?: { port?: number } };
+    if (raw?.server?.port) {
+      return { ...DEFAULT_CONFIG, port: raw.server.port };
+    }
+  } catch { /* fall through to default */ }
   return { ...DEFAULT_CONFIG };
 }
diff --git a/src/gateway/rpc-methods.ts b/src/gateway/rpc-methods.ts
index 1d0d7b40..2738df2f 100644
--- a/src/gateway/rpc-methods.ts
+++ b/src/gateway/rpc-methods.ts
@@ -1437,7 +1437,7 @@ export function createRpcMethods(
 
     // Send prompt
     const systemPromptTemplate = workspace?.configJson?.systemPrompt || undefined;
-    const result = await client.prompt({ sessionId, text: promptText, modelProvider, modelId, brainType, systemPromptTemplate, modelConfig, credentials });
+    const result = await client.prompt({ sessionId, text: promptText, modelProvider, modelId, brainType, systemPromptTemplate, modelConfig, credentials, username });
     console.log(`[rpc] prompt sent → sessionId=${result.sessionId}`);
 
     // Build redaction config from credential payload + model secrets (sanitize outbound WS stream)
diff --git a/src/gateway/server.ts b/src/gateway/server.ts
index 299e5799..5a917944 100644
--- a/src/gateway/server.ts
+++ b/src/gateway/server.ts
@@ -191,6 +191,93 @@ export interface StartGatewayOptions {
   extraHttpHandlers?: Map<string, (req: http.IncomingMessage, res: http.ServerResponse) => void>;
 }
 
+/** Format unix-ms as Beijing "YYYY-MM-DD HH:mm:ss.SSS" for trace query filters. */
+function formatBeijingMs(ms: number): string {
+  const d = new Date(ms + 8 * 3600_000);
+  const p2 = (n: number) => (n < 10 ? `0${n}` : String(n));
+  const p3 = (n: number) => (n < 10 ? `00${n}` : n < 100 ? `0${n}` : String(n));
+  return `${d.getUTCFullYear()}-${p2(d.getUTCMonth() + 1)}-${p2(d.getUTCDate())} ` +
+         `${p2(d.getUTCHours())}:${p2(d.getUTCMinutes())}:${p2(d.getUTCSeconds())}.${p3(d.getUTCMilliseconds())}`;
+}
+
+/**
+ * GET /api/traces           — list persisted traces (keyset paginated)
+ * GET /api/traces/:traceKey — full trace JSON body (identical to trace-*.json file)
+ *
+ * Served by Gateway because it's a pure DB read, independent of agent
+ * runtime. AgentBox is lazy-spawned — we do NOT want this to block on that.
+ */
+async function handleTracesQuery(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+  const { getTraceStore } = await import("../core/trace-store.js");
+  const store = await getTraceStore();
+  if (!store) {
+    res.writeHead(503, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Trace store unavailable (no sinks configured; set SICLAW_TRACE_MYSQL_URL or SICLAW_TRACE_SQLITE_ENABLED=1)" }));
+    return;
+  }
+
+  const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+  const pathname = url.pathname;
+
+  // GET /api/traces/:traceKey — single trace body
+  if (pathname !== "/api/traces") {
+    const m = pathname.match(/^\/api\/traces\/([^/]+)$/);
+    if (!m) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Not found" }));
+      return;
+    }
+    const traceKey = decodeURIComponent(m[1]);
+    const rec = await store.getById(traceKey);
+    if (!rec) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Trace not found" }));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(rec.bodyJson);
+    return;
+  }
+
+  // GET /api/traces — paginated list
+  const q = url.searchParams;
+  const num = (k: string): number | undefined => {
+    const v = q.get(k);
+    if (v === null || v === "") return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+  };
+  const beijingStr = (k: string): string | undefined => {
+    const v = q.get(k);
+    if (!v) return undefined;
+    const asNum = Number(v);
+    if (Number.isFinite(asNum) && String(asNum) === v.trim()) return formatBeijingMs(asNum);
+    return v;
+  };
+
+  const nowMs = Date.now();
+  let from = beijingStr("from");
+  const to = beijingStr("to");
+  const lastHours = num("lastHours");
+  const lastDays = num("lastDays");
+  if (from === undefined && lastHours !== undefined) from = formatBeijingMs(nowMs - lastHours * 3600_000);
+  if (from === undefined && lastDays !== undefined)  from = formatBeijingMs(nowMs - lastDays * 86400_000);
+
+  const result = await store.list({
+    userId: q.get("userId") ?? undefined,
+    username: q.get("username") ?? undefined,
+    from,
+    to,
+    minDurationMs: num("minDurationMs"),
+    outcome: q.get("outcome") ?? undefined,
+    limit: num("limit"),
+    cursorStartedAt: q.get("cursorStartedAt") ?? undefined,
+    cursorId: q.get("cursorId") ?? undefined,
+  });
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(result));
+}
+
 export async function startGateway(opts: StartGatewayOptions): Promise<GatewayServer> {
   const { config, agentBoxManager, spawner, extraRpcMethods, extraHttpHandlers } = opts;
 
@@ -680,6 +767,15 @@ export async function startGateway(opts: StartGatewayOptions): Promise<GatewaySe
       return;
     }
 
+    // ── Trace query API ───────────────────────────────────
+    // Pure DB read; intentionally served by Gateway (always-on) rather than
+    // AgentBox (lazy-spawned) so queries work immediately after dev:gateway
+    // starts, with zero dependency on agent runtime state.
+    if (url.startsWith("/api/traces") && method === "GET") {
+      handleTracesQuery(req, res);
+      return;
+    }
+
     // SSO: redirect to IdP authorize URL
     if (url === "/auth/sso" && method === "GET") {
       if (!cachedSsoEnabled || !cachedOAuth2Config) {
diff --git a/src/gateway/web/src/hooks/usePilot.ts b/src/gateway/web/src/hooks/usePilot.ts
index 56ed111d..b91e8ae1 100644
--- a/src/gateway/web/src/hooks/usePilot.ts
+++ b/src/gateway/web/src/hooks/usePilot.ts
@@ -34,6 +34,14 @@ export interface PilotMessage {
     isStreaming?: boolean;
     /** Hidden from chat bubbles (e.g. update_plan tool messages) */
     hidden?: boolean;
+    /** performance.now() when tool_execution_start was received — drives live stopwatch */
+    startedAt?: number;
+    /** Elapsed ms from tool_execution_start to tool_execution_end */
+    durationMs?: number;
+    /** Elapsed ms for LLM thinking (message_start to message_end) — on assistant messages */
+    llmDurationMs?: number;
+    /** ms from last anchor event (tool_execution_end or send) to message_start — TTFT approximation */
+    waitMs?: number;
 }
 
 export interface Session {
@@ -155,6 +163,17 @@ function reduceInvestigationProgress(
 }
 
 const SESSION_KEY_STORAGE = 'siclaw_current_session';
+
+const TIMING_MAX_SAMPLES = 200;
+function appendTimingSample(key: string, ms: number): void {
+    try {
+        const arr = JSON.parse(localStorage.getItem(key) ?? '[]') as number[];
+        arr.push(Math.round(ms));
+        if (arr.length > TIMING_MAX_SAMPLES) arr.splice(0, arr.length - TIMING_MAX_SAMPLES);
+        localStorage.setItem(key, JSON.stringify(arr));
+        window.dispatchEvent(new CustomEvent('siclaw_timing_update'));
+    } catch { /* ignore storage errors */ }
+}
 const SESSION_WORKSPACE_STORAGE = 'siclaw_session_workspace';
 const SELECTED_BRAIN_STORAGE = 'siclaw_selected_brain';
 
@@ -300,6 +319,20 @@ export function usePilot() {
     // The actual brain type of the current active session (from backend), null = no session / unknown
     const [sessionBrainType, setSessionBrainType] = useState<BrainType | null>(null);
 
+    // Timing: performance.now() when the current prompt was sent (drives ThinkingIndicator stopwatch)
+    const [loadingStartedAt, setLoadingStartedAt] = useState<number | null>(null);
+    // Ref tracks performance.now() of last message_start for LLM duration calculation
+    const llmStartRef = useRef<number>(0);
+    // When LLM only emits tool calls (no text), llmDurationMs has nowhere to attach —
+    // park it here until the next tool_execution_start claims it
+    const pendingLlmDurationMsRef = useRef<number>(0);
+    // Server-side Date.now() of last anchor event (sendMessage or tool_execution_end) — for TTFT calc
+    const lastServerTsRef = useRef<number>(0);
+    // Parked TTFT value (message_start.ts - lastServerTsRef) awaiting attachment to a message
+    const pendingWaitMsRef = useRef<number>(0);
+
+    // Ref for sendRpc — handleWsMessage has [] deps and can't close over sendRpc directly
+    const sendRpcRef = useRef<(<T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>) | null>(null);
     // Ref to allow loadSessions calls from event handler without stale closures
     const loadSessionsRef = useRef<() => void>(() => {});
     // Ref for fetching context usage from event handler
@@ -415,6 +448,14 @@ export function usePilot() {
                         setInvestigationProgress(prev => prev ?? { hypotheses: [] });
                         // Checklist creation now handled by dp_status event from gateway.
                     }
+                    // Claim pending LLM thinking duration (set when LLM only emitted tool calls, no text)
+                    const thinkMs = pendingLlmDurationMsRef.current || undefined;
+                    pendingLlmDurationMsRef.current = 0;
+                    // Claim pending TTFT (set at message_start when LLM only emitted tool calls)
+                    const waitMs = pendingWaitMsRef.current || undefined;
+                    pendingWaitMsRef.current = 0;
+                    if (waitMs != null) appendTimingSample('siclaw_timing_ttft', waitMs);
+                    if (thinkMs != null) appendTimingSample('siclaw_timing_llm', thinkMs);
                     // end_investigation cleanup now driven by dp_status "completed" event from gateway.
                     setMessages(prev => [...prev, {
                         id: `tool-${Date.now()}`,
@@ -426,11 +467,16 @@ export function usePilot() {
                         timestamp: new Date().toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }),
                         isStreaming: true,
                         hidden,
+                        startedAt: performance.now(),
+                        llmDurationMs: thinkMs,
+                        waitMs,
                     }]);
                     break;
                 }
 
                 case 'tool_execution_end': {
+                    // Update anchor timestamp for next TTFT calculation
+                    if (payload.ts) lastServerTsRef.current = payload.ts as number;
                     const result = payload.result as { content?: Array<{ type: string; text?: string }>; details?: Record<string, unknown> } | undefined;
                     const resultText = result?.content
                         ?.filter((c: { type: string }) => c.type === 'text')
@@ -443,6 +489,12 @@ export function usePilot() {
                     // Check toolName before entering setMessages to avoid side effects
                     // inside the state updater (React StrictMode calls updaters twice).
                     const endedToolName = payload.toolName as string | undefined;
+                    const endPerfNow = performance.now();
+                    // Capture timing from the running tool BEFORE setMessages (messagesRef is last committed state)
+                    const runningTool = [...messagesRef.current].reverse().find(m => m.role === 'tool' && m.isStreaming);
+                    const durationMsSnap = runningTool?.startedAt != null ? Math.round(endPerfNow - runningTool.startedAt) : undefined;
+                    const toolWaitMs = runningTool?.waitMs;
+                    const toolLlmDurationMs = runningTool?.llmDurationMs;
                     // When deep_search completes, mark all remaining checklist items
                     // as done and auto-clear after 3s. This replaces the old
                     // manage_checklist(conclusion=done) trigger.
@@ -463,6 +515,9 @@ export function usePilot() {
                     setMessages(prev => {
                         const last = prev[prev.length - 1];
                         if (last?.role === 'tool' && last.isStreaming) {
+                            const durationMs = last.startedAt != null
+                                ? Math.round(endPerfNow - last.startedAt)
+                                : undefined;
                             return [
                                 ...prev.slice(0, -1),
                                 {
@@ -470,6 +525,7 @@ export function usePilot() {
                                     content: resultText,
                                     toolStatus: isError ? 'error' as const : 'success' as const,
                                     isStreaming: false,
+                                    durationMs,
                                     ...(toolDetails ? { toolDetails } : {}),
                                     ...(dbMessageId ? { id: dbMessageId } : {}),
                                 }
@@ -477,6 +533,17 @@ export function usePilot() {
                         }
                         return prev;
                     });
+                    // Collect tool execution time sample for dashboard statistics
+                    if (durationMsSnap != null) appendTimingSample('siclaw_timing_tool', durationMsSnap);
+                    // Persist timing + toolStatus to DB via metadata so they survive navigation and session reload
+                    if (dbMessageId && sendRpcRef.current) {
+                        const meta: Record<string, unknown> = {};
+                        meta.toolStatus = isError ? 'error' : 'success';
+                        if (durationMsSnap != null) meta.durationMs = durationMsSnap;
+                        if (toolWaitMs != null) meta.waitMs = toolWaitMs;
+                        if (toolLlmDurationMs != null) meta.llmDurationMs = toolLlmDurationMs;
+                        sendRpcRef.current('message.updateMeta', { id: dbMessageId, metadata: meta }).catch(() => {});
+                    }
                     break;
                 }
 
@@ -515,6 +582,13 @@ export function usePilot() {
                 }
 
                 case 'message_start': {
+                    llmStartRef.current = performance.now();
+                    // Compute TTFT: server ts of this event minus server ts of last anchor
+                    if (payload.ts && lastServerTsRef.current > 0) {
+                        pendingWaitMsRef.current = Math.max(0, Math.round((payload.ts as number) - lastServerTsRef.current));
+                    } else {
+                        pendingWaitMsRef.current = 0;
+                    }
                     const msg = payload.message as { role?: string; customType?: string; details?: Record<string, unknown>; content?: string | Array<{ type: string; text?: string }> } | undefined;
 
                     // Show steer (user) messages injected mid-conversation.
@@ -542,6 +616,36 @@ export function usePilot() {
 
                 case 'message_end': {
                     const endMsg = payload.message as { role?: string; toolName?: string; details?: Record<string, unknown> } | undefined;
+                    // Stamp LLM duration + TTFT onto the last streaming assistant message.
+                    // If LLM only emitted tool calls (no text), no streaming assistant message exists —
+                    // park both in pending refs so tool_execution_start can claim them.
+                    if (endMsg?.role === 'assistant' && llmStartRef.current > 0) {
+                        const llmDurationMs = Math.round(performance.now() - llmStartRef.current);
+                        llmStartRef.current = 0;
+                        const waitMs = pendingWaitMsRef.current || undefined;
+                        pendingWaitMsRef.current = 0;
+                        const hasStreamingAssistant = messagesRef.current.some(
+                            m => m.role === 'assistant' && m.isStreaming
+                        );
+                        if (hasStreamingAssistant) {
+                            if (waitMs != null) appendTimingSample('siclaw_timing_ttft', waitMs);
+                            appendTimingSample('siclaw_timing_llm', llmDurationMs);
+                            setMessages(prev => {
+                                for (let i = prev.length - 1; i >= 0; i--) {
+                                    if (prev[i].role === 'assistant' && prev[i].isStreaming) {
+                                        const updated = [...prev];
+                                        updated[i] = { ...prev[i], llmDurationMs, waitMs };
+                                        return updated;
+                                    }
+                                }
+                                return prev;
+                            });
+                        } else {
+                            pendingLlmDurationMsRef.current = llmDurationMs;
+                            // waitMs stays in pendingWaitMsRef — already cleared above, restore it
+                            pendingWaitMsRef.current = waitMs ?? 0;
+                        }
+                    }
                     if (endMsg?.role === 'toolResult' && endMsg.details && Object.keys(endMsg.details).length > 0) {
                         // Pi-agent brain: tool result details arrive via message_end (not tool_execution_end).
                         // Backfill toolDetails onto the matching tool message.
@@ -601,6 +705,7 @@ export function usePilot() {
                     // During abort, don't unlock here — abortResponse will do it after RPC completes
                     if (!isAbortingRef.current) {
                         setIsLoading(false);
+                        setLoadingStartedAt(null);
                     }
                     setPendingMessages([]);
                     loadSessionsRef.current();
@@ -608,6 +713,33 @@ export function usePilot() {
                     loadModelsRef.current();
                     fetchModelRef.current();
 
+                    // Persist timing for assistant messages — they have no dbMessageId during streaming,
+                    // so we fetch the just-saved DB messages and match by role+content to update metadata.
+                    if (!isAbortingRef.current && sendRpcRef.current && currentSessionKeyRef.current) {
+                        const sessionId = currentSessionKeyRef.current;
+                        const rpc = sendRpcRef.current;
+                        const assistantsToSave = messagesRef.current.filter(m =>
+                            m.role === 'assistant' && (m.llmDurationMs != null || m.waitMs != null)
+                        );
+                        if (assistantsToSave.length > 0) {
+                            setTimeout(async () => {
+                                try {
+                                    const res = await rpc<{ messages: PilotMessage[] }>('chat.history', { sessionId });
+                                    const dbMessages = res.messages ?? [];
+                                    for (const m of assistantsToSave) {
+                                        const match = dbMessages.find(d => d.role === 'assistant' && d.content === m.content);
+                                        if (match) {
+                                            const meta: Record<string, unknown> = {};
+                                            if (m.llmDurationMs != null) meta.llmDurationMs = m.llmDurationMs;
+                                            if (m.waitMs != null) meta.waitMs = m.waitMs;
+                                            await rpc('message.updateMeta', { id: match.id, metadata: meta });
+                                        }
+                                    }
+                                } catch { /* best-effort */ }
+                            }, 800);
+                        }
+                    }
+
                     // DP checklist completion now handled by dp_status "completed" event from gateway.
                     // No safety-net needed — gateway emits dp_status on agent_end when status is concluding.
                     break;
@@ -688,7 +820,8 @@ export function usePilot() {
         }
     }, [isConnected, sendRpc, workspaceId]);
 
-    // Keep ref in sync
+    // Keep refs in sync
+    sendRpcRef.current = sendRpc;
     loadSessionsRef.current = loadSessions;
     loadModelsRef.current = loadModels;
     fetchModelRef.current = fetchCurrentModel;
@@ -718,6 +851,11 @@ export function usePilot() {
 
     const mapMessages = (raw: PilotMessage[]) => raw.map(m => ({
         ...m,
+        // Restore timing + toolStatus from metadata (persisted at runtime; absent on first load before any conversation)
+        toolStatus: m.toolStatus ?? (m.metadata?.toolStatus as ToolStatus | undefined) ?? (m.role === 'tool' && m.content ? 'success' as ToolStatus : undefined),
+        durationMs: m.durationMs ?? (m.metadata?.durationMs as number | undefined),
+        llmDurationMs: m.llmDurationMs ?? (m.metadata?.llmDurationMs as number | undefined),
+        waitMs: m.waitMs ?? (m.metadata?.waitMs as number | undefined),
         toolInput: m.role === 'tool' && m.toolInput
             ? parseToolInput(m.toolName ?? '', m.toolInput)
             : undefined,
@@ -811,6 +949,9 @@ export function usePilot() {
         };
         setMessages(prev => [...prev, userMsg]);
         setIsLoading(true);
+        setLoadingStartedAt(performance.now());
+        lastServerTsRef.current = Date.now();
+        pendingWaitMsRef.current = 0;
 
         try {
             const result = await sendRpc<{ sessionId: string; brainType?: BrainType }>('chat.send', {
@@ -1278,5 +1419,6 @@ export function usePilot() {
         selectedBrain,
         selectBrain,
         sessionBrainType,
+        loadingStartedAt,
     };
 }
diff --git a/src/gateway/web/src/pages/Metrics/DashboardTab.tsx b/src/gateway/web/src/pages/Metrics/DashboardTab.tsx
index 58c3c0dd..8288b850 100644
--- a/src/gateway/web/src/pages/Metrics/DashboardTab.tsx
+++ b/src/gateway/web/src/pages/Metrics/DashboardTab.tsx
@@ -6,6 +6,7 @@ import { SessionsChart } from './SessionsChart';
 import { ToolCallsPanel } from './ToolCallsPanel';
 import { SkillCallsPanel } from './SkillCallsPanel';
 import { CumulativePanel } from './CumulativePanel';
+import { TimingStatsPanel } from './TimingStatsPanel';
 
 interface DashboardTabProps {
     data: TimeseriesResponse | null;
@@ -48,7 +49,10 @@ export function DashboardTab({ data, range, loading }: DashboardTabProps) {
                 {/* Row 4: Sessions & Connections (full width) */}
                 <SessionsChart buckets={buckets} />
 
-                {/* Row 5: Cumulative Statistics (full width) */}
+                {/* Row 5: Response Timing Distribution (full width) */}
+                <TimingStatsPanel />
+
+                {/* Row 6: Cumulative Statistics (full width) */}
                 <CumulativePanel />
             </div>
         </div>
diff --git a/src/gateway/web/src/pages/Metrics/TimingStatsPanel.tsx b/src/gateway/web/src/pages/Metrics/TimingStatsPanel.tsx
new file mode 100644
index 00000000..a35c68b1
--- /dev/null
+++ b/src/gateway/web/src/pages/Metrics/TimingStatsPanel.tsx
@@ -0,0 +1,169 @@
+import { useState, useEffect } from 'react';
+import { BarChart, Bar, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer, Cell } from 'recharts';
+
+function readSamples(key: string): number[] {
+    try { return JSON.parse(localStorage.getItem(key) ?? '[]') as number[]; } catch { return []; }
+}
+
+function computeStats(samples: number[]) {
+    if (samples.length === 0) return null;
+    const sorted = [...samples].sort((a, b) => a - b);
+    const n = sorted.length;
+    const pct = (p: number) => sorted[Math.min(Math.ceil(n * p) - 1, n - 1)];
+    return {
+        min: sorted[0],
+        avg: Math.round(samples.reduce((s, v) => s + v, 0) / n),
+        p95: pct(0.95),
+        p99: pct(0.99),
+        max: sorted[n - 1],
+        count: n,
+    };
+}
+
+function fmt(ms: number | undefined): string {
+    if (ms == null) return '—';
+    if (ms < 1000) return `${ms}ms`;
+    return `${(ms / 1000).toFixed(2)}s`;
+}
+
+type StatKey = 'min' | 'avg' | 'p95' | 'p99' | 'max';
+const STAT_ROWS: { key: StatKey; label: string }[] = [
+    { key: 'min', label: 'MIN' },
+    { key: 'avg', label: 'AVG' },
+    { key: 'p95', label: 'P95' },
+    { key: 'p99', label: 'P99' },
+    { key: 'max', label: 'MAX' },
+];
+
+const METRICS = [
+    { key: 'siclaw_timing_ttft', label: 'TTFT', color: '#6366f1' },
+    { key: 'siclaw_timing_llm',  label: 'Thinking', color: '#f59e0b' },
+    { key: 'siclaw_timing_tool', label: 'Tool Exec', color: '#10b981' },
+] as const;
+
+export function TimingStatsPanel() {
+    const [tick, setTick] = useState(0);
+
+    useEffect(() => {
+        const handler = () => setTick(t => t + 1);
+        window.addEventListener('siclaw_timing_update', handler);
+        return () => window.removeEventListener('siclaw_timing_update', handler);
+    }, []);
+
+    const stats = METRICS.map(m => ({
+        ...m,
+        samples: tick >= 0 ? readSamples(m.key) : [],
+        stat: null as ReturnType<typeof computeStats>,
+    })).map(m => ({ ...m, stat: computeStats(m.samples) }));
+
+    const totalSamples = Math.max(...stats.map(m => m.samples.length));
+    const hasData = totalSamples > 0;
+
+    const handleClear = () => {
+        METRICS.forEach(m => localStorage.removeItem(m.key));
+        setTick(t => t + 1);
+    };
+
+    // Bar chart data: one bar per metric, height = avg
+    const barData = stats.map(m => ({
+        name: m.label,
+        avg: m.stat?.avg ?? 0,
+        color: m.color,
+    }));
+
+    return (
+        <div className="bg-white rounded-lg border border-gray-200 p-5">
+            <div className="flex items-center justify-between mb-5">
+                <div>
+                    <h3 className="text-sm font-semibold text-gray-900">Response Timing Statistics</h3>
+                    <p className="text-xs text-gray-400 mt-0.5">
+                        TTFT, thinking, and tool execution times
+                        {hasData ? ` — last ${totalSamples} / 200 calls` : ''}
+                    </p>
+                </div>
+                {hasData && (
+                    <button
+                        type="button"
+                        onClick={handleClear}
+                        className="text-xs text-gray-400 hover:text-red-500 px-2 py-1 rounded hover:bg-red-50 transition-colors"
+                    >
+                        Clear
+                    </button>
+                )}
+            </div>
+
+            {!hasData ? (
+                <div className="h-40 flex items-center justify-center text-xs text-gray-400 border border-dashed border-gray-200 rounded-lg">
+                    No data yet — start a conversation to collect timing samples
+                </div>
+            ) : (
+                <div className="flex gap-8 items-start">
+                    {/* Left: bar chart comparing avg of each metric */}
+                    <div className="flex-1 min-w-0">
+                        <p className="text-xs text-gray-400 mb-2">Average comparison</p>
+                        <ResponsiveContainer width="100%" height={200}>
+                            <BarChart data={barData} margin={{ top: 4, right: 4, bottom: 0, left: 0 }}>
+                                <CartesianGrid strokeDasharray="3 3" vertical={false} stroke="#f3f4f6" />
+                                <XAxis dataKey="name" tick={{ fontSize: 12 }} axisLine={false} tickLine={false} />
+                                <YAxis
+                                    tickFormatter={(v: number) => fmt(v)}
+                                    tick={{ fontSize: 10 }}
+                                    width={56}
+                                    axisLine={false}
+                                    tickLine={false}
+                                />
+                                <Tooltip
+                                    formatter={(v: unknown) => [fmt(v as number), 'Average']}
+                                    contentStyle={{ fontSize: 12, borderRadius: 6 }}
+                                    cursor={{ fill: '#f9fafb' }}
+                                />
+                                <Bar dataKey="avg" radius={[4, 4, 0, 0]}>
+                                    {barData.map((entry, i) => (
+                                        <Cell key={i} fill={entry.color} />
+                                    ))}
+                                </Bar>
+                            </BarChart>
+                        </ResponsiveContainer>
+                    </div>
+
+                    {/* Right: stats table */}
+                    <div className="shrink-0">
+                        <p className="text-xs text-gray-400 mb-2">Percentiles</p>
+                        <table className="text-xs border-collapse">
+                            <thead>
+                                <tr>
+                                    <th className="text-left pr-4 pb-2 font-medium text-gray-400 w-10"></th>
+                                    {stats.map(m => (
+                                        <th key={m.key} className="text-right pr-4 pb-2 font-semibold" style={{ color: m.color }}>
+                                            {m.label}
+                                        </th>
+                                    ))}
+                                </tr>
+                            </thead>
+                            <tbody>
+                                {STAT_ROWS.map(({ key, label }) => (
+                                    <tr key={key} className="border-t border-gray-100">
+                                        <td className="pr-4 py-1.5 font-medium text-gray-400">{label}</td>
+                                        {stats.map(m => (
+                                            <td key={m.key} className="text-right pr-4 py-1.5 font-mono text-gray-700">
+                                                {fmt(m.stat?.[key])}
+                                            </td>
+                                        ))}
+                                    </tr>
+                                ))}
+                                <tr className="border-t border-gray-200">
+                                    <td className="pr-4 pt-2 text-gray-400">n</td>
+                                    {stats.map(m => (
+                                        <td key={m.key} className="text-right pr-4 pt-2 font-mono text-gray-400">
+                                            {m.stat?.count ?? 0}
+                                        </td>
+                                    ))}
+                                </tr>
+                            </tbody>
+                        </table>
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+}
diff --git a/src/gateway/web/src/pages/Pilot/components/PilotArea.tsx b/src/gateway/web/src/pages/Pilot/components/PilotArea.tsx
index 6839d1f1..9ec33f2f 100644
--- a/src/gateway/web/src/pages/Pilot/components/PilotArea.tsx
+++ b/src/gateway/web/src/pages/Pilot/components/PilotArea.tsx
@@ -60,6 +60,8 @@ export interface PilotAreaProps {
     /** Current workspace ID for cron job operations */
     selectedWorkspaceId?: string | null;
     isAdmin?: boolean;
+    /** performance.now() when the current prompt was sent — drives the top-level stopwatch */
+    loadingStartedAt?: number | null;
 }
 
 /** Compute superseded status for schedule messages */
@@ -108,7 +110,7 @@ function computeScheduleStatuses(messages: PilotMessage[]): Map<string, Schedule
     return statuses;
 }
 
-export function PilotArea({ messages, isLoading, isLoadingHistory, wsStatus, isConnected, hasMore, isLoadingMore, sendMessage, abortResponse, loadMoreHistory, sendRpc, contextUsage, isCompacting, isRetrying, onOpenSchedulePanel, onOpenSkillPanel, updateMessageMeta, pendingMessages, onRemovePending, investigationProgress, dpActive, onSetDpActive, dpFocus, dpChecklist, onHypothesesConfirmed, onExitDp, systemStatus, onNavigateModels, onNavigateCredentials, sessionKey, selectedWorkspaceId, isAdmin }: PilotAreaProps) {
+export function PilotArea({ messages, isLoading, isLoadingHistory, wsStatus, isConnected, hasMore, isLoadingMore, sendMessage, abortResponse, loadMoreHistory, sendRpc, contextUsage, isCompacting, isRetrying, onOpenSchedulePanel, onOpenSkillPanel, updateMessageMeta, pendingMessages, onRemovePending, investigationProgress, dpActive, onSetDpActive, dpFocus, dpChecklist, onHypothesesConfirmed, onExitDp, systemStatus, onNavigateModels, onNavigateCredentials, sessionKey, selectedWorkspaceId, isAdmin, loadingStartedAt }: PilotAreaProps) {
     const scrollRef = useRef<HTMLDivElement>(null);
     const scrollContainerRef = useRef<HTMLDivElement>(null);
     const prevScrollHeightRef = useRef(0);
@@ -501,7 +503,7 @@ export function PilotArea({ messages, isLoading, isLoadingHistory, wsStatus, isC
                                 <DpChecklistCard items={dpChecklist} investigationProgress={investigationProgress} onDismiss={onExitDp} />
                             )}
 
-                            {isLoading && <ThinkingIndicator />}
+                            {isLoading && <ThinkingIndicator startedAt={loadingStartedAt ?? undefined} />}
 
                             {showFeedbackHint && (
                                 <div className={cn(
@@ -536,9 +538,10 @@ export function PilotArea({ messages, isLoading, isLoadingHistory, wsStatus, isC
     );
 }
 
-function ThinkingIndicator() {
+function ThinkingIndicator({ startedAt }: { startedAt?: number }) {
     const [tipIndex, setTipIndex] = useState(0);
     const [visible, setVisible] = useState(true);
+    const [elapsed, setElapsed] = useState(0);
 
     useEffect(() => {
         const interval = setInterval(() => {
@@ -551,6 +554,12 @@ function ThinkingIndicator() {
         return () => clearInterval(interval);
     }, []);
 
+    useEffect(() => {
+        if (!startedAt) return;
+        const tick = setInterval(() => setElapsed(Math.floor((performance.now() - startedAt) / 1000)), 1000);
+        return () => clearInterval(tick);
+    }, [startedAt]);
+
     return (
         <div className="flex gap-4">
             <div className="w-8 h-8 rounded-full bg-white border border-gray-200 flex items-center justify-center text-primary-600 shadow-sm">
@@ -564,6 +573,9 @@ function ThinkingIndicator() {
                 )}>
                     {THINKING_TIPS[tipIndex]}
                 </span>
+                {startedAt != null && elapsed > 0 && (
+                    <span className="text-xs font-mono text-gray-400">{elapsed}s</span>
+                )}
             </div>
         </div>
     );
@@ -761,6 +773,12 @@ function MessageItem({ message, scheduleStatus, onOpenSchedulePanel, onOpenSkill
                     {message.isStreaming && !isUser && (
                         <Loader2 className="w-3 h-3 animate-spin text-gray-400" />
                     )}
+                    {!message.isStreaming && !isUser && message.waitMs != null && message.waitMs > 100 && (
+                        <span className="text-xs font-mono text-gray-400">⏳{formatDuration(message.waitMs)}</span>
+                    )}
+                    {!message.isStreaming && !isUser && message.llmDurationMs != null && (
+                        <span className="text-xs font-mono text-gray-400">💭{formatDuration(message.llmDurationMs)}</span>
+                    )}
                 </div>
 
                 {/* Reference chips (user messages only) */}
@@ -828,12 +846,38 @@ function MessageItem({ message, scheduleStatus, onOpenSchedulePanel, onOpenSkill
     );
 }
 
+function ToolItemTimer({ startedAt }: { startedAt: number }) {
+    const [elapsed, setElapsed] = useState(0);
+    useEffect(() => {
+        const tick = setInterval(() => setElapsed(Math.floor((performance.now() - startedAt) / 1000)), 1000);
+        return () => clearInterval(tick);
+    }, [startedAt]);
+    return <span className="text-xs font-mono text-blue-400 ml-auto shrink-0">{elapsed}s</span>;
+}
+
+function formatDuration(ms: number): string {
+    if (ms < 1000) return `${ms}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+
 function ToolItem({ message }: { message: PilotMessage }) {
     const [expanded, setExpanded] = useState(false);
     const isOpen = message.isStreaming || expanded;
 
     return (
         <div className="pl-12 min-w-0">
+            {message.waitMs != null && message.waitMs > 100 && (
+                <div className="flex items-center gap-1.5 px-3 py-1 text-xs text-gray-400 font-mono">
+                    <span>⏳</span>
+                    <span>Waiting {formatDuration(message.waitMs)}</span>
+                </div>
+            )}
+            {message.llmDurationMs != null && (
+                <div className="flex items-center gap-1.5 px-3 py-1 text-xs text-gray-400 font-mono">
+                    <span>💭</span>
+                    <span>Thinking {formatDuration(message.llmDurationMs)}</span>
+                </div>
+            )}
             <div className="bg-white border border-gray-200 rounded-lg shadow-sm overflow-hidden">
                 <button
                     type="button"
@@ -849,14 +893,27 @@ function ToolItem({ message }: { message: PilotMessage }) {
                     {message.toolInput && (
                         <span className="font-mono text-xs text-gray-500 truncate min-w-0">{message.toolInput}</span>
                     )}
-                    {message.toolStatus === 'running' && (
+                    {message.toolStatus === 'running' && message.startedAt != null && (
+                        <ToolItemTimer startedAt={message.startedAt} />
+                    )}
+                    {message.toolStatus === 'running' && message.startedAt == null && (
                         <Loader2 className="w-3 h-3 animate-spin text-blue-400 ml-auto shrink-0" />
                     )}
                     {message.toolStatus === 'success' && (
-                        <CheckCircle2 className="w-3.5 h-3.5 text-green-500 ml-auto shrink-0" />
+                        <span className="flex items-center gap-1 ml-auto shrink-0">
+                            {message.durationMs != null && (
+                                <span className="text-xs font-mono text-gray-400">{formatDuration(message.durationMs)}</span>
+                            )}
+                            <CheckCircle2 className="w-3.5 h-3.5 text-green-500" />
+                        </span>
                     )}
                     {message.toolStatus === 'error' && (
-                        <XCircle className="w-3.5 h-3.5 text-red-500 ml-auto shrink-0" />
+                        <span className="flex items-center gap-1 ml-auto shrink-0">
+                            {message.durationMs != null && (
+                                <span className="text-xs font-mono text-gray-400">{formatDuration(message.durationMs)}</span>
+                            )}
+                            <XCircle className="w-3.5 h-3.5 text-red-500" />
+                        </span>
                     )}
                     {message.toolStatus === 'aborted' && (
                         <Ban className="w-3.5 h-3.5 text-amber-500 ml-auto shrink-0" />
diff --git a/src/gateway/web/src/pages/Pilot/index.tsx b/src/gateway/web/src/pages/Pilot/index.tsx
index 58459ab7..9eea5a68 100644
--- a/src/gateway/web/src/pages/Pilot/index.tsx
+++ b/src/gateway/web/src/pages/Pilot/index.tsx
@@ -170,6 +170,7 @@ export function PilotPage() {
                         onNavigateCredentials={() => navigate('/credentials')}
                         sessionKey={pilot.currentSessionKey}
                         isAdmin={isAdmin}
+                        loadingStartedAt={pilot.loadingStartedAt}
                     />
                 </div>
             </div>