dsh-ptc-plus 0.4.10 → 0.5.0

package/docs/architecture.md

@@ -16,33 +16,28 @@ PTC Plus 把 DSH PTC 模式的顶层 `run_code` 变成与 session 绑定的连
 求值层由插件自有的 helper 进程承载：Host 只持有 `IsolatedWorker` transport，真实 `node:worker_threads` session worker 与其私有 `MessagePort` 都留在 helper 内，IPC 只传输 plain data。宿主回收卡住的计算时只强杀自己的 helper process，DSH 进程内没有需要终止的 session worker，因此不会触达已测得会落入 Node 24/26 cppgc teardown fault 的 in-host worker 强杀路径；`IsolatedOwner` 只在该实例的 real exit、output close 和 cleanup 都完成后释放。kernel、console、candidate 三个入口各自拥有 owner。helper 的 `init` 携带 fork 前 snapshot 的投影环境，user Worker 及其子进程保持原 env 契约，不会继承 `NODE_V8_COVERAGE` 等宿主 instrumentation；Electron Host 只在 helper fork 环境覆盖 `ELECTRON_RUN_AS_NODE=1`，该启动变量不进入 user Worker。inner Worker 的 compute budget 在每次请求提交时通过 helper 的 on-demand sample 取新鲜 `eventLoopUtilization` baseline，ready handshake 另有启动样本；采样失败按 worker-exit 有界失败且不派发 prepare/run。唯一例外由 [ADR 0024](adr/0024-repl-console-observation.md) 所有：同一 worker 已确认存在未完成的 observation 时，prepare 可先于预算启动，确认 observation 完成后才开始计时。
 
 主入口接管模型直接发起的顶层 `run_code`，并通过 DSH tool registry 真实注册 `edit_run_code`。
-使用 code-only direct-tool projection 的 PTC request 始终按固定顺序暴露 `[run_code, edit_run_code]`；插件用 agent scope 的
-`tools.register()` 真实注册 edit transport，并用同一 scope 的 `tools.presentAs('both')` 放行这两个 provider tool call，再把其他 native tool 保留在 program SDK。首次可判定的 prompt assembly 在安装这项 presentation effect 前建立 agent composition owner；注册与 mode 记录都在所属 session、agent 或插件释放时撤销，native-mode 与无关 agent scope 不继承 `edit_run_code`。
-DSH 为一个 agent composition 固定选择 `native`、`ptc` 或 `both`。首次 assembly 的非空 `tools:ptc-only` section text 证明 `ptc`，同名空 section 证明 `both`；`tools:code-only` 仅在 `tools:ptc-only` 缺失时作为兼容别名，两者同时存在时以 `tools:ptc-only` 为准。只有缺少 owner signal 时才能从 tool shape 推断。后续 assembly 不重新解释插件自己的 `tools.presentAs('both')` 效果，而是从 agent composition owner 派生 presentation。`ptc` 独占 direct-tool collapse、顶层 native-call normalization 和 native dispatch rejection；`both` 保留 native direct tools。`ptc` 与 `both` 都适配 PTC `run_code` schema、program SDK 和 session runtime contexts，只有 `ptc` 安装并直接执行 `edit_run_code`。model stream 将完整 call 的 session 与 call ID 绑定到由 composition mode 派生的 request policy，dispatch wrapper 替换 cancellation signal 不改变执行判定；result settlement 和 session、agent 或插件释放分别撤销单次 call 与整个 lifecycle。
-若模型误发 live schema 可证明的顶层 native call，stream canonicalizer 会把这个 out-of-surface 调用规范为与模型本应生成的同一 member `run_code`；未知、畸形或不一致输入原样透传。派生 cell 不携带 provenance、纠错提示或其他模型可见标记；普通参数保留原始 JSON，含 own `__proto__` 的参数使用安全字面量，超过 TypeScript parser 安全深度的参数才使用浅层 `JSON.parse` 表达式。该规范化只修复无效 direct call。已声明的 `run_code` 与 `edit_run_code` 原样通过，因此 session history、UI 与下一轮 model context 保留合法调用的实际 tool name 和参数。
-
-`edit_run_code` 对其持久化 `tool/call` 事件出现时当前 open turn 最近的可编辑 cell 生效，无论该 cell 被拒绝、运行失败，还是成功执行但结果需要微调。执行通过 call event sequence 读取该快照，后续 settlement 或 handler 调度不改变目标；派生 cell 则按外层 `tool/result` event sequence 进入恢复历史，使 cold replay 保持 live kernel 的实际结算顺序。
-调查 tool 不擦除目标；edit 发起后的其他 settlement 不追溯改变其目标；一次成功 edit 生成的新 cell 成为下一次 edit 的目标。调用方必须且只能提交 `edits` 或
-`regex_edits` 之一，并可携带 `expected_target_call_seq` 作为目标前置条件；它与 call event 已捕获目标不一致时，在任何派生 dispatch 前返回未编辑结果。`internal/rejected-cell-editor.js` 统一拥有 schema、匹配、replacement 语义、预算和原子源码组装；
-所有位置都针对原始目标源码解析，全部范围不得重叠，预算通过后才以单次线性扫描物化结果。
-
-注册工具通过 DSH 公共 `tools.execute()` 将完整修改后源码派生执行为 `run_code`。外层历史仍是模型真实发出的
-`edit_run_code(delta)`；模型可见 result 只包含 `{ edited, value, error, logs }` 或拒绝原因。完整派生源码、journal 和目标 call sequence 只写入
-外层 tool result 的私有 metadata，供审计和 cold replay 使用，不进入下一轮模型上下文，也不伪装成 assistant-authored
-`run_code`。无目标或参数不合法时不执行，返回 `{ edited: false, reason }` 并保留原目标。
-进程内 claim 区分 executing 与 settled：抛错、取消或缺少有效 PTC journal 的派生结果立即释放；已由 journal 证明进入 runtime 的派生执行继续占用旧 target，直到外层 result 的私有 metadata 通过最终 policy 并由 session log 投影为新 target。最终 result 丢失 metadata 时由 `tools/result` 释放。session log 投影在 edit call event 处记录 eligible target，只接受 target call sequence 匹配该快照且 journal 有效、非 noop 的派生源码，因此 live 与 cold recovery 从同一持久关系决定可编辑目标。
-
-`internal/session-log-view.js` 通过公开 `sessionProjections` 注册 host-only 的 `ptcPlusSessionLog` 单元。同步单事件转移维护最新执行、可编辑目标、rewrite metadata、规范 journal 的 Cordis transcript 计数、已投递提示身份与 cooldown/escalation 事实，以及按公开 surface operation 排序的当前 runtime messages。pre-step 与 assembly 只读该单元，不重新读取或折叠历史；异步恢复通过 `sessionQuery.observeSession` 取得不可变观察切点，派生 edit 与其内层执行共享该切点。旧的 array-backed session 使用同一转移的批量折叠，不修改 Host 状态。详见 [ADR 0032](adr/0032-own-session-log-facts-in-a-host-only-projection.md)。
+使用 code-only direct-tool projection 的 PTC request 只暴露 `[run_code]`；插件用 agent scope 的
+`tools.register()` 真实注册 edit transport，使 `tools.edit_run_code` 在首轮 program SDK 中可用。注册与 composition mode 记录都在所属 session、agent 或插件释放时撤销，native-mode 与无关 agent scope 不继承 `edit_run_code`。
+DSH 的公开 presentation 为 `native` 或 `ptc`。agent composition owner、正式 `tools:ptc-only` section（兼容旧名 `tools:code-only`）与 live tool shape 决定是否接管 PTC；插件不选择额外 presentation mode。PTC 请求的 direct schema 只有 `run_code`，其他工具通过 program SDK 调用。model stream 将 session 与 call ID 绑定到请求策略；result settlement 和 session、agent 或插件释放分别撤销单次 call 与所属生命周期。
+若模型误发 live schema 可证明的顶层 native call，stream canonicalizer 可将其规范为调用同一 member 的 `run_code`；未知、畸形或不一致输入原样透传。普通 JSON 参数保持原值，含 own `__proto__` 的参数使用安全字面量，超过 TypeScript parser 安全深度的参数使用浅层 `JSON.parse` 表达式。顶层 `run_code` 原样通过；`edit_run_code` 只允许正式 nested SDK 调用，不通过顶层 native-call 修复取得执行资格。
+
+`edit_run_code` 在持久化 `tool/ptc-dispatch-start` 处捕获当前 open turn 最近的可编辑 cell，按 root、parent、sub-call identity、参数与 sequence 校验正式事件。调查工具不擦除目标，后来的 settlement 不追溯改变它。调用必须且只能提交 `edits` 或 `regex_edits` 之一，并可携带 `expected_target_call_seq`；目标前置条件不一致时不派生执行。`internal/rejected-cell-editor.js` 统一拥有 schema、匹配、JavaScript replacement 语义、预算和原子源码物化。
+
+接受收据为 `{ accepted: true, scheduled: true, target_call_seq }`，拒绝为 `{ accepted: false, scheduled: false, reason }`。接受只表示待执行：外层 cell 的后续语句仍使用当前状态，保留其 canonical return 或 error。外层 worker 结束后、根结果结算前，runtime bridge 通过 DSH 公共 `tools.execute()` 执行完整修订源码，并通过调用开始前已安装的公开 `projectContent` 将派生 content、images 送入根 post-policy；`exec.deferContext` 与 `exec.concludeTurn` 转发 additionalContexts 和成功根结果的 concludesTurn。成功根结果保留 Host canonical 对象，避免重新投影丢失 journal；根 policy 仍可替换或阻断这些展示内容。 runtime bridge 保留原有 callback 与 property descriptor；安装失败时撤回已安装部分，卸载时只恢复自己仍拥有的 callback。普通外层计算失败不撤销已接受编辑；取消、lease 结束或 disposal 阻止未开始的派生执行。同一根 cell 至多接受一次编辑，派生执行不能重新取得根编辑资格。
+
+assistant history 保留原始根 `run_code`，正式 nested events 保留 editor 的名称、delta 参数与收据。插件通过公开 `Session.append` 记录真实派生 `run_code` 的 start/settle，实际执行的 parent token 与事件 parent 都来自仍在运行的根 transport；公开 scoped `tools/ptc-dispatch-log` 使用真实根 execution 留存内容。根结果私有 `dshPtcPlusPostEdit` 记录完整派生源码、journal、目标、editor 的 `startSeq` 与实际执行的 `executionStartSeq`；不虚构 assistant call、父调用或结算。最终 metadata 丢失不能撤销已发生效果，只使未证明状态丧失恢复资格。恢复 owner 校验根 journal 的收据、editor 和派生执行的正式 dispatch pairs、canonical 结算事实、目标变换与根/目标双重模型可见来源，按实际 root 后 derived 顺序恢复状态；cold replay 返回 recorded binding 值，不重新派发 editor 或外部效果。成功修订成为下一编辑目标。历史顶层 editor metadata 继续由其原有 generation 校验。详见 [ADR 0005](adr/0005-temporary-rejected-cell-edit-transport.md)。
+
+`internal/session-log-view.js` 通过公开 `sessionProjections` 注册 host-only 的 `ptcPlusSessionLog` 单元。同步单事件转移维护最新执行、可编辑目标、rewrite metadata、规范 journal 的 Cordis transcript 计数、已投递提示身份与 cooldown/escalation 事实，以及按公开 surface operation 排序的当前 runtime messages。pre-step 与 assembly 只读该单元，不重新读取或折叠历史；异步恢复通过 `sessionQuery.observeSession` 取得不可变观察切点：editor 在自身 start 切点捕获目标，真实派生执行另取切点并获得新 admission；各入口只消费自身选定的不可变切点。旧的 array-backed session 使用同一转移的批量折叠，不修改 Host 状态。详见 [ADR 0032](adr/0032-own-session-log-facts-in-a-host-only-projection.md)。
 `edit_run_code` 不产生专用 runtime context：真实 call/result 已完整表达操作身份和结果，额外 contribution
 会重复已有事实；此类信息不进入独立 PTC 消息。只有缺少有效 journal、无法确认完成状态的 rewrite feedback 才保留独立生命周期；已结算失败的恢复指引由当前结果表达；成功的透明改写不产生 runtime context。
 
 执行接入由 `internal/execution-provider-owner.js` 经公开 Loader/Cordis 组合：保留原 row 的模块与配置，将原服务置于 named isolation，另注册插件自有 global provider。`internal/execution-seam-compat.js` 选择该服务并拥有 request/spec 边界；主插件卸载只释放自有 provider 的私有 execution callback，恢复原生委托与能力 getter，不写原实例的 `run` 或描述符。移除完整 bundle 时，Loader 生命周期先同步撤销插件注册，再让原 provider 回到 global slot。`presentationMeta` 仍由 runtime bridge 单独还原；它不属于 provider composition（见 [ADR 0028](adr/0028-attach-to-the-host-ptc-execution-seam.md)）。旧 provider generation 不能复活已释放的 session 状态。
 稳定 REPL 指引与执行共同从 `binding-update-policy.js` 取得语言代际。新代际说明 TypeScript、顶层 await/return、静态 import/export 与所选绑定更新策略；旧兼容态才按其独立开关说明支持的模块语法。显式结果使用 return，日志使用 console；原生表达式 completion 同样可以提供结果值。失败恢复先按状态分类：result 已证明解析或 preflight 未执行且提供符合任务意图的 validated repair 时，
-优先直接使用带目标保护的 `edit_run_code`，无需等待 recovery context；该验证只证明语法/preflight 接受。其他小型修正可用 edit 执行完整 cell；
+优先在新 `run_code` cell 中使用带目标保护的 `tools.edit_run_code`，无需等待 recovery context；该验证只证明语法/preflight 接受。其他小型修正可用 edit 执行完整 cell；
 已执行或可能产生外部 effect 的目标，则必须依据操作 owner 的 retry/idempotence 契约和执行事实判断重跑。短 `run_code` 可以复用仍存活的 binding，但缩短源码不能证明幂等。能力和命令执行依赖当前 request
 与 execution world，模型必须先探查 live binding、实际 executable 和路径语义，不假设某个平台、shell 或 package runner。
 
-live `PTC-C001` 若精确落在源码 EOF，独立的 bounded analyzer 只把追加由 `}`、`)`、`]` 组成、长度为一或二的 12 项候选源码分别送入该 cell 提交时的同一 preparation context。仅当唯一候选通过、无 binding collision，现有 exact editor 能从不超过固定预算的唯一尾部物化同一源码，并且 runtime 已取得该 rejected `run_code` 的持久 call sequence 时，诊断才输出一行可直接调用的 `edit_run_code({ edits: [...], expected_target_call_seq })`。edit transport 把该 sequence 与其 call event 捕获的目标比较，目标已变化时不编辑也不派生执行。这项 validated repair 优先于长度阈值，但只证明语法/preflight 接受；插件不自动 dispatch，也不改写原始 `run_code`。非 EOF、多候选、需要三个及以上闭合符、超预算、缺少目标身份或后续 preparation 拒绝均使用 length-adaptive help。
+live `PTC-C001` 若精确落在源码 EOF，独立的 bounded analyzer 只把追加由 `}`、`)`、`]` 组成、长度为一或二的 12 项候选源码分别送入该 cell 提交时的同一 preparation context。仅当唯一候选通过、无 binding collision，现有 exact editor 能从不超过固定预算的唯一尾部物化同一源码，并且 runtime 已取得该 rejected `run_code` 的持久 call sequence 时，诊断才输出一行供新 `run_code` cell 使用的 `await tools.edit_run_code({ edits: [...], expected_target_call_seq })`。edit transport 把该 sequence 与正式 nested start 捕获的目标比较，目标已变化时不编辑也不派生执行。这项 validated repair 优先于长度阈值，但只证明语法/preflight 接受；插件不自动 dispatch，也不改写原始 `run_code`。非 EOF、多候选、需要三个及以上闭合符、超预算、缺少目标身份或后续 preparation 拒绝均使用 length-adaptive help。
 
 稳定指引保留这些跨任务不变量和失败恢复的优先动作。长 cell 失败的短提示直接作为当前 `PTC-X001` 的结构化 `help` 输出；重复绑定失败和当前 execution world 中由诊断确认的 executable、shell 或 path 错误仍由当前 session log 派生为以 `tools:ptc-plus-tip/<trigger>/<ordinal>` 标识的独立 notice，词法失败指向可见源码与初始化，worker-owned capability 失败才指向能力探查，平台错误则提示重新确认环境。投影合并规范 PTC notice 与历史 DSH system-prompt snapshot sections，同一已投递 identity 跨两种来源只计一次，正文不参与身份判断。
 相同提示受 `tipCooldownMessages` 间隔约束，连续未解决时才升级为详细版本，成功 cell 会重置未解决计数；提示不会改变
@@ -108,17 +103,19 @@ Client 遇到冲突后重读 catalog、draft 和 review；只有权威空 draft
 
 PTC 动态状态通过 DSH 公共 `agent/pre-step` 追加为 `source.kind: plugin:ptc-plus` 的独立 `user/message`。未知完成状态的 rewrite feedback 与 Cordis recovery 构成有界 `snapshot`；全局绑定 API 说明使用独立 `catalog`；恢复 tip 是以 trigger/ordinal 为 identity 的 `notice`。恢复快照只替代 PTC 旧状态，空快照撤销旧状态，不替代绑定目录、authoring task、Skill、tool result 或其他 producer。PTC 更新不重发其他 owner 文本，其他 owner 的 aggregate 更新也不重发未变 PTC 信息。`systemPrompt.context` 中的空 witness 受 `includeRuntimeContext` 与 scoped suppression 管理且不渲染 aggregate 文本；assembly 捕获精确请求事实，pre-step 委托宿主 waterfall 后只对匹配且未取消的 accepted step 提议消息。已提交记录与公共 ordered surface 共同决定去重和状态重申；缺少公共 surface 时不推断可见状态，不投递。raw history 只可用于 tip identity/cooldown，不能让隐藏 binding 变成模型知识。关闭 PTC 后仅保留撤销旧声明所需的被动 presentation cleanup，不安装 runtime 或读取 binding 存储。Cordis 恢复使用规范 journal 与当前 agent/enable generation；绑定目录只描述当前启用配置，不要求激活证明。目录和恢复快照分别去重与撤销，Host aggregate 的撤销不适用于目录；暂停只限制新投递。历史快照中的绑定段由一次恢复快照退役。此类状态不得进入 `PromptAssembly.sections`，也不得通过 tool/schema/order 变化传递。来源、边界与历史兼容由 [ADR 0010](adr/0010-session-log-derived-recovery-tips.md) 拥有。
 
-所有模型可见输入都必须能从 session log 重建。静态 system/schema 由 `request/header` 保存，动态 context 由带来源的 `user/message` 保存；进程内临时状态不能直接成为未记录的模型输入。在同一插件版本与配置下，普通执行结果、可编辑目标、诊断和其他插件拥有的运行期变化都不得改变 header；`edit_run_code` 的身份与结果由真实 call/result 表达，不生成 edit feedback context。插件升级、显式配置变化、provider/model route 变化、真实 native capability schema 变化，以及 DSH 拥有的 history replacement 可以使缓存从首个变化 token 起失效。
+所有模型可见输入都必须能从 session log 重建。当前静态 system 由正式 `system/message` 与公共 ordered surface 保存，配置和完整有序 schema 由 `request/header` 保存，动态 context 由带来源的 `user/message` 保存；历史 `header.system` 只按其记录的旧 Session 格式解释。进程内临时状态不能直接成为未记录的模型输入。在同一插件版本与配置下，普通执行结果、可编辑目标、诊断和其他插件拥有的运行期变化都不得改变静态 system 或 header；`edit_run_code` 的身份与结果由真实 call/result 表达，不生成 edit feedback context。插件升级、显式配置变化、provider/model route 变化、真实 native capability schema 变化，以及 DSH 拥有的 history replacement 可以使缓存从首个变化 token 起失效。
 
 全局绑定条目属于可变的用户计算输入；修改其提示词、接口、源码或启用集合通过上述追加通道同步，不能套用静态插件配置变化的例外来重写 header。配置说明可从已提交 PTC catalog 重建，且不为保留隐藏的 session-local 状态提供额外证明。
 
+能力方案在首个请求前组装完成；会话尚无已提交任务历史时，经 `agent/pre-step` 将初始方案放在接受批次的任务文本之前，受保护 system head 仍由 Host 先提交。正文依次为有界的固定类别用途导航、显式完整契约、已选基线、其余统计选择的契约，各组按身份排序并去重共享依赖。自动选择改变不改导航；样本数和 digest 不渲染。相同方案的不同任务可共享整个能力说明前缀，统计改变成员时尽量共享变化组之前的文本。已有会话冻结启用与披露选择；宿主实际契约修订或撤下能力以 capability-contracts 追加说明，不重分配选择。显式刷新和恢复仍追加，不为提高缓存率重排历史。初始能力格式统一为 v1，恢复核验方案及正文。目录不复制单项完整描述，保持预算与缓存前缀两项约束。
+
 缓存稳定性必须有 keyless contract test：跨每个相关生命周期状态序列化并比较完整 system text 与有序 tool schemas，同时断言 edit 不增加 runtime context。真实模型的 `cacheReadTokens` 只作为端到端补充；“不破坏缓存”表示插件保留已有可复用前缀，不承诺 provider 建立、保留或命中缓存。
 
 ## 能力表面
 
-cell 直接使用 DSH 为当前 request 提供的 `tools.*`，不按工具名过滤，不翻译已提供的 program-call 参数或 canonical result。只有完全省略参数且 DSH 的 live object schema 验证 `{}` 合法时，worker 才在 encoding 前把 omission 规范为 `{}`；显式 `undefined`、需要输入的 member 与其他 namespace 不变，调用方携带的内部 metadata 不能扩大这项集合。模型 direct-call 边界与这个 data-plane contract 分离：声明的顶层 transport 是 `run_code` 和 `edit_run_code`；可证明的误发 native call 可先规范为 `run_code`，native member 随后在 cell 内 nested dispatch。所有 native member、`capabilities.*`、`repl.state` 和 `code.*` 共享 cell lease；cell 结束后，捕获的函数统一失效。调用时仍由 DSH 检查 scope、policy、取消和 scheduler。
+cell 直接使用 DSH 为当前 request 提供的 `tools.*`，仅按显式启用的冻结会话方案移除关闭成员，不翻译已提供的 program-call 参数或 canonical result。只有完全省略参数且 DSH 的 live object schema 验证 `{}` 合法时，worker 才在 encoding 前把 omission 规范为 `{}`；显式 `undefined`、需要输入的 member 与其他 namespace 不变，调用方携带的内部 metadata 不能扩大这项集合。模型 direct-call 边界与这个 data-plane contract 分离：声明的顶层 transport 只有 `run_code`，editor 经 `tools.edit_run_code` 调用；可证明的误发 native call 可先规范为 `run_code`，native member 随后在 cell 内 nested dispatch。所有 native member、`capabilities.*`、`repl.state` 和 `code.*` 共享 cell lease；cell 结束后，捕获的函数统一失效。调用时仍由 DSH 检查 scope、policy、取消和 scheduler。
 
-`capabilities.tree/find/inspect` 是描述 API，不是反射调用入口。默认 SDK 展开这个导航器，Global User Bindings 开启时另声明稳定的 `code.submitBindingDraft`；`repl.state` 与 `code.run` 保持可调用，但其完整契约只在 explorer 中按需返回。explorer 合并 live tool schema 与插件自有 program-binding 描述；可证明的 metadata 包括名称、描述、输入/输出 schema、authority 和 replay。effect 与 result completeness 没有 owner 证据时保持 `unknown`。探索不会授予权限或触发额外模型调用。
+`capabilities.tree/find/inspect/search` 是描述 API，不是反射调用入口。search 的 cell-local 派生索引返回完整匹配条目，计量完整 JSON 的 UTF-8 字节，延续游标绑定目录及 query，过长条目给出明确 inspect 指针。默认 SDK 展开这个导航器，Global User Bindings 开启时另声明稳定的 `code.submitBindingDraft`；`repl.state` 与 `code.run` 保持可调用，但其完整契约只在 explorer 中按需返回。explorer 合并 live tool schema 与插件自有 program-binding 描述；可证明的 metadata 包括名称、描述、输入/输出 schema、authority 和 replay。effect 与 result completeness 没有 owner 证据时保持 `unknown`。探索不会授予权限或触发额外模型调用。
 
 当前公共扩展面没有跨 prompt assembly 与 cell dispatch 的冻结 view token。PTC Plus 使用同一 agent scope 分别读取 prompt 和 runtime view，并让实际 request binding 成为执行事实；能力在两阶段之间变化时，不伪造原子快照保证。
 
@@ -148,7 +145,8 @@ cell 的静态 import 与 remote re-export 产生有序 preload，Node 继续拥
 
 ```ts
 {
-  version: 10,
+  version: 11,
+  executionCwd: string | null,
   languageSemantics: "legacy-v1" | "stateful-v1" | "protected-v1",
   moduleTransform: "amaro@1.1.11" | "stateful-module-v1+amaro@1.1.11" |
     "stateful-module-v2+amaro@1.1.11" | "protected-module-v1+amaro@1.1.11",
@@ -175,9 +173,9 @@ cell 的静态 import 与 remote re-export 产生有序 preload，Node 继续拥
 }
 ```
 
-`languageSemantics` 选择语言契约，`moduleTransform` 选择确切 parser、compiler 与 lowering generation；两者必须是允许的配对。v1–v8 固定迁移为 legacy transform，v9 按发布时映射恢复，其中 `stateful-v1` 使用 `stateful-module-v1`，不能按当前 transform 重解释。`bindingPolicy`、`rewritePolicy` 与 `moduleSemantics` 保留历史细分契约；新代际从统一策略派生它们，旧代际由冻结编译器消费。`userBindingsFingerprint` 以 `null` 证明不存在 Global User Binding 输入，或以 SHA-256 绑定并行私有快照；声明存在但快照缺失或不一致时，node 形成 unknown boundary。`userBindingsShadowPolicy` 固化该 cell 的 session-local 覆盖粒度，`userBindingNames` 以按名称排序的 `{name, state}` 记录结算时的 provider/local/absent/unknown 事实，因此 cold replay 按历史粒度重放覆盖关系，不从当前实现推断 v1-v7 cell 的整条 entry 语义；provider 事实必须对应并行快照的条目 ID，并覆盖该快照公开的每个名称，否则 node 形成 unknown boundary。`calls` 只保存 global、member、PTC Value Graph 编码的 args/result 或 error，以及 settlement 序号。cold replay 校验调用名称、参数、数量和提交顺序，并按 recorded settlement order 释放 recorded result；不会重新 dispatch program binding 或重做外部 effect。该规则同样适用于 native tools、owner-provided namespace 和 `code.run`，不按名称分支。Cordis 的进程内对象不会因此被宣称已恢复；presentation 可以从已验证 transcript 派生重新检查要求，但不能改变 replay。若基础设施终止时仍有未结算 binding，heap 回滚到 durable frontier，discarded journal 以最先观察到的 `global.member` 保留 possible-effect boundary。effect、completeness 和 source metadata 属于 capability explorer，不伪装成 journal 字段。
+`executionCwd` 记录本 cell 的已解析当前目录；重放消费记录值，v1–v10 保留 header/worker 基准，不按当前目录重解释历史（[ADR 0041](adr/0041-record-cell-execution-directories.md)）。`languageSemantics` 选择语言契约，`moduleTransform` 选择确切 parser、compiler 与 lowering generation；两者必须是允许的配对。v1–v8 固定迁移为 legacy transform，v9 按发布时映射恢复，其中 `stateful-v1` 使用 `stateful-module-v1`，不能按当前 transform 重解释。`bindingPolicy`、`rewritePolicy` 与 `moduleSemantics` 保留历史细分契约；新代际从统一策略派生它们，旧代际由冻结编译器消费。`userBindingsFingerprint` 以 `null` 证明不存在 Global User Binding 输入，或以 SHA-256 绑定并行私有快照；声明存在但快照缺失或不一致时，node 形成 unknown boundary。`userBindingsShadowPolicy` 固化该 cell 的 session-local 覆盖粒度，`userBindingNames` 以按名称排序的 `{name, state}` 记录结算时的 provider/local/absent/unknown 事实，因此 cold replay 按历史粒度重放覆盖关系，不从当前实现推断 v1-v7 cell 的整条 entry 语义；provider 事实必须对应并行快照的条目 ID，并覆盖该快照公开的每个名称，否则 node 形成 unknown boundary。`calls` 只保存 global、member、PTC Value Graph 编码的 args/result 或 error，以及 settlement 序号。cold replay 校验调用名称、参数、数量和提交顺序，并按 recorded settlement order 释放 recorded result；不会重新 dispatch program binding 或重做外部 effect。该规则同样适用于 native tools、owner-provided namespace 和 `code.run`，不按名称分支。Cordis 的进程内对象不会因此被宣称已恢复；presentation 可以从已验证 transcript 派生重新检查要求，但不能改变 replay。若基础设施终止时仍有未结算 binding，heap 回滚到 durable frontier，discarded journal 以最先观察到的 `global.member` 保留 possible-effect boundary。effect、completeness 和 source metadata 属于 capability explorer，不伪装成 journal 字段。
 
-journal 通过 `run_code.output.presentationMeta` 附着到最终 result，再由 `tools/result` 做两阶段确认。live binding catalog 在 worker 结算时随实际状态更新，下一条排队 cell 使用这份目录准备；journal 确认只推进持久历史，迟到或逆序的确认不能覆盖较新的 live 目录，也不能恢复已重置的状态。缺失、损坏或被替换的 journal 形成 unknown/volatile 边界；未进入 runtime 的 call 由后续 `confirms` 以对应 `tool/call.seq` 证明为 no-op。volatile 源码保留在原 session log，但不参与 cold replay。
+根 journal 通过 `run_code.output.presentationMeta` 附着到最终 result；受控派生执行在公开 Host 未调用 nested projector 时可采用保留 canonical value 身份的私有凭证（[durability design](durability-design.md#两阶段确认)），再由 `tools/result` 做两阶段确认。live binding catalog 在 worker 结算时随实际状态更新，下一条排队 cell 使用这份目录准备；journal 确认只推进持久历史，迟到或逆序的确认不能覆盖较新的 live 目录，也不能恢复已重置的状态。缺失、损坏或被替换的 journal 形成 unknown/volatile 边界；未进入 runtime 的 call 由后续 `confirms` 以对应 `tool/call.seq` 证明为 no-op。volatile 源码保留在原 session log，但不参与 cold replay。
 
 恢复从当前请求对应的 head 沿 parent 关系向更早状态收缩，而不是越过损坏记录继续假定原 heap 存在。候选 frontier 同时受两种证据约束：append-only session log 中的 journal 证明状态可重建；生成当前调用的 DSH ordered surface/derived request history 证明模型可以知道其精确 binding provenance。raw event 未删除不等于模型仍可见，Client 的 `dshPtcPlusBindings` inventory 也只是 UI presentation。只裁剪 tool result、仍把携带源码的 assistant call 留在模型 surface 中时不必删除对应状态；assistant provenance 被遮蔽且没有显式、有界、模型可见的结构化状态投影时，live worker 与 cold replay 都必须收缩。插件不从自然语言 compaction summary 推断 binding。
 

package/docs/capability-planning-components.md

@@ -0,0 +1,93 @@
+# 能力方案与统计组件
+
+本文描述方案、统计及其会话接入。独立组合规则由 [ADR 0043](adr/0043-compose-capability-and-context-policies.md) 拥有，冻结与权限边界由 [ADR 0038](adr/0038-freeze-session-capability-plans.md) 拥有，执行证据见[覆盖矩阵](context-public-interface-coverage.md)。`internal/capability-environment.js` 将纯方案用于首轮目录、冻结环境、编译前成员投影、刷新和恢复；`internal/capability-statistics-store.js` 将真实家族事实接入锁定的原子存储。
+
+## 方案计算
+
+`internal/capability-plan.js` 导出 `createCapabilityPlan(input)`，有 `contextEnabled` 输入时返回递归冻结的 `ptc-capability-plan/v3`，记录整体选择及有效管理状态；缺省该维度时，有 `policy` 输入使用 `v2`，否则使用 `v1`，保留历史精确校验。
+
+| 输入 | 契约 |
+| --- | --- |
+| `contextEnabled` | 整组是否选用；false 通过 `effectiveCapabilitySettings` 暂停管理、采集、恢复和预览，不改写独立保存输入 |
+| `enabled`、`configurationRevision` | 独立管理开关和配置修订；关闭时条目选择为 `host`，不修改宿主 |
+| `capabilities` | owner 提供的准确 `{id, revision, category, contract, dependencies?}`；依赖为 `{id, text}` |
+| `policy` | `ptc-capability-policy/v1`：默认、类别、MCP 来源、单项分别保存 availability 与 disclosure，allocation 分别选择 baseline/statistics/budget；见下文 |
+| `manual` | 可编辑的 `baseline: string[]`；历史输入的 `overrides: { [id]: "full" \| "on-demand" \| "closed" }`；显式项始终优先 |
+| `statistics` | `enabled` 控制采集而非分配；正整数 `windowSize`、`minimumSamples` 和 `[0,1]` 范围的 `fullThreshold` |
+| `coverage` | 按准确能力 ID 索引的 `{revision, workspace, global}`；覆盖证据形状由下述归约组件提供 |
+| `budgetBytes`、`directoryBudgetBytes`、`navigationText` | 完整契约和目录分别按 UTF-8 字节计量；固定发现指引必须在目录预算内 |
+
+`internal/capability-policy.js` 统一校验和解析可复用规则。`defaults` 必须同时包含 `availability: enabled|closed` 和 `disclosure: host|full|on-demand|adaptive`；`categories`、`mcpServers`、`items` 可分别覆盖其中一个维度。默认 → 类别 → 已证明 MCP 来源 → 单项按维度覆盖；MCP 来源关闭是外层移除，优先于子项启用，但不删除子项偏好。每个派生条目保留两项原意、各自来源和兼容的有效 `selection`，关闭时仍保留 disclosure。未解析的非空单项 ID 保留为可撤销输入，只有真实受管库存使规则生效。管理关闭时所有实际能力沿用 host；未选用的关闭规则不参与库存过滤或归属诊断。
+
+`host` 保留已有 PTC 提供方说明路径；纯启停不会让其余能力变成按需。共享说明只在没有沿用宿主的消费者时移除，SDK 仅保留 host 披露的可用工具与始终可调用的编辑传输成员（`edit_run_code` 不属于管理域，每次渲染都保留其宿主签名）；全体仍为 host 时保留原 SDK。Skill 全部沿用时保留宿主目录；混合披露时完整保留 host Skill 的目录说明并隐藏按需说明，不加载正文。按需项始终可获取完整契约。v3 另外区分 Skill 原生准入与有效调用路径：关闭模型 loader 不关闭独立用户入口；无可用入口时派生不可用而保留偏好，管理关闭也不将缺失入口计入实际供给或统计资格；未选用的关闭偏好不参与该事实。MCP 资源契约只列实际可用且未关闭的操作。全部功能未选用或只使用预览时不强制读取能力库存。
+
+只有 adaptive 项消费 `allocation.baseline`、`allocation.statistics` 和 `allocation.budget`；关闭预算约束时允许全部选中的分配候选，仍计量正文与超额。显式 full 不因任一预算选择被降级或截断。统计采集由 `capabilityStatistics.enabled` 单独拥有，不取决于管理或分配是否选用；管理关闭时从公共 live inventory 取得真实资格，记录 host 披露；Host 增删沿真实 live inventory 更新统计资格，不变更冻结配置。停止采集后仍可选用留存有效证据。只读观察既不采集也不需要启用统计分配。
+
+配置格式与纯方案组件接受 `tool`、`skill`、`resource`、`resource-template`、`task` 五类。当前宿主库存仅产出 `tool`、`skill`、`resource`，定义由 `internal/capability-policy.js` 的 `CAPABILITY_INVENTORY_CATEGORIES` 统一供库存与类别控件消费。MCP 资源与模板共用每个服务器的 `resource` 条目；没有独立模板或任务库存，执行任务的 SDK 工具仍归 `tool`。设置仅显示这三类，但保存和历史方案仍保留五类契约；`language`、`node`、`repl`、`ptc-plus`、`global-binding` 保持范围外。适配器必须提供真实来源身份和完整契约；本组件不从工具名字猜测来源，也不加载 Skill 正文。Skill 库存、完整契约、检索与设置来源元数据保留 owner 的 `modelInvocable`/`userInvocable`：模型可调用项说明 `tools.skill({name})`，用户专用项说明 `/name` 用户入口；两者关闭的项不进入可用目录。披露不能扩大加载权限。
+
+adaptive 选择统计依据时，统计不足可回退到已选用的基线；工作区样本足够时优先采用，工作区不足时才参考全局，不将重叠家族相加。无效设置或不可用证据不撤销手动选择。纯描述或 schema 的修订继承尚未由公共适配器证明，因此当前不同 `revision` 隔离。
+
+排序综合覆盖率和契约长度，采用确定性的 ID 裁决。预算计入实际 `catalogText` 的标题、完整契约、分隔和去重后的公共依赖。显式完整条目可超预算，`budgets.overageBytes` 明确报告；自动项不截断契约。存在按需项时，目录保留固定检索指引，在独立预算内提供输入库存中非关闭能力类别的简短用途导航（纯组件支持工具、Skill、MCP 资源/模板及任务；当前宿主接入前三类），不复制单项完整描述或按 ID 抽取长尾条目。存在按需项时，完整或按需分配变化不改变目录结构；未逐项列名的能力仍可通过检索发现。冲突的共享依赖不能合并成一个貌似完整的契约。
+
+完整契约依次排列显式完整、已选基线、其余自动完整三组，组内按 ID 排列；每组先放尚未提供的共享依赖，全目录仅提供一次。统计用于分配，不用于重排已选条目。目录先于完整契约，使统计分配变化尽量保留导航与显式完整契约前缀。统计数字、配置 digest 和会话身份仅在来源元数据中，不进入说明正文。目录只承担用途发现，完整 owner 描述由完整披露或实际检索提供。
+
+输出还包含每项选择及原因、统计范围与样本数、未解析的配置 ID、范围外集合和字节计量。这里的字节不是模型 token；设置页显示方案和预算，任务收益仍须独立校准。没有推荐列表或数字被伪装成实际使用。
+
+## 家族统计归约
+
+`internal/capability-statistics.js` 导出：
+
+```js
+createCapabilityStatistics({ windowSize, maxFamilies, maxScopes, maxCapabilitiesPerFamily })
+reduceCapabilityStatistics(state, familyObservation)
+validateCapabilityStatistics(state)
+capabilityCoverage(state, { userId, workspaceId, id, revision })
+```
+
+输入事实为 `type: "family-observation"`，包含真实 `userId`、`familyId`、单调 `observationRevision`、`settlement`、不可变 `eligibleOrder` 和累计 `observations`。结算状态为 `active`、`settled` 或 `unknown`；只有已结算且具有正整数资格序号的家族可用于分配。适配器必须证明资格，不能把 root idle 或缺少后代用量当成家族结束。
+
+每个可用观察包含 `workspaceId`、能力 `id/revision/category`、当时的 `disclosure` 和 `planRevision`；只允许真实可用的 `host`、`full` 或 `on-demand`，关闭和未提供项不能进入分母。使用证据分别为工具/任务的 `host-execution-result`、Skill 的 `skill-body-accepted`、资源/模板的 `resource-access`。查询、cold replay 和权限阻止的请求不接受为使用证据。工具使用表示真实调用进入 DSH 的 around execution 管线并获得正式规范结果（包括失败和合法 wrapper 提供的结果）；不证明注册 body 或外部效果执行。失败或已准入的取消结果独立保留，明确的 dispatch 前取消、未知工具及未准入调用不算使用。
+
+同一家族、能力、范围只贡献一个使用位。工作区观察和全局观察分别归约，跨工作区后代不增加全局权重。每项能力和范围使用最近 N 个合格家族；续接修改已有身份的使用事实，不改变原资格顺序。正在运行或结算未知的家族不形成负样本。淘汰前沿阻止旧观察重读后重新进入已有窗口；不使用自然时间衰减。
+
+`capabilityCoverage` 返回样本量、使用量、窗口和覆盖率；没有样本时覆盖率为 `null`。窗口已淘汰旧证据后，近期家族恢复为运行中或结算未知，若剩余已结算样本不足 N，状态为 `incomplete-window`，样本量、使用量和覆盖率均为 `null`；不能把无法重建的窗口子集用于自动分配。再次具有 N 个已结算样本时恢复有效。超过显式容量上限后状态为 `capacity-exceeded`，覆盖依据为 `null`。这两种不可用证据均回退手动基线；未淘汰证据的正常冷启动仍可返回实际样本数。结构损坏由验证器拒绝，存储适配器将读取失败转为统计不可用诊断，保留手动配置并继续合法计算。
+
+组件状态是可验证的 JSON 数据。存储适配器使用宿主 home 路径下的 `ptc-plus/capability-statistics.json`，以 `withFileLock` 和 `writeFileAtomic` 串行化跨实例更新，仅保存身份、资格、使用和结算元数据。续接修订原家族使用位，资格顺序保持不变。公开家族 census 不完整、未进入 step 或 turn 非正常完成时不产生负样本。
+
+## 会话接入
+
+历史 `ptc-capability-environment/v3`：`sourceSettings` 保存采用的复用配置，`sessionOverrides` 保存独立临时维度，`settings` 与 v2 `plan` 为验证后的派生值；其中 `recoveryEnabled` 和 `previewEnabled` 冻结额外说明恢复与插件预览选择。旧 v1/v2 环境仍用原方案计算和正文恢复，保留其管理耦合行为，不套新默认值。配置迁移把旧完整/按需/关闭选择转为规则，并保留原 adaptive 默认、统计分配及已开启管理的恢复/预览；新配置默认 host，恢复/预览关闭。
+
+独立命令为 `/capabilities set session|global <id> availability enabled|closed|automatic|inherit` 与 `/capabilities set session|global <id> disclosure host|full|on-demand|adaptive|automatic|inherit`。`automatic` 仅撤销该维度单项覆盖、重新消费上层规则；`inherit` 仅取消该维度临时选择，恢复冻结源。同项全局保存只清除对应临时维度，保留其它维度。原组合命令仍兼容：closed 关闭且保留说明偏好，full/on-demand 恢复可用并选用说明，automatic 撤销两项单项选择。
+
+以下 v1/v2 描述保留旧代际恢复依据；v3 采用上述独立职责。
+
+`ptc-capability-environment/v1` 源消息记录设置、完整 owner inventory、统计依据与派生方案，digest、方案重算与精确正文共同校验恢复。新方案显式记录当前 `navigationText`；缺少该字段的既存 v1 方案按其原固定导航重算和核验，升级不重写历史正文。首次准备在模型请求之前完成，只产生待接受方案；尚无已提交任务历史时，通过公共 `agent/pre-step` 将新方案放在本次接受消息批次的任务之前，由 Host 在受保护 system head 之后提交一次。已有历史不重排，拒绝、取消或请求准备失败不构成方案恢复证据。已提交方案不重复追加，被压缩的正文不因原始日志仍有记录而复活。
+
+宿主 prompt section 的空字符串或纯空白说明不形成契约依赖，但其 section 身份仍可证明 MCP server 归属。工具签名和资源契约保持可发现；非空说明原样保留并去重，非字符串等无效依赖仍由方案校验拒绝。
+
+工具完整契约与程序检索元数据来自公共 `ToolRuntime.schemas(scope)` 与 `ToolRuntime.get(name, scope).output.schema` 的准确 JSON 快照，包含参数及返回值 schema；输出 schema 也参与修订身份和恢复比较。新 cell 的检索与 inspect 从同一份当前 SDK 快照派生结构化 schema、签名、依赖及修订，不将冻结方案中的旧签名覆盖到新返回值类型上；冻结的是启用与披露选择。每次准备与接受步骤重新读取 live owner 契约；同名工具的参数、输出或说明依赖变化，以及 Skill 调用资格变化或能力移除，以 `capability-contracts` 的 `ptc-capability-contracts/v1` 来源消息更新当前效力。消息记录原方案 digest、当前修订向量、变化项和当前完整说明超额，digest 与精确正文共同校验；不修改原方案。仍选完整的项提供完整新契约和去重依赖，按需项要求检索当前契约，移除项明确撤销。投递经 accepted step，拒绝与取消不提交；未变视图不重复追加，恢复按正式可见消息协调。实际可用和使用统计采用当时的契约修订，已准入调用保留捕获时的观察身份。顶层模型工具 schema、准入与调用规范化继续使用独立的 `ToolRuntime.schemas(scope)`，不向模型工具定义追加 SDK 输出字段。冻结方案只为冻结时已捕获的身份保存选择；宿主随后 live 提供且未被显式关闭的新成员保持宿主声明（工具保留 SDK 命名成员与类型化签名，Skill 保持可加载），刷新才把它折入方案，刷新边界不把成员身份从声明、检索或分派面移除。
+
+Skill 目录的 `snapshot.complete` 由公共 registry 拥有，表示本次 provider 发现与 revision 稳定性已证明。暂时不完整不证明某个 Skill 已撤下：已有冻结环境保留最近完整观察或已校验、已接受的本会话 `capability-contracts` 更新所证明的 Skill 视图，不发布未完整证明的新 Skill，也不把这轮 Skill 观察计为新的统计资格。工具与 MCP 继续消费当前 live owner。冷恢复沿同一已接受契约来源保留确证撤下结果，不能由初始快照复活旧 Skill。新环境和显式刷新仍要求完整目录，失败保留旧环境；取消和真实 Host 错误保持原语义。session Skill projection 仅在实际输出变化时调用 registration-scoped `invalidate()`，不因每次父子会话准备使全局 revision 无意义变化。
+
+保存普通设置不改已有会话；`/capabilities refresh` 在公共 maintenance 边界主动同步。`/capabilities list [all|skills|tools|mcp|mcp_tools] [query]` 只读检索当前受管库存，关闭项仍可查、可重新启用。`/capabilities set session|global <id> full|on-demand|closed|automatic|inherit` 明确操作范围：`session` 只改变本会话临时选择，`global` 以真实设置 namespace 和 revision CAS 保存并在同一次操作内更新本会话，不刷新其他已有会话；`inherit` 仅用于取消临时覆盖，`automatic` 撤销该项显式选择。旧组合命令的 MCP server 只接受关闭、恢复自动和取消临时覆盖；新维度命令支持独立可用性与说明规则，重新启用仍保留子项策略。ID 由命令草稿入口编码，输入匹配由正式 `input.hint` 声明。
+
+新环境 `ptc-capability-environment/v4` 冻结总选择 `settings.contextEnabled` 与原子项，即使整组暂停也通过 accepted 计划消息保存来源；新会话和明确刷新使用最新设置。历史 v1-v3 不接受这一新维度，保持原代际解释。
+
+`ptc-capability-environment/v2` 独立记录 `sourceSettings`、`sessionOverrides` 和合并后的 `settings`；恢复校验合并结果、完整方案及精确正文。普通刷新保留临时选择，全局单项快捷操作清除同项旧临时覆盖；命名配置只导出全局源设置。恢复后的首次检索、刷新或修改均从同一已验证输入来源读取，不要求先发一个模型请求。检索不准备方案或制造统计。
+
+已初始化会话在完成所有可失败的 Skill 投影准备后，追加一次正式计划消息；准备或追加失败保留旧完整环境。首轮前不得越过受保护 system head；实际命令回执在 `CommandResult.text` 内保留结构化 pending 提案，由 Host 记录配对的 `command/run` 和成功 `command/done`，首次 accepted step 才将其通知投递给模型。取消、失败、缺少配对或损坏回执不能证明临时选择，也不能由迟到的 handler 返回值重新激活。只调用导出的 `appendPluginRecord` 仍违反外部插件禁令，故不采用。全局保存成功而后续读取或会话发布失败时报告 saved-only 及原因，不回滚已经确认的全局写入，不假称本会话已更新。历史无方案的会话保持原提供方式，损坏方案通过真实发布边界关闭管理并继续宿主环境，用户可主动刷新。
+
+家族资格顺序和单调观察修订独立于可淘汰样本保存在统计文件的 `families` provenance 中；缺失或损坏的 provenance 不作为有效统计。
+
+正式 `tool/result` 的 `dshPtcPlusCapabilities` 元数据记录 `ptc-capability-evidence/v1` 的方案 digest、展开与使用身份。恢复按原方案和当前 ordered surface 中完整契约及依赖的实际文本去重；计算内展开不等于模型可见，选用说明恢复时在独立预算内补回近期实际使用且已展开的 API 契约及依赖，不补回 Skill 正文，不改变 binding 保留规则。`run_code` 的正式 output presentation metadata 与 `edit_run_code` 的派生结果共同携带证据。
+
+设置清单通过只读 `ptcPlusCapabilities/invoke` 的 `catalog` 操作读取 code agent 当前的公共工具与 Skill inventory，以及已捕获 prompt sections 的 MCP server 目录，不创建模型请求、发布方案或加载 Skill 正文；`inspect` 独立提供冻结会话方案。目录的 `name` 与 `source` 仅为 UI 展示：普通 Tool 说明来自 DSH 注册表，捕获的 MCP owner section 才能证明具体服务器；Skill 来源取公开 provider/source，跨 agent 来源冲突标为未确认。它们不进入冻结能力快照、修订或模型说明。没有可观察 code agent 时展示明确空状态，读取失败保留最后观察结果及已保存选择，可用状态改为未确认。
+
+设置刷新按钮通过只读 `targets` 获取活跃 PTC 会话身份，并要求明确选择目标；星光菜单从公共 slot 读取当前会话的命令可用性，与绑定编写共用输入框保护，将 `/capabilities refresh` 预填到空输入框并关闭菜单，等待用户发送。设置按钮由 `CapabilityRefreshButton` 通过 authenticated `commands.execute` 直接执行；最终都委托同一 Host 刷新 owner。身份观察不读取或准备冻结方案，管理关闭时仍可主动同步关闭配置。目录/方案重读保持只读。Client 在取消、断线、preset 改变、会话切换、卸载或插件关闭后丢弃迟到回执；停止等待不表示撤销已提交的 Host 效果。
+
+管理默认关闭。设置工作台分为能力、上下文、统计、配置四个页签。能力页默认直达清单，名称下展示精确 ID，类型和来源独立显示；行内启停只修改可用性，上下文选择、常用集与继承规则在单项详情中独立编辑。筛选在独立小窗中按需打开，提供类型、来源、规则、常用与可用状态筛选；五列表头支持升序、降序、默认三态排序，会话列表复用同一展示排序 owner。批量设置打开一次性小弹窗，将当前筛选中真实可用的目标固化为单项变更，确认才写入；默认、类别和来源的持久继承规则使用独立入口。类型切换清除不兼容来源，Tools 与 MCP 工具的浏览入口区分，来源规则只使用已证明的 server 身份。详情区分保存值与明确选定会话的结果。上下文页以能力说明、说明恢复、结果与日志三个固定目的地组织双栏设置，各项开关及额度独立，关闭保留参数；预算预览位于能力说明详情。全部开关使用官方 capsule track、圆形 thumb、尺寸和主题 token。统计页可切换查看所选活跃 PTC 会话的当前工作区或全局使用数、合格家族样本数和覆盖率；不完整窗口或不可用证据保持明确状态。能力说明的预算预览从该会话当前 SDK/Skill/MCP 清单、已保存配置与实际统计调用同一纯方案 owner，显示完整/按需/关闭选择、原因、正文大小、包含共享依赖的总预算和超额。观察通过 `allocation` RPC，使用只读 assembly observation，不准备或发布会话方案，不登记样本、读取 Skill 正文、调用工具或请求模型；目标退出和迟到回复会失效。配置序列化由 Client 完成，用户无需编写 JSON；最低样本数超过窗口等无效输入不提交。已有配置中暂不可用的能力选择保留并可撤销。配置页以左侧命名配置库、右侧所选详情组织；唯一保存当前设置、导入和更多动作在列表下方，会话观察另行展开，与已保存配置分开。`capabilityProfiles` 的 `ptc-capability-profiles/v1` 文档保存最多 100 份具名能力设置，支持命名保存、重命名、删除、文件导入导出和一次公共设置 mutation 切换；导入不自动应用，同名导入生成新名称。会话观察同时提供源设置，用户可读取并命名保存，不复制统计证据或计算状态。切换配置不刷新旧会话，明确选定目标的正式 Host 命令才提交刷新；原冻结方案继续展示选择、原因、覆盖率、显式超额和待刷新状态。格式与边界见 [ADR 0040](adr/0040-separate-capability-configurations-from-session-observations.md)。有界 `capabilities.search` 的原接口保持兼容，见[能力投影](capability-projection.md)。大结果和日志使用宿主 spill 服务保留完整展示，存储失败回退原文；canonical 程序值不受预览影响。
+
+组件和接入证据见 `test/capability-plan.test.js`、`test/capability-statistics.test.js`、`test/capability-environment.test.js`、`test/plugin-program-bindings.test.js`、`test/context-result-preview.test.js` 与能力设置 Client 用例。固定 7 项普通任务加 1 项 canary 的 Command Goat / DeepSeek V4.1 Flash 付费配对已运行并完成 16 份盲评。插件侧盲评总分为 correctness 22/24、efficiency 15/24、clarity 21/24，原生基线为 22/24、10/24、21/24；机器验收因原生基线 3 项超过预设调用或 token 上限而阻止。全任务 traffic 为插件 132,332、基线 340,712（普通任务排除 canary 后为 122,933 对 325,862），这是一轮单 replicate 结果，不构成普遍收益保证。
+
+历史 MCP server 总开关复用手动覆盖中的 `mcpServers.<server>: closed` 配置身份，工具和资源仍保留其单项配置。纯方案先应用已捕获的 `mcpServer` 归属关闭，再处理子项披露；目录、共享资源 server 枚举和编译成员同取该冻结结果。来源以公共 server 目录/归属段与已注册限定命名空间为证，重叠且无法区分的命名空间在刷新前报告缺少准确 owner，不猜测删除。原有无归属字段的历史库存按原单项语义恢复。目录观察使用 `ptcPlusCapabilityObservation` 的公共 assembly context，直接 surface owner 在该只读路径跳过会话准备和绑定输入加载。

package/docs/capability-projection.md

@@ -25,12 +25,17 @@ profile 使用 `node:fs/promises.readFile` 或 stream，并接受该直接 I/O
 ## Descriptive explorer
 
 ```ts
+await capabilities.search({ query: "read file content", budgetBytes: 8192 })
 await capabilities.tree()
 await capabilities.find("session")
 await capabilities.inspect({ symbols: ["tools.session_search"], budget: 8 })
 await capabilities.inspect({ symbols: ["repl.state", "code.run"], budget: 2 })
 ```
 
+- `search({ query, budgetBytes?, limit?, cursor? })` 用中英文词项、名称及当前索引的 owner 描述/关键词查找；一次返回完整索引条目，包括参数、返回 schema 和已有 metadata。精确 symbol/name 优先，多词不要求连续；它是词法检索，不是模型语义推断。它不读取未公开的 Skill、资源或服务，也不补造 owner 指引。
+- `search` 默认 16384 UTF-8 JSON 字节、至少 512 字节，默认每页考虑 10 个匹配项。这些是检索响应边界，不是已校准的 token 最优值。`usedBytes` 计入整个返回 JSON 的包装、游标和省略指针；外层 `run_code` 格式及值图展示另有成本。契约无法容纳时不截断 schema，返回 `oversized` 与单项 `inspect` 参数；调用者可提高字节预算，或显式使用原有无字节预算的 inspect。
+- `cursor` 在相同 query 与索引内容下继续；契约/目录变化时拒绝旧游标。`remaining` 表示还未考虑的匹配项，不表示缺少的 API。每个 cell 构建一次派生索引，调用不执行被描述的能力、不请求模型，并沿用 cell lease 和 recorded-value replay。
+- search 在规范化前校验并快照原始 owner/member 及嵌套 schema 的无损 JSON 数据；accessor、非枚举字段和非普通对象会被拒绝，校验不调用 getter。这个新增边界不改变 tree/find/inspect 的原有元数据接受规则。
 - `tree()` 返回 `tools`、`repl`、`code` namespace 与 member 名称，适合低成本定位；
 - `find(query)` 在 symbol 与 description 中做确定性查找，返回 completeness、effect 和 replay 摘要；
 - `inspect({ symbols?, budget? })` 批量返回 live JSON schema 与 metadata，并显式返回 `omitted`、`unknown` 和实际 budget；不传 symbols 时检查当前 view 的前 50 项。
@@ -39,6 +44,8 @@ await capabilities.inspect({ symbols: ["repl.state", "code.run"], budget: 2 })
 
 explorer 不调用 capability、不提升 authority、不读取隐藏服务、不触发辅助模型请求。`tools` metadata 来自执行时 agent scope 的 live schemas；`repl.state` 与 `code.run` metadata 由插件自身契约提供。模型若要根据探索结果决定下一步，仍会发生正常的后续 turn。当前公共扩展面没有跨 prompt assembly 与 runtime dispatch 的冻结 token，因此定义变化不能被描述成原子 snapshot。
 
+能力管理开启时，同一冻结方案拥有启用与披露选择，当前宿主契约拥有首轮说明、按需检索及编译前实际成员投影。可用性与说明分别选择；host 项继续保留原说明路径，只有完整或按需项由方案替代其 SDK 说明。分配、统计采集、恢复与预览各自独立；见 [ADR 0043](adr/0043-compose-capability-and-context-policies.md)。配置保存不重排已有会话；`/capabilities refresh` 同步环境并提交持久通知。search 的字节边界不能独自证明完整任务 token 降低；接入证据见[公共接口覆盖](context-public-interface-coverage.md)，格式和恢复路径见[组件说明](capability-planning-components.md)。
+
 `code.run` 返回 `{ logs: string[], result?: unknown }`：`logs` 按发出顺序保存 child console 输出，child 返回 `undefined` 时省略 `result`。该结构描述不改变其中任意值的 completeness，也不表示 child 无外部 effect。
 
 ## Non-tool APIs

package/docs/client-ui.md

@@ -1,6 +1,6 @@
 # Client UI
 
-标准 `verify`、`check` 与 CI 的 `verify:ci` 均执行 `test:client:visual`，在一次 Client 测试生成的实际 renderer 夹具上检查关键控件的尺寸、可读性、悬停、键盘焦点、禁用反馈及布局。浏览器准备、覆盖清单、故障反例与官方宿主验收边界见 [Client visual contract](client-visual-contract.md)。
+标准 `verify`、`check` 的完整验证分支与 CI 的 `verify:ci` 均执行 `test:client:visual`，在一次 Client 测试生成的实际 renderer 夹具上检查关键控件的尺寸、可读性、悬停、键盘焦点、禁用反馈及布局。浏览器准备、覆盖清单、故障反例与官方宿主验收边界见 [Client visual contract](client-visual-contract.md)。
 
 PTC Plus 提供**插件设置卡片**。卡片座位由宿主代际决定：更早、未冻结的代际在 DSH Web/Desktop 的 Settings → Plugin configuration 中以 `settings.plugin.item` 渲染，当前代际在侧栏 Plugins → Installed 页面以 `plugins.row.config`（键 `<包名>#<行 id>`）渲染该 bundle 自己的配置；General 设置不是本卡片的座位，`src/client-host-compat.js` 只发布到这两个插件配置座位，由声明了槽位的那一代决定哪个生效，卡片按座位提供的 `summary`/`page` 视图分别渲染一句描述与完整表单。输入框旁的星光菜单还直接打开复用同一表单的应用内设置窗口，不依赖宿主页面的局部导航状态；菜单项悬浮提示保留原生设置座位的路径。
 
@@ -25,35 +25,60 @@ Client 按数据、传输、注册与视图分文件，沿用既有 `createX(Rea
 ## 设置命名空间
 
 当前 Host half 的 `Config` 文档由 DSH 公共 `settings` 服务按 owning Loader entry 的 profile ID 寻址；更早 section installer 兼容支仍注册 `ptc-plus` 命名空间。失败补偿由 settings compatibility owner 绑定同一写入身份，不把固定 namespace 当作 profile entry ID。字段清单、默认值和校验来自 `internal/config-spec.js`，
-由 `index.js` 的 `Config` schema 与设置注册共用；client half 构建时把同一份字段清单打进 bundle，不在 UI 中复制默认值。`CONFIG_GROUPS` 独立拥有按用途排列的展示顺序：插件总开关单独置顶，其后为“调用容错”“REPL 语法”“状态与恢复”“工具扩展”“界面显示”“资源限制”。每个字段只展示一次，各组使用独立标题、留白与分隔线。
+由 `index.js` 的 `Config` schema 与设置注册共用；client half 构建时把同一份字段清单打进 bundle，不在 UI 中复制默认值。`CONFIG_MODULES` 与 `CONFIG_GROUPS` 独立拥有功能模块和展示顺序：核心工作区（REPL 语法、状态与恢复）、扩展与容错（工具扩展、调用容错）、界面与资源（界面显示、资源限制）、实验性（能力与上下文）。配置页与弹窗将总开关与导航顶部的 PTC Plus 标题合成无描边的一行，整行标题可点击，开关状态代替重复的已启用标签；静态模块标题使用小字与分隔线，导航项使用图标、箭头和选中标记，正文不重复总开关；旧折叠卡片保留置顶的总开关。设置工作台在宽屏下使用左侧分区导航与右侧内容双列布局，小屏回退为横向导航与独立正文；官方插件配置页使用独立留白和以实际容器宽度决定的分栏，正文有界滚动，小容器导航变为横向列表；弹窗导航和正文分别滚动，正文滚轮与分区导航都不移动左侧导航或共享弹窗容器；桌面导航的高度受实际正文视口约束，短窗口中独立滚动以显示键盘焦点；窄且极短的弹窗将标题开关与横向导航合成一行，进一步压缩头部和标题留白，保留正文视口。键盘焦点只在自有横向导航列表内展开，分区定位按实际正文高度保留可用留白。分区导航只设置插件自有正文的滚动位置，不调用会连带移动外层页面的 `scrollIntoView()`；每个字段只展示一次，各组使用独立标题、留白与分隔线；能力与上下文内部的当前会话能力方案显示有效选择与待刷新状态。
+
+能力列表通过能力 Remote 的只读 `catalog` 操作观察 code agent 的当前公共工具、Skill inventory 和已捕获的 MCP server 目录，与 `inspect` 返回的冻结方案分开。分组标题旁的总开关保存 `capabilityContextEnabled`，整体暂停而不改写子项；控制仍可编辑，配置库和冻结来源复制保留该维度。重新开启恢复保存组合，仍遵守新会话与明确刷新边界。`src/client-capabilities-view.js` 拥有能力配置、提示设置、使用统计和配置方案四个页签；页签支持方向键与 Home/End，字段仍由原配置 owner 保存。能力页首先显示搜索、类型按钮和能力清单；每行分别展示名称与精确 ID、类型、来源、保存规则的启停结果和上下文提供方式。名称下方不使用 provider 原始介绍。只有公共目录证明 MCP 来源时才标记 MCP，不从工具名称猜测服务器。Skill 来源使用公开 provider/source，冲突显示未确认。
+
+行内启停只修改 availability；上下文入口打开独立小窗编辑。该小窗不使用折叠入口：可用性与说明两个下拉并排、常用基线为带说明的开关、能力说明与来源规则、所选会话方案全部平铺。保留 availability/disclosure 的独立继承、常用集、Skill 调用资格、完整目录描述及已证明来源规则。来源关闭优先于子项，但子项偏好仍保留。缺失、未知和能力配置未开启分别显示，保存规则不冒充会话实际状态。筛选在独立小窗中按需打开，批量设置使用独立的一次性小弹窗；筛选可组合来源、已保存启停、已保存说明、常用项和库存状态，活跃条件显示摘要并可清除。类型切换清除不兼容来源，五列表头三态排序保留同值项的默认相对顺序，列表独立滚动。默认不打开单项或选取首个会话；详情中的冻结方案只供明确目标观察。目录失败保留最后观察内容并标为未确认，已保存的缺失项仍可编辑或移除。基础 REPL 公共能力不列为受管设置项。
+
+提示设置页使用固定功能导航与单项编辑的两栏结构，导航仅包含“初始提示”“提示恢复”“输出节选”，没有编号或新增条目动作。名称旁与摘要复用同一保存状态判定：已选用、未选用、已暂停、沿用 DSH 或未确认。初始提示随能力配置应用，提示恢复与输出节选各有独立开关；总开关关闭时保留选择并显示暂停；状态与导航选中高亮分开，不断言现有会话已同步。短名称作为可访问名，状态作为可访问描述；窄容器使用三条全宽紧凑功能行，名称在左、状态在右。能力说明设置默认提供方式，常用集、使用统计与预算各自选用，分配依据、额度与只读分配预览直接展示。分配只影响 adaptive，显式完整说明不会被预算降级。提示恢复和输出节选分别有独立开关，关闭不清除额度，不依赖能力管理。统计页先选择观察会话并显示真实证据，工作区与全局分别查看使用家族数、可用家族数和覆盖率；未知或不完整显示破折号和证据状态，不能计零。采集开关独立于统计消费，窗口、最低样本数和百分比阈值放在“统计设置”中；保存前校验正整数窗口、最低样本不超过窗口与 0–100% 阈值，无效数字草稿不阻止关闭采集。
+
+配置页采用左配置库、右详情；唯一“保存当前设置”与导入、配置库更多操作位于列表下方。命名保存、重命名与会话复制仅在对应动作后展开；列表可在只读状态浏览，写入遵循公共 settings 资格。详情显示可复用设置摘要与应用按钮，配置库更多导出全部、详情更多导出所选，导入仅加入库。应用用一次原子 mutation 更新保存设置，读回冲突不能显示成功；从会话复制只读取已证明的 frozen.configuration，不复制统计、变量或执行状态。已有会话观察和明确刷新位于独立折叠入口。异步导入遇到只读、关闭插件或卸载永久失效，即使资格恢复也不提交迟到内容。详见 [ADR 0040](adr/0040-separate-capability-configurations-from-session-observations.md)。
+
+页内保存状态来自真实 pending/status 和 settings 资格，说明保存设置供新会话采用；已有会话保留冻结环境，需要明确刷新。任一能力与上下文功能选用时可观察冻结来源，全部关闭时取消方案读取；目录观察与手动配置独立。插件关闭、设置关闭与 transport 释放取消请求，迟到响应不能恢复旧状态。所有开关使用 DSH 尺寸与主题 token，按钮文字居中，边框轻量；六列清单在窄容器中分行，配置页堆叠。
+
+能力与上下文提供独立的“刷新会话能力”操作，必须明确选择活跃 PTC 会话；“重新读取目录/方案”只观察状态。星光菜单的同名操作与“编写新绑定”“修改绑定”共用输入框保护，只将 `/capabilities refresh` 填入空输入框并关闭菜单，由用户发送；已有草稿保留。设置按钮通过宿主 `commands.execute` 提交命令，不发起模型任务。关闭能力管理后仍可主动同步关闭配置；冻结方案观察跟随各独立功能的选用状态。关闭 Global User Bindings 只隐藏绑定操作，保留星光设置与刷新。未确认目标、命令不可用、只读设置或插件关闭时不能刷新；取消、断线、preset 改变、切换会话或卸载使迟到回执失效。Host 回执区分已接受、通知待首次接受与失败，取消只停止等待，需重读状态确认实际效果。
+
+会话能力工作台使用一份待应用更改，不先切换生效范围。底部提供“放弃更改”“应用到会话”和“应用到全局”：分别清空草稿、写入会话临时选择、保存全局默认并更新当前会话。撤销临时覆盖只允许“应用到会话”，不能把 `inherit` 写入全局设置。全局提交只有重新读取到对应保存选择且该项临时覆盖已清除才从草稿移除；部分失败和无法确认的更改仍可重试。详情区使用独立的 13px/20px 正文与紧凑的状态信息，来源、全局设置、冻结继承、临时覆盖和实际生效分别显示；冻结来源未知时不从全局值猜测。整行都可选中：任意单元格（含空白处）与名称按钮一样打开该条目详情，可用性与上下文单元格保留各自的维度焦点。共享 Select 使用居中的 SVG 箭头，Radix 继续拥有键盘、焦点与独立 Portal。
+
+`/capabilities refresh` 与结构化状态回执使用独立的 13px/20px 单行提示，只显示当前界面的结果文案，不显示命令标题、重复状态或原始结果入口。运行、待生效和失败保留各自的真实文案，长错误可以换行；历史刷新回执的已记录通知文本同样转换为简短提示。能力查询保留命令卡片。`ptc-capability-catalog/v1` 结果默认显示条目数，展开后以有高度上限的可滚动表格显示列表；其他 JSON 显示详情入口，不直接铺在正文里。查询的原始结果单独折叠，在展开时显示完整原文，既不改写历史结果也不把成功回执当作完整值或模型投递的新证明。
 
 ## 可用设置
 
-| 分组 | 字段 | 说明 |
-| --- | --- | --- |
-| 开关 | `enabled` | 关闭后不注册 `run_code`/`edit_run_code`、不修改 system prompt、不创建 session runtime；保留设置 UI，Host 在下一允许步骤撤销旧 PTC 声明。 |
-| 调用容错 | `autoDescribeRunCode` / `canonicalizeToolCalls` | 默认开启；允许缺少外层摘要的 `run_code` 执行，并修复 schema 可唯一确认的顶层 native 工具误调用。 |
-| REPL 语法 | `bindingUpdates` | 默认 `stateful`；同作用域的声明与赋值更新变量、函数、类和导入。选择 `protected` 后保护新建 const/import，并检测跨 cell 重声明。两种策略均支持静态 import/export。 |
-| 状态与恢复 | `durableReplay` / `tipsEnabled` | 默认开启；控制 worker 重启后的状态恢复与失败恢复提示。 |
-| 状态与恢复 | `tipCooldownMessages` / `tipEscalationFailures` | 同类提示间隔与详细提示阈值。 |
-| 工具扩展 | `userBindingsEnabled` | 默认开启，显式关闭仍有效；开启时加载跨会话 TypeScript helper，并在开关下方显示管理按钮，同时启用全局绑定工作台与 `/binding` Agent 编写入口。 |
-| 工具扩展 | `cordisToolsEnabled` | 默认关闭；开启后为 PTC agent 加入官方 Cordis 工具、指引与精确的 `cordis-plugin-development` companion Skill，不发布同目录 sibling。 |
-| 界面显示 | `enhancedToolView` | 默认开启；关闭后注销 PTC Plus 的两个 keyed tool view，恢复 DSH 原生 generic row。 |
-| 界面显示 | `replViewEnabled` | 默认开启；控制顶级 REPL 页签，关闭时释放观察订阅，不影响设置中的全局管理入口。 |
-| 界面显示 | `bindingAuthorButtonVisible` | 默认开启；控制输入框旁的 PTC Plus 快捷入口（全局绑定查看/启停/编写，以及直接打开完整插件设置窗口），不撤销 `/binding` 命令。 |
-| 资源限制 | `computeMs` / `maxWallMs` | 单 cell event-loop active（包括同步阻塞）与总耗时预算；前者不证明 CPU 消耗。 |
-| 资源限制 | `maxOldGenerationSizeMb` / `maxNestedRunCodeDepth` | kernel worker 内存与嵌套执行深度。 |
-| 资源限制 | `maxOutputBytes` | 单 cell 日志与返回结果的合计字节上限。 |
-| 资源限制 | `maxValueNodes` / `maxValueEdges` / `maxValueArrayLength` / `maxValueBigIntDigits` | Value Graph 与大数组、BigInt 的返回上限；数组长度限制同时约束单数组和一份 graph 的累计槽位。 |
+| 功能模块 | 分组 | 字段 | 说明 |
+| --- | --- | --- | --- |
+| 插件开关 | 开关 | `enabled` | 关闭后不注册 `run_code`/`edit_run_code`、不修改 system prompt、不创建 session runtime；保留设置 UI，Host 在下一允许步骤撤销旧 PTC 声明。 |
+| 核心工作区 | REPL 语法 | `bindingUpdates` | 默认 `stateful`；同作用域的声明与赋值更新变量、函数、类和导入。选择 `protected` 后保护新建 const/import，并检测跨 cell 重声明。两种策略均支持静态 import/export。 |
+| 核心工作区 | 状态与恢复 | `durableReplay` / `tipsEnabled` | 默认开启；控制 worker 重启后的状态恢复与失败恢复提示。 |
+| 核心工作区 | 状态与恢复 | `tipCooldownMessages` / `tipEscalationFailures` | 同类提示间隔与详细提示阈值。 |
+| 扩展与容错 | 工具扩展 | `userBindingsEnabled` | 默认开启，显式关闭仍有效；开启时加载跨会话 TypeScript helper，并在开关下方显示管理按钮，同时启用全局绑定工作台与 `/binding` Agent 编写入口。 |
+| 扩展与容错 | 工具扩展 | `cordisToolsEnabled` | 默认关闭；开启后为 PTC agent 加入官方 Cordis 工具、指引与精确的 `cordis-plugin-development` companion Skill，不发布同目录 sibling。 |
+| 扩展与容错 | 调用容错 | `autoDescribeRunCode` / `canonicalizeToolCalls` | 默认开启；允许缺少外层摘要的 `run_code` 执行，并修复 schema 可唯一确认的顶层 native 工具误调用。 |
+| 界面与资源 | 界面显示 | `enhancedToolView` | 默认开启；关闭后注销 PTC Plus 的两个 keyed tool view，恢复 DSH 原生 generic row。 |
+| 界面与资源 | 界面显示 | `toolHoverPreviewEnabled` | 默认开启；控制执行行的悬停与键盘聚焦预览，即时生效。 |
+| 界面与资源 | 界面显示 | `replViewEnabled` | 默认开启；控制顶级 REPL 页签，关闭时释放观察订阅，不影响设置中的全局管理入口。 |
+| 界面与资源 | 界面显示 | `bindingAuthorButtonVisible` | 默认开启；控制输入框旁的 PTC Plus 快捷入口（全局绑定查看/启停/编写，以及直接打开完整插件设置窗口），不撤销 `/binding` 命令。 |
+| 界面与资源 | 资源限制 | `computeMs` / `maxWallMs` | 单 cell event-loop active（包括同步阻塞）与总耗时预算；前者不证明 CPU 消耗。 |
+| 界面与资源 | 资源限制 | `maxOldGenerationSizeMb` / `maxNestedRunCodeDepth` | kernel worker 内存与嵌套执行深度。 |
+| 界面与资源 | 资源限制 | `maxOutputBytes` | 单 cell 日志与返回结果的合计字节上限。 |
+| 界面与资源 | 资源限制 | `maxValueNodes` / `maxValueEdges` / `maxValueArrayLength` / `maxValueBigIntDigits` | Value Graph 与大数组、BigInt 的返回上限；数组长度限制同时约束单数组和一份 graph 的累计槽位。 |
+| 实验性 | 能力与上下文 | `capabilityManagementEnabled` | 默认关闭；开启实验性能力管理，冻结新会话的能力方案。 |
+| 实验性 | 能力与上下文 | `capabilityBaseline` / `capabilityPolicy` | 可搜索的能力列表、常用勾选、独立可用性与说明规则；默认/类别/来源/单项覆盖，分配依据及预算分别选择。 |
+| 实验性 | 能力与上下文 | `capabilityStatistics` | 实际使用统计与采集开关及样本窗口、最低样本数、完整披露百分比输入；无效输入不提交，关闭或无可用样本时保留手动基线。 |
+| 实验性 | 能力与上下文 | `capabilityProfiles` | 最多 100 份命名能力配置；保存、重命名、删除、文件导入导出、原子切换与读取会话源设置。 |
+| 实验性 | 能力与上下文 | `capabilityBudgetBytes` / `capabilityDirectoryBytes` / `capabilityRecoveryEnabled` / `capabilityRecoveryBytes` | 完整契约、导航及压缩后说明恢复的 UTF-8 字节预算；显式完整契约不截断。 |
+| 实验性 | 能力与上下文 | `modelPreviewEnabled` / `modelPreviewTokens` | 独立选择模型展示的估计 token 预算，复用宿主 spill 服务，不改变完整程序值。 |
 
 旧配置的五个开关（`looseTopLevelRedeclarations`、`looseTopLevelFunctionClassRedeclarations`、`autoRewriteImports`、`autoStripExports`、`autoSplitRedeclarations`）先由共享 resolver 迁移。完整策略映射到 `stateful` 或 `protected`；混合选择保留显式兼容态，只有该状态才显示旧控件。兼容态的统一策略控件显示“沿用旧版设置（尚未迁移）”，可直接选择“允许重声明和覆盖”或“启用名称保护”；选择后一次写入同时保存 `bindingUpdates` 并清除兼容标记，随后执行和模型指引采用相同的新语言策略，设置页恢复统一开关。仅查看设置不触发写入。
 
+能力配置通过可搜索列表、常用勾选与独立可用性／说明方式选择编辑；默认、类别、MCP 来源、单项分别按维度覆盖。“沿用上层规则”撤销当前维度的显式选择，“按依据分配”独立选用常用集、统计和预算。使用统计、提示恢复与输出节选分别设置，Client 负责序列化。统计数字输入保留未完成或无效草稿，失焦时仅保存有效组合；无效草稿显示错误，统计开关仍可独立保存并恢复最近有效的数字组合。方案展示通过公共能力 RPC 读取当前会话的选择原因、覆盖率、预算超额和待刷新状态，保存配置本身不等于旧会话已更新。
+
 ## enabled 开关与正文功能标记
 
-所有字段都是实时设置：Host 在 settings watch 中安装、卸载或重配置 runtime。已提交的 cell 固定使用提交时的配置快照，运行中的更新从随后提交的 cell 开始使用；这不会替换 session-bound REPL 或已有 binding。`maxOldGenerationSizeMb` 在活动 worker 存在时因 Node 的创建期限制而拒绝并回滚，其他可重配置字段照常交给 owner。关闭后唯一的宿主副作用是注册 settings 命名空间，
+保存设置后，Host 在 settings watch 中安装、卸载或重配置对应 owner。能力与上下文的独立职责输入用于新会话；已有会话保持冻结方案，执行 `/capabilities refresh` 后才同步说明、发现与执行成员。其他可重配置字段即时生效。已提交的 cell 固定使用提交时的配置快照，运行中的更新从随后提交的 cell 开始使用；这不会替换 session-bound REPL 或已有 binding。`maxOldGenerationSizeMb` 在活动 worker 存在时因 Node 的创建期限制而拒绝并回滚，其他可重配置字段照常交给 owner。关闭后唯一的宿主副作用是注册 settings 命名空间，
 保证设置卡片仍然可读；此时只有 `enabled` 可写，其他控件被禁用。运行时重配置失败时回滚到上一次已应用值。
 
-`cordisToolsEnabled` 默认关闭并即时生效。它不切换 preset，而是把官方 Cordis 工具、owner guidance 与 `cordis-plugin-development` Skill 作为一个 agent-scoped mount 加入或移出同时暴露 `run_code`、`skill` 工具与 preset/Skill service 的 PTC agent；顶层仍为 `run_code` / `edit_run_code`，普通 agent 不继承。暴露面齐全但挂载失败时，启用会完整回滚；agent scope 缺少 companion surface 时只是延后，不报错也不发布。完整运行要求见 [运行时参考](runtime-reference.md)。
+`cordisToolsEnabled` 默认关闭并即时生效。它不切换 preset，而是把官方 Cordis 工具、owner guidance 与 `cordis-plugin-development` Skill 作为一个 agent-scoped mount 加入或移出同时暴露 `run_code`、`skill` 工具与 preset/Skill service 的 PTC agent；顶层仍只有 `run_code`，编辑器通过程序内的 `tools.edit_run_code` 调用，普通 agent 不继承。暴露面齐全但挂载失败时，启用会完整回滚；agent scope 缺少 companion surface 时只是延后，不报错也不发布。完整运行要求见 [运行时参考](runtime-reference.md)。
 
 ## 全局用户 Binding 工作台
 
@@ -107,7 +132,7 @@ PTC session 的头部弹窗在功能启用时增加 Session 与 Global 页签。
 
 投影通过 DSH 正式的 `tool/call.data.callId` / `tool/result.data.message.source.callId` 身份配对 `run_code` 与 `edit_run_code`，不依赖可选 `sourceEventSeqs`。它只接受当前 runtime generation 的 envelope，并在 `session/end-seed` 清除旧 lifecycle 的 live 证明；缺少、损坏、其他 generation 的 metadata、无关 tool result 与不影响 binding provenance 的 result-only replacement 都不能覆盖仍有效的最后已证明清单。若 surface replacement 遮蔽了声明 provenance，runtime 与 projection 共用的 model-visible frontier 判定会让相关 inventory 失效。缺少有效 metadata、projection service 或兼容 registration contract 时只显示不可确认，不主动读取历史、不迁移日志，也不影响继续会话。来源跳转要求 Host 提供打开 tool call 或 source location 的公共 capability；缺少该 capability 时，卡片只提供内联检查，不访问私有 store 或宿主 DOM。
 
-`enhancedToolView` 开启且插件启用时，Client 通过公共 keyed `tool.call.toolview` 注册 `run_code` 与 `edit_run_code`；任一开关关闭时实时 dispose 两个注册，让 owner 恢复 DSH 原生 fallback。这个正文 slot 只依赖 Host 提供的 key、`toolName`、`sessionId`、`useSessions`、运行中/已结算 `block` 与 `inspect` 公共契约。增强行保留 Code / Code edit 标题、可展开的原始源码（`arguments` 与 `argsRaw` 任一公共形态均可读）、结果、可见且可访问的运行/失败/中断状态和 Inspect 入口；在提供时优先使用公共 `DisclosureRow` 与 `CodeBlock`，缺少 `DisclosureRow` 时回退到插件自有行，缺少 `CodeBlock` 时回退为纯文本源码。`DisclosureRow` 路径把运行/失败/中断状态、摘要和已证明的功能标记放进始终可见的预览区，摘要可换行，功能标记独立排列在其下方；完成态由标题与摘要表达，运行/失败/中断状态由文字 chip 承担并保持可访问。插件通过公共 class 槽位让标题行按内容高度伸展，标题和图标与预览首行顶端对齐，摘要与功能标记之间保留 4px 间距；Host 继续拥有展开交互。源码、结果和 Inspect 只出现在展开主体。结果内容与原生 ioCard 采用相同的灰色圆角背景（`--dsw-alias-markdown-code-block` 加 12px 圆角与边框），失败态使用错误色文字；代码块的语言/复制栏保持原生 CodeBlock 的常亮可见；`检查调用` 入口采用原生 inspectButton 同款胶囊样式，默认 opacity 0，仅在卡片 `:hover` 或 `:focus-visible` 时淡入（opacity .1s），不触发任何布局位移。窄屏下回退路径的摘要允许换行。
+`enhancedToolView` 开启且插件启用时，Client 通过公共 keyed `tool.call.toolview` 注册 `run_code` 与 `edit_run_code`；任一开关关闭时实时 dispose 两个注册，让 owner 恢复 DSH 原生 fallback。这个正文 slot 只依赖 Host 提供的 key、`toolName`、`sessionId`、`useSessions`、运行中/已结算 `block` 与 `inspect` 公共契约。增强行保留 Code / Code edit 标题、可展开的原始源码（`arguments` 与 `argsRaw` 任一公共形态均可读）、结果、可见且可访问的运行/失败/中断状态和 Inspect 入口；在提供时优先使用公共 `DisclosureRow` 与 `CodeBlock`，缺少 `DisclosureRow` 时回退到插件自有行，缺少 `CodeBlock` 时回退为纯文本源码。`DisclosureRow` 路径把运行/失败/中断状态、摘要和已证明的功能标记放进始终可见的预览区，摘要可换行，功能标记独立排列在其下方；完成态由标题与摘要表达，运行/失败/中断状态由文字 chip 承担并保持可访问。插件通过公共 class 槽位让标题行按内容高度伸展，标题和图标与预览首行顶端对齐，摘要与功能标记之间保留 4px 间距；Host 继续拥有展开交互。Inspect 只出现在展开主体。`toolHoverPreviewEnabled` 默认开启，位于“界面显示”，关闭时即时取消待打开或已显示的预览，原行仍可点击展开。收起的可见工具行在指针停留 400ms 或键盘聚焦后打开紧凑预览；源码最多显示前 6 行、结果最多显示前 3 行，单行与字符预算进一步限制摘录，受限内容标明“部分内容”。预览采用单层主题背景、细边框、语言标签与底部展开提示，不包含复制栏或滚动区域，预览及后代均不参与鼠标命中，滚轮仍由下方对话处理。Client 通过原生 manual Popover 置于顶层，不支持时使用公开 React Portal；只从自有锚点、指针位置和预览节点定位；优先在鼠标右侧显示，右侧空间不足时回退到行的下方或上方，避开鼠标位置，按视口可用空间裁剪正文并保留底部提示，空间不足时不打开。一个工具预览 owner 为所有行共享被动 wheel/scroll 观察：收到事件立即隐藏预览并取消待打开计时，不取消事件、不重派滚轮或访问宿主滚动祖先；滚动停止至少 350ms 后，还需新的指针移动或重新进入行才开始下一次停留计时，静止指针不会自动重开。移出行、Escape、失去焦点、展开、触摸点击或卸载都会关闭；键盘聚焦打开后 Escape 不移动焦点。点击或 Enter／空格仍展开原行，完整已记录内容、复制与 Inspect 仅在显式展开后可用；展开时不显示重复预览，没有源码或结果时不打开空预览。各工作步骤展示模式都遵循此契约，整组收起时须先展开过程组。预览与展开主体来自同一已记录投影，摘录不改变完整值、模型内容或执行结果，不调用 Inspect、Host 或执行代码。滚动与展示职责见 [ADR 0037](adr/0037-keep-tool-hover-previews-passive.md)。结果内容与原生 ioCard 采用相同的灰色圆角背景（`--dsw-alias-markdown-code-block` 加 12px 圆角与边框），失败态使用错误色文字；代码块的语言/复制栏保持原生 CodeBlock 的常亮可见；`检查调用` 入口采用原生 inspectButton 同款胶囊样式，默认 opacity 0，仅在卡片 `:hover` 或 `:focus-visible` 时淡入（opacity .1s），不触发任何布局位移。窄屏下回退路径的摘要允许换行。
 
 功能标记不是计数，也不把“插件已启用”冒充成一次功能收益。Client 只在完整 v1-v10 journal 和对应附属 metadata 能证明时显示：自动改写 import（附模块名）、自动剥离 export、自动拆分混合重声明（附已有 binding）、带完整 target/derived-run/non-noop/可选恢复边界关系且与调用目标前置条件一致的安全编辑执行、成功的 `code.run`、由 `PTC-R002` 的 `warning/recover/rolled-back` 语义元组证明本次确实发生的持久重放，以及 `repl.state` 操作。Client 对 v4 同时封闭校验 `bindingPolicy`、`rewritePolicy` 与 `moduleSemantics`，对 v5 还要求 `userBindingsFingerprint`，对 v6 进一步要求 `userBindingsReusePolicy` 为 `fingerprint-v1` 或 `implementation-v1`，对 v7 还要求 `moduleSemantics` 携带可识别的 `importExpressionBoundary`（v1-v6 的 `moduleSemantics` 保持只含 `defaultExportBinding` 的封闭字段集），对 v8 还要求 `userBindingsShadowPolicy` 与 `userBindingNames` 通过封闭校验，对 v9 进一步要求已知的 `languageSemantics`，对 v10 还要求 `moduleTransform` 与语言契约匹配；任一缺失或畸形都不产生功能标记。进程保留或 discarded 状态不作为正文功能标记。普通变量或 function/class 重声明、顶层 native 调用是否来自 canonicalizer、`cordis_*` 成员是否由官方可选 Cordis mount 提供，以及是否实际选择了 prompt 恢复提示没有独立的 Client-only 事实，因此不根据可复制的代码形状、工具名前缀或设置默认值推测；恢复边界本身不展示。
 
@@ -137,15 +162,35 @@ REPL 是单页工作区，上方为“会话绑定”，下方直接展示完整
 
 live 配置若因宿主能力缺失或 runtime 安装/重配置失败，会先回滚所有已创建或更新的 owner，再把持久设置回写为上一次已应用值；回滚写入失败时 Host 记录 activation diagnostic，避免静默把配置显示成不存在的 runtime。
 
+## 能力列表与批量操作
+
+设置与会话能力工作台均提供能力、类型、来源、是否启用、上下文五列。点击表头依次切换升序、降序和默认顺序；切换到另一列从升序开始，同值项保留默认相对顺序。排序只作用于展示，不保存规则或改变当前选中项。窄屏仍保留可操作表头，来源和精确 ID 保持可读。两处清单的整行都可选中：点击任意单元格（含空白处）与点击名称或铅笔等同选择该项；设置清单的可用性开关及其状态标签保持自身启停语义，不触发整行选中，该单元格其余空白同样选择整行。会话工作台以当前生效事实展示这些列，待应用的修改单独显示，不能把草稿当作已生效。
+
+会话的能力与上下文暂停或能力管理未启用时，工作台明确标注该状态并关闭暂存与提交；清单每行显示沿用宿主的事实，不再显示无法收敛的待生效。只有已启用管理、但尚未刷新折入方案的宿主动态成员才显示待生效。
+
+“批量设置”打开独立小弹窗，对打开时当前筛选中的真实可用能力执行一次单项变更。可用性和说明方式独立选择，初始均为不更改；确认前只保留临时草稿，取消不写入。确认使用最新配置，仅改目标单项的所选维度，保留非目标项、其他维度及继承规则；目标失效或保存失败时显示错误，不能显示成功。默认、类别和 MCP 来源的持久继承规则通过“继承规则”入口编辑，与批量操作分开。保存选择仍只在新会话或明确刷新后生效。
+
+提示设置的三个侧栏项在选用状态旁显示具体配置摘要，分别来自默认说明方式及其分配依据、恢复额度和输出额度；总开关暂停和未知配置保持明确标识。分配依据、额度与当前能力分配直接展示，统计设置同样直接展示。观察会话旁以灰色说明其只读统计与预算预览用途，窄屏可自然换行。
+
+## 能力组合摘要与会话对照
+
+“新会话设置”在四个页签上方持续显示，按能力配置、初始提示、提示恢复、输出节选、使用统计排列。五个四字名称与编辑入口相同，按能力、提示、统计三个职责分组，宽屏为1:3:1，窄屏按组纵排。初始提示对应现有首轮能力说明、常用集与预算，不编辑完整宿主 system prompt；其应用依赖能力配置，不新增独立开关。五个状态按钮只导航到已有编辑区，不增加互斥模式或保存来源。提示固定栏目选择由同一 Workbench 拥有，摘要的 aria-controls 直接关联具体编辑 pane。保存反馈由 settings owner 发布，读取不到配置时不把默认值标成已保存选择。总开关只暂停有效输入，摘要沿 `effectiveCapabilitySettings` 显示保留选择与暂停的区别。
+
+“对照已有会话”复用唯一目标与正式刷新入口，不默认选中首个会话。计划观察不依赖子功能开启，只读设置也允许选择目标和重新读取。`describeSessions()` 用持有的实际 Session 沿 `planCommitted` 返回 `publication`；已记录仅证明方案消息已进入记录，不能证明模型已消费通知。界面分别显示冻结来源、临时覆盖、待接受通知与保存差异。历史方案缺少总选择时保持缺失并沿原代际解释恢复/预览，不以当前默认补齐。没有方案或读不到事实不计为零。
+
+读取生命周期记录 pending、error 和对应保存配置身份。保存配置变化、刷新开始或读取失败使上次观察不能证明当前一致；旧观察可保留，但明确标为上次读取。取消与失败后可重新读取，迟到响应不能恢复已中止的读取；目标切换仅消费同一身份的方案。刷新仍通过 DSH 正式命令执行，重新读取不启动任务、执行计算或自动刷新。逐项方案仅显示明确目标。
+
+选择旁的条件说明区分能力可用性与说明方式、采集与历史统计消费，以及保存偏好与实际参与分配。按需仍可发现和使用，分配只作用于最终 adaptive 且当前可用的能力，不关闭能力、不降级显式完整契约。来源关闭压过子项开启但保留偏好；管理关闭时显示未应用并允许编辑偏好。恢复与预览独立，分别保留近期有效已展开 API/无 Skill 正文及完整 canonical 值/执行结果的边界；详细条件按需展开。
+
 ## Client bundle
 
-浏览器入口为 `src/client.js`，构建为 `client.js`：
+浏览器入口为 `src/client.js`，构建为 `client.cjs`：
 
 ```sh
 npm run build
 ```
 
-`package.json` 声明 `dsh.client` 与 `./client` export，并声明当前公共 UI 模块的依赖图。`npm run build` 从 `src/client.js` 生成 `client.js`，`npm run build:check` 比较确定性产物；`prepack` 会阻止陈旧 bundle 发布。
+`client.cjs` 保持 DSH ModuleLoader 所需的 CommonJS factory 格式，扩展名明确区分于包内 ESM 源码；公开入口仍为 `./client`。`package.json` 声明 `dsh.client` 与 `./client` export，并声明当前公共 UI 模块的依赖图。`npm run build` 从 `src/client.js` 生成 `client.cjs`，`npm run build:check` 比较确定性产物；`prepack` 会阻止陈旧 bundle 发布。
 
 `npm run test:client` 使用 DSH 发布的 Cordis、SlotTestRuntime、renderer 和 conversation registry/assembler 验证激活、Location 关联、响应式更新和释放。产物测试（`test/client-bundle.test.js`）只断言构建产物契约：可加载、公开 slot 与 entry 身份、依赖边界和检出换行属性；它不读取 `src/client.js`，也不断言源码写法、CSS 数值或文案字面量，界面行为归运行测试。测试 loader 只适配发布的 ModuleLoader 格式，并为上游 test-runtime 缺失的两个源码引用暴露同一发布 renderer 的函数，不复制其行为。打包后的浏览器启动另由 `npm run test:client:web` 验证，前置条件与命令见 [安装指南](installation.md)。
 
@@ -155,3 +200,5 @@ npm run build
 
 如果 DSH settings service 不可用，Host half 不会因缺少设置服务而加载失败：设置卡片不可用时直接回退为 composition `config`，
 `enabled` 默认开启，运行时按 composition config 工作。
+
+MCP 列表按 server 分组，来源可用性与说明方式使用和单项一致的独立选择器，均可撤销为沿用上层规则。来源显式关闭是外层移除，优先于子项启用；默认关闭仍可由子项启用覆盖，二者不混同。会话详情显示保存选择、临时规则、冻结来源结果及生效的维度来源，空规则显示继承或无覆盖。目录分别保留当前保存设置与冻结会话各自代际的事实；新保存规则不能把历史 scalar 来源改写成空结构规则。已证明的冻结 `managementEnabled` 决定是否预测来源关闭；管理未选用时保留关闭偏好、显示实际 Host 可用，不报待关闭。待应用的来源关闭会在子项详情预告；正式提交和重新读取确认之后才改变生效状态。