dsh-ptc-plus 0.5.1 → 0.5.3

package/docs/v0.5.3-goals.md

@@ -0,0 +1,117 @@
+# v0.5.3 目标：可证明的状态
+
+## 0.5.2 留下了什么
+
+0.5.2 解决的是**状态连续**：视图变化不再重建内核，绑定不会因为一次重渲染而丢失，编辑是追加而不是改写历史。它把"REPL 环境活着的时候算数"这件事做扎实了。
+
+但它留下一个未回答的问题：**插件对模型说的那些话，凭什么算数？**"这个绑定可用""这条记录没被改过""这个能力已经生效"——这些都只是**声明**，不是**证明**。0.5.2 里已经能看到三种破口：
+
+- 恢复提示说某个名字 live，下一格却 `not defined`（`PTC-R002` 收口了一部分）；
+- 保存了全局绑定开关，面板只能说"已保存"，说不出"已投递""已可用"；
+- 历史记录被事后改动，插件从记录本身看不出来，因为记录与它的副本永远自洽。
+
+所以 0.5.3 的主题不是再加功能，而是**把声明变成证明**：
+
+> **0.5.3：可证明的状态。** 插件对模型陈述的每一条事实，都要有它能产出、模型能检验的证据；并且永远区分"已配置""已投递""已证明"。
+
+## 概念基元
+
+四个词贯穿本版全部目标，先定义再谈功能。
+
+| 概念 | 回答的问题 | 谁拥有 |
+| --- | --- | --- |
+| **供给 supply** | 产品声明存在哪些能力、绑定、能力开关 | 全局配置与目录 |
+| **取用 adoption** | 这个会话的环境选择用其中哪些 | 会话 |
+| **物化 materialization** | worker 真的把它装进环境了吗 | 运行时与 worker |
+| **证明 proof** | 有什么可被模型检验的证据 | 日志、探测、诊断 |
+
+三条不变式：
+
+- **I1 层次不可互相代答。** 供给不能代取用，取用不能代物化，物化不能代证明。
+- **I2 只有证明可以宣称"可用"。** 没有证明时如实说"不可确认"，而不是默认可用。
+- **I3 可证明的事实必须能从会话日志重建。** 重建不出来的，要显式标注为不可重建，而不是假装它不存在。
+
+0.5.2 的教训正好对应 I1：全局开关是供给，会话要不要用是取用，装了没有是物化——三层混成一个"开关"，就会出现"我改了全局，为什么这个会话不变"和"配置关了但绑定还在"这类说不清的状态。
+
+## 目标
+
+### G1 绑定：从"开关"到"环境成员"
+
+**概念纠正。** 绑定不是配置项，是**环境成员**。全局决定目录供给，会话决定取用，worker 决定可用。
+
+- 全局关闭一个条目 = 它不在目录里，会话无从取用。**"覆盖复活已删除条目"这个概念上不存在**，不需要额外的冲突规则去禁止。
+- 会话取用是二态（用 / 不用）加一个缺省（未表态即全取），不需要三态哨兵，也不借用能力侧的 `automatic`——那个词的含义是"由宿主推导"，绑定没有可推导的决策。
+- 取用 ≠ 物化成功：装失败的名字必须点名（接 `PTC-R002`），曾经 live 后消失的必须点名（`PTC-R006`）。
+
+**验收**：不设会话取用时行为与 0.5.2 完全一致；A 会话不用某绑定、B 会话仍可用；全局关闭后会话不可取用且无"复活"路径；重启后取用关系随日志重建；物化失败在模型可见处点出名字。
+
+### G2 能力与上下文：把"已保存"升级为"已投递"
+
+**概念。** 保存设置只改变供给，不证明模型看得到、也不证明 worker 初始化过。面板与提示必须分开说这三件事。
+
+**验收**：保存后能报告目录是否出现该能力、新单元格能否真的取到它；三种状态（已保存 / 已投递 / 已可用）在面板与模型可见提示中区分；任一层失败都指名，而不是笼统"已生效"。
+
+### G3 历史证据：记录必须能自证未被改动
+
+**概念。** 一份可以被事后编辑、且编辑后仍与自身副本一致的记录，不是证据。执行时要写入**不可重算的快照**，折叠时用它比对。
+
+现有的半成品：`completion` 与诊断已经互相校验（0.5.2），但 `diagnostics` 被改后再重算 `completion` 就自洽了——因为事件里没有第三份独立副本（`message.content` 为空）。
+
+**契约**：快照字段随 journal schema 一起版本化；不一致即判该格不可信；**否决必须是重放终态**，不能进入重试循环（上一次实现因此挂死）。
+
+**验收**：篡改 completion 或 diagnostic 都使该格不可信；恢复矩阵不退化；journal 迁移对旧记录保持兼容。
+
+### G4 改写历史：`editRewritesHistory`
+
+**概念纠正。** "改写历史"不是删除，而是**取代关系**。旧单元格仍然留在日志里，只是不再参与环境构建；它声明的名字以"被取代"报告，而不是以"丢失"报告。
+
+这比"追加"更诚实：不假装旧执行没发生过，而是显式声明谁取代了谁（日志里记为 `supersedes`：这条记录取代了哪条）。默认关闭，开启时改写才真正替换目标单元格。
+
+**验收**：关闭时全部既有用例不变；开启时"改写 → 后续格子读到新值"成立；被取代单元格的绑定以专门诊断点名；折叠能从日志重建取代关系。
+
+### G5 快照归属：REPL 面板的 generation
+
+**概念。** 面板显示的不是"当前状态"，而是**某个运行期的一次观察**。需要分开两件事：
+
+- **新鲜度**：同一运行期内的投影刷新——清单仍然有效，不该闪成"不可确认"；
+- **归属**：跨运行期的快照——属于上一个进程，必须判为不可确认（既有契约，`repl-memory-projection` 的用例钉着它）。
+
+0.5.2 的客户端兜底只解决了新鲜度，没有表达归属。0.5.3 要在数据里表达"这份清单来自哪个运行期"，而不是靠随机 UUID 与对象身份比较去猜。
+
+**验收**：两个会话并行、其中一个结束时，另一个面板不闪；真正重建后显示不可确认并说明原因；既有契约用例保持绿。
+
+### G6 覆盖率：证据，不是仪式
+
+**概念。** 覆盖率是"这段代码被执行过"的证据；阈值是策略，不是证据。0.5.2 为发版引入了"按改动文件 100% + 历史欠账白名单"，那是策略例外。
+
+**验收**：全局 `lines 100 / functions 100`，白名单清空；`review:finalize` 记录对应证明；发布流程不再需要"按改动文件"的特殊分支。
+
+## 非目标
+
+- 不新增 PTC 语言特性，不改 DSH 的公共契约；
+- 不做跨会话共享 worker 或跨会话共享 REPL 状态；
+- 不为通过门槛而放宽断言或增加 coverage ignore（除非证明不可达并写入提交信息）。
+
+## 发布判据
+
+1. 六个目标各自的验收项全部有可执行证据；
+2. `npm run check`、`npm run coverage`（全局 100%）、`semantic:check`（unknown 0）全绿；
+3. `docs/` 中受影响的 owner 文档与 ADR 同步更新；
+4. Release 工作流 `stage` 成功，npm 进入 staged 状态；
+5. 发布说明按 [release-notes.md](release-notes.md) 的用户视角重写，不以功能清单代替变化说明。
+
+## 发布时机
+
+0.5.2 已经把"提前适配"这条路的代价演示过一遍：为一个尚未发布到 GitHub 的 alpha 改代码，等对应 rc 出来又要再改一轮，而 alpha 的接口形状在正式发布前并不稳定。
+
+因此 0.5.3 的发布以**通道**为准，不以"某天适配好了"为准：
+
+| 通道 | 含义 | 对发布的作用 |
+| --- | --- | --- |
+| `latest` | 最新的已发布 rc | 必须通过；它决定能不能发 |
+| `next` | 正在推进的下一条 rc 线，GitHub 已有发布说明 | 必须通过 |
+| `alpha` | 提前适配，正式发布尚未出现 | 只报告，不阻塞 |
+
+规则：**插件可以提前适配 alpha（那是有价值的预警），但版本发布等待包含该形状的正式 rc。** 已经 staged 的包如果对应的是 alpha 形状的实现，就撤掉重新准备，而不是"先发出去再说"。
+
+通道的具体版本由 `npm run host:channels:update` 从 dist-tag 解析并写入 [compat/channels.json](../compat/channels.json)，不手工编辑版本号；行为代码只做形状探测，由 `npm run host:shape-check` 守住。

package/docs/verification.md

@@ -13,6 +13,10 @@ Backend and browser entries accept `--list`, and selections can repeat. Omitting
 
 `npm run check` classifies the complete source candidate against HEAD, runs the appropriate checks below, checks source/ledger stability, and records the verified tree and verification scope for the commit hook. Run `check` alone when the ledger is absent or resolved; while findings remain unresolved, use `verify`. Do not run complete component suites around the same final command: that duplicates its work. Focused evidence is not a source-bound commit proof. Inspect a failed gate's stage/case, reproduce it with a focused entry, repair it, and rerun the final command only after the candidate is stable.
 
+The full branch of `check` runs `npm run verify:check`: `review:validate`, `host:channels:verify`, `host:shape-check`, `semantic:check`, `build:check`, the syntax checks and `scripts/deterministic-test-groups.mjs --check`, which selects `npm run test:client` and `npm run test:backend:fast`. The Client units run in the gate because a change can be covered only by them; the backend tier is the set of test files `semantic-obligations.json` names as evidence for at least one obligation, excluding coverage-only paths and the verification-tooling probes that fail by construction outside their harness. It targets a few minutes so the commit gate is actually run; [ADR 0046](adr/0046-gate-the-commit-with-the-semantic-evidence-tier.md) owns this split and its evidence.
+
+`npm run verify` keeps the complete behavioral gate: `test:client:visual` plus the whole ordinary backend inventory. CI runs `verify:ci`; release preparation runs `verify`, and coverage stays release-only. A change that touches a semantic owner missing from the graph must extend the graph, which widens the fast tier at the same time. The browser suites are not part of the commit gate: they are the complete visual contract and run in `verify`, in CI, and on demand.
+
 Stage runners print inventory, concurrency and elapsed times. Start a permitted long gate with a short tool yield and retain its process/session ID. Tell the user the command, start time and expected range before waiting. Keep verbose diagnostics in ignored logs and wait on the same process in intervals no longer than 60 seconds. Report completed stages, failures or changed timing expectations. Inspect process activity and stage output before treating a slow run as stalled; elapsed time alone is insufficient. Stop only the owned process on cancellation, and never report an interrupted run as verified. Do not start another copy while waiting.
 
 ## Change classification
@@ -41,11 +45,11 @@ The full local and CI behavioral gates run `test:client:visual`: one Client suit
 
 `npm run verify` and the full branch of `npm run check` validate the ledger, compare generated bundles, check syntax, run Client tests, and run all ordinary backend tests through `npm run test:backend` without coverage instrumentation. The ordinary runner selects the sorted root `test/*.test.js` inventory. Coverage-only runner/report tests and collection probes live under `test/coverage/` and are excluded from daily execution. The release coverage runner includes both inventories and sets `DSH_PTC_TEST_COVERAGE_SUITE=1` for mixed instrumented cases; the ordinary runner clears that marker. Both runners share the concurrency calculation. Backend test files run in separate Node processes. Compiler boundary protocols are divided into disjoint storage, Promise and reflection files so the bounded file pool can execute them alongside the parameter/namespace/error cases without sharing their native or PTC realms. The default process count is half the available CPUs, rounded down and bounded between one and eight; each process can also own runtime Workers. Tests within each file retain their existing ordering. The ordinary runner enables module mocks without preloading coverage hooks and removes inherited coverage and temporary bytecode settings from its test-process environment.
 
-After the shared ledger, baseline, semantic, build and syntax prerequisites pass, `scripts/deterministic-test-groups.mjs` runs the complete Client visual and backend groups concurrently on machines with at least 12 available CPUs. Smaller machines retain serial phases; CI keeps its focused runtime group. Both concurrent groups must settle, and any nonzero exit, signal or startup failure rejects verification. Each browser pool retains its own CPU bound and process isolation.
+After the shared ledger, channel, semantic, build and syntax prerequisites pass, `scripts/deterministic-test-groups.mjs` selects its groups by gate: `--check` (the commit gate) runs only the semantic-evidence backend tier, the default `verify` runs the complete Client visual and backend groups concurrently on machines with at least 12 available CPUs, and `--ci` keeps the focused runtime group. Smaller machines retain serial phases. Every selected group must settle, and any nonzero exit, signal or startup failure rejects verification. Each browser pool retains its own CPU bound and process isolation.
 
-The full branch of the local pre-commit `npm run check` runs the complete ordinary backend suite. Both verification scopes produce a review-bound proof. Coverage runs only before a new version is released, as specified by [ADR 0035](adr/0035-run-coverage-only-before-a-new-release.md). CI starts from a clean lockfile install and runs `verify:ci` on every supported Node and operating-system entry: frozen-baseline validation, semantic ownership, generated builds, Client tests, and focused runtime contracts covering compiler startup, helper-process lifecycle, plugin takeover, native-call transport, and durable argument diagnostics. Ubuntu Node 24 additionally exercises the packed plugin against both frozen official `latest` and `next` DSH graphs. Normal CI therefore proves portable installation and runtime integration without running coverage-specific suites, collecting coverage, or running the exhaustive semantic suite on hosted runners.
+Both verification scopes produce a review-bound proof. Coverage runs only before a new version is released, as specified by [ADR 0035](adr/0035-run-coverage-only-before-a-new-release.md). CI starts from a clean lockfile install and runs `verify:ci` on every supported Node and operating-system entry: channel-manifest validation, semantic ownership, generated builds, Client tests, and focused runtime contracts covering compiler startup, helper-process lifecycle, plugin takeover, native-call transport, and durable argument diagnostics. A separate job per host channel packs the plugin and runs the host contracts against that channel's installed release. Normal CI therefore proves portable installation and runtime integration without running coverage-specific suites, collecting coverage, or running the exhaustive semantic suite on hosted runners.
 
-`host:baseline:verify`, which is part of deterministic verification, is offline. It requires the installed root DSH `next` cohort to match `package-lock.json` and validates the tracked `compat/latest` declaration and lock without installing it. CI separately runs `test:host-contract`: the root graph exercises `next`, while a temporary consumer created from `compat/latest/package-lock.json` exercises `latest` against the packed plugin. The tracked `compat/current` graph additionally captures the newest published official release, even when its distribution is on another npm channel; its isolated packed consumer is part of `test:host-contract`. Registry and official release lookup and lock regeneration belong only to `host:baseline:update` and the scheduled baseline-refresh workflow. That workflow publishes a changed frozen candidate as a pull request and explicitly dispatches this CI workflow once because its `GITHUB_TOKEN`-authored events cannot start another run; ordinary gates never install a floating channel.
+`host:channels:verify`, which is part of deterministic verification, is offline: it validates the tracked channel manifest — schema, per-channel dist-tag and blocking role, full coverage of the probed host packages, one release per pinned cohort, and a recorded integrity for each — without resolving a tag or installing a host. CI runs `test:host-contract` as one job per channel. Each job installs its channel on demand from the manifest into an ignored cache, proves the installed versions against the manifest, packs the plugin, and runs the host contracts through a repository-external consumer; the `alpha` job reports without failing the workflow. Registry resolution belongs only to `host:channels:update` and the scheduled channel-refresh workflow. That workflow publishes a changed manifest as a pull request and explicitly dispatches this CI workflow once because its `GITHUB_TOKEN`-authored events cannot start another run; ordinary gates never install a floating channel.
 
 ## Release coverage
 

package/index.js

@@ -13,13 +13,15 @@ import { CapabilityStatisticsStore } from './internal/capability-statistics-stor
 import { createCapabilityEnvironment } from './internal/capability-environment.js'
 import { capabilityCommandReceipt } from './internal/capability-command-receipt.js'
 import { toolSdkSchemas } from './internal/program-bindings.js'
+import { hostTransportDefinition, hostTransportUnreadable } from './internal/host-tool-sdk.js'
 import { createRuntimeMessageOwner, handBackRuntimeSessions } from './internal/runtime-contexts.js'
-import { createSessionLogOwner } from './internal/session-log-view.js'
+import { createSessionLogOwner, projectionRegistrationDisposer } from './internal/session-log-view.js'
 import { PTC_DELIVERY_CONTEXT } from './internal/runtime-messages.js'
 import { createCordisToolsOwner } from './internal/cordis-tools-owner.js'
 import { createEditTransportOwner, EDIT_RUN_CODE } from './internal/edit-transport-owner.js'
 import { createRuntimeBridgeOwner, RUN_CODE } from './internal/runtime-bridge-owner.js'
 import { resolveConfig, watchVolatileConfig } from './internal/runtime-config.js'
+import { configureRetention } from './internal/projection-retention.js'
 import {
   CONFIG_FIELDS,
   SETTINGS_NAMESPACE,
@@ -31,10 +33,12 @@ import { valueLimitsFromConfig } from './internal/value-wire-schema.js'
 import { createReplMemoryProjection } from './internal/repl-memory-projection.js'
 import { createUserBindingDraftProjection } from './internal/user-binding-draft-projection.js'
 import { createUserBindingsOwner } from './internal/user-bindings-owner.js'
+import { latestBindingAdoption } from './internal/binding-adoption.js'
 import { createHostRpc } from './internal/host-rpc.js'
 import { RPC_CONTRACTS } from './internal/rpc-contract.js'
 import { createReplObservationInterest } from './internal/repl-observation-interest.js'
 import { guidancePolicies } from './internal/binding-update-policy.js'
+import { PROMPT_SLOT_IDS, resolvePromptTextConfig } from './internal/prompt-text.js'
 import * as dshSettings from '@deepseek-ai/dsh-settings'
 
 const INSTALL_CLEANUP = Symbol('ptc-plus install cleanup')
@@ -59,7 +63,7 @@ export const Config = Schema.object(Object.fromEntries(
  */
 export const inject = ['tools', 'systemPrompt', 'agents']
 
-function replGuidance({ bindingPolicy, rewritesEnabled, languageSemantics, durableReplay, cordisToolsEnabled }) {
+function replGuidance({ bindingPolicy, rewritesEnabled, languageSemantics, durableReplay, cordisToolsEnabled }, promptText) {
   const looseTopLevelRedeclarations = bindingPolicy.variableRedeclarations
   const looseTopLevelFunctionClassRedeclarations = bindingPolicy.functionClassRedeclarations
   const autoRewriteImports = rewritesEnabled.autoRewriteImports
@@ -92,22 +96,35 @@ function replGuidance({ bindingPolicy, rewritesEnabled, languageSemantics, durab
   const cordisRecovery = cordisToolsEnabled
     ? 'Keep large Cordis plugin source in a binding before the tool call so it can be reused after an error. A Cordis parse or validation failure can follow external effects; repeat the call only when its retry rules and current results establish that it is safe.'
     : ''
-  return `\`run_code\` continues one persistent PTC REPL. Use Node.js modules in the cell; use external processes when their environment is needed. Ordinary top-level bindings remain available to later cells, so reuse them instead of resending setup code. Choose the smallest cell that answers the request and return only the value the next step needs.
-
-After an execution error, earlier statements may have taken effect. Inspect relevant values in a short cell, then continue from them; repeat external operations only when their retry rules and current results establish safety. \`edit_run_code\` edits and reruns a complete cell.
-
-## Cell conventions
-Use \`return\` for an explicit result and \`console\` for logs. Return supported values directly, including undefined, NaN, infinities, -0 and BigInt; JSON.stringify loses distinctions or rejects BigInt. Do not mix BigInt with Number arithmetic; use a BigInt literal or convert explicitly. Keep functions, Date, Map and other unsupported values in bindings; return needed data or type observations. Native \`tools.*\` arguments must satisfy their own JSON schemas; PTC value transport does not widen those contracts. Keep large inspection results in bindings or reduce them to targeted excerpts: \`tools.read\` is bounded inspection, not a lossless whole-file reader. Relative filesystem, path and default child-process operations use the current working directory at the time they run; a successful in-cell \`tools.working_directory({ cd })\` applies to the rest of that cell, while cell imports and \`import.meta\` keep the directory the cell started in, and \`process.chdir\` is unavailable. ${cellConventions}
-
-## Available capabilities
-Use \`capabilities.tree()\`, \`capabilities.find()\`, and \`capabilities.inspect()\` for unfamiliar program APIs; Reserve \`code.run\` for isolated execution of source held as data.
-Program API references expire when their cell ends. Reusable helpers must read the current namespace when called, for example \`async function readNow(args) { return tools.read(args) }\`, instead of retaining an earlier \`tools\` object or method. Completed-cell callbacks cannot call program APIs.
+  // Each paragraph is an editable asset; a derived policy sentence is appended to
+  // the paragraph that owns it, so rewriting prose can never contradict the
+  // configuration that produced it. Omitting a paragraph keeps its derived clause.
+  const prose = id => (promptText.omitted(id) ? '' : promptText.text(id))
+  const withDerived = (id, derived) => {
+    const base = prose(id)
+    return base === '' ? derived : `${base} ${derived}`
+  }
+  const paragraphs = [
+    prose(PROMPT_SLOT_IDS.guidanceOpening),
+    prose(PROMPT_SLOT_IDS.guidanceErrorRecovery),
+    withDerived(PROMPT_SLOT_IDS.guidanceCellConventions, cellConventions),
+    prose(PROMPT_SLOT_IDS.guidanceCapabilities),
+    withDerived(PROMPT_SLOT_IDS.guidanceExecutionWorld, `${recovery}${cordisToolsEnabled ? ` ${cordisRecovery}` : ''}`),
+  ]
+  return paragraphs.filter(paragraph => paragraph.trim().length > 0).join('\n\n')
+}
 
-Native tool availability depends on the current DSH profile and execution world; inspect executables, shells, and paths instead of assuming Windows, WSL, POSIX, or a particular shell. ${recovery}${cordisToolsEnabled ? ` ${cordisRecovery}` : ''}`
+/**
+ * The reserved `run_code` transport definition, from whichever surface this
+ * host publishes it on. Session execution is available exactly when one of
+ * those surfaces answers.
+ */
+function runCodeDefinitionFor(tools, scope) {
+  return hostTransportDefinition(tools, scope, RUN_CODE)
 }
 
 /** Register the session-bound REPL runtime. */
-function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolSdkSchemasForAgent, sessionId, sessionLog, settingsForCommand) {
+function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolSdkSchemasForAgent, sessionId, sessionLog, settingsForCommand, readPromptText) {
   const presentationGeneration = randomUUID()
   const replMemoryProjection = createReplMemoryProjection(presentationGeneration)
   const userBindingDraftProjection = createUserBindingDraftProjection(presentationGeneration)
@@ -241,11 +258,17 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
   const cancelCordisActivation = () => pendingCordisActivation?.cancel()
   const registerProjection = (projection, label) => {
     try {
-      const unregister = projectionService?.register?.(projection)
-      if (typeof unregister !== 'function') {
-        throw new Error('ptc-plus: sessionProjections.register did not return a disposer')
+      // A newer host returns a ProjectionHandle (`stateOf`/`readerFor`/`dispose`,
+      // possibly async); earlier hosts returned a disposer. Accept either shape so
+      // the projection is not silently dropped on the newer contract.
+      const dispose = projectionRegistrationDisposer(projectionService?.register?.(projection))
+      if (dispose === undefined) {
+        throw new Error('ptc-plus: sessionProjections.register returned neither a disposer nor a handle')
       }
-      return unregister
+      // Unregistration failures belong to the caller that is suspending or
+      // reloading the projection: it retries and reports them. Swallowing one
+      // here would turn a failed disposal into a silent duplicate projection.
+      return () => dispose()
     } catch (error) {
       ctx.logger?.warn?.(`ptc-plus: ${label} projection unavailable`, error)
       return undefined
@@ -342,9 +365,13 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
       readSessionLog: sessionLog.read,
       enabled: activeConfig.userBindingsEnabled,
       draftProjectionAvailable,
+      // A session's adoption is its own recorded decision, so it is read from
+      // that session's log instead of a process-local map.
+      bindingAdoptionForAgent: agent => latestBindingAdoption(sessionLog.project(agent)?.ptcMessages ?? []),
       maxWallMs: activeConfig.maxWallMs,
       maxOutputBytes: activeConfig.maxOutputBytes,
       maxOldGenerationSizeMb: activeConfig.maxOldGenerationSizeMb,
+      workerReclaimMs: activeConfig.workerReclaimMs,
       valueLimits: valueLimitsFromConfig(activeConfig),
     })
     capabilityEnvironment = createCapabilityEnvironment({ ctx, config: activeConfig,
@@ -353,6 +380,7 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
     runtimeBridge = createRuntimeBridgeOwner({
       ctx,
       seam,
+      readPromptText,
       observeSession: id => observationInterest.has(id),
       readSessionLog: sessionLog.read,
       sessionConfig: activeConfig,
@@ -375,6 +403,7 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
       presentationGeneration,
       sessionId,
       toolSchemasForAgent,
+      promptText: resolvePromptTextConfig(activeConfig),
     })
     directSurface = createDirectSurfaceOwner({
       sessionLogView: sessionLog.project,
@@ -384,7 +413,8 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
       sessionId,
       toolSchemasForAgent,
       capabilityEnvironment,
-      userBindingsForAgent: () => userBindings.snapshot(),
+      declaresRunCode: agent => runCodeDefinitionFor(ctx.tools, agent) !== undefined,
+      userBindingsForAgent: agent => userBindings.snapshotForAgent(agent),
       setAgentPresentation: (agent, presentation) => (
         userBindings.setAgentPresentation(agent, presentation)
       ),
@@ -393,25 +423,33 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
       name: 'tools:ptc-plus-repl',
       order: 98,
       text: context => {
-        if (ctx.tools.get(RUN_CODE, context?.scope) === undefined) return ''
-        return replGuidance(guidancePolicies(activeConfig))
+        if (runCodeDefinitionFor(ctx.tools, context?.scope) === undefined) return ''
+        return replGuidance(guidancePolicies(activeConfig), resolvePromptTextConfig(activeConfig))
       },
     }))
+    let unreadableTransportReported = false
     disposers.push(ctx.on('system-prompt/assemble', async (assembly, context, next) => {
       const projected = await directSurface.assemble(assembly, context, next)
-      if (ctx.tools.get(RUN_CODE, context?.agent) !== undefined) runtimeBridge.prepareAgent(context?.agent)
+      if (runCodeDefinitionFor(ctx.tools, context?.agent) !== undefined) runtimeBridge.prepareAgent(context?.agent)
+      else if (!unreadableTransportReported && hostTransportUnreadable(ctx.tools, context?.agent)) {
+        // The host declares the reserved transport and this plugin cannot read it.
+        // Every gate that needs execution answers "unavailable", so the operator is
+        // told which of the two facts holds instead of finding the features gone.
+        unreadableTransportReported = true
+        ctx.logger?.warn?.('ptc-plus: the host tool executor declares run_code but publishes no transport definition this plugin can read; session execution stays unavailable')
+      }
       return projected
     }))
     disposers.push(() => capabilityEnvironment.dispose())
     disposers.push(ctx.on('agent/pre-step', (payload, next) => capabilityEnvironment.preStep(payload, next), { prepend: true }))
     disposers.push(ctx.on('agent/created', ({ agent }) => {
-      if (ctx.tools.get(RUN_CODE, agent) !== undefined) {
+      if (runCodeDefinitionFor(ctx.tools, agent) !== undefined) {
         runtimeBridge.prepareAgent(agent)
         editTransport.ensureInstalled(agent)
       }
     }))
     for (const agent of ctx.agents?.list?.() ?? []) {
-      if (ctx.tools.get(RUN_CODE, agent) !== undefined) {
+      if (runCodeDefinitionFor(ctx.tools, agent) !== undefined) {
         runtimeBridge.prepareAgent(agent)
         editTransport.ensureInstalled(agent)
       }
@@ -440,17 +478,22 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
           input: { hint: 'refresh | list [all|skills|tools|mcp|mcp_tools] [query] | set session|global <id> [availability|disclosure] <choice>' },
           handler: async ({ commandId, agent, rawInput, signal }) => {
             const input = rawInput.trim()
-            const receipt = (state, error) => capabilityCommandReceipt(state, String(agent.session.id), error,
+            const receipt = (state, error, proof) => capabilityCommandReceipt(state, String(agent.session.id), error,
               state === 'pending' && capabilityEnvironment.pendingChoiceMessage(agent)
-                ? { commandId, rawInput, message: capabilityEnvironment.pendingChoiceMessage(agent) } : undefined)
+                ? { commandId, rawInput, message: capabilityEnvironment.pendingChoiceMessage(agent) } : undefined,
+              proof)
             const selection = /^set (session|global) (\S+) (?:(availability|disclosure) )?(full|on-demand|closed|automatic|inherit|enabled|host|adaptive)$/.exec(input)
             if (selection) {
               if (!capabilityEnvironment.canRefresh(agent)) return { kind: 'error', text: receipt('unavailable') }
               const changed = await capabilityEnvironment.change(agent, {
                 scope: selection[1], id: decodeURIComponent(selection[2]), dimension: selection[3], selection: selection[4], commandId,
               }, signal, settingsForCommand?.())
+              // A save states what it changed and what it did not prove: the
+              // model-visible catalog and a cell that reached the capability are
+              // separate facts, reported by the layer that owns each one.
+              const proof = capabilityEnvironment.describeCapabilityProof(agent, decodeURIComponent(selection[2]))
               return { kind: changed.sessionApplied ? 'success' : 'error',
-                text: receipt(changed.sessionApplied ? changed.publication === 'pending' ? 'pending' : 'recorded' : 'saved-only', changed.error) }
+                text: receipt(changed.sessionApplied ? changed.publication === 'pending' ? 'pending' : 'recorded' : 'saved-only', changed.error, proof) }
             }
             const listing = /^list(?: (all|skills|tools|mcp|mcp_tools))?(?: (.*))?$/.exec(input)
             if (listing) {
@@ -624,8 +667,11 @@ export const apply = (ctx, config = {}) => {
   // Configuration is validated before the plugin waits for the host's seam, so
   // an unusable configuration fails at the load call rather than later.
   const resolvedConfig = resolveConfig(config)
+  // The retention window is user configuration; install it before any fold can run.
+  configureRetention(resolvedConfig)
   return installExecutionSeam(ctx, {
     services: inject,
+    attachmentTimeoutMs: resolvedConfig.executionSeamTimeoutMs,
     attach: (scope, seam) => applyWithExecutionSeam(scope, resolvedConfig, seam, ctx, config),
     reportFailure: (error, seamName) => ctx.logger?.warn?.(
       `ptc-plus: execution seam ${seamName} failed to attach`,
@@ -719,7 +765,9 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
   // Execution ownership is a per-attachment property: `owned` installs the
   // session runtime, `deferred` leaves run_code to the official provider.
   const executionShape = nextConfig => (
-    defersToOfficialRepl(nextConfig, seam.provider) ? 'deferred' : 'owned'
+    defersToOfficialRepl(nextConfig, {
+      get retainsState() { return seam.originalRetainsState },
+    }) ? 'deferred' : 'owned'
   )
   const startActivation = record => {
     if (record.cancelled || disposed || activating !== record) {
@@ -733,7 +781,7 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
     try {
       candidate = record.shape === 'deferred'
         ? createDeferredRuntime()
-        : installPtCRuntime(ctx, record.config, seam, toolSchemasForAgent, toolSdkSchemasForAgent, sessionId, sessionLog, () => settingsWriter)
+        : installPtCRuntime(ctx, record.config, seam, toolSchemasForAgent, toolSdkSchemasForAgent, sessionId, sessionLog, () => settingsWriter, currentPromptText)
       record.runtime = candidate
     } catch (error) {
       const failedRuntime = error?.[INSTALL_CLEANUP]
@@ -886,9 +934,17 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
   ctx.effect(() => async () => controller.dispose(), 'ptc-plus runtime lifecycle')
 
   const handbackOwners = Object.fromEntries(['sessions', 'sessionPersistence', 'sessionQuery'].map(name => [name, ctx.get(name)]))
+  // One spelling of "the current document": the same resolved configuration the
+  // reconciliation loop applies, so a delivered message and the assembled prompt can
+  // never read two different prompt-text documents. One holder per attachment, handed
+  // to the runtime it installs, so two attachments in one process keep their own
+  // document. Read lazily: the settings section replaces `configSource` after
+  // activation.
+  const currentPromptText = () => resolvePromptTextConfig(configSource())
   const messageOwner = createRuntimeMessageOwner(context => (
     committed?.retiring ? [] : committed?.runtime.contextsForRequest(context) ?? []
-  ), sessionLog.project, () => committed !== undefined && committed.retiring !== true, handbackOwners.sessionQuery)
+  ), sessionLog.project, () => committed !== undefined && committed.retiring !== true, handbackOwners.sessionQuery,
+  currentPromptText)
   ctx.effect(() => ctx.systemPrompt.context({
     name: PTC_DELIVERY_CONTEXT, order: 98, text: '',
   }), 'ptc-plus dynamic message delivery witness')
@@ -901,10 +957,21 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
   ctx.effect(() => ctx.on('agent/disposed', ({ agent }) => messageOwner.disposeAgent(agent)), 'ptc-plus message agent disposal')
   ctx.effect(() => () => messageOwner.dispose(), 'ptc-plus dynamic message lifecycle')
   ctx.effect(() => async () => {
-    await controller.dispose()
+    // The model-visible handback states a fact about execution, so it must not
+    // ride on whether every projection unregistered: a failed disposal is
+    // reported by the caller that retries it, and the runtime is gone either way.
+    let disposalFailure
+    try {
+      await controller.dispose()
+    } catch (error) {
+      disposalFailure = error
+    }
     await handBackRuntimeSessions(ctx, handbackOwners)
+    if (disposalFailure !== undefined) throw disposalFailure
   }, 'ptc-plus provider handback')
 
+  // The settings section replaces this source after activation; the prompt-text
+  // accessor above reads it lazily for exactly that reason.
   let configSource = () => resolveConfig(volatileConfig ?? resolvedConfig)
   let configurationGeneration = 0
   let configurationRollback = false
@@ -935,6 +1002,7 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
   }
   const reconcile = (propagateFailure = false) => {
     const current = resolveConfig(configSource())
+    configureRetention(current)
     const generation = ++configurationGeneration
     if (!current.enabled) {
       const operation = controller.uninstall()
@@ -982,6 +1050,7 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
   }
   ctx.effect(() => seam.onSourceChange(() => {
     const current = resolveConfig(configSource())
+    configureRetention(current)
     if (!current.enabled) return undefined
     if (seam.language !== 'typescript') {
       const language = seam.language

package/internal/binding-adoption.js

@@ -0,0 +1,136 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { isPtcMessageSource, PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
+
+/**
+ * Session binding adoption: which Global User Binding catalog entries this
+ * session uses.
+ *
+ * The question is answered per session and per entry, and the answer is a
+ * decision of exactly two states: this session uses the entry, or it does not.
+ * An entry the session never named is used, because the global catalog already
+ * answered the supply question. That default is the absence of a decision, not
+ * a third state: "use" and "never mentioned" lead to the same environment, so
+ * they are one state rather than two.
+ *
+ * Adoption can only take an entry away from this session. It cannot supply one,
+ * enable one, or name a source: an entry the global configuration disabled is
+ * absent from the catalog, so "adoption revives a deleted entry" has no
+ * encoding here and needs no rule forbidding it. Naming an entry the catalog
+ * does not offer is rejected at the surface that states the decision, because
+ * the record would otherwise claim authority over supply.
+ *
+ * The neighbour this must not be confused with is the capability pane's
+ * `automatic`, which means "the host derives this value". A binding has no host
+ * derivation to defer to, so borrowing that word would misdescribe both.
+ *
+ * The decision is recorded as one PTC message in the session log, so it is
+ * reconstructed by replaying that log after a restart instead of being kept in
+ * process memory.
+ */
+export const BINDING_ADOPTION_FORM = 'binding-adoption'
+export const BINDING_ADOPTION_SCHEMA = 'ptc-binding-adoption/v1'
+
+const MAX_DECLINED = 64
+const ENTRY_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
+const PREFIX = 'PTC Plus session binding adoption. This session uses every entry the global catalog supplies except the declined ones. Adoption can only withdraw an entry from this session: it cannot supply, enable or revive one, and the global configuration decides which entries exist at all. Declined entry IDs:'
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function sortIds(ids) {
+  return [...ids].sort((left, right) => left < right ? -1 : left > right ? 1 : 0)
+}
+
+export function normalizeBindingAdoption(value) {
+  if (!isRecord(value) || Reflect.ownKeys(value).length !== 2
+    || !Object.hasOwn(value, 'schema') || !Object.hasOwn(value, 'declined')) {
+    throw new TypeError('invalid binding adoption')
+  }
+  if (value.schema !== BINDING_ADOPTION_SCHEMA) throw new TypeError('invalid binding adoption schema')
+  if (!Array.isArray(value.declined) || value.declined.length > MAX_DECLINED) {
+    throw new TypeError('invalid binding adoption declined entries')
+  }
+  const declined = []
+  for (const id of value.declined) {
+    if (typeof id !== 'string' || !ENTRY_ID.test(id)) throw new TypeError('invalid binding adoption entry id')
+    if (declined.includes(id)) throw new TypeError('duplicate binding adoption entry id')
+    declined.push(id)
+  }
+  return Object.freeze({ schema: BINDING_ADOPTION_SCHEMA, declined: Object.freeze(sortIds(declined)) })
+}
+
+/** The exact model-visible wording one adoption record carries. */
+export function bindingAdoptionText(adoption) {
+  return `${PREFIX}\n${JSON.stringify(normalizeBindingAdoption(adoption).declined)}`
+}
+
+export function bindingAdoptionMessage(adoption) {
+  const text = bindingAdoptionText(adoption)
+  const message = createUserMessage({
+    source: { kind: PTC_MESSAGE_SOURCE_KIND, form: BINDING_ADOPTION_FORM },
+    content: [{ type: 'text', text }],
+  })
+  if (readBindingAdoption(message) === undefined) throw new TypeError('invalid binding adoption message')
+  return message
+}
+
+/** Read one adoption record back from a message, message projection or message fact. */
+export function readBindingAdoption(value) {
+  const source = value?.source
+  if (!isPtcMessageSource(source) || source.form !== BINDING_ADOPTION_FORM) return undefined
+  if (!Array.isArray(value.content) || value.content.length !== 1 || value.content[0]?.type !== 'text') return undefined
+  const text = value.content[0].text
+  if (typeof text !== 'string' || !text.startsWith(`${PREFIX}\n`)) return undefined
+  try {
+    const declined = JSON.parse(text.slice(PREFIX.length + 1))
+    const adoption = normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined })
+    return bindingAdoptionText(adoption) === text ? adoption : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The newest adoption this session recorded, or `undefined` while it recorded
+ * none. The newest record replaces earlier ones, because stating a decision
+ * again is how a session changes its mind.
+ */
+export function latestBindingAdoption(records) {
+  if (!Array.isArray(records)) return undefined
+  for (let index = records.length - 1; index >= 0; index -= 1) {
+    const record = records[index]
+    if (record?.form !== BINDING_ADOPTION_FORM) continue
+    try {
+      return normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined: record.declined })
+    } catch {
+      // A record that cannot be read is not evidence for an earlier record
+      // either: the newest statement is the current one, and it is unreadable.
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * The declined entry IDs of one adoption, as a set the environment uses.
+ * An adoption that was never stated declines nothing.
+ */
+export function declinedBindingEntries(adoption) {
+  return new Set(adoption === undefined ? [] : normalizeBindingAdoption(adoption).declined)
+}
+
+/** State one entry as used (`adopt` true) or not used, leaving the rest alone. */
+export function withBindingAdoption(adoption, entryId, adopt) {
+  if (typeof entryId !== 'string' || !ENTRY_ID.test(entryId)) throw new TypeError('invalid binding adoption entry id')
+  if (typeof adopt !== 'boolean') throw new TypeError('binding adoption decision must be a boolean')
+  const declined = declinedBindingEntries(adoption)
+  if (adopt) declined.delete(entryId)
+  else declined.add(entryId)
+  return normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined: [...declined] })
+}
+
+/** Drop every declined entry: this session again uses the whole catalog. */
+export function clearedBindingAdoption() {
+  return normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined: [] })
+}