dsh-ptc-plus 0.4.8 → 0.5.0

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,53 +1,88 @@
 # Client UI
 
-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` 视图分别渲染一句描述与完整表单。输入框旁的星光菜单还直接打开复用同一表单的应用内设置窗口，不依赖宿主页面的局部导航状态；菜单项悬浮提示保留原生设置座位的路径。
+标准 `verify`、`check` 的完整验证分支与 CI 的 `verify:ci` 均执行 `test:client:visual`，在一次 Client 测试生成的实际 renderer 夹具上检查关键控件的尺寸、可读性、悬停、键盘焦点、禁用反馈及布局。浏览器准备、覆盖清单、故障反例与官方宿主验收边界见 [Client visual contract](client-visual-contract.md)。
 
-Client 根入口只依赖 `slots`、`locale`、`connection` 和 `remote`；settings transport 由当前代的 `configForms` 或上一代的 `settingsScope` 可选注入提供。头部贡献直接消费公开 session slot 提供的 `useProjection`；REPL 注册另依赖 `sessions` 的当前选择和 projection face。命令卡片等待公开 command slot，composer 管理入口直接消费现有管理 Remote；其中的编写动作再等待 `remote.commands` 与公开输入 hooks，不依赖已改名的 conversation registry 或未使用的 `ui-session` 模块。缺失、卸载或迟到的 slot/provider 只影响需要它的贡献；没有 `useProjection` 时不挂载依赖它的会话视图，命令卡片保留宿主结果但不提供草稿操作。没有输入 hooks 时不显示编写动作，已有全局绑定仍可查看和启停。preset 优先读取 `agentPreset` projection，缺失时依次读取会话公开摘要里的 projection 值与旧宿主的 `agentPreset` 字段；binding 值和草稿资格不采用该回退。当前会话身份取宿主已发布的选中证据：旧代际在会话列表上投影 `current`，当前代际把视图选择留在 controller 之外、以主视图持有的会话表达。两者都不读取私有 store。设置和独立正文 tool view 继续可用，不读取私有 store 或自行重建会话状态。
+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` 视图分别渲染一句描述与完整表单。输入框旁的星光菜单还直接打开复用同一表单的应用内设置窗口，不依赖宿主页面的局部导航状态；菜单项悬浮提示保留原生设置座位的路径。
+
+Client 根入口只依赖 `slots`、`locale`、`connection` 和 `remote`；settings transport 由当前代的 `configForms` 或更早未冻结兼容支的 `settingsScope` 可选注入提供，两者都缺席时不再等待某个名字出现：插件以 `internal/config-spec.js` 的默认值参与订阅，transport 出现时自动接管，因此改名或裁剪设置传输只会降级设置面，不会让根入口在注册任何贡献之前挂起。功能资格只被显式关闭：可读快照按字段判定，不可读快照按同一份默认值判定，`enabled: false` 才关闭。头部贡献直接消费公开 session slot 提供的 `useProjection`；REPL 注册另依赖 `sessions` 的当前选择和 projection face。命令卡片等待公开 command slot，composer 管理入口直接消费现有管理 Remote；其中的编写动作再等待 `remote.commands` 与公开输入 hooks，不依赖已改名的 conversation registry 或未使用的 `ui-session` 模块。缺失、卸载或迟到的 slot/provider 只影响需要它的贡献；没有 `useProjection` 时不挂载依赖它的会话视图，命令卡片保留宿主结果但不提供草稿操作。没有输入 hooks 时不显示编写动作，已有全局绑定仍可查看和启停。preset 优先读取 `agentPreset` projection，缺失时依次读取会话公开摘要里的 projection 值与旧宿主的 `agentPreset` 字段；binding 值和草稿资格不采用该回退。当前会话身份取宿主已发布的选中证据：更早未冻结的选择形状在会话列表上投影 `current`，当前代际把视图选择留在 controller 之外、以主视图持有的会话表达。两者都不读取私有 store。设置和独立正文 tool view 继续可用，不读取私有 store 或自行重建会话状态。
 
 组件通过 renderer 提供的 `useProjection`、旧宿主的公开 `useSessions` 和注入 `hooks` 读取外部状态，设置写入与 RPC 由 apply 层注入 callback。业务组件不自行构造 external-store hook。设置、slot、provider 与插件释放共同拥有注册和订阅的生命周期；开关关闭时撤销相关贡献。
 
+设置 transport 各自拥有 injection registration 和订阅，即使两者返回同一个 preference face 也不共享释放身份。`configForms` 优先，仍存活的 `settingsScope` 保持备用；优先项移除后读写回到备用项，不以默认开启覆盖其显式关闭值。移除备用项不得撤销当前项，插件释放回收所有订阅。
+
 REPL 对 composer 的接管优先使用当前公开 `sessionId`/`pendingInteraction` 参数；旧宿主仅在 `session.sessionId` 匹配且 `interactions` 为空数组时允许接管。审批、提问和无法确认的交互状态继续显示宿主 composer，不通过 DOM 隐藏输入框。
 
-这些新旧接口差异由 `src/client-host-compat.js` 集中处理：组件使用 `useSessionPreset`，注册层使用 `watchCurrentSessionPreset` 跟随当前会话及其 projection，并用 `isIdleSessionComposer` 判断 composer 资格。适配模块负责证据优先级与订阅切换、释放；`src/client.js` 负责设置开关、PTC 功能资格和 slot 生命周期。当前会话变化时重新读取公共能力，不缓存全局宿主版本或会话能力。
+冻结 Host 图只证明当前成员；更早回退的 fixture 证据和误删后果见[安装：兼容证据](installation.md#compatibility-evidence)。这些接口形状差异由 `src/client-host-compat.js` 集中处理：组件使用 `useSessionPreset`，注册层使用 `watchCurrentSessionPreset` 跟随当前会话及其 projection，并用 `isIdleSessionComposer` 判断 composer 资格。适配模块负责证据优先级与订阅切换、释放；`src/client.js` 负责设置开关、PTC 功能资格和 slot 生命周期。当前会话变化时重新读取公共能力，不缓存全局宿主版本或会话能力。
+
+Client 按数据、传输、注册与视图分文件，沿用既有 `createX(React, deps)` 工厂：`src/client-copy.js` 拥有双语字典，`src/client-styles.js` 拥有样式数据、样式表的 DSH 归属（创建时即写 `data-plugin`/`data-plugin-css`，因此不会被后物化的插件认领，也不会随别的插件被删除）以及对依赖方挂载的全局样式表（CodeMirror 的 style-mod）的收编，`src/client-primitives.js` 拥有“宿主 primitive → 可用组件”的唯一解析与缺失兜底，`src/client-rpc.js` 与 `src/client-transport.js` 拥有 Remote 调用和观察传输，`src/client-feature-gates.js` 拥有“设置快照 → 功能资格”的唯一映射与受门控注册，`src/client-catalog.js` 拥有全局目录读取，`src/client-workbench.js` 拥有工作台状态迁移与视图，`src/client-settings-view.js`、`src/client-tool-view.js`、`src/client-repl-view.js`、`src/client-authoring-view.js`、`src/client-indicator-view.js` 各自拥有一个 slot 的视图。`src/client.js` 只做装配与注册，不持有业务状态。设置快照到功能布尔只有一个纯函数（`featureEnabled`），受门控贡献共用一个“订阅 → 判定 → 注册/注销 → 回滚”实现（`registerGated`）；preset、projection 和公共能力仍由各自 owner 判定，在调用点与设置资格组合。
+
+## 缺失组件回退
 
-Client 按数据、传输、注册与视图分文件，沿用既有 `createX(React, deps)` 工厂：`src/client-copy.js` 与 `src/client-styles.js` 拥有双语字典和样式数据，`src/client-rpc.js` 与 `src/client-transport.js` 拥有 Remote 调用和观察传输，`src/client-feature-gates.js` 拥有“设置快照 → 功能资格”的唯一映射与受门控注册，`src/client-catalog.js` 拥有全局目录读取，`src/client-workbench.js` 拥有工作台状态迁移与视图，`src/client-settings-view.js`、`src/client-tool-view.js`、`src/client-repl-view.js`、`src/client-authoring-view.js`、`src/client-indicator-view.js` 各自拥有一个 slot 的视图。`src/client.js` 只做装配与注册，不持有业务状态。设置快照到功能布尔只有一个纯函数（`featureEnabled`），受门控贡献共用一个“订阅 → 判定 → 注册/注销 → 回滚”实现（`registerGated`）；preset、projection 和公共能力仍由各自 owner 判定，在调用点与设置资格组合。
+回退菜单和弹窗的输入法 guard 覆盖 compositionstart 到 compositionend 后的 closing key；该 key 被消费或 keyup/window blur 释放后，独立普通 Escape 才能关闭。每次按下 Escape 只关闭一层，repeat 事件仍被消费但不再次关闭外层弹窗。该边界与原生 primitive 的生命周期一致，保留尚未保存的草稿。
+
+缺失 primitive 包或 `Menu.children` 时，插件自有菜单保留入口的正常布局，列表通过 React DOM 基线 portal 到 `document.body`，只用公开 `getAnchorRect` 与 viewport 为自己的列表定位和限制高度。自有 Modal 的普通与 `headless` 模式共用 portal、mask 和焦点层；`headless` 只移除默认标题与正文装饰，不取消模态遮罩。`npm run test:client:fallback` 在隔离 Chromium fixture 中验证小视口菜单操作、背景 pointer 阻挡与关闭后的焦点返回；它不替代 packed Host 的完整浏览器验证。
 
 ## 设置命名空间
 
-Host half 通过 DSH 公共 `settings` 服务注册命名空间 `ptc-plus`。字段清单、默认值和校验来自 `internal/config-spec.js`，
-由 `index.js` 的 `Config` schema 与设置注册共用；client half 构建时把同一份字段清单打进 bundle，不在 UI 中复制默认值。`CONFIG_GROUPS` 独立拥有按用途排列的展示顺序：插件总开关单独置顶，其后为“调用容错”“REPL 语法”“状态与恢复”“工具扩展”“界面显示”“资源限制”。每个字段只展示一次，各组使用独立标题、留白与分隔线。
+当前 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_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 工作台
 
-`/binding new` 和 `/binding edit` 的历史命令处保留原始需求、状态和错误说明。候选被接受后，完整源码、模型上下文与保存/启用/丢弃操作由官方 `conversation.input.dock` 在当前输入框上方承载；历史条目只提供该请求自己的只读来源。面板通过 dock 内的零高度锚点悬浮在整个普通输入区上方，不顶高正文或宿主遮罩；默认展开，正文内部滚动。整条标题按钮支持点击与 Enter/Space，箭头随折叠状态变化；输入框只保留一个星光入口：首轮前即可通过官方 Menu 悬停、点击或键盘查看全局绑定、切换启停及打开完整工作台；设置条目直接打开复用设置卡片表单的应用内窗口，关闭后将焦点还给仍可用的星光按钮；编写命令可用时显示“编写新绑定”，并在同一个 Menu 内提供“修改绑定”第二步来选择已有条目。该入口与头部标识、REPL 页签同属 PTC surface：只在当前会话使用 `ptc` 或兼容 `code` preset 时注册，其他 preset 既不显示入口也不读取该会话的命令目录。该入口以插件署名提示说明来源与用途，有草稿时改为提示待处理草稿。有草稿时显示数量角标，草稿在独立分组中选择。当前 Host 每会话只保留一份候选，菜单不列出过期历史；隐藏编写快捷入口或命令服务缺席不影响已有草稿的访问。关闭和重新打开只改变展示，不撤销候选或待决 RPC。保存或丢弃确认成功后面板自动关闭；失败和结果待确认时保持用户的显隐选择。候选身份、写资格和异步结算由一个 Client review controller 复用 draft projection 与现有 RPC owner，页头不再提供第二套当前写操作。实现细节与验收证据见[Binding 审阅位置设计](binding-review-placement-design.md)。
+`/binding new` 和 `/binding edit` 的历史命令处保留原始需求、状态和错误说明。候选被接受后，完整源码、模型上下文与保存/启用/丢弃操作由官方 `conversation.input.dock` 在当前输入框上方承载；历史条目只提供该请求自己的只读来源。公开 dock 内的零高度自有锚点定位 Portal 内的 fixed 悬浮预览，避免宿主裁切与层叠覆盖；只在预览可见时跟踪自有锚点和 visualViewport 的几何变化，可用高度不足时收为标题栏，仍可放大审阅，不测量或改写宿主祖先与滚动容器；展开和折叠不改变对话或输入框高度。该贡献排在普通 dock 内容之前，预览向上展开。放大通过公共 Modal 或既有回退弹窗承载同一个候选内容与操作区；正文独立滚动，标题与底栏保持可达，Escape、遮罩或独立缩小按钮返回预览，关闭按钮则隐藏面板；尺寸切换和关闭按钮之间留有间距。弹窗只在当前输入入口可见时显示，宿主接管时隐藏并保留展示选择。整条标题按钮支持点击与 Enter/Space，箭头随折叠状态变化；菜单条目与焦点恢复只操作插件自有内容节点，定位由公开 Menu 的 anchor/getAnchorRect/portal 契约承担；没有 children 的历史 primitive 使用自有菜单兜底。设置窗口的初始焦点使用 `data-modal-autofocus`，焦点回环交给 Modal；没有 composer 焦点接口时返回自有入口，不寻找宿主编辑器。输入框只保留一个星光入口：首轮前即可通过官方 Menu 悬停、点击或键盘查看全局绑定、切换启停及打开完整工作台；设置条目直接打开复用设置卡片表单的应用内窗口，关闭后将焦点还给仍可用的星光按钮；编写命令可用时显示“编写新绑定”，并在同一个 Menu 内提供“修改绑定”第二步来选择已有条目。该入口与头部标识、REPL 页签同属 PTC surface：只在当前会话使用 `ptc` 或兼容 `code` preset 时注册，其他 preset 既不显示入口也不读取该会话的命令目录。该入口以插件署名提示说明来源与用途，有草稿时改为提示待处理草稿。有草稿时显示数量角标，草稿在独立分组中选择。当前 Host 每会话只保留一份候选，菜单不列出过期历史；隐藏编写快捷入口或命令服务缺席不影响已有草稿的访问。关闭和重新打开只改变展示，不撤销候选或待决 RPC。保存或丢弃确认成功后面板自动关闭；失败和结果待确认时保持用户的显隐选择。候选身份、写资格和异步结算由一个 Client review controller 复用 draft projection 与现有 RPC owner，页头不再提供第二套当前写操作。实现细节与验收证据见[Binding 审阅位置设计](binding-review-placement-design.md)。
 
 `userBindingsEnabled` 关闭时不渲染任何 Global User Binding 管理界面，Host 也不注册对应 RPC 或 Agent 命令。开启后，REPL 页签中的“全局绑定”和设置管理按钮打开的大尺寸应用内弹窗复用同一个 `UserBindingsWorkbench`。设置卡片保留开关与管理按钮，不嵌入编辑器。普通管理不依赖当前存在 PTC 会话；Agent 辅助编写仍使用当前可用会话的 `/binding` 入口。
 
@@ -81,7 +116,9 @@ PTC session 的头部弹窗在功能启用时增加 Session 与 Global 页签。
 
 `enhancedToolView` 默认开启并即时生效。开启时 PTC Plus 通过公共 keyed tool-view surface 为 `run_code` 与 `edit_run_code` 提供增强行，并在可用时使用 DSH 公共 `DisclosureRow`/`CodeBlock` primitive，缺少某项 capability 时使用插件自有的等价降级；关闭时立即注销这两个 keyed view，由 DSH 原生 generic row 负责布局、状态、代码高亮和输入/输出卡片。该开关只影响 Client 展示，不改变工具、prompt、runtime 或 session 语义。composer 星光入口使用公共 `Menu`、`Tooltip`、`Toast`、`Modal` 和 `IconSparkle16`；设置窗口复用设置卡片的完整表单与写入 callback，星光菜单的“修改绑定”第二步继续使用同一公共 `Menu` 的条目、滚动与键盘语义。缺失 `IconSparkle16` 时降级为纯文本按钮，缺失 `Toast` 时使用插件自有的内联状态提示；缺失 `Tooltip` 时悬浮说明由原生 `title` 承载。
 
-星光入口的四个动作（编写新绑定、修改绑定、管理全局绑定、PTC Plus 设置）始终由插件自己的动作区承载——`Agent 编写` 分组标题加两列网格，再一行工具入口——而不是宿主的列表行。该动作区优先放进公共 `Menu` 的 `children` 区域。这个区域不是所有已发布 Client 都会渲染的输入：较早的实现接受 `children` 属性却不挂载任何节点。`src/client-host-compat.js` 因此以已挂载输出而不是版本号判定该契约：首个 composer 入口挂载时渲染一次隐藏、非 portal 的 `Menu`，读取其中是否出现插件自己的哨兵子节点，随后在同一次提交内丢弃探测；答案在单个 Client 生命周期内只记录第一次结果，后续会话入口复用该答案、不再渲染探测。未渲染 `children` 时插件不把“未回答”当作结论，也不退化成宿主行：同一份动作区改由该 `Menu` 一向渲染的 pinned 区域承载（入口类型为 label，内容仍是插件自己的网格），因此分组、分组分隔线、两列布局、文案、顺序和设置座位提示在所有代际一致；渲染 `children` 的 Client 不再追加 pinned 副本，避免同一动作出现两次。pinned 载体只抵消自身的外边距和上边框，避免与宿主 footer 的 hairline 叠成两条；分组分隔线位于 `Agent 编写` 网格与工具入口之间，不会与它重复。已发布的 Client 至少渲染 pinned 区域；两处都不渲染的代际没有可承载这四个动作的宿主插槽，插件不以自有浮层替换宿主菜单，也不因此伪造宿主能力。探测挂载失败时不记录任何结论，入口保持原有渲染路径。
+星光菜单的自有内容根拥有 13px/18px 基础字号与行高，停用组标题和绑定名称使用 13px，说明使用 12px、启停状态使用 11px；通过 portal 挂载后也不继承宿主的字号与行高。长名称和说明保留单行省略及完整 `title`。星光菜单通过公开 `Menu.children` 将目录滚动区与不收缩的底部操作区分开；只有目录滚动，四个操作和修改步骤的“返回”保持可见。启用条目优先显示，启用与停用标题带数量，停用组每次打开默认折叠；折叠行不渲染。启停后焦点跟随同一条目，条目进入折叠停用组时返回该组按钮，菜单关闭或外部已有焦点时不抢焦点。菜单实际获取和离开焦点的事件拥有恢复资格，待决请求期间关闭再重开也遵循当前资格；初次打开、步骤切换和归组恢复共用自有目录内的焦点显示操作，只调整该目录的 `scrollTop`，不调用祖先 `scrollIntoView`。短视口隐藏底栏的编写文字标题，保留分组的可访问名称和按钮。星光入口的四个动作（编写新绑定、修改绑定、管理全局绑定、PTC Plus 设置）由插件自己的动作区承载：`Agent 编写` 分组标题、两列网格及工具入口。公开 `Menu` 能挂载 `children` 时，该动作区放入其 `children`；缺少 Menu primitive 或已确认不挂载 `children` 时，同一份动作区交给 `src/client-primitives.js` 的自有 `MenuFallback`。列表通过 React DOM portal 呈现，以公开 `getAnchorRect` 和视口预算定位，保留分组、文案、顺序、设置座位提示与可用操作。
+
+`src/client-host-compat.js` 以实际挂载输出判定 `children` 能力：首个 composer 入口在隐藏、非 portal 的 Menu 中放入插件自己的哨兵子节点，读取后丢弃探测。答案只记录一次，后续会话入口复用；未挂载或探测失败时不记录能力结论。该探测只读取插件创建的节点，fallback 的定位、滚动与焦点也由自有节点承担，具体边界见前述 primitive 降级契约。
 
 悬浮窗里的条目启停不改变列表的可用性：写入由 catalog source 串行化、重复请求被丢弃，因此请求期间行不会被禁用（宿主会给禁用行降透明度）也不会插入“正在保存”行，避免整个悬浮窗在每次切换时闪一下；只有尚无目录可操作或读取失败时行才不可用。
 
@@ -95,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 承担并保持可访问。预览间距由插件自有类对称提供，并按单行内容布局，不依赖 Host primitive 的行内几何；源码、结果和 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 事实，因此不根据可复制的代码形状、工具名前缀或设置默认值推测；恢复边界本身不展示。
 
@@ -125,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)。
 
@@ -143,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

@@ -0,0 +1,65 @@
+# Client visual contract
+
+The Client must expose readable, distinguishable and reachable computation controls. DOM classes and functioning RPC handlers do not establish that obligation. `scripts/client-visual-contract.mjs` owns a bounded browser oracle used by deterministic fixtures and packed official-Host acceptance. This is a usability contract, not a pixel snapshot of DSH.
+
+## Gate and prerequisites
+
+Install the lockfile dependencies and the matching Playwright browser before verification:
+
+```sh
+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`, 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
+
+All fixture families exercise light and dark reference palettes, English and Chinese, and widths 320, 390 and 1440 px. Reference tokens deliberately exercise both foreground polarities; they do not claim to reproduce official or customized themes. The separate model-free packed acceptance uses DSH's public theme settings on an unmodified official Host, reuses the oracle for dock actions and the global workbench, and retains its existing actual editor, permission, session-log and layout assertions.
+
+| Surface | Actual controls | Visual states and evidence |
+| --- | --- | --- |
+| 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; 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 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 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, 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. 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 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.