@lqc123qwe/car-runtime 1.8.0 → 1.10.0

package/dist/runtime-core/trace.js

@@ -0,0 +1,137 @@
+/**
+ * 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 枚举——无会话内容/提示词/路径。
+ *
+ * 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 零独立出站通道）。
+ *
+ * 1.9（D-32 · 远程 MCP Streamable HTTP 头通道）：mcpToolSpan 产出的 traceparent 除 1.8 `params._meta`
+ * 载体外，经 gateway.callTool → transport.send 第二参透传，httpClient 注入 `traceparent` 请求头
+ * （W3C Trace Context HTTP 载体惯例——远程 server 主消费面）。本模块仅复用 parseTraceparent 作
+ * 传输层 fail-open 校验（畸形不注入不抛）——编解码与传播语义 1.8 口径零触碰。
+ */
+import { randomBytes } from 'node:crypto';
+/** 1.8-D29：W3C traceparent 出站形态（flags '01' = 本端记录中；采样为端点本地决策不跨端传播） */
+export function formatTraceparent(traceId, spanId) {
+    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) {
+    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 {
+    #facade;
+    constructor(facade) {
+        // 默认关（无端点）= noop 句柄（零出站零积累——telemetry 三原则）
+        this.#facade = facade?.enabled ? facade : null;
+    }
+    /** 1.8-D30：opts.trace = 远端挂链（mcp-serve session_turn `_meta.traceparent` 提取后传入；缺省新 trace 不变） */
+    startTurn(turnId, opts) {
+        if (!this.#facade) {
+            return {
+                traceId: '', spanId: '', setTurnId() { }, recordException() { }, end() { },
+                stepSpan: () => ({ end() { }, recordException() { } }),
+                mcpToolSpan: () => ({ traceparent: '', end() { }, recordException() { } }),
+                ptcRelay: () => ({ workerTrace: null, complete() { } }),
+            };
+        }
+        const tracer = this.#facade.getTracer();
+        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();
+            },
+            stepSpan(step) {
+                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); },
+                };
+            },
+            // 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() {
+                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/dist/runtime-core/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * M8 · 运行时底座共享 DTO（《系统设计》§3.2.M8.3 / §3.3.1 O-10/O-11/O-13/O-14）
+ *
+ * 口径：
+ *  - LlmChunk.finishReason 为不可变透传（readonly 语义，ADR-001；vLLM #53269 教训 SR-17）——
+ *    唯一信号源，禁止中间层改写/吞没；llm.ts 的流包装层对此做防御性断言；
+ *  - LlmRequest.tools 含 declaredSideEffect（权限门依据；readonly 是 ADR-001 补错重试白名单前置）；
+ *  - ToolDefinition 为 M8 共享 DTO（O-10）：M3 授权门/M5 MCP 网关/M8 模型请求三方复用；
+ *    与 loop/stop.ts 的 ToolDef 分工——ToolDefinition 是声明面（进模型 schema），ToolDef 是执行面；
+ *  - CredentialRef 不落明文（O-13）：ref 只含来源定位，值经 credentials.reveal 按需取用；
+ *  - 规格外扩展字段（adapterId / error）以加法演进登记——与 hostRaw 同纪律，不改动规格最小集语义。
+ */
+/** 模型请求（Provider 无关） */
+export interface LlmRequest {
+    model: string;
+    messages: Array<{
+        role: 'system' | 'user' | 'assistant' | 'toolResult';
+        content: unknown;
+    }>;
+    /** 工具 schema（缓存失效因素：工具集合/模型切换/compaction，D3 §14.6） */
+    tools: ToolDefinition[];
+    maxTokens?: number;
+    metadata?: {
+        sessionId: string;
+        turnId: string;
+        traceId: string;
+    };
+    /** 多适配器在册时显式路由；缺省用默认适配器 */
+    adapterId?: string;
+    /** 1.4-S4（D-19）：turn 取消信号（runTurn 的 {aborted} 形态透传）——适配器在 attempt 前 /
+     *  chunk 间隙检查；外部取消 ≠ 失败（不 retry、不产 error chunk，静默收口由 chatStep 抛 TurnAborted） */
+    signal?: {
+        aborted: boolean;
+    };
+}
+/** 工具调用流式增量（跨 chunk 聚合出完整 ToolCall） */
+export interface ToolCallDelta {
+    index?: number;
+    id?: string;
+    name?: string;
+    /** JSON 增量片段，聚合后整体 JSON.parse（半截 JSON 不解析——ADR-001 同纪律） */
+    argumentsDelta?: string;
+}
+/** 流式块（finishReason 一经产生不可被任何中间层改写） */
+export interface LlmChunk {
+    delta?: string;
+    toolCallDelta?: ToolCallDelta;
+    finishReason?: 'stop' | 'length' | 'toolUse' | 'error' | 'aborted';
+    /** finishReason='error' 时的结构化原因（消费方落 turnEnd meta，不进模型消息流） */
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/** Provider 适配器（ACL，C-02）：统一签名，消解 Provider 差异 */
+export interface LlmAdapter {
+    /** 如 openai-compat / anthropic */
+    id: string;
+    chat(req: LlmRequest): AsyncIterable<LlmChunk>;
+}
+/** 可逆注册句柄（dispose = Effect 回卷） */
+export interface Disposable {
+    dispose(): void;
+}
+/** 共享工具声明 DTO（O-10；注册时构造，进模型请求 schema） */
+export interface ToolDefinition {
+    name: string;
+    description?: string;
+    /** JSON Schema 形态参数声明 */
+    parameters?: unknown;
+    /** 副作用声明（必填——M5 网关 T-22 强制点同一口径：缺声明即 write） */
+    declaredSideEffect: 'readonly' | 'write';
+}
+/** 凭据来源（§3.2.M8.3 字段表：env 需用户显式开启 fallback） */
+export type CredentialSource = 'keychain' | 'env';
+/** 凭据引用（O-13）：只含来源定位与掩码提示，值永不入此结构 */
+export interface CredentialRef {
+    provider: string;
+    source: CredentialSource;
+    /** 来源标识：keychain 服务名 / env 变量名 */
+    origin: string;
+    /** keychain 通道不可用等降级留痕（降级必须显式，禁静默） */
+    degraded?: string;
+}

package/dist/runtime-core/types.js

@@ -0,0 +1,13 @@
+/**
+ * M8 · 运行时底座共享 DTO（《系统设计》§3.2.M8.3 / §3.3.1 O-10/O-11/O-13/O-14）
+ *
+ * 口径：
+ *  - LlmChunk.finishReason 为不可变透传（readonly 语义，ADR-001；vLLM #53269 教训 SR-17）——
+ *    唯一信号源，禁止中间层改写/吞没；llm.ts 的流包装层对此做防御性断言；
+ *  - LlmRequest.tools 含 declaredSideEffect（权限门依据；readonly 是 ADR-001 补错重试白名单前置）；
+ *  - ToolDefinition 为 M8 共享 DTO（O-10）：M3 授权门/M5 MCP 网关/M8 模型请求三方复用；
+ *    与 loop/stop.ts 的 ToolDef 分工——ToolDefinition 是声明面（进模型 schema），ToolDef 是执行面；
+ *  - CredentialRef 不落明文（O-13）：ref 只含来源定位，值经 credentials.reveal 按需取用；
+ *  - 规格外扩展字段（adapterId / error）以加法演进登记——与 hostRaw 同纪律，不改动规格最小集语义。
+ */
+export {};

package/dist/sandbox/sandbox.d.ts

@@ -0,0 +1,68 @@
+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 declare function probeCapabilities(opts?: {
+    landlockRunPath?: string;
+    platform?: NodeJS.Platform;
+}): Promise<ProbeResult>;
+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 declare function buildSeatbeltProfile(mode: SandboxMode, workspace: string): string;
+export declare class SandboxExecutor {
+    #private;
+    constructor(opts: {
+        probe: ProbeResult;
+        audit: SandboxAuditSink;
+        landlockRunPath?: string;
+        workspace: string;
+    });
+    get degraded(): boolean;
+    /** Q-04 定稿：降级态运行约束判定（在授权门之前生效） */
+    effectivePermission(permissionMode: ExecRequest['permissionMode'], capabilities: Capability[]): {
+        mode: 'readonly' | 'confirm' | 'full';
+        denied: string | null;
+    };
+    /** 沙箱内执行：argv 数组、写类能力需授权、降级态 Q-04 约束、审计全量留痕 */
+    exec(req: ExecRequest): Promise<ExecResult>;
+}

package/dist/sandbox/sandbox.js

@@ -0,0 +1,153 @@
+/**
+ * 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';
+/** 能力探测：Linux 用 landlock-run --probe；其余平台直接降级（可插拔真实探测） */
+export async function probeCapabilities(opts = {}) {
+    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((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 未启用）' };
+}
+/**
+ * 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, workspace) {
+    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;
+    #audit;
+    #landlockRunPath;
+    #workspace;
+    constructor(opts) {
+        this.#probe = opts.probe;
+        this.#audit = opts.audit;
+        this.#landlockRunPath = opts.landlockRunPath;
+        this.#workspace = opts.workspace;
+    }
+    get degraded() { return this.#probe.degraded; }
+    /** Q-04 定稿：降级态运行约束判定（在授权门之前生效） */
+    effectivePermission(permissionMode, capabilities) {
+        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) {
+        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, timeoutMs = 300_000, degraded) {
+        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 });
+            });
+        });
+    }
+}