@v587d/capital-generation 2.8.2 → 2.9.0

package/config/index.js

@@ -4,28 +4,10 @@ import { SELECTED_SKILL_CATALOG, SELECTED_SKILL_SKILL_DIRS } from '../selected-s
 export const name = 'capital-config'
 
 /**
- * 本包在 profile 里的**条目 id**。0.1.7 起它就是 settings 命名空间本身：
- * `dsh-settings` 不再接受 `settings.register()`，而是把**活动 profile 条目**的 Config schema 里
- * 声明为 `.volatile()` 的字段投影成表单，`ns` 恒等于 `entry.options.id`。两个事实因此承重：
- *
- *  1. **它是卡片的取数通道**：浏览器半边 `ctx.configForms.get(条目 id)` 与
- *     `whileServed([条目 id])` 都按它寻址；卡片本身注册进 `plugins.bundle.config`，
- *     key 是**组合包的包名**（`@v587d/capital-generation`），不是 `<包名>#<行 id>`。
- *     条目 id 或包名任一处漂移，表现都是**卡片静默消失**（零报错）。
- *  2. **它是取数配置的来源**：主插件 `@v587d/capital-generation` 经
- *     `settings.describe()` 读同一条目的解析值，拿 `fuyaoCredentialRef` /
- *     `retriever.credentialRef` / `retriever.windDocs.credentialRef` /
- *     `retriever.paddleOcr.credentialRef` 这些**引用名**去寻密钥。
- *
- * 密钥本身恒不进本条目：API Key 写在 credentials 域（`remote.credentials.set`），
- * 这里只存引用名。唯一写进配置的偏好是回退开关 `retriever.localFetch.enabled`。
- *
- * ⛔ 字段必须 `.volatile()`：`volatileForm(schema)` 在没有任何 volatile 字段时返回
- * `undefined`，该条目就**不进** describe 镜像——卡片读不到命名空间，写入也会被
- * `Config field "…" is not volatile` 拒绝。非 volatile 字段仍是普通配置，只能改 profile 文件。
- *
- * 浏览器半边镜像了这个 id（`client.src.cjs` 的 `ENTRY_ID`），两处同改由
- * `test/capital-config.test.mjs` 钉住。
+ * Profile entry id; 0.1.7 makes it the settings namespace itself. The browser half
+ * addresses it via `configForms.get(ENTRY_ID)` and the main plugin reads the same
+ * entry's `*.credentialRef` names; drift makes the card vanish silently. Every
+ * editable field must be `.volatile()` or describe omits it.
  */
 export const SETTINGS_ENTRY_ID = 'capital-config'
 
@@ -36,11 +18,8 @@ const WindDocsSchema = z.object({
 })
 
 /**
- * 本地直连回退默认值。必须与主插件 `src/index.ts` 的 `LOCAL_FETCH_DEFAULTS` 逐字一致
- * （两处 schema 漂移会被 `test/capital-config.test.mjs` 的 deepEqual 用例抓住）。
- * 数值口径对齐官方 `dsh-web-fetch-http`（timeoutMs=30000 / maxBodyChars=100000）；
- * `maxContentChars` 切在转换前的原始 HTML 上，所以按 HTML 体积给足。
- * `userAgent` 默认是产品标识；显式配成空串时消费点回落到插件版本号。
+ * Must match `LOCAL_FETCH_DEFAULTS` in `src/index.ts` verbatim (test pins it).
+ * `maxContentChars` cuts the pre-conversion HTML, so it is sized by HTML volume.
  */
 export const LOCAL_FETCH_DEFAULTS = {
   enabled: true,
@@ -61,12 +40,8 @@ const LocalFetchSchema = z.object({
 })
 
 /**
- * PaddleOCR 文档解析（`ocr` 工具）默认值。必须与主插件 `src/index.ts` 的
- * `PADDLE_OCR_DEFAULTS` 逐字一致（漂移被 `test/capital-config.test.mjs` 的 deepEqual 抓住）。
- *
- * `endpoint` / `model` 留空是把真值让给 `src/ocr/client.ts`；`pollBudgetMs: 0` = 客户端默认的
- * 200000 毫秒自有等待预算，必须小于 `ocr` 工具声明的 240000 超时，否则框架先超时、
- * 回执里没有 `doc_id` 可续查。
+ * Must match `PADDLE_OCR_DEFAULTS` in `src/index.ts` verbatim.
+ * `pollBudgetMs: 0` = client default 200000 ms, below the tool's 240000 timeout.
  */
 export const PADDLE_OCR_DEFAULTS = {
   endpoint: '',
@@ -84,15 +59,15 @@ const PaddleOcrSchema = z.object({
 
 const SelectedSkillsShape = Object.fromEntries(SELECTED_SKILL_CATALOG.map((entry) => [
   entry.key,
-  z.boolean().default(false).volatile().description(`Enable ${entry.name} for the Capital root Agent (experimental; default off)`),
+  z.boolean().default(false).volatile().description(`Enable ${entry.name} for the Auto mode root Agent (experimental; default off)`),
 ]))
 const SelectedSkillsSchema = z.object(SelectedSkillsShape)
 
 const SELECTED_SKILL_DEFAULTS = Object.fromEntries(SELECTED_SKILL_CATALOG.map((entry) => [entry.key, false]))
 
 export const Config = z.object({
-  customPersona: z.string().default('').volatile().description('Capital 模式附加人设文本'),
-  selectedSkills: SelectedSkillsSchema.default(SELECTED_SKILL_DEFAULTS).description('Explicitly selected community experiments; default off and visible only to the Capital root Agent'),
+  customPersona: z.string().default('').volatile().description('自动模式附加人设文本'),
+  selectedSkills: SelectedSkillsSchema.default(SELECTED_SKILL_DEFAULTS).description('Explicitly selected community experiments; default off and visible only to the Auto mode root Agent'),
   fuyaoCredentialRef: z.string().default('FUYAO_API_KEY').volatile().description('Fuyao credentials 引用名'),
   ftshareCredentialRef: z.string().default('FTSHARE_API_KEY').volatile().description('FTShare（非凸科技）credentials 引用名'),
   retriever: z.object({
@@ -115,30 +90,17 @@ export const Config = z.object({
 })
 
 /**
- * 「精选 Skills」那一格的**原文旁路**：卡片上的「详情」悬浮要显示 `SKILL.md` 原文，
- * 而原文是随包携带的快照文件（35 份共 ~750 KB）。
- *
- * 为什么走一条本机路由，而不是把原文打进客户端 bundle：客户端 bundle 在页面加载那一刻
- * 整体送达浏览器（`window.__ModuleLoader__.load` 是单文件 IIFE，没有按需分片），750 KB 会
- * 让每一次打开插件页都付一遍——包括从不点「详情」的那次。旁路只在悬停时取一份，且取的是
- * **磁盘上当前那份**，不是构建期抄的副本：抄来的原文会随快照更新而变旧，而这块 UI 说的
- * 是"这就是原文"（控件对自己的状态说谎 = 事故）。
- *
- * 闭集：路径按 `SELECTED_SKILL_CATALOG` × `SELECTED_SKILL_SKILL_DIRS` 在模块加载时现算成
- * `Map<skill 名, file: URL>`，请求里的名字**只做这张表的键**，不参与任何路径拼接——
- * `%2F..%2F` 之类一律落在"表里没有这个名字"那一侧（404）。路径用 `URL` 表示：`fs` 直接收
- * `file:` URL，省掉一次 `fileURLToPath`（也就省掉在 import 期依赖 node 内置模块）。
- *
- * ⛔ 认证围栏与 `/capital-charts`、`/capital-watchlist` 同一写法（`connection.requestRejection`，
- * docs/dev/chart-presentation.md §6.1）：`webServer.register({ kind: 'prefix' })` 本身不做任何认证。
+ * Read-only route for the "Selected Skills" detail hover: serves the packaged
+ * SKILL.md snapshot from disk instead of shipping ~750 KB in the client bundle.
+ * Request names only index a precomputed Map (never path fragments). Same auth
+ * fence as `/capital-charts` (`requestRejection`).
  */
 export const SKILL_DOC_ROUTE = '/capital-skills'
-/** 单份原文的字节上限：超限**整份拒绝、绝不截断**（"原文"被切一半比没有原文更误导人）。 */
+/** Byte cap per document: oversized files are rejected whole, never truncated. */
 export const MAX_SKILL_DOC_BYTES = 128 * 1024
 
 const SKILL_DOC_SUFFIX = 'SKILL.md'
 
-/** catalog 里的顺序 = 卡片上的顺序，所以这里只多算一份"名字 → 快照文件"的索引。 */
 export const SKILL_DOCS = new Map(SELECTED_SKILL_CATALOG.map((entry) => [
   entry.name,
   new URL(`../selected-skills/${entry.repository}/${SELECTED_SKILL_SKILL_DIRS[entry.repository]}/${entry.name}/${SKILL_DOC_SUFFIX}`, import.meta.url),
@@ -159,10 +121,7 @@ function sendJson(res, status, payload) {
   res.end(JSON.stringify(payload))
 }
 
-/**
- * @param options.readFile - `(url) => string | Buffer`，用例注入假读盘。
- * @param options.authorize - `(req) => 401 | 403 | undefined`；非空即拒，**且一次都不碰文件系统**。
- */
+/** `options.authorize` = `(req) => 401 | 403 | undefined`; non-empty rejects without touching fs. */
 export function createSkillDocHandler(options = {}) {
   const readFile = options.readFile ?? ((target) => fsModule().readFileSync(target, 'utf8'))
   const statSize = options.statSize ?? ((target) => fsModule().statSync(target).size)
@@ -173,7 +132,7 @@ export function createSkillDocHandler(options = {}) {
       try {
         rejection = authorize(req)
       } catch {
-        // 围栏自己答不上来时必须 fail closed：放行就等于"认证失败 = 不认证"。
+        // Fail closed: an authorizer that cannot answer must not mean "no auth".
         rejection = 401
       }
       if (rejection !== undefined && rejection !== null) {
@@ -220,7 +179,7 @@ export function createSkillDocHandler(options = {}) {
     try {
       bytes = statSize(target)
     } catch {
-      // 快照没随包落地（装到一半 / files 清单漏了）：说清楚"读不到"，别回一份空原文当好结果。
+      // Snapshot missing from the package: say unreadable, never an empty document.
       sendJson(res, 404, { error: 'skill_doc_unreadable', name })
       return
     }
@@ -243,23 +202,14 @@ export function createSkillDocHandler(options = {}) {
   }
 }
 
-/**
- * 卡片那侧拼 URL 的唯一口径（文件名里带 `.` 的 slug 也要能拼，所以走 encodeURIComponent）。
- * 客户端 bundle 与这里是**同一条字符串**的两端：漂移的表现为"详情永远读不到"，由
- * `test/capital-config.test.mjs` 的同字断言钉住（客户端不能 import 本模块 ⇒ 只能对着产物量）。
- */
+/** URL built identically in the client bundle; drift = details never load (test pins both). */
 export function skillDocUrl(name) {
   return `${SKILL_DOC_ROUTE}/${encodeURIComponent(name)}.md`
 }
 
 /**
- * 本行消费两件事：自己的配置（schema 事实，见上）与快照原文的读盘旁路。
- *
- * `webServer` 只走 `inject`——`ctx.get('webServer')` 解析得到值**不代表**属性访问合法
- * （cordis 的属性代理只认"本层声明过 inject"），探测式写法会把正确性押在装配顺序上，
- * 这条踩过两次（见 `chart-ui/index.js` 的同一段注释）。认证面 `connection` 反之要**惰性**
- * 解析：它缺席（Electron / file:// 这类没有浏览器认证面的载体）就退化成"没有认证面"的旧行为，
- * 但解析抛错一律 401。
+ * `webServer` only via inject (probing `ctx.webServer` bets on mount order);
+ * `connection` resolved lazily: absent = no auth plane, throwing = 401.
  */
 export function apply(ctx) {
   const authorize = (req) => {

package/config/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@v587d/config",
-  "version": "2.8.2",
-  "description": "Capital 模式的取数凭据与偏好配置行：卡片坐在 @v587d/capital-generation 插件主页的「配置」段，点这一行本身没有表单。",
+  "version": "2.9.0",
+  "description": "自动模式的取数凭据与偏好配置行：卡片坐在 @v587d/capital-generation 插件主页的「配置」段，点这一行本身没有表单。",
   "license": "MIT",
   "type": "module",
   "exports": {

package/cordis.patch.yml

@@ -1,42 +1,29 @@
 # Capital Generation is a distributable DSH profile bundle.
-#
-# 本文件只挂 **host 平面** 的客户端 bundle 行（下面三个 insert）。预设不在这里：0.1.7 起
-# 预设是普通条目行，本包的预设声明住在 `preset/capital-generation/agent.patch.yml`，由
-# package.json 的 `dsh.bundle.patch` 数组按序应用（`agent-preset-registry` 行由 dsh-web-app
-# 自己提供，我们只 insert 自己的预设声明，不动它的 config）。
-#
-# ⛔ 升级事故（2026-09-26，issue #3）：这里原先是 patch `agent-presets` 行 + `config.roots`
-# 的目录式注册。0.1.7 把该条目改名为 `agent-preset-registry` 并**删掉了 roots 机制**（registry
-# 「既不扫目录也不接受预设路径」），于是每次启动静默报
-# `dsh: [@v587d/capital-generation] patch: entry "agent-presets" not found` —— 预设永不注册，
-# 历史会话（头部记着 `"agentPreset":"capital-generation"`）全部 `Unknown agent preset` 读不回。
+# This file mounts host-plane rows only (the inserts below). Presets are ordinary entry rows and
+# live in preset/capital-generation/agent.patch.yml, applied in order by package.json's
+# `dsh.bundle.patch`; we insert our own preset declaration and never touch the registry's config.
+# ⛔ Do not register presets by patching an `agent-presets` row's `config.roots`: 0.1.7 renamed the
+# entry to `agent-preset-registry` and deleted the roots mechanism. The failure is a single boot warn
+# (`patch: entry "agent-presets" not found`), so presets never register and every saved session
+# reopening with `"agentPreset":"capital-generation"` reports `Unknown agent preset`.
 
-# ── 图表前端组件（host 平面行）────────────────────────────────────────────────
-#
-# 为什么这一行必须在这里、必须是 host 平面：客户端 bundle 的注入发生在
-# index.html 渲染那一刻，运行期新增 entry 没有送达浏览器的通道；挂在 preset 行上的
-# 客户端 bundle 到不了已经打开的页面。见 chart-ui/README.md。
+# ── Chart frontend (host plane) ────────────────────────────────────────────────
+# Host plane because client bundles are injected at index.html render time; a bundle mounted on a
+# preset row never reaches an already-open page (see chart-ui/README.md).
+# `name` must be a literal, path-like relative path — three pitfalls, each hit for real:
+#  1. only `config` is interpolated, so `!!js` in `name` reaches the ESM import verbatim
+#     (`name.startsWith is not a function`, whole profile fails to boot).
+#  2. a subpath specifier (`@v587d/capital-generation/chart-ui`) is neither path-like nor a
+#     resolvable package name, so locatePkgJson silently classifies the row as "not a client
+#     bundle": the bundle never enters __DSH_BOOT__, the UI is missing, nothing is logged.
+#  3. the resolution base is this file's directory, not the profile root, so `./chart-ui/index.js`
+#     works under any node_modules layout; package identity comes from chart-ui/package.json
+#     (@v587d/capital-charts), which is why it cannot collide with the main package.
+# Regression: test/chart-composition.test.mjs (name stays a literal path-like string and resolves).
 #
-# 为什么行名是**相对本包目录的路径**（三个坑都踩过，都不是猜的）：
-#  1. **`name` 不接受 `!!js`**：loader 只对 fiber 的 `config` 做插值
-#     （cordis-plugin-loader 的 `internal/config` 钩子），`name` 永远按字面量送进 ESM import。
-#     写过 !!js 的后果是启动期 `name.startsWith is not a function`——整个 profile 起不来。
-#  2. **`name` 也不能是 subpath 说明符**（如 `@v587d/capital-generation/chart-ui`）：
-#     dsh-client-modules 的 locatePkgJson 里
-#       `if (!pathLike && exactPackageSpecifier(loaderName) === undefined) return undefined`
-#     —— subpath 既非 path-like、打包名解析又返回 undefined，于是这颗行被**静默**当成
-#     "不是客户端包"，bundle 永不进 __DSH_BOOT__（表现是图表 UI 不出现，且不报错）。
-#  3. 解析基址是**本 patch 文件所在目录**，不是 profile 根：
-#     cordis-plugin-include 装载 patch 时会 `ctx.baseUrl = new URL('.', pathToFileURL(filename))`。
-#     所以这里的相对路径就是本包目录下的 chart-ui/index.js —— 与 profile 的 node_modules
-#     布局无关（pnpm 的 isolated 布局也照常工作）。
-#     locatePkgJson 随后按"最近的 package.json"归属，正好是 chart-ui/package.json，
-#     包身份为 @v587d/capital-charts，与主包不撞名。
-# 回归断言见 test/chart-composition.test.mjs（name 必须是字面量且 path-like，并真的解析一次）。
-#
-# ⚠ 目录名 / 包名与**行 id 是两条独立的链**（AGENTS.md §5.1）：下面两颗行住在 `config/` 与
-# `watchlist/`，行 id 却仍是 `capital-config` / `capital-watchlist`——后者是 settings 命名空间与
-# 「包含的组件」里那两行的身份，改了就会吃掉用户已保存的配置。不许"顺手对齐"。
+# ⚠ Directory name and row id are two independent chains (AGENTS.md §5.1): the rows below live in
+# `config/` and `watchlist/`, yet keep ids `capital-config` / `capital-watchlist` — those ids are
+# the settings namespace and the identity of the user's saved config; "aligning" them discards it.
 - insert:
     - id: capital-config
       name: './config/index.js'
@@ -55,22 +42,30 @@
     - id: capital-charts
       name: './chart-ui/index.js'
 
-# ── 用户自选股（host 平面行）──────────────────────────────────────────────────
-#
-# 为什么也必须在 host 平面：自选股是**跨 workspace 的用户侧资产**（清单与报价快照落
-# `~/.dsh/storages/capital_watchlist.json`），而客户端 bundle 的注入只发生在 index.html
-# 渲染那一刻——挂在 preset 行上就到不了已经打开的页面（同 chart-ui 的理由）。
-#
-# 与上一颗 preset 行的方向是**反的**：chart-ui 的数据由插件侧 push 进来（`ctx.get` 只能
-# 从会话作用域向外解析），本行则要在 host 平面自己出网，所以它 import
-# `../lib/sources/fuyao-core.js`（零 import 的叶子内核）——**同一份** key 解析 / 信封判定 /
-# 错误映射，不许有第二份（AGENTS.md §9.7）。这条跨包相对导入在本仓没有先例，因此由
-# `test/watchlist-quote.test.mjs` 的**模块同一性探针**钉住：两处 import 必须拿到同一实例，
-# 探针不过就重新设计，而不是先上线再说。
-#
-# `id` 与 `./watchlist/index.js` 的 path-like 字面量规则同上（!!js / subpath 两个坑
-# 对这颗行同样成立）。
+# ── User watchlist (host plane) ───────────────────────────────────────────────
+# Cross-workspace user asset (~/.dsh/storages/capital_watchlist.json), so host plane for the same
+# injection reason as chart-ui; the `name` rules above apply here too.
+# Direction is the opposite of chart-ui's: this row reaches the network itself, so it imports
+# ../lib/sources/fuyao-core.js (a zero-import leaf) rather than a second copy of key resolution,
+# envelope checks and error mapping (AGENTS.md §9.7). No precedent for that cross-package relative
+# import here, so test/watchlist-quote.test.mjs pins module identity: both import sites must get
+# the same instance, and if the probe fails the design is wrong — don't ship it and hope.
 - insert:
     - id: capital-watchlist
       name: './watchlist/index.js'
 
+# ── Cross-preset runtime / policy (0.2.1) ─────────────────────────────────────
+# Root and role presets mount separately, so apply() runs several times per process. Shared state
+# (chart source tokens, chart artifacts) and the agent/created listeners (root convergence, shell
+# and fs guards) must exist exactly once, which only a host-plane provide gives.
+# These two rows use package subpath entries (@v587d/capital-generation/runtime and /policy): they
+# are server-side, so the literal-path rule above doesn't apply — DSH composes its own
+# @deepseek-ai/dsh-tool-subagent-control rows the same way.
+- insert:
+    - id: capital-runtime
+      name: '@v587d/capital-generation/runtime'
+
+- insert:
+    - id: capital-policy
+      name: '@v587d/capital-generation/policy'
+

package/lib/agents/bash-guard.d.ts

@@ -1,60 +1,14 @@
-/**
- * shell 调用闸门（`bash` / `pwsh` 两个名字都认，只拦**必然失败的沙箱升级**，不看命令内容）。
- *
- * 背景与边界（设计理由全文在 preset/capital-generation/README.md）：
- *  - bash 不是计算器，是一台完整终端。本仓实测：沙箱**只拦写**（workspace + /tmp 之外
- *    一律 EROFS），**不拦读**（`~/.dsh/.credentials.yaml`、`sessions/**` 整机可读），
- *    **不拦网络**（`curl` 直连 200）。这是 DSH 沙箱词汇表的既定边界——`SandboxMode`
- *    只覆盖文件效果，官方文档亦如此声明。
- *  - 因此本文件**不做命令内容匹配**：正则挡不住 `node -e`/`python3 -c`，而 node/python
- *    正是引入 bash 的目的（未来 data_analyst 也靠它）。禁区与出网纪律走 data_junior 的
- *    persona 软约束，不在这里伪装成安全边界。
- *  - 沙箱写边界也无法单独收窄：数据集管线自己就走沙箱，`store.writeContext()` 用**调用方
- *    session** 的 policy 且要求 mode ∈ {workspace-write, danger-full-access}，把 data_junior
- *    的会话钉成 read-only 会直接打断 `describe_dataset` 的 profile 落盘
- *    （`workspace_not_writable`）。bash 与 Dataset 管线共用同一把尺子（session policy）。
- *
- * 规则只留一层（2026-10-15 用户决策「开 read、同时保留 bash」后）：
- *  A 结构层（**已随决策移除**）：曾拒绝根会话的 shell 调用（"只对被委派子会话开放"）。
- *    现在主 Agent 保留 bash / pwsh（读 skill 分册、纯计算）；shell 归谁由可见性收敛——
- *    `ROOT_AGENT_DENIED_TOOLS` 不再含 shell 名，子会话侧由委派行的 `toolFilter` 把 shell
- *    只给 data_junior。迁移的断言在 `test/bash-guard.test.mjs`（根会话放行是**新契约**）。
- *  B UX 层（保留，收窄到"被委派 / 身份不可考的调用方"）：委派子会话的审批策略由框架固定为
- *    `never`（dsh-subagent 的 `captureDelegatedPolicyOverrides` → `approval/policy: never`，
- *    `dsh-user-approval.decide()` 在 never 时**直接返回 rejected、根本不调用 answerer**），
- *    所以 `sandbox_permissions` 必然失败，而且模型会收到「the user rejected…」这种
- *    **把系统拒绝说成用户拒绝**的文案。这里提前拦下并给出正确路径：省一次必然白跑的往返 +
- *    纠正归因。主 Agent 自己的升级照常走 ask 审批（那正是 escalation 的正当用途）。
- *
- * 为什么用 `tools.guard` 而不是 `tools/pre-execute`：guard 是**单调**的（没有 allow 结果，
- * 任何监听顺序都无法把别人的 deny 翻回 allow），同步、拿到解析后的 `arguments`，且
- * 「注册在 agent.ctx 上就只作用于该 agent」。pre-execute 是 waterfall，可扩展也意味着可被后续
- * 监听改写。
- */
+/** Shell guard for bash/pwsh: blocks only doomed sandbox escalation; command content is never
+ * inspected (the sandbox blocks writes, not reads/network). Delegated approvals are fixed to
+ * `never`, so escalation auto-rejects with a misleading "user rejected"; block early instead.
+ * Root escalation still uses ask; do not pin delegated sessions read-only (`store.writeContext`
+ * needs workspace-write). `tools.guard` is monotonic; pre-execute is a rewritable waterfall. */
 import { type GuardedExecution, type PolicyContext } from './root-tool-policy.js';
-/** 闸门看到的调用形状：guard 拿到的是解析后的 arguments，不是一个 shell 字符串。 */
 export type BashGuardExecution = GuardedExecution;
-/**
- * 沙箱升级拒绝文案：说清"这不是用户拒绝"，并给出正确路径。
- * （A 结构层文案 `SHELL_DELEGATED_ONLY` 随 2026-10-15 决策删除，断言迁移到
- * `test/bash-guard.test.mjs` 的"根会话放行"用例。）
- */
+/** States that the rejection is the system's, not the user's, and gives the recovery path. */
 export declare const SHELL_ESCALATION_UNREACHABLE: string;
-/**
- * 单次 shell 调用的判定：返回拒绝理由，或 undefined 放行。
- *
- * 2026-10-15 起主 Agent 的 shell 调用一律放行（A 层随决策移除）；被拦的只有**升级参数**
- * ——注意这里**只读两个字段**（调用方身份、`sandbox_permissions`/`justification`），
- * 绝不解析 `command`——理由见文件头。升级判不了身份时 fail closed：根会话的形状是
- * "有 session 且无 parentSession"，证明不了就当最坏打算，不给"拿不到身份就放行"的口子。
- */
+/** Reads identity plus `sandbox_permissions`/`justification`, never `command`; unknown identity fails closed. */
 export declare function bashGuardReason(exec: BashGuardExecution | undefined): string | undefined;
-/**
- * 注册 shell 闸门：对**本 preset 的每个 agent**（含主 Agent）在它自己的 scope 上装一次 guard。
- *
- * 监听位置与 `registerRootToolPolicy` 同因：`agent/created` 的路由键是 agent 对象本身，
- * 注册在 standing scope（打了标签）的监听器**收不到且不报错**，必须挂 `ctx.root`。
- * 安装/释放都不得抛回 agent 创建路径——宁可少一层闸门，也不能挡住建 agent；
- * 静默失败会留下诊断 warn（见 `registerBashGuard` 的返回值处理）。
- */
+/** Installs on every Capital preset agent. Must listen on `ctx.root`: agent/created routes by
+ * the agent object, so tagged standing-scope listeners never fire. Failures only warn. */
 export declare function registerBashGuard(ctx: PolicyContext): void;

package/lib/agents/bash-guard.js

@@ -1,64 +1,21 @@
-/**
- * shell 调用闸门（`bash` / `pwsh` 两个名字都认，只拦**必然失败的沙箱升级**，不看命令内容）。
- *
- * 背景与边界（设计理由全文在 preset/capital-generation/README.md）：
- *  - bash 不是计算器，是一台完整终端。本仓实测：沙箱**只拦写**（workspace + /tmp 之外
- *    一律 EROFS），**不拦读**（`~/.dsh/.credentials.yaml`、`sessions/**` 整机可读），
- *    **不拦网络**（`curl` 直连 200）。这是 DSH 沙箱词汇表的既定边界——`SandboxMode`
- *    只覆盖文件效果，官方文档亦如此声明。
- *  - 因此本文件**不做命令内容匹配**：正则挡不住 `node -e`/`python3 -c`，而 node/python
- *    正是引入 bash 的目的（未来 data_analyst 也靠它）。禁区与出网纪律走 data_junior 的
- *    persona 软约束，不在这里伪装成安全边界。
- *  - 沙箱写边界也无法单独收窄：数据集管线自己就走沙箱，`store.writeContext()` 用**调用方
- *    session** 的 policy 且要求 mode ∈ {workspace-write, danger-full-access}，把 data_junior
- *    的会话钉成 read-only 会直接打断 `describe_dataset` 的 profile 落盘
- *    （`workspace_not_writable`）。bash 与 Dataset 管线共用同一把尺子（session policy）。
- *
- * 规则只留一层（2026-10-15 用户决策「开 read、同时保留 bash」后）：
- *  A 结构层（**已随决策移除**）：曾拒绝根会话的 shell 调用（"只对被委派子会话开放"）。
- *    现在主 Agent 保留 bash / pwsh（读 skill 分册、纯计算）；shell 归谁由可见性收敛——
- *    `ROOT_AGENT_DENIED_TOOLS` 不再含 shell 名，子会话侧由委派行的 `toolFilter` 把 shell
- *    只给 data_junior。迁移的断言在 `test/bash-guard.test.mjs`（根会话放行是**新契约**）。
- *  B UX 层（保留，收窄到"被委派 / 身份不可考的调用方"）：委派子会话的审批策略由框架固定为
- *    `never`（dsh-subagent 的 `captureDelegatedPolicyOverrides` → `approval/policy: never`，
- *    `dsh-user-approval.decide()` 在 never 时**直接返回 rejected、根本不调用 answerer**），
- *    所以 `sandbox_permissions` 必然失败，而且模型会收到「the user rejected…」这种
- *    **把系统拒绝说成用户拒绝**的文案。这里提前拦下并给出正确路径：省一次必然白跑的往返 +
- *    纠正归因。主 Agent 自己的升级照常走 ask 审批（那正是 escalation 的正当用途）。
- *
- * 为什么用 `tools.guard` 而不是 `tools/pre-execute`：guard 是**单调**的（没有 allow 结果，
- * 任何监听顺序都无法把别人的 deny 翻回 allow），同步、拿到解析后的 `arguments`，且
- * 「注册在 agent.ctx 上就只作用于该 agent」。pre-execute 是 waterfall，可扩展也意味着可被后续
- * 监听改写。
- */
-import { agentSessionId, isCapitalAgent, SHELL_TOOL_NAMES } from './root-tool-policy.js';
-/**
- * shell 工具名全集（`bash` / `pwsh`，定义只在 {@link SHELL_TOOL_NAMES} 一份）。
- *
- * ⛔ 这里不能按 `process.platform` 挑一个：preset 里那两行是平台成对挂载的，Windows 上
- * 模型调的是 `pwsh`，而闸门跑在**同一个进程**里——只认 `bash` 的话，两层判定在 Windows 上
- * 一次都不触发，且不报错（2026-09-30 实测发现，症状是"§1.6 那道闸门在 Windows 上是死代码"）。
- */
+/** Shell guard for bash/pwsh: blocks only doomed sandbox escalation; command content is never
+ * inspected (the sandbox blocks writes, not reads/network). Delegated approvals are fixed to
+ * `never`, so escalation auto-rejects with a misleading "user rejected"; block early instead.
+ * Root escalation still uses ask; do not pin delegated sessions read-only (`store.writeContext`
+ * needs workspace-write). `tools.guard` is monotonic; pre-execute is a rewritable waterfall. */
+import { agentSessionId, isCapitalPresetAgent, SHELL_TOOL_NAMES } from './root-tool-policy.js';
+/** Both names on every platform: the preset mounts a pair, so matching only the local platform kills the Windows gate. */
 const shellToolNames = new Set(SHELL_TOOL_NAMES);
-/**
- * 沙箱升级拒绝文案：说清"这不是用户拒绝"，并给出正确路径。
- * （A 结构层文案 `SHELL_DELEGATED_ONLY` 随 2026-10-15 决策删除，断言迁移到
- * `test/bash-guard.test.mjs` 的"根会话放行"用例。）
- */
+/** One listener set per root context: host policy and legacy call sites install once. */
+const installedRoots = new WeakSet();
+/** States that the rejection is the system's, not the user's, and gives the recovery path. */
 export const SHELL_ESCALATION_UNREACHABLE = 'shell 工具（bash / pwsh）的沙箱升级只有主 Agent 的会话能拿到用户审批：被委派的子会话拿不到'
     + '（框架把委派会话的审批策略固定为 never，不会去问用户），当前调用方也不是可确认的主 Agent 会话。'
     + '不要重试升级：缺数值用 describe_dataset / query_dataset，缺数据用 send_message 发 data_gap 回主 Agent。';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/**
- * 单次 shell 调用的判定：返回拒绝理由，或 undefined 放行。
- *
- * 2026-10-15 起主 Agent 的 shell 调用一律放行（A 层随决策移除）；被拦的只有**升级参数**
- * ——注意这里**只读两个字段**（调用方身份、`sandbox_permissions`/`justification`），
- * 绝不解析 `command`——理由见文件头。升级判不了身份时 fail closed：根会话的形状是
- * "有 session 且无 parentSession"，证明不了就当最坏打算，不给"拿不到身份就放行"的口子。
- */
+/** Reads identity plus `sandbox_permissions`/`justification`, never `command`; unknown identity fails closed. */
 export function bashGuardReason(exec) {
     if (exec === undefined || typeof exec.name !== 'string' || !shellToolNames.has(exec.name))
         return undefined;
@@ -70,7 +27,6 @@ export function bashGuardReason(exec) {
     const knownRoot = exec.agent?.session !== undefined && (typeof parent !== 'string' || parent.length === 0);
     return knownRoot ? undefined : SHELL_ESCALATION_UNREACHABLE;
 }
-/** 在某个 agent 自己的 scope 上安装 guard，返回 disposer（不可用时返回 undefined）。 */
 function installAgentGuard(agent) {
     let tools;
     try {
@@ -89,25 +45,22 @@ function installAgentGuard(agent) {
         return undefined;
     }
 }
-/**
- * 注册 shell 闸门：对**本 preset 的每个 agent**（含主 Agent）在它自己的 scope 上装一次 guard。
- *
- * 监听位置与 `registerRootToolPolicy` 同因：`agent/created` 的路由键是 agent 对象本身，
- * 注册在 standing scope（打了标签）的监听器**收不到且不报错**，必须挂 `ctx.root`。
- * 安装/释放都不得抛回 agent 创建路径——宁可少一层闸门，也不能挡住建 agent；
- * 静默失败会留下诊断 warn（见 `registerBashGuard` 的返回值处理）。
- */
+/** Installs on every Capital preset agent. Must listen on `ctx.root`: agent/created routes by
+ * the agent object, so tagged standing-scope listeners never fire. Failures only warn. */
 export function registerBashGuard(ctx) {
     const listenCtx = ctx.root ?? ctx;
     if (typeof listenCtx.on !== 'function')
         return;
-    /** agent 会话 id → guard 的 disposer；agent/disposed 时释放，避免跨实例残留。 */
+    if (installedRoots.has(listenCtx))
+        return;
+    installedRoots.add(listenCtx);
+    /** Session id -> disposer; released on agent/disposed to avoid cross-instance leaks. */
     const guards = new Map();
     const install = () => {
         const stopCreated = listenCtx.on?.('agent/created', (payload) => {
             try {
                 const agent = payload?.agent;
-                if (!isCapitalAgent(ctx, agent))
+                if (!isCapitalPresetAgent(ctx, agent))
                     return;
                 const dispose = installAgentGuard(agent);
                 if (dispose === undefined) {
@@ -133,7 +86,7 @@ export function registerBashGuard(ctx) {
                 guards.delete(id);
                 dispose();
             }
-            catch { /* 释放失败不该影响 agent 拆除路径 */ }
+            catch { /* disposal must not break agent teardown */ }
         });
         return () => {
             try {
@@ -158,7 +111,14 @@ export function registerBashGuard(ctx) {
     if (typeof ctx.effect === 'function') {
         ctx.effect(() => {
             const dispose = install();
-            return () => dispose();
+            return () => {
+                try {
+                    dispose();
+                }
+                finally {
+                    installedRoots.delete(listenCtx);
+                }
+            };
         }, 'capital-generation.bash-guard()');
         return;
     }

package/lib/agents/preset-roster.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Hide delegation-only role presets from the host's new-session roster.
+ *
+ * The registry has no hidden flag. `remoteExportList()` is what the remote `agentPresets/list`
+ * endpoint invokes, so wrapping it changes the selector without touching `list()`, `resolve()`,
+ * delegation or settings management. Fail open: unknown shapes and missing methods leave the
+ * roster untouched, and fiber cleanup restores the original property descriptor.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+type EffectContext = {
+    effect?: (execute: () => () => void, label?: string) => unknown;
+};
+/** Drop internal rows without mutating the caller's array; unknown shapes pass through. */
+export declare function filterPresetRoster(value: unknown): unknown;
+/**
+ * Install on one registry instance. Returns false when the host exposes no roster method or the
+ * property cannot be shadowed; callers then behave exactly as if this filter did not exist.
+ */
+export declare function installPresetRosterFilter(service: unknown, ctx: EffectContext): boolean;
+/** Wait for the registry service, then filter its remote roster. */
+export declare function registerPresetRosterFilter(ctx: Context): void;
+export {};

package/lib/agents/preset-roster.js

@@ -0,0 +1,87 @@
+import { isInternalRolePresetId } from '../preset-ids.js';
+// A future host may serve `agentPresets/list` straight from `list`; prefer the dedicated export.
+const METHODS = ['remoteExportList', 'list'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isInternalRow(row) {
+    return isRecord(row) && isInternalRolePresetId(row.id);
+}
+/** Drop internal rows without mutating the caller's array; unknown shapes pass through. */
+export function filterPresetRoster(value) {
+    try {
+        if (Array.isArray(value))
+            return value.filter((row) => !isInternalRow(row));
+        if (!isRecord(value) || !Array.isArray(value.presets))
+            return value;
+        return { ...value, presets: value.presets.filter((row) => !isInternalRow(row)) };
+    }
+    catch {
+        return value;
+    }
+}
+function pickMethod(service) {
+    return METHODS.find((method) => typeof service[method] === 'function');
+}
+/**
+ * Install on one registry instance. Returns false when the host exposes no roster method or the
+ * property cannot be shadowed; callers then behave exactly as if this filter did not exist.
+ */
+export function installPresetRosterFilter(service, ctx) {
+    if (!isRecord(service))
+        return false;
+    const method = pickMethod(service);
+    if (method === undefined)
+        return false;
+    const original = service[method];
+    if (typeof original !== 'function')
+        return false;
+    const previous = Object.getOwnPropertyDescriptor(service, method);
+    const wrapper = (...args) => {
+        const result = original.call(service, ...args);
+        try {
+            if (isRecord(result) && typeof result.then === 'function') {
+                return result.then((value) => filterPresetRoster(value));
+            }
+            return filterPresetRoster(result);
+        }
+        catch {
+            return result;
+        }
+    };
+    try {
+        Object.defineProperty(service, method, {
+            configurable: true,
+            enumerable: previous?.enumerable ?? false,
+            writable: true,
+            value: wrapper,
+        });
+    }
+    catch {
+        return false;
+    }
+    const restore = () => {
+        if (service[method] !== wrapper)
+            return;
+        try {
+            if (previous === undefined)
+                delete service[method];
+            else
+                Object.defineProperty(service, method, previous);
+        }
+        catch {
+        }
+    };
+    if (typeof ctx.effect === 'function')
+        ctx.effect(() => restore, 'capital-preset-roster');
+    return true;
+}
+/** Wait for the registry service, then filter its remote roster. */
+export function registerPresetRosterFilter(ctx) {
+    const host = ctx;
+    if (typeof host.inject !== 'function')
+        return;
+    host.inject(['agentPresets'], (injected) => {
+        installPresetRosterFilter(injected.agentPresets, injected);
+    });
+}