dsh-ptc-plus 0.2.1

package/docs/adr/0017-track-the-latest-dsh-public-surface.md

@@ -0,0 +1,23 @@
+# Track The Latest DSH Public Surface
+
+## Problem
+
+PTC Plus integrates with DSH services, request bindings, prompt assembly, session events, and CLI/profile installation through public extension surfaces. A literal compatibility version can become stale independently of those contracts, misrepresent newer releases as unsupported, and defer integration failures until maintainers manually update a label.
+
+## Decision
+
+The compatibility target is the latest available DSH release. Production behavior, configuration, tests, installation guidance, and current compatibility claims depend on public extension contracts and observed live schemas, never on a DSH version allowlist or comparison. An upstream default projection is not an extension ceiling: when public scoped registration and presentation support a plugin-owned capability, PTC Plus preserves that capability and its model-visible identity instead of deleting or renaming it to match the default. Deterministic normalization remains valid for a call that is outside the declared direct surface when the live schema proves one native target and the lowering preserves arguments, call identity, authority, and result semantics. Deterministic tests exercise the consumed contracts; model-backed and packaging acceptance runners use the installed DSH and record `dsh --version` in generated reports so failures remain attributable without turning the observed value into policy. Concrete DSH release numbers may appear only in source comments that identify historical integration or evaluation evidence and cannot influence execution or acceptance.
+
+## Alternatives considered
+
+**Pin one verified DSH release.** A pin makes one historical environment reproducible but turns normal upstream progress into an artificial incompatibility and allows the implementation to drift from the release users actually install.
+
+**Maintain a supported-version range.** A range communicates broader intent, but semver cannot prove compatibility with evolving extension contracts. Maintaining the range duplicates evidence already produced by contract and end-to-end tests while still requiring every new release to be evaluated.
+
+**Treat the upstream default tool projection as an immutable plugin limit.** This avoids scoped presentation work, but discards capabilities that the public registry supports and can force valid model calls through lossy aliases. Defaults describe the host's built-in product choice; public extension contracts define what a plugin may add. Invalid out-of-surface calls may still be normalized when their intended native target is provable.
+
+**Silently accept any installed version without recording it.** This avoids a gate but weakens failure attribution and benchmark reproducibility. Recording the observed version in generated acceptance output preserves evidence without coupling behavior to it.
+
+## Consequences
+
+Each upstream DSH release becomes the immediate compatibility target and must pass the public-surface, packaging, and model-backed checks appropriate to the change. Users are not blocked by stale version metadata. Historical reports remain attributable through generated runtime metadata or source comments, while a passing older run never substitutes for validation against the latest release.

package/docs/adr/0018-use-versioned-fixture-for-ab-benchmark.md

@@ -0,0 +1,25 @@
+# Use A Versioned Fixture For The Ordinary-Task A/B Benchmark
+
+## Problem
+
+The ordinary-task A/B benchmark previously copied the active PTC Plus checkout into each arm. The workload therefore changed whenever the plugin repository grew, making absolute machine budgets and longitudinal comparisons unstable. The same source tree was also serving as the host, the treatment-under-test workspace, and the measurement workload, which mixes unrelated variables into one measurement.
+
+## Decision
+
+The primary ordinary-task A/B workload is now a purpose-built, versioned, zero-dependency Node.js fixture in `fixtures/ab-node-project-v1`. The fixture manifest is the single owner of the fixture name, version, content SHA-256, deterministic Git identity/commit, and deterministic dirty state. The runner materializes the fixture independently into each arm workspace, initializes the same deterministic Git history, applies the same uncommitted changes, and never copies the active PTC Plus checkout as the model workload.
+
+The A/B task set contains a fixed, cheap, machine-checkable canary that exercises `run_code` before the full paired matrix starts. Reports record the fixture path, version, and content hash so future runs are grouped by benchmark version. The current PTC Plus checkout is kept as a separate self-hosting acceptance surface; it is not the stable README headline benchmark.
+
+## Alternatives considered
+
+**Keep freezing the active PTC Plus checkout.** This preserved a single running workload but made the measurement scale track repository growth and precluded stable cross-version comparisons.
+
+**Use a fixed snapshot of the DSH source tree.** This would decouple from plugin growth but remains a large, host-domain-coupled workload and would not isolate the fixture from DSH evolution.
+
+**Synchronize fixture facts across the runner and task descriptors.** This spreads the version and content ownership across files and creates a drift hazard; the manifest is the single explicit owner instead.
+
+**Continue using a blind-only canary.** This would make preflight depend on semantic review and spend quota before machine transport facts are known; the cheap machine-checkable canary stops an invalid build before paid work expands.
+
+## Consequences
+
+The benchmark workload is stable under unrelated PTC Plus source changes and has its own result series tied to `fixtureVersion` and content hash. Existing README totals from the checkout-based series are explicitly non-comparable to the new fixture series. Maintaining a benchmark now requires updating the fixture manifest together with the fixture content, and a materially different task set or fixture change starts a new series rather than reusing old totals.

package/docs/adr/0019-plugin-settings-and-kill-switch.md

@@ -0,0 +1,32 @@
+# 0019 Plugin Settings UI and Enabled Kill Switch
+
+Date: 2026-05-21 (source snapshot `dsh-v0.1.1-rc.2`)
+
+## Status
+
+Accepted
+
+## Context
+
+PTC Plus 0.1.0 deliberately had no Client UI. The runtime surface was the DSH PTC mode `run_code`/`edit_run_code` transport, and adding a settings bundle was judged not to improve the core REPL path. The plugin also lacked a user-facing way to disable its runtime without removing the Cordis entry, and enabling/disabling state was invisible outside the session log. The operator now wants a plugin settings UI containing every Host Config field, a kill switch, and an explicit enabled marker. `dsh-element-inspector` demonstrates the supported DSH pattern: Host registers a settings namespace and the browser half contributes a card into `settings.plugin.item`. `deepseek-harness-rc2` defines the settings service, client `settingsScope`, and the slot contract.
+
+## Decision
+
+PTC Plus registers one DSH settings namespace `ptc-plus` with the same field list, defaults and validation as the Host Config schema. The field definitions live once in `internal/config-spec.js`; `index.js` builds the Cordis Config schema from it, and the esbuild client bundle imports the same module so the UI does not copy defaults or validation.
+
+The configurable set is the Host runtime configuration plus `enabled: boolean` (default true). `enabled` is the kill switch: when false the Host registers only the settings namespace and keeps the client card available; it does not install the runtime bridge, edit transport, direct-surface owner, system prompt section, tool registrations or session hooks. When true the same runtime as pre-settings PTC Plus is installed. Every field is live when its owner can reconcile it: the Host observes the settings scope and installs, uninstalls, or reconfigures owners without replacing existing session-bound bindings. Node fixes a worker's V8 `maxOldGenerationSizeMb` limit at construction, so changing that field while a session worker is active is rejected and the settings provider is restored to the previous value; other reconfiguration failures use the same compensation path. The TypeScript language check occurs at activation, allowing disabled settings to load on a host using another code runtime while rejecting and rolling back an enable attempt. If the settings service is absent, the Host falls back to composition config and enables the runtime.
+
+Enabled state is visible in the settings card as “已启用/已停用”. The collapsed card header also identifies the session-level TypeScript REPL and exposes an accessible expand/collapse label. When enabled for a session using the `code` preset, the Client separately shows a `PTC Plus` header indicator. Stable REPL guidance remains protocol text without UI branding. The tool names remain `run_code`/`edit_run_code`; we do not rename DSH-owned transport names.
+
+Runtime activation is transactional. If a live enable cannot complete, every owner acquired before the failing setup step is disposed, the failure is logged, and the settings provider is asked to persist `enabled: false`; a failed compensating write remains an explicit activation diagnostic rather than an unreported state mismatch.
+
+## Alternatives Considered
+
+1. Keep no Client UI. Rejected: the operator explicitly needs a settings surface and a kill switch. Away from settings, users cannot tell whether PTC Plus is actively installed because the only marker is application behavior.
+2. Rely on DSH generic schema rendering without a `settings.plugin.item` card. Rejected: the generic tab renders only namespace cards supplied through the slot; shipping no card would leave the namespace invisible even though the schema is registered.
+3. Rename the `run_code` tool or use a schema/name-level UI alias. Rejected: PTC Plus must preserve the DSH host tool names and their public pipeline semantics; presentation labels belong in Client-owned UI, not in transport identity or model-visible stable text.
+4. Keep non-`enabled` fields restart-applied. Rejected: a settings UI that persists values without changing the active runtime is misleading. Runtime owners now accept live configuration updates; session kernels keep their bindings while applying new limits and policies to subsequent cells.
+
+## Consequences
+
+The package gains a browser bundle (`src/client.js` → `client.js`), `dsh.client` metadata, a `./client` export and the `@deepseek-ai/dsh-settings` dependency. Host tests must cover the settings-disabled path and the live toggle path. Bundle loading follows DSH's public injected module and slot contracts; it does not advertise a literal DSH compatibility floor. Missing settings service degrades to the previous behavior instead of failing the plugin.

package/docs/adr/0020-optional-cordis-tools-in-ptc-mode.md

@@ -0,0 +1,36 @@
+# 0020 Optional Cordis Tools in PTC Mode
+
+Date: 2026-08-24
+
+## Status
+
+Accepted
+
+## Context
+
+DSH's shipped 创造模式 composes `@deepseek-ai/dsh-tool-cordis` and the `cordis-plugin-development` companion Skill into its native `cordis` preset. PTC users may also need that complete official authoring workflow without leaving PTC mode, but adding it unconditionally would enlarge a high-authority tool surface and add stable schema/prompt cost to every request. PTC Plus must not copy DSH's Cordis implementation or Skill content, or turn this choice into another preset system.
+
+Tool registration must finish before the prompt assembly returned to the agent; otherwise the first request lacks Cordis schemas and guidance. DSH's synchronous `agent/created` lifecycle and agent context provide the publication point and owner, but child-fiber readiness can still overlap the first provider snapshot.
+
+## Decision
+
+Add `cordisToolsEnabled: boolean`, default `false`, as a live PTC Plus setting. When enabled, PTC Plus mounts the official `@deepseek-ai/dsh-tool-cordis` plugin and a maintained `@deepseek-ai/dsh-skill-filesystem` provider in each agent scope that exposes `run_code`; disabling it disposes both fibers immediately. The provider resolves the shipped `cordis` preset through the public `agentPresets` service and publishes only its sibling `skills` directory under a PTC Plus-specific provider name. It neither switches the current preset nor includes default roots. If an agent is created before `run_code` becomes visible, the owner retains it as pending and retries on the DSH tools-change signal.
+
+The Skill provider and official Cordis child fiber form one reversible mount. Both must settle, and the scoped `skills` service must prove that `cordis-plugin-development` resolves from the added provider as model-invocable and loadable, before the first prompt assembly is returned. A prepended public `system-prompt/assemble` waterfall listener is the final race barrier: if collection began before the mount settled, it waits for readiness, discards that stale assembly, and invokes public assembly again so DSH recollects the official providers. It does not synthesize or mutate Cordis schemas or guidance. The Cordis fiber's resolved `inject` declaration is the authoritative required-service list, and its live registrations are the authoritative tool names, schemas, and guidance. A missing or broken preset, Skill service/tool, declared service, publication, or child fiber is a configuration error and rolls back every contribution.
+
+The official plugin also registers Host inspect providers in the process-global `cordisInspect` service. Per-agent fibers therefore acquire owner-scoped leases for identical provider manifests instead of registering the same provider ID independently. Queries delegate to a registration from a still-live official fiber, and the process-global provider is removed when the final lease is released. A manifest mismatch remains a configuration error rather than silently choosing one contract.
+
+Cordis tools remain native program bindings under `tools.*`. The PTC code-only direct-tool projection remains exactly `[run_code, edit_run_code]`; native agents and unrelated scopes do not inherit this option.
+
+## Alternatives Considered
+
+1. Add the Cordis row to the PTC preset. Rejected: PTC Plus is installed as a host plugin and does not own or fork DSH's shipped preset files; the operator asked for a plugin setting.
+2. Register Cordis tools during `system-prompt/assemble` and continue with the existing assembly. Rejected: provider and schema collection has already happened, so waiting alone would still omit the tools. The selected barrier instead discards that stale snapshot and asks DSH's public assembler to recollect after the owner-controlled mount is ready.
+3. Copy the tool definitions or their current names. Rejected: DSH owns their schemas, guidance, lifecycle, authority, and compatibility. Even a names-only completeness list would drift when DSH evolves and create a second contract.
+4. Enable the tools by default. Rejected: the tools can execute model-written plugins against the live runtime and carry a fixed schema cost. That trust and context expansion must be explicit.
+5. Mount one global Cordis tool fiber and hide it from native agents. Rejected: its prompt hook and `@pluginId` context listener would remain global even if tool schemas were restricted, so unrelated agents would inherit behavior they did not enable.
+6. Copy `SKILL.md` into PTC Plus or add the Cordis preset's directory to global Skill roots. Rejected: copied instructions drift, while a global root leaks the optional workflow into agents that did not enable it.
+
+## Consequences
+
+PTC Plus declares the maintained DSH Cordis tool, Skill filesystem, settings, and tool-runtime packages as required peers through the current release channel and mirrors them in development dependencies. They resolve from DSH's installation-maintained profile fallback; installing PTC Plus must not add a profile-local DSH core package instance. When enabled, the official Cordis schemas, guidance, and companion Skill become available together in PTC agent scopes; disabled configurations remain unchanged. Changing this option updates live agent scopes without a DSH restart, including repeated disable/re-enable cycles. A DSH release may rename or reshape its Cordis surface without requiring a mirrored-name change in PTC Plus, provided the public plugin, preset, Skill, and inspect-provider contracts remain compatible.

package/docs/adr/0021-separate-host-bootstrap-from-session-runtime.md

@@ -0,0 +1,68 @@
+# Separate Host Bootstrap From Session Runtime
+
+## Problem
+
+PTC Plus needs to distinguish host-level work from the session-bound REPL. The
+current entry point installs tool, prompt, worker, and journal behavior in an
+agent/session scope. Moving that entry point earlier in the DSH composition
+would make those owners global and could break binding, authority, and cleanup
+boundaries.
+
+An external reference, [DSH-EasyRewrite](https://github.com/Renzic-Stone/DSH-EasyRewrite),
+shows a useful public extension pattern: a host entry point is mounted through
+`cordis.patch.yml`, while a separate client entry point consumes browser slots
+and session/workspace APIs. That project does not, however, intercept
+`sessionPersistence` or migrate raw session artifacts before restore.
+
+## Decision
+
+Keep the existing PTC Plus entry point as the agent/session runtime owner. If a
+host-level integration is needed later, add a narrow, separate bootstrap entry
+point for host configuration, diagnostics, and an upstream-provided restore
+preflight contract. The bootstrap must not create a second workspace/session
+coordinator, duplicate DSH authority, or move worker and binding state out of
+the session scope.
+
+The plugin may consume a DSH public restore-preflight migrator or an atomic raw
+artifact rewrite API when one exists. Until then, PTC Plus must not rewrite
+files obtained from private storage paths or race the persistence provider's
+append/flush queue. Legacy `ptc-plus/recovery-boundary` artifacts therefore
+remain an explicit, startup-before-restore migration concern rather than a
+runtime event handler concern.
+
+The EasyRewrite host/client split is an architectural reference only; its
+session and workspace UI APIs are not a persistence recovery mechanism.
+
+## Alternatives considered
+
+**Move the whole plugin earlier in the composition.** This would expose the
+runtime before its required agent/session services and could turn isolated
+workers, bindings, and hooks into shared state.
+
+**Load a child plugin from the current entry point.** A Cordis child plugin is
+loaded after its parent, so it cannot provide an earlier persistence hook.
+
+**Rewrite raw artifacts directly from a host plugin.** DSH currently exposes
+raw reads but not a public replacement operation. Direct path mutation depends
+on private storage layout and can conflict with active persistence writes.
+
+**Treat one failed session as a plugin-owned workspace failure.** DSH owns the
+workspace registry and session lifecycle. PTC Plus must not replicate that
+coordination layer; per-session load isolation belongs in the DSH persistence
+contract.
+
+## Consequences
+
+The runtime remains correctly scoped and EasyRewrite's public host/client
+assembly pattern remains available for future UI or host features. A plugin
+update alone cannot repair an already-running DSH process that has failed while
+loading legacy artifacts; the process must be stopped and the artifacts
+migrated before restore. Existing valid sessions are unaffected by the
+migration, while malformed legacy artifacts must fail closed and remain
+diagnosable.
+
+The long-term upstream requirement is one of: a restore-preflight migration
+hook, an atomic raw-artifact rewrite API, or a contract that isolates one bad
+session from workspace registry initialization. None of these is emulated by
+PTC Plus in the absence of a public DSH extension point.
+

package/docs/adr/README.md

@@ -0,0 +1,18 @@
+# Architecture Decision Records
+
+This directory records stable design constraints for PTC Plus. An ADR states a decision, the problem it answers, the alternatives it rejected, and the consequences it accepts.
+
+## Rules
+
+- **A new or changed durable decision updates or adds an ADR** in the same change. Record architecture, public or cross-module contracts, persisted or wire formats, and process or tooling choices that a maintainer may reasonably revisit. A difficult or non-trivial implementation of an existing decision does not by itself require an ADR.
+- **`## Alternatives considered` is mandatory.** Name each genuine alternative and why it lost, one bold-led paragraph per alternative. A decision recorded without what it beat invites re-litigation.
+- **Naming.** Files follow `NNNN-kebab-case-title.md`. Keep the number sequence monotonic; never reuse a number.
+- **Format.** One physical line per paragraph:
+  - `# <title>` — the decision in one line
+  - `## Problem` — the motivation, written to stand without the solution
+  - `## Decision` — shipped reality in the present tense; keep it current with what actually shipped
+  - bespoke technical sections as needed
+  - `## Alternatives considered` — mandatory
+  - `## Consequences` — what the trade-off cost and bought
+- **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).

package/docs/architecture.md

@@ -0,0 +1,134 @@
+# Architecture
+
+PTC Plus 把 DSH PTC 模式的顶层 `run_code` 变成与 session 绑定的连续 TypeScript REPL。它负责 cell 求值、binding continuity、诊断、journal 和 cold replay；权限、sandbox、工具调度、取消、审批和跨平台进程治理仍属于 DSH 与操作系统。
+
+## 运行边界
+
+| 层 | 所有者 | PTC Plus 的工作 |
+| --- | --- | --- |
+| Authority / policy | DSH / 宿主 | 不复制；每次 native tool dispatch 仍经过原流水线 |
+| Capability view | DSH 当前 scope | 保留 native typed `tools.*`，为一个 cell 建立统一 lease |
+| Evaluation | session worker | 连续求值、顶层 binding、预算与输出编码 |
+| Journal / replay | PTC Plus + session log | 记录 call transcript、settlement、completion 和恢复边界 |
+| Presentation | DSH + PTC Plus | 保留 native guidance，并追加 REPL 指引与最小 explorer 声明 |
+
+主入口接管模型直接发起的顶层 `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`、`code` 或 `both`。首次 assembly 的非空 `tools:code-only` section text 证明 `code`，同名空 section 证明 `both`；只有缺少该 owner signal 时才能从 tool shape 推断。后续 assembly 不重新解释插件自己的 `tools.presentAs('both')` 效果，而是从 agent composition owner 派生 presentation。`code` 独占 direct-tool collapse、顶层 native-call normalization 和 native dispatch rejection；`both` 保留 native direct tools。`code` 与 `both` 都适配 PTC `run_code` schema、program SDK 和 session runtime contexts，只有 `code` 安装并直接执行 `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` 之一。`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` 单次前向扫描 session events，分别投影最新执行、可编辑目标、rewrite metadata 和恢复 tip
+所需事实。`edit_run_code` 不产生专用 runtime context：真实 call/result 已完整表达操作身份和结果，额外 contribution
+只会触发 DSH 聚合 runtime-context 全量快照并重复无关 policy 文本。只有失败或完成状态不可信的 rewrite feedback 才保留独立生命周期；成功的透明改写不产生 runtime context。
+
+插件卸载时恢复仍由自己持有的 `CodeRuntime.run` 与 `presentationMeta` 属性；若外层插件仍持有旧 wrapper，已卸载 wrapper 会透明委托原 provider，不会恢复已释放的 session 状态。
+稳定 REPL 指引说明 cell 是 async function body、module 使用 dynamic import 或 require，并要求显式
+return 或打印需要展示的值。失败恢复先按状态分类：解析或 preflight 失败且 `state: unchanged`、无外部效果证据时，
+禁止重发完整源码，优先使用 `edit_run_code` 做精确修正并重放完整 cell；`state: partially-applied` 或可能已有外部 effect 时新建短
+`run_code` 并复用已有 binding，完整重写只保留给结构性改动或超出编辑预算的修正。能力和命令执行依赖当前 request
+与 execution world，模型必须先探查 live binding、实际 executable 和路径语义，不假设某个平台、shell 或 package runner。
+
+稳定指引保留这些跨任务不变量和失败恢复的优先动作。长 cell 失败的短提示直接作为当前 `PTC-X001` 的结构化 `help` 输出，避免一次性建议触发完整 runtime-context 快照；重复绑定失败和当前 execution world 中由诊断确认的 executable、shell 或 path 错误仍由当前 session log 派生为 `tools:ptc-plus-tip/<trigger>/<ordinal>` runtime context，分别提示能力探查或重新确认环境。投影只接受 DSH system-prompt owner 的规范快照，并按命名 section 的有效状态变化重建提示；聚合快照重复同一 section 不增加次数，正文不参与身份判断。
+相同提示受 `tipCooldownMessages` 间隔约束，连续未解决时才升级为详细版本，成功 cell 会重置未解决计数；提示不会改变
+system sections、tool schema 或 tool order，也不假设 Windows、WSL、POSIX、shell 或 package runner。
+
+当前策略位于独立的 `internal/recovery-tips.js` local provider，核心只消费其有界的 named context。未来外部决策插件的接入必须等待稳定的 facts/decision contract；在此之前不猜测跨插件 API，local provider 继续作为 fallback。
+
+## 设置与启用开关
+
+Host half 通过 DSH 公共 settings 服务注册 `ptc-plus` 命名空间，字段清单、默认值与校验来自 `internal/config-spec.js`。
+Client half 通过 `settings.plugin.item` 卡片呈现全部配置。`enabled` 是 kill switch：关闭时只保留 settings 注册和设置卡片，
+不注册 runtime、hook、tool surface 或 system prompt section；设置卡片显示“已启用/已停用”，`code` preset 会话在头部单独显示 `PTC Plus` 指示器。稳定指引不包含 UI 品牌名。
+所有字段都由 settings watch 即时交给各自 owner，且不替换已有 session-bound binding。每个已提交 cell 固定其提交时的配置代际，timer、worker 消息、program binding bridge、结果校验和诊断共同消费该快照；重配置更新随后提交 cell 的默认值。`maxOldGenerationSizeMb` 在活动 worker 存在时因 Node 的创建期限制而拒绝并回滚。settings 服务缺失时 Host 回退到 composition config，原有行为不变。
+
+`cordisToolsEnabled` 默认关闭且即时生效。Host 只在可见 `run_code` 的 agent scope 中挂载官方 `@deepseek-ai/dsh-tool-cordis`，并通过公共 `agentPresets` service 定位 shipped `cordis` preset，再用维护中的 Skill filesystem plugin 把其 companion Skill 目录发布到同一 scope。两个 child fiber、tool guidance 与 `cordis-plugin-development` Skill 是一个 mount；首轮 request 等待完整发布和 scoped Skill load 验证，关闭、agent/runtime 释放或任一激活失败时逆序卸载。工具名、数量、schema 和 guidance 直接来自 official tool fiber，Skill 内容直接来自 shipped preset，Host 均不复制。官方插件同时向 process-global `cordisInspect` 注册 Host provider；owner 将 manifest 相同的 per-agent 注册合并为引用计数 lease，查询委托给当前仍存活的官方 registration，最后一份 lease 释放后才注销 provider。manifest 不一致时启用失败。该开关不切换 preset，也不改变 code-only direct-tool projection。
+
+## Prompt 前缀稳定性
+
+对当前 DSH 公共扩展面的集成，模型 request 由重复的 system prompt、完整有序 tool schemas 和从 session log 派生的消息历史组成。缓存契约按变化位置分类，而不以某次 provider 是否命中作为判断依据：
+
+| 类型 | 本项目约束 |
+| --- | --- |
+| Stable repeated prefix | 插件配置、模型 route 与 native capability view 不变时，插件拥有的 system text、schema 内容和 tool order 在每次 request 中保持字节一致。 |
+| Append-only growth | tool call/result、诊断和动态 runtime context 只追加到已保留历史之后，不修改 `request/header` 或更早的消息。 |
+| Replacement | 只有 DSH 拥有的 compaction 或其他显式 surface replacement 可以替换已保留历史；PTC Plus 不用 replacement 表达瞬时状态。 |
+| Independent request | 新的辅助模型调用必须单独说明 route、prefix 和 token 影响，不能用它的缓存表现证明主会话前缀稳定。当前插件不发起辅助模型请求。 |
+
+一次性或会变化的 session 状态必须作为 `PromptAssembly.contexts` 的命名贡献交给 DSH。DSH 将完整快照记录为带来源的 `user/message` 并追加到历史尾部；值未变时不重复，值变化或全部消失时追加更新或 clearance。完整快照携带当时所有 owner 的命名 context，因此任一贡献变化都会使未变化贡献在新的尾部消息中再次出现；这会增加 append-only history token，但不会改写已有前缀。PTC Plus 不通过绕过 prompt assembly 的私有消息通道规避这项宿主聚合成本。此类状态不得进入 `PromptAssembly.sections`，也不得通过增删 tool、改变 schema 字段或调整 tool order 传递。
+
+所有模型可见输入都必须能从 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 起失效。
+
+缓存稳定性必须有 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.run` 共享 cell lease；cell 结束后，捕获的函数统一失效。调用时仍由 DSH 检查 scope、policy、取消和 scheduler。
+
+`capabilities.tree/find/inspect` 是描述 API，不是反射调用入口。默认 SDK 只展开这个导航器；`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 成为执行事实；能力在两阶段之间变化时，不伪造原子快照保证。
+
+CodeRuntime request 已携带的 owner-provided program namespace 会被原样保留并共享 cell lease，PTC Plus 不翻译其参数或结果。与插件保留的 `capabilities`、`code` 或 `repl` 同名时 request fail-fast，避免主线程与 worker 绑定分叉；普通 cell 局部变量允许自然 shadow 这三个低频 namespace，必要时可通过 `globalThis` 访问。`tools` 仍是保留名称，因为 shadow 它会切断主要能力面。当前公共扩展面没有用于发现额外服务的 program-binding registry；插件不提供名称分发总线或私有 provider registry。若 DSH 以后提供统一 registry，PTC Plus 只消费实际 request 中的 live binding，不复制 authority 或 discovery。
+
+## REPL 生命周期
+
+每个顶层 `run_code` 是同一 session kernel 的下一格。顶层 binding 跨 cell 保留；默认宽松模式允许一个完整 declarator 全部替换已有变量，严格模式拒绝重声明，关闭 `autoSplitRedeclarations` 时混合新旧名称的解构也在执行前拒绝。cell 始终作为 async function body 求值，支持 block scope、top-level `await` 和普通控制流 return；return lowering 通过顶层 `this` receiver 访问每个 cell 独立生成并在 settlement 清理的 worker-global signal property，因此 lexical `globalThis` 与 `with` object environment 都不能重定向控制流。worker 启动时验证该 receiver 指向 evaluator 的 global context。跨 cell 重声明是 REPL 便利策略，由 `internal/repl-convenience.js` 独立实现；它不是 cell 语言或原生 JavaScript 语义的组成部分。
+
+包裹前的 AST 重写适配模块语法（cell 是 async function body，模块声明在函数体内非法）：全部默认开启且可用 config 关闭（`autoRewriteImports` / `autoStripExports` / `autoSplitRedeclarations`）。原始 Babel Program 在任何 lowering 或 preload 前完成 scope validation；同一 cell 的 value import 与 lexical、hoisted `var`、function 或其他 import 重名会按模块 binding 规则拒绝，block shadow 和 type-only 名称仍合法。静态 `import` 声明产生有序 module preload record；worker 通过短生命周期 ESM adapter 让 Node 从 session cwd 完成解析和 export linkage，再在 cell 编译前通过生成的临时 global identifier 把 namespace 交给另一个持久 lexical identifier。两者都避开当前源码、持久 binding、program binding 与活跃 private namespace，生成的 prologue 直接引用临时 identifier，因此 lexical `globalThis` shadowing 不参与 host capture；临时 global 在 cell settlement 清理。session 未记录 cwd 时，解析基准回退到 worker process cwd；目标模块的依赖保持各自的自然 parent。scope-aware alias lowering 保留 named/default binding 的 live read、只读、shadowing 和跨 cell 重放语义。value import alias 活跃时，原始 Program 上的 direct `eval` 与 `WithStatement` 在任何 preload record 生效前拒绝，因为生成的 namespace property read 无法复现它们的动态 lexical resolution；没有 value alias 的非严格 `with`、type-only import 和局部 shadow 的 `eval` 仍使用普通 JavaScript 语义。顶层 `export` 修饰符剥离（声明保留、`export default` 转为 `__default` 绑定、re-export 转为预加载的副作用模块、type-only export 擦除）；REPL 便利层在 `autoSplitRedeclarations` 开启时按插件定义的兼容规则 lowering 混合新旧名称的顶层解构，关闭时保持原文走既有解析失败路径。无法精确适配的形态在执行前拒绝。改写来源以 `meta.dshPtcPlusRewrites` 平行记录（journal schema 封闭）。成功改写不改变下一步决策，因此不产生 runtime context；改写后失败或缺少有效 journal 时，`tools:ptc-plus-rewrite-info` 才在下一轮说明恢复边界。
+
+可确定的计算和 recorded-value capability call 可以推进 durable head。未进入 journal 的 Node/OS 能力、环境输入、时钟、随机数和 timer 进入 sticky `volatile`；live worker 继续可用，cold replay 回到最后 durable frontier。`require(...)` 与动态导入按同一白名单分类：白名单内置模块（assert/buffer/querystring/string_decoder/stream/util/url/zlib）保持 durable，其余 volatile，`worker_threads`/`cluster` 等内核控制模块在执行前以 PTC-C002 拒绝。durable 只描述冷恢复对已结算历史的重放能力；失败 cell 仍可能已经修改 binding 或产生外部 effect，不能由 durability 推导出安全重试。worker thread 是生命周期隔离，不是安全沙箱。
+
+宿主工具调用经 worker 回调回到主线程时，DSH 的 AsyncLocalStorage initiator 上下文在回调中为空。插件注入 `agents` 服务并在 `invokeBinding` 处用 `withInitiator(精确活跃 agent, ...)` 建立边界，因此要求 driver 内精确调用 agent 的宿主工具（如 goal 跟踪的 `goalToolExecution` 检查）可从 cell 内直接调用；`edit_run_code` 的派生 `run_code` 也复用该宿主流水线，不通过 stream canonicalizer 伪造模型调用。
+
+## Journal 与恢复
+
+每个进入 evaluator 的 cell 写入版本化 journal：
+
+```ts
+{
+  version: 3,
+  bindingMode: "loose" | "strict",
+  rewritePolicy: { autoRewriteImports, autoStripExports, autoSplitRedeclarations },
+  status: "durable" | "volatile" | "discarded" | "noop",
+  calls: CallTranscript[],
+  operations: StateOperation[],
+  confirms: number[],
+  diagnostics: Diagnostic[],
+  completion?: Completion,
+  volatileReason?: string
+}
+```
+
+`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`，不按名称分支。若基础设施终止时仍有未结算 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` 做两阶段确认。缺失、损坏或被替换的 journal 形成 unknown/volatile 边界；未进入 runtime 的 call 由后续 `confirms` 以对应 `tool/call.seq` 证明为 no-op。volatile 源码保留在原 session log，但不参与 cold replay。
+
+durable replay 无法验证某个 node 时，当前已结算 `tool/result` 的私有 `meta.dshPtcPlusRecoveryBoundaries` 记录失败 call 与其 parent frontier，不修改冻结的历史 result。boundary 在进入排序前必须完成 schema 与 event-sequence validation；损坏 metadata 使恢复 fail closed，不能从 fold 中静默消失。折叠器剪除该 node 及依赖后代、重算可重建 checkpoints；kernel 重置 worker 并逐级验证更早 frontier，随后执行当前 live cell。新 durable node 的 parent 始终是 worker 实际拥有的 frontier。旧版自定义 boundary event 不由运行时生成，迁移工具必须在 DSH restore 前显式转换它。
+
+诊断由封闭结构确定性渲染，包括语法、preflight、绑定冲突、输出、运行异常和恢复边界。普通成功与首次进入 volatile 不投影 warning/note；恢复分类保留在 journal 和 `repl.state(list)` 中。
+
+更详细的结果边界见 [Program Data Plane](program-data-plane.md)，能力元数据见 [Capability Surface](capability-projection.md)，恢复协议见 [Durable / Volatile](durability-design.md)。
+
+## Decisions
+
+- [Delegate Governance to DSH](adr/0001-delegate-governance-to-dsh.md)
+- [Limit Work Map Scope](adr/0002-limit-work-map-scope.md)
+- [Prefer Native Program Surfaces](adr/0003-prefer-native-program-surfaces.md)
+- [Declare Program Bindings At The Owner](adr/0004-declare-program-bindings-at-the-host.md)
+- [Register Edit And Run As A Truthful Composite Tool](adr/0005-temporary-rejected-cell-edit-transport.md)
+- [Track The Latest DSH Public Surface](adr/0017-track-the-latest-dsh-public-surface.md)
+- [Plugin Settings UI and Enabled Kill Switch](adr/0019-plugin-settings-and-kill-switch.md)
+- [Optional Cordis Tools in PTC Mode](adr/0020-optional-cordis-tools-in-ptc-mode.md)
+- [Separate Host Bootstrap From Session Runtime](adr/0021-separate-host-bootstrap-from-session-runtime.md)

package/docs/capability-projection.md

@@ -0,0 +1,48 @@
+# Capability Surface
+
+PTC Plus 保留 DSH 原生 typed `tools.*`，不建立工具名称特例层、参数适配表或反射调用总线。`danger-full-access` 是一等体验；其他 profile 只暴露当前 DSH request 实际拥有的能力，缺少的能力不由插件模拟。
+
+## Native tools
+
+工具参数、canonical result、错误、policy、取消和调度语义均由 DSH owner contract 决定。PTC Plus 只为每个 cell 包一层统一 lease，并把 call 的 args/result 与 settlement 写入 journal。captured member 在 cell 结束后失效，不能绕过下一次 scope/policy 检查。
+
+`canonical` 只表示交给程序的结构化值，不表示完整世界快照。结果完整性分为：
+
+| 类别 | 含义 |
+| --- | --- |
+| `complete` | 对契约声明范围完整 |
+| `bounded` | 明确窗口、预算或上限 |
+| `incremental` | 自上次读取后的增量或消费结果 |
+| `open-world` | 来源空间不可穷尽，只表示当前查询 |
+| `unknown` | 现有契约不足以证明 |
+
+当前 live tool schema 不携带 owner-proven completeness/effect 注解，所以 explorer 对所有工具默认返回
+`unknown`，不按名称补写 metadata。当前 DSH `tools.read` 的返回值是有界 inspection window，这是一项
+owner contract 使用注意，而不是 PTC 推导出的 capability annotation。需要无损整文件计算时，一等
+profile 使用 `node:fs/promises.readFile` 或 stream，并接受该直接 I/O 使 cold replay 进入 volatile。
+降级 profile 没有无损入口时，明确报告不支持。
+
+## Descriptive explorer
+
+```ts
+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 })
+```
+
+- `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 项。
+
+当前 replay 分类为 `recorded-value`：PTC journal 会在 cold replay 返回已记录的 canonical value，不重新 dispatch tool。它不表示外部 effect 被撤销、重做或验证。`owner-replay`、`volatile` 与 `unknown` 已属于 metadata vocabulary，但只有 owner/DSH 提供证据后才能声明。
+
+explorer 不调用 capability、不提升 authority、不读取隐藏服务、不触发辅助模型请求。`tools` metadata 来自执行时 agent scope 的 live schemas；`repl.state` 与 `code.run` metadata 由插件自身契约提供。模型若要根据探索结果决定下一步，仍会发生正常的后续 turn。当前公共扩展面没有跨 prompt assembly 与 runtime dispatch 的冻结 token，因此定义变化不能被描述成原子 snapshot。
+
+`code.run` 返回 `{ logs: string[], result?: unknown }`：`logs` 按发出顺序保存 child console 输出，child 返回 `undefined` 时省略 `result`。该结构描述不改变其中任意值的 completeness，也不表示 child 无外部 effect。
+
+## Non-tool APIs
+
+CodeRuntime request 已携带的 owner-provided program namespace 会原样进入 cell，并与 native tools 共享 lease；插件不翻译其领域契约。与插件保留的 `capabilities`、`code` 或 `repl` 同名时 request 明确失败，避免两套 binding 静默分叉；普通 cell 局部变量可以 shadow 这些低频 namespace，需要时从 `globalThis` 访问。`tools` 仍保持保留，因为 shadow 它会移除主要 typed 能力面。`code.run` 只隔离执行已经作为数据持有的 source；当前 cell 能直接完成的 Node、fetch 或 native tool 工作不需要嵌套。当前公共扩展面没有发现额外 DSH/插件服务的 registry，PTC Plus 不猜测隐藏服务，也不保留未来脚手架。显式注册、生成 manifest、装饰器或扫描只是可能的发现机制，不能替代类型、authority、lease 和 settlement 契约。
+
+explorer 本身只做 deterministic inspection，不调用模型。任何 Agent 生成的语义摘要都必须由用户主动触发，或由用户预先授权且有硬预算、用量记录和取消能力的 policy 触发；它不属于当前运行时。

package/docs/client-ui.md

@@ -0,0 +1,47 @@
+# Client UI
+
+PTC Plus 现在提供 DSH Web/Desktop 的**插件设置卡片**，位置在 Settings → Plugin configuration。
+
+## 设置命名空间
+
+Host half 通过 DSH 公共 `settings` 服务注册命名空间 `ptc-plus`。字段清单、默认值和校验来自 `internal/config-spec.js`，
+由 `index.js` 的 `Config` schema 与设置注册共用；client half 构建时把同一份字段清单打进 bundle，不在 UI 中复制默认值。
+
+## 可用设置
+
+| 分组 | 字段 | 说明 |
+| --- | --- | --- |
+| 开关 | `enabled` | 关闭后不注册 `run_code`/`edit_run_code`、不修改 system prompt、不创建 session runtime；只保留设置 UI。 |
+| Cordis | `cordisToolsEnabled` | 默认关闭；开启后为 PTC agent 加入创造模式使用的官方 Cordis 工具、指引与 companion Skill。 |
+| 计算 | `computeMs` / `maxWallMs` | 单 cell CPU 与墙钟预算。 |
+| 输出 | `maxOutputBytes` / `maxValueNodes` / `maxValueEdges` / `maxValueArrayLength` / `maxValueBigIntDigits` | Value Graph 与输出字节预算。 |
+| Worker | `maxOldGenerationSizeMb` / `maxNestedRunCodeDepth` | kernel worker 内存与嵌套执行深度。 |
+| 行为 | `canonicalizeToolCalls` / `looseTopLevelRedeclarations` / `durableReplay` | REPL 与 transport 策略。 |
+| 模块 | `autoRewriteImports` / `autoStripExports` / `autoSplitRedeclarations` | AST 重写开关。 |
+| 提示 | `tipsEnabled` / `tipCooldownMessages` / `tipEscalationFailures` | 恢复提示策略。 |
+
+## enabled 开关与启用标识
+
+所有字段都是实时设置：Host 在 settings watch 中安装、卸载或重配置 runtime。已提交的 cell 固定使用提交时的配置快照，运行中的更新从随后提交的 cell 开始使用；这不会替换 session-bound REPL 或已有 binding。`maxOldGenerationSizeMb` 在活动 worker 存在时因 Node 的创建期限制而拒绝并回滚，其他可重配置字段照常交给 owner。关闭后唯一的宿主副作用是注册 settings 命名空间，
+保证设置卡片仍然可读；此时只有 `enabled` 可写，其他控件被禁用。运行时重配置失败时回滚到上一次已应用值。
+
+`cordisToolsEnabled` 默认关闭并即时生效。它不切换 preset，而是把官方 Cordis 工具、owner guidance 与 `cordis-plugin-development` Skill 作为一个 agent-scoped mount 加入或移出 PTC agent；顶层仍为 `run_code` / `edit_run_code`，普通 agent 不继承。Host 缺少 official preset、Skill/Cordis service 或任一 contribution 加载失败时，启用会完整回滚。完整运行要求见 [运行时参考](runtime-reference.md)。
+
+设置卡片折叠头部显示 `PTC Plus`、`PTC 模式的会话级 TypeScript REPL。`、启用状态和可访问的展开/收起名称；稳定 REPL 指引不承载 UI 品牌名。启用且会话选择 `code` preset 时，`conversation.session.header.actions` 额外显示 `PTC Plus` 指示器。关闭时不注入任何 PTC 指引或工具 surface。
+
+live 配置若因宿主能力缺失或 runtime 安装/重配置失败，会先回滚所有已创建或更新的 owner，再把持久设置回写为上一次已应用值；回滚写入失败时 Host 记录 activation diagnostic，避免静默把配置显示成不存在的 runtime。
+
+## Client bundle
+
+浏览器入口为 `src/client.js`，构建为 `client.js`：
+
+```sh
+npm run build
+```
+
+`package.json` 声明 `dsh.client` 与 `./client` export。`npm run build` 从 `src/client.js` 生成 `client.js`，`npm run build:check` 比较确定性产物；`prepack` 会阻止陈旧 bundle 发布。Client half 只依赖 DSH 注入面提供的 settings、session、slot 与 UI primitive 模块。
+
+## 回退
+
+如果 DSH settings service 不可用，Host half 不会因缺少设置服务而加载失败：设置卡片不可用时直接回退为 composition `config`，
+`enabled` 默认开启，原有运行时行为保持不变。