@lqc123qwe/car-runtime 1.3.0 → 1.5.0

package/src/runtime-core/telemetry.ts

@@ -4,7 +4,8 @@
  * 口径（§3.2.M8.5 关键约束，逐条落地）：
  *  - 默认关：无端点配置时不初始化任何 exporter——无配置 = noop 句柄 + 零出站（可机器断言）；
  *  - 显式开：用户配置端点即视为开启（CAR_OTEL_ENDPOINT 或显式 config 传入）；
- *  - 端点归用户：数据只发往用户自配 E-05；OTLP/HTTP JSON（fetch），导出超时 5s；
+ *  - 端点归用户：数据只发往用户自配 E-05；OTLP/HTTP JSON（node:http(s) 出站——1.4-BUG-2：全局
+ *    fetch/undici 在 win32 进程退出时触发 libuv 断言崩溃），导出超时 5s；
  *    1.2-S3 生产级策略（D-12b 口径修订，2026-09-27）：**0 重试 → 有界重试 ≤2**（仅 429/5xx/
  *    网络错误，退避 1s/2s；4xx 业务错不重试）——重试耗尽静默丢弃 + droppedExports 计数，
  *    永不抛错（BD-05「不抛错、不落审计」收紧保持）；隐私三原则不变（数据仍只发用户自配端点）；
@@ -22,6 +23,8 @@
  *    不引入 @opentelemetry/* 依赖（项目零依赖红线，README engines 纪律）。
  */
 import { randomBytes } from 'node:crypto'
+import { request as httpRequest } from 'node:http'
+import { request as httpsRequest } from 'node:https'
 
 export type SamplingSpec = 'always_on' | 'always_off' | { ratio: number }
 
@@ -55,10 +58,16 @@ export interface TelemetrySpan {
   recordException(err: unknown): this
   end(): void
   readonly traceId: string
+  /** 1.4-S6：子 span 挂链需要父 spanId（TurnTracer turn→step 层级） */
+  readonly spanId: string
 }
 
 export interface TelemetryTracer {
-  startSpan(name: string, opts?: { attributes?: Record<string, string | number | boolean> }): TelemetrySpan
+  startSpan(name: string, opts?: {
+    attributes?: Record<string, string | number | boolean>
+    /** 1.4-S6：trace 透传（traceId 复用 + parentSpanId 挂链）；缺省 = 新独立 trace */
+    trace?: { traceId: string; parentSpanId?: string }
+  }): TelemetrySpan
 }
 
 export interface TelemetryCounter {
@@ -102,6 +111,7 @@ const noopSpan = (): TelemetrySpan => ({
   recordException() { return noopSpan() },
   end() {},
   traceId: '',
+  spanId: '',
 })
 const NOOP_TRACER: TelemetryTracer = { startSpan: () => noopSpan() }
 const NOOP_METER: TelemetryMeter = { createCounter: () => ({ add() {} }) }
@@ -164,7 +174,25 @@ export function createTelemetryFacade(
     }
   }
 
-  const fetchImpl = opts.fetchImpl ?? fetch
+  // 1.4-BUG-2：出站默认走 node:http(s)（非全局 fetch/undici）——win32 上 undici socket +
+  // 进程退出触发 libuv 断言崩溃（UV_HANDLE_CLOSING, 0xC0000409，Node 23.5 实测、22 不复现）；
+  // 测试仍可注入 fetchImpl（缝保留）。res.resume() 排空响应体（连接干净归还）。
+  const fetchImpl = opts.fetchImpl ?? ((url: string | URL, init?: RequestInit): Promise<{ ok: boolean; status: number }> => new Promise(resolve => {
+    try {
+      const u = String(url)
+      const mod = u.startsWith('https:') ? httpsRequest : httpRequest
+      const req = mod(u, { method: init?.method ?? 'GET', headers: init?.headers as Record<string, string> | undefined }, res => {
+        res.resume()
+        res.on('end', () => {
+          const st = res.statusCode ?? 0
+          resolve({ ok: st >= 200 && st < 300, status: st })
+        })
+      })
+      req.setTimeout(timeoutMs, () => req.destroy(new Error('timeout')))
+      req.on('error', () => resolve({ ok: false, status: 599 })) // 网络/超时错误 → 599 可重试类
+      req.end(init?.body ?? null)
+    } catch { resolve({ ok: false, status: 599 }) }
+  }))
   const now = opts.now ?? Date.now
   const sleep = config?.sleep ?? (ms => new Promise<void>(r => setTimeout(r, ms)))
   const timeoutMs = config?.exportTimeoutMs ?? 5_000
@@ -194,12 +222,16 @@ export function createTelemetryFacade(
    */
   const exportOtlp = async (path: string, body: unknown): Promise<boolean> => {
     for (let attempt = 0; ; attempt++) {
+      // 1.4-BUG-2：AbortSignal.timeout 的内部定时器在进程退出时触发 libuv win32 断言崩溃
+      // （UV_HANDLE_CLOSING, 0xC0000409）——改手动 AbortController + clearTimeout 确定性清理
+      const controller = new AbortController()
+      const abortTimer = setTimeout(() => controller.abort(), timeoutMs)
       try {
         const res = await fetchImpl(endpoint + path, {
           method: 'POST',
           headers: baseHeaders,
           body: JSON.stringify(body),
-          signal: AbortSignal.timeout(timeoutMs),
+          signal: controller.signal,
         })
         if (res.ok) return true
         if ((res.status === 429 || res.status >= 500) && attempt < retryLimit) {
@@ -214,6 +246,8 @@ export function createTelemetryFacade(
           continue
         }
         return false
+      } finally {
+        clearTimeout(abortTimer)
       }
     }
   }
@@ -277,9 +311,10 @@ export function createTelemetryFacade(
   const activeTracer: TelemetryTracer = {
     startSpan(name, startOpts) {
       const record: SpanRecord = {
-        traceId: randomBytes(16).toString('hex'),
+        // 1.4-S6：trace 透传（traceId 复用 + parentSpanId 挂链）——缺省仍为独立随机 trace（1.1 行为不变）
+        traceId: startOpts?.trace?.traceId ?? randomBytes(16).toString('hex'),
         spanId: randomBytes(8).toString('hex'),
-        parentSpanId: null,
+        parentSpanId: startOpts?.trace?.parentSpanId ?? null,
         name,
         startMs: now(),
         endMs: 0,
@@ -287,6 +322,7 @@ export function createTelemetryFacade(
       }
       return {
         get traceId() { return record.traceId },
+        get spanId() { return record.spanId },
         setAttribute(key, value) { record.attributes[key] = value; return this },
         addEvent(evtName, attrs) { record.attributes[`event.${evtName}`] = attrs ? JSON.stringify(attrs) : evtName; return this },
         recordException(err) { record.attributes['exception.message'] = String((err as Error)?.message ?? err); return this },

package/src/runtime-core/tools.ts

@@ -0,0 +1,27 @@
+/**
+ * 1.4-S1 · 工具声明面转换（执行面 Map → 模型声明面 ToolDefinition[]）
+ *
+ * 口径（1.4 规划 W1-3 / D-18 / T-22 / 声明面=授权面红线）：
+ *  - **执行面与声明面同一对象**：ToolDef（loop/stop.ts，declaredSideEffect+run）即声明来源——
+ *    插件注册的 ToolReg 经 bindCore 收集后直接进本转换器，模型看到的工具集合 = 授权门放行的集合
+ *    （多渲一个 = 无授权执行面，少渲一个 = 授权白给——PTC SDK 同款红线）；
+ *  - T-22 收口：declaredSideEffect 缺省 write（未声明按最高约束——mcp/gateway.ts 注册点同款）；
+ *  - 跨源同名显式报错（禁静默覆盖）：Map 键即名字，插件/MCP 工具合并由调用方先行去重——
+ *    本转换器对重名（Map 键重复不可能，但 ToolDef.name 与键不一致时）显式报错；
+ *  - declaredSideEffect 不出站（llm.ts 出站映射只带 name/description/parameters——权限面只进权限门）。
+ */
+import type { ToolDef } from '../loop/stop.ts'
+import type { ToolDefinition } from './types.ts'
+
+export function toToolDefinitions(tools: Map<string, ToolDef>): ToolDefinition[] {
+  const out: ToolDefinition[] = []
+  for (const [name, t] of tools) {
+    out.push({
+      name,
+      ...(t.description !== undefined ? { description: t.description } : {}),
+      ...(t.parameters !== undefined ? { parameters: t.parameters } : {}),
+      declaredSideEffect: t.declaredSideEffect ?? 'write',
+    })
+  }
+  return out
+}

package/src/runtime-core/trace.ts

@@ -0,0 +1,63 @@
+/**
+ * 1.4-S6 · Turn 级 trace 面（W1 遥测未入链收尾）：turn span 包全程、step span 挂每次 model() 调用
+ *
+ * 口径（1.4 规划 W1 遥测块 / telemetry.ts 头注释）：
+ *  - 层级：turn（根 span，traceId 在此生成）→ step（parentSpanId = turn.spanId）——同一 turn 共享 trace；
+ *  - **挂点在装配层**（car run 的 model 回调闭包），loop 层零改动——遥测治理属调用方（telemetry.ts
+ *    「内容治理属调用方」口径）；设计微调登记：规划原文「runTurn opts.telemetry 注入面」改为装配层
+ *    闭包挂点，语义等价（turn/step 层级与出站面不变），loop 层保持纯停止语义；
+ *  - attributes 零内容面：turn_id/step 序号/outcome 枚举——无会话内容/提示词/路径。
+ */
+import { randomBytes } from 'node:crypto'
+import type { TelemetryFacade } from './telemetry.ts'
+
+export interface StepSpanHandle {
+  end(outcome: string): void
+  recordException(e: unknown): void
+}
+
+export interface TurnSpanHandle {
+  traceId: string
+  spanId: string
+  end(outcome: string): void
+  stepSpan(step: number): StepSpanHandle
+}
+
+export class TurnTracer {
+  readonly #facade: TelemetryFacade | null
+
+  constructor(facade: TelemetryFacade | null | undefined) {
+    // 默认关（无端点）= noop 句柄（零出站零积累——telemetry 三原则）
+    this.#facade = facade?.enabled ? facade : null
+  }
+
+  startTurn(turnId: string): TurnSpanHandle {
+    if (!this.#facade) {
+      return { traceId: '', spanId: '', end() {}, stepSpan: () => ({ end() {}, recordException() {} }) }
+    }
+    const tracer = this.#facade.getTracer()
+    const traceId = randomBytes(16).toString('hex')
+    const turn = tracer.startSpan('car.turn', { attributes: { 'car.turn_id': turnId }, trace: { traceId } })
+    return {
+      traceId,
+      spanId: turn.spanId,
+      end(outcome) {
+        turn.setAttribute('car.outcome', outcome)
+        turn.end()
+      },
+      stepSpan(step: number): StepSpanHandle {
+        const s = tracer.startSpan('car.step', {
+          attributes: { 'car.turn_id': turnId, 'car.step': step },
+          trace: { traceId, parentSpanId: turn.spanId },
+        })
+        return {
+          end(outcome) {
+            s.setAttribute('car.outcome', outcome)
+            s.end()
+          },
+          recordException(e) { s.recordException(e) },
+        }
+      },
+    }
+  }
+}

package/src/runtime-core/types.ts

@@ -19,9 +19,12 @@ export interface LlmRequest {
   tools: ToolDefinition[]
   maxTokens?: number
   metadata?: { sessionId: string; turnId: string; traceId: string }
-  // —— 规格外加法扩展（登记：M8 收口文档 §4）——
+  // —— 规格外加法扩展（登记：M8 收口文档 §4 / 1.4-S4）——
   /** 多适配器在册时显式路由；缺省用默认适配器 */
   adapterId?: string
+  /** 1.4-S4（D-19）：turn 取消信号（runTurn 的 {aborted} 形态透传）——适配器在 attempt 前 /
+   *  chunk 间隙检查；外部取消 ≠ 失败（不 retry、不产 error chunk，静默收口由 chatStep 抛 TurnAborted） */
+  signal?: { aborted: boolean }
 }
 
 /** 工具调用流式增量（跨 chunk 聚合出完整 ToolCall） */

package/src/session/log.ts

@@ -10,7 +10,7 @@ import { createHash } from 'node:crypto'
 import { readFileSync } from 'node:fs'
 import { decodeLogBuffer, splitJsonlLines } from './format.ts'
 
-export type EventKind = 'user' | 'assistant' | 'toolCall' | 'toolResult' | 'turnEnd' | 'goalUpdate' | 'hostRaw' | 'fork' // M3-S11 加法扩展：多宿主归一化降级通道（pattern 未命中留痕，零静默）；M5-DEC4 加法扩展：跨宿主 fork 标记事件；六值 TurnEndReason 不变
+export type EventKind = 'user' | 'assistant' | 'toolCall' | 'toolResult' | 'turnEnd' | 'goalUpdate' | 'hostRaw' | 'fork' | 'system' // M3-S11 加法扩展：多宿主归一化降级通道（pattern 未命中留痕，零静默）；M5-DEC4 加法扩展：跨宿主 fork 标记事件；1.4-S2 加法扩展：system prompt 落链（§3.5.5：新模型可见输入 = 新事件类型）；六值 TurnEndReason 不变
 export type Actor = 'user' | 'model' | 'plugin' | 'runtime'
 export interface SessionEvent {
   seq: number
@@ -88,7 +88,8 @@ export class SessionLog {
     const out: Array<{ role: string; [k: string]: unknown }> = []
     for (const e of this.events) {
       if (upTo !== undefined && e.seq >= upTo) break
-      if (e.kind === 'user') out.push({ role: 'user', content: e.payload })
+      if (e.kind === 'system') out.push({ role: 'system', content: e.payload })
+      else if (e.kind === 'user') out.push({ role: 'user', content: e.payload })
       else if (e.kind === 'assistant') out.push({ role: 'assistant', content: e.payload })
       else if (e.kind === 'toolCall') out.push({ role: 'assistant', toolCall: e.payload })
       else if (e.kind === 'toolResult') out.push({ role: 'toolResult', content: e.payload })

package/test/contract/eventmap.golden.json

@@ -1,6 +1,6 @@
 {
   "comment": "J-09 contract 基线：SessionEventMap/SessionEvent 签名字段集。只增不删——本文件中任何键从 src/session/log.ts 的当前签名中消失即 FAIL（M2部署设计增补 §2.3 J-09）",
-  "eventKinds": ["user", "assistant", "toolCall", "toolResult", "turnEnd", "goalUpdate", "hostRaw", "fork"],
+  "eventKinds": ["user", "assistant", "toolCall", "toolResult", "turnEnd", "goalUpdate", "hostRaw", "fork", "system"],
   "actors": ["user", "model", "plugin", "runtime"],
   "sessionEventFields": ["seq", "ts", "actor", "kind", "turnId", "payload", "meta", "prevHash", "hash"],
   "sessionLogApi": ["append", "snapshotModelRequest", "verifyChain", "deriveMessages", "assertModelVisibleLogged", "stats", "fromEvents", "exportJSONL"]

package/test/s26-signature-closeout.spec.ts

@@ -273,7 +273,7 @@ test('S26: CLI 配置通道真实消费——car run 经 car.config.json 走 enf
     assert.equal(r1.code, 1)
     assert.match(r1.stderr, /签名门禁拒绝.*signature missing/)
     // env 显式 0 压过配置 → warn 放行到装配段
-    const r2 = await car(['run', 'plugin.ts'], { cwd: dir, env: { CAR_SIG_ENFORCE: '0' } })
+    const r2 = await car(['run', 'plugin.ts', '--demo'], { cwd: dir, env: { CAR_SIG_ENFORCE: '0' } })  // 1.4 D-13：stub 流挂 --demo
     assert.equal(r2.code, 0, r2.stderr)
     assert.match(r2.stdout, /\[1\/5 装配\] OK/)
     // 坏配置 fail-visible 中止（exit 2，不进入装载）

package/test/s28-session-index-followup.spec.ts

@@ -213,7 +213,7 @@ test('S28: 生产调用点——car run 真进程 append → cwd sessions-index.
     // 工具名避开 demo_tool：CLI 演示脚手架硬编码注册 demo_tool，同名插件工具触发预存在的 provide
     // 撞名边缘（登记不修——W1 重做 car run 装配面时出清）
     writeFileSync(join(dir, 'p.ts'), `export const manifest = { name: 'p', version: '1.0.0' }\nexport default function apply(api) {\n  api.registerTool({ name: 't', run: async () => 'ok' })\n}\n`)
-    const r = await car(['run', 'p.ts'], { cwd: dir })
+    const r = await car(['run', 'p.ts', '--demo'], { cwd: dir })  // 1.4 D-13：stub 流挂 --demo
     assert.equal(r.code, 0, r.stderr)
     const dbPath = join(dir, 'sessions-index.db')
     assert.ok(existsSync(dbPath), 'car run 运行后 cwd 索引自举在位')

package/test/s31-real-model-wiring.spec.ts

@@ -0,0 +1,329 @@
+/**
+ * 1.4-S1~S5 · 真实模型接线（S31）：声明面统一 / system 落链 / llm.* 配置 / loopback 豁免 /
+ * 取消透传 / CarM8Error 保形 / car run 装配重做（D-13）+ 多步真 E2E
+ *
+ * 覆盖（1.4-迭代规划 W1-1~W1-7）：
+ *  - toToolDefinitions：schema 透传 / T-22 缺省 write 收口
+ *  - 'system' 事件：投影 role:'system'（§3.5.5 新可见输入 = 新事件类型）
+ *  - llm.* 配置：校验 fail-visible / 优先级 flag > env > config / CAR_LLM_* env
+ *  - D-12a：http loopback 豁免（127.0.0.1/localhost/[::1]）+ 非 loopback http 拒绝
+ *  - 取消（D-19）：TurnAborted 首次实抛（finish 检查前序）+ runTurn 收口 aborted
+ *  - CarM8Error 保形：A080001 userHint/retryable 到 turnEnd
+ *  - 多步真 E2E：本地 loopback 假 SSE 服务——system 出站 / 工具 schema 出站 / Bearer 凭据 /
+ *    第二请求含 toolResult / 声明面=授权面；car run spawn 全链 + 无配置 exit 2
+ */
+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, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { toToolDefinitions } from '../src/runtime-core/tools.ts'
+import { createOpenAICompatAdapter, RuntimeCore } from '../src/runtime-core/llm.ts'
+import { chatStep } from '../src/runtime-core/chatStep.ts'
+import { CredentialService } from '../src/runtime-core/credentials.ts'
+import { runTurn } from '../src/loop/stop.ts'
+import { Context } from '../src/kernel/context.ts'
+import { SessionLog } from '../src/session/log.ts'
+import { mergeLlmConfig, loadCarConfig } from '../src/load/config.ts'
+import { doctorModelReadiness } from '../src/dx/doctor.ts'
+
+// 密钥扫描口径（generic-secret-assign）：夹具凭据经变量注入（赋值行无引号字面量）；值非真实凭据
+const TEST_KEY = 'test-key-123'
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'cli.ts')
+
+function withTempDir(name: string, fn: (dir: string) => Promise<void> | void): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), `car-s31-${name}-`))
+  try {
+    const r = fn(dir)
+    const cleanup = () => { try { rmSync(dir, { recursive: true, force: true }) } catch { /* 红线 8 */ } }
+    if (r instanceof Promise) return r.finally(cleanup)
+    cleanup()
+    return Promise.resolve()
+  } catch (e) {
+    try { rmSync(dir, { recursive: true, force: true }) } catch { /* 红线 8 */ }
+    throw e
+  }
+}
+
+/** SSE 流响应（openai-compat 形态） */
+function sse(chunks: object[]): string {
+  return chunks.map(c => `data: ${JSON.stringify(c)}\n\n`).join('') + 'data: [DONE]\n\n'
+}
+
+const TOOL_CALL_SSE = (name: string, argsJson: string, id: string) => sse([
+  { choices: [{ delta: { role: 'assistant', content: '' } }] },
+  { choices: [{ delta: { tool_calls: [{ index: 0, id, function: { name, arguments: argsJson.slice(0, 3) } }] } }] },
+  { choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: argsJson.slice(3) } }] } }] },
+  { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
+])
+const TEXT_SSE = (text: string) => sse([
+  { choices: [{ delta: { role: 'assistant', content: '' } }] },
+  { choices: [{ delta: { content: text } }] },
+  { choices: [{ delta: {}, finish_reason: 'stop' }] },
+])
+
+/** 本地假 OpenAI 兼容服务：捕获请求体，按脚本回放 SSE */
+function fakeOpenAI(script: Array<(body: any) => string>): Promise<{ server: Server; url: string; bodies: any[]; headers: any[]; done: Promise<void> }> {
+  const bodies: any[] = []
+  const headers: any[] = []
+  let idx = 0
+  let finish: (v: void) => void = () => {}
+  const done = new Promise<void>(r => { finish = r })
+  const server = createServer((req, res) => {
+    let raw = ''
+    req.on('data', c => { raw += c })
+    req.on('end', () => {
+      bodies.push(JSON.parse(raw))
+      headers.push(req.headers)
+      res.writeHead(200, { 'content-type': 'text/event-stream' })
+      const step = script[Math.min(idx, script.length - 1)]
+      idx++
+      res.end(step(bodies[bodies.length - 1]))
+      if (idx >= script.length) finish()
+    })
+  })
+  const url = new Promise<string>(r => server.listen(0, '127.0.0.1', () => r(`http://127.0.0.1:${(server.address() as { port: number }).port}/v1`)))
+  return url.then(u => ({ server, url: u, bodies, headers, done }))
+}
+
+// ==================== S1：声明面统一 ====================
+
+test('S31: toToolDefinitions——description/parameters 透传 + T-22 缺省 write 收口 + 声明面=授权面', () => {
+  const map = new Map<string, any>([
+    ['full', { declaredSideEffect: 'readonly' as const, run: async () => 1, description: '读工具', parameters: { type: 'object', properties: { q: { type: 'string' } } } }],
+    ['bare', { declaredSideEffect: 'write' as const, run: async () => 2 }],
+  ])
+  const defs = toToolDefinitions(map)
+  assert.deepEqual(defs, [
+    { name: 'full', description: '读工具', parameters: { type: 'object', properties: { q: { type: 'string' } } }, declaredSideEffect: 'readonly' },
+    { name: 'bare', declaredSideEffect: 'write' },
+  ])
+  // declaredSideEffect 不出站的口径由 llm.ts 出站映射承载（llm.ts:237 只带 name/description/parameters）
+})
+
+// ==================== S2：system 落链 ====================
+
+test('S31: system 事件——落链 → deriveMessages 投影 role:system（§3.5.5 新可见输入 = 新事件类型）', () => {
+  const log = new SessionLog('S-sys-1')
+  log.append('runtime', 'system', 'system', '你是测试助手')
+  log.append('user', 'user', 'T0', 'hi')
+  const msgs = log.deriveMessages()
+  assert.deepEqual(msgs[0], { role: 'system', content: '你是测试助手' })
+  assert.equal(log.verifyChain(), null, '哈希链含 system 事件仍完整')
+  assert.equal(log.assertModelVisibleLogged().ok, true, 'N1 含 system 事件成立')
+})
+
+// ==================== S3：llm.* 配置通道 ====================
+
+test('S31: llm.* 配置——校验 fail-visible / 优先级 flag > env > config / CAR_LLM_* env 通道', () => {
+  withTempDir('llm-config', dir => {
+    // 未知键 / 类型错 fail-visible
+    writeFileSync(join(dir, 'bad.json'), JSON.stringify({ llm: { temperature: 0.7 } }))
+    assert.match(loadCarConfig({ explicitPath: join(dir, 'bad.json') }).error!, /未知键 llm\.temperature/)
+    writeFileSync(join(dir, 'bad2.json'), JSON.stringify({ llm: { maxTokens: 1.5 } }))
+    assert.match(loadCarConfig({ explicitPath: join(dir, 'bad2.json') }).error!, /llm\.maxTokens 必须为正整数/)
+    // 有效配置
+    const good = join(dir, 'good.json')
+    writeFileSync(good, JSON.stringify({ llm: { baseUrl: 'https://cfg.example/v1', model: 'cfg-model', maxTokens: 100, allowEnvFallback: true } }))
+    const cfg = loadCarConfig({ explicitPath: good }).config
+    // 优先级：config < env < flag
+    const c = mergeLlmConfig({}, cfg)
+    assert.equal(c.baseUrl, 'https://cfg.example/v1')
+    assert.equal(c.model, 'cfg-model')
+    assert.equal(c.allowEnvFallback, true)
+    const e = mergeLlmConfig({ CAR_LLM_BASE_URL: 'https://env.example/v1', CAR_LLM_MODEL: 'env-model' }, cfg)
+    assert.equal(e.baseUrl, 'https://env.example/v1')
+    assert.equal(e.model, 'env-model')
+    const f = mergeLlmConfig({ CAR_LLM_MODEL: 'env-model' }, cfg, { baseUrl: 'https://flag.example/v1', model: 'flag-model', maxTokens: 7 })
+    assert.equal(f.baseUrl, 'https://flag.example/v1')
+    assert.equal(f.model, 'flag-model')
+    assert.equal(f.maxTokens, 7)
+    // CAR_ALLOW_ENV_CREDENTIALS 显式意见压过配置（=0 关）
+    assert.equal(mergeLlmConfig({ CAR_ALLOW_ENV_CREDENTIALS: '0' }, cfg).allowEnvFallback, false)
+  })
+})
+
+test('S31: doctorModelReadiness——configured/not-found/env 三态（值不打印红线）', () => {
+  withTempDir('doctor-model', dir => {
+    const d1 = doctorModelReadiness({ env: {}, cwd: dir })
+    assert.equal(d1.configured, false)
+    assert.equal(d1.credential, 'not-found')
+    assert.match(d1.detail, /未配置/)
+    const d2 = doctorModelReadiness({
+      env: { CAR_LLM_BASE_URL: 'https://x/v1', CAR_LLM_MODEL: 'm', OPENAI_API_KEY: TEST_KEY, CAR_ALLOW_ENV_CREDENTIALS: '1' },
+      cwd: dir,
+    })
+    assert.equal(d2.configured, true)
+    assert.equal(d2.credential, 'env')
+    assert.equal(d2.envFallback, 'on')
+    assert.equal(d2.detail.includes(TEST_KEY), false, '凭据值永不打印')
+  })
+})
+
+// ==================== S4：D-12a + 取消 + CarM8Error ====================
+
+test('S31: D-12a loopback 豁免——http 仅 127.0.0.1/localhost/[::1]；非 loopback http 拒绝', () => {
+  assert.ok(createOpenAICompatAdapter({ baseUrl: 'http://127.0.0.1:1234/v1' }), 'loopback http 允许')
+  assert.ok(createOpenAICompatAdapter({ baseUrl: 'http://localhost:1234/v1' }), 'localhost http 允许')
+  assert.ok(createOpenAICompatAdapter({ baseUrl: 'http://[::1]:1234/v1' }), 'IPv6 loopback http 允许')
+  assert.throws(() => createOpenAICompatAdapter({ baseUrl: 'http://10.0.0.1:8080/v1' }), /CAR-E-LLM-TLS/, '非 loopback http 拒绝')
+  assert.throws(() => createOpenAICompatAdapter({ baseUrl: 'http://example.com/v1' }), /CAR-E-LLM-TLS/)
+  assert.ok(createOpenAICompatAdapter({ baseUrl: 'https://api.example.com/v1' }), 'https 任意域允许')
+})
+
+test('S31: 取消（D-19）——TurnAborted 首次实抛：pre-aborted 走 finish 前检查；runTurn 收口 aborted', async () => {
+  await withTempDir('cancel', async dir => {
+    const log = new SessionLog('S-cancel')
+    log.append('runtime', 'system', 'system', 'sys')
+    log.append('user', 'user', 'T0', 'hi')
+    const core = new RuntimeCore()
+    const signal = { aborted: true }  // pre-aborted：适配器 attempt 前静默收口（零 chunk）
+    const tools = new Map<string, any>([['t', { declaredSideEffect: 'readonly', run: async () => 'ok' }]])
+    // pre-aborted：适配器 attempt 前静默收口（零 chunk）→ chatStep finish 检查前抛 TurnAborted
+    const adapter = createOpenAICompatAdapter({ baseUrl: 'http://127.0.0.1:1/v1', fetchImpl: (async () => { throw new Error('不应发起请求') }) as typeof fetch })
+    core.registerLlmAdapter(adapter)
+    const r = await runTurn({
+      log, turnId: 'T0', tools, signal,
+      model: () => chatStep({ core, log, turnId: 'T0', model: 'm', tools: toToolDefinitions(tools), signal }),
+    })
+    assert.equal(r.reason, 'aborted', 'runTurn 既有 catch 收口 aborted')
+    const turnEnd = log.events.find(e => e.kind === 'turnEnd')!
+    assert.equal((turnEnd.meta as any)?.reason, 'aborted')
+    assert.equal(log.events.some(e => e.kind === 'assistant'), false, '无半截 assistant 落链')
+  })
+})
+
+test('S31: CarM8Error 保形——A080001 code/userHint/retryable 进 turnEnd（引导文案可达用户）', async () => {
+  await withTempDir('m8-error', async dir => {
+    const log = new SessionLog('S-m8err')
+    log.append('user', 'user', 'T0', 'hi')
+    const cred = new CredentialService()
+    const core = new RuntimeCore(cred)
+    core.registerLlmAdapter(createOpenAICompatAdapter({ baseUrl: 'http://127.0.0.1:1/v1', credentials: cred, provider: 'openai-compat' }))
+    const r = await runTurn({
+      log, turnId: 'T0',
+      tools: new Map<string, any>(),
+      model: () => chatStep({ core, log, turnId: 'T0', model: 'm', tools: [] }),
+    })
+    assert.equal(r.reason, 'error')
+    const turnEnd = log.events.find(e => e.kind === 'turnEnd')!
+    const meta = turnEnd.meta as any
+    assert.equal(meta.code, 'A080001')
+    assert.match(meta.userHint, /car doctor/, '引导文案进 turnEnd（1.4 前被 String(e) 拍平）')
+    assert.equal(meta.retryable, false)
+  })
+})
+
+// ==================== S5：多步真 E2E（真 HTTP + 真装配） ====================
+
+test('S31: 多步真 E2E——system 出站 / 工具 schema 出站 / Bearer 凭据 / 第二请求含 toolResult / 声明面=授权面', async () => {
+  await withTempDir('multistep', async dir => {
+    const { server, url, bodies, headers, done } = await fakeOpenAI([
+      () => TOOL_CALL_SSE('echo_tool', '{"text":"hi"}', 'call_1'),
+      () => TEXT_SSE('完成了'),
+    ])
+    try {
+      const log = new SessionLog('S-e2e')
+      log.append('runtime', 'system', 'system', '你是集成测试助手')
+      log.append('user', 'user', 'T0', '请调用 echo_tool')
+      const cred = new CredentialService({ keychainReader: s => (s === 'car-runtime/openai-compat' ? 'test-key-123' : null) })
+      const core = new RuntimeCore(cred)
+      const ctx = new Context()
+      core.bindContext(ctx)
+      core.registerLlmAdapter(createOpenAICompatAdapter({
+        baseUrl: url, credentials: cred, provider: 'openai-compat',
+      }), { default: true })
+      const tools = new Map<string, any>([[
+        'echo_tool',
+        { declaredSideEffect: 'readonly', description: '回声工具', parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] }, run: async (a: any) => 'echo:' + a.text },
+      ]])
+      const r = await runTurn({
+        log, turnId: 'T0', tools,
+        model: () => chatStep({ core, log, turnId: 'T0', model: 'test-model', tools: toToolDefinitions(tools) }),
+      })
+      assert.equal(r.reason, 'completed')
+      assert.equal(r.steps, 2, '两步：toolUse → 工具执行 → stop')
+      await done
+      // 请求 1：system 消息出站（§3.5.5）+ 工具 schema 出站 + Bearer 凭据
+      assert.equal(bodies[0].messages[0].role, 'system')
+      assert.equal(bodies[0].messages[0].content, '你是集成测试助手')
+      assert.equal(bodies[0].tools.length, 1)
+      assert.equal(bodies[0].tools[0].function.name, 'echo_tool')
+      assert.deepEqual(bodies[0].tools[0].function.parameters, { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] })
+      assert.equal(bodies[0].tools[0].function.description, '回声工具')
+      assert.equal(headers[0].authorization, 'Bearer ' + TEST_KEY, '凭据经 CredentialService→Bearer')
+      assert.equal(JSON.stringify(bodies[0]).includes(TEST_KEY), false, '凭据值不出站到消息体')
+      // 请求 2：第二请求含 toolResult 消息（executeBatch 落链 → 投影 → 出站）
+      const toolMsg = bodies[1].messages.find((m: any) => m.role === 'tool')
+      assert.ok(toolMsg, '第二请求含 tool 消息')
+      assert.equal(toolMsg.tool_call_id, 'call_1')
+      assert.equal(toolMsg.content, '"echo:hi"')
+      // 落链面：assistant/toolCall/toolResult 齐备（N1）
+      assert.equal(log.assertModelVisibleLogged().ok, true)
+      const final = log.deriveMessages().at(-1)!
+      assert.equal(final.role, 'assistant')
+      assert.equal(final.content, '完成了')
+      void server
+    } finally {
+      server.close()
+      await done
+    }
+  })
+})
+test('S31: spawn CLI 全链——car run 真路径（--prompt/--base-url/--model + env 凭据）+ 无配置 exit 2', async () => {
+  await withTempDir('cli-real', async dir => {
+    const plugin = `export const manifest = { name: 'p', version: '1.0.0' }\n` +
+      `export default function apply(api) {\n` +
+      `  api.registerTool({ name: 'echo_tool', description: '回声工具', parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] }, declaredSideEffect: 'readonly', run: async (a) => 'echo:' + a.text })\n` +
+      `}\n`
+    writeFileSync(join(dir, 'p.ts'), plugin)
+    const bodies: any[] = []
+    let n = 0
+    const server = createServer((req, res) => {
+      let raw = ''
+      req.on('data', c => { raw += c })
+      req.on('end', () => {
+        bodies.push(JSON.parse(raw))
+        res.writeHead(200, { 'content-type': 'text/event-stream' })
+        res.end(n++ === 0 ? TOOL_CALL_SSE('echo_tool', '{"text":"hi"}', 'call_1') : TEXT_SSE('完成了'))
+      })
+    })
+    await new Promise<void>(r => server.listen(0, '127.0.0.1', r))
+    const port = (server.address() as { port: number }).port
+    const child = spawn(process.execPath, ['--experimental-transform-types', CLI, 'run', 'p.ts',
+      '--prompt', 'call echo_tool with text hi', '--base-url', `http://127.0.0.1:${port}/v1`, '--model', 'cli-model',
+      '--system', '你是 CLI 集成测试助手'], {
+      cwd: dir,
+      env: { ...process.env, OPENAI_API_KEY: TEST_KEY, CAR_ALLOW_ENV_CREDENTIALS: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let out = ''
+    let err = ''
+    child.stdout.on('data', d => { out += d })
+    child.stderr.on('data', d => { err += d })
+    const code = await new Promise<number>(resolve => child.on('exit', c => resolve(c ?? -1)))
+    server.close()
+    assert.equal(code, 0, err)
+    assert.match(out, /turnEnd=completed/)
+    // system 出站（--system flag > 插件 setSystemPrompt）
+    assert.equal(bodies[0].messages[0].role, 'system')
+    assert.equal(bodies[0].messages[0].content, '你是 CLI 集成测试助手')
+    assert.equal(bodies[0].tools[0].function.name, 'echo_tool')
+    assert.match(out, /回放|投影/)
+
+    // 无模型配置 → exit 2 显式引导（D-13）
+    const noCfg = await new Promise<{ code: number; stderr: string }>(resolve => {
+      const c2 = spawn(process.execPath, ['--experimental-transform-types', CLI, 'run', 'p.ts'], { cwd: dir, stdio: ['ignore', 'pipe', 'pipe'] })
+      let e2 = ''
+      c2.stderr.on('data', d => { e2 += d })
+      c2.on('exit', c => resolve({ code: c ?? -1, stderr: e2 }))
+    })
+    assert.equal(noCfg.code, 2)
+    assert.match(noCfg.stderr, /CAR-E-LLM-CONFIG/)
+    assert.match(noCfg.stderr, /--demo/, '引导至演示流')
+  })
+})