@v587d/capital-generation 0.0.0-stage → 2.6.0

package/chart-ui/client.src.cjs

@@ -0,0 +1,126 @@
+/**
+ * `@v587d/capital-charts` browser half.
+ *
+ * 单一 surface：`tool.call.toolview['render_chart']` —— 图表生成过程的明细卡片
+ * （子会话与展开视图里都能看）。数据经 `/capital-charts/<chart_id>.json` 旁路取，
+ * 不进任何 Agent 上下文。
+ *
+ * ⚠️ 这里**没有** turn-tail 卡片，且不要再加回来（2026-09-18 事故，实测根因）：
+ * 内嵌卡片依赖宿主往会话里追加自定义事件 `capital/chart-rendered`，而会话日志的事件
+ * 词汇表是闭集——`Session.append` 无法设置 `ignorable`，非 first-party 事件写进去之后，
+ * **整份会话在冷加载时会被 fail-closed 拒绝**（6 份会话 `failed to observe session`）。
+ * 现在图表以官方 `deliverables/presented` 登记为「本轮交付」，用户在收尾的交付行点开
+ * `chart.html`，由官方 document preview 的 script-enabled iframe 渲染自包含图表
+ * （见 src/chart/events.ts）。**呈现走官方通道，客户端不再需要任何图表专属投影。**
+ */
+const { useEffect, useRef, useState, createElement: h } = require('react')
+const LightweightCharts = require('lightweight-charts')
+const { __capitalChart } = require('./client.runtime.gen.cjs')
+
+const TOOLVIEW_SLOT = 'tool.call.toolview'
+
+function readReceipt(block) {
+  if (!block || block.kind !== 'tool-result') return undefined
+  const items = Array.isArray(block.content) ? block.content : []
+  for (const item of items) {
+    if (item && item.type === 'text' && typeof item.text === 'string') {
+      try {
+        const parsed = JSON.parse(item.text)
+        if (parsed && typeof parsed === 'object') return parsed
+      } catch {
+        // Not the structured receipt; continue scanning.
+      }
+    }
+  }
+  return undefined
+}
+
+function ChartCanvas(props) {
+  const holder = useRef(null)
+  useEffect(() => {
+    const node = holder.current
+    if (!node || !props.payload) return undefined
+    let chart
+    try {
+      chart = __capitalChart.render(node, props.payload, LightweightCharts)
+    } catch (error) {
+      node.textContent = '图表渲染失败：' + String((error && error.message) || error)
+    }
+    return () => {
+      try {
+        if (chart && typeof chart.remove === 'function') chart.remove()
+      } catch {
+        // The host removed the card.
+      }
+    }
+  }, [props.payload])
+  return h('div', { ref: holder, 'data-chart-canvas': '1', style: { width: '100%', height: '320px' } })
+}
+
+function useJson(url) {
+  const [value, setValue] = useState(null)
+  const [error, setError] = useState(null)
+  useEffect(() => {
+    setValue(null)
+    setError(null)
+    if (!url) return undefined
+    const controller = typeof AbortController === 'function' ? new AbortController() : null
+    let active = true
+    fetch(url, controller ? { cache: 'no-store', signal: controller.signal } : { cache: 'no-store' })
+      .then((response) => {
+        if (!response.ok) throw new Error('HTTP ' + response.status)
+        return response.json()
+      })
+      .then((next) => {
+        if (active) setValue(next)
+      })
+      .catch((reason) => {
+        if (active) setError(String((reason && reason.message) || reason))
+      })
+    return () => {
+      active = false
+      if (controller) controller.abort()
+    }
+  }, [url])
+  return { value, error }
+}
+
+/** 工具过程明细：保留在子会话与展开视图里。 */
+function ChartView(props) {
+  const block = props.block
+  const settled = Boolean(block) && block.kind === 'tool-result'
+  const failed = settled && block.isError
+  const receipt = settled ? readReceipt(block) : undefined
+  const url = receipt && typeof receipt.chart_url === 'string' ? receipt.chart_url : null
+  const { value: payload, error: loadError } = useJson(url)
+
+  if (!settled) return h('div', { className: 'capital-chart', 'data-state': 'running' }, '正在生成图表…')
+  if (failed || !receipt) return h('div', { className: 'capital-chart', 'data-state': 'error' }, '图表生成失败。')
+
+  const openHtml = () => {
+    if (typeof receipt.html_path === 'string') props.openFile(receipt.html_path)
+  }
+  const head = h(
+    'div',
+    { className: 'capital-chart-head', style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: '8px', fontSize: '12px', color: 'var(--dsw-alias-label-secondary)' } },
+    h('span', null, typeof receipt.title === 'string' && receipt.title.length > 0 ? receipt.title : '图表'),
+    h('button', { type: 'button', onClick: openHtml, title: '打开自包含图表文件', style: { font: 'inherit', background: 'none', border: 'none', color: 'var(--dsw-alias-link)', cursor: 'pointer', padding: 0 } }, '打开'),
+  )
+
+  let body
+  if (url === null) body = h('div', { className: 'capital-chart-note' }, '图表已生成；点“打开”查看可交互文件。')
+  else if (loadError !== null) body = h('div', { className: 'capital-chart-note' }, `图表数据取不到（${loadError}），可点“打开”查看自包含文件。`)
+  else if (payload === null) body = h('div', { className: 'capital-chart-note', 'data-state': 'loading' }, '正在加载图表数据…')
+  else body = h(ChartCanvas, { payload })
+  return h('div', { className: 'capital-chart', 'data-state': 'ok', style: { margin: '8px 0' } }, head, body)
+}
+
+function apply(ctx) {
+  ctx.slots.inject(TOOLVIEW_SLOT, () => ctx.slots.register({ name: TOOLVIEW_SLOT, key: 'render_chart' }, ChartView))
+  ctx.logger?.info?.('capital-charts: 客户端半边已挂载（render_chart toolview；呈现走官方交付通道）')
+}
+
+exports.name = 'capital-charts'
+exports.inject = ['slots']
+exports.apply = apply
+exports.ChartView = ChartView

package/chart-ui/index.js

@@ -0,0 +1,205 @@
+/**
+ * `@v587d/capital-charts` 的 host half。
+ *
+ * It owns only opaque chart registrations and their browser route. It never
+ * reads Dataset files itself; render_chart supplies the resolved chart series
+ * path, and the turn event published by the plugin carries the small metadata
+ * the client renders.
+ */
+
+export const name = 'capital-charts'
+export const ROUTE_PATH = '/capital-charts'
+
+const CHART_ID_PATTERN = /^ch_[A-Za-z0-9._-]{1,80}$/
+const MAX_ENTRIES = 500
+
+function defaultReadFile(path) {
+  const processLike = globalThis.process
+  const fs = processLike?.getBuiltinModule?.('node:fs')
+  if (!fs || typeof fs.readFileSync !== 'function') throw new Error('capital-charts: Node fs is unavailable')
+  return fs.readFileSync(path, 'utf8')
+}
+
+export function createChartStore(options = {}) {
+  const readFile = options.readFile ?? defaultReadFile
+  let routeReady = options.routeReady ?? true
+  const files = new Map()
+
+  return {
+    publish(input) {
+      const chartId = input?.chartId
+      const filePath = input?.filePath
+      if (typeof chartId !== 'string' || !CHART_ID_PATTERN.test(chartId)) {
+        throw new Error(`capital-charts: chart_id is invalid: ${String(chartId)}`)
+      }
+      if (typeof filePath !== 'string' || filePath.length === 0) {
+        throw new Error('capital-charts: filePath is required')
+      }
+      files.delete(chartId)
+      files.set(chartId, filePath)
+      while (files.size > MAX_ENTRIES) files.delete(files.keys().next().value)
+      return routeReady ? `${ROUTE_PATH}/${chartId}.json` : null
+    },
+
+    setRouteReady(value) {
+      routeReady = value === true
+    },
+
+    filePathOf(chartId) {
+      return files.get(chartId)
+    },
+
+    read(filePath) {
+      return readFile(filePath)
+    },
+
+    get size() {
+      return files.size
+    },
+  }
+}
+
+function send(res, status, payload) {
+  const body = JSON.stringify(payload)
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(body)
+}
+
+function pathnameOf(req, res) {
+  try {
+    return new URL(req.url ?? '/', 'http://localhost').pathname
+  } catch {
+    send(res, 400, { error: 'bad_request' })
+    return undefined
+  }
+}
+
+/**
+ * Build the series route handler.
+ *
+ * @param store - the opaque chart registry.
+ * @param options.authorize - optional `(req) => 401 | 403 | undefined`. When it
+ *   returns a status the handler answers with that status and never touches the
+ *   registry, so an unauthenticated caller learns nothing about `chart_id`.
+ *   `apply()` passes `connection.requestRejection` here: that is the same
+ *   trusted-Host fence + signed browser cookie every other session-scoped Web
+ *   route runs behind (`/api`, the static index), and a route that skips it is
+ *   readable by any local process or page that learns a `chart_id`
+ *   (2026-09-17 review). A composition with no `connection` service (no browser
+ *   auth plane at all) passes nothing and keeps the old behaviour.
+ */
+export function createRouteHandler(store, options = {}) {
+  const authorize = options.authorize
+  return async function handler(req, res) {
+    if (typeof authorize === 'function') {
+      let rejection
+      try {
+        rejection = authorize(req)
+      } catch {
+        // An authorizer that cannot answer must not fall through to the data:
+        // fail closed on the same status the platform uses for a missing cookie.
+        rejection = 401
+      }
+      if (rejection !== undefined && rejection !== null) {
+        res.statusCode = rejection
+        res.setHeader('content-type', 'text/plain; charset=utf-8')
+        res.setHeader('cache-control', 'no-store')
+        res.end(rejection === 401 ? 'unauthorized' : 'forbidden')
+        return
+      }
+    }
+    if (req?.method !== 'GET') {
+      send(res, 405, { error: 'method_not_allowed' })
+      return
+    }
+    const pathname = pathnameOf(req, res)
+    if (pathname === undefined) return
+    if (pathname !== ROUTE_PATH && !pathname.startsWith(`${ROUTE_PATH}/`)) {
+      send(res, 404, { error: 'not_found' })
+      return
+    }
+    const match = /^\/([^/]+)\.json$/.exec(pathname.slice(ROUTE_PATH.length))
+    if (!match) {
+      send(res, 404, { error: 'not_found' })
+      return
+    }
+    let chartId
+    try {
+      chartId = decodeURIComponent(match[1])
+    } catch {
+      send(res, 400, { error: 'bad_request' })
+      return
+    }
+    if (!CHART_ID_PATTERN.test(chartId)) {
+      send(res, 400, { error: 'invalid_chart_id' })
+      return
+    }
+    const filePath = store.filePathOf(chartId)
+    if (filePath === undefined) {
+      send(res, 404, { error: 'chart_not_published', chart_id: chartId })
+      return
+    }
+    let body
+    try {
+      body = await store.read(filePath)
+    } catch {
+      send(res, 404, { error: 'chart_file_unreadable', chart_id: chartId })
+      return
+    }
+    res.statusCode = 200
+    res.setHeader('content-type', 'application/json; charset=utf-8')
+    res.setHeader('cache-control', 'no-store')
+    res.end(body)
+  }
+}
+
+export function apply(ctx) {
+  const store = createChartStore({ routeReady: false })
+  ctx.provide('capitalCharts', {
+    publish: (input) => store.publish(input),
+  })
+
+  /**
+   * 认证围栏：优先解析 host 平面的 `connection`（web profile 由
+   * `@deepseek-ai/dsh-client-connection` 提供），把它的 `requestRejection`
+   * 原样接到本路由上——trusted-Host（403）+ 签名 cookie（401）。
+   *
+   * 惰性解析而不是 apply 时解析一次：`connection` 与本行的挂载先后不由我们决定。
+   * 服务整体缺席（Electron/file:// 这类没有浏览器认证面的载体）时返回 undefined，
+   * 退化成"没有认证面"的旧行为；但**解析抛错**（上下文已销毁）一律 401，宁可拒绝。
+   */
+  const authorize = (req) => {
+    let connection
+    try {
+      connection = ctx.get('connection')
+    } catch {
+      return 401
+    }
+    if (connection === undefined || connection === null) return undefined
+    if (typeof connection.requestRejection !== 'function') return undefined
+    return connection.requestRejection(req)
+  }
+
+  const registerRoute = (webCtx) => {
+    webCtx.effect(
+      () => {
+        const chartDispose = webCtx.webServer.register({ kind: 'prefix', path: ROUTE_PATH, handler: createRouteHandler(store, { authorize }) })
+        store.setRouteReady(true)
+        return () => {
+          store.setRouteReady(false)
+          if (typeof chartDispose === 'function') chartDispose()
+        }
+      },
+      'capital-charts: series route',
+    )
+  }
+  // 只走 inject，不许"先 get 探测、再直接拿属性"。`ctx.get('webServer')` 能解析出值
+  // **不代表** `ctx.webServer` 这个属性访问合法：cordis 的属性代理只认"本层声明过 inject"
+  // （ReflectService 找不到就抛 cannot get property "webServer" without inject）。探测式写法
+  // 把正确性押在装配顺序上——桌面端 webServer 在本行之前已就绪，于是走了"直接调用"那条并
+  // 当场炸（2026-09-30 实机：capital-charts 与 capital-watchlist 两行 异常）；web profile 里
+  // 它还没就绪，反而躲过。inject 两种顺序都对：已就绪立刻起，没出现就一直等（本行仍激活）。
+  ctx.inject(['webServer'], registerRoute)
+}

package/chart-ui/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@v587d/capital-charts",
+  "version": "2.6.0",
+  "description": "Capital 模式的图表前端组件（浏览器半边 + 序列旁路路由）：由 @v587d/capital-generation 随包携带并作为 host 平面行挂载。",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    },
+    "./client": {
+      "default": "./client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "README.md"
+  ]
+}

package/cordis.patch.yml

@@ -0,0 +1,72 @@
+# 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` 读不回。
+
+# ── 图表前端组件（host 平面行）────────────────────────────────────────────────
+#
+# 为什么这一行必须在这里、必须是 host 平面：客户端 bundle 的注入发生在
+# index.html 渲染那一刻，运行期新增 entry 没有送达浏览器的通道；挂在 preset 行上的
+# 客户端 bundle 到不了已经打开的页面。见 chart-ui/README.md。
+#
+# 为什么行名是**相对本包目录的路径**（三个坑都踩过，都不是猜的）：
+#  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，并真的解析一次）。
+- insert:
+    - id: capital-config
+      name: './capital-config/index.js'
+      config:
+        customPersona: ''
+        fuyaoCredentialRef: FUYAO_API_KEY
+        retriever:
+          baseURL: ''
+          credentialRef: ANYSEARCH_API_KEY
+          windDocs:
+            endpoint: 'https://mcp.wind.com.cn/vserver_financial_docs/mcp/'
+            credentialRef: WIND_API_KEY
+            timeoutMs: 60000
+
+- insert:
+    - 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` 与 `./capital-watchlist/index.js` 的 path-like 字面量规则同上（!!js / subpath 两个坑
+# 对这颗行同样成立）。
+- insert:
+    - id: capital-watchlist
+      name: './capital-watchlist/index.js'
+

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

@@ -0,0 +1,55 @@
+/**
+ * data_junior 的 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）。
+ *
+ * 两层规则：
+ *  A 结构层：shell 只对**被委派**的子会话开放（镜像 src/tool-exec.ts 的 delegatedSession）——
+ *    即使哪天 ROOT_AGENT_DENIED_TOOLS 或 allow 过滤被改坏，执行层仍然拒绝根会话。
+ *    docs/dev/bash-gate.md「工具可见性不是权限隔离」。
+ *  B UX 层：委派子会话的审批策略由框架固定为 `never`（dsh-subagent 的
+ *    `captureDelegatedPolicyOverrides` → `approval/policy: never`，`dsh-user-approval.decide()`
+ *    在 never 时**直接返回 rejected、根本不调用 answerer**），所以 `sandbox_permissions`
+ *    必然失败，而且模型会收到「the user rejected…」这种**把系统拒绝说成用户拒绝**的文案。
+ *    这里提前拦下并给出正确路径：省一次必然白跑的往返 + 纠正归因。
+ *
+ * 为什么用 `tools.guard` 而不是 `tools/pre-execute`：guard 是**单调**的（没有 allow 结果，
+ * 任何监听顺序都无法把别人的 deny 翻回 allow），同步、拿到解析后的 `arguments`，且
+ * 「注册在 agent.ctx 上就只作用于该 agent」。pre-execute 是 waterfall，可扩展也意味着可被后续
+ * 监听改写。
+ */
+import { type GuardedExecution, type PolicyContext } from './root-tool-policy.js';
+/** 闸门看到的调用形状：guard 拿到的是解析后的 arguments，不是一个 shell 字符串。 */
+export type BashGuardExecution = GuardedExecution;
+/** A 结构层拒绝文案：模型可据此改走委派。 */
+export declare const SHELL_DELEGATED_ONLY: string;
+/** B UX 层拒绝文案：说清"这不是用户拒绝"，并给出正确路径。 */
+export declare const SHELL_ESCALATION_UNREACHABLE: string;
+/**
+ * 单次 shell 调用的判定：返回拒绝理由，或 undefined 放行。
+ *
+ * 判定顺序是"先身份、后能力"：身份不对时不该让模型以为问题出在参数上。
+ * 注意这里**只读两个字段**（调用方身份、`sandbox_permissions`/`justification`），
+ * 绝不解析 `command`——理由见文件头。
+ */
+export declare function bashGuardReason(exec: BashGuardExecution | undefined): string | undefined;
+/**
+ * 注册 bash 闸门：对**本 preset 的每个 agent** 在它自己的 scope 上装一次 guard。
+ *
+ * 监听位置与 `registerRootToolPolicy` 同因：`agent/created` 的路由键是 agent 对象本身，
+ * 注册在 standing scope（打了标签）的监听器**收不到且不报错**，必须挂 `ctx.root`。
+ * 安装/释放都不得抛回 agent 创建路径——宁可少一层闸门，也不能挡住建 agent；
+ * 静默失败会留下诊断 warn（见 `registerBashGuard` 的返回值处理）。
+ */
+export declare function registerBashGuard(ctx: PolicyContext): void;

package/lib/agents/bash-guard.js

@@ -0,0 +1,162 @@
+/**
+ * data_junior 的 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）。
+ *
+ * 两层规则：
+ *  A 结构层：shell 只对**被委派**的子会话开放（镜像 src/tool-exec.ts 的 delegatedSession）——
+ *    即使哪天 ROOT_AGENT_DENIED_TOOLS 或 allow 过滤被改坏，执行层仍然拒绝根会话。
+ *    docs/dev/bash-gate.md「工具可见性不是权限隔离」。
+ *  B UX 层：委派子会话的审批策略由框架固定为 `never`（dsh-subagent 的
+ *    `captureDelegatedPolicyOverrides` → `approval/policy: never`，`dsh-user-approval.decide()`
+ *    在 never 时**直接返回 rejected、根本不调用 answerer**），所以 `sandbox_permissions`
+ *    必然失败，而且模型会收到「the user rejected…」这种**把系统拒绝说成用户拒绝**的文案。
+ *    这里提前拦下并给出正确路径：省一次必然白跑的往返 + 纠正归因。
+ *
+ * 为什么用 `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 上是死代码"）。
+ */
+const shellToolNames = new Set(SHELL_TOOL_NAMES);
+/** A 结构层拒绝文案：模型可据此改走委派。 */
+export const SHELL_DELEGATED_ONLY = 'shell 工具（bash / pwsh）只对被委派的数据子 Agent 开放，当前调用方不是被委派的子会话；'
+    + '数据与统计请由主 Agent 委派 data_collector / data_junior。';
+/** B UX 层拒绝文案：说清"这不是用户拒绝"，并给出正确路径。 */
+export const SHELL_ESCALATION_UNREACHABLE = 'shell 工具（bash / pwsh）的沙箱升级在子 Agent 会话里永远无法获批（框架把委派会话的审批策略固定为 never，不会去问用户），不要重试：'
+    + '缺数值用 describe_dataset / query_dataset，缺数据用 send_message 发 data_gap 回主 Agent。';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 单次 shell 调用的判定：返回拒绝理由，或 undefined 放行。
+ *
+ * 判定顺序是"先身份、后能力"：身份不对时不该让模型以为问题出在参数上。
+ * 注意这里**只读两个字段**（调用方身份、`sandbox_permissions`/`justification`），
+ * 绝不解析 `command`——理由见文件头。
+ */
+export function bashGuardReason(exec) {
+    if (exec === undefined || typeof exec.name !== 'string' || !shellToolNames.has(exec.name))
+        return undefined;
+    const parent = exec.agent?.session?.header?.parentSession;
+    if (typeof parent !== 'string' || parent.length === 0)
+        return SHELL_DELEGATED_ONLY;
+    const args = isRecord(exec.arguments) ? exec.arguments : undefined;
+    if (args !== undefined && (args.sandbox_permissions !== undefined || args.justification !== undefined)) {
+        return SHELL_ESCALATION_UNREACHABLE;
+    }
+    return undefined;
+}
+/** 在某个 agent 自己的 scope 上安装 guard，返回 disposer（不可用时返回 undefined）。 */
+function installAgentGuard(agent) {
+    let tools;
+    try {
+        tools = agent?.ctx?.tools;
+    }
+    catch {
+        return undefined;
+    }
+    if (tools === undefined || typeof tools.guard !== 'function')
+        return undefined;
+    try {
+        const dispose = tools.guard(bashGuardReason);
+        return typeof dispose === 'function' ? dispose : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 注册 bash 闸门：对**本 preset 的每个 agent** 在它自己的 scope 上装一次 guard。
+ *
+ * 监听位置与 `registerRootToolPolicy` 同因：`agent/created` 的路由键是 agent 对象本身，
+ * 注册在 standing scope（打了标签）的监听器**收不到且不报错**，必须挂 `ctx.root`。
+ * 安装/释放都不得抛回 agent 创建路径——宁可少一层闸门，也不能挡住建 agent；
+ * 静默失败会留下诊断 warn（见 `registerBashGuard` 的返回值处理）。
+ */
+export function registerBashGuard(ctx) {
+    const listenCtx = ctx.root ?? ctx;
+    if (typeof listenCtx.on !== 'function')
+        return;
+    /** agent 会话 id → guard 的 disposer；agent/disposed 时释放，避免跨实例残留。 */
+    const guards = new Map();
+    const install = () => {
+        const stopCreated = listenCtx.on?.('agent/created', (payload) => {
+            try {
+                const agent = payload?.agent;
+                if (!isCapitalAgent(ctx, agent))
+                    return;
+                const dispose = installAgentGuard(agent);
+                if (dispose === undefined) {
+                    ctx.logger?.warn('capital-generation: bash 闸门未生效（agent scope 上没有 tools.guard）：data_junior 的 bash 只剩 persona 软约束');
+                    return;
+                }
+                const id = agentSessionId(agent);
+                if (id !== undefined)
+                    guards.set(id, dispose);
+            }
+            catch (error) {
+                ctx.logger?.warn(`capital-generation: bash 闸门安装异常：${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+        const stopDisposed = listenCtx.on?.('agent/disposed', (payload) => {
+            try {
+                const id = agentSessionId(payload?.agent);
+                if (id === undefined)
+                    return;
+                const dispose = guards.get(id);
+                if (dispose === undefined)
+                    return;
+                guards.delete(id);
+                dispose();
+            }
+            catch { /* 释放失败不该影响 agent 拆除路径 */ }
+        });
+        return () => {
+            try {
+                if (typeof stopCreated === 'function')
+                    stopCreated();
+            }
+            catch { /* ignore */ }
+            try {
+                if (typeof stopDisposed === 'function')
+                    stopDisposed();
+            }
+            catch { /* ignore */ }
+            for (const dispose of guards.values()) {
+                try {
+                    dispose();
+                }
+                catch { /* ignore */ }
+            }
+            guards.clear();
+        };
+    };
+    if (typeof ctx.effect === 'function') {
+        ctx.effect(() => {
+            const dispose = install();
+            return () => dispose();
+        }, 'capital-generation.bash-guard()');
+        return;
+    }
+    install();
+}