@lqc123qwe/car-runtime 1.6.0 → 1.8.0

package/src/runtime-core/trace.ts

@@ -7,6 +7,28 @@
  *    「内容治理属调用方」口径）；设计微调登记：规划原文「runTurn opts.telemetry 注入面」改为装配层
  *    闭包挂点，语义等价（turn/step 层级与出站面不变），loop 层保持纯停止语义；
  *  - attributes 零内容面：turn_id/step 序号/outcome 枚举——无会话内容/提示词/路径。
+ *
+ * 1.7-S3（D-28）：mcp-serve turn span 面——sessionTurn 挂 turn 级 span（无 step span：mcp-serve
+ * 无 model() 循环，step span 面外推登记为不适用）。facade 内部自增派生 turnId（T{n}），装配层
+ * 调用前不可知——TurnSpanHandle 加法 `setTurnId` 回填面（car run 直传 turnId 路径不受影响）；
+ * startTurn('') 空值不设 car.turn_id 属性（回填前出站形态无占位内容）。
+ *
+ * 1.8（D-29/D-30/D-31 · W3C traceparent 跨进程传播）：自研 traceId（16B hex）与 spanId（8B hex）
+ * 格式天然满足 W3C Trace Context（trace-id 32hex / span-id 16hex），1.8 补齐编解码与三边界载体：
+ *  - formatTraceparent/parseTraceparent（D-29）：纯字符串编解码，零依赖；parse 严格校验
+ *    （version 00 / 32hex / 16hex / 全零拒绝），畸形返回 null——**协议面 fail-open**（挂链放弃、
+ *    新 trace，遥测面禁 fail-hard——BD-05 同源）；flags 出站恒 '01'（本端记录中——采样为端点
+ *    本地决策，不跨端传播语义）；
+ *  - mcpToolSpan（D-29）：car run 外呼 MCP 工具的 client span（parent = turn span——step span 已于
+ *    model() 返回时收口，工具执行在 step 外）；attributes car.mcp_server/car.tool 为**登记标识符面**
+ *    （零内容口径扩展：注册表枚举标识，非会话内容）；traceparent 供 gateway.callTool 注入
+ *    params._meta（otel 关 = '' 不注入，线上 JSON-RPC 字节面不变）；
+ *  - startTurn 加法 opts.trace（D-30）：mcp-serve 服务端挂链远端宿主——traceId 复用远端 +
+ *    parentSpanId = 远端 spanId，car.turn span 加入宿主 trace（fail-open：畸形 traceparent 由
+ *    调用方 parse 为 null 后不传，新 trace）；
+ *  - ptcRelay（D-31）：PTC worker 桥挂链——workerTrace 载荷（traceId/parentSpanId）经 workerData
+ *    进隔离体，worker 计时经 done 消息回传后 complete() 主线程单点收口 car.ptc span（facade
+ *    time.startMs/end(atMs) 时刻覆盖；单 exporter 纪律——worker 零独立出站通道）。
  */
 import { randomBytes } from 'node:crypto'
 import type { TelemetryFacade } from './telemetry.ts'
@@ -16,11 +38,53 @@ export interface StepSpanHandle {
   recordException(e: unknown): void
 }
 
+/** 1.8-D29：MCP 外呼 client span 句柄——traceparent = '' 表示无遥测（不注入 _meta） */
+export interface McpClientSpanHandle {
+  readonly traceparent: string
+  end(outcome: string): void
+  recordException(e: unknown): void
+}
+
+/** 1.8-D31：PTC worker 桥挂链句柄——workerTrace=null 表示无遥测（worker 零感知零改动） */
+export interface PtcRelayHandle {
+  readonly workerTrace: { traceId: string; parentSpanId: string } | null
+  /** worker 计时回传收口（主线程单点出站；error 路径 recordException D-26 形态） */
+  complete(startMs: number, endMs: number, outcome: string, error?: unknown): void
+}
+
 export interface TurnSpanHandle {
   traceId: string
   spanId: string
+  /** 1.7-D28：turnId 事后回填（mcp-serve——facade 内部自增派生，调用前不可知；car run 直传不受影响） */
+  setTurnId(turnId: string): void
+  /** 1.7-D28：turn 级异常留痕（D-26 exception 形态在 turn span 同样成立） */
+  recordException(e: unknown): void
   end(outcome: string): void
   stepSpan(step: number): StepSpanHandle
+  /** 1.8-D29：MCP 外呼 client span（parent = turn span；noop 门面 traceparent='' 零注入） */
+  mcpToolSpan(serverId: string, tool: string): McpClientSpanHandle
+  /** 1.8-D31：PTC worker 桥挂链面（noop 门面 workerTrace=null 零载荷） */
+  ptcRelay(): PtcRelayHandle
+}
+
+/** 1.8-D29：W3C traceparent 出站形态（flags '01' = 本端记录中；采样为端点本地决策不跨端传播） */
+export function formatTraceparent(traceId: string, spanId: string): string {
+  return `00-${traceId}-${spanId}-01`
+}
+
+const W3C_TP_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/
+
+/**
+ * 1.8-D29：W3C traceparent 解析——严格校验（version 00 / trace-id 32hex 非 / span-id 16hex 非 / 全零拒绝）。
+ * 畸形返回 null = 挂链放弃（调用方走新 trace——协议面 fail-open，禁 fail-hard）。
+ */
+export function parseTraceparent(tp: string): { traceId: string; parentSpanId: string } | null {
+  const m = W3C_TP_RE.exec(tp.trim())
+  if (!m) return null
+  const traceId = m[1]!
+  const parentSpanId = m[2]!
+  if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId)) return null
+  return { traceId, parentSpanId }
 }
 
 export class TurnTracer {
@@ -31,16 +95,27 @@ export class TurnTracer {
     this.#facade = facade?.enabled ? facade : null
   }
 
-  startTurn(turnId: string): TurnSpanHandle {
+  /** 1.8-D30：opts.trace = 远端挂链（mcp-serve session_turn `_meta.traceparent` 提取后传入；缺省新 trace 不变） */
+  startTurn(turnId: string, opts?: { trace?: { traceId: string; parentSpanId: string } }): TurnSpanHandle {
     if (!this.#facade) {
-      return { traceId: '', spanId: '', end() {}, stepSpan: () => ({ end() {}, recordException() {} }) }
+      return {
+        traceId: '', spanId: '', setTurnId() {}, recordException() {}, end() {},
+        stepSpan: () => ({ end() {}, recordException() {} }),
+        mcpToolSpan: () => ({ traceparent: '', end() {}, recordException() {} }),
+        ptcRelay: () => ({ workerTrace: null, complete() {} }),
+      }
     }
     const tracer = this.#facade.getTracer()
-    const traceId = randomBytes(16).toString('hex')
-    const turn = tracer.startSpan('car.turn', { attributes: { 'car.turn_id': turnId }, trace: { traceId } })
+    const traceId = opts?.trace?.traceId ?? randomBytes(16).toString('hex')
+    const turn = tracer.startSpan('car.turn', {
+      attributes: turnId ? { 'car.turn_id': turnId } : {},
+      trace: { traceId, ...(opts?.trace?.parentSpanId ? { parentSpanId: opts.trace.parentSpanId } : {}) },
+    })
     return {
       traceId,
       spanId: turn.spanId,
+      setTurnId(id) { turn.setAttribute('car.turn_id', id) },
+      recordException(e) { turn.recordException(e) },
       end(outcome) {
         turn.setAttribute('car.outcome', outcome)
         turn.end()
@@ -58,6 +133,38 @@ export class TurnTracer {
           recordException(e) { s.recordException(e) },
         }
       },
+      // 1.8-D29：client span 挂 turn（工具执行在 step span 收口后——turn 为最近存活父）
+      mcpToolSpan(serverId, tool) {
+        const s = tracer.startSpan('car.mcp.tool', {
+          attributes: { 'car.mcp_server': serverId, 'car.tool': tool },
+          trace: { traceId, parentSpanId: turn.spanId },
+        })
+        return {
+          traceparent: formatTraceparent(traceId, s.spanId),
+          end(outcome) {
+            s.setAttribute('car.outcome', outcome)
+            s.end()
+          },
+          recordException(e) { s.recordException(e) },
+        }
+      },
+      // 1.8-D31：worker 侧计时 relay——span 生成收口在主线程（单 exporter 纪律）
+      ptcRelay(): PtcRelayHandle {
+        return {
+          workerTrace: { traceId, parentSpanId: turn.spanId },
+          complete(startMs, endMs, outcome, error) {
+            // 负时长防线（同时钟域不应出现——防御下游转换器语义错乱）
+            const s = tracer.startSpan('car.ptc', {
+              attributes: { 'car.turn_id': turnId },
+              trace: { traceId, parentSpanId: turn.spanId },
+              time: { startMs },
+            })
+            if (error !== undefined) s.recordException(error instanceof Error ? error : new Error(String(error)))
+            s.setAttribute('car.outcome', outcome)
+            s.end(Math.max(endMs, startMs))
+          },
+        }
+      },
     }
   }
 }

package/test/s39-otlp-span-semantics.spec.ts

@@ -0,0 +1,100 @@
+/**
+ * 1.7-S1 · OTLP span 语义标准化（D-26）：exception 标准事件 + status / addEvent 标准 events 编码
+ *
+ * 覆盖（1.7-迭代规划 TELE-1；1.4 遗留「遥测 OTLP 增强」出清主体）：
+ *  - recordException → OTel 规范形态：span event（name='exception'，exception.type/exception.message
+ *    事件属性 + timeUnixNano）+ span status → STATUS_CODE_ERROR——替换 1.1 起「仅 exception.message
+ *    属性 + 恒 UNSET」非标准形态；stacktrace 缺省不出站（D-26 口径：防路径/源码面外泄）
+ *  - addEvent → 标准 events 数组编码（name + 原形态属性 + 时刻）——替换 `event.<name>` JSON 属性串
+ *  - 出站体加法字段：无事件 span 不出 events 键（空形态合法）；正常 span 恒 STATUS_CODE_UNSET（行为不变面）
+ *  - noop 门面零出站不变（默认关三原则；s29/s32 回归由全量保证）
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createTelemetryFacade } from '../src/runtime-core/telemetry.ts'
+
+const okRes = () => ({ ok: true, status: 200 }) as unknown as Response
+
+function capture() {
+  const bodies: any[] = []
+  const f = createTelemetryFacade({ endpoint: 'https://otel' }, {
+    fetchImpl: (async (_u: string | URL, init?: RequestInit) => { bodies.push(JSON.parse(String(init?.body))); return okRes() }) as typeof fetch,
+  })
+  return { f, bodies }
+}
+
+const spansOf = (bodies: any[]) => bodies.filter(b => b.scopeSpans).flatMap(b => b.scopeSpans[0].spans)
+
+test('S39: recordException → 标准 exception 事件 + STATUS_CODE_ERROR（stacktrace 不出站）', async () => {
+  const { f, bodies } = capture()
+  const s = f.getTracer().startSpan('car.step', { attributes: { 'car.step': 1 } })
+  s.recordException(new TypeError('boom'))
+  s.end('error')
+  await f.flush()
+  const span = spansOf(bodies)[0]
+  assert.equal(span.status.code, 'STATUS_CODE_ERROR', 'recordException → status ERROR（1.7 前恒 UNSET）')
+  assert.ok(Array.isArray(span.events) && span.events.length === 1, 'exception 为 span event')
+  const ev = span.events[0]
+  assert.equal(ev.name, 'exception')
+  assert.ok(ev.timeUnixNano, '事件时刻出站')
+  const attrs = Object.fromEntries(ev.attributes.map((a: any) => [a.key, a.value.stringValue]))
+  assert.equal(attrs['exception.type'], 'TypeError', 'err.name → exception.type')
+  assert.equal(attrs['exception.message'], 'boom', 'err.message → exception.message')
+  const allKeys = [...span.attributes, ...span.events.flatMap((e: any) => e.attributes)].map((a: any) => a.key)
+  assert.equal(allKeys.some((k: string) => /stack/i.test(k)), false, 'stacktrace 缺省不出站（D-26）')
+  assert.equal(allKeys.includes('exception.message') && span.attributes.some((a: any) => a.key === 'exception.message'), false,
+    'exception.message 不再落于 span attributes（1.1 非标准形态退役）')
+})
+
+test('S39: recordException 非 Error 值兜底——type=Error / message=String(err)', async () => {
+  const { f, bodies } = capture()
+  const s = f.getTracer().startSpan('car.step')
+  s.recordException('plain failure')
+  s.end('error')
+  await f.flush()
+  const ev = spansOf(bodies)[0].events[0]
+  const attrs = Object.fromEntries(ev.attributes.map((a: any) => [a.key, a.value.stringValue]))
+  assert.deepEqual(attrs, { 'exception.type': 'Error', 'exception.message': 'plain failure' })
+})
+
+test('S39: addEvent → 标准 events 编码（原形态属性 + 时刻；attributes 不再承载事件）', async () => {
+  const { f, bodies } = capture()
+  const s = f.getTracer().startSpan('car.turn')
+  s.addEvent('cache-hit', { key: 'x', n: 1, flag: true })
+  s.end('completed')
+  await f.flush()
+  const span = spansOf(bodies)[0]
+  assert.equal(span.status.code, 'STATUS_CODE_UNSET', '正常 span 恒 UNSET（行为不变面）')
+  assert.equal(span.events.length, 1)
+  const ev = span.events[0]
+  assert.equal(ev.name, 'cache-hit')
+  assert.ok(ev.timeUnixNano)
+  const map = Object.fromEntries(ev.attributes.map((a: any) => [a.key, a.value]))
+  assert.deepEqual(map, { key: { stringValue: 'x' }, n: { doubleValue: 1 }, flag: { boolValue: true } },
+    '原形态属性出站（1.7 前为 event.<name>=JSON 串）')
+  const attrKeys = span.attributes.map((a: any) => a.key)
+  assert.equal(attrKeys.includes('event.cache-hit'), false, 'attributes 不再承载事件（非标准形态退役）')
+})
+
+test('S39: 无事件 span 不出 events 键（出站体加法字段——空形态合法）', async () => {
+  const { f, bodies } = capture()
+  f.getTracer().startSpan('plain').end()
+  await f.flush()
+  const span = spansOf(bodies)[0]
+  assert.equal('events' in span, false, '无事件不出 events 键')
+  assert.equal(span.status.code, 'STATUS_CODE_UNSET')
+})
+
+test('S39: 多事件按序出站（exception 与 addEvent 混排——事件数组保序）', async () => {
+  const { f, bodies } = capture()
+  const s = f.getTracer().startSpan('car.step')
+  s.addEvent('retry')
+  s.recordException(new Error('net'))
+  s.addEvent('fallback')
+  s.end('completed')
+  await f.flush()
+  const names = spansOf(bodies)[0].events.map((e: any) => e.name)
+  assert.deepEqual(names, ['retry', 'exception', 'fallback'])
+  // exception 事件混排下 status 仍 ERROR
+  assert.equal(spansOf(bodies)[0].status.code, 'STATUS_CODE_ERROR')
+})

package/test/s40-metrics-cumulative.spec.ts

@@ -0,0 +1,67 @@
+/**
+ * 1.7-S2 · metrics CUMULATIVE 时序语义修正（D-27）：累计基数保持
+ *
+ * 覆盖（1.7-迭代规划 TELE-2；1.2-S3 起 clear() 与 AGGREGATION_TEMPORALITY_CUMULATIVE 标注矛盾出清）：
+ *  - 同计数器双 flush：第二次导出仍为全量累计（5 → 7），非增量（5 → 2）——真 CUMULATIVE；
+ *    intervalMs>0 自动导出场景下下游（Prometheus 转换器等）不再解读为总量回落；
+ *  - labels 形态与 temporality 标注不变；DELTA 备选不采纳（D-27：生态主流 + S17 计数语义即累计）；
+ *  - 内存有界由 label 基数保证（零内容枚举红线——AllowedLabels 3 计数器）。
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createTelemetryFacade } from '../src/runtime-core/telemetry.ts'
+
+const okRes = () => ({ ok: true, status: 200 }) as unknown as Response
+
+test('S40: 累计基数保持——同计数器双 flush 导出全量累计快照（真 CUMULATIVE，非增量）', async () => {
+  const bodies: any[] = []
+  const f = createTelemetryFacade({ endpoint: 'https://otel' }, {
+    fetchImpl: (async (_u: string | URL, init?: RequestInit) => { bodies.push(JSON.parse(String(init?.body))); return okRes() }) as typeof fetch,
+  })
+  const c = f.getMeter().createCounter('car_test_total')
+  c.add(5, { result: 'ok' })
+  await f.flush()
+  c.add(2, { result: 'ok' })
+  await f.flush()
+  assert.equal(bodies.length, 2, '两次 flush 各一次 metrics 出站')
+  const values = bodies.map(b => b.scopeMetrics[0].metrics[0].sum.dataPoints[0].asInt)
+  assert.deepEqual(values, [5, 7], '第二次导出 = 累计 7（1.7 前为增量 2——CUMULATIVE 语义错误）')
+  for (const b of bodies) {
+    const m = b.scopeMetrics[0].metrics[0]
+    assert.equal(m.name, 'car_test_total')
+    assert.equal(m.sum.aggregationTemporality, 'AGGREGATION_TEMPORALITY_CUMULATIVE')
+    const dp = m.sum.dataPoints[0]
+    assert.equal(dp.attributes[0].key, 'result', 'labels 形态不变')
+    assert.equal(dp.attributes[0].value.stringValue, 'ok')
+  }
+  assert.equal(f.stats().metricsExported, 2)
+})
+
+test('S40: 无新增计数 interval 下重复 flush——全量快照幂等重出（CUMULATIVE 口径正确形态）', async () => {
+  const bodies: any[] = []
+  const f = createTelemetryFacade({ endpoint: 'https://otel' }, {
+    fetchImpl: (async (_u: string | URL, init?: RequestInit) => { bodies.push(JSON.parse(String(init?.body))); return okRes() }) as typeof fetch,
+  })
+  f.getMeter().createCounter('car_load_total').add(3, { result: 'ok' })
+  await f.flush()
+  await f.flush()
+  const values = bodies.map(b => b.scopeMetrics[0].metrics[0].sum.dataPoints[0].asInt)
+  assert.deepEqual(values, [3, 3], '无新增 = 同值重出（累计快照，非清零/缺席）')
+})
+
+test('S40: 多计数器并存——各自独立累计（互不串值）', async () => {
+  const bodies: any[] = []
+  const f = createTelemetryFacade({ endpoint: 'https://otel' }, {
+    fetchImpl: (async (_u: string | URL, init?: RequestInit) => { bodies.push(JSON.parse(String(init?.body))); return okRes() }) as typeof fetch,
+  })
+  const c1 = f.getMeter().createCounter('car_load_total')
+  const c2 = f.getMeter().createCounter('car_registry_decision')
+  c1.add(1, { result: 'ok' })
+  c2.add(2, { source: 'registry' })
+  c1.add(1, { result: 'ok' })
+  await f.flush()
+  const metrics = bodies[0].scopeMetrics[0].metrics
+  assert.equal(metrics.length, 2)
+  const byName = Object.fromEntries(metrics.map((m: any) => [m.name, m.sum.dataPoints[0].asInt]))
+  assert.deepEqual(byName, { car_load_total: 2, car_registry_decision: 2 })
+})

package/test/s41-mcp-serve-turn-span.spec.ts

@@ -0,0 +1,148 @@
+/**
+ * 1.7-S3 · mcp-serve turn span 面（D-28）：sessionTurn 挂 turn 级 span（装配层拦截）
+ *
+ * 覆盖（1.7-迭代规划 TELE-3；1.2-S3「span 面随 W1」mcp-serve 半边出清）：
+ *  - spawn E2E：mcp-serve 真进程 + 本地 http 捕获端点——session_turn 产 car.turn span 出站
+ *    （car.turn_id=T1 回填〔facade 内部自增派生，装配层调用前不可知〕/ outcome=归一化 reason /
+ *    traceId 生成 / parentSpanId 缺席=根 span）；turn span 落 /v1/traces；
+ *  - 非会话工具（session_start）不产 span——拦截面仅 session_turn（D-28 口径）；
+ *  - 既有 meter 桥与 S17 快照面不受影响（s29 全量回归保证）；遥测审计禁混流红线（静态断言）s29 保持。
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { createServer, type Server } from 'node:http'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { deriveSessionId } from '../src/host/mappings.ts'
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'cli.ts')
+
+function withTempDir(name: string, fn: (dir: string) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), `car-s41-${name}-`))
+  return fn(dir).finally(() => { try { rmSync(dir, { recursive: true, force: true }) } catch { /* 红线 8 */ } })
+}
+
+test('S41: spawn E2E——mcp-serve sessionTurn → car.turn span 出站（turnId 回填 / outcome=reason）', async () => {
+  await withTempDir('e2e', async dir => {
+    const traceBodies: any[] = []
+    let done: (v: void) => void = () => {}
+    const closed = new Promise<void>(r => { done = r })
+    const server: Server = createServer((req, res) => {
+      let body = ''
+      req.on('data', c => { body += c })
+      req.on('end', () => {
+        if (req.url === '/v1/traces') traceBodies.push(JSON.parse(body))
+        res.writeHead(200).end()
+      })
+    })
+    await new Promise<void>(r => server.listen(0, '127.0.0.1', r))
+    const port = (server.address() as { port: number }).port
+    try {
+      const child = spawn(process.execPath, ['--experimental-transform-types', CLI, 'mcp-serve'], {
+        cwd: dir,
+        env: { ...process.env, CAR_OTEL_ENDPOINT: `http://127.0.0.1:${port}`, CAR_OTEL_INTERVAL_MS: '0' },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+      let err = ''
+      child.stderr.on('data', d => { err += d })
+      // 确定性派生（s36 同款）：session_start 返回的 CAR 会话 id 进程内预计算——双请求可并发下发
+      const sid = deriveSessionId('claude-code', 's41-span')
+      child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'session_start', arguments: { hostSessionId: 's41-span' } } }) + '\n')
+      child.stdin.write(JSON.stringify({
+        jsonrpc: '2.0', id: 2, method: 'tools/call',
+        params: {
+          name: 'session_turn',
+          arguments: { sessionId: sid, input: { events: [{ hostEvent: 'user_message', payload: { content: 'hi' } }, { hostEvent: 'turn_complete' }] } },
+        },
+      }) + '\n')
+      child.stdin.end()
+      child.on('exit', () => done())
+      // macOS runner 慢启动容差（s29 同款）；落选 race timer 必须 clear
+      let raceTimer: ReturnType<typeof setTimeout> | undefined
+      try {
+        await Promise.race([
+          closed,
+          new Promise<never>((_, rej) => { raceTimer = setTimeout(() => rej(new Error(`mcp-serve 超时\n${err}`)), 60_000) }),
+        ])
+      } finally {
+        if (raceTimer) clearTimeout(raceTimer)
+      }
+      const spans = traceBodies.flatMap(b => b.scopeSpans[0].spans)
+      const turnSpan = spans.find(s => s.name === 'car.turn')
+      assert.ok(turnSpan, 'session_turn 产 car.turn span 出站（v1/traces 面可达）')
+      const attrs = Object.fromEntries(turnSpan.attributes.map((a: any) => [a.key, a.value.stringValue]))
+      assert.equal(attrs['car.turn_id'], 'T1', 'turnId 事后回填（facade 内部自增派生）')
+      assert.equal(attrs['car.outcome'], 'completed', 'outcome = 归一化 turnEnd reason')
+      assert.ok(turnSpan.traceId && turnSpan.spanId, 'traceId/spanId 生成')
+      assert.equal('parentSpanId' in turnSpan, false, '根 span 无 parent')
+      assert.equal('events' in turnSpan, false, '正常路径无 exception 事件')
+      assert.equal(turnSpan.status.code, 'STATUS_CODE_UNSET')
+      // 非会话工具（session_start）不产 span——拦截面仅 session_turn（D-28）
+      assert.equal(spans.length, 1, '单 session_turn = 单 turn span（session_start 不产 span）')
+      // 零内容口径：span 出站体无会话内容（user_message payload 不出站）
+      assert.equal(/hi|user_message/.test(JSON.stringify(traceBodies)), false, 'span 出站体零内容（事件批内容不出站）')
+    } finally {
+      server.closeAllConnections()
+      server.close()
+    }
+  })
+})
+
+test('S41: session_turn 未知会话显式报错——span 收口 error + exception 事件出站', async () => {
+  await withTempDir('err', async dir => {
+    const traceBodies: any[] = []
+    let done: (v: void) => void = () => {}
+    const closed = new Promise<void>(r => { done = r })
+    const server: Server = createServer((req, res) => {
+      let body = ''
+      req.on('data', c => { body += c })
+      req.on('end', () => {
+        if (req.url === '/v1/traces') traceBodies.push(JSON.parse(body))
+        res.writeHead(200).end()
+      })
+    })
+    await new Promise<void>(r => server.listen(0, '127.0.0.1', r))
+    const port = (server.address() as { port: number }).port
+    try {
+      const child = spawn(process.execPath, ['--experimental-transform-types', CLI, 'mcp-serve'], {
+        cwd: dir,
+        env: { ...process.env, CAR_OTEL_ENDPOINT: `http://127.0.0.1:${port}`, CAR_OTEL_INTERVAL_MS: '0' },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+      let err = ''
+      child.stderr.on('data', d => { err += d })
+      child.on('exit', () => done())
+      child.stdin.write(JSON.stringify({
+        jsonrpc: '2.0', id: 1, method: 'tools/call',
+        params: { name: 'session_turn', arguments: { sessionId: 'SH-nonexistent', input: { events: [] } } },
+      }) + '\n')
+      child.stdin.end()
+      let raceTimer: ReturnType<typeof setTimeout> | undefined
+      try {
+        await Promise.race([
+          closed,
+          new Promise<never>((_, rej) => { raceTimer = setTimeout(() => rej(new Error(`mcp-serve 超时\n${err}`)), 60_000) }),
+        ])
+      } finally {
+        if (raceTimer) clearTimeout(raceTimer)
+      }
+      const spans = traceBodies.flatMap(b => b.scopeSpans[0].spans)
+      const turnSpan = spans.find(s => s.name === 'car.turn')
+      assert.ok(turnSpan, '失败路径 turn span 仍出站')
+      assert.equal(turnSpan.status.code, 'STATUS_CODE_ERROR', 'handle 异常 → status ERROR')
+      const ev = turnSpan.events?.find((e: any) => e.name === 'exception')
+      assert.ok(ev, 'exception 事件出站（D-26 形态在 mcp-serve 路径成立）')
+      const evAttrs = Object.fromEntries(ev.attributes.map((a: any) => [a.key, a.value.stringValue]))
+      assert.match(evAttrs['exception.message'] ?? '', /CAR-E-HOST/, '异常消息进 exception.message（内容治理属调用方）')
+      const attrs = Object.fromEntries(turnSpan.attributes.map((a: any) => [a.key, a.value.stringValue]))
+      assert.equal(attrs['car.outcome'], 'error')
+      assert.equal('car.turn_id' in attrs, false, '回填前失败：无占位 turnId（startTurn(\'\') 空值不设属性）')
+    } finally {
+      server.closeAllConnections()
+      server.close()
+    }
+  })
+})