berry-agent 0.1.0-alpha.1

package/dist/credentials/refresh.js

@@ -0,0 +1,152 @@
+/**
+ * credentials — oauth 刷新链（03 §10.9 oauth bullet 刷新/轮换三振细则；
+ * c-6 落码批）。
+ *
+ * 形态 = 件内自持挂钟（obs/service.ts 同形先例：setInterval + unref；
+ * interval 0 = 不自驱——测试经 tick() 手动驱动）。巡检面 = 流注册表 ×
+ * 存储行 meta：到期位（expiresAt）落入提前量（缺省 5 分钟）即经 refresh
+ * token 换新。
+ *
+ * 三律（保留上次有效值律细则——02 §7 张力细则同源）：
+ *  1. **成功 rotate**：主行换新 token（source 'refresh'、failures 清零、
+ *     expired 位随整列换消失）；端点下发新 refresh token 才动刷新行
+ *     （RFC 6749 §6 不下发即复用旧值）；附加键保全（账号句柄等插件自记
+ *     meta 键不因链写抹掉）。
+ *  2. **失败保留旧值续用**：值不动只记 failures++（durable——连续计数）；
+ *     单败走 warn（日志面）；invalid_grant（EXPIRED 码）= 授权态坏重试
+ *     无益，直落三振语义。
+ *  3. **三振 notify 不执法**：到阈值（缺省 3）置 meta.expired 告示位 +
+ *     notify 用户（只通知——旧 token 可能仍有效，c-5 list 已呈现「已过期
+ *     ——保留上次有效值」）；notify 只在转换位发（已 expired 行继续失败
+ *     不重复告警）；撤销唯一路径 = 人面 rm（链不清删）。
+ *
+ * 窄面注入律：存储四法（CredentialsCommandStore——commands.ts 同面）+
+ * 注册表 + fetch/now/notify/warn 全注入；本件零宿主依赖，纯逻辑可测。
+ */
+import { BaseError } from '../contracts/index.js';
+import { pluginNamespace } from './types.js';
+import { refreshOAuthToken } from './oauth.js';
+/** 剔除 failures/expired 两键的 meta 残余（链管键整列换、插件自记附加键保全） */
+function stripChainKeys(meta) {
+    const { failures: _failures, expired: _expired, ...rest } = meta;
+    return rest;
+}
+/**
+ * 构造刷新链。巡检逐流隔离（单流失败不连坐他流）；重入护栏（上一拍未收口
+ * 跳过本拍——慢端点下不叠拍）。
+ */
+export function createRefreshChain(deps) {
+    const { store, registry, fetchFn } = deps;
+    const now = deps.now;
+    const notify = deps.notify;
+    const warn = deps.warn;
+    const aheadMs = deps.aheadMs ?? 5 * 60 * 1000;
+    const maxFailures = deps.maxFailures ?? 3;
+    let timer;
+    let running = false;
+    /** 单流巡检（读到写全包——单流异常折 warn 不炸整拍） */
+    const refreshOne = async (flow) => {
+        const ns = pluginNamespace(flow.pluginId);
+        const name = flow.def.name;
+        let row;
+        let meta;
+        try {
+            row = store.getCredential(ns, name);
+            if (row === undefined)
+                return; // 未授权过——不归链管
+            meta = (row.meta ?? {});
+            if (typeof meta.expiresAt !== 'number')
+                return; // 无到期位（manual/静态）不归链管
+            if (meta.expiresAt - now() > aheadMs)
+                return; // 未到提前量
+        }
+        catch (err) {
+            warn(`凭证 ${ns}/${name} 刷新巡检读侧异常：${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        const wasExpired = meta.expired === true;
+        const refreshName = typeof meta.refreshName === 'string' ? meta.refreshName : undefined;
+        if (refreshName === undefined)
+            return; // 单 token 形（无刷新行）——到期不自动续
+        try {
+            const refreshRow = store.getCredential(ns, refreshName);
+            if (refreshRow === undefined) {
+                throw new BaseError('CREDENTIALS_OAUTH_EXPIRED', `refresh 凭据行 ${refreshName} 缺席（已被人面 rm）——授权态不完整，重新发起授权流 /credentials oauth ${flow.pluginId} ${name}。`);
+            }
+            const grant = await refreshOAuthToken(flow.def, refreshRow.apiKey, { fetchFn, now });
+            // 成功 rotate：主行换新（source 'refresh'、failures/expired 随整列换消失；
+            // 端点未给 expires_in 则保留旧到期位）
+            store.setCredential(ns, name, {
+                apiKey: grant.accessToken,
+                meta: { ...stripChainKeys(meta), source: 'refresh', expiresAt: grant.expiresAt ?? meta.expiresAt },
+            });
+            // 新 refresh token 才动刷新行（不下发即复用——RFC 6749 §6）
+            if (grant.refreshToken !== undefined && grant.refreshToken !== refreshRow.apiKey) {
+                store.setCredential(ns, refreshName, { apiKey: grant.refreshToken, meta: { source: 'refresh' } });
+            }
+            // credentials/changed 审计 seam（值域 05 §1.1 单源：刷新轮换 = rotate/oauth-flow）
+            deps.onCredentialChanged?.({ namespace: ns, name, action: 'rotate', origin: 'oauth-flow' });
+        }
+        catch (err) {
+            // 失败保留旧值续用：值不动，failures 递增（durable）
+            const failures = (typeof meta.failures === 'number' ? meta.failures : 0) + 1;
+            // invalid_grant（EXPIRED 码）= 授权态坏——直落三振语义（重试无益不空转三拍）
+            const stateBroken = err instanceof BaseError && err.code === 'CREDENTIALS_OAUTH_EXPIRED';
+            const strike = stateBroken || failures >= maxFailures;
+            store.setCredential(ns, name, {
+                apiKey: row.apiKey, // 保留上次有效值（铁律——链不清删不清值）
+                meta: {
+                    ...stripChainKeys(meta),
+                    refreshName,
+                    expiresAt: meta.expiresAt,
+                    failures,
+                    ...(strike ? { expired: true } : {}),
+                },
+            });
+            if (strike) {
+                // 三振 notify（只通知不执法——旧 token 可能仍有效；唯一转换位发，已 expired 行不重复告警）
+                if (!wasExpired) {
+                    notify(`凭证 ${ns}/${name} 刷新${stateBroken ? '被拒（授权态坏——refresh 凭据失效或行不完整）' : `连续 ${failures} 次失败`}——已标记过期，保留上次有效值；重新授权：/credentials oauth ${flow.pluginId} ${name}`);
+                }
+                else {
+                    warn(`凭证 ${ns}/${name} 刷新仍失败（已过期告示在案，第 ${failures} 次）：${errText(err)}`);
+                }
+            }
+            else {
+                warn(`凭证 ${ns}/${name} 刷新失败（第 ${failures} 次，阈值 ${maxFailures}）：${errText(err)}——保留旧值续用`);
+            }
+        }
+    };
+    return {
+        async tick() {
+            if (running)
+                return; // 重入护栏——上一拍未收口跳过本拍
+            running = true;
+            try {
+                for (const flow of registry.list()) {
+                    await refreshOne(flow);
+                }
+            }
+            finally {
+                running = false;
+            }
+        },
+        start(intervalMs) {
+            this.stop(); // 幂等重启（重复 start 先清旧钟）
+            const ms = intervalMs ?? 60_000;
+            timer = setInterval(() => void this.tick(), ms);
+            // 不阻进程退出（obs/service.ts 同律——挂钟是后台巡检非存活语义）
+            timer.unref?.();
+        },
+        stop() {
+            if (timer !== undefined) {
+                clearInterval(timer);
+                timer = undefined;
+            }
+        },
+    };
+}
+/** 非 BaseError 错误折文案（oauth.ts errText 同形——本件零依赖不回流） */
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/credentials/secrets.js

@@ -0,0 +1,118 @@
+/**
+ * credentials — 读腿服务面工厂（03 §2.2 能力面第十面 + §10.9 读腿；c-3 落码批）。
+ *
+ * 消费形（§2.2 钉词面）：**服务面**——宿主装配序逐插件 fork 作用域
+ * `provide('secrets', …本工厂产物…)`，插件经 `ctx.get("secrets")` 取自域
+ * 绑定版（服务闭包携带 pluginId——插件面永不自报身份，防冒名）。
+ *
+ * 三动词执法全景：
+ *  - `get(name)`：自域读——物理键恒 `(plugin:<本插件 id>, name)`，越域名
+ *    恒解析为本域（不存在路径式逃逸：name 是 provider 作用名、非 namespace
+ *    载体）；缺席拒 `CREDENTIALS_NOT_FOUND`。
+ *  - `get(name, { namespace })`：显式越域读——值域好形判（'host' | 好形
+ *    plugin:<id>，坏形拒 `CREDENTIALS_NAMESPACE_DENIED` 同码分流）→ 高危面
+ *    门检 `credentials.read-cross`（§4.6 v1 首批第四枚——未开门拒同码，
+ *    message 底稿 = 门检 verdict 原文指路 opens 授予位；core: 官方件直开
+ *    豁免——triggers.ts 同律：装配即用户意图）→ 开门后逐次 `capability/used`
+ *    审计 seam（缺省 no-op = 测试形；生产装配已接线 audit_events 真发射
+ *    ——assembly U3 批 U3-5，2026-09-13 勘正旧挂账注记）。
+ *  - `set(name, value, meta?)`：恒自域写——受理窗判定（宿主回调窗内可达，
+ *    窗外拒 `CREDENTIALS_WRITE_WINDOW_CLOSED`；缺省恒窗外 = fail-closed）；
+ *    写成功落 `credentials/changed` 审计 seam（action 'rotate'/origin
+ *    'oauth-flow'——05 §1.1 值域单源：oauth 首写与刷新轮换均计 rotate；
+ *    人面 add/remove 的 'add'/'remove'·'human' 随 c-5）。
+ *  - `registerOAuthFlow(spec)`（c-6 第十面第三动词）：装载窗内注册 oauth
+ *    流（窗外拒 PLUGIN_WINDOW_CLOSED——12f-2a 装载窗执法码；回调窗内
+ *    动态注册不开放：流注册是装载期声明，注册面无运行时增量）。注册只入
+ *    host-owned 注册表，不触存储——授权写入发生在流被用户发起时的回调窗
+ *    handler 内（set 动词）。
+ *
+ * in-process TCB 诚实成文（§10.9）：get 返回明文值给插件码面（它要外联
+ * 必然持有值）；本腿防的是磁盘/env 明文落盘与跨插件串读，不防同进程内存
+ * 窥探。值恒不入 durable 面、恒不出模型面（注入腿 c-4 执法）。
+ *
+ * 窄面注入律：本件 DAG 无 host/context 边——窗判定/开门集/审计发射全经
+ * 构造注入（词面独立律：受局面结构兼容 host 装配桥真身，compat 互证归
+ * 本件测试）。
+ */
+import { BaseError } from '../contracts/index.js';
+// internal 桶机制符号深导（门检裁决核——03 §4.6；开门是宿主裁决面非插件
+// API；DEEP_FACES 面册 sanctioned 位，triggers.ts 同律消费）
+import { adjudicateCapabilityDoor } from '../contracts/api.js';
+import { pluginNamespace, isPluginNamespace } from './types.js';
+/** 高危面名（本件门检唯一消费位——§4.6 v1 首批第四枚） */
+const READ_CROSS_CAPABILITY = 'credentials.read-cross';
+/**
+ * 构造插件凭证面（host 装配序 createContext 位逐插件调用——fork 作用域
+ * provide('secrets', 产物)）。
+ */
+export function createSecretsFace(options) {
+    const { store, pluginId } = options;
+    const selfNamespace = pluginNamespace(pluginId);
+    const getOpens = options.getOpens ?? (() => new Set());
+    const inWriteWindow = options.inWriteWindow ?? (() => false);
+    return {
+        get(name, opts) {
+            const target = opts?.namespace;
+            // 缺省/显式自域：恒自域读（越域名不是载体——name 是 provider 作用名，
+            // 「显式指定自域」等价缺省形，不开门不审计）
+            if (target === undefined || target === selfNamespace) {
+                const entry = store.getCredential(selfNamespace, name);
+                if (entry === undefined) {
+                    throw new BaseError('CREDENTIALS_NOT_FOUND', `凭证 ${name} 不在本插件域（${selfNamespace}）——人面录入路径 /credentials add（03 §10.9 读腿）`);
+                }
+                return entry.apiKey;
+            }
+            // 越域读：先值域好形（'host' | 好形 plugin:<id>——坏形同码分流拒；
+            // isPluginNamespace 单源判据，裸前缀/无前缀形全拒）
+            if (target !== 'host' && !isPluginNamespace(target)) {
+                throw new BaseError('CREDENTIALS_NAMESPACE_DENIED', `namespace「${target}」坏形——值域 = 'host' | 'plugin:<id>'（03 §10.9 namespace 归属列值域单源，types.ts 判据）`);
+            }
+            // 门检（§4.6——credentials.read-cross 默认关）。core: 官方件直开豁免
+            // （装配即用户意图——triggers.ts 同律；capability/used 审计照记）
+            if (!pluginId.startsWith('core:')) {
+                const verdict = adjudicateCapabilityDoor(getOpens(), READ_CROSS_CAPABILITY);
+                if (!verdict.ok) {
+                    throw new BaseError('CREDENTIALS_NAMESPACE_DENIED', `${verdict.message}（插件 ${pluginId}）`);
+                }
+            }
+            const entry = store.getCredential(target, name);
+            if (entry === undefined) {
+                throw new BaseError('CREDENTIALS_NOT_FOUND', `凭证 ${name} 不在目标域（${target}）——越域读命中空名同响亮拒`);
+            }
+            // 开门后逐次审计（05 §1.1 capability/used——audit_events 真发射：生产
+            // 装配已接线 assembly U3 批 U3-5；core: 直开豁免同记审计——豁免免的是门不是账）
+            options.onCapabilityUsed?.({ pluginId, capability: READ_CROSS_CAPABILITY, namespace: target, name });
+            return entry.apiKey;
+        },
+        set(name, value, meta) {
+            // 受理窗判定（宿主回调窗内可达——唯一合法流 = 用户发起 oauth 授权流）
+            if (!inWriteWindow()) {
+                throw new BaseError('CREDENTIALS_WRITE_WINDOW_CLOSED', `凭证写在受理窗外被拒（插件 ${pluginId}——ctx.secrets.set 只在宿主回调窗内可达：用户发起授权流 → 宿主回调插件 handler → 窗内写，03 §10.9 写入面复合案）`);
+            }
+            // 恒自域写（无跨域写面——同读腿隔离律）
+            store.setCredential(selfNamespace, name, { apiKey: value, meta });
+            // credentials/changed 审计 seam（值恒不入载荷——05 §1.1 立词条款；action/
+            // origin 值域同源：oauth 首写与刷新轮换均计 rotate，流内写 = 'oauth-flow'）
+            options.onCredentialChanged?.({ namespace: selfNamespace, name, action: 'rotate', origin: 'oauth-flow' });
+        },
+        registerOAuthFlow(spec) {
+            const wiring = options.oauth;
+            // 受局面缺位执法（装配缺陷响亮——plugin-context required() 同判据同码；
+            // 词面归 context 域，BaseError 携码不校验归属，本件 DAG 无 context 边
+            // 故字面直用，漂移由全链测试互证）
+            if (wiring === undefined) {
+                throw new BaseError('CONTEXT_SERVICE_MISSING', `注册动词 ctx.secrets.registerOAuthFlow 的受局面 oauth（流注册表）缺席（插件 ${pluginId}——装配根未接线；装配缺陷 fail-loud）`);
+            }
+            // 装载窗执法（12f-2a 窗执法码 PLUGIN_WINDOW_CLOSED——词面归 host 域，
+            // 同上字面直用；本面严于通律：回调窗内动态注册不开放——流注册是装载
+            // 期声明，注册面无运行时增量）
+            if (!wiring.inLoadWindow()) {
+                throw new BaseError('PLUGIN_WINDOW_CLOSED', `注册动词 ctx.secrets.registerOAuthFlow 在装载窗口外被拒（插件 ${pluginId}——流注册只在 apply 执行期间合法，03 §10.9 oauth 案）`);
+            }
+            // 入 host-owned 注册表（(pluginId, name) 分键——同插件同名后写胜出，
+            // 跨插件结构性不撞；openWriteWindow 绑本插件 handle——invoke 时开窗）
+            wiring.registry.register(pluginId, spec, wiring.openWriteWindow);
+        },
+    };
+}

package/dist/credentials/types.js

@@ -0,0 +1,30 @@
+/**
+ * credentials — 契约词面件（03 §10.9 凭证代管面）。
+ *
+ * namespace 值域与 meta 键约定的**单源**（物理载体在 persist 的 credentials
+ * 表——05 §9 扩形列；本件只立词面，值域执法在 c-3 读腿受理位）：
+ *   - namespace 列即归属列（立题档「namespace / 归属列」合取定形）：'host'
+ *     （宿主自用域——模型 API key 与静态人面凭证）| 'plugin:<id>'（插件域）；
+ *   - meta 列住条目来源（manual / oauth / refresh）与 expired 状态位
+ *     （保留上次有效值律——条目不清删，撤销唯一路径 = 人面 rm）。
+ *
+ * persist 面签名用裸 string（DAG：credentials → persist 单向——persist 不
+ * import 本件，值域类型不回流物理层）。
+ */
+/** 宿主域 namespace（模型 API key 射程界桩 + 静态人面凭证归属——03 §10.9） */
+export const HOST_NAMESPACE = 'host';
+/**
+ * 插件域 namespace 构造器（c-3 读腿「恒自域」的物理键合成位——受理面以
+ * 本插件 id 构造，插件面永不手拼字符串）。
+ */
+export function pluginNamespace(pluginId) {
+    return `plugin:${pluginId}`;
+}
+/** 插件域判定（值域窄化——'host' 与坏形前缀均 false） */
+export function isPluginNamespace(namespace) {
+    return namespace.startsWith('plugin:') && namespace.length > 'plugin:'.length;
+}
+/** 插件域反解（取插件 id；非插件域返回 null——跨域审计/列示面消费） */
+export function parsePluginNamespace(namespace) {
+    return isPluginNamespace(namespace) ? namespace.slice('plugin:'.length) : null;
+}

package/dist/exec/bash.js

@@ -0,0 +1,279 @@
+/**
+ * bash 工具件（04 §8 全规格：发现序/超时帽/后台化截获/沙箱消费/失败二分）。
+ *
+ * 参数面恰 {command, timeoutMs?, cwd?, sandbox_permissions?, justification?}——
+ * 无 stdin、无 env 注入、无后台化。升权闭包（会话内审批缓存/粘性）归驱动层，
+ * 本件纯逻辑腿只做 allowed-once 语义：审批产物 target 只用于本次 spawn，不写
+ * 回会话档（04 §8「只授予当次调用」）。
+ *
+ * 失败二分的工具面分报：spawn 阶段失败（EXEC_SPAWN_FAILED——bash 不在场/
+ * runner 没跑起来）与执行阶段失败（exitCode ≠ 0 → isError）走两条腿；沙箱
+ * 策略拒绝（denialSignatures 命中）单独成第三腿——拒绝标记 + 升权提示引导
+ * 模型走正道，拒绝是最终的不许投机。
+ */
+import { accessSync, constants as fsConstants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { BaseError } from '../contracts/index.js';
+import { Type } from 'typebox';
+import { canonicalPath, deriveWritableRoots, escalationHintMarker, requestEscalation, sandboxDenialMarker, validateEscalationArgs, } from '../safety/index.js';
+import { BASH_TIMEOUT_DEFAULT_MS, BASH_TIMEOUT_MAX_MS } from './types.js';
+import { findGitRedirectViolations, isGitMetadataExempt, worktreeGitDir } from './git-guard.js';
+/**
+ * bash 发现序（04 §8）：BERRY_AGENT_BASH_PATH > 系统 PATH 逐目录 X_OK 扫描。
+ * 候选命中 WSL launcher（win32 的 bash.exe 系 WSL 代跳板——非真 bash）视为
+ * 缺席继续扫；全链缺席 fail-loud 抛 EXEC_SPAWN_FAILED（不降级 cmd——降级会
+ * 制造半兼容 shell 的静默行为分叉）。
+ * @param env 环境源（BERRY_AGENT_BASH_PATH 与 PATH 的读面；缺省 process.env）
+ */
+export function discoverBash(env = process.env) {
+    const override = env.BERRY_AGENT_BASH_PATH;
+    if (override !== undefined && override !== '') {
+        // 显式指名不可用 = 配置错：fail-loud 带修复提示（不静默回落 PATH——回落
+        // 会掩盖配置失效，用户以为在用指定 bash 实则不是）
+        assertExecutable(override);
+        return override;
+    }
+    const pathValue = env.PATH ?? '';
+    const launcherNames = new Set(['bash.exe', 'wsl.exe', 'wsl']);
+    for (const dir of pathValue.split(delimiter)) {
+        if (dir === '')
+            continue;
+        const candidate = join(dir, 'bash');
+        if (!assertExecutable(candidate, true))
+            continue;
+        // WSL launcher 防线：win32 下名为 bash 的实为 WSL 代跳板（basename 族）
+        const base = candidate.split(/[\\/]/).pop() ?? '';
+        if (process.platform === 'win32' && launcherNames.has(`${base}.exe`))
+            continue;
+        return candidate;
+    }
+    throw new BaseError('EXEC_SPAWN_FAILED', 'bash 不在场（PATH 全链无 X_OK 命中；不降级 cmd）——可经 BERRY_AGENT_BASH_PATH 显式指名');
+}
+/** X_OK 可执行判定（soft 形返回 false；hard 形抛 EXEC_SPAWN_FAILED 带路径提示） */
+function assertExecutable(path, soft = false) {
+    try {
+        accessSync(path, fsConstants.X_OK);
+        return true;
+    }
+    catch (error) {
+        if (soft)
+            return false;
+        throw new BaseError('EXEC_SPAWN_FAILED', `BERRY_AGENT_BASH_PATH 指名的 bash 不可执行：${path}（${error instanceof Error ? error.message : String(error)}）`, { cause: error });
+    }
+}
+/** 后台化截获（04 §8「无后台化」：模型不能脱管留后台进程） */
+export function assertNoBackgroundCommand(command) {
+    const trimmed = command.trimEnd();
+    // 尾部单 &（不含 && 逻辑与——两字符形是串行算子）= 后台化
+    if (trimmed.endsWith('&') && !trimmed.endsWith('&&')) {
+        throw new BaseError('EXEC_BACKGROUND_REJECTED', '命令尾部单 &（后台化）被拒——模型不能脱管留后台进程；长任务用 timeoutMs 显式控预算');
+    }
+    // 命令位 nohup/disown（首 token）：挂断免疫/脱管语义同为后台化面
+    const firstToken = command.trimStart().split(/\s+/)[0] ?? '';
+    if (firstToken === 'nohup' || firstToken === 'disown') {
+        throw new BaseError('EXEC_BACKGROUND_REJECTED', `命令位 ${firstToken}（脱管语义）被拒——模型不能脱管留后台进程`);
+    }
+}
+/**
+ * bash 工具定义工厂（conversation ExecToolService.bashTool 的直供体——装载
+ * 态 scope.provide('exec') 归批 12 装配面后装配批）。
+ */
+export function createBashTool(deps) {
+    // 发现一次即缓存（PATH 扫描有成本；会话期 bash 在场性不变）
+    let bashPath;
+    const resolveBash = () => {
+        if (bashPath === undefined)
+            bashPath = discoverBash(deps.env);
+        return bashPath;
+    };
+    return {
+        name: 'bash',
+        description: '在工作区执行 bash 命令（login shell：profile 级工具链在场）。默认 120 秒' +
+            '超时（上限 600 秒，到点进程组树杀）；输出保尾 60KiB 合计截断。工作目录' +
+            '缺省为工作区根。不支持后台化（尾部 & 与 nohup 被拒）。受限沙箱档下写' +
+            '工作区外会被拒；确需越档时同调用携带 sandbox_permissions（目标档）与' +
+            'justification（理由）发起升权审批。',
+        parameters: Type.Object({
+            command: Type.String({ description: '要执行的 bash 命令串' }),
+            timeoutMs: Type.Optional(Type.Integer({
+                minimum: 1,
+                maximum: BASH_TIMEOUT_MAX_MS,
+                description: `超时预算毫秒（缺省 ${BASH_TIMEOUT_DEFAULT_MS}，上限 ${BASH_TIMEOUT_MAX_MS}）`,
+            })),
+            cwd: Type.Optional(Type.String({ description: '工作目录（缺省工作区根）' })),
+            sandbox_permissions: Type.Optional(Type.String({ description: '升权目标档（workspace-write / danger）——须与 justification 成对' })),
+            justification: Type.Optional(Type.String({ description: '升权理由——须与 sandbox_permissions 成对' })),
+        }, { additionalProperties: false }),
+        // bash 执行任意 shell 命令 = exec 档（04 §9 定形块①三值扩——v1 升档清单
+        // 恰一处即本件：任意进程执行类固有风险位最高，自 write 升 exec 档；批内
+        // 调度 write|exec 同串行屏障（03 §2.3 尾注）、审批对照走、write 档免问
+        // 授权不覆盖 bash 调用（偏序窄化自限））
+        effect: 'exec',
+        execute: async (args, toolCtx) => {
+            try {
+                const command = String(args.command);
+                assertNoBackgroundCommand(command);
+                const timeoutMs = typeof args.timeoutMs === 'number' ? args.timeoutMs : BASH_TIMEOUT_DEFAULT_MS;
+                const cwd = typeof args.cwd === 'string' ? args.cwd : deps.workspaceRoot();
+                // ---- 腿一（04 §252）：.git 重定向目标扫描——硬拒前置（升权审批前，
+                // 不空耗审批对；任何档无升权出路、白名单不豁免——carve-out 路径级
+                // 直写恒不可写） ----
+                const gitViolations = findGitRedirectViolations(command, cwd);
+                if (gitViolations.length > 0) {
+                    throw new BaseError('EXEC_GIT_REDIRECT_DENIED', `bash 重定向目标落在 .git 版本史内（${gitViolations.join('、')}）——carve-out 平台底线：` +
+                        '任何档恒不可写、无升权出路（04 §252）；git 元数据操作请走 git 命令白名单形' +
+                        '（add/commit/branch 等直陈命令，不带命令替换/子壳）');
+                }
+                const bash = resolveBash();
+                // ---- 三级解析本调用腿（04 §8）：工具参数携带升权 → 校验 → 审批 ----
+                let mode = deps.currentMode();
+                if (args.sandbox_permissions !== undefined || args.justification !== undefined) {
+                    const valid = validateEscalationArgs({
+                        current: mode,
+                        sandboxPermissions: typeof args.sandbox_permissions === 'string' ? args.sandbox_permissions : undefined,
+                        justification: typeof args.justification === 'string' ? args.justification : undefined,
+                    });
+                    if (deps.approval === undefined) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `[SANDBOX_UNAVAILABLE] 升权审批面缺席——拒绝无审批的升权执行（${mode} → ${valid.target}）`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    const decision = await requestEscalation(deps.approval, {
+                        ...valid,
+                        current: mode,
+                        toolName: 'bash',
+                        toolCallId: toolCtx.toolCallId,
+                        ...(toolCtx.signal !== undefined ? { signal: toolCtx.signal } : {}),
+                    });
+                    if (decision.outcome !== 'allowed-once') {
+                        // 用户拒绝/取消/审批面不可用：拒绝是最终的——不带升权提示（不许
+                        // 投机重试；提示标记只随真实策略拒绝走）
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `升权审批未通过（${mode} → ${valid.target}，结果 ${decision.outcome}）——本次调用拒绝执行`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    // allowed-once：目标档只用于本次 spawn，不写回会话档
+                    mode = valid.target;
+                }
+                // ---- argv 组装：三档一律 confine（04 §8 定形②「任何档一律」——
+                // 2026-09-08 P0①；danger 形 = 最小读 deny profile，后端件分支定形；
+                // 沙箱缺席恒 fail-closed 拒裸跑——换档不是绕后端的路） ----
+                // -lc login shell：profile 级工具链（nvm 等）在场——承 berry getShellArgs 语义
+                const rawArgv = [bash, '-lc', command];
+                if (deps.sandboxService === undefined) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `[SANDBOX_UNAVAILABLE] 沙箱服务缺席，拒绝以 ${mode} 档裸跑（不静默无沙箱执行）`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // ---- 腿二（04 §252）：静态洁净白名单分类 + 策略组装 ----
+                // 非豁免形恒携 workspace .git 写 deny（任何档含 danger——底线不交档位；
+                // 运行时兜底关 tee/python/sed -i/dd/变量间接等全部非重定向向量）；
+                // 豁免形不携 deny，且 worktree 锚定时补 backing gitdir 可写根（修
+                // worktree 会话 git 命令沙箱断链——backing 在 worktree 根外、缺省
+                // 推导不可达；仅 workspace-write 档追加：danger 已全盘、read-only
+                // 空根不授予——豁免是 carve-out 面非写权授予）。
+                const wsRoot = deps.workspaceRoot();
+                const gitExempt = isGitMetadataExempt(command);
+                // worktree 授予腿：豁免形 + worktree 锚定 + workspace-write 档 →
+                // backing gitdir 入可写根（danger 已全盘不追加、read-only 空根不授予
+                // ——豁免是 carve-out 面非写权授予）
+                const backing = gitExempt && mode === 'workspace-write' ? worktreeGitDir(wsRoot) : undefined;
+                const policy = !gitExempt
+                    ? { mode, workspaceRoot: wsRoot, denyWritePaths: [canonicalPath(join(wsRoot, '.git'))] }
+                    : backing !== undefined
+                        ? { mode, workspaceRoot: wsRoot, writableRoots: [...deriveWritableRoots(wsRoot, mode), backing] }
+                        : { mode, workspaceRoot: wsRoot };
+                const confined = deps.sandboxService.confine(rawArgv, policy);
+                const result = await deps.pipeline.run({
+                    argv: confined.argv,
+                    cwd,
+                    timeoutMs,
+                    ...(toolCtx.signal !== undefined ? { signal: toolCtx.signal } : {}),
+                    owner: toolCtx.toolCallId,
+                });
+                // ---- 结算分类（退出码非工具面异常——数据面分报） ----
+                if (result.outcome === 'timeout') {
+                    return errorWithTail(`[EXEC_TIMEOUT] 命令超时（预算 ${timeoutMs}ms）——已进程组树杀；尾部输出保留下方`, result);
+                }
+                if (result.outcome === 'abort') {
+                    return errorWithTail('[EXEC_ABORTED] 命令被打断（协作中止信号）', result);
+                }
+                // runner 自身失败（runner 没跑起来——区别于策略拒绝生效）：EXEC_SPAWN_FAILED
+                // 分类（spawn 阶段失败同族：进程虽 spawn 了但沙箱 runner 未成活）
+                if (result.exitCode !== 0) {
+                    const lower = result.stderr.toLowerCase();
+                    const fatal = confined.runnerFailureRules.some((rule) => rule.fatalSignatures.some((sig) => lower.includes(sig.toLowerCase())));
+                    if (fatal) {
+                        return errorWithTail(`[EXEC_SPAWN_FAILED] 沙箱 runner 未跑起来（后端故障非策略拒绝）——安装对应沙箱后端`, result);
+                    }
+                    // 策略拒绝（denialSignatures 命中）：拒绝标记 + 真实 stderr + 升权提示
+                    const denied = confined.denialSignatures.some((sig) => lower.includes(sig.toLowerCase()));
+                    if (denied) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `${sandboxDenialMarker(mode)}\n${result.stderr.trim()}\n${escalationHintMarker()}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+                // 自然退出：exitCode ≠ 0 = 执行阶段失败（失败二分后者——正常结算 isError）
+                const sections = [`Exit code: ${result.exitCode ?? 'null（信号终止）'}`];
+                if (result.stdout !== '')
+                    sections.push(`--- stdout ---\n${result.stdout}`);
+                if (result.stderr !== '')
+                    sections.push(`--- stderr ---\n${result.stderr}`);
+                if (result.truncated) {
+                    sections.push(`（输出超 60KiB 已截尾：实收 ${result.bytes} 字节，保尾部）`);
+                }
+                const text = sections.join('\n');
+                return result.exitCode === 0
+                    ? { content: [{ type: 'text', text }] }
+                    : { content: [{ type: 'text', text }], isError: true };
+            }
+            catch (error) {
+                // 抛出面（EXEC_SPAWN_FAILED/EXEC_BACKGROUND_REJECTED/SANDBOX_* 校验族）
+                // 编码为 isError 数据面（03 §2.3）——BaseError 携码前置披露
+                const code = error instanceof BaseError ? error.code : undefined;
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: code ? `[${code}] ${message}` : message }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}
+/** isError + 输出保尾段（超时/打断/runner 失败三形共用——尾部现场须保留） */
+function errorWithTail(prefix, result) {
+    const sections = [prefix];
+    if (result.stdout !== '')
+        sections.push(`--- stdout ---\n${result.stdout}`);
+    if (result.stderr !== '')
+        sections.push(`--- stderr ---\n${result.stderr}`);
+    if (result.truncated) {
+        sections.push(`（输出超 60KiB 已截尾：实收 ${result.bytes} 字节，保尾部）`);
+    }
+    return { content: [{ type: 'text', text: sections.join('\n') }], isError: true };
+}

package/dist/exec/codes.js

@@ -0,0 +1,37 @@
+/**
+ * exec 域错误码注册（04 §11 spawn 管道 + §8 bash 工具件——EXEC_ 前缀族）。
+ *
+ * 前缀族在 contracts/errors.ts ERROR_CODE_PREFIXES 已注册（02 §5.3 #1）；
+ * 码名两枚为规范具名（EXEC_SPAWN_FAILED / EXEC_ENV_FORBIDDEN——04 §11/§8
+ * 原文），两枚为落码批定名（EXEC_TIMEOUT / EXEC_BACKGROUND_REJECTED——
+ * 04 §11 超时归因条与 §8「无后台化」截获条的拒执面，族清单随本批补明）。
+ * 本文件由模块公开面 index.ts 引入（注册纪律：import 发生才注册）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'EXEC_SPAWN_FAILED',
+        module: 'exec',
+        description: 'spawn 阶段失败（可执行不存在/权限——进程从未存在）与执行阶段失败（exitCode ≠ 0）分报的前者（04 §11 失败二分条）',
+    },
+    {
+        code: 'EXEC_ENV_FORBIDDEN',
+        module: 'exec',
+        description: 'env 白名单 deny-by-default 拒静默继承——请求继承/注入 deny 覆盖变量的凭证泄漏面封死（04 §11 env 白名单条）',
+    },
+    {
+        code: 'EXEC_TIMEOUT',
+        module: 'exec',
+        description: '执行超时——已进程组树杀，归因 timeout（04 §11 超时归因先到先得条；04 §8 timeoutMs 上限 600s）',
+    },
+    {
+        code: 'EXEC_BACKGROUND_REJECTED',
+        module: 'exec',
+        description: '后台化命令截获拒——尾部单 & 或命令位 nohup/disown（04 §8「无后台化」：模型不能脱管留后台进程）',
+    },
+    {
+        code: 'EXEC_GIT_REDIRECT_DENIED',
+        module: 'exec',
+        description: 'bash 重定向目标落在 .git 版本史内——carve-out 路径级直写硬拒（04 §252 桥条款腿一）：任何档无升权出路、白名单不豁免；git 元数据操作走命令白名单形（成熟度缺口 #9 落码批）',
+    },
+]);