berry-agent 0.1.0-alpha.1

package/dist/persist/write-behind.js

@@ -0,0 +1,238 @@
+/**
+ * persist — write-behind 批落链（05 篇 §6.3）。
+ *
+ * append 热路径零 I/O（session 侧 onAppend 直通 enqueue——纯内存入队）；
+ * 落库编舞全在本文件：微任务节流 + 批尺寸帽 64、事务序 = 入队序（单全局
+ * 队列——多会话事件按全局入队序交织落库，同会话序天然保真）、批级失败
+ * 退避重试（指数退避，耗尽 3 次 fail-loud）、毒丸分类（约束违例逐行诊断：
+ * 单条隔离不重试 + durable 标记 + 会话 durability 切断）、flush 屏障。
+ *
+ * 毒丸切断语义（§6.3 终态条款的实现推论）：被隔离事件不落库，其会话日志
+ * 即现空洞——seq 连续律（恢复重放的前缀语义）下，洞后事件重放不可达；故
+ * 毒丸一旦确认，该会话后续事件一并不再落库（每会话一笔 incident 自述，
+ * 不逐条刷账）。其他会话不受牵连（「不阻塞整队列」的另一半）。
+ */
+import { BaseError } from '../contracts/index.js';
+/**
+ * 判别是否 SQLite 约束违例类（确定性失败——重试必再败，毒丸分类入口）。
+ * 结构化判别（code 字符串前缀）而非 instanceof：better-sqlite3 的 SqliteError
+ * 在 @types 里是构造器类型属性，instanceof 收窄面失真；code 前缀是稳定契约。
+ */
+function isConstraintError(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'code' in err &&
+        typeof err.code === 'string' &&
+        err.code.startsWith('SQLITE_CONSTRAINT'));
+}
+/**
+ * WriteBehind——进程级单写队列（Persistence 构造并持有；跨会话共用，
+ * 05 §6.1 律 2「单进程内所有打开的会话共享同一 write-behind 队列」）。
+ *
+ * 生命周期态三枚：queued（队列本体）/ draining（在飞 drain 任务——enqueue
+ * 只入队 + 按需点火）/ broken（fatal 熔断——此后 enqueue 即抛，诚实拒写）。
+ */
+export class WriteBehind {
+    target;
+    maxBatchSize;
+    retryLimit;
+    backoffBaseMs;
+    sleep;
+    onFatal;
+    warn;
+    clock;
+    /** 待写队列（全局序 = 事务序） */
+    queue = [];
+    /** 在飞 drain 任务（null = 空闲；finally 补射防「drain 收尾与 enqueue 竞速」漏项） */
+    drainTask = null;
+    /** 微任务节流旗（已排队未点火——同 tick 内连续 enqueue 合一批） */
+    drainScheduled = false;
+    /** 毒丸诊断模式旗（本 drain 周期内逐行写——批路径在毒丸后不可回用：前段已逐行落账） */
+    rowMode = false;
+    /** 连续批级失败计数（成功清零；达 retryLimit 熔断） */
+    consecutiveFailures = 0;
+    /** 熔断旗（fatal 后诚实拒写——写链已死，再入队 = 谎报持久化） */
+    broken = false;
+    /** 已切断 durability 的会话（毒丸后——后续事件静默丢弃，不再入队落库） */
+    severed = new Set();
+    constructor(options) {
+        this.target = options.target;
+        this.maxBatchSize = options.maxBatchSize ?? 64;
+        this.retryLimit = options.retryLimit ?? 3;
+        this.backoffBaseMs = options.backoffBaseMs ?? 50;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.onFatal =
+            options.onFatal ??
+                ((err) => {
+                    throw err;
+                });
+        this.warn = options.warn ?? ((message) => console.error(message));
+        this.clock = options.clock ?? (() => Date.now());
+    }
+    /**
+     * 入队（append 热路径直通——O(1) 内存操作 + 按需点火微任务）。
+     * 熔断后抛 PERSIST_WRITE_EXHAUSTED（诚实拒写：调用方立即知道持久化已死）。
+     * 切断会话静默丢弃（incident 已自述——毒丸后该会话 durability 已终）。
+     */
+    enqueue(write) {
+        if (this.broken) {
+            throw new BaseError('PERSIST_WRITE_EXHAUSTED', '写链已熔断（批级重试耗尽）——进程应退出，拒绝继续假写');
+        }
+        if (this.severed.has(write.sessionId))
+            return;
+        this.queue.push(write);
+        this.scheduleDrain();
+    }
+    /** 队列深度（诊断面/测试断言） */
+    get pending() {
+        return this.queue.length;
+    }
+    /** 毒丸切断会话清单（诊断只读面） */
+    get severedSessions() {
+        return [...this.severed];
+    }
+    /**
+     * flush 屏障（05 §4/§6.3#5）：等待队列写尽并确认全部落库（含在飞 drain 与
+     * 退避等待——屏障后崩溃 = 已落库）。失败原样抛（毒丸不视为失败——其终态
+     * 在 incident 账，队列照常清空）。
+     */
+    async flush() {
+        if (this.broken) {
+            throw new BaseError('PERSIST_WRITE_EXHAUSTED', '写链已熔断——flush 无从屏障（进程应退出）');
+        }
+        this.scheduleDrain();
+        while (this.drainTask !== null || this.queue.length > 0 || this.drainScheduled) {
+            if (this.broken) {
+                throw new BaseError('PERSIST_WRITE_EXHAUSTED', 'flush 期间写链熔断——屏障失败（进程应退出）');
+            }
+            const task = this.drainTask;
+            if (task) {
+                await task;
+            }
+            else {
+                // 节流旗在排但 drain 未点火——让一个微任务（点火位先行）后再查
+                await new Promise((resolve) => queueMicrotask(resolve));
+            }
+        }
+    }
+    /**
+     * 点火 drain——微任务节流（05 §6.3）：enqueue 只入队不写（append 热路径零
+     * I/O 的兑现位），同一 tick 内的连续 append 合一批；已排队或在飞则不重复点火。
+     */
+    scheduleDrain() {
+        if (this.drainScheduled || this.drainTask !== null || this.broken)
+            return;
+        this.drainScheduled = true;
+        queueMicrotask(() => {
+            this.drainScheduled = false;
+            // 点火时队列已空（flush 消费完）或已熔断——本次空转
+            if (this.broken || this.queue.length === 0)
+                return;
+            this.drainTask = this.drain()
+                .catch((err) => {
+                // fatal 熔断：标记后交 onFatal（缺省重抛 → 未捕获拒绝 → 进程 fail-loud）
+                this.broken = true;
+                this.onFatal(err instanceof BaseError ? err : new BaseError('PERSIST_WRITE_EXHAUSTED', String(err), { cause: err }));
+            })
+                .finally(() => {
+                this.drainTask = null;
+                if (!this.broken && this.queue.length > 0)
+                    this.scheduleDrain();
+            });
+        });
+    }
+    /**
+     * 落库主循环（微任务链上跑——非真后台线程；节流 = 每轮微任务一批）：
+     * 批模式（快路径）→ 约束违例翻行模式逐行诊断 → 非约束错走退避重试。
+     */
+    async drain() {
+        for (;;) {
+            if (this.queue.length === 0) {
+                this.rowMode = false; // 队列清空——下一周期恢复批模式
+                this.consecutiveFailures = 0;
+                return;
+            }
+            if (this.rowMode) {
+                const write = this.queue.shift();
+                if (this.severed.has(write.sessionId))
+                    continue; // 切断会话：静默丢弃（incident 已记）
+                try {
+                    this.target.writeEventSingle(write);
+                    this.consecutiveFailures = 0;
+                }
+                catch (err) {
+                    if (isConstraintError(err)) {
+                        this.isolatePoison(write, err);
+                    }
+                    else {
+                        this.queue.unshift(write); // 放回队首——事务序保持
+                        if (!(await this.failOrBackoff(err)))
+                            return;
+                    }
+                }
+            }
+            else {
+                const batch = this.queue.splice(0, this.maxBatchSize);
+                try {
+                    this.target.writeEvents(batch);
+                    this.consecutiveFailures = 0;
+                }
+                catch (err) {
+                    if (isConstraintError(err)) {
+                        // 批内含毒丸：整批放回 + 翻行模式逐行定位（批事务已回滚，无损）
+                        this.queue.unshift(...batch);
+                        this.rowMode = true;
+                    }
+                    else {
+                        this.queue.unshift(...batch);
+                        if (!(await this.failOrBackoff(err)))
+                            return;
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * 批级失败处置：计数 → 达帽熔断（抛出 = drain 链拒绝 → onFatal）；
+     * 未达帽则指数退避后继续。
+     * @returns false = 已熔断（调用方即刻收场）
+     */
+    async failOrBackoff(err) {
+        this.consecutiveFailures++;
+        if (this.consecutiveFailures >= this.retryLimit) {
+            throw new BaseError('PERSIST_WRITE_EXHAUSTED', `write-behind 批级重试耗尽（连续 ${this.consecutiveFailures} 次失败）——写不进库的会话继续跑 = 谎报持久化，进程 fail-loud`, { cause: err });
+        }
+        const delay = this.backoffBaseMs * 2 ** (this.consecutiveFailures - 1);
+        await this.sleep(delay);
+        return true;
+    }
+    /**
+     * 毒丸隔离（§6.3 终态条款）：单条不重试 + durable 标记（persist_incidents）
+     * + 进程级告警 + 会话 durability 切断（后续事件不再落库——seq 连续律推论，
+     * 见文件头注）。游标跳记账（accountDropped）让其他会话的连续性断言不受牵连。
+     */
+    isolatePoison(write, err) {
+        const { sessionId, event } = write;
+        const code = typeof err === 'object' && err !== null && 'code' in err
+            ? String(err.code)
+            : 'SQLITE_CONSTRAINT';
+        const message = err instanceof Error ? err.message : String(err);
+        this.severed.add(sessionId);
+        this.target.accountDropped(sessionId, event.seq);
+        const entry = {
+            time: this.clock(),
+            sessionId,
+            seq: event.seq,
+            type: event.type,
+            reason: `${code}: ${message}；毒丸隔离不落库丢弃，该会话后续事件一并停写（seq 连续律破——durable 前缀止于 seq<${event.seq}）`,
+        };
+        try {
+            this.target.recordIncident(entry);
+        }
+        catch (recordErr) {
+            // 标记面自身失败：告警面兜底（进程还活着就让人看得见——审计优先于静默）
+            this.warn(`[persist] 毒丸标记落账失败（审计缺口）：${String(recordErr)}`);
+        }
+        this.warn(`[persist] 毒丸隔离：会话 ${sessionId} seq#${event.seq} ${event.type} 约束违例不落库（${message}）——durable 标记已落 persist_incidents，该会话后续事件停写`);
+    }
+}

package/dist/safety/approval.js

@@ -0,0 +1,171 @@
+/**
+ * L3 safety — ApprovalService（04 §9 审批与动作安全）。
+ *
+ * 机制全景：
+ * - 粘性短路（04 §9 粘性段定形①）：ask 前先查会话粘性表——同指纹（粘性
+ *   第 1 款）或子集预批（第 2 款：同目标更严档位请求被既有放行包含）命中
+ *   即免问放行，**不产生审批对**（没有问就没有 asked/decided——审计诚实）；
+ * - ask 档：经 approval/answer waterfall 派发给已注册 answerer（通道面短路
+ *   返回四值答案）；无人应答 fail-closed → unavailable（source=timeout——
+ *   headless 无人挂与超时同源）；answerer 自身抛错先落 decided 闭合审计对
+ *   再上抛（功能面 fail-closed 由管道守门段承担，本 catch 只护审计对完整）；
+ * - never 档：确定性拒绝回执（不发起问询——策略面定死「问都不问」；落
+ *   decided 单腿带 source=policy-never，审计可分辨）。
+ *
+ * 审批对 durable 落账（05 篇词汇 approval/asked + approval/decided）：经注入
+ * sink 接 session.append（装配层接线）——回放时决策已是既成事实，不重问。
+ *
+ * 升权审批（04 §8 严格变宽条）与守门审批共用本服务，reason 区分。
+ */
+import { randomUUID } from 'node:crypto';
+/** answerer 监听的活体事件名（waterfall 语义：能答者置 envelope.answer 且不调 next 短路；调 next() = 本行不接） */
+export const APPROVAL_ANSWER_EVENT = 'approval/answer';
+/**
+ * run 信号桥接（04 §9 run 信号透传条款——answerer 实现共用单源工具）：把
+ * ApprovalRequest.signal（发起 run 的取消信号）桥进 answerer 的 per-request
+ * controller——abort 同 reason，run abort 与竞速败腿收束汇入同一撤销面。
+ * 已 abort 的 signal 同步触发（abort 事件只发一次，只挂监听则死路）。
+ * @returns 监听摘除函数（ask 结算时调用——迟到 abort 落在已结算提问上
+ * no-op 无害，摘除是「任何结算路径摘监听」不变式纪律非正确性依赖）
+ */
+export function bridgeApprovalSignal(req, controller) {
+    const runSignal = req.signal;
+    if (runSignal === undefined)
+        return () => { };
+    const relay = () => controller.abort(runSignal.reason);
+    if (runSignal.aborted)
+        relay();
+    else
+        runSignal.addEventListener('abort', relay, { once: true });
+    return () => runSignal.removeEventListener('abort', relay);
+}
+/** 沙箱档宽度偏序秩（read-only ⊂ workspace-write ⊂ danger）——子集预批判定用 */
+const TIER_RANK = {
+    'read-only': 0,
+    'workspace-write': 1,
+    danger: 2,
+};
+/**
+ * outcome → durable 决议值映射。allowed-once 落日志记 approve——「批了这
+ * 一次」；always 单列（第二参数，条目真实写入时的决议值——与 approve 审计
+ * 语义不同）。
+ */
+function outcomeToDecision(outcome, alwaysWritten) {
+    if (outcome === 'allowed-once')
+        return alwaysWritten ? 'always' : 'approve';
+    switch (outcome) {
+        case 'rejected':
+            return 'reject';
+        case 'cancelled':
+            return 'cancel';
+        case 'unavailable':
+            return 'unavailable';
+    }
+}
+/**
+ * 组装审批服务。每次 ask 独立 approvalId（randomUUID）——审批对以此为关联
+ * 键落日志。构造时注册 approval/answer 事件词汇（幂等跳过——批 19c-1 修正：
+ * 「同 dispatch 重复组装是装配 bug」前提随多会话同栈装配废止〔in-process
+ * 子代理真工厂首例——每会话各装配一份审批服务共享词汇〕；归属路由恰一键
+ * 在 answerer 侧隔离他会话 ask，词汇层不承担装配检测）。
+ */
+export function createApprovalService(dispatch, opts = {}) {
+    const policy = opts.policy ?? 'ask';
+    const sink = opts.sink ?? { asked: () => { }, decided: () => { } };
+    if (!dispatch.isRegistered(APPROVAL_ANSWER_EVENT)) {
+        dispatch.registerEventNames([APPROVAL_ANSWER_EVENT]);
+    }
+    /** 会话粘性表（粘性第 1/2 款内存面——随服务生命周期即会话生命周期） */
+    const stickyGrants = new Map(); // 键 = target
+    const service = {
+        policyMode: policy,
+        async ask(req) {
+            // 粘性短路（04 §9 粘性段定形①——ask 之前）：同目标命中且请求档宽
+            // ≤ 已授档宽（第 1 款同指纹 = 恰等；第 2 款子集预批 = 请求更严被
+            // 宽批包含）→ 免问放行。不产生审批对（没有问就没有 asked/decided）。
+            const key = req.stickyKey;
+            if (key !== undefined) {
+                const grant = stickyGrants.get(key.target);
+                if (grant !== undefined && TIER_RANK[key.tier] <= TIER_RANK[grant.grantedTier]) {
+                    return {
+                        outcome: 'allowed-once',
+                        source: key.tier === grant.grantedTier ? 'sticky' : 'subset',
+                    };
+                }
+            }
+            const approvalId = randomUUID();
+            // 审批对第一腿：请求落日志（问询真实发生的开头；never 档不问不落）
+            if (policy !== 'never') {
+                sink.asked({ approvalId, summary: req.summary });
+            }
+            // 归属织入（恰一键 {sessionId}）+ approvalId——answerer 的消费面载荷
+            const enriched = {
+                ...req,
+                approvalId,
+                ...(opts.ownership !== undefined ? { ownership: opts.ownership } : {}),
+            };
+            let outcome;
+            let source;
+            // always 是否真实写入条目（决议落账值分流：真写入才落 'always'）
+            let alwaysWritten = false;
+            if (policy === 'never') {
+                // never：确定性拒绝，不派发 answerer（无人值守姿态没有「问谁」）；
+                // decided 单腿落账（source=policy-never——审计可分辨策略拒与人拒）
+                outcome = 'rejected';
+                source = 'policy-never';
+            }
+            else {
+                try {
+                    // ask：waterfall 派发——answerer 能答者写 envelope.answer 且短路
+                    // （不调 next 即已答）；全链无人写 = answer 字段 undefined
+                    const envelope = await dispatch.waterfall(APPROVAL_ANSWER_EVENT, { req: enriched });
+                    const answer = envelope.answer;
+                    if (answer === 'always') {
+                        // 「始终允许」：批准本次 + 授权写跨会话条目 + 会话粘性表入账。
+                        // 载荷无草案或写入回调未装配 = answerer 面本不该呈现该选项，防御
+                        // 收口视同 approve（零草案零副作用——含粘性表：一次性批准不产生
+                        // 会话免问面，与「decided 落 approve 而非 always」同口径）
+                        if (enriched.suggestedEntry !== undefined && opts.persistToolPolicy !== undefined) {
+                            opts.persistToolPolicy(enriched.suggestedEntry);
+                            alwaysWritten = true;
+                            // 粘性表入账（stickyKey 在场时）——会话内同指纹/子集后续免问
+                            if (key !== undefined) {
+                                stickyGrants.set(key.target, { target: key.target, grantedTier: key.tier });
+                            }
+                        }
+                        outcome = 'allowed-once';
+                        source = 'user';
+                    }
+                    else {
+                        outcome =
+                            answer === 'approve'
+                                ? 'allowed-once'
+                                : answer === 'reject'
+                                    ? 'rejected'
+                                    : answer === 'cancel'
+                                        ? 'cancelled'
+                                        : // 无人应答 fail-closed：unavailable 不是「稍后再试」，是本次
+                                            // 不放行（超时/无应答者同归 timeout 源——04 §9 无静默审批条）
+                                            'unavailable';
+                        source = 'user';
+                        if (outcome === 'unavailable')
+                            source = 'timeout';
+                    }
+                }
+                catch (cause) {
+                    // answerer 自身缺陷的错误路收口：先落 decided 闭合审批对
+                    // （unavailable = 确定收场，不留 asked 无 decided 的悬空审计记录）
+                    // 再原样上抛——功能面 fail-closed 由管道守门段承担（TOOL_GATE_FAILED
+                    // block），本 catch 只护审计对完整
+                    sink.decided({ approvalId, decision: 'unavailable', source: 'timeout' });
+                    throw cause;
+                }
+            }
+            // 审批对第二腿：决议落日志（never 档 asked 未落但 decided 单腿在——
+            // 审计面据 source=policy-never 分辨「问都没问」）
+            sink.decided({ approvalId, decision: outcomeToDecision(outcome, alwaysWritten), source });
+            return { outcome, source };
+        },
+    };
+    return service;
+}

package/dist/safety/bwrap.js

@@ -0,0 +1,123 @@
+/**
+ * L3 safety — Linux bwrap（bubblewrap）后端（04 §8 执行 seam 条）。
+ *
+ * 形态：拼 mount 参数。基础面 --ro-bind / /（全系统只读视图）+ 必要的虚拟
+ * 设备与隔离挂载；逐根追加 --bind（真实读写）——/tmp 恒 tmpfs（临时面
+ * 「能用不留痕」）。argv 生成纯函数可单测。
+ */
+import { spawnSync } from 'node:child_process';
+import { resolvePolicyRoots } from './sandbox.js';
+/**
+ * bwrap argv 前缀（不含策略差异）：全系统只读 + 虚拟 /dev /proc + 隔离 PID
+ * 命名空间。/tmp tmpfs 恒前置为第一条挂载：bwrap 按参数序建挂载，若 tmpfs
+ * /tmp 出现在某 /tmp 子路径根的 bind 之后，会整树遮蔽该 bind（berry 刀四
+ * CI 首跑红根因：bind 先、tmpfs 后 → 挂载点不可见；tmpfs 先、bind 后 →
+ * bwrap 在 tmpfs 上自动造出 dest 挂载点，根正确露出——顺序即正确性）。
+ */
+function bwrapBaseArgs() {
+    return [
+        '--tmpfs',
+        '/tmp',
+        '--ro-bind',
+        '/',
+        '/',
+        '--dev',
+        '/dev',
+        '--proc',
+        '/proc',
+        '--unshare-pid',
+        '--die-with-parent',
+    ];
+}
+/**
+ * 敏感件读 deny 遮蔽参数（04 §7 读侧 carve-out + 2026-09-08 P0① 定形）：
+ * `--ro-bind-try /dev/null <canonical 路径>` 逐件一对。要点：
+ * - SRC 恒在场（/dev/null 必在）、DEST 由 bwrap 自建（不必预先存在）；
+ *   `-try` 形 = DEST 缺席跳过不报错（保护面不含「目录不存在即失败」语义）；
+ * - 后位遮蔽：mount 点后建遮蔽前挂载——必须排在全部既有 bind 之后（末位
+ *   追加），否则被后续 bind 整树覆盖（顺序即正确性，与 base 的 tmpfs 前置
+ *   同一律）；
+ * - 遮蔽形下硬链攻击链结构性失败：link() 跨 mount 点对只读遮蔽源操作不可
+ *   达（内核 errno 多形不钉死——实机核验定形）。
+ */
+function bwrapDenyArgs(policy) {
+    const args = [];
+    for (const p of policy.denyReadFiles ?? [])
+        args.push('--ro-bind-try', '/dev/null', p);
+    return args;
+}
+/**
+ * 写 deny 遮蔽参数（04 §252 腿二——成熟度缺口 #9）：`--ro-bind-try <path>
+ * <path>` 逐件一对——把宿主该路径**只读**挂载遮蔽沙箱内同名路径（写即
+ * read-only file system 拒）。与读 deny 同律末位追加（后位遮蔽——排在全部
+ * 既有 bind 之后）；`-try` 形 DEST 缺席跳过（.git 未建的会话新建可写——
+ * 已文档化边界：新建仓非篡改既有版本史）。danger 档 `--bind / /` 后追加
+ * 同律（底线不交档位）。
+ */
+function bwrapDenyWriteArgs(policy) {
+    const args = [];
+    for (const p of policy.denyWritePaths ?? [])
+        args.push('--ro-bind-try', p, p);
+    return args;
+}
+/**
+ * 按策略生成 bwrap 参数前缀（纯函数）。两档统一消费 resolvePolicyRoots——
+ * 缺省按档位推导（read-only 空根 = 无 rw bind、workspace-write 工作区根族），
+ * 显式 writableRoots 覆盖在两档同等生效（与 seatbeltProfile 同律）。不变式：
+ * /tmp 恒 tmpfs 由 base 前缀承接；根恰为 /tmp 时跳过重复挂载；/tmp 子路径
+ * 根在 tmpfs 之上 bind 露出（见 base 前缀注记）。读 deny 遮蔽行末位追加
+ * （后位遮蔽——见 bwrapDenyArgs 注记）。
+ *
+ * danger 档形（04 §8 定形②「任何档一律」）：`--bind / /` 全盘真读写 +
+ * /dev /proc + 遮蔽行——跳过 tmpfs /tmp 与 --ro-bind /（danger 不走只读基
+ * 座）；--unshare-pid / --die-with-parent 卫生旗恒保留（/proc 同 uid 进程
+ * 面结构性不可见——c-4 泄漏面③同判收口）。
+ */
+export function bwrapArgs(policy) {
+    if (policy.mode === 'danger') {
+        return [
+            '--bind',
+            '/',
+            '/',
+            '--dev',
+            '/dev',
+            '--proc',
+            '/proc',
+            '--unshare-pid',
+            '--die-with-parent',
+            ...bwrapDenyArgs(policy),
+            ...bwrapDenyWriteArgs(policy),
+        ];
+    }
+    const args = [...bwrapBaseArgs()];
+    for (const root of resolvePolicyRoots(policy)) {
+        // 可写根与 fs fence 同源；/tmp 已由 base tmpfs 覆盖，其余根真实 bind
+        if (root !== '/tmp')
+            args.push('--bind', root, root);
+    }
+    args.push(...bwrapDenyArgs(policy), ...bwrapDenyWriteArgs(policy));
+    return args;
+}
+/**
+ * 组装 Linux bwrap 后端。
+ * 后端差异数据化下发：
+ * - 策略拒绝 → stderr 含 "read-only file system"（只读 bind 上的写标准 errno 文案）；
+ * - runner 自身失败（bwrap 未装/参数错/权限不够）→ stderr 前缀 "bwrap: "。
+ */
+export function createBwrapBackend() {
+    return {
+        id: 'bwrap',
+        enforcement: 'full',
+        denialSignatures: ['read-only file system'],
+        runnerFailureRules: [{ fatalSignatures: ['bwrap: '] }],
+        wrap(argv, policy) {
+            return ['bwrap', ...bwrapArgs(policy), '--', ...argv];
+        },
+        probe(timeoutMs) {
+            // 功能性探测：真跑一次 read-only 包装的 /bin/true——status 0 才算后端可用
+            const confined = ['bwrap', ...bwrapArgs({ mode: 'read-only', workspaceRoot: '/' }), '--', '/bin/true'];
+            const result = spawnSync(confined[0], confined.slice(1), { timeout: timeoutMs });
+            return result.status === 0;
+        },
+    };
+}

package/dist/safety/codes.js

@@ -0,0 +1,57 @@
+/**
+ * safety 域错误码注册（04 §8 沙箱栈——SANDBOX_ 前缀族首批）。
+ *
+ * 前缀族明列见 contracts/errors.ts ERROR_CODE_PREFIXES（02 §5.3 #1）；码名清
+ * 单与语义真源 = 02 篇 §5.3 SANDBOX_ 族明列段（2026-09-06 safety 纵切批）。
+ * 本文件由模块公开面 index.ts 引入（注册纪律：写入点文件必须实际 import 本
+ * 文件注册才发生——与 tools/llm/session 的 codes.ts 同款）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'SANDBOX_UNAVAILABLE',
+        module: 'safety',
+        description: '策略要求沙箱而后端链空/全部探测失败——fail-closed 拒执行绝不裸跑（04 §8 执行 seam 条）',
+    },
+    {
+        code: 'SANDBOX_MODE_INVALID',
+        module: 'safety',
+        description: 'sandbox/mode 事件折叠遇非三档词汇——静默跳过坏事件会沿用旧档属 fail-open，宁响亮失败（04 §8 策略三级解析条）',
+    },
+    {
+        code: 'SANDBOX_ESCALATION_INVALID',
+        module: 'safety',
+        description: '升权参数残缺：sandbox_permissions 与 justification 不成对非空 / 目标档非法 / 非严格变宽（04 §8 严格变宽升权条）',
+    },
+    // DANGER_ 六码（04 §13 危险工具闸——02 §5.3 族明细 2026-09-09 #4 规范先行批同笔入册）
+    {
+        code: 'DANGER_CONSENT_ABSENT',
+        module: 'safety',
+        description: '危险闸 consent 缺席（fail-closed 缺省——缺席 = 闸落地零配置零行为变化，deny 路径即原「阻塞转人审」语义；指路 /danger approve 签发）',
+    },
+    {
+        code: 'DANGER_CONSENT_INVALID',
+        module: 'safety',
+        description: '危险闸 consent 过期或 mandate 漂移（哈希不符——批了 A 契约不等于批了 B 契约；两形同码：过期不自动续不静默宽限、漂移即死——重签唯一出路）',
+    },
+    {
+        code: 'DANGER_HALTED',
+        module: 'safety',
+        description: '危险闸 HALT 哨兵在场（存在性判内容不解析、stat 不可达按在场——touch 即全停；指路删除数据目录下 HALT 文件恢复）',
+    },
+    {
+        code: 'DANGER_TARGET_DENIED',
+        module: 'safety',
+        description: '危险闸动作/目标不在 mandate 值域（action 越闭集或 target 不匹配 targets——04 §13 闸序步 4）',
+    },
+    {
+        code: 'DANGER_CAP_EXCEEDED',
+        module: 'safety',
+        description: '危险闸当日成功帽已满（allow-succeeded 计数 UTC 日界恢复——账本派生无第二状态；提帽须重签 consent）',
+    },
+    {
+        code: 'DANGER_LEDGER_CORRUPT',
+        module: 'safety',
+        description: '危险闸审计账本链坏拒续写（改/删任何历史行则哈希传播破坏其后全部——账本完整性先于可用性；修复归人手，截断/重建是人工决策）',
+    },
+]);