dsh-ptc-plus 0.4.10 → 0.5.1

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/N 与 0% 保持数字），窗口证据不完整或容量超限同样显示破折号和状态。采集开关独立于统计消费，窗口、最低样本数和百分比阈值放在“统计设置”中；保存前校验正整数窗口、最低样本不超过窗口与 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 可用，不报待关闭。待应用的来源关闭会在子项详情预告；正式提交和重新读取确认之后才改变生效状态。

package/docs/client-visual-contract.md

@@ -11,7 +11,7 @@ npx playwright install --with-deps chromium
 npm run test:client:visual
 ```
 
-`test:client:visual` runs the Client suite once, exporting actual renderer DOM and current plugin, public primitive and CodeMirror CSS to a newly created ignored directory. The layout runner consumes that invocation's fixtures; missing fixtures, unavailable browsers and failing children fail the command. Its temporary HTML is removed afterwards. The standalone layout entry also removes its own directory after fixture failure, browser-launch failure or completion; an explicitly supplied fixtures directory remains owned by its caller. Screenshots and measurements remain under ignored `artifacts/binding-layout` and `artifacts/button-styles` as diagnostics; screenshots alone are not acceptance assertions. `verify`, `check` through `verify`, and every `verify:ci` matrix entry include this command. CI installs Chromium explicitly and does not download browsers inside the gate. An installed compatible Chromium channel can be selected for focused diagnostics with `--browser-channel msedge`.
+`test:client:visual` runs the Client suite once, exporting actual renderer DOM and current plugin, public primitive and CodeMirror CSS to a newly created ignored directory. The layout runner consumes that invocation's fixtures; missing fixtures, unavailable browsers and failing children fail the command. Its temporary HTML is removed afterwards. The standalone layout entry also removes its own directory after fixture failure, browser-launch failure or completion; an explicitly supplied fixtures directory remains owned by its caller. Screenshots and measurements remain under ignored `artifacts/binding-layout` and `artifacts/button-styles` as diagnostics; screenshots alone are not acceptance assertions. `verify`, the full branch of `check`, and every `verify:ci` matrix entry include this command. CI installs Chromium explicitly and does not download browsers inside the gate. An installed compatible Chromium channel can be selected for focused diagnostics with `--browser-channel msedge`.
 
 ## Coverage
 
@@ -19,30 +19,47 @@ All fixture families exercise light and dark reference palettes, English and Chi
 
 | Surface | Actual controls | Visual states and evidence |
 | --- | --- | --- |
-| Settings and settings dialog | Disclosure, action, numeric input, select, checkbox switch | Normal, keyboard focus, disabled feedback; hover for commands/disclosure; dialog containment |
+| Settings and settings dialog | Disclosure, section navigation, fixed close button, action, numeric input, select, checkbox switch, capability search and independently scrolling choices | Normal, keyboard focus, disabled feedback; hover for commands/disclosure/navigation/close; large dialog containment, wide navigation/content columns and narrow stacking, header and navigation frame remain fixed during owned settings-column wheel scrolling and section selection; borderless title pointer/Space toggle, smaller static module captions and icon/arrow navigation rows are checked; shared parent-scroll counterexample is rejected; desktop native/fallback navigation at 240/420/600px heights reveals every Tab-focused switch/button and Enter target, including native Host insets, and rejects removal of the navigation scrolling constraint; 64px native Host overlay insets at 900px and 240px heights retain the dialog and close hit target; narrow 320/390×240 native dialogs also reveal each selected heading and focused section control, and reject restored stacked navigation; 48 long capability names, row nonoverlap and first/last choice reachability in both locales at narrow/wide widths; typed capability workbench exercises compatible type/source filters plus strategy/availability filters, stable sorting, unavailable preference removal, saved versus frozen Skill disclosure, tab arrow-key focus, one-shot filter, inheritance and row-editor windows that stay inside the viewport without moving navigation or the document; the row-editor window keeps every field flat (no disclosure rows, captioned description and source sections, a labeled common-baseline switch) |
+| Official plugin settings page | Section navigation, settings switches, numeric inputs and selects | Actual page renderer with padded columns and locally scrolling content; container-width stacking at 600px within a wide viewport; live pointer and Enter navigation at 320/390/1440px in both locales/themes retain nonzero document and Host-container scroll offsets; native `scrollIntoView()` counterexample must move an outer ancestor |
 | Global workbench and dialog | Selection, enable switch, icon commands, action buttons, input, instructions, search | Normal, focus, hover where the control or its owner supplies it, disabled feedback, long-label geometry |
 | Draft dock and enlarged review | All three actions, disclosure, separate resize/close icon controls, author attention badge | Native and absent-Button fallback matrix; normal, hover, focus, disabled, actual busy rendering; Enter saves exactly once; combined 320×240/320/400 short-width cases with long source and RPC errors, expanded reading thresholds and near-top anchors |
 | REPL | Observation selection, search, tabs, definition disclosure, four binding-name kinds | Normal and keyboard focus, definition hover, light/dark name readability, long inventory and source geometry |
-| Sparkle menu | Binding rows, disabled-group disclosure, authoring/revision/management/settings and fixed Back | 48 mixed entries; enabled-first counts and default collapse; native/fallback, English/Chinese, light/dark at 390×600, 320×420 and 320×240; independently scrolling catalog, fixed footer, actual action hits and keyboard access; single disabled entry with long purpose, 14px/21px and 24px/36px carrier typography |
-| Command card | Action and native source disclosure | Readable/reachable actions, focus, disabled feedback; saved card remains compact |
-| Tool row | Official DisclosureRow and fallback summary, inspection action, running/error/stopped status and description | Typography hierarchy, long descriptions, absent/multiple feature labels and long details; text containment, nonoverlap, preview spacing and separation from the following message; Enter expansion and inspection, focused inspection becomes visible |
+| Sparkle menu | Binding rows, disabled-group disclosure, authoring/revision/management/settings and fixed Back | 48 mixed entries; enabled-first counts and default collapse; native/fallback, English/Chinese, light/dark at 390×600, 320×420 and 320×240; independently scrolling catalog, fixed footer, actual action hits and keyboard access; single disabled entry with long purpose, 14px/21px and 24px/36px carrier typography; root and revision rows retain explicit enabled state and distinct green/gray badge text and backgrounds, with a same-color counterexample |
+| Session capability workbench | Modal catalog, grouped Tools/Skills/MCP servers and resources/MCP tools, source and state filters, shared Select, detail choice and fixed Discard / Apply to session / Apply to global | 80 ordinary tools plus Skill and MCP entries prove untruncated reachability; native/fallback, English/Chinese and light/dark at 320×240, 390×600, 768×720 and 1440×900; resolved Modal identity and actual DOM prove the native/fallback path; closed/open category Select screenshots, bounded modal, independent catalog scrolling, owned 13px body typography under a 24px/36px carrier, vertically centered SVG choice glyphs, detail choice and command application, phone list/detail drill-down, Home/End, arrow opening, typeahead and closed-trigger Tab navigation, separate Select portal containment, first Escape dismissal and trigger focus return, followed by Modal dismissal and focus return to the sparkle button |
+| Command card | Action and native source disclosure | Readable/reachable actions, focus, disabled feedback; saved card remains compact; capability refresh shows only its outcome in one 13px/20px line without a command header, duplicate status or original-result disclosure; catalog count stays compact, all rows remain accessible in an independently scrolling table, and original result disclosure preserves exact JSON |
+| Tool row | Official DisclosureRow and fallback summary, inspection action, running/error/stopped status and description | Typography hierarchy, long descriptions, absent/multiple feature labels and long details; text containment, nonoverlap, preview spacing and separation from the following message; Enter expansion and inspection, focused inspection becomes visible; passive bounded hover/focus previews, clipping escape, viewport containment and unchanged conversation wheel ownership |
+
+`scripts/client-tool-hover.mjs`, included in `test:client:visual`, retains 24 native/fallback, Chinese/English, light/dark and 320/390/1440 px preview cases plus eight placement, scroll, touch and native-Popover-unavailable cases. It checks recorded source/result/features, lifecycle state, bounded-content labels, no hover buttons or scroll surface, nontransparent material and readable text, viewport containment with right-of-pointer preference and above/below fallback on live width changes, focus/Escape/Enter/Space, complete source/result and Copy after expansion, inspection isolation, multiple-row identity and cleanup. Real `page.mouse.wheel()` gestures must move the conversation while hovering a row or passing the preview footprint, cancel pending/visible previews and never reopen under a stationary pointer. Making the actual preview hit-testable must change the browser hit test, so pointer pass-through is not inferred solely from a class name. Runtime tests independently cover the 400ms dwell, shared wheel/scroll cancellation, 350ms idle-plus-new-movement reopening and live default-on settings, locale and lifecycle cleanup. The preview reads existing recorded text; a folded process group provides no anchor. Exact diagnostics use `node scripts/client-tool-hover.mjs --focus --case <id>` (repeatable) or `--list`; a focused invocation without selection fails before Chromium starts.
 
 Tool previews may contain multiple lines. The plugin's public DisclosureRow class slots size the header to its content and align the title with the first preview line; the Host retains the component and interaction behavior. The browser oracle measures text ranges against the card, header and clipping ancestors within the card, rejects intersecting text and requires a readable gap before feature labels. Horizontal ellipsis remains valid for descriptions and feature details; it does not allow vertical text clipping or lost titles, states or feature names. Injected fixed-height clipping and removed preview spacing must fail on the real renderer. Packed acceptance with `--binding-workflow` produces recorded import/export features through the official execution pipeline and checks the actual collapsed and expanded tool row at narrow and wide widths. The default packed smoke's synthetic typography probe establishes only that the shipped CSS is installed.
 
-The oracle requires actionable button padding of at least 10 px and height of at least 28 px, other controls of at least 16 px height, viewport containment and center hit reachability after scrolling. Enabled text (including nonempty input/textarea values and selected options) and relevant icon foregrounds must have at least 3:1 contrast against the alpha-composited ancestor background; primary actions must retain a nontransparent fill. Hover feedback must change a painted foreground, background, border or shadow without resizing. Keyboard focus must establish `:focus-visible` and a contrasted outline, a changed contrasted border or solid outer shadow ring of at least 1 px (zero offset and blur, positive spread), or the search owner's contrasted `:focus-within` outline. Disabled controls must change opacity/color, retain the disabled cursor and reject focus. Presentation probes restore the previous disabled property without dispatching business events. The dynamic dock additionally obtains disabled state from its real busy view; recorded callbacks prove the probes do not save or inspect accidentally.
+The shared Select oracle samples the visible `button[role=combobox]` trigger, requires nonempty coverage whenever a plugin combobox is visible, and checks hover, keyboard focus and disabled feedback. Radix’s hidden native select carries form values and is excluded from visible-control geometry and modal focus traversal; the trigger retains the ordinary viewport and reachability assertions. Runtime cases cover empty and arbitrary string values, disabled options and disabling an open control.
+
+The oracle requires actionable button padding of at least 10 px and height of at least 28 px, other controls of at least 16 px height, viewport containment and center hit reachability after scrolling. Enabled text (including nonempty input/textarea values and selected options) and relevant icon foregrounds must have at least 3:1 contrast against the alpha-composited ancestor background; primary actions must retain a nontransparent fill. Hover feedback must change a painted foreground, background, border or shadow without resizing. Keyboard focus must establish `:focus-visible` and a contrasted outline, a changed contrasted border or solid outer shadow ring of at least 1 px (zero offset and blur, positive spread), or the search owner's contrasted `:focus-within` outline. Disabled controls must change opacity/color, retain the disabled cursor and reject focus. Presentation probes restore the previous disabled property without dispatching business events. Each hover, focus and disabled probe flushes pending styles and waits for finite animations to finish, including replacements started by browser-dispatched completion or cancellation events. After animated work, the oracle yields one rendering frame before refreshing the animation inventory; the same deadline governs both animation and event settlement. Pages without active animations need no frame delay. A 500 ms settlement deadline fails the probe explicitly rather than accepting an intermediate style; transition-enabled pages and reduced-motion fixtures are measured at their destination state. The dynamic dock additionally obtains disabled state from its real busy view; recorded callbacks prove the probes do not save or inspect accidentally.
 
 Each declared responsibility must occur in the generated layout inventory. Repeated rows share one style owner and are sampled; four REPL name kinds are checked individually. Selected binding rows may retain their selected background on hover, while readability and geometry remain required; an unselected row independently exercises hover feedback. Padding removal, primary-fill removal, same foreground/background, zero opacity, removed hover/focus cues and removed disabled feedback are injected into the real fallback action DOM without replacing its classes or handlers. Each fault must fail its corresponding assertion and is removed afterwards. Additional real-control probes reject white-on-white input values, unreadable selected-row hover and transparent focus outlines and transparent, inset or negative-spread shadows; a contrasted shadow remains a legal focus cue. Error and stopped tool summaries use the public state-error-primary and state-warn-primary tokens; the shared warning foreground mixes the latter with label-primary for light/dark readability, and attention badges use the theme background as foreground; reference palettes do not supply the unsupported danger/warning aliases.
 
 The draft oracle measures the CSS-owned preview budget and compact header controls separately from expanded content. Compact body/actions remain measurable for stable classification but are hidden and inert. When the full header cannot fit above the owned anchor, the preview is hidden and inert; manual review always opens the enlarged surface independently of hidden-period geometry, closing returns to the owned entry, and a neighboring native dock action must retain its actual center hit. Expanded previews retain at least 40 px of source space; enlarged reviews retain at least 24 px even in the narrow/short cases, with larger reading areas at normal viewport sizes. Source scrolling must leave footer actions fixed, and all visible header/footer controls must pass actual hit testing. Resize and close remain separate header controls with at least 12 px between their hit targets; shrink returns to preview while close hides the panel. Return-focus tests interleave exact cloned candidate refresh with modal closure and retain stale, hidden, completed, unreachable and disposed counterexamples.
 
-The sparkle-menu typography oracle requires a plugin-owned 13px/18px content base, 13px disclosure captions and binding names, 12px purposes and 11px states, all with 18px line-height and the inherited font family. It measures text ranges within their row for vertical clipping and checks the caret center against the caption line center, rather than its potentially stretched flex box; injected caption stretching must fail. Horizontal name/purpose ellipsis remains valid. Native/fallback fixtures reproduce a single disabled binding under larger carrier typography, preserve the full purpose title, reject injected inherited font-size and line-height, and accept a smaller carrier. The mixed-catalog root and revision paths and packed official-Host acceptance share the same oracle.
+The sparkle-menu typography oracle also requires the public Menu class slot to retain a bordered, rounded card with padding and shadow when Host CSS loads after plugin installation; injected border, radius and shadow removal must fail on the native surface. It requires a plugin-owned 13px/18px content base, 13px disclosure captions and binding names, 12px purposes and 11px states, all with 18px line-height and the inherited font family. It measures text ranges within their row for vertical clipping and checks the caret center against the caption line center, rather than its potentially stretched flex box; injected caption stretching must fail. Horizontal name/purpose ellipsis remains valid. Native/fallback fixtures reproduce a single disabled binding under larger carrier typography, preserve the full purpose title, reject injected inherited font-size and line-height, and accept a smaller carrier. The mixed-catalog root and revision paths and packed official-Host acceptance share the same oracle.
 
-The sparkle-menu oracle requires at least 24 px of catalog reading space, viewport containment, nonoverlapping catalog and footer, no outer scrolling, and fully reachable footer actions of at least 24 px height. Scrolling the expanded mixed catalog and the revision list in both directions must leave footer geometry unchanged. Injecting a shared outer scroll container must fail the oracle; restoring the layout must pass. Actual catalog writes must retain a focused control whose center is inside the catalog clip and passes hit testing: collapsed disable, expanded enable, revision Back, and pending close/reopen are covered. Removing the reveal by resetting only the catalog scrollTop must fail this focus oracle; restoring it must pass. Page scroll and footer geometry remain unchanged. Packed official-Host acceptance repeats the mixed-catalog checks through the isolated profile and exercises actual management and settings actions.
+The sparkle-menu oracle requires at least 24 px of catalog reading space, viewport containment, nonoverlapping catalog and footer, no outer scrolling, and fully reachable footer actions of at least 24 px height, including the capability-refresh command shortcut. The root starts with the enabled group without a scope caption, disabled-group disclosure uses a neutral rounded surface, binding states use green enabled and gray disabled pills in both root and revision lists; the oracle rejects missing state attributes or indistinguishable text/background colors, and authoring plus utility actions use two-column buttons with centered captions, balanced icon gutters and a soft fill without borders. The oracle measures caption centering against each button and rejects visible button borders. Command shortcuts fill the empty composer and close the menu; they never execute a command or overwrite unsent text. All settings and workbench switches use the official 36×20 capsule and 16px thumb with public theme tokens. Both checkbox pseudo-element and button/span switch thumbs are measured. The off-state oracle requires exact official geometry and token colors with a distinguishable thumb; checked states retain the contrast assertion and same-color thumb counterexample. MCP server source availability and disclosure use independent selectors with the shared Select appearance contract; browser fixtures change source availability from closed to parent rules while retaining child disclosure preferences. Capability workbench fixtures use the shared refresh component and verify explicit target selection, management-off synchronization and read-only reload separation. Per-row pick checkboxes with the first-column select-all drive the batch window in both the settings list and the session workbench; the session batch lists exactly the picked rows, stages without running commands, and keeps every action reachable at the smallest captured viewport. Scrolling the expanded mixed catalog and the revision list in both directions must leave footer geometry unchanged. Injecting a shared outer scroll container must fail the oracle; restoring the layout must pass. Actual catalog writes must retain a focused control whose center is inside the catalog clip and passes hit testing: collapsed disable, expanded enable, revision Back, and pending close/reopen are covered. Removing the reveal by resetting only the catalog scrollTop must fail this focus oracle; restoring it must pass. Page scroll and footer geometry remain unchanged. Packed official-Host acceptance repeats the mixed-catalog checks through the isolated profile and exercises actual management and settings actions.
 
 ## Limits
 
 Static DOM exports establish presentation, not live RPC, editor, switch or permission behavior; Client interaction tests and packed acceptance own those facts. Disabled presentation is sampled on supported HTML form controls; tabs, disclosures and read-only observations have no disabled/busy product state. Native tool hover remains the official DisclosureRow's responsibility and is not required to paint the plugin fallback title. Static settings/workbench fixtures use public native primitives; the shared ActionButton fallback is tested dynamically in the dock, while fallback menu/modal keyboard, portal, mask, composition and focus-return behavior remain in the same browser runner. Dynamic busy checks cover draft actions and a pending workbench catalog reload. Workbench buttons may retain full opacity when a readable status and wait cursor identify the pending request; they must still reject focus. Request sequencing remains covered by Client interaction tests.
 
-The 3:1 floor detects loss of readability and does not claim full WCAG conformance. Empty input placeholder paint and native select popups are outside this bounded text oracle. Shadow evidence is limited to contrasted solid outer rings; arbitrary blur, offset and inset effects are not accepted as proof of visible focus. No pixel baseline freezes typography, animation, every CodeMirror token, offscreen content, antialiasing, arbitrary third-party themes or future CSS properties. New controls or new state owners require updating the responsibility inventory and executable evidence. Backend coverage cannot substitute for this browser contract, and fixture success cannot substitute for official-Host delivery evidence.
+The 3:1 floor detects loss of readability and does not claim full WCAG conformance. Empty input placeholder paint is outside this bounded text oracle; the shared portaled Select popup is exercised in open and closed states. Shadow evidence is limited to contrasted solid outer rings; arbitrary blur, offset and inset effects are not accepted as proof of visible focus. No pixel baseline freezes typography, animation, every CodeMirror token, offscreen content, antialiasing, arbitrary third-party themes or future CSS properties. New controls or new state owners require updating the responsibility inventory and executable evidence. Backend coverage cannot substitute for this browser contract, and fixture success cannot substitute for official-Host delivery evidence.
 
 Draft review checks measure viewport bounds, header/body/action separation, actual control hit targets, independently scrolling source, and the enlarged reading height. Packed Host acceptance compares composer geometry and transcript extent across disclosure and enlargement; native/fallback fixtures exercise the same layout oracle.
+
+The layout and fallback inventories execute through `scripts/browser-case-runner.mjs`. Each lane owns a distinct Chromium process and page, so keyboard focus, hover, timers and fixture globals are isolated; completed results retain inventory order. Default concurrency is half of available CPUs, rounded up, bounded between one and three; multi-core runners retain at least one spare CPU. This gives three-core runners two isolated lanes to overlap rendering and input waits. A failed case stops queued work, drains active cases and closes every owned browser; cleanup failures remain visible. The complete inventories retain 168 layout combinations and 173 native/fallback scenarios, including all native/fallback, locale, theme, viewport and fault probes. `--list` and exact repeated `--case` selections support bounded diagnostics; default gate invocations select the full inventory.
+
+`node scripts/client-visual-settlement.mjs` is a short real-browser contract check, also retained in the complete visual gate. It distinguishes empty styles, asynchronous transitioncancel replacement work, pending finite animation, ignored infinite animation and explicit deadline failure.
+
+Selection-required development entries are `test:client:layout:focus` and `test:client:fallback:focus`. They reject execution without `--case` before generating fixtures or starting Chromium; `--list` remains available. An independent layout run uses `test:client:fixtures` to select the two actual-renderer export owners. The complete visual gate retains the full Client suite once and every browser case. Runners report elapsed time; focused measurements remain separate from complete evidence.
+
+
+能力工作台的单项规则显示独立的可用性与说明方式选择，默认与类别规则、常用集／统计／预算分配各有明确标签。
+窄屏下两项选择换行并保持在列表边界内；会话工作台在原生与回退 Modal 中都能逐维提交，停用不丢失说明草稿。
+聚焦浏览器的 `capability-workbench` 与 `session-capabilities` 场景使用当前组合配置和双维目录事实，验证控件可达、主题可读和维度命令读取确认；五列表头通过键盘循环三态排序且保留当前事实与草稿，短提示和统计参数直接可达。批量弹窗验证真实目标、取消不写与窄屏边界；筛选、继承规则与单项编辑同时验证独立小窗边界，观察说明验证灰色、基线对齐、自然换行和不溢出。会话能力另包含 320×420 与 1920×1080 的主题、语言及 native/fallback 组合。

package/docs/context-management.md

@@ -0,0 +1,22 @@
+# PTC Plus context management
+
+This page describes the current implementation. The [context optimization plan](context-optimization-plan.md) and [ADR 0038](adr/0038-freeze-session-capability-plans.md) own independent manual settings, family statistics, frozen session plans and explicit refresh. The [components](capability-planning-components.md) are connected to settings, public session messages and compilation preparation; the [coverage matrix](context-public-interface-coverage.md) maps these paths to executable evidence. Complete-task token savings remain unproved.
+
+PTC Plus keeps the model-facing surface divided into three layers:
+
+- stable plugin guidance and the ordered `run_code`/`edit_run_code` schema;
+- the host-owned SDK and native capability descriptions;
+- accepted-step runtime messages for recovery, binding configuration, and bounded notices.
+
+The host owns capability contracts; enabled capability management projects their disclosure through public assembly, discovery and compilation preparation. With unchanged configuration, model route, and live capability view, the plugin keeps its system section, tool schemas, and ordering byte-stable. Changing session facts are appended through the existing runtime-context owner. This preserves the host's cache boundary and prevents a recovery notice from becoming a new system prefix.
+
+Session evidence shows why the boundary matters: state reuse, edit recovery, isolated child computation, capability discovery, and rich values can work without establishing provider billing or cache savings. The [recorded A/B evaluation](evaluations/command-goat-deepseek-v4.1-flash.md) likewise showed quality and direct-error improvements in one cohort while total traffic rose, so byte reductions are not reported as token or cost savings.
+
+The current optimization policy is therefore:
+
+1. Prefer one bounded `search` request for matching complete indexed API descriptions. Its serialized UTF-8 JSON budget includes the response envelope, cursor and oversized references. Legacy `tree`, short `find` and item-budgeted `inspect` remain compatible and are not byte bounded. With capability management off, the full native SDK remains supplied. When enabled, a stable bootstrap replaces it and the frozen session plan supplies full contracts or on-demand discovery. No default state projection is injected.
+2. Keep runtime notices short, source-backed, accepted-step-only, and deduplicated so they can stop being re-emitted. Removing an already appended notice belongs to the host's surface replacement; journal ancestry and exact model-visible provenance remain the recovery authority. UI inventories and natural-language summaries do not extend hidden state.
+3. Keep parent agents, DSH child agents, and `code.run` isolated according to their existing host/runtime owners. PTC Plus does not add cross-agent memory or a second scheduler.
+4. State the value-wire boundary where it prevents a predictable model error. The stable guidance now says to return BigInt directly, avoid `JSON.stringify` for it, and never mix BigInt with `Number` arithmetic without an explicit conversion. This is a model-facing clarification; it does not change the canonical value graph or native tool JSON schemas.
+
+Future prompt experiments must compare the complete adapter-facing system text and ordered schemas, not just character counts. They must cover ordinary continuation, failed and edited cells, compaction/recovery, rich values, malformed tool JSON, capability discovery, and parent/child scopes. A candidate is acceptable only when it preserves byte stability, does not increase tool-call or serialization errors, and reports cache-read/write, uncached input, output, reasoning, retry, and exploration measurements separately. Provider cache counters are supporting evidence rather than proof of a reusable prefix.