dsh-ptc-plus 0.4.10 → 0.5.1

package/docs/adr/0043-compose-capability-and-context-policies.md

@@ -0,0 +1,37 @@
+# 0043 Compose Capability and Context Policies
+
+## Status
+
+Accepted. Extends ADR 0038 and ADR 0040 for newly created environments.
+
+## Context
+
+A single full/on-demand/closed choice loses disclosure preferences when disabled, while a management switch also selects recovery and previews. Users need to compose those responsibilities without inheriting unrelated changes.
+
+## Decision
+
+`capabilityContextEnabled` is the persistent group selection. Turning it off pauses capability rules, statistics collection, explanation recovery and plugin previews together, without overwriting their independent saved choices, rules, budgets or retained observations. Turning it on restores that combination. The default is true for compatibility; it does not opt into any child feature. The group delegates Host capability and presentation behavior while paused and does not change computation, canonical values or DSH authority. `effectiveCapabilitySettings` owns the pure derivation from retained intent to applied settings; configuration libraries and frozen source copies retain the original inputs.
+
+Capability availability and disclosure are separate inputs. A `ptc-capability-policy/v1` policy contains `defaults`, `categories`, `mcpServers`, `items` and `allocation`. Rules contain independently optional `availability` (`enabled` or `closed`) and `disclosure` (`host`, `full`, `on-demand` or `adaptive`). Defaults contain both dimensions. Category, proven MCP server and item rules override defaults in that order, independently for each dimension. An MCP server closure is an enclosing removal and wins over child enablement without deleting child preferences. Ambiguous server ownership cannot establish closure. Nonempty unresolved item identities remain removable configuration inputs; only actual managed inventory can give them effect.
+
+`host` retains the existing PTC owner-provided explanation path for available members. `full` supplies complete contracts, `on-demand` retains bounded discovery, and `adaptive` permits allocation. Only adaptive choices consume the independently selected `allocation.baseline`, `allocation.statistics` and `allocation.budget` inputs. No allocation closes a capability. Explicit full contracts remain complete even when over budget. The policy applies only when capability management is selected; it never replaces DSH authority or the PTC code-only direct-tool projection.
+
+Statistics collection uses `capabilityStatistics.enabled`; consuming those observations uses `allocation.statistics`. Either may be selected independently, and read-only observation requires neither. Collection without management derives eligibility from the actual live public inventory, including Host additions and withdrawals, never an empty disabled plan. Allocation may consume retained valid observations after collection stops. Host disclosure is recorded as such, not relabeled as on-demand. Existing family settlement, admission, revision and workspace evidence rules continue to apply.
+
+`capabilityRecoveryEnabled` independently selects bounded recovery of recently used, expanded, currently valid API explanations after compaction. It does not control necessary navigation, contract withdrawal or environment change notices. It never restores Skill bodies or changes binding provenance. `modelPreviewEnabled` independently selects the plugin's result and log presentation budget. Unselected presentation delegates to the Host, preserving any existing Host policy, canonical values and execution outcomes.
+
+Fresh settings retain host disclosure and do not select statistics allocation, explanation recovery or plugin previews. Migration of an older saved configuration preserves its former choices, including adaptive disclosure and management-coupled recovery/previews. Named configurations store all these reusable inputs atomically, never observations or session state.
+
+New sessions record `ptc-capability-environment/v4` and `ptc-capability-plan/v3`, including the group selection, source settings, independent temporary overrides and effective derivation. Even a paused group records its frozen selection through the accepted plan message. Existing environment v1/v2/v3 and plan v1/v2 snapshots retain their original planner and rendering; v1/v2 environments retain their coupled behavior and v3 its independent selections. Current defaults never reinterpret them. Unknown or generation-inconsistent selections fail evidence validation. Saved settings do not change active sessions until explicit refresh. Dimension-specific session choices can remove only their saved dimension (`automatic`) or resume the frozen source (`inherit`); neither changes unrelated preferences. Existing combined commands retain their documented meaning.
+
+## Alternatives considered
+
+**Add more booleans around the combined choice.** Downstream switches cannot recover the disclosure preference that the combined representation discarded. Independent dimensions preserve that information at its owner.
+
+**Split the feature into capability control and context optimization modes.** Each mode still bundles statistics, allocation, recovery and presentation. Structured responsibilities allow useful combinations without another mutually exclusive mode state.
+
+**Reinterpret existing snapshots with current defaults.** That would change frozen environments and recovery semantics. A new recorded generation retains exact validation for historical plans.
+
+## Consequences
+
+The same rule resolver owns planner inputs, configuration inspection and all available-member consumers. Presentation may retain host contracts for one subset while using complete or on-demand contracts for others; shared owner instructions must remain wherever a retained member needs them. Operational inventory is required by selected management, collection or recovery, not by the presence of a policy generation. All unselected features and preview alone delegate the Host inventory lifecycle. In managed environments, Skill native eligibility remains recorded separately from effective invocation paths: removing the model loader preserves an independent user invocation. Resource contracts list only their available selected operations. Absence of every invocation path derives unavailability independently of management selection, without deleting preferences; it cannot establish statistics eligibility. Unselected policy closures never remove an actual Host path. Configuration controls expose dimensions and precedence rather than mutually exclusive feature modes. Combination support does not establish task quality or token savings.

package/docs/adr/0044-coexist-with-the-official-persistent-repl.md

@@ -0,0 +1,35 @@
+# Coexist With The Official Persistent REPL
+
+## Problem
+
+DSH added an opt-in official Node execution mode (`executionMode: persistent-in-memory`) that retains a confined REPL per Agent, and extended the `ptcRuntime` seam with `PtcRunRequest.stateOwner`, `PtcRuntime.programFormat` and `PtcRuntime.release(owner)`. The host `run_code` consumer registers `runtime.release(agent)` at Agent disposal for every provider, passes `stateOwner` on requests, and program-format consumers (the workflow adapter, cua) wrap programs according to `programFormat`. PTC Plus owns the same seam: without a policy, its provider surface lacked the new members so Agent disposal could fail, non-session consumers could not see the format of the provider that actually executes their programs, and an explicitly enabled official mode stayed silently inert for session cells while the plugin kept owning them.
+
+## Decision
+
+`internal/execution-seam-compat.js` and `internal/execution-provider-owner.js` forward `programFormat` to the live original generation and `release(owner)` to the originals that served that owner. These describe the provider that actually performs an execution: owner-keyed retained environments and the executed source format belong to the original, which still serves non-session consumers while the plugin owns session cells, and a bounded generation that lacks the members falls back to `'function-body'` and a resolved no-op. Execution retirement does not retire cleanup: the composition retains weak owner-to-original provenance for dispatched `stateOwner` programs, so Agent cleanup through a captured adapter still reaches a surviving original after bundle removal or source replacement. Successful cleanup removes that original from the owner's pending set; failed cleanup remains available for explicit retry, with synchronous and asynchronous failures observable. An owner without recorded dispatch delegates to the live original, or receives a resolved no-op if execution is unavailable. `executionInstructions`, `sandboxMode` and `timeout` keep their existing withholding policy while PTC Plus owns session execution, because those describe the session kernel ([ADR 0028](0028-attach-to-the-host-ptc-execution-seam.md)).
+
+`officialReplPriority` (default `false`, State and recovery) selects who owns PTC session execution when the official persistent REPL is live. The decision reads the live capability — `provider.programFormat === 'repl'` — rather than a release number, and is re-evaluated on every configuration and host source change. Execution ownership is an attachment shape: `owned` installs the session runtime, `deferred` installs `internal/official-repl-priority.js`'s runtime record, which owns no execution resources and answers the attachment contract with empty contexts. Changing the shape retires the current attachment, disposing its live kernels, and installs the other shape before later cells; no committed cell mixes the two contracts. While deferred, `run_code` and its descriptors stay with the official provider and the plugin's REPL guidance, session-state semantics, recovery, editor tool, capability SDK, REPL observation and binding workbench are suspended with the attachment, while the settings card, enablement and stored global bindings stay available so the switch can be reversed.
+
+Cells executed under the official mode produce no plugin journal records. They are an unrecorded execution interval: recovery never replays them, and they do not extend plugin state as recovery evidence.
+
+## Alternatives considered
+
+**Gate on the DSH release or on reading the original row's `executionMode` configuration.** The mode is a live runtime capability and a configuration fact outside the plugin's public contract; `programFormat` is the provider-owned proof that a REPL actually retains state, and it degrades safely on older generations that lack it.
+
+**Keep owning execution unconditionally and only add the missing seam members.** That repairs disposal, but it silently ignores an explicit official mode, cannot honor a user's choice to run the official semantics, and keeps two competing REPL contracts alive for the same session surface.
+
+**Suspend execution in place inside the installed runtime.** Toggling individual owners (prompt, tool bridge, plans, projections) mixes the two execution contracts in one attachment and creates states no single owner can prove; the installation shape is the granularity the plugin already uses for language retirement.
+
+**Keep management owners (global binding workbench, capability workbench) outside the deferred attachment.** Splitting the management surface from the execution runtime is a larger refactor that would change ownership for every state, not only deferral; it remains possible future work instead of being smuggled into this decision.
+
+**Forward `release(owner)` only while delegating execution.** Non-session consumers keep running through the original provider even while PTC Plus owns session cells, so owner-keyed environments can exist in every state; a delegation-only forward would leave those environments unreleased and the registered provider contract incomplete.
+
+## Consequences
+
+Agent disposal on the current official host releases cleanly, and both the format and the owner release reach the generation that owns the environment.
+
+Leaving plugin ownership disposes its live kernels, and plugin-mode state contraction follows the existing disposal rules. Official in-memory state belongs to DSH's Agent/provider lifecycle and may remain available when priority is switched back to the official provider; the deferred attachment does not clear it. State built during an official interlude is never replayed or claimed by the plugin. After returning to plugin ownership, the session continues from plugin-verifiable evidence only.
+
+Deferred mode intentionally reduces the plugin's computation surface (no REPL guidance, session semantics, recovery, editor, capability SDK, REPL observation or binding workbench for that attachment); the setting copy and README state this so the user's choice is informed.
+
+The plugin keeps withholding `sandboxMode` while it owns execution, so deployments that require file confinement still need another PTC execution environment — unchanged by this decision, and now also visible in the workflow adapter's explicit refusal.

package/docs/adr/README.md

@@ -16,3 +16,11 @@ This directory records stable design constraints for PTC Plus. An ADR states a d
   - `## Consequences` — what the trade-off cost and bought; older entries may carry `## Verification` instead or omit it
 - **Supersession.** When a later decision replaces an ADR, fold every unique rationale, alternative, and consequence into the current owner and repair inbound links before deleting the old file. Partial supersession keeps both files cross-linked. Git history is not the only copy of rationale.
 - **Kept current.** When the code later moves a file, renames a surface, or changes a default, update the owning ADR in the same change (facts only, not the decision itself).
+
+- [0041: Record Cell Execution Directories](0041-record-cell-execution-directories.md) — current execution, captured module sources and historical replay use distinct directory evidence.
+
+- [0042: Persist Provider Availability And Handback](0042-persist-provider-availability-and-handback.md) — accepted-step availability, public persistent release and separately sourced configuration receipts.
+
+- [0043: Compose Capability and Context Policies](0043-compose-capability-and-context-policies.md) — independent availability, disclosure, allocation, collection, recovery and presentation inputs with historical replay generations.
+
+- [0044: Coexist With The Official Persistent REPL](0044-coexist-with-the-official-persistent-repl.md) — forwarded owner release and program format, plus live-capability ownership selection between PTC Plus and the official persistent REPL.

package/docs/architecture.md

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

package/docs/capability-planning-components.md

@@ -0,0 +1,93 @@
+# 能力方案与统计组件
+
+本文描述方案、统计及其会话接入。独立组合规则由 [ADR 0043](adr/0043-compose-capability-and-context-policies.md) 拥有，冻结与权限边界由 [ADR 0038](adr/0038-freeze-session-capability-plans.md) 拥有，执行证据见[覆盖矩阵](context-public-interface-coverage.md)。`internal/capability-environment.js` 将纯方案用于首轮目录、冻结环境、编译前成员投影、刷新和恢复；`internal/capability-statistics-store.js` 将真实家族事实接入锁定的原子存储。
+
+## 方案计算
+
+`internal/capability-plan.js` 导出 `createCapabilityPlan(input)`，有 `contextEnabled` 输入时返回递归冻结的 `ptc-capability-plan/v3`，记录整体选择及有效管理状态；缺省该维度时，有 `policy` 输入使用 `v2`，否则使用 `v1`，保留历史精确校验。
+
+| 输入 | 契约 |
+| --- | --- |
+| `contextEnabled` | 整组是否选用；false 通过 `effectiveCapabilitySettings` 暂停管理、采集、恢复和预览，不改写独立保存输入 |
+| `enabled`、`configurationRevision` | 独立管理开关和配置修订；关闭时条目选择为 `host`，不修改宿主 |
+| `capabilities` | owner 提供的准确 `{id, revision, category, contract, dependencies?}`；依赖为 `{id, text}` |
+| `policy` | `ptc-capability-policy/v1`：默认、类别、MCP 来源、单项分别保存 availability 与 disclosure，allocation 分别选择 baseline/statistics/budget；见下文 |
+| `manual` | 可编辑的 `baseline: string[]`；历史输入的 `overrides: { [id]: "full" \| "on-demand" \| "closed" }`；显式项始终优先 |
+| `statistics` | `enabled` 控制采集而非分配；正整数 `windowSize`、`minimumSamples` 和 `[0,1]` 范围的 `fullThreshold` |
+| `coverage` | 按准确能力 ID 索引的 `{revision, workspace, global}`；覆盖证据形状由下述归约组件提供 |
+| `budgetBytes`、`directoryBudgetBytes`、`navigationText` | 完整契约和目录分别按 UTF-8 字节计量；固定发现指引必须在目录预算内 |
+
+`internal/capability-policy.js` 统一校验和解析可复用规则。`defaults` 必须同时包含 `availability: enabled|closed` 和 `disclosure: host|full|on-demand|adaptive`；`categories`、`mcpServers`、`items` 可分别覆盖其中一个维度。默认 → 类别 → 已证明 MCP 来源 → 单项按维度覆盖；MCP 来源关闭是外层移除，优先于子项启用，但不删除子项偏好。每个派生条目保留两项原意、各自来源和兼容的有效 `selection`，关闭时仍保留 disclosure。未解析的非空单项 ID 保留为可撤销输入，只有真实受管库存使规则生效。管理关闭时所有实际能力沿用 host；未选用的关闭规则不参与库存过滤或归属诊断。
+
+`host` 保留已有 PTC 提供方说明路径；纯启停不会让其余能力变成按需。共享说明只在没有沿用宿主的消费者时移除，SDK 仅保留 host 披露的可用工具与始终可调用的编辑传输成员（`edit_run_code` 不属于管理域，每次渲染都保留其宿主签名）；全体仍为 host 时保留原 SDK。Skill 全部沿用时保留宿主目录；混合披露时完整保留 host Skill 的目录说明并隐藏按需说明，不加载正文。按需项始终可获取完整契约。v3 另外区分 Skill 原生准入与有效调用路径：关闭模型 loader 不关闭独立用户入口；无可用入口时派生不可用而保留偏好，管理关闭也不将缺失入口计入实际供给或统计资格；未选用的关闭偏好不参与该事实。MCP 资源契约只列实际可用且未关闭的操作。全部功能未选用或只使用预览时不强制读取能力库存。
+
+只有 adaptive 项消费 `allocation.baseline`、`allocation.statistics` 和 `allocation.budget`；关闭预算约束时允许全部选中的分配候选，仍计量正文与超额。显式 full 不因任一预算选择被降级或截断。统计采集由 `capabilityStatistics.enabled` 单独拥有，不取决于管理或分配是否选用；管理关闭时从公共 live inventory 取得真实资格，记录 host 披露；Host 增删沿真实 live inventory 更新统计资格，不变更冻结配置。停止采集后仍可选用留存有效证据。只读观察既不采集也不需要启用统计分配。
+
+配置格式与纯方案组件接受 `tool`、`skill`、`resource`、`resource-template`、`task` 五类。当前宿主库存仅产出 `tool`、`skill`、`resource`，定义由 `internal/capability-policy.js` 的 `CAPABILITY_INVENTORY_CATEGORIES` 统一供库存与类别控件消费。MCP 资源与模板共用每个服务器的 `resource` 条目；没有独立模板或任务库存，执行任务的 SDK 工具仍归 `tool`。设置仅显示这三类，但保存和历史方案仍保留五类契约；`language`、`node`、`repl`、`ptc-plus`、`global-binding` 保持范围外。适配器必须提供真实来源身份和完整契约；本组件不从工具名字猜测来源，也不加载 Skill 正文。Skill 库存、完整契约、检索与设置来源元数据保留 owner 的 `modelInvocable`/`userInvocable`：模型可调用项说明 `tools.skill({name})`，用户专用项说明 `/name` 用户入口；两者关闭的项不进入可用目录。披露不能扩大加载权限。
+
+adaptive 选择统计依据时，统计不足可回退到已选用的基线；工作区样本足够时优先采用，工作区不足时才参考全局，不将重叠家族相加。无效设置或不可用证据不撤销手动选择。纯描述或 schema 的修订继承尚未由公共适配器证明，因此当前不同 `revision` 隔离。
+
+排序综合覆盖率和契约长度，采用确定性的 ID 裁决。预算计入实际 `catalogText` 的标题、完整契约、分隔和去重后的公共依赖。显式完整条目可超预算，`budgets.overageBytes` 明确报告；自动项不截断契约。存在按需项时，目录保留固定检索指引，在独立预算内提供输入库存中非关闭能力类别的简短用途导航（纯组件支持工具、Skill、MCP 资源/模板及任务；当前宿主接入前三类），不复制单项完整描述或按 ID 抽取长尾条目。存在按需项时，完整或按需分配变化不改变目录结构；未逐项列名的能力仍可通过检索发现。冲突的共享依赖不能合并成一个貌似完整的契约。
+
+完整契约依次排列显式完整、已选基线、其余自动完整三组，组内按 ID 排列；每组先放尚未提供的共享依赖，全目录仅提供一次。统计用于分配，不用于重排已选条目。目录先于完整契约，使统计分配变化尽量保留导航与显式完整契约前缀。统计数字、配置 digest 和会话身份仅在来源元数据中，不进入说明正文。目录只承担用途发现，完整 owner 描述由完整披露或实际检索提供。
+
+输出还包含每项选择及原因、统计范围与样本数、未解析的配置 ID、范围外集合和字节计量。这里的字节不是模型 token；设置页显示方案和预算，任务收益仍须独立校准。没有推荐列表或数字被伪装成实际使用。
+
+## 家族统计归约
+
+`internal/capability-statistics.js` 导出：
+
+```js
+createCapabilityStatistics({ windowSize, maxFamilies, maxScopes, maxCapabilitiesPerFamily })
+reduceCapabilityStatistics(state, familyObservation)
+validateCapabilityStatistics(state)
+capabilityCoverage(state, { userId, workspaceId, id, revision })
+```
+
+输入事实为 `type: "family-observation"`，包含真实 `userId`、`familyId`、单调 `observationRevision`、`settlement`、不可变 `eligibleOrder` 和累计 `observations`。结算状态为 `active`、`settled` 或 `unknown`；只有已结算且具有正整数资格序号的家族可用于分配。适配器必须证明资格，不能把 root idle 或缺少后代用量当成家族结束。
+
+每个可用观察包含 `workspaceId`、能力 `id/revision/category`、当时的 `disclosure` 和 `planRevision`；只允许真实可用的 `host`、`full` 或 `on-demand`，关闭和未提供项不能进入分母。使用证据分别为工具/任务的 `host-execution-result`、Skill 的 `skill-body-accepted`、资源/模板的 `resource-access`。查询、cold replay 和权限阻止的请求不接受为使用证据。工具使用表示真实调用进入 DSH 的 around execution 管线并获得正式规范结果（包括失败和合法 wrapper 提供的结果）；不证明注册 body 或外部效果执行。失败或已准入的取消结果独立保留，明确的 dispatch 前取消、未知工具及未准入调用不算使用。
+
+同一家族、能力、范围只贡献一个使用位。工作区观察和全局观察分别归约，跨工作区后代不增加全局权重。每项能力和范围使用最近 N 个合格家族；续接修改已有身份的使用事实，不改变原资格顺序。正在运行或结算未知的家族不形成负样本。淘汰前沿阻止旧观察重读后重新进入已有窗口；不使用自然时间衰减。
+
+`capabilityCoverage` 返回样本量、使用量、窗口和覆盖率；没有可用样本时覆盖率为 `null`。尚无任何相关记录时状态为 `no-samples`，窗口内已有记录但家族当前未结算时状态为 `pending-settlement`，两者样本量、使用量和覆盖率均为 `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