@lqc123qwe/car-runtime 1.0.0-rc.1

package/src/mcp/gateway.ts

@@ -0,0 +1,118 @@
+/**
+ * F8 · MCP 桥接网关：登记制 + 工具桥接 + 崩溃隔离 + 凭据门
+ *
+ * 口径（《系统设计》M5 / 冻结决策① / 安全设计 T3 域）：
+ *  - serverId 登记制：运行期不接受未登记连接（A050001）；Python 侧仅工具供给方，无 ctx 级 API
+ *  - 工具桥接为一等 ToolDefinition：declaredSideEffect 未声明按 write 最高约束（T-22）
+ *  - 调用过三权限审批门（与其他工具同一审批门，无旁路——US-6 AC3）
+ *  - Server 崩溃/超时 → BD-02 整体标记不可用，不传导进内核主链路（US-6 AC4）
+ *  - McpServerConfig.env 禁明文密钥（疑似凭据模式即拒绝，sk- 前缀等——§3.2.5 传参禁忌）
+ *  - 传输抽象：stdio 真实通道（JSON-RPC over 换行分隔 JSON）/ in-process 测试通道
+ */
+export interface JsonRpcRequest { jsonrpc: '2.0'; id: number; method: string; params?: unknown }
+export interface JsonRpcResponse { jsonrpc: '2.0'; id: number; result?: unknown; error?: { code: number; message: string } }
+
+/**
+ * 客户端传输（CAR → MCP Server 方向）。M3-S11 双向分层：本接口为 client 侧对偶；
+ * server 侧（宿主 → CAR）见 src/host/hostGateway.ts 的 ServerTransport。
+ */
+export interface ClientTransport {
+  send(req: JsonRpcRequest): Promise<JsonRpcResponse>
+  /** 进程/通道存活状态 */
+  alive(): boolean
+  /** 主动终止 */
+  close(): void
+}
+
+/** M1 兼容别名（M2 代码零改动；M4 评估移除） */
+export type McpTransport = ClientTransport
+
+/**
+ * 服务端传输对偶（宿主 → CAR 方向，M3 多宿主）：宿主作为 MCP client 调用 CAR 暴露的 tool 面。
+ * 与 ClientTransport 语义对偶：CAR 不主动 send，仅响应 method 调用。
+ */
+export interface ServerTransport {
+  /** 宿主到达的 JSON-RPC 方法调用（由 HostGateway 分发到 9 tool 注册表） */
+  onRequest(method: string, params: unknown): Promise<JsonRpcResponse>
+  alive(): boolean
+  close(): void
+}
+
+/** 疑似明文凭据检测（§3.2.5：env 值出现 sk- 等前缀即拒绝） */
+export function containsPlaintextCredential(env: Record<string, string>): string | null {
+  const patterns = [/^sk-/, /^ghp_/, /^xox[bap]-/, /^AKIA/]
+  for (const [k, v] of Object.entries(env)) {
+    if (patterns.some(p => p.test(v))) return `env "${k}" looks like a plaintext credential（经 M8 凭据门注入，禁止明文透传）`
+  }
+  return null
+}
+
+export interface McpServerConfig {
+  serverId: string
+  transport: ClientTransport
+  /** 启动环境变量（禁明文凭据，凭据经 M8 凭据门运行时注入） */
+  env?: Record<string, string>
+}
+
+export interface McpToolDefinition {
+  serverId: string
+  name: string
+  description?: string
+  /** 未声明按 write 最高约束（T-22：安全默认） */
+  declaredSideEffect?: 'readonly' | 'write'
+}
+
+export class McpGateway {
+  #servers = new Map<string, McpServerConfig>()
+  #tools = new Map<string, McpToolDefinition & { serverId: string }>()
+  #unavailable = new Set<string>()
+  #nextId = 1
+
+  /** 登记并连接：拉起后发现工具并注册进能力矩阵（加载报告可见） */
+  async register(cfg: McpServerConfig): Promise<McpToolDefinition[]> {
+    if (this.#servers.has(cfg.serverId)) {
+      throw new Error(`CAR-E-MCP: serverId "${cfg.serverId}" already registered（登记制：重复注册显式报错）`)
+    }
+    const cred = cfg.env ? containsPlaintextCredential(cfg.env) : null
+    if (cred) throw new Error(`CAR-E-MCP: ${cred}`)
+    this.#servers.set(cfg.serverId, cfg)
+    const res = await cfg.transport.send({ jsonrpc: '2.0', id: this.#nextId++, method: 'tools/list' })
+    const tools = (res.result as { tools: Array<{ name: string; description?: string; sideEffect?: 'readonly' | 'write' }> }).tools
+    for (const t of tools) {
+      // T-22：未声明 sideEffect 按 write 最高约束收敛（安全默认，注册时强制）
+      this.#tools.set(`${cfg.serverId}:${t.name}`, {
+        serverId: cfg.serverId, name: t.name, description: t.description,
+        declaredSideEffect: t.sideEffect ?? 'write',
+      })
+    }
+    return [...this.#tools.values()].filter(t => t.serverId === cfg.serverId)
+  }
+
+  /** 能力矩阵视图（加载报告用） */
+  listTools(): McpToolDefinition[] { return [...this.#tools.values()] }
+
+  isAvailable(serverId: string): boolean { return this.#servers.has(serverId) && !this.#unavailable.has(serverId) }
+
+  /** 调用：走统一权限/审计链路（无旁路）；结果回填日志前必经 redact（调用方职责） */
+  async callTool(serverId: string, tool: string, args: Record<string, unknown>, opts: { timeoutMs?: number } = {}): Promise<{ ok: boolean; result?: unknown; error?: string }> {
+    const cfg = this.#servers.get(serverId)
+    if (!cfg) throw new Error('CAR-A050001: unregistered MCP connection rejected（登记制）')
+    if (this.#unavailable.has(serverId)) {
+      // BD-02：崩溃/超时整体标记不可用——显式错误结果，不抛异常不阻断主链路
+      return { ok: false, error: `MCP server "${serverId}" unavailable (BD-02)` }
+    }
+    const key = `${serverId}:${tool}`
+    if (!this.#tools.has(key)) return { ok: false, error: `unknown tool "${tool}" on "${serverId}"` }
+    try {
+      const res = await Promise.race([
+        cfg.transport.send({ jsonrpc: '2.0', id: this.#nextId++, method: 'tools/call', params: { name: tool, arguments: args } }),
+        new Promise<never>((_, rej) => setTimeout(() => rej(new Error('mcp timeout')), opts.timeoutMs ?? 30_000)),
+      ])
+      return { ok: true, result: (res as JsonRpcResponse).result }
+    } catch (e) {
+      // BD-02：崩溃/超时 → 整体不可用（不静默：错误事件由调用方落审计日志）
+      this.#unavailable.add(serverId)
+      return { ok: false, error: `MCP call failed, server marked unavailable (BD-02): ${String(e)}` }
+    }
+  }
+}

package/src/ptc/budget.ts

@@ -0,0 +1,37 @@
+/**
+ * T-2 · PTC 预算控制（M3-S14）
+ *
+ * 口径（M3系统设计增补 T-2 / D5 §12 一手口径）：
+ *  - 初始对齐 dsh：computeMs=60s / maxWallMs=600s / maxOutputBytes=64MB；
+ *  - **三层收敛只许下调**（fail-closed）：任何上调 = 显式报错——预算放宽属安全相关变更，
+ *    须经标定流程（四步标定法：P99×2 余量校验 + 逃逸验证 + 季度复标）而非配置直改；
+ *  - 预算定位 = **资源护栏而非安全边界**（containment 非安全边界，对外声明口径归安全设计）。
+ */
+
+export interface PtcBudget { computeMs: number; maxWallMs: number; maxOutputBytes: number }
+
+/** 初始基线（dsh 一手口径对齐值；标定后经 ADR 修订） */
+export const PTC_BUDGET_BASELINE: Readonly<PtcBudget> = Object.freeze({
+  computeMs: 60_000,
+  maxWallMs: 600_000,
+  maxOutputBytes: 64 * 1024 * 1024,
+})
+
+/**
+ * 预算收敛校验：用户覆盖值只许 ≤ 基线（逐项）；上调 = CAR-E-BUDGET 显式报错。
+ * 返回收敛后的完整预算（未覆盖项取基线）。
+ */
+export function convergeBudget(override?: Partial<PtcBudget>): PtcBudget {
+  const out: PtcBudget = { ...PTC_BUDGET_BASELINE }
+  if (!override) return out
+  for (const key of ['computeMs', 'maxWallMs', 'maxOutputBytes'] as const) {
+    const v = override[key]
+    if (v === undefined) continue
+    if (!Number.isFinite(v) || v <= 0) throw new Error(`CAR-E-BUDGET: ${key} must be a positive number, got ${v}`)
+    if (v > PTC_BUDGET_BASELINE[key]) {
+      throw new Error(`CAR-E-BUDGET: ${key}=${v} exceeds baseline ${PTC_BUDGET_BASELINE[key]}——预算只许下调（fail-closed），上调须经四步标定流程修订基线`)
+    }
+    out[key] = v
+  }
+  return out
+}

package/src/ptc/erasable.ts

@@ -0,0 +1,28 @@
+/**
+ * T-2 · erasable-only TS 静态检查（M3-S14 双挂点：loader 提交链 + run_code 入口）
+ *
+ * 口径（M3系统设计增补 T-2 / dsh 源码一手口径 code-runtime-worker-thread/src/index.ts:306-308）：
+ *  - PTC 程序体与插件提交链只接受 erasable TS（Node type-stripping 可直接剥离的语法）——
+ *    禁止 enum / namespace / module / 构造器参数属性 / import=require 等需转换的语法；
+ *  - 双挂点保证「无 worker 即无执行，漏检面 = 0」：loader 在插件装载时检查源码，
+ *    run_code 在 worker 启动前检查程序体——两处调用同一函数（单一事实源）。
+ */
+
+/** erasable 语法黑名单（启发式正则；完整 AST 检查随 jiti 实装升级为语法级） */
+const NON_ERASABLE: Array<{ name: string; re: RegExp }> = [
+  { name: 'enum 声明', re: /(?:^|\n)\s*(?:export\s+)?(?:const\s+)?enum\s+[A-Za-z_$]/ },
+  { name: 'namespace 声明', re: /(?:^|\n)\s*(?:export\s+)?namespace\s+[A-Za-z_$]/ },
+  { name: 'module 声明', re: /(?:^|\n)\s*(?:export\s+)?module\s+[A-Za-z_$"'`]/ },
+  { name: '构造器参数属性', re: /constructor\s*\(\s*(?:public|private|protected|readonly)\s+[A-Za-z_$]/ },
+  { name: 'import=require', re: /import\s+[A-Za-z_$][\w$]*\s*=\s*require\s*\(/ },
+  { name: 'export=require', re: /export\s*=\s*/ },
+  { name: '装饰器（实验性，非 erasable）', re: /@\s*[A-Za-z_$][\w$]*\s*\(/ },
+]
+
+/** erasable-only 检查：违规 = 显式报错（冲突链定位到语法名；v1 为启发式，行号随 AST 升级） */
+export function checkErasableOnly(code: string): { ok: boolean; violation?: string } {
+  for (const { name, re } of NON_ERASABLE) {
+    if (re.test(code)) return { ok: false, violation: `non-erasable TS: ${name}（PTC 程序体与插件提交链仅接受 erasable TS，见 M3系统设计增补 T-2）` }
+  }
+  return { ok: true }
+}

package/src/ptc/runCode.ts

@@ -0,0 +1,127 @@
+/**
+ * F16 · PTC（Programmatic Tool Calling）执行器（M3-S14）
+ *
+ * 口径（M3系统设计增补 T-2 / 决议③ PTC 落位 / dsh 一手口径）：
+ *  - run_code 签名：code + description **双必填**（description = 授权门「凭什么」人审凭据，无默认值）；
+ *  - 隔离：每次新 worker（独立无跨运行状态）；containment 非安全边界 → **强制 declaredSideEffect='write'**
+ *    走 stop.ts 既有权限门（S15 authorizationId='ptc-'+id 幂等集成）；
+ *  - erasable-only 双挂点之一（本入口）；挂点二在 loader 提交链（mountPlugin）；
+ *  - **预算到期不掐 turn**：超限 = 工具错误结果交回模型（TurnEndReason 六值零扩展，ADR-001 兼容）；
+ *  - 并发护栏（自研五维）：并发 4 / 子调用超时 30s / 总 worker 存活由本执行器串行门管控。
+ */
+import { Worker } from 'node:worker_threads'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { convergeBudget, type PtcBudget } from './budget.ts'
+import { checkErasableOnly } from './erasable.ts'
+import { redactSecrets } from '../security/secrets.ts'
+
+export interface PtcRequest { code: string; description: string; toolCallId: string; budget?: Partial<PtcBudget> }
+export interface PtcResult { ok: boolean; result?: unknown; error?: string; wallMs: number; outputBytes: number; budgetExceeded?: boolean
+  /** F12 出站覆盖命中数（secrets 脱敏在回填上下文前强制执行） */ secretsRedacted?: number }
+
+export interface ToolBridge { run(args: unknown): Promise<unknown> }
+
+const WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), 'worker-entry.ts')
+const MAX_CONCURRENT = 4
+let active = 0
+
+/** PTC 程序执行：每次新 worker；子调用经消息桥回主线程执行工具（宿主权限门生效面） */
+export interface RunCodeOpts { tools: Map<string, ToolBridge>; audit?: (d: Record<string, unknown>) => void
+  /** 授权门（S15）：返回 false = 拒绝（无 worker 启动，审计留痕）；authorizationId 幂等由 authz 服务承载 */ authorize?: (req: PtcRequest) => Promise<boolean> }
+
+export async function runCode(req: PtcRequest, opts: RunCodeOpts): Promise<PtcResult> {
+  // 双必填（description 为授权凭据——S15 授权门消费）
+  if (!req.code?.trim()) throw new Error('CAR-E-PTC: code is required（run_code 双必填）')
+  if (!req.description?.trim()) throw new Error('CAR-E-PTC: description is required——授权门人审凭据（无默认值，M3系统设计增补 T-2）')
+  // 授权门前置（无 worker 启动）：拒绝 = 工具错误结果 + 审计留痕（authorizationId='ptc-'+id 幂等键）
+  if (opts.authorize) {
+    const granted = await opts.authorize(req)
+    if (!granted) {
+      opts.audit?.({ kind: 'ptc-denied', toolCallId: req.toolCallId, authorizationId: 'ptc-' + req.toolCallId, description: req.description })
+      return { ok: false, error: 'authorization-denied (ptc)——授权拒绝落审计，程序未执行', wallMs: 0, outputBytes: 0 }
+    }
+  }
+  // erasable-only 挂点（入口）
+  const era = checkErasableOnly(req.code)
+  if (!era.ok) throw new Error(`CAR-E-PTC: ${era.violation}`)
+  const budget = convergeBudget(req.budget)
+  if (active >= MAX_CONCURRENT) {
+    return { ok: false, error: 'CAR-E-PTC: concurrency guard (max=4)——超限拒绝留痕', wallMs: 0, outputBytes: 0 }
+  }
+  const started = Date.now()
+  active++
+  opts.audit?.({ kind: 'ptc-start', description: req.description, toolCallId: req.toolCallId, budget })
+  try {
+    return await new Promise<PtcResult>((resolve) => {
+      const worker = new Worker(WORKER_PATH, {
+        workerData: { code: req.code, budget },
+        resourceLimits: { maxOldGenerationSizeMb: 256, maxYoungGenerationSizeMb: 32 },
+      })
+      // 主线程侧兜底（worker 内计时器失效时强杀——双层预算）
+      const killer = setTimeout(() => {
+        void worker.terminate()
+        resolve({ ok: false, error: `budget-exceeded (maxWallMs=${budget.maxWallMs}, main-side guard)`, wallMs: Date.now() - started, outputBytes: 0, budgetExceeded: true })
+      }, budget.maxWallMs + 1000)
+      worker.on('message', (m: { type: string; callId?: string; name?: string; args?: unknown; result?: unknown; error?: string }) => {
+        if (m.type === 'tool') {
+          const def = opts.tools.get(m.name!)
+          // 工具异常必须回传为 tool-result error（供程序体 try/catch 恢复）——
+          // 无 catch 会成为 unhandled rejection 崩溃主进程（S19 评测 E1 捕获）
+          void (def
+            ? def.run(m.args).then(
+                r => worker.postMessage({ type: 'tool-result', callId: m.callId, result: r }),
+                (e: unknown) => worker.postMessage({ type: 'tool-result', callId: m.callId, error: String(e) }),
+              )
+            : Promise.resolve(worker.postMessage({ type: 'tool-result', callId: m.callId, error: `unknown tool "${m.name}"` })))
+          return
+        }
+        if (m.type === 'done') {
+          clearTimeout(killer)
+          // F12 出站覆盖：worker 输出回填上下文前强制 redact（M3安全设计增补 T-4）
+          let result = m.result
+          let secretsRedacted = 0
+          if (result !== undefined) {
+            const serialized = JSON.stringify(result)
+            const r = redactSecrets(serialized)
+            secretsRedacted = r.redacted
+            if (r.redacted > 0) {
+              result = JSON.parse(r.text)
+              opts.audit?.({ kind: 'ptc-secrets-redacted', toolCallId: req.toolCallId, hits: r.redacted })
+            }
+          }
+          resolve({
+            ok: !m.error,
+            result,
+            error: m.error,
+            wallMs: Date.now() - started,
+            outputBytes: Buffer.byteLength(JSON.stringify(result ?? null)),
+            budgetExceeded: !!m.error?.startsWith('budget-exceeded'),
+            secretsRedacted,
+          })
+        }
+      })
+      worker.on('error', (e) => { clearTimeout(killer); resolve({ ok: false, error: String(e), wallMs: Date.now() - started, outputBytes: 0 }) })
+      worker.on('exit', (code) => { clearTimeout(killer); active-- })
+      // exit 可能先于 done（budget killer）——兜底 resolve 幂等由 Promise 语义保证
+    })
+  } finally {
+    // active 递归在 exit 事件处理；此处为异常路径兜底
+    setTimeout(() => { active = Math.max(0, active - 0) }, 0)
+  }
+}
+
+/** PTC 作为一等 ToolDefinition：强制 write 侧效应（授权门无旁路），接入 runTurn 工具面 */
+export function makePtcToolDefinition(opts: { tools: Map<string, ToolBridge>; audit?: (d: Record<string, unknown>) => void }) {
+  return {
+    name: 'run_code',
+    description: '执行一段 erasable TypeScript 程序（PTC）——程序体内经 tools.<name>(args) 调用已注册工具',
+    // T-22 语义：PTC 与 bash 同信任级别 → 强制 write 最高约束（不可声明为 readonly）
+    declaredSideEffect: 'write' as const,
+    run: async (args: { code: string; description: string; toolCallId?: string }) => {
+      const r = await runCode({ code: args.code, description: args.description, toolCallId: args.toolCallId ?? 'ptc-' + Date.now().toString(36) }, opts)
+      if (!r.ok) throw new Error(r.error)
+      return r.result
+    },
+  }
+}

package/src/ptc/sdk.ts

@@ -0,0 +1,28 @@
+/**
+ * T-2 · PTC TS SDK 渲染（M3-S15）
+ *
+ * 口径（M3系统设计增补 T-2 / dsh 一手口径 tools/src/index.ts:26,97）：
+ *  - SDK = 从工具注册表快照渲染进 system prompt 的 TS 声明（**非 .d.ts 文件生成**）；
+ *  - **声明面/授权面一致性红线**：渲染源与授权消费源必须同一 Map 快照——模型看到的工具集合
+ *    即授权门放行的集合（多渲一个 = 无授权执行面，少渲一个 = 授权白给）；
+ *  - 参数形状以 description + 可选 paramHint 声明（v1 不做 JSON Schema→TS 深度转换，S16 评估）。
+ */
+import type { ToolBridge } from './runCode.ts'
+
+export interface SdkToolDef { name: string; description?: string; /** 参数形状提示（TS 字面量），如 '{ x: number; y: number }' */ paramHint?: string }
+
+/** 渲染 SDK 声明：注入 PTC 程序体上文的 TS 类型面（模型据此写代码） */
+export function renderSdk(defs: Iterable<SdkToolDef>): string {
+  const lines = ['// CAR PTC SDK —— 以下声明与授权门消费同一注册表快照（声明面=授权面）', 'declare const tools: {']
+  for (const d of defs) {
+    const hint = d.paramHint ?? 'args: unknown'
+    lines.push(`  ${JSON.stringify(d.name)}: (${hint}) => Promise<unknown>${d.description ? ` // ${d.description}` : ''}`)
+  }
+  lines.push('};')
+  return lines.join('\n')
+}
+
+/** 从 ToolBridge 注册表快照渲染（包装：接受可选 description/paramHint 的注册表条目） */
+export function renderSdkFromRegistry(registry: Map<string, ToolBridge & { description?: string; paramHint?: string }>): string {
+  return renderSdk([...registry.entries()].map(([name, d]) => ({ name, description: d.description, paramHint: d.paramHint })))
+}

package/src/ptc/worker-entry.ts

@@ -0,0 +1,67 @@
+/**
+ * PTC worker 入口（M3-S14）：隔离执行 PTC 程序体
+ *
+ * 协议：
+ *  - workerData: { code, budget }；
+ *  - 程序体 = async 函数体（顶层 await/return 支持，dsh 一手口径）；
+ *  - tools proxy：await tools.<name>(args) → postMessage {type:'tool'} → 主线程执行 → {type:'tool-result'} 回传；
+ *  - 预算：maxWallMs 计时超限 → done(error='budget-exceeded (maxWallMs)')；maxOutputBytes 序列化后检查；
+ *  - done 消息单发即退——程序体 = 一次原子 toolCall（收口点唯一在 executor 返回）。
+ */
+import { parentPort, workerData } from 'node:worker_threads'
+
+const port = parentPort!
+const pending = new Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void }>()
+
+port.on('message', (m: { type: string; callId?: string; result?: unknown; error?: string }) => {
+  if (m.type === 'tool-result' && m.callId) {
+    const p = pending.get(m.callId)
+    if (!p) return
+    pending.delete(m.callId)
+    if (m.error) p.reject(new Error(m.error))
+    else p.resolve(m.result)
+  }
+})
+
+const tools: Record<string, (args: unknown) => Promise<unknown>> = new Proxy({}, {
+  get: (_, name: string) => (args: unknown) => new Promise((resolve, reject) => {
+    const callId = Math.random().toString(36).slice(2)
+    pending.set(callId, { resolve, reject })
+    port.postMessage({ type: 'tool', callId, name, args })
+  }),
+})
+
+const budget = (workerData as { budget: { maxWallMs: number; maxOutputBytes: number } }).budget
+const finish = (msg: { type: 'done'; result?: unknown; error?: string }) => {
+  port.postMessage(msg)
+  setTimeout(() => process.exit(0), 50) // 让消息冲刷
+}
+
+const wallTimer = setTimeout(() => finish({ type: 'done', error: `budget-exceeded (maxWallMs=${budget.maxWallMs})——预算到期为资源护栏，不掐 turn（工具错误结果交回模型）` }), budget.maxWallMs)
+
+void (async () => {
+  try {
+    const code = (workerData as { code: string }).code
+    // erasable-only 的执行端：eval 前剥离类型（Node 22.13+ 内置 stripTypeScriptTypes）——
+    // 程序体是 erasable TS（含类型注解），new Function 是纯 JS 求值器，不剥离则注解即 SyntaxError
+    const { stripTypeScriptTypes } = await import('node:module')
+    // stripTypeScriptTypes 以「模块」语义解析——片段含顶层 return 会报 ERR_INVALID_TYPESCRIPT_SYNTAX；
+    // 故先包成 export default 箭头函数再剥离，剥离后还原为 return 表达式（程序体含字面 export default 不受支持，见 erasable 禁项）
+    const wrapped = 'export default async () => {\n' + code + '\n}'
+    const js = stripTypeScriptTypes(wrapped, { mode: 'strip' })
+    const body = js.replace(/^export default /, 'return ')
+    // 程序体 = async 函数体（顶层 await/return）；tools 为受控 proxy（仅显式调用，无宿主 import 面）
+    const fn = new Function('tools', '"use strict";\n' + body + '\n') as (t: typeof tools) => () => Promise<unknown>
+    const result = await fn(tools)()
+    clearTimeout(wallTimer)
+    const out = JSON.stringify(result ?? null)
+    if (Buffer.byteLength(out) > budget.maxOutputBytes) {
+      finish({ type: 'done', error: `budget-exceeded (maxOutputBytes=${budget.maxOutputBytes})` })
+      return
+    }
+    finish({ type: 'done', result: JSON.parse(out) })
+  } catch (e) {
+    clearTimeout(wallTimer)
+    finish({ type: 'done', error: String(e) })
+  }
+})()

package/src/sandbox/sandbox.ts

@@ -0,0 +1,199 @@
+/**
+ * F3 · 沙箱执行器：能力探测 + 三档模式 + 降级路径（BD-01）+ 逃逸回归接口
+ *
+ * 口径（《系统设计》F3 / 安全设计 §5.3 / Q-04 定稿 / 冻结决策② + M2系统设计增补 T-3）：
+ *  - 平台后端：linux = landlock-run（dsh 同款独立 C11 可执行：--probe 探测、--ro/--rw -- argv、
+ *    fail-closed）+ seccomp 过滤集；darwin = Seatbelt（sandbox-exec 动态生成 profile，M2-S7 实装）；
+ *    win32 = 受限 token + Job Object（koffi FFI，S7 出 spike 方案、S8 实装——dsh win32 为 koffi 纯 JS，
+ *    sandbox-local/src/index.ts:160-161 源码级已核实）。
+ *    容器内 Landlock 不可用 → 探测失败走同一降级路径（SR-01/19 口径）
+ *  - 降级态约束（Q-04）：写类操作强制确认模式（full 亦受限）、env-read 一律拒绝、
+ *    降级事件 + 每次降级态授权带 degraded=true 留痕、静默降级 = AL-03 P1（计数必须为 0）
+ *  - 执行：argv 数组形式（A03 红线：禁 shell -c 拼接）、单命令 300s 上限、0 自动重试
+ */
+import { spawn } from 'node:child_process'
+
+export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access'
+export type Capability = 'fs-write' | 'net' | 'exec' | 'mcp' | 'env-read'
+
+export interface ProbeResult {
+  platform: NodeJS.Platform
+  landlock: boolean
+  seccomp: boolean
+  degraded: boolean
+  /** 降级原因（审计留痕用）；未降级为 null */
+  reason: string | null
+}
+
+export interface SandboxAuditSink {
+  (event: { kind: 'sandbox-degraded' | 'sandbox-denied' | 'sandbox-exec'; detail: Record<string, unknown>; ts: number }): void
+}
+
+/** 能力探测：Linux 用 landlock-run --probe；其余平台直接降级（可插拔真实探测） */
+export async function probeCapabilities(opts: {
+  landlockRunPath?: string
+  platform?: NodeJS.Platform
+} = {}): Promise<ProbeResult> {
+  const platform = opts.platform ?? process.platform
+  if (platform !== 'linux' || !opts.landlockRunPath) {
+    return {
+      platform,
+      landlock: false, seccomp: false, degraded: true,
+      reason: platform === 'linux'
+        ? 'landlock-run binary not available（BD-01：需编译 native/landlock-run 或提供路径）'
+        : `platform ${platform} 沙箱原语未实装（S3：Linux 先行，经中间确认②）`,
+    }
+  }
+  const probe = await new Promise<{ ok: boolean }>((resolve) => {
+    try {
+      const child = spawn(opts.landlockRunPath!, ['--probe'], { stdio: 'ignore' })
+      child.on('exit', (code) => resolve({ ok: code === 0 }))
+      child.on('error', () => resolve({ ok: false }))
+    } catch { resolve({ ok: false }) }
+  })
+  return probe.ok
+    ? { platform, landlock: true, seccomp: true, degraded: false, reason: null }
+    : { platform, landlock: false, seccomp: false, degraded: true, reason: 'landlock-run probe failed（内核 <5.13 或 LSM 未启用）' }
+}
+
+export interface ExecRequest {
+  argv: string[]
+  /** 声明所需能力（能力标签 = 跨域请求唯一凭证） */
+  capabilities: Capability[]
+  mode: SandboxMode
+  /** 运行权限模式（F4）：readonly/confirm/full——降级态下 full 亦受限为 confirm */
+  permissionMode: 'readonly' | 'confirm' | 'full'
+  authorize?: (req: ExecRequest) => Promise<boolean>
+  timeoutMs?: number
+}
+
+export interface ExecResult { ok: boolean; stdout: string; stderr: string; code: number | null; degraded: boolean; denied?: string }
+
+/**
+ * M2-S7 · Seatbelt profile 生成器（darwin 后端）
+ *
+ * 口径：参照 Codex sandbox-exec 动态生成 profile（SR-19，源码级已核实）+ dsh darwin=['seatbelt'] 路由。
+ * 生成规则（fail-closed：默认全部拒绝，仅显式 allow）：
+ *  - 全模式：允许进程基本运行（process-exec/process-fork）+ /usr,/bin,/sbin,/System 只读；
+ *  - read-only / workspace-write：拒绝 network*（deny-by-default 网络）；
+ *  - workspace-write：仅 {workspace} 与 CAR_HOME 临时目录允许 file-write*，.git 强制只读（受保护路径）；
+ *  - danger-full-access：不生成 profile（直跑，与 Codex 三档一致）。
+ */
+export function buildSeatbeltProfile(mode: SandboxMode, workspace: string): string {
+  if (mode === 'danger-full-access') throw new Error('CAR-E-SANDBOX: danger-full-access does not use a seatbelt profile（直跑语义）')
+  const ws = workspace.replace(/"/g, '\\"')
+  const lines = [
+    '(version 1)',
+    '(deny default)', // fail-closed
+    ';; 进程基本运行',
+    '(allow process-fork)',
+    '(allow process-exec)',
+    ';; 系统只读面',
+    '(allow file-read* (subpath "/usr"))',
+    '(allow file-read* (subpath "/bin"))',
+    '(allow file-read* (subpath "/sbin"))',
+    '(allow file-read* (subpath "/System"))',
+    '(allow file-read* (subpath "/private/var/db/dyld"))',
+    ';; 系统运行必需',
+    '(allow sysctl-read)',
+    '(allow mach-lookup)',
+    '(allow iokit-open)',
+  ]
+  if (mode === 'workspace-write') {
+    lines.push(
+      `;; 工作区可写（.git 强制只读——受保护路径）`,
+      `(allow file-write* (subpath "${ws}"))`,
+      `(deny file-write* (subpath "${ws}/.git"))`,
+      `;; 工作区读取`,
+      `(allow file-read* (subpath "${ws}"))`,
+      `;; 临时目录（编译器/子进程必需）`,
+      '(allow file-write* (subpath "/private/tmp"))',
+      '(allow file-read* (subpath "/private/tmp"))',
+      '(allow file-write* (subpath "/private/var/tmp"))',
+    )
+  } else {
+    lines.push(
+      `;; read-only：工作区仅读`,
+      `(allow file-read* (subpath "${ws}"))`,
+      '(allow file-read* (subpath "/private/tmp"))',
+    )
+  }
+  lines.push(';; deny-by-default 网络（写类能力需显式豁免才可放行，本模板一律拒绝）', '(deny network*)')
+  return lines.join('\n')
+}
+
+export class SandboxExecutor {
+  #probe: ProbeResult
+  #audit: SandboxAuditSink
+  #landlockRunPath?: string
+  #workspace: string
+
+  constructor(opts: { probe: ProbeResult; audit: SandboxAuditSink; landlockRunPath?: string; workspace: string }) {
+    this.#probe = opts.probe
+    this.#audit = opts.audit
+    this.#landlockRunPath = opts.landlockRunPath
+    this.#workspace = opts.workspace
+  }
+
+  get degraded(): boolean { return this.#probe.degraded }
+
+  /** Q-04 定稿：降级态运行约束判定（在授权门之前生效） */
+  effectivePermission(permissionMode: ExecRequest['permissionMode'], capabilities: Capability[]): { mode: 'readonly' | 'confirm' | 'full'; denied: string | null } {
+    if (!this.degraded) return { mode: permissionMode, denied: null }
+    const writeish = capabilities.some(c => c === 'fs-write' || c === 'net' || c === 'exec' || c === 'mcp')
+    if (capabilities.includes('env-read')) return { mode: 'confirm', denied: 'env-read denied in degraded sandbox（Q-04：一律拒绝）' }
+    if (writeish) return { mode: 'confirm', denied: null } // full 亦受限为 confirm
+    return { mode: permissionMode === 'full' ? 'confirm' : permissionMode, denied: null }
+  }
+
+  /** 沙箱内执行：argv 数组、写类能力需授权、降级态 Q-04 约束、审计全量留痕 */
+  async exec(req: ExecRequest): Promise<ExecResult> {
+    const { mode: effMode, denied: degradedDenial } = this.effectivePermission(req.permissionMode, req.capabilities)
+    if (degradedDenial) {
+      this.#audit({ kind: 'sandbox-denied', detail: { argv: req.argv, reason: degradedDenial, degraded: true }, ts: Date.now() })
+      return { ok: false, stdout: '', stderr: degradedDenial, code: -1, degraded: true, denied: degradedDenial }
+    }
+    // 权限门：写类能力在 readonly 一律拒；confirm 需审批（降级态强制 confirm）
+    const writeish = req.capabilities.some(c => c === 'fs-write' || c === 'net' || c === 'exec' || c === 'mcp')
+    if (writeish && effMode !== 'full') {
+      const granted = effMode === 'confirm' ? await (req.authorize?.(req) ?? Promise.resolve(false)) : false
+      if (!granted) {
+        this.#audit({ kind: 'sandbox-denied', detail: { argv: req.argv, mode: effMode, degraded: this.degraded }, ts: Date.now() })
+        return { ok: false, stdout: '', stderr: `authorization-denied (mode=${effMode}${this.degraded ? ', degraded' : ''})`, code: -1, degraded: this.degraded, denied: 'authorization-denied' }
+      }
+    }
+    if (this.degraded) {
+      // 降级态执行：无内核背书——仅透传执行并留痕（授权门已按 Q-04 收紧）
+      this.#audit({ kind: 'sandbox-exec', detail: { argv: req.argv, degraded: true }, ts: Date.now() })
+      return this.#spawn(req.argv, req.timeoutMs, true)
+    }
+    // 正常态：Linux landlock-run 包装（self-restrict-then-exec，fail-closed）
+    if (process.platform === 'linux' && this.#landlockRunPath) {
+      const ro = req.mode === 'read-only'
+      const wrapped = [this.#landlockRunPath, ro ? '--ro' : '--rw', '--', ...req.argv]
+      return this.#spawn(wrapped, req.timeoutMs, false)
+    }
+    // 正常态：macOS Seatbelt（sandbox-exec 动态 profile，M2-S7）
+    if (process.platform === 'darwin' && req.mode !== 'danger-full-access') {
+      const profile = buildSeatbeltProfile(req.mode, this.#workspace)
+      return this.#spawn(['sandbox-exec', '-p', profile, ...req.argv], req.timeoutMs, false)
+    }
+    return this.#spawn(req.argv, req.timeoutMs, false)
+  }
+
+  #spawn(argv: string[], timeoutMs = 300_000, degraded: boolean): Promise<ExecResult> {
+    return new Promise((resolve) => {
+      const child = spawn(argv[0], argv.slice(1), { cwd: this.#workspace, shell: false, env: { ...process.env } })
+      let stdout = '', stderr = ''
+      const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs)
+      child.stdout?.on('data', d => { stdout += d })
+      child.stderr?.on('data', d => { stderr += d })
+      child.on('error', (e) => { clearTimeout(timer); resolve({ ok: false, stdout, stderr: String(e), code: -1, degraded }) })
+      child.on('exit', (code) => {
+        clearTimeout(timer)
+        this.#audit({ kind: 'sandbox-exec', detail: { argv, code, degraded }, ts: Date.now() })
+        resolve({ ok: code === 0, stdout, stderr, code, degraded })
+      })
+    })
+  }
+}