berry-agent 0.1.0-alpha.1

package/dist/safety/sandbox.js

@@ -0,0 +1,214 @@
+/**
+ * L3 safety — 沙箱 seam（04 §8 执行 seam 与 fail-closed 条）。
+ *
+ * confine(argv, policy) → ConfinedArgv 是纯包装接口：后端无状态、策略逐调用
+ * 携带、消费方（bash 工具等）自行 spawn——沙箱不造进程，只约束进程。后端
+ * 差异数据化下发（denialSignatures / runnerFailureRules），消费方零后端知识。
+ * 无可用后端抛 SANDBOX_UNAVAILABLE——fail-closed，绝不静默裸跑。
+ *
+ * 本文件同时持有：effective mode 三级解析的 fold 半边（显式档是调用方的
+ * 事，会话 override 事件与部署缺省在此折叠）+ 升权词汇（严格变宽阶梯 /
+ * 成对必填校验 / 统一拒绝标记）——bash 与 fs 两族工具共享同一 home，防文
+ * 案与顺序漂移。
+ *
+ * 与 berry 分叉注记：①第三档定名 `danger`（短名——04 §8 拍板）；②折叠
+ * 缺省档 = workspace-write（04 §8「个人开发机形态的实用缺省」；berry 的
+ * read-only 兜底不承）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { canonicalPath, deriveWritableRoots } from './roots.js';
+import { sensitiveReadFiles } from './sensitive.js';
+// 平台链引用（函数体内才调用，无顶层互调——与后端文件的双向引用安全）
+import { createSeatbeltBackend } from './seatbelt.js';
+import { createBwrapBackend } from './bwrap.js';
+/**
+ * 策略实际生效的可写根列表（缺省按档位推导；两个后端与 fs fence 共用同一
+ * 来源。read-only 档空根——Seatbelt read-only profile 本就全拒写（不吃根列
+ * 表）、Bwrap 空根即无 rw bind）。
+ */
+export function resolvePolicyRoots(policy) {
+    return policy.writableRoots ?? deriveWritableRoots(policy.workspaceRoot, policy.mode);
+}
+/* ------------------------------------------------------------------ */
+/* 三级解析的 fold 半边（04 §8 策略三级解析条）。                          */
+/* 实况注记（2026-09-11 遗漏扫描批定形）：本函数 = 词先锚定的读位半边—— */
+/* sandbox/mode 落账词在册（05 §1.1）而 v1 无会话中切档面（TUI/webui/CLI  */
+/* 均无切档命令），零 append 写点；生产生效档 = boot 闭包 CLI 旗标形      */
+/* （conversation-stack options.sandboxMode——run-entry --read-only 唯一 */
+/* 注入源）。会话策略中间档随切档面立题接线，届时本函数即 fold 读点。     */
+/* ------------------------------------------------------------------ */
+/** 三档词汇守卫（fold 与配置解析共用；拼错档位必须响亮失败） */
+export function isSandboxMode(value) {
+    return value === 'read-only' || value === 'workspace-write' || value === 'danger';
+}
+/**
+ * 折叠会话 sandbox/mode 事件序列 → 生效档（最后一条胜出）。缺省档 =
+ * workspace-write（04 §8「个人开发机形态的实用缺省」——与 berry 的
+ * read-only 兜底分叉）。载荷不在三档词汇内直接抛 SANDBOX_MODE_INVALID——
+ * 静默跳过坏事件会沿用旧档，是 fail-open。
+ */
+export function resolveEffectiveMode(events, fallback = 'workspace-write') {
+    let mode = fallback;
+    for (const event of events) {
+        if (!isSandboxMode(event.mode)) {
+            throw new BaseError('SANDBOX_MODE_INVALID', `sandbox/mode 事件档位非法：${JSON.stringify(event.mode)}（三档词汇：read-only / workspace-write / danger）`);
+        }
+        mode = event.mode;
+    }
+    return mode;
+}
+/**
+ * 组装沙箱服务。选后端规则（单候选链不预探测）：
+ * - 空链 → confine 抛 SANDBOX_UNAVAILABLE（fail-closed）；
+ * - 单候选 → 直接使用不预探测（探测有 spawn 开销，且坏了 spawn 会响亮
+ *   失败，runnerFailureRules 负责分类）；
+ * - 多候选 → 按注册序找首个 probe 通过者（无 probe 视为可用）——探测结果
+ *   按后端缓存一次，探测失败的候选不重试。
+ */
+export function createSandboxService(opts = {}) {
+    /** 后端链（注册序即优先序） */
+    const chain = [...(opts.backends ?? createDefaultBackends())];
+    /** probe 结果缓存（backend.id → 布尔；注销即清除） */
+    const probeCache = new Map();
+    /**
+     * 策略 enrich：读 deny 单源补位 + 数据目录写 deny 恒并入。
+     * - 读侧（04 §7）：未显式携带 denyReadFiles 且装配持有 dataDir 时，以敏
+     *   感件集单源补位。显式携带（含空数组）恒胜出——测试/宿主覆盖位不与
+     *   单源打架。
+     * - 写侧（04 §7/§14「模型不可自授」的 bash 腿）：dataDir 在场即无条件
+     *   并入 denyWritePaths——danger 档 allow-default 下 `> ~/.berry-agent/
+     *   tool-policy.json`〔原 allowlist.json——更名批同笔〕自授面此前敞门，本条封死；恒 = 平台底线不交装配
+     *   裁量，调用方携带值与 enrich 取并集去重。
+     */
+    const enrichPolicy = (policy) => {
+        let enriched = policy;
+        if (enriched.denyReadFiles === undefined && opts.dataDir != null) {
+            enriched = { ...enriched, denyReadFiles: sensitiveReadFiles(opts.dataDir) };
+        }
+        if (opts.dataDir != null) {
+            const dataDirCanonical = canonicalPath(opts.dataDir);
+            const existing = enriched.denyWritePaths ?? [];
+            if (!existing.includes(dataDirCanonical)) {
+                enriched = { ...enriched, denyWritePaths: [...existing, dataDirCanonical] };
+            }
+        }
+        return enriched;
+    };
+    /** 单个后端的可用性判定（无 probe = 视为可用；结果缓存一次） */
+    const isAvailable = (backend) => {
+        if (!backend.probe)
+            return true;
+        if (!probeCache.has(backend.id)) {
+            // 功能性探测：真跑一次 read-only 包装（后端实现负责），status 0 才证明内核确实执行
+            probeCache.set(backend.id, backend.probe(PROBE_TIMEOUT_MS));
+        }
+        return probeCache.get(backend.id);
+    };
+    const service = {
+        confine(argv, policy) {
+            if (chain.length === 0) {
+                // fail-closed：没有后端就拒绝执行，绝不静默裸跑（04 §8——任何档一律，
+                // danger 不豁免：换档不是绕后端的路）
+                throw new BaseError('SANDBOX_UNAVAILABLE', `无可用沙箱后端，拒绝裸跑（后端链为空；${policy.mode} 档一律经沙箱——可安装沙箱后端）`);
+            }
+            // 单候选直接用；多候选按 probe 仲裁
+            const backend = chain.length === 1 ? chain[0] : (chain.find((b) => isAvailable(b)) ?? undefined);
+            if (!backend) {
+                throw new BaseError('SANDBOX_UNAVAILABLE', `后端链全部探测失败（${chain.map((b) => b.id).join(' → ')}），拒绝以 ${policy.mode} 档裸跑`);
+            }
+            return {
+                argv: backend.wrap(argv, enrichPolicy(policy)),
+                enforcement: backend.enforcement,
+                denialSignatures: backend.denialSignatures,
+                runnerFailureRules: backend.runnerFailureRules,
+            };
+        },
+        registerBackend(backend) {
+            chain.push(backend);
+            let done = false;
+            return () => {
+                if (done)
+                    return;
+                done = true;
+                // 同位注销护栏：仅当链尾仍是本后端时弹出（防误撤他者注册的同 id 后端）
+                if (chain[chain.length - 1] === backend) {
+                    chain.pop();
+                    probeCache.delete(backend.id);
+                }
+            };
+        },
+        listBackends() {
+            return [...chain];
+        },
+    };
+    return service;
+}
+/** 功能性探测超时（毫秒）：真跑一次包装不该超过这个时长，超过视为不可用 */
+const PROBE_TIMEOUT_MS = 5_000;
+/** 平台默认后端链（04 §8：macOS Seatbelt / Linux bwrap；其余平台无后端——confine fail-closed，如实空链不假装覆盖） */
+export function createDefaultBackends() {
+    if (process.platform === 'darwin')
+        return [createSeatbeltBackend()];
+    if (process.platform === 'linux')
+        return [createBwrapBackend()];
+    return [];
+}
+/* ------------------------------------------------------------------ */
+/* 升权词汇（04 §8 严格变宽升权条；bash 与 fs 共享同一 home）            */
+/* ------------------------------------------------------------------ */
+/** 严格变宽阶梯：只许变宽不许变窄绕行（read-only→两档 / workspace-write→danger / danger 无更宽） */
+export const WIDER_MODES = {
+    'read-only': ['workspace-write', 'danger'],
+    'workspace-write': ['danger'],
+    danger: [],
+};
+/** 可请求的升权目标档（= 比受限两档更宽的「两档受限/全放」词汇中更宽者） */
+export const ESCALATION_TARGETS = ['workspace-write', 'danger'];
+/**
+ * 升权参数校验（04 §8 严格变宽条全在此）：sandbox_permissions 与
+ * justification 强制成对非空（空句同非法）；目标必须是合法升权档；必须
+ * 严格变宽（非变宽请求不弹窗直接拒，防窄绕行与同档重试噪音）。
+ */
+export function validateEscalationArgs(args) {
+    const perm = args.sandboxPermissions?.trim();
+    const just = args.justification?.trim();
+    // 成对非空：一边有一边无 = 参数残缺，不给问询机会（04 §8「拒在 schema 段」）
+    if (!perm && !just) {
+        throw new BaseError('SANDBOX_ESCALATION_INVALID', '升权请求缺 sandbox_permissions 与 justification（两者必须成对提供）');
+    }
+    if (!perm || !just) {
+        throw new BaseError('SANDBOX_ESCALATION_INVALID', `升权参数不成对：sandbox_permissions=${JSON.stringify(perm ?? '')} justification=${JSON.stringify(just ?? '')}（两者必须成对非空）`);
+    }
+    if (!isSandboxMode(perm) || !ESCALATION_TARGETS.includes(perm)) {
+        throw new BaseError('SANDBOX_ESCALATION_INVALID', `升权目标档非法：${perm}（合法目标：${ESCALATION_TARGETS.join(' / ')}）`);
+    }
+    if (!WIDER_MODES[args.current].includes(perm)) {
+        // 非严格变宽（变窄或同档）：不问询直接拒——变窄绕行与无意义重试都不进审批
+        throw new BaseError('SANDBOX_ESCALATION_INVALID', `升权请求非严格变宽：${args.current} → ${perm}（当前档只可升至 ${WIDER_MODES[args.current].join(' / ') || '（已是最高档）'}）`);
+    }
+    return { target: perm, justification: just };
+}
+/** 统一拒绝标记：被策略拒绝时回给模型的固定句式（工具结果与守门 block 共用） */
+export function sandboxDenialMarker(mode) {
+    return `[sandbox: file access denied under ${mode}]`;
+}
+/** 升权提示标记：拒绝后引导模型基于真实 denial 走正道（明确不许投机） */
+export function escalationHintMarker() {
+    return '[sandbox hint: 若确需本次访问，在同一工具调用中同时提供 sandbox_permissions（workspace-write 或 danger）与 justification 发起升权；拒绝是最终的——不许绕路、不许无真实拒绝依据的投机升权]';
+}
+/**
+ * 走审批的升权序列：校验产物 → approval.ask（reason 注明目标档与理由）→
+ * 原样返回结果元数据。allowed-once 的「只授予当次调用」由调用方保证（把
+ * 返回的 target 仅用于本次 spawn，不写回会话 override）。
+ */
+export function requestEscalation(approval, input) {
+    return approval.ask({
+        summary: `沙箱升权 ${input.current} → ${input.target}`,
+        reason: `目标档 ${input.target}；理由：${input.justification}`,
+        toolName: input.toolName,
+        toolCallId: input.toolCallId,
+        // run 取消信号随 ask 载荷透传（undefined 不携带）
+        ...(input.signal !== undefined ? { signal: input.signal } : {}),
+        ...(input.suggestedEntry !== undefined ? { suggestedEntry: input.suggestedEntry } : {}),
+    });
+}

package/dist/safety/seatbelt.js

@@ -0,0 +1,88 @@
+/**
+ * L3 safety — macOS Seatbelt 后端（04 §8 执行 seam 条：后端 = 数据 + 包装）。
+ *
+ * 形态：拼 SBPL profile 字符串，argv = ['sandbox-exec','-p',profile,'--',...argv]。
+ * profile 生成是纯函数（可单测不 spawn）；probe 用功能性探测——真跑一次
+ * read-only 包装（版本检查会漏「有 syscall 但拒绝执行」的内核形态）。
+ */
+import { spawnSync } from 'node:child_process';
+import { resolvePolicyRoots } from './sandbox.js';
+/** SBPL 字符串字面量转义（SBPL 语法内 " 与 \ 需反斜杠转义） */
+function sbplString(value) {
+    return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+/** read-only 基座 SBPL：全默认放行 + 拒写 + /dev/null 例外（大量 CLI 静默写 /dev/null） */
+export function seatbeltReadOnlyProfile() {
+    return ['(version 1)', '(allow default)', '(deny file-write*)', '(allow file-write* (literal "/dev/null"))'].join('\n');
+}
+/**
+ * 敏感件读 deny 行（04 §7 读侧 carve-out + 2026-09-08 P0① 实机核验定形）：
+ * `(deny file-read* (literal "<canonical 路径>"))` 逐件一行。要点：
+ * - 末位追加——SBPL last-match-wins，末位 deny 压过此前一切 allow；
+ * - literal 必须是符号链解析后的真实路径（/tmp 拼写字面 miss /private/tmp
+ *   实体——denyReadFiles 数据源 sensitiveReadFiles 已 canonical 派生）；
+ * - 单行 deny 结构性覆盖硬链攻击链：link() 对源路径即触发 file-read* 判定
+ *   ——「链时即拦」，无需独立 link 算子（实机核验：ln 直接 Operation not
+ *   permitted）。
+ */
+function seatbeltDenyLines(policy) {
+    return (policy.denyReadFiles ?? []).map((p) => `(deny file-read* (literal ${sbplString(p)}))`);
+}
+/**
+ * 写 deny 行（04 §252 腿二——成熟度缺口 #9）：`(deny file-write* (subpath
+ * "<canonical 路径>"))` 逐件一行，恒末位追加（SBPL last-match-wins——压过
+ * 此前一切 allow，含 workspace-write 档的逐根 allow 与 danger 档的
+ * allow default；subpath 覆盖整树）。read-only 档与全局 `(deny file-write*)`
+ * 并存冗余无害——三档统一形。
+ */
+function seatbeltDenyWriteLines(policy) {
+    return (policy.denyWritePaths ?? []).map((p) => `(deny file-write* (subpath ${sbplString(p)}))`);
+}
+/**
+ * 按策略生成 SBPL profile（纯函数）。两档统一消费 resolvePolicyRoots——缺省
+ * 按档位推导（read-only 空根 = 纯拒写、workspace-write 工作区根族），显式
+ * writableRoots 覆盖在两档同等生效（字段契约本义：e1 式宿主只读档携刚需根
+ * 即走此路——berry 真机冒烟实证原 mode 分支吃不到显式根的教训照搬防御）。
+ *
+ * danger 档形（04 §8 定形②「任何档一律」）：(version 1) + (allow default)
+ * + 读 deny 行——无拒写、无逐根 allow；danger 同过最小读 deny profile。
+ * 写 deny 行两档同律恒末位（含 danger——04 §252 底线不交档位）。
+ */
+export function seatbeltProfile(policy) {
+    const denies = seatbeltDenyLines(policy);
+    const writeDenies = seatbeltDenyWriteLines(policy);
+    if (policy.mode === 'danger') {
+        return ['(version 1)', '(allow default)', ...denies, ...writeDenies].join('\n');
+    }
+    const allows = resolvePolicyRoots(policy)
+        .map((root) => `(allow file-write* (subpath ${sbplString(root)}))`)
+        .join('\n');
+    return allows
+        ? [seatbeltReadOnlyProfile(), allows, ...denies, ...writeDenies].join('\n')
+        : [seatbeltReadOnlyProfile(), ...denies, ...writeDenies].join('\n');
+}
+/**
+ * 组装 macOS Seatbelt 后端。
+ * 后端差异数据化下发（消费方零后端知识）：
+ * - 策略拒绝 → stderr 含 "operation not permitted"（seatbelt 拒写标准句）；
+ * - runner 自身失败（profile 语法错/内核拒绝加载）→ stderr 前缀 "sandbox-exec: "。
+ */
+export function createSeatbeltBackend() {
+    return {
+        id: 'seatbelt',
+        enforcement: 'full',
+        denialSignatures: ['operation not permitted'],
+        runnerFailureRules: [{ fatalSignatures: ['sandbox-exec: '] }],
+        wrap(argv, policy) {
+            const profile = seatbeltProfile(policy);
+            return ['sandbox-exec', '-p', profile, '--', ...argv];
+        },
+        probe(timeoutMs) {
+            // 功能性探测：真跑一次 read-only 包装的 /usr/bin/true——status 0 才证明
+            // 内核确实执行了 profile（不是「命令存在」而是「策略真的生效」）
+            const confined = ['sandbox-exec', '-p', seatbeltReadOnlyProfile(), '--', '/usr/bin/true'];
+            const result = spawnSync(confined[0], confined.slice(1), { timeout: timeoutMs });
+            return result.status === 0;
+        },
+    };
+}

package/dist/safety/sensitive.js

@@ -0,0 +1,34 @@
+/**
+ * L3 safety — 敏感件读集单源（04 §7 读侧 carve-out + 03 §10.9 凭证代管 + 04 §9 allowlist）。
+ *
+ * SENSITIVE_READ_BASENAMES = dataDir 直下「恒不可读」件名的唯一字面源，消费
+ * 面 = fs 工具族读脸（装配层注入 tools）与沙箱 profile 读 deny（confine
+ * enrich）两条执法腿的同源数据。
+ *
+ * 对拍锚（字面镜像）：persist/secret-box.ts 的 SECRET_KEY_BASENAME 与
+ * host/tool-policy-store.ts 的 TOOL_POLICY_BASENAME。safety 不 import
+ * persist/host（DAG 边表——与 gate.dataDir 必填注入同律），字面同步由对拍
+ * 测试互证（漂移即红）。
+ */
+import { join } from 'node:path';
+import { canonicalPath } from './roots.js';
+/**
+ * 敏感件 basename 集（canonical dataDir 直下）。
+ * - secret.key：会话密钥（03 §10.9 / persist secret-box——密文与凭据的根钥）；
+ * - tool-policy.json：策略表面（04 §9——免问/拒绝条目本体泄出即审批面测绘；
+ *   2026-09-11 审批分档批更名，原 allowlist.json）；
+ * - allowlist.json：旧载体名留置保护（更名批共存序「旧文件留置不删」——
+ *   旧文件在数据目录滞留期间同不可读，防升格遗存读敞门）。
+ * canonical 派生不可省：literal deny（seatbelt）与 ro-bind 遮蔽（bwrap）
+ * 都必须落在符号链解析后的真实路径上才生效（/tmp → /private/tmp 字面
+ * miss——2026-09-08 实机核验定形）。
+ */
+export const SENSITIVE_READ_BASENAMES = ['secret.key', 'tool-policy.json', 'allowlist.json'];
+/**
+ * 敏感件 canonical 绝对路径集（路径判与 inode 判的比对基准；沙箱读 deny 行
+ * 的数据源）。逐件 canonical 派生而非整目录——canonicalPath(dataDir) 目录
+ * 存在时两者等价，目录缺席（首启未建）时逐件回退最近在场祖先仍稳定。
+ */
+export function sensitiveReadFiles(dataDir) {
+    return SENSITIVE_READ_BASENAMES.map((name) => canonicalPath(join(dataDir, name)));
+}

package/dist/safety/tool-policy.js

@@ -0,0 +1,203 @@
+/**
+ * L3 safety — 跨会话工具策略表匹配引擎（04 §9 粘性第 3/4 款 + 2026-09-11
+ * 审批分档批定形块③④——纯函数半边；原「allowlist 匹配引擎」随文件更名
+ * tool-policy.json 同步升格「工具策略表」概念）。
+ *
+ * 定位：条目双面——**allow = advisory 免问面**（只影响「问不问」，不折算
+ * 执行权：fence / 可写根 / carve-out 硬拒面 / 执行段照走）；**deny = 用户
+ * 主权硬拒**（不可被 sticky / allow / policy-never / sandbox danger 任何
+ * 后续面翻转——④deny 优先律：首个 deny 命中恒最先且硬拒，reason
+ * `policy-deny:<条目序>`）。deny 永远最高，本引擎 deny 命中即终局返回。
+ * 条目落用户配置层（`~/.berry-agent/tool-policy.json`，非模型可写面——
+ * §7 fence；存储读写接线在 host 件，本文件定形状与判定语义）。
+ *
+ * 三族匹配器（04 §9 粘性段定形③，族分派沿旧）：
+ * - fs 族（write / edit）：条目 pattern = 路径前缀（相对则锚 workspace）——
+ *   本次调用**全部**写目标都落在前缀内才命中（多路径 all-or-nothing，保守）；
+ * - bash 族：条目 pattern = 命令词干（≤2 词：命令 [子命令]）——剥壳语义全
+ *   集见 commandStem（环境变量前缀剥除 / shell 包装穿透一层 / 管道与串接
+ *   即不可判定 / 任何 flag 即不可判定——v1 无「已知 flag 白名单」，白名单
+ *   随真实命令谱定稿；git -C 换仓走私被「flag 即 miss」自然覆盖）；
+ * - 其余工具族：工具名整匹配（pattern 字段忽略，留位后续扩族）。
+ *
+ * TTL（粘性第 4 款）：**仅 allow 条目**——`expiresAt`（Unix 毫秒）过期 =
+ * 未命中（回落 ask），缺省 = 用户显式选择永久；deny 条目**无 TTL**（带
+ * `expiresAt` 的 deny 条目属坏形——deny 自动过期 = 自动变宽松，方向性不
+ * 允许；引擎按逐条剔除语义跳过，与读侧坏形剔除同形）。
+ *
+ * 档位限定（定形块③偏序包含判）：条目 `effect?` 缺席 = 全档；在场时——
+ * **allow 条目窄化自限**（只作用于该档及以下：write 档 allow 条目不覆盖
+ * exec 调用）、**deny 条目覆写扩面**（作用于该档及以上：write 档 deny
+ * 条目覆盖 write+exec 调用）——方向性同律：allow 不自动放宽、deny 不自动
+ * 收紧。
+ */
+import { basename, resolve as resolvePath, sep } from 'node:path';
+import { TOOL_TIER_RANK } from '../contracts/index.js';
+import { canonicalPath } from './roots.js';
+/** fs 写路径工具族（与 gate 守门行认知的写意图工具同源；导出供守门行判定收窄共用） */
+export const FS_WRITE_TOOLS = new Set(['write', 'edit']);
+/**
+ * 命中来源标注串（ap-3 三面同源单源）：守门行 deny 理由 / allow 免问
+ * allowReason、/approval explain 干跑呈现、session_status 整名族干跑呈现
+ * ——三面共用本函数，执法与呈现漂移在结构上不可能（同函数同条目同串）。
+ */
+export function policyHitNote(match) {
+    return `policy-${match.entry.decision}:${match.index}`;
+}
+/**
+ * 判定入口（04 §9 定形块④评估序的纯函数半边）：**deny 命中恒最先且终局**
+ * ——全表扫描中首个 deny 命中即返回（**序在 allow 之前恒胜**：条目序不构成
+ * deny 与 allow 的优先级，deny 是不同维度的主权裁决）；无 deny 命中时返回
+ * 首个未过期 allow 命中；无命中返回 undefined。
+ * 保守原则：任何不可判定（管道/串接/引号/flag/条目形状非法/deny 带 TTL）
+ * 都按未命中处理——照问照审，不做假静态分析（deny 坏形剔除同向：被剔除的
+ * deny 条目不参与评估，其余条目照常）。
+ */
+export function matchToolPolicy(entries, input, now) {
+    let firstAllow;
+    for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index];
+        if (entry.tool !== input.tool)
+            continue;
+        // 偏序包含判（③）：缺席全档；allow 及以下 / deny 及以上
+        if (!tierIncluded(entry, input.effect))
+            continue;
+        // deny 条目带 expiresAt = 坏形 → 逐条剔除（跳过继续扫，非整档失效）。
+        // decision 缺席防御：仅精确 'deny' 走硬拒腿（旧形行经读侧归一为 allow）
+        if (entry.decision === 'deny') {
+            if (entry.expiresAt !== undefined)
+                continue;
+            if (entryMatches(entry, input))
+                return { index, entry };
+            continue;
+        }
+        // TTL（粘性第 4 款，仅 allow）：过期 = 未命中（回落 ask；过期条目由配置面提示清理）
+        if (entry.expiresAt !== undefined && now >= entry.expiresAt)
+            continue;
+        if (firstAllow === undefined && entryMatches(entry, input))
+            firstAllow = { index, entry };
+    }
+    return firstAllow;
+}
+/** 档位偏序包含判（③）：allow 条目只作用于该档及以下（窄化自限）、deny 条目作用于该档及以上（覆写扩面） */
+function tierIncluded(entry, callEffect) {
+    if (entry.effect === undefined)
+        return true;
+    const callRank = TOOL_TIER_RANK[callEffect];
+    const entryRank = TOOL_TIER_RANK[entry.effect];
+    return entry.decision === 'deny' ? callRank >= entryRank : callRank <= entryRank;
+}
+/** 三族匹配分派（fs 前缀 all-or-nothing / bash 词干 / 整名族） */
+function entryMatches(entry, input) {
+    if (FS_WRITE_TOOLS.has(entry.tool)) {
+        return fsPrefixHit(entry.pattern, input);
+    }
+    if (entry.tool === 'bash') {
+        const command = input.bashCommand ?? '';
+        return command.trim().length > 0 && matchesCommandStem(entry.pattern ?? '', command);
+    }
+    // 整名族：工具名相等即命中（TTL/档位判已在前）
+    return true;
+}
+/** fs 族判定：全部写目标落在条目前缀内（前缀到路径分隔边界——/app 不匹配 /apple）；pattern 缺席/不可解析 = 条目无效 = 不命中 */
+function fsPrefixHit(pattern, input) {
+    if (typeof pattern !== 'string' || pattern.length === 0)
+        return false;
+    const paths = input.writePaths ?? [];
+    if (paths.length === 0)
+        return false; // 无写意图不归本族（整名语义由他族条目表达）
+    let prefix;
+    try {
+        // 相对 pattern 锚 workspace；canonical 化与 fence/根推导同源
+        prefix = canonicalPath(resolvePath(input.workspace ?? process.cwd(), pattern));
+    }
+    catch {
+        return false; // pattern 不可解析 = 条目无效 = 不命中
+    }
+    return paths.every((p) => p === prefix || p.startsWith(prefix + sep));
+}
+/** 不可判定字符集：管道 / 串接 / 重定向 / 命令替换 / 换行——任一出现即照问 */
+const INDETERMINATE = /[|;&<>$(`)\n]/;
+/** 引号字符（剥离 shell 包装引号后仍残留即视为不可判定） */
+const QUOTES = /["'`]/;
+/** shell 包装器名（穿透一层取内层命令） */
+const WRAPPERS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh']);
+/** 包装器选项中含 c（-c / -lc / -ec——payload 在下一个词） */
+const WRAPPER_C_OPTION = /^-[a-z]*c[a-z]*$/;
+/**
+ * 剥壳取主命令词干（≤2 词：命令 [子命令]）——「始终允许」bash 草案生成器
+ * （04 §9 粘性段定形③：fs = 精确路径、bash = 剥壳词干——与 matchesCommandStem
+ * 同源同实现，剥壳全集共享，双实现漂移结构性不可能）。不可判定（管道/串接/
+ * 重定向/命令替换/换行/残留引号/flag——全局无害三件除外）返回 undefined：
+ * 剥不出干净词干即无草案，「始终允许」选项不呈现。
+ */
+export function commandStem(command) {
+    // 换行（含 \r）是命令分隔符，且会被下方 \s+ 分词吞掉——必须先于分词对原文
+    // 检查（INDETERMINATE 其余字符均非空白、分词后仍存活；唯换行需要前置）
+    if (/[\r\n]/.test(command))
+        return undefined;
+    // 剥壳：环境变量前缀赋值 + shell 包装穿透一层
+    let tokens = command.trim().split(/\s+/).filter(Boolean);
+    while (tokens.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=\S*$/.test(tokens[0])) {
+        tokens = tokens.slice(1);
+    }
+    if (tokens.length === 0)
+        return undefined;
+    let head = basename(tokens[0]);
+    if (WRAPPERS.has(head)) {
+        // 找 -c 类选项后的 payload 词（选项序列之后的第一个非选项词）
+        let i = 1;
+        let sawC = false;
+        while (i < tokens.length && tokens[i].startsWith('-') && WRAPPER_C_OPTION.test(tokens[i])) {
+            sawC = true;
+            i += 1;
+        }
+        if (sawC && i < tokens.length) {
+            // payload = 选项后全部剩余词拼接（引号内空格已被分词拆散——拼接还原后再剥引号）
+            let payload = tokens.slice(i).join(' ');
+            // 剥整段包裹引号；引号内含空白则重新分词（只此一层，不递归）
+            if (payload.length >= 2 &&
+                ((payload.startsWith("'") && payload.endsWith("'")) || (payload.startsWith('"') && payload.endsWith('"')))) {
+                payload = payload.slice(1, -1);
+            }
+            tokens = payload.split(/\s+/).filter(Boolean);
+            head = tokens.length > 0 ? basename(tokens[0]) : '';
+        }
+    }
+    if (tokens.length === 0 || head === '')
+        return undefined;
+    // 不可判定：命令全文任一危险字符 / 残留引号 → 无词干（草案不生成）
+    const peeled = tokens.join(' ');
+    if (INDETERMINATE.test(peeled) || QUOTES.test(peeled))
+        return undefined;
+    // 剩余参数保守判定：flag 即无词干（--help/-h/--version 三件无害除外）
+    const rest = tokens.slice(1);
+    for (const arg of rest) {
+        if (arg.startsWith('-') && arg !== '--help' && arg !== '-h' && arg !== '--version')
+            return undefined;
+    }
+    // 词干 = 主命令 [子命令]（≤2 词；子命令存在且非 flag 才纳入）
+    const cmd = basename(tokens[0]);
+    const sub = tokens[1];
+    return sub !== undefined && !sub.startsWith('-') ? `${cmd} ${sub}` : cmd;
+}
+/**
+ * bash 族判定：剥壳与不可判定全权委托 commandStem（同源同实现——草案生成
+ * 与本判定共用同一套剥壳全集）；本函数只做 pattern（≤2 词）对词干的**逐词
+ * 前缀对齐**——pattern 单词（如 `git`）匹配「该命令 + 任意非 flag 形参」
+ * （`git status` 命中 `git` 条目），双词条目（`git push`）要求词干恰好两词
+ * 且逐词相等。
+ */
+function matchesCommandStem(pattern, command) {
+    // pattern 解析：≤2 词（命令 [子命令]）；超长/空 = 条目无效
+    const patternTokens = pattern.trim().split(/\s+/).filter(Boolean);
+    if (patternTokens.length === 0 || patternTokens.length > 2)
+        return false;
+    const stem = commandStem(command);
+    if (stem === undefined)
+        return false; // 剥不出干净词干（不可判定）即 miss
+    const stemTokens = stem.split(' ');
+    if (patternTokens.length > stemTokens.length)
+        return false;
+    return patternTokens.every((token, i) => token === stemTokens[i]);
+}

package/dist/safety/types.js

@@ -0,0 +1,13 @@
+/**
+ * L3 safety — 公共类型词汇（04 §8 沙箱栈 / §9 审批与动作安全）。
+ *
+ * 两个正交旋钮（04 §9）：sandbox 档（三档文件效果）× 审批策略档（ask /
+ * never）——两闸独立，不合成一个「安全级别」糊面。预设只是用户面打包，
+ * 组合逻辑不进执行路径。
+ *
+ * 与 berry 分叉注记：三档第三席本仓定名 `danger`（04 §8 拍板句「机器面
+ * 枚举字面以短名为准」——berry 的 `danger-full-access` 不承，两名并存已
+ * 于 2026-09-06 终结）；审批请求归属恰一键 `{sessionId}`（立项改造裁决：
+ * 承 berry 删插件位）。
+ */
+export {};

package/dist/scheduler/codes.js

@@ -0,0 +1,54 @@
+/**
+ * scheduler 域错误码注册（04 §12 调度条——SCHEDULER_ 前缀族；02 §5.3 批 15a
+ * 明列八码）。
+ *
+ * 码语义分层：四码守 /tick 六动词与程序面的行管理（NAME_INVALID/NAME_EXISTS/
+ * NOT_FOUND/JOB_INVALID）；一码管 schedule 串词法（SCHEDULE_INVALID——
+ * GoalJobsFace register 坏串响亮拒不炸装配时 message 即引此码）；三码管
+ * OS cron 可选后端（CRON_UNSUPPORTED/CRON_UNAUTHORIZED/CRON_WRITE_FAILED
+ * ——04 §12「OS 定时注册态」已裁乙案条的跨平台处置与人面授权链执法面）。
+ * 本文件由模块公开面 index.ts 引入（注册纪律：import 发生才注册）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'SCHEDULER_NAME_INVALID',
+        module: 'scheduler',
+        description: '任务名词法违例——须匹配 ^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$（goal 挂钟行名 goal-<goalId> 同型合法）',
+    },
+    {
+        code: 'SCHEDULER_NAME_EXISTS',
+        module: 'scheduler',
+        description: '名冲突守卫——add/挂钟 register 撞既有行拒（jobs 表行即唯一事实源）',
+    },
+    {
+        code: 'SCHEDULER_NOT_FOUND',
+        module: 'scheduler',
+        description: '幽灵名零行守卫——enable/disable/rm 作用行缺席响亮拒（04 §12 /tick 瘦身条 2026-09-04 同款守卫）',
+    },
+    {
+        code: 'SCHEDULER_SCHEDULE_INVALID',
+        module: 'scheduler',
+        description: 'schedule 串词法/语义坏形——四形 every:/once@+相对/once@绝对/daily@/weekly@ 之外，含 interval 下限 5s 违反与 cron 后端 sub-minute/非 60 倍数拒',
+    },
+    {
+        code: 'SCHEDULER_JOB_INVALID',
+        module: 'scheduler',
+        description: '行载荷坏——prompt 空/超 16KiB、cwd 非绝对路径或建行时不存在',
+    },
+    {
+        code: 'SCHEDULER_CRON_UNSUPPORTED',
+        module: 'scheduler',
+        description: 'cron 可选后端诚实拒——win32 无用户 crontab 形态、后端缺席形态下启用 OS 注册面（04 §12 OS 定时注册态已裁条）',
+    },
+    {
+        code: 'SCHEDULER_CRON_UNAUTHORIZED',
+        module: 'scheduler',
+        description: '人面授权链未过——写系统 crontab 需一次人面授权，授权拒即拒写（04 §12 OS 定时注册态已裁条）',
+    },
+    {
+        code: 'SCHEDULER_CRON_WRITE_FAILED',
+        module: 'scheduler',
+        description: 'crontab 读改写链失败——保留他人行的写回失败亮拒不静默（以 # berry-agent:<名> 标记行定位自有条目）',
+    },
+]);