dsh-ptc-plus 0.4.10 → 0.5.1

package/docs/verification.md

@@ -1,114 +1,56 @@
 # Deterministic verification
 
-`npm run check` runs `npm run verify`, checks that the source tree and review ledger did not change, and records the verified tree for the commit hook. Run `check` alone when the ledger is absent or resolved; running `verify` immediately before it repeats the full suite. While the ledger has unresolved findings, use `npm run verify` to collect verification evidence.
+Development and independent review run focused tests for the changed semantic owner and its consumers. An executable edit does not by itself require the complete suite. Complete behavioral validation runs on a stable executable candidate for delivery proof, an explicit full-validation/timing request, or a cross-suite risk that focused evidence cannot settle. [ADR 0036](adr/0036-separate-focused-development-from-delivery-verification.md) owns this scheduling decision.
 
-## Incremental independent review
-
-The standard local and CI gates run `test:client:visual`: one Client suite exports fresh renderer fixtures, followed by deterministic browser layout and visual assertions. Install its locked browser first with `npx playwright install --with-deps chromium`; missing browsers fail verification. The [Client visual contract](client-visual-contract.md) owns the bounded control/state inventory, reference palettes, fault counterexamples and official-Host evidence limits. Focused diagnostics may run `npm run test:client:visual` independently; they do not replace the final gate.
-
-Independent review is partitioned before reviewers start. Create the ignored working plan, replace every placeholder, then record it against the commit that defines the change scope:
-
-```bash
-npm run review:plan:new
-npm run review:plan -- --base <base-commit>
-```
-
-The plan uses `dsh-review-plan/v1`, and the ignored root `REVIEW_PLAN.json` is its only active source. All five standard obligations from the template must remain present. Each standard or change-specific obligation is assigned to a lane or excluded with a concrete reason. A lane declares semantic scope, exact file paths or directory prefixes, upstream lanes, owners, consumers, and counterexamples. `.` selects the complete checkout. Paths only determine content inputs and changed-path coverage; they do not replace the semantic declarations. A lane fingerprint covers that declaration, its assigned obligations, selected raw Git entry identities, persistent invalidation generation, and upstream fingerprints. Dependencies must form a DAG. The plan command refuses missing standard obligations, placeholders, unknown obligations, dependency cycles, a non-ancestor base, and changed paths outside every lane.
-
-The plan command prints one `review-lane <id> <head> <fingerprint>` line per lane. Lanes may be reviewed concurrently. Record each clean external report with the identity captured before that review:
-
-```bash
-npm run review:lane -- \
-  --lane <id> \
-  --evidence <report-path> \
-  --expect-head <head> \
-  --expect-fingerprint <lane-fingerprint>
-```
-
-The report's last non-empty line must be `VERDICT: NO FINDINGS`. A readable findings or incomplete report retires the named lane and every declared dependent from the recorded plan before checking whether the current candidate drifted; restoring an earlier tree therefore cannot revive evidence that the report rejected. An unreadable or missing report path is a command-input error and does not retire valid evidence. Unrelated lanes remain effective. A clean report retains the captured `HEAD` as provenance; an unrelated concurrent edit or `HEAD` advance does not prevent recording. Direct input, upstream fingerprint, scope, obligation, owner, consumer, counterexample, or dependency changes do. Put findings in `REVIEW_FINDINGS.md`, fix them, and rerun only the incomplete lanes shown by `npm run review:status`.
-
-Review-state mutations and authorization decisions use one atomic lock under checkout-local Git metadata. Plan recording, clean or negative lane recording, finalization, clearing, and pre-commit therefore have one observable order. A negative report queued behind an older clean recorder advances the reported lane's persistent invalidation `{epoch, revision}`, including while that lane is temporarily absent from the current plan, before retiring its current dependent closure. Advancement increments the revision normally and rotates to a new random epoch with revision zero at `Number.MAX_SAFE_INTEGER`, so a valid tuple never becomes unretirable. A temporarily absent lane must already have a retained tuple; unknown or mistyped lane IDs are rejected rather than creating state. Every active lane must have an explicit tuple. The tuple participates in the lane fingerprint and propagates through dependency fingerprints, so an older clean report cannot be submitted after re-addition. It survives normal `review:clear` and temporary lane removal; only a review captured after retirement can authorize the repaired fingerprint. Missing, partial, or malformed generation state blocks status and authorization. Explicit clear preserves valid generations but removes damaged generation state; plan recording then creates a new random epoch, so old reports still cannot match. The lock records a PID and unique release token and bounds acquisition, but never reclaims another owner automatically. If a command crashed, confirm that no review-state command is active, obtain the exact checkout-local path with `git rev-parse --git-path review-findings/state.lock`, remove only that directory, and retry. `review:status` remains a diagnostic snapshot and does not grant authorization. Finalization and pre-commit also re-read the active plan, candidate, proof, lane records, and evidence before they persist or return a decision, so edits made outside the review commands fail closed.
+| Scope | Entry and required selection |
+| --- | --- |
+| Backend | `npm run test:backend:focus -- --file test/<owner>.test.js --test-name-pattern="<case>"` |
+| Client | `npm run test:client:focus -- "<test-name pattern>"` |
+| Layout | `npm run test:client:layout:focus -- --case <id>` |
+| Fallback/native fixture | `npm run test:client:fallback:focus -- --case <id>` |
 
-Do not mutate a recorded boundary implicitly. Every status, clean lane verdict, finalization, and commit decision compares the normalized active file with the recorded plan. Missing, malformed, or semantically changed active content blocks clean authorization; it does not block a findings or incomplete report from retiring the recorded lane closure. Whitespace and object-key formatting alone do not change plan identity. When evidence reveals a missing path or semantic dependency, edit `REVIEW_PLAN.json` and run `npm run review:plan` without another `--base`; the command reuses the recorded base. The new plan hash invalidates its aggregate verdict, but clean lane records survive when their base, complete declaration, selected Git entries, upstream fingerprints, and evidence hashes are unchanged.
+Backend and browser entries accept `--list`, and selections can repeat. Omitting selection from a focused execution fails before starting the suite. `test:semantics` selects six files and is not a quick diagnostic; choose its relevant file/case through `test:backend:focus`. An independent layout invocation exports fresh HTML through `test:client:fixtures`, which selects only the two tests that own all 26 states. Its browser assertions remain unchanged. The complete visual gate still runs the full Client suite once and reuses its exports. Fixtures supplied through `--fixtures-dir` must come from the current candidate.
 
-After `review:status` reports `clean`, run the deterministic gate once and bind the composite verdict to it:
+`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.
 
-```bash
-npm run check
-npm run review:finalize
-git diff --check HEAD --
-```
+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.
 
-The final verdict uses `dsh-review-verdict/v2`. Pre-commit verifies its plan hash, lane fingerprints, evidence hashes, whole source fingerprint, `HEAD`, and prospective index. A later `HEAD` change retires the proof and aggregate verdict. Source or index drift blocks the gate while it differs; restoring the exact finalized candidate preserves those records, while keeping a changed candidate requires another `check` and `review:finalize`. Only lanes whose effective inputs changed need another independent review. `npm run review:clear` abandons the recorded plan, lane records, aggregate verdict, and verification proof while leaving the working `REVIEW_PLAN.json` available for revision; persistent invalidation generations remain so pre-retirement reports cannot revive in a rebuilt plan. Clearing is not a normal retry step. The prior single-report `verdict` command and `dsh-review-verdict/v1` records are not accepted.
+## Change classification
 
-`npm run verify` and `npm run check` validate the ledger, compare generated bundles, check syntax, run Client tests, and run all backend tests with coverage. Backend test files run in separate Node processes. The default process count is half the available CPUs, rounded down and bounded between one and four; each process can also own runtime Workers. Tests within each file retain their existing ordering. Coverage still requires 100% lines and functions and at least 95% branches, including compiler source remapping. The graded merge additionally asserts that the plugin-source closure it claims — `index.js` and every `internal/*.js` owner — appears in the merged report, so a module no instrumented process loads fails the gate instead of silently leaving it. Generated artifacts stay outside that closure: the root `compiler-*.cjs` bundles and the `internal/*.cjs` shims are remapped onto their original `internal/` sources or verified by the bundle checks, and `scripts/migrate-session-log.mjs` is verified by its own migration suite.
+`npm run verify:docs` checks a documentation-only candidate without starting builds, runtime tests, browsers or models. It rejects a mixed candidate instead of expanding into the full gate. `npm run check` chooses this same path automatically when every change from HEAD is a regular non-executable Markdown file in `docs/`, `AGENTS.md`, `CONTEXT.md`, `README.md` or `README.en.md`. Additions and deletions count, as do unstaged and untracked source files. Markdown fixtures, templates, symlinks, executable modes, configuration, tests and implementation changes select full verification. An explicit complete-validation request uses `npm run check -- --full` for a source proof or `npm run verify` for behavioral validation alone, regardless of changed paths. An unchanged tree also uses the full path when a new check is explicitly requested; reuse an existing matching proof instead.
 
-Coverage, the exhaustive backend suite, and the review-bound proof belong to the local pre-commit `npm run check`. 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. CI therefore proves portable installation and runtime integration without repeating coverage or the exhaustive semantic suite on hosted runners.
+The documentation path checks diff whitespace, local link target existence and literal `npm run` commands in changed documents and documents linking to them. It does not execute code blocks, visit remote links, check heading anchors or establish semantic accuracy. Independent review checks anchors, contracts, examples and instruction behavior against their owners. A deleted document is checked through its remaining referrers. Source, `HEAD` and findings stay unchanged through verification; after that stability check, a resolved local findings ledger may be archived. The proof records `documentation` or `full`. `check` does not enforce the review plan, lane evidence or prospective-index identity: `review:finalize` enforces the first two after the proof, and pre-commit enforces the last against the staged tree. [ADR 0039](adr/0039-verify-documentation-without-runtime-suites.md) owns this distinction.
 
-`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. Registry tag 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.
+For test-description or comment changes, inspect the diff and verify that test registration, selectors, executable fixtures and assertions retain their meaning. Select changed cases when execution can distinguish a possible behavior change; cosmetic wording does not justify unrelated runtime or browser matrices. Runtime or verification-owner changes use their focused regressions. These development observations do not replace the candidate classification used for a later commit.
 
-Use focused coverage while developing or after a full gate identifies a narrow coverage failure. Select every source whose threshold matters and the smallest test set that can distinguish the correction:
+## Reading test output
 
-```bash
-npm run coverage:focus -- \
-  --source internal/source-position-map.js \
-  --test test/source-position-map.test.js \
-  --test test/compiler-memory-facts.test.js \
-  --test test/stateful-source-line-mapping.test.js
-```
+Start with the selected inventory and a case pattern. Keep lengthy complete-run output in an ignored log, report the command, exit status, elapsed time and failures, then read the failing case's local context. Do not replay successful-case inventories or entire prior logs into progress messages and handoffs. Preserve exact failure text and its log location; summaries are not substitutes for evidence when diagnosing a failure. Test descriptions follow [the semantic naming guidance](semantic-validation.md#test-descriptions).
 
-Repeat `--source` and `--test` as needed. Paths must exist inside the checkout; sources must belong to the full coverage gate, and tests must be `test/*.test.js` files. Arguments after a standalone `--` are forwarded as Node test options. The focused runner uses the same compiler bytecode preparation, mock-dependent grouping, real Worker coverage instrumentation, source-map filtering, and 100% line/function plus 95% branch thresholds as the full runner. It includes selected but unexecuted sources as uncovered, so an empty report cannot pass. Its evidence and retained TAP diagnostics use the ignored `coverage/` directory.
+## Findings ledger
 
-Focused coverage establishes only the selected source-and-test relation. It does not establish full-suite compatibility and never replaces the final `verify` or `check`. A failed full gate must be diagnosed with the smallest check that reproduces its failure before another full run. Because `check` already invokes `verify`, running both consecutively against an unchanged tree repeats the full suite without adding evidence.
+Before creating or updating findings, read [Findings ledger](review-procedure.md#findings-ledger).
 
-Source fingerprints use Git with temporary administrative files, an index and an object directory. Configuration includes and repository attributes preserve canonical content, and newly computed objects stay in the temporary directory. One tagged file inventory identifies tracked, missing, untracked and sparse entries without repeatedly starting Git for each category. The temporary files are written directly, avoiding repeated Git initialization and configuration processes; explicit Git command arguments preserve isolation across Windows/WSL command forwarders.
-
-Set `DSH_PTC_TEST_CONCURRENCY` to a positive integer to override the backend process count. Use `1` for serial diagnosis or when CPU/memory contention affects timing-sensitive tests. This changes scheduling, not runtime compute budgets, test selection, or coverage thresholds. For example:
-
-```bash
-DSH_PTC_TEST_CONCURRENCY=1 npm run verify
-```
-
-```powershell
-$env:DSH_PTC_TEST_CONCURRENCY = '1'
-npm run verify
-Remove-Item Env:DSH_PTC_TEST_CONCURRENCY
-```
-
-Coverage runs additionally set `DSH_PTC_TEST_WORKER_COVERAGE=1` and load `scripts/instrument-worker-coverage.mjs` through Node's `--import`; that test-only seam adds the coverage variable to the helper's inner-Worker launch environment so real kernel, console, and candidate worker branches are measured. Production never sets the marker and continues to project `NODE_V8_COVERAGE` out of the user Worker environment. Because some transport tests install module mocks before importing the real transport, the runner executes two backend groups into the same coverage directory: the mock-dependent files run without the preload, and the remaining files run with it. Each group writes its own `run-*-mock.tap` or `run-*-instrumented.tap` diagnostic, both managed by the same retention and cleanup lifecycle. Test arguments such as `--test-name-pattern` are placed before the selected file list so Node applies them to test selection rather than treating them as file inputs.
-
-`npm run coverage` and `npm run coverage:focus` print their current stage and total elapsed time. Each invocation collects worker coverage in its own temporary directory under `coverage/`, removed after c8 finishes reporting, so simultaneous runs cannot erase or combine each other's evidence. The default report is printed to the terminal. A separate `coverage/run-*.tap` log retains Node's test diagnostics, including process exit codes and signals that the concise terminal reporter can omit. An explicit Node test reporter option replaces these default reporters. Source changes during verification still invalidate a `check` proof; separate coverage directories do not make concurrent source edits safe.
-
-Windows Node 24 and 26 reproductions and stacks identify a cppgc finalizer (`node::contextify::ContextifyScript`, or `ContextifyContext` when coverage was enabled) running after the environment that owned its private realm was gone, which wrote through a dangling `node::Realm` during isolate teardown. The reproduction ended the whole DSH process when an in-host session worker was terminated; macOS runners also observed whole-file aborts under coverage, but the available evidence does not establish that those aborts came from the same Windows stack or that the same cause applies across platforms. The session kernel now runs in a plugin-owned helper process (`internal/kernel-child.js`); `IsolatedWorker` sends a cooperative shutdown and, if the helper does not leave within its bound, kills only that helper. DSH is no longer the worker-teardown target on any supported host, so a wedged kernel is contained as a helper failure rather than a host-native crash. The former file-level retry wrapper is gone, and any failing CI smoke or local exhaustive test fails its run. This boundary removes the plugin's in-host kill exposure; it neither repairs the upstream Node path nor proves the macOS abort shared the Windows cause.
-
-Native oracle workers and external Windows command fixtures explicitly disable inherited `NODE_V8_COVERAGE`; they execute no code included by the plugin coverage gate. Subprocesses testing plugin implementations still collect coverage. PowerShell semantic-version observations share one invocation, and Windows registry fixtures read the three effective registry values with one real npm configuration query. Each retains its original inputs and assertions.
+## Incremental independent review
 
-The reporting adapter filters script records before c8 merges them. It reads source-map metadata once per input file, retains maps that lead to selected original sources, and leaves unknown or malformed maps to c8. Dependency-only compiler artifacts can be excluded before remapping; mixed compiler bundles retain their original coverage records. c8 still owns merging, remapping, counters, reporting and threshold checks. This uses an isolated adapter for c8's normalization method; dependency upgrades must pass the comparison with ordinary c8, including uncovered counters and mapped sources. The raw V8 reports are not rewritten.
+Before independent review or a review-state command, read [Incremental independent review](review-procedure.md#incremental-independent-review). Keep reviewer reports outside the checkout or in an ignored path so they cannot become candidate source after the plan is frozen. Both documentation and executable changes retain source-bound proof, independent review and prospective-index checks.
 
-Runtime Workers defer parsing the compiler bundle until their first compiler operation. Ordinary cells already prepared by the host avoid that startup work. Once an uninstrumented host has initialized its compiler, it snapshots V8 compiler bytecode for subsequent session kernel Workers. Coverage runs prepare that snapshot once in a separate uninstrumented process and pass its temporary file through `DSH_PTC_COMPILER_BYTECODE`; instrumented compiler instances neither produce nor consume bytecode. The runner owns this variable and removes the file after the tests. Workers receive private bytes through their initialization data and do not inherit the temporary file setting.
+## Complete behavioral validation
 
-A Worker uses a snapshot only when its complete compiler source matches; V8 checks bytecode compatibility and recompiles when it rejects the snapshot. Workers still initialize independent compiler realms and session state. The host retains one snapshot in memory, and each Worker discards its private copy after consumption; bytecode contains no saved program values. The bundle source, VM constructor and options are captured or isolated from source-owned mutations before execution.
+The full local and CI behavioral gates run `test:client:visual`: one Client suite exports fresh renderer fixtures, followed by deterministic browser layout and visual assertions. Install its locked browser first with `npx playwright install --with-deps chromium`; missing browsers fail verification. The [Client visual contract](client-visual-contract.md) owns the bounded control/state inventory, reference palettes, fault counterexamples and official-Host evidence limits. Use the selection-required browser entries for focused diagnostics; `test:client:visual` is the complete gate and is not a development feedback loop.
 
-Repeated Global User Binding validation reuses export descriptions and durability analysis inside the private compiler realm. Each cache keys the complete source and transform generation, retains at most 64 entries and 512 Ki characters of serialized keys, and returns fresh data to its caller. Snapshot fields, fingerprints and publication evidence still undergo validation on each request. This cache contains source-derived metadata, never executed values or module state, and is rebuilt for every compiler realm.
+`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.
 
-Cell preparation carries its successful native JavaScript parse proof into scope normalization, as module preparation already does. Decorator and resource transforms consume their feature scan's existing syntax tree through Babel's AST API. Recovered invalid decorator input retains the original parser diagnostic path. Intrinsic binding skips its source scan when the compiler recorded no bindings to replace. These changes remove repeated preparation work without changing execution budgets or coverage collection.
+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.
 
-Nested callable reflection reuses completed ordinary function recipes inside enclosing recipes. A source-position index selects the outermost reusable descendants, and syntax inspection skips their complete AST subtrees. Each reused function already contains its generated helper dependencies; class and method definition recipes keep their separate lowering paths. If all non-native syntax is inside those substituted functions, the surrounding recipe needs no additional type-erasure pass. Enclosing type syntax and resource declarations still undergo their own lowering. Callable marker emission uses cumulative edit offsets and binary searches to retain exact source boundaries without rescanning all edits for each mapping point. Declaration analysis groups at most 64 declarations into each shared ancestry witness, so Babel assigns ownership without repeatedly walking the same ancestors or retaining a full expression graph.
+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.
 
-Dynamic eval and Function preparation reuse source-derived compilation results within their private compiler realm. The key includes the complete source and syntax options. Every hit rechecks the original-source facts consulted by that compilation; a changed fact requires compilation again. The cache holds at most 64 entries and 2 Mi characters of serialized keys, results and source facts. Callers receive fresh metadata, and each execution still declares its variables and creates a new activation against the current environment. Cell operation plans remain with their existing compiler owner.
+`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.
 
-Optional-chain transforms allocate temporary names through the complete compilation unit's allocator. A scoped Babel adapter retains Babel's UID reservations and restores its original method when the transform completes or throws. This avoids a subsequent whole-scope rename for every generated temporary while preserving uniqueness across module regions.
+## Release coverage
 
-Callable catalogs compress windows containing referenced source ranges. Ranges separated by at most one source block share a window, preserving compression across nearby functions; large unreferenced gaps and unused buffers are omitted. Empty catalogs retain no source buffers. Entries keep their registration order and exact UTF-16 text in the existing catalog format.
+Coverage runs only when preparing a new version. Read [Release coverage](release-coverage.md) before its commands; ordinary development, review and commit preparation do not run it.
 
-Cell preparation traverses parsed trees and edit mappings without allocating a
-temporary object per unit of work. The namespace walk reads a node's own keys
-once and indexes node arrays directly instead of materializing an entry pair
-per property; the source-map builder validates and writes its four offsets
-positionally, and replacement runs reach that builder through a direct emitter
-instead of a generator and a per-run segment object. Rehomed compiler messages
-write their owned data descriptor directly rather than copying a generic
-descriptor first. Every one of these paths produced identical output before and
-after the change; only the immediately discarded allocations are gone.
+Browser scripts accept `--list` without launching a browser or generating fixtures, repeated exact `--case <id>` selections, and `--concurrency <positive integer>`. Default invocations execute every case. Focused layout measurements use `measurements-focused.json`, separate from complete layout evidence. Ordinary backend diagnostics accept repeated `--file <test/path.test.js>` and `--list`; unknown files and coverage-only paths are rejected before execution, while supported Node name/skip patterns, reporters and destinations, timeout, concurrency, only and force-exit options remain available. Additional positional paths, unknown options and coverage flags are rejected by the same parser for both CLI and library execution. For example, `npm run test:backend -- --file test/semantic-boundary-promises.test.js --test-name-pattern="promise catch"` runs only that responsibility through the ordinary environment owner. Focused runs cannot establish the complete verification proof.
 
-For focused diagnostics, use `npm run test:client`, `npm run test:semantics`, or Node's test runner with selected test files. These do not replace the final complete command. Model-backed evaluation remains separate and opt-in; see [Evaluation](evaluation.md).
+For development diagnostics, use the selection-required entries above. `test:semantics`, `test:client:visual` and the default backend entry are complete inventories for their respective scopes, so they are not short feedback loops. Focused execution does not replace a requested delivery gate. Model-backed evaluation remains separate and opt-in; see [Evaluation](evaluation.md).

package/index.js

@@ -9,7 +9,11 @@
 import Schema from '@deepseek-ai/schemastery'
 import { randomUUID } from 'node:crypto'
 import { createDirectSurfaceOwner } from './internal/direct-surface-owner.js'
-import { createRuntimeMessageOwner } from './internal/runtime-contexts.js'
+import { CapabilityStatisticsStore } from './internal/capability-statistics-store.js'
+import { createCapabilityEnvironment } from './internal/capability-environment.js'
+import { capabilityCommandReceipt } from './internal/capability-command-receipt.js'
+import { toolSdkSchemas } from './internal/program-bindings.js'
+import { createRuntimeMessageOwner, handBackRuntimeSessions } from './internal/runtime-contexts.js'
 import { createSessionLogOwner } from './internal/session-log-view.js'
 import { PTC_DELIVERY_CONTEXT } from './internal/runtime-messages.js'
 import { createCordisToolsOwner } from './internal/cordis-tools-owner.js'
@@ -22,11 +26,13 @@ import {
 } from './internal/config-spec.js'
 import { configFieldSchema, installSettingsSectionCompat } from './internal/settings-compat.js'
 import { installExecutionSeam } from './internal/execution-seam-compat.js'
+import { createDeferredRuntime, defersToOfficialRepl } from './internal/official-repl-priority.js'
 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 { 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 * as dshSettings from '@deepseek-ai/dsh-settings'
@@ -77,8 +83,8 @@ function replGuidance({ bindingPolicy, rewritesEnabled, languageSemantics, durab
     : 'Mixed new/existing top-level destructuring remains unsupported; separate the declaration from the assignment.'
   const cellConventions = languageSemantics === 'legacy-v1'
     ? `Cells are async function bodies; ${moduleSyntax} Use dynamic import or require explicitly when static module syntax is unsupported. ${variableRedeclaration} ${functionClassRedeclaration} ${splitSyntax}`
-    : `Cells support TypeScript, top-level await, return, static import and top-level export. ${languageSemantics === 'stateful-v1'
-      ? 'Declarations and assignments update the same logical binding within its scope, including const, functions, classes and imports. A bare declaration preserves an existing value. A declaration publishes its bindings after its whole pattern initializes; explicit assignments preserve actual partial writes. Imports follow their module until locally overwritten; importing again changes that same binding source. Existing closures observe later updates, while saved values retain their identity.'
+      : `Cells support TypeScript, top-level await, return, static import and top-level export. ${languageSemantics === 'stateful-v1'
+      ? 'Declarations and assignments update the same logical binding within its scope, including const, functions, classes and imports. A bare declaration preserves an existing value. A declaration publishes its bindings after its whole pattern initializes; assignments preserve partial writes. Imports follow their module until locally overwritten; importing again changes that same binding source. Existing closures observe later updates, while saved values retain their identity.'
       : 'Redeclaration protection is enabled: existing session names cannot be redeclared, and newly created const and import bindings reject assignment. Other declarations follow native scope rules. Previously writable bindings stay writable.'}`
   const recovery = durableReplay
     ? 'Direct Node/OS access remains live but is not replayed after a kernel restart.'
@@ -86,22 +92,22 @@ 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. 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.
+  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 and continue from them; repeat external operations only when their retry rules and current results establish that it is safe. \`edit_run_code\` edits and reruns a complete cell.
+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. Keep large inspection results in bindings or reduce them to targeted excerpts: \`tools.read\` is bounded inspection, not a lossless whole-file reader. ${cellConventions}
+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. Prefer direct current-cell work; 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) }\`, rather than retaining an earlier \`tools\` object or method. Background callbacks from completed cells cannot call program APIs.
+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.
 
-Native tool availability, executable names, shells, and path syntax depend on the current DSH profile and execution world; inspect them instead of assuming Windows, WSL, POSIX, or a particular shell. ${recovery}${cordisToolsEnabled ? ` ${cordisRecovery}` : ''}`
+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}` : ''}`
 }
 
 /** Register the session-bound REPL runtime. */
-function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, sessionId, sessionLog) {
+function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolSdkSchemasForAgent, sessionId, sessionLog, settingsForCommand) {
   const presentationGeneration = randomUUID()
   const replMemoryProjection = createReplMemoryProjection(presentationGeneration)
   const userBindingDraftProjection = createUserBindingDraftProjection(presentationGeneration)
@@ -112,6 +118,7 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, sessi
   let runtimeBridge
   let editTransport
   let directSurface
+  let capabilityEnvironment
   let userBindings
   let observationInterest
   let ready
@@ -340,6 +347,9 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, sessi
       maxOldGenerationSizeMb: activeConfig.maxOldGenerationSizeMb,
       valueLimits: valueLimitsFromConfig(activeConfig),
     })
+    capabilityEnvironment = createCapabilityEnvironment({ ctx, config: activeConfig,
+      toolSchemasForAgent: toolSdkSchemasForAgent, modelSchemasForAgent: toolSchemasForAgent,
+      store: new CapabilityStatisticsStore({ ctx }) })
     runtimeBridge = createRuntimeBridgeOwner({
       ctx,
       seam,
@@ -350,15 +360,18 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, sessi
       maxNestedRunCodeDepth: activeConfig.maxNestedRunCodeDepth,
       presentationGeneration,
       sessionId,
-      toolSchemasForAgent,
+      toolSchemasForAgent: toolSdkSchemasForAgent,
+      capabilityEnvironment,
       userBindingDraftForAgent: agent => userBindings.draftCapabilityForAgent(agent),
       bindingSubmissionForAgent: (agent, ensureLease, onAccepted) => userBindings.submissionForAgent(agent, ensureLease, onAccepted),
     })
     editTransport = createEditTransportOwner(ctx, {
-      readSessionLog: runtimeBridge.readSubmissionLog,
+      readSessionLog: runtimeBridge.readNestedDispatchLog,
       sessionLogView: sessionLog.project,
       durableReplay: activeConfig.durableReplay,
       executeTentative: runtimeBridge.executeTentative,
+      canScheduleEdit: runtimeBridge.canScheduleEdit,
+      scheduleEdit: runtimeBridge.scheduleEdit,
       presentationGeneration,
       sessionId,
       toolSchemasForAgent,
@@ -370,6 +383,7 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, sessi
       canonicalizeToolCalls: activeConfig.canonicalizeToolCalls,
       sessionId,
       toolSchemasForAgent,
+      capabilityEnvironment,
       userBindingsForAgent: () => userBindings.snapshot(),
       setAgentPresentation: (agent, presentation) => (
         userBindings.setAgentPresentation(agent, presentation)
@@ -383,9 +397,94 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, sessi
         return replGuidance(guidancePolicies(activeConfig))
       },
     }))
-    disposers.push(ctx.on('system-prompt/assemble', (assembly, context, next) => (
-      directSurface.assemble(assembly, context, next)
-    )))
+    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)
+      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) {
+        runtimeBridge.prepareAgent(agent)
+        editTransport.ensureInstalled(agent)
+      }
+    }))
+    for (const agent of ctx.agents?.list?.() ?? []) {
+      if (ctx.tools.get(RUN_CODE, agent) !== undefined) {
+        runtimeBridge.prepareAgent(agent)
+        editTransport.ensureInstalled(agent)
+      }
+    }
+    disposers.push(ctx.on('tools/post-execute', (exec, result, next) => capabilityEnvironment.postExecute(exec, result, next), { prepend: true }))
+    disposers.push(ctx.on('tools/ptc-dispatch-log', (dispatch, next) => capabilityEnvironment.dispatchLog(dispatch, next), { prepend: true }))
+    disposers.push(ctx.on('agent/status', payload => { if (payload?.agent) capabilityEnvironment.status(payload.agent, payload.status) }))
+    disposers.push(ctx.on('agent/created', ({ agent }) => capabilityEnvironment.status(agent, agent.status)))
+    if (typeof ctx.inject === 'function') {
+      const capabilitiesRpc = ctx.inject(['ptcPlusRpc'], scope => {
+        scope.effect(() => scope.ptcPlusRpc.register(RPC_CONTRACTS.capabilities, async (operation, payload, signal) => {
+          signal.throwIfAborted()
+          if (operation === 'catalog') return { ok: true, value: await capabilityEnvironment.describeCatalog(signal) }
+          if (operation === 'targets') return { ok: true, value: capabilityEnvironment.describeTargets() }
+          if (operation === 'session-catalog') return { ok: true, value: await capabilityEnvironment.describeSessionCatalog(payload, signal) }
+          if (operation === 'allocation') return { ok: true, value: await capabilityEnvironment.observeAllocation(payload, signal) }
+          if (operation !== 'inspect') return { ok: false, error: { code: 'UNKNOWN_OPERATION', message: 'Unknown capability plan operation', details: null } }
+          return { ok: true, value: capabilityEnvironment.describeSessions() }
+        }), 'ptc-plus: capability plan observation')
+      })
+      if (typeof capabilitiesRpc === 'function') disposers.push(capabilitiesRpc)
+      else if (typeof capabilitiesRpc?.dispose === 'function') disposers.push(() => capabilitiesRpc.dispose())
+      const commands = ctx.inject(['commands'], scope => {
+        scope.effect(() => scope.commands.register({ name: 'capabilities',
+          description: 'Inspect, search or change session capabilities; global choices also save settings.',
+          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,
+              state === 'pending' && capabilityEnvironment.pendingChoiceMessage(agent)
+                ? { commandId, rawInput, message: capabilityEnvironment.pendingChoiceMessage(agent) } : undefined)
+            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?.())
+              return { kind: changed.sessionApplied ? 'success' : 'error',
+                text: receipt(changed.sessionApplied ? changed.publication === 'pending' ? 'pending' : 'recorded' : 'saved-only', changed.error) }
+            }
+            const listing = /^list(?: (all|skills|tools|mcp|mcp_tools))?(?: (.*))?$/.exec(input)
+            if (listing) {
+              const entries = await capabilityEnvironment.catalogFor(agent, signal)
+              const query = (listing[2] ?? '').toLocaleLowerCase()
+              const kind = listing[1] ?? 'all'
+              return { kind: 'success', text: JSON.stringify({ schema: 'ptc-capability-catalog/v1', entries: entries.filter(entry => (
+                kind === 'all' || kind === 'skills' && entry.category === 'skill'
+                || kind === 'tools' && entry.category === 'tool' && entry.source?.kind !== 'mcp'
+                || kind === 'mcp' && ['server', 'resource'].includes(entry.category)
+                || kind === 'mcp_tools' && entry.category === 'tool' && entry.source?.kind === 'mcp'
+              ) && (!query || `${entry.id} ${entry.description}`.toLocaleLowerCase().includes(query))) }) }
+            }
+            if (input !== '' && input !== 'refresh') return { kind: 'error', text: receipt('usage') }
+            if (input === 'refresh') {
+              if (!capabilityEnvironment.canRefresh(agent)) {
+                return { kind: 'error', text: receipt('unavailable') }
+              }
+              await capabilityEnvironment.refresh(agent, undefined, signal, commandId)
+              // A refresh always republishes the saved configuration; when that
+              // configuration has capability management or context off, report
+              // the off state instead of claiming an updated environment.
+              const described = capabilityEnvironment.describe(agent)
+              const state = described.effective?.enabled !== true
+                ? described.sourceSettings?.contextEnabled === false ? 'paused' : 'off'
+                : described.publication === 'pending' ? 'pending' : 'recorded'
+              return { kind: 'success', text: receipt(state) }
+            }
+            return { kind: 'success', text: JSON.stringify(capabilityEnvironment.describe(agent), null, 2) }
+          } }), 'ptc-plus capability command')
+      })
+      if (typeof commands === 'function') disposers.push(commands)
+      else if (typeof commands?.dispose === 'function') disposers.push(() => commands.dispose())
+    }
     disposers.push(ctx.on('llm/stream', (options, next) => directSurface.stream(options, next), { global: true }))
     disposers.push(ctx.on('tools/execute', (exec, next) => {
       const rejected = directSurface.executionRejection(exec)
@@ -402,9 +501,12 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, sessi
           .then(result => directSurface.argumentDiagnostic(exec, result))
       }
       if (exec.name === EDIT_RUN_CODE) return runtimeBridge.withSubmission(exec, next)
+      capabilityEnvironment.validateSupply(exec.agent, exec.name, exec.arguments)
+      capabilityEnvironment.admitted(exec)
       return next()
     }))
     disposers.push(ctx.on('tools/result', (exec, result) => {
+      capabilityEnvironment.dispatched(exec, result)
       directSurface.handleResult(exec)
       if (exec.name === EDIT_RUN_CODE) return editTransport.handleResult(exec, result)
       if (exec.name === RUN_CODE) return runtimeBridge.handleResult(exec, result)
@@ -423,6 +525,7 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, sessi
       () => editTransport.disposeAgent(agent),
       () => runtimeBridge.disposeAgent(agent),
       () => userBindings.clearAgentPresentation(agent),
+      () => capabilityEnvironment.disposeAgent(agent),
     ], 'ptc-plus: agent disposal failed')))
     disposers.push(ctx.on('session/disposed', session => disposeLifecycleOwners([
       () => directSurface.disposeSession(session),
@@ -464,8 +567,6 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, sessi
     try {
       runtimeBridge.reconfigure(nextConfig)
       rollbacks.push(() => runtimeBridge.reconfigure(previousConfig))
-      editTransport.reconfigure(nextConfig)
-      rollbacks.push(() => editTransport.reconfigure(previousConfig))
       directSurface.reconfigure(nextConfig)
       rollbacks.push(() => directSurface.reconfigure(previousConfig))
       await userBindings.reconfigure(nextConfig)
@@ -495,6 +596,7 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, sessi
         }
       }
       activeConfig = nextConfig
+      capabilityEnvironment.reconfigure(nextConfig)
       observationInterest.reconfigure(nextConfig.replViewEnabled)
     } catch (error) {
       const rollbackFailures = []
@@ -534,10 +636,13 @@ export const apply = (ctx, config = {}) => {
 
 /** Install the plugin into the scope of the seam the host registered. */
 function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatileConfig) {
+  let settingsWriter
   const sessionLog = createSessionLogOwner(ctx)
   const toolSchemasForAgent = agent => typeof ctx.tools.schemas === 'function'
     ? ctx.tools.schemas(agent)
     : []
+  // SDK contracts include output schemas; model-facing schemas remain unchanged.
+  const toolSdkSchemasForAgent = agent => toolSdkSchemas(ctx.tools, agent)
   const sessionId = agent => {
     const id = agent?.session?.id ?? agent?.id
     return id === undefined ? undefined : String(id)
@@ -611,6 +716,11 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
     )
     return cleanup
   }
+  // 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'
+  )
   const startActivation = record => {
     if (record.cancelled || disposed || activating !== record) {
       record.completion.resolve({ status: 'superseded' })
@@ -621,7 +731,9 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
     }
     let candidate
     try {
-      candidate = installPtCRuntime(ctx, record.config, seam, toolSchemasForAgent, sessionId, sessionLog)
+      candidate = record.shape === 'deferred'
+        ? createDeferredRuntime()
+        : installPtCRuntime(ctx, record.config, seam, toolSchemasForAgent, toolSdkSchemasForAgent, sessionId, sessionLog, () => settingsWriter)
       record.runtime = candidate
     } catch (error) {
       const failedRuntime = error?.[INSTALL_CLEANUP]
@@ -666,6 +778,7 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
     const record = {
       config: nextConfig,
       generation,
+      shape: executionShape(nextConfig),
       runtime: undefined,
       disposal: undefined,
       disposed: false,
@@ -715,6 +828,15 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
         return beginActivation(nextConfig, generation, cleanup)
       }
       const current = committed
+      if (current.shape !== executionShape(nextConfig)) {
+        // Ownership changes are installation changes: dispose the live kernels
+        // and install the other shape, so no committed cell can mix the two
+        // execution contracts or extend state the new owner cannot see.
+        current.retiring = true
+        void disposeRuntime(current)
+        const cleanup = disposeRetainedRuntimes()
+        return beginActivation(nextConfig, generation, cleanup)
+      }
       if (!nextConfig.cordisToolsEnabled) current.runtime.cancelCordisActivation()
       return enqueueTransition(async () => {
         if (disposed || committed !== current) return { status: 'superseded' }
@@ -763,9 +885,10 @@ 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)]))
   const messageOwner = createRuntimeMessageOwner(context => (
     committed?.retiring ? [] : committed?.runtime.contextsForRequest(context) ?? []
-  ), sessionLog.project)
+  ), sessionLog.project, () => committed !== undefined && committed.retiring !== true, handbackOwners.sessionQuery)
   ctx.effect(() => ctx.systemPrompt.context({
     name: PTC_DELIVERY_CONTEXT, order: 98, text: '',
   }), 'ptc-plus dynamic message delivery witness')
@@ -777,10 +900,13 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
   )), 'ptc-plus accepted messages')
   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()
+    await handBackRuntimeSessions(ctx, handbackOwners)
+  }, 'ptc-plus provider handback')
 
   let configSource = () => resolveConfig(volatileConfig ?? resolvedConfig)
   let configurationGeneration = 0
-  let settingsWriter
   let configurationRollback = false
   const reportActivationFailure = (error) => {
     ctx.logger?.warn?.('ptc-plus: runtime activation failed', error)

package/internal/binding-toggle-receipt.js

@@ -0,0 +1,24 @@
+import { isPtcMessageSource, PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
+
+const PREFIX = 'Global binding configuration saved. This does not prove model catalog delivery or worker initialization:\n'
+
+export function bindingToggleMessage(entry, revision) {
+  const receipt = { schema: 'ptc-binding-toggle/v1', id: entry.id, name: entry.name, enabled: entry.enabled, revision }
+  if (!valid(receipt)) throw new TypeError('invalid binding toggle receipt')
+  return { source: { kind: PTC_MESSAGE_SOURCE_KIND, form: 'binding-toggle', receipt },
+    content: [{ type: 'text', text: PREFIX + JSON.stringify(receipt) }] }
+}
+
+function valid(receipt) {
+  return receipt?.schema === 'ptc-binding-toggle/v1' && typeof receipt.id === 'string' && receipt.id.length > 0
+    && receipt.id.length <= 64 && typeof receipt.name === 'string' && receipt.name.length <= 256
+    && typeof receipt.enabled === 'boolean' && Number.isSafeInteger(receipt.revision) && receipt.revision >= 0
+    && Object.keys(receipt).length === 5
+}
+
+export function readBindingToggle(message) {
+  const receipt = message?.source?.receipt
+  return isPtcMessageSource(message?.source) && message.source.form === 'binding-toggle' && valid(receipt)
+    && message.content?.length === 1 && message.content[0]?.type === 'text'
+    && message.content[0].text === PREFIX + JSON.stringify(receipt) ? receipt : undefined
+}