berry-agent 0.1.0-alpha.1

package/dist/safety/gate.js

@@ -0,0 +1,226 @@
+/**
+ * L3 safety — 守门固定行（04 §7 守门段 + §8 carve-out 条 + §9 审批对）。
+ *
+ * 本行装在 tools_pre_execute 守门段首位，评估序六步（04 §9 定形块④——
+ * 2026-09-11 审批分档批重排定形，read-only 档让棒沿旧保持一切判定之前）：
+ * 1. **(1) 工具策略表 deny 面**——命中即 block **硬拒**最先短路（reason
+ *    `policy-deny:<条目序>`，**不可被任何后续面翻转**：sticky always /
+ *    allow 命中 / policy never / sandbox danger 全不豁免——deny 是用户
+ *    主权裁决；deny 可拦 read 档工具，(1) 先于 (3)）；
+ * 2. **(2) carve-out 判定**（04 §8 2026-09-06 定形）：fs 写路径在根内但命中
+ *    carve-out 例外（.git / .env 族 + 数据目录族）→ block **硬拒**——denial
+ *    marker 回执、无升权出路（不存在「升到哪档能写 .git」，任何档含 danger
+ *    恒不可写——底线不交模型裁决。与 berry 分叉：berry 把命中做成升权审批面
+ *    不承）；数据目录条（04 §7 宿主状态根）无条件恒追加、不可经 entries=[]
+ *    关闭（恒 = 平台底线，不交装配裁量——2026-09-06 遗漏审计批补钉）；
+ * 3. **(3) read 档放行**（显式声明 read 才有宽档；未声明经注册面归一 exec
+ *    不经此位——04 §9 ②未知缺省最危律）；
+ * 4. **(4) allow 命中免问**（策略表 allow 条目 + 偏序档位判——advisory：只
+ *    影响问不问，fence/执行段照走；carve-out 硬拒面与之无交叉命中面）；
+ * 5. **(5) fence 前核**（§7 outside-roots 不问直接拒，沿旧）；
+ * 6. **(6) write/exec 审批对 ask**（03 §2.3「write|exec 触发审批对」——粘性
+ *    短路在 ApprovalService 内；policy never → 直接拒沿旧）。
+ *
+ * 分工（防重复拦截）：粗粒度根 containment 在 tools/fs 的 fence——路径在可
+ * 写根外（outside-roots）是 fence 的拒绝面，本行不拦不问（问了 fence 也会
+ * 拒——审批对为可执行动作而设）；read-only 档 fence 拒全量写（空根），本行
+ * 跳过不产生审批交互。
+ *
+ * 链续约定：放行必须 return next(input)（waterfall 委托——不调 next 即短路
+ * 会吞掉链上后续守门者）；block 置 input.outcome 后返回（不调 next）。
+ * 装配纪律：本仓 EventDispatch 无 prepend 选项、链序 = 注册序——装配根必须
+ * **先装本行**再装其余守门者（安全栈固定占守门段首位）。
+ */
+import { TOOL_PRE_EXECUTE_EVENT } from '../contracts/index.js';
+import { parseApplyPatch } from '../tools/index.js';
+import { absolutize, buildCarveOutTable, canonicalPath, deriveWritableRoots, resolveWritability, } from './roots.js';
+import { FS_WRITE_TOOLS, matchToolPolicy, policyHitNote } from './tool-policy.js';
+import { sandboxDenialMarker } from './sandbox.js';
+/** 内置默认 carve-out 条目（04 §8 例示：.git 转只读 + .env 族遮罩——含单层 glob 两形） */
+export const DEFAULT_CARVE_OUT_ENTRIES = [
+    { pattern: '.git', effect: 'deny', note: '版本库元数据默认只读' },
+    { pattern: '.env', effect: 'deny', note: '环境变量敏感文件' },
+    { pattern: '*.env', effect: 'deny', note: '环境变量敏感文件（glob）' },
+    { pattern: '.env.*', effect: 'deny', note: '环境变量敏感文件（glob）' },
+];
+/**
+ * 从写类工具参数提取目标路径集合（相对路径保持原样，统一由本行锚 workspace）。
+ * 未知工具返回空（本行的路径语义只覆盖 fs 写族；其余 write-effect 工具走
+ * 整名审批，无路径可提取）。
+ */
+function extractWritePaths(toolName, args) {
+    if (toolName === 'write') {
+        // write 工具：单目标 path 参数
+        return typeof args.path === 'string' ? [args.path] : [];
+    }
+    if (toolName === 'edit') {
+        // edit 工具：apply_patch 补丁文本（多文件操作段，逐段提取路径）；
+        // 补丁格式错不在本行的管辖面——放行给 edit 工具自身报 FS_PATCH_FAILED
+        const patch = typeof args.patch === 'string' ? args.patch : '';
+        try {
+            return parseApplyPatch(patch).map((op) => op.path);
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
+/**
+ * 安装安全守门行（tools_pre_execute 守门段首位——装配根先于其余守门者注册）。
+ * @returns 退订闭包（装配层经 scope.effect 组合生命周期）
+ *
+ * carve-out 判定表在装配期钉死（glob「先展开再遮罩」的展开时刻在此）——
+ * 会话中途新建的 .env 新文件不追溯遮罩（诚实语义；要再遮罩须换条目重装）。
+ */
+export function installSafetyGate(dispatch, opts) {
+    const workspace = canonicalPath(opts.workspace);
+    // 数据目录恒排除条（04 §7）：无条件追加于用户 entries 之后——entries=[] 关
+    // 闭的是 .git/.env 例示面，本条不随装配裁量关闭（恒 = 平台底线）。pattern
+    // 为绝对路径（resolveDataDir 产物），buildCarveOutTable 内展开即其自身
+    const entries = [
+        ...(opts.entries ?? DEFAULT_CARVE_OUT_ENTRIES),
+        { pattern: opts.dataDir, effect: 'deny', note: '数据目录（04 §7——宿主状态根，任何档含 danger 恒不可写）' },
+    ];
+    const carveTable = buildCarveOutTable(workspace, entries);
+    const approval = opts.approval;
+    const handler = async (input, next) => {
+        // 会话归属过滤（批 19c-1）：归属位与调用位双在场且相异 = 他会话的工具
+        // 调用——本行让棒（不执法不产生审批交互，交棒给归属行）。双缺席任一 =
+        // 无会话判据语境（单会话测试形 / 无会话管道调用），不过滤保持旧行为。
+        if (opts.sessionId !== undefined && input.sessionId !== undefined && input.sessionId !== opts.sessionId) {
+            return next(input);
+        }
+        const mode = opts.mode();
+        const tool = input.tool;
+        // read-only 档让棒沿旧（04 §9 定形块④：skip 位保持一切判定之前——fence
+        // 拒全量写（空根），本行跳过不产生审批交互；策略表在 read-only 会话无
+        // 执法位〔冷读闸 m1 定位〕，deny 亦不因 read-only 档而前置执法）
+        if (mode === 'read-only')
+            return next(input);
+        const isFsFamily = FS_WRITE_TOOLS.has(tool.name);
+        // canonical 写目标集一次提取（fs 族）：deny 匹配 / fence 前核 / 粘性指纹
+        // 三消费点共用（相对路径锚 workspace、符号链解析与 fence 同源）
+        const canonicalWritePaths = isFsFamily
+            ? extractWritePaths(tool.name, input.args).map((p) => absolutize(workspace, p))
+            : [];
+        /* ---- (1) 工具策略表 deny 面（04 §9 定形块④评估序①——最先短路） ---- */
+        // 匹配一次全表持有：引擎 deny 优先律（首个 deny 命中即终局返回）——deny
+        // 序位在 carve-out / read 放行 / allow 免问 / ask 全部之前，**不可被任何
+        // 后续面翻转**（sticky always / allow 命中 / policy never / sandbox danger
+        // 全不豁免——deny 是用户主权裁决，其余面无权翻案）。deny 可拦 read 档
+        // 工具（(1) 先于 (3)：「此工具永拒」的用户主权语义自然覆盖只读工具——
+        // read 档免审 ≠ 免策略表）。deny 拒不产生 approval 对（短路在 ask 之前
+        // ——粘性命中无审批对同律），reason policy-deny:<条目序> 落 gate/decision。
+        const hit = opts.toolPolicy !== undefined && opts.toolPolicy.length > 0
+            ? matchToolPolicy(opts.toolPolicy, isFsFamily
+                ? {
+                    tool: tool.name,
+                    // 档位取值：注册面归一（04 §9 定形块②反转）后应恒在场；类型
+                    // 位缺省兜底 = exec（未知缺省最危律同律——守门行自身防御与
+                    // 注册面归一同向，双保险）
+                    effect: tool.effect ?? 'exec',
+                    writePaths: canonicalWritePaths,
+                    workspace,
+                }
+                : { tool: tool.name, effect: tool.effect ?? 'exec' }, Date.now())
+            : undefined;
+        if (hit !== undefined && hit.entry.decision === 'deny') {
+            input.outcome = {
+                action: 'block',
+                reason: `${sandboxDenialMarker(mode)} ${tool.name} 命中工具策略表 deny 条目 ${policyHitNote(hit)}${hit.entry.reason !== undefined ? `（${hit.entry.reason}）` : ''}——用户主权硬拒，任何面不可翻转（解除唯手删条目）。`,
+            };
+            return input; // 不调 next：短路整链（deny 优先律——硬拒）
+        }
+        /* ---- (2) carve-out 判定（fs 族写路径；任何档含 danger 照走——硬拒） ---- */
+        if (isFsFamily) {
+            const roots = deriveWritableRoots(workspace, mode);
+            // 逐路径独立判定：任一 deny 命中即整调用硬拒（多文件补丁不部分放行）
+            for (const rawPath of extractWritePaths(tool.name, input.args)) {
+                // 与 fence 同源的 canonical 化（相对锚 workspace、最近存在祖先解析符号链）
+                const absPath = absolutize(workspace, rawPath);
+                const verdict = resolveWritability(absPath, roots, carveTable);
+                if (!verdict.allowed && verdict.kind === 'carve-out') {
+                    const node = verdict.matched;
+                    // 硬拒回执（04 §8 定形）：denial marker + 命中条目——无升权 hint
+                    // （不存在「升到哪档能写」，任何档恒不可写——引导升权即引导徒劳）
+                    input.outcome = {
+                        action: 'block',
+                        reason: `${sandboxDenialMarker(mode)} ${rawPath} 命中 carve-out 恒排除条目 ${node.entry.pattern}${node.entry.note ? `（${node.entry.note}）` : ''}——任何档（含 danger）恒不可写，无升权出路。`,
+                    };
+                    return input; // 不调 next：短路整链（守门段 block 语义）
+                }
+            }
+        }
+        /* ---- (3) read 档放行（04 §9 定形块④评估序③：显式声明 read 才有宽档） ---- */
+        // 本行只管写/执行意图（03 §2.3 effect 面）：write/exec 同走审批链——
+        // exec 档不留审批旁路；未声明效果面工具经注册面归一（04 §9 ②缺省反转
+        // ?? 'exec'）已恒为 exec 档，不经本位放行
+        if (tool.effect === 'read')
+            return next(input);
+        /* ---- (4) allow 命中免问（评估序④：策略表 allow 条目 + 偏序档位判） ---- */
+        // 命中审计（04 §9 ④）：放行来源标注 policy-allow:<条目序> 落 GateInput
+        // ——管道 recordGate 承接进 gate/decision 的 reason 位（免问放行仍可审计
+        // ——不产生 approval 事件对，来源在此标注）
+        if (hit !== undefined) {
+            input.allowReason = policyHitNote(hit);
+            return next(input);
+        }
+        /* ---- (5)(6) write/exec 审批对（03 §2.3；粘性短路在 ApprovalService 内） ---- */
+        // 审批前先核 fence 面：任一写目标在可写根外 = fence 必拒（本行不问——
+        // 审批对为可执行动作而设，防「批了又被 fence 拒」的空转交互）
+        if (isFsFamily) {
+            const roots = deriveWritableRoots(workspace, mode);
+            const outside = canonicalWritePaths.some((p) => {
+                const verdict = resolveWritability(p, roots, carveTable);
+                return !verdict.allowed && verdict.kind === 'outside-roots';
+            });
+            if (outside)
+                return next(input); // fence 的拒绝面，本行不重复拦
+        }
+        // 粘性指纹目标摘要（04 §9 粘性第 1/2 款）：fs 族 = 写目标路径（单目标 =
+        // 该路径；多目标 = 排序去重拼接——同集合才谈得上免问）；其余 write/exec
+        // 工具 = 工具名（整名族语义——同工具的后续调用免问）
+        const targets = isFsFamily ? [...new Set(canonicalWritePaths)].sort() : [tool.name];
+        // 草案（04 §9 定形③）：fs 族仅在单目标时携带（精确 canonical 路径——批
+        // 这一次不升格批全仓）；多目标无单一路径可代表即无草案；非 fs 族无路径
+        // 语义亦无草案（整名草案随真实消费者出现再裁）
+        const draft = isFsFamily && targets.length === 1 ? { tool: tool.name, pattern: targets[0] } : undefined;
+        const summary = isFsFamily
+            ? targets.length === 1
+                ? `写入 ${targets[0]}`
+                : `写入 ${targets.length} 个目标（${targets[0]} 等）`
+            : `${tool.name} 写动作`;
+        const { outcome } = await approval.ask({
+            summary,
+            toolName: tool.name,
+            toolCallId: input.toolCallId,
+            // 粘性指纹（tier = 当前档——子集偏序维度：更严档的重复请求被既有宽批包含）
+            stickyKey: { target: targets.join('\n'), tier: mode },
+            ...(draft !== undefined ? { suggestedEntry: draft } : {}),
+            // run 取消信号随 ask 载荷透传（interrupt 链——answerer 桥接撤销；
+            // undefined = 无 run 语境不携带）
+            ...(input.signal !== undefined ? { signal: input.signal } : {}),
+        });
+        if (outcome === 'allowed-once')
+            return next(input); // 放行交棒（仅本次调用）
+        // 拒绝族 block：cancelled 是打断非拒绝（run 已 abort 时模型看不见——
+        // loop break 在先，收的是 durable 审计面与 resume 回放语境的诚实）；
+        // rejected/unavailable 不带升权 hint（fs 写审批无升权出路——用户已当面
+        // 说否，引导绕路违背 04 §8「拒绝是最终的」）
+        if (outcome === 'cancelled') {
+            input.outcome = {
+                action: 'block',
+                reason: `${sandboxDenialMarker(mode)} ${summary}未执行（审批已取消——run 已打断）。`,
+            };
+            return input;
+        }
+        input.outcome = {
+            action: 'block',
+            reason: `${sandboxDenialMarker(mode)} ${summary}被拒（审批结果：${outcome}${outcome === 'unavailable' ? '——无人应答，fail-closed 拒执行' : ''}）。`,
+        };
+        return input;
+    };
+    // 无 prepend 选项的装配纪律见文件头注——调用方（装配根）保证本行先注册
+    return dispatch.onWaterfall(TOOL_PRE_EXECUTE_EVENT, handler);
+}

package/dist/safety/index.js

@@ -0,0 +1,24 @@
+/**
+ * L3 safety 公开面（02 篇席 8：审批对 + 沙箱三档 + carve-out + 可写根推导 +
+ * 权限预设 + 升权编舞）。
+ *
+ * 消费方：tools/fs 的 fence（createRootsProvider 数据源）、exec 的 bash 工具
+ * 件（confine + 升权）、host 装配根（installSafetyGate + createApprovalService
+ * + 持久/策略表接线——审批分档批起载体名 tool-policy.json）。权限预设（presets
+ * 纯数据件 + host 人面/装配消费腿）2026-09-11 审批分档批 ap-3 落码。
+ *
+ * 引入 './codes.js' 触发 SANDBOX_ 三码注册（注册纪律：import 发生才注册——
+ * 与 tools/llm/session 的 codes.ts 同款）。
+ */
+import './codes.js';
+export * from './types.js';
+export * from './roots.js';
+export * from './sensitive.js';
+export * from './tool-policy.js';
+export * from './presets.js';
+export * from './approval.js';
+export * from './sandbox.js';
+export * from './seatbelt.js';
+export * from './bwrap.js';
+export * from './gate.js';
+export * from './danger.js';

package/dist/safety/presets.js

@@ -0,0 +1,73 @@
+/**
+ * L3 safety — 权限预设打包（04 §9 定形块⑥·RP5——纯数据半边，2026-09-11
+ * 审批分档批 ap-3）。
+ *
+ * 预设 = sandbox 档 × 审批 policy × 策略表建议集的**打包缺省**，三档定名：
+ * - `conservative`：read-only + ask + 空建议集；
+ * - `balanced`：workspace-write + ask + 空建议集——**缺省档 = 现状打包**，零行为变化；
+ * - `open`：workspace-write + ask + 建议集 = 工作区根 fs 写前缀两件 +
+ *   git 本地只读词干五件（04 §8 GIT_METADATA_COMMANDS 闭集取本地只读子集
+ *   ——**push/pull/fetch 网络族不入集**：§13「此类词干不经 allowlist 放行」
+ *   不因预设翻转，git push 恒走危险闸〔冷读闸 M5 定形〕）。
+ *
+ * 展开式非引用式（不留预设名第二真相源）：本件只产**展开值**——两旋钮
+ * （sandboxMode/approvalPolicy）与 allow 草案清单；草案经写侧唯一正门
+ * `appendToolPolicyEntry` 落盘（host 消费腿），机器条目无 reason/effect/
+ * expiresAt（与审批服务 suggestedEntry 同形——ToolPolicyDraft 两字段）。
+ * 无静默审批不破：open 档不含任何 yolo 形自动放行——policy 闭集 ask/never
+ * 本就无「不问放行」档，预设只打包既有合法态组合。
+ */
+/** 预设名闭集（三档——04 §9 ⑥定名；CLI --preset 值域同源本表） */
+export const APPROVAL_PRESET_NAMES = ['conservative', 'balanced', 'open'];
+/**
+ * 三档打包表（静态单源）。balanced = 现状（workspace-write + ask）零变化；
+ * conservative 只收紧沙箱档（policy 仍 ask——never 档缺省不给：无人应答
+ * fail-closed 已是缺省语义，无需用户选「直接拒」档防身）。
+ */
+export const APPROVAL_PRESETS = [
+    {
+        name: 'conservative',
+        sandboxMode: 'read-only',
+        approvalPolicy: 'ask',
+        description: '只读沙箱——文件写/执行全走审批（最严档）',
+    },
+    {
+        name: 'balanced',
+        sandboxMode: 'workspace-write',
+        approvalPolicy: 'ask',
+        description: '工作区可写 + 审批如常（缺省档 = 现状打包，零行为变化）',
+    },
+    {
+        name: 'open',
+        sandboxMode: 'workspace-write',
+        approvalPolicy: 'ask',
+        description: '工作区可写 + fs 写与 git 本地只读命令免问建议集（不含网络写动词族）',
+    },
+];
+/** 取预设（未知名返 undefined——调用方自定错误面，本件不抛） */
+export function approvalPresetOf(name) {
+    return APPROVAL_PRESETS.find((preset) => preset.name === name);
+}
+/**
+ * open 档 bash 建议词干五件（04 §8 GIT_METADATA_COMMANDS 本地只读子集——
+ * 网络写动词 push/pull/fetch 恒不入集，见文件头注）。
+ */
+const OPEN_GIT_STEMS = ['git status', 'git log', 'git diff', 'git show', 'git branch'];
+/**
+ * 预设建议集展开（写盘腿专用——CLI 逐次形不产条目，04 §9 ⑥ ap-3 定形补充）：
+ * - conservative/balanced：空清单（建议集为空零写入——切档不清不删既有条目）；
+ * - open：fs 两件（write/edit × 工作区根前缀）+ bash 五词干，共七条 allow 草案。
+ * pattern = 工作区根 canonical 绝对路径（fs 前缀语义）或命令词干（bash 语义）
+ * ——与审批服务 suggestedEntry 同源同形（ToolPolicyDraft 两字段），机器条目
+ * 无 reason/effect/expiresAt。
+ */
+export function presetSuggestedEntries(preset, workspaceRoot) {
+    if (preset !== 'open')
+        return [];
+    const root = workspaceRoot.length > 0 ? workspaceRoot : '.';
+    return [
+        { tool: 'write', pattern: root },
+        { tool: 'edit', pattern: root },
+        ...OPEN_GIT_STEMS.map((stem) => ({ tool: 'bash', pattern: stem })),
+    ];
+}

package/dist/safety/roots.js

@@ -0,0 +1,139 @@
+/**
+ * L3 safety — 可写根唯一推导函数 + carve-out 层叠例外（04 §8 deriveWritableRoots 表 + carve-out 条款）。
+ *
+ * deriveWritableRoots() 是「某档是什么意思」的唯一 home：沙箱 profile
+ * （seatbelt/bwrap）与进程内 fs fence（tools/fs.ts 的 writableRoots
+ * provider）都从这里取根列表——两套防线同源生成、永不漂移。carve-out
+ * 在根列表之上叠加按路径层叠的例外条目（.git / .env 族）。
+ *
+ * 与 berry 分叉注记：carve-out 命中 = 守门行 block **硬拒**（04 §8
+ * 2026-09-06 定形——「恒不可写=平台底线」字面从硬，无升权出路）；berry
+ * 把 carve-out 命中做成升权审批面（用户可裁放行）不承。external 分域
+ * 变体（externalWritableRoots 族）不落——本仓插件进程隔离批随需再裁。
+ */
+import { readdirSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, resolve as resolvePath, sep } from 'node:path';
+/**
+ * 路径 canonical 化（符号链解析到真实位置）。
+ * 路径或前缀不存在时：回退**最近存在祖先**解析符号链再拼回尾部段——与写侧
+ * fs.ts canonicalize 同律（别名工作区下新建文件的绝对别名路径若原样返回，
+ * 与 canonical 化的根比较恒 miss → 守门判根外跳过而写侧父目录递归判在根内
+ * 放行——两层 canonical 化分歧乘出遮罩绕过，蓝本真缺陷教训照搬防御）。
+ */
+export function canonicalPath(path) {
+    try {
+        // native 实现按文件系统逐组件查找（与 spawn 及各强制层一致）；JS 实现
+        // 在部分平台会先做词法折叠再解析符号链，与强制层判定不一致
+        return realpathSync.native(path);
+    }
+    catch {
+        // 不存在：父目录递归解析（父到达文件系统根仍失败即回退原样——绝对病理
+        // 形态不虚构路径）
+        const parent = dirname(path);
+        if (parent === path)
+            return path;
+        return join(canonicalPath(parent), basename(path));
+    }
+}
+/**
+ * 按档位推导可写根列表（canonical 化去重）——04 §8 表的唯一落码：
+ * - read-only：空列表（fence 拒全量写——mode 是一等输入，不是装饰参数）；
+ * - workspace-write：workspace + /tmp + os.tmpdir()；
+ * - danger：文件系统根 [sep]（全盘可写——配合 isInsideRoot 的根分隔符特判，
+ *   任意绝对路径皆命中）。
+ * 这是 fs fence 与沙箱 profile（seatbelt/bwrap）的共同数据源。
+ */
+export function deriveWritableRoots(workspace, mode) {
+    if (mode === 'read-only')
+        return [];
+    if (mode === 'danger')
+        return [sep];
+    return [...new Set([workspace, '/tmp', tmpdir()].map(canonicalPath))];
+}
+/** child 是否位于 root 内（相等或隔分隔符的前缀——防 /root 与 /root-evil 误判；root 为 sep 时任意绝对路径皆命中） */
+export function isInsideRoot(child, root) {
+    const prefix = root === sep ? sep : root + sep;
+    return child === root || child.startsWith(prefix);
+}
+/**
+ * carve-out 条目展开：pattern → canonical 绝对路径集合。
+ * 字面 pattern 直接转绝对（不检查存在性——尚未存在的敏感路径也预先遮罩，
+ * .git 在 init 前就该挡）；含 `*` 的 pattern 扫描其所在目录层（单层不递归）
+ * 把实际存在的匹配项展开——「glob 先展开再遮罩」。展开结果同时用于判定表
+ * 构建与审计输出。
+ */
+export function expandCarveOutEntry(workspace, entry) {
+    const dir = entry.pattern.includes('/')
+        ? resolvePath(workspace, entry.pattern.slice(0, entry.pattern.lastIndexOf('/')))
+        : workspace;
+    const leaf = entry.pattern.includes('/') ? entry.pattern.slice(entry.pattern.lastIndexOf('/') + 1) : entry.pattern;
+    if (!leaf.includes('*')) {
+        return [absolutize(workspace, entry.pattern)];
+    }
+    // 顶层单层 glob：`*` 不跨分隔符，扫描目录层取实际存在的匹配
+    const pattern = new RegExp(`^${leaf.replace(/[.+^${}()|[\]\\]/g, String.raw `\$&`).replaceAll('*', '[^/]*')}$`);
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((e) => pattern.test(e.name))
+            .map((e) => canonicalPath(join(dir, e.name)));
+    }
+    catch {
+        // 目录不存在：glob 无可展开（字面条目不同——见上）
+        return [];
+    }
+}
+/**
+ * 构建 carve-out 判定表：全部条目展开后按「最具体路径胜出」排序（路径段数
+ * 多者先；同深按 deny 优先——保守）。层叠语义由排序后的首个前缀匹配实现：
+ * 父条目宽、子条目窄，孙条目比子条目更窄时赢回（allow 效果的用途）。
+ */
+export function buildCarveOutTable(workspace, entries) {
+    const nodes = [];
+    for (const entry of entries) {
+        for (const path of expandCarveOutEntry(workspace, entry)) {
+            nodes.push({ path, effect: entry.effect, entry });
+        }
+    }
+    // 最长路径（最深）优先；同路径 deny 胜 allow（保守）；再按 pattern 字典序稳定排序
+    return nodes.sort((a, b) => {
+        const depth = b.path.split(sep).length - a.path.split(sep).length;
+        if (depth !== 0)
+            return depth;
+        if (a.effect !== b.effect)
+            return a.effect === 'deny' ? -1 : 1;
+        return a.entry.pattern.localeCompare(b.entry.pattern);
+    });
+}
+/**
+ * 判定一个 canonical 绝对路径在当前策略下的可写性：carve-out 判定表首个
+ * 前缀命中即为其效果（无命中再看根 containment）。顺序保证「根内但被遮罩」
+ * 判为 carve-out（守门硬拒面），「根外」判为 outside-roots（fence 的面）——
+ * 两个拒绝面词汇不同、去处不同。
+ */
+export function resolveWritability(absPath, roots, carveOut) {
+    // carve-out 先判：表按最具体优先排序，首个（最深的）前缀命中即生效
+    for (const node of carveOut) {
+        const inside = absPath === node.path || absPath.startsWith(node.path + sep);
+        if (inside) {
+            return node.effect === 'deny' ? { allowed: false, kind: 'carve-out', matched: node } : { allowed: true };
+        }
+    }
+    // 根 containment：相等或隔分隔符前缀（防 /root-evil 误判；全盘根见 isInsideRoot）
+    const inRoots = roots.some((root) => isInsideRoot(absPath, root));
+    return inRoots ? { allowed: true } : { allowed: false, kind: 'outside-roots' };
+}
+/**
+ * 组装 fs 工具族的 writableRoots provider（装配层接线位：替换 tools/fs 的
+ * 过渡缺省——批 8 挂账兑现）。返回的根列表按当前档位推导（mode getter 每
+ * 次 fence 检查取最新——read-only 空根 / danger 全盘根 / workspace-write
+ * 三根），已 canonical 化，与沙箱 profile 同源。
+ */
+export function createRootsProvider(input) {
+    const workspace = canonicalPath(input.workspace);
+    return () => deriveWritableRoots(workspace, input.mode());
+}
+/** 绝对化工具：workspace 锚定 canonical 化（相对锚 workspace、绝对原样——守门行预检单源） */
+export function absolutize(workspace, p) {
+    return canonicalPath(isAbsolute(p) ? resolvePath(p) : resolvePath(workspace, p));
+}