dsh-ptc-plus 0.4.10 → 0.5.0

package/docs/adr/0031-close-semantic-obligations-by-owner.md

@@ -8,7 +8,7 @@ Focused tests and coverage can prove their selected examples executed, but they
 
 `semantic-obligations.json` is the tracked graph of plugin-owned semantic boundaries. Each obligation records one semantic owner, exact implementation files, disposition, owning contract, preserved observables or declared differences, execution entries, lifecycle states, language or data generations, platform bounds, consumers, oracle, executable evidence and upstream obligations. Dispositions distinguish behavior preserved from an external owner, intentional PTC differences and bounded external surfaces; an omitted or uncertain obligation is unknown and fails validation rather than being relabeled as preserved.
 
-`scripts/semantic-obligations.mjs` validates the graph before build and coverage in `npm run verify`. The exact inventory covers every JavaScript implementation file in `internal/` and `src/`, the public `index.js` and `client.js` entries, and the journal migration entry, with exactly one semantic owner per file. Adding, removing or assigning a source twice fails closed until the graph changes. Contract and evidence files must exist, every obligation needs executable test evidence, dependencies must resolve without cycles, journal versions must remain a contiguous recorded range, and declared language and module generations must equal their executable owners. The command emits counts for preserved, intentional-difference, bounded-external and unknown obligations; zero unknown means closure over the declared plugin source boundary, not equivalence with all current or future Node or DSH behavior.
+`scripts/semantic-obligations.mjs` validates the graph before build and backend tests in `npm run verify`; release-only coverage scheduling is owned by [ADR 0035](0035-run-coverage-only-before-a-new-release.md). The exact inventory covers every JavaScript implementation file in `internal/` and `src/`, the public `index.js` and `client.cjs` entries, and the journal migration entry, with exactly one semantic owner per file. Adding, removing or assigning a source twice fails closed until the graph changes. Contract and evidence files must exist, every obligation needs executable test evidence, dependencies must resolve without cycles, journal versions must remain a contiguous recorded range, and declared language and module generations must equal their executable owners. The command emits counts for preserved, intentional-difference, bounded-external and unknown obligations; zero unknown means closure over the declared plugin source boundary, not equivalence with all current or future Node or DSH behavior.
 
 The graph complements, rather than replaces, focused tests, coverage and independent review lanes. A boundary-specific registry can enforce a stronger relation where the implementation supplies one: worker realm mutations use their classified installation entry and AST check, journal generations use their closed schema, and language/module generations use exported sets. Other records bind exact owner files and evidence so a new boundary cannot enter the tracked source inventory silently; review still evaluates whether an edit inside an existing owner changes its obligation or dependencies.
 

package/docs/adr/0034-keep-program-values-separate-from-output-projections.md

@@ -0,0 +1,29 @@
+# Keep program values separate from output projections
+
+## Problem
+
+An isolated PTC computation can return a value that the parent must continue computing with. DSH's outer execution seam accepts JSON-safe output, so its readable rendering of a BigInt or cyclic graph cannot also be the parent program result. An unsupported transfer likewise has different consequences before dispatch, after a binding completes, and after a cell computes its result.
+
+## Decision
+
+Plugin-owned isolated `code.run` uses the canonical completion of its settled child runtime, decoded by the existing PTC Value V1 codec. The child owns an independent binding root and is disposed after settlement. The private `runTentative` program-completion option validates canonical graph admission without generating model presentation; a sparse graph may fit transfer limits while its unused rendering would exceed them. Only the native execution seam consumes its public JSON-safe projection. An explicit `return undefined` has a `result` property; a child without a return does not. Existing native `run_code` members retain their owner-defined result contract, including when their execution re-enters the plugin. Legacy upstream execution retains its previous contract.
+
+Journal calls already store canonical argument and result envelopes. Cold replay returns exactly the recorded value without redispatching child computation or external effects. Historical codec refusal diagnostics remain readable only when the actual refusal or a codec-owned legacy message exactly matches their recorded diagnostic; arbitrary errors do not acquire that compatibility. Historical strings remain strings; neither a language generation nor a wire migration is required because replay does not recompute the changed bridge result. Renderer text is never decoded or inspected to guess an encoding.
+
+PTC Value V1 retains its explicit support domain. Codec-owned failures retain private structured categories (`unsupported`, `shape`, `budget`) and paths. Native Node brand checks identify known excluded data types without consulting user getters, `toJSON`, constructor names or `Symbol.toStringTag`. Prototype admission uses data descriptors; a hostile or unknown prototype remains unsupported. Proxy reflection in actual encoding still belongs to worker execution and budgets; diagnostic classification does not perform additional reflection.
+
+Parameters reject before dispatch. Result encoding happens only after the owner call completes and reports that fact, possible effects and the absence of automatic retry. A completion encoding failure preserves the live worker and supplies category-specific help. Stable guidance distinguishes direct result transfer, live computation and native tool JSON contracts. Native JSON serialization and BigInt arithmetic retain their own errors.
+
+## Alternatives considered
+
+**Decode rendered strings.** Ordinary strings overlap with renderer output; parsing cannot recover value identity or distinguish a historical string from a canonical value.
+
+**Return rich values through the public DSH seam.** The seam's JSON-safe contract does not permit this. A private canonical child completion already exists and provides the necessary boundary without changing Host packages or public dispatch.
+
+**Expand V1 using structuredClone or Node v8 serialization.** Maintained platform serializers support more data types, but their semantics differ from V1: structured clone can read accessors, normalize class instances and descriptors, and v8 binary output does not provide this project's closed canonical JSON envelope and versioned admission guarantees. Type expansion requires a separately specified generation covering references, own properties, intrinsic state, budgets and historical decoding. Neither platform support nor a diagnostic repair proves those semantics. V1 is retained rather than silently widening or lossy-stringifying it.
+
+**Convert BigInt to Number or JSON text automatically.** Conversion can lose precision or turn computation into string concatenation. Native tool schemas remain authoritative; callers select meaningful explicit representations at those boundaries.
+
+## Consequences
+
+Supported child values retain their types and graph relationships across plugin IPC, while parent and child bindings stay isolated. Unsupported live values remain usable inside their worker, with actionable transfer diagnostics instead of undifferentiated budget advice. This does not add support for Date, Map, class instances or live resources, or imply that a failed transfer undoes an external effect. The wire format, native owner authority and historical recorded results remain unchanged.

package/docs/adr/0035-run-coverage-only-before-a-new-release.md

@@ -0,0 +1,27 @@
+# Run Coverage Only Before a New Release
+
+## Problem
+
+Collecting and merging instrumented coverage on every local verification and commit repeats release-readiness work during ordinary development. Behavioral verification, source-bound commit proof, and coverage thresholds establish different facts, so moving coverage must preserve the complete daily test suite and the independent-review gate.
+
+## Decision
+
+Coverage collection, coverage runner/report regression suites, and instrumented probes run only while preparing a new version for release. `npm run verify` and the `npm run check` proof path retain generated-build checks, syntax validation, Client verification, and the complete ordinary backend test suite without coverage instrumentation. Ordinary discovery selects root `test/*.test.js`; coverage-only suites and collection probes live under `test/coverage/`. The release coverage runner selects both inventories and owns `DSH_PTC_TEST_COVERAGE_SUITE=1` for mixed instrumented cases. Ordinary execution clears that marker. Both runners share the bounded concurrency calculation. Ordinary execution enables module mocks but does not preload coverage hooks or inherit coverage and temporary bytecode settings into the test process.
+
+The Release workflow runs `npm run coverage` against its verified annotated tag before packing or npm staging. The full coverage gate retains compiler source remapping, plugin-source closure checks, 100% line and function coverage, and at least 95% branch coverage. A failure prevents staging. Normal CI keeps its portable runtime and official-Host contracts without collecting coverage. During release preparation, maintainers may run the full gate locally and use `npm run coverage:focus` to diagnose a failed coverage threshold; focused evidence cannot replace the full release gate.
+
+This changes coverage scheduling, not findings-ledger readiness, independent review, source and index identity, or pre-commit authorization from [ADR 0016](0016-archive-resolved-review-findings.md) and [ADR 0026](0026-persist-the-delivery-verdict-against-the-verified-candidate.md). The release authority and immutable artifact path remain owned by [ADR 0022](0022-stage-npm-releases-with-oidc.md).
+
+## Alternatives considered
+
+**Keep coverage in every local verification and commit.** This preserves the old timing but forces development and review to pay the instrumentation and merge cost even when no new version is being prepared.
+
+**Remove the coverage command without retaining the complete backend suite.** This shortens daily verification by silently dropping behavioral evidence. Ordinary verification instead retains every ordinary behavioral case while coverage-specific cases remain in the release inventory.
+
+**Treat coverage regression fixtures as an exception to the daily prohibition.** Those test bodies can start collection or instrumentation even when the package command no longer invokes coverage. The scheduling boundary therefore owns test discovery and mixed-case selection as well as the top-level command.
+
+**Require coverage only in a human release checklist.** This records the intended timing but lets the automated staging path publish a candidate without meeting the thresholds. The Release workflow enforces the gate before creating and staging the artifact.
+
+## Consequences
+
+Daily verification and commit proof no longer establish coverage thresholds. Those thresholds remain a new-version release requirement, and the release job needs enough time for the instrumented suite and report merge. Behavioral regressions still fail daily verification, while coverage deficits may first be discovered during release preparation. The maintained command and diagnostic contracts live in [release coverage](../release-coverage.md), [focused verification](../verification-optimization-work.md), and [publishing](../publishing.md).

package/docs/adr/0036-separate-focused-development-from-delivery-verification.md

@@ -0,0 +1,29 @@
+# Separate Focused Development From Delivery Verification
+
+## Problem
+
+Requiring a complete deterministic gate after every executable development turn repeats long backend and browser matrices while the candidate is still changing. A focused command that silently defaults to all tests creates the same cost when an agent forgets a selection. Full behavioral validation and source-bound delivery proof remain necessary, but neither is a useful failure-localization loop.
+
+## Decision
+
+Development and independent review select the changed semantic owner and its bounded consumers. Executable edits alone do not trigger a complete gate. Backend and browser focused package entries require exact file or case selections before execution; listing the inventory is permitted without executing it. Client focused execution requires a test-name pattern. Independent layout diagnostics generate fresh HTML from only the two Client test owners that export all states. The complete visual gate retains the full Client suite once, followed by every layout and fallback case.
+
+Complete validation runs on a stable executable candidate when preparing delivery/commit proof, when explicitly requested for full validation or timing, or when a specific cross-suite risk cannot be settled with focused evidence. [ADR 0039](0039-verify-documentation-without-runtime-suites.md) selects documentation checks for a strictly classified documentation-only delivery candidate. Use `verify` with unresolved findings and `check` otherwise. A valid result for an unchanged candidate is reused rather than repeating its component suites. A full failure returns to a discriminating focused check before the next stable-candidate gate.
+
+These rules change scheduling, not test obligations, ordinary/release discovery, coverage thresholds, independent review, ledger readiness or pre-commit authorization. Focused evidence never becomes a commit proof. [ADR 0026](0026-persist-the-delivery-verdict-against-the-verified-candidate.md) retains the review/proof contract, [ADR 0033](0033-gate-client-visual-usability-in-a-browser.md) retains complete browser validation and [ADR 0035](0035-run-coverage-only-before-a-new-release.md) retains release-only coverage.
+
+Runners expose inventory, concurrency and elapsed stage time. Agents wait on the existing process in intervals no longer than 60 seconds, remain responsive to new input, and inspect stage output when elapsed time exceeds expectations. A slow complete run does not authorize retries or a second concurrent copy.
+
+## Alternatives considered
+
+**Run a complete gate at the end of every development turn.** This makes turn boundaries, rather than candidate stability or delivery needs, determine expensive work and repeatedly verifies intermediate trees.
+
+**Remove complete backend or browser cases.** This reduces time by weakening acceptance. Bounded concurrency, disjoint semantic partitions and eliminating duplicated fixture generation preserve the original obligations.
+
+**Rely only on an instruction to choose focused tests.** A missing selector can still start the entire suite. Selection-required package entries reject that error before starting any tests or browsers.
+
+**Treat focused success as delivery authorization.** This conflates selected behavioral evidence with complete validation and source/index identity. The final gate and pre-commit proof remain required for delivery.
+
+## Consequences
+
+Development results explicitly cover selected responsibilities. Cross-suite regressions may first appear at the stable-candidate gate or CI. Contributors must select relevant owners and consumers rather than claiming whole-tree correctness from samples. Maintained commands and examples live in [verification](../verification.md); the agent entry rules live in `AGENTS.md`.

package/docs/adr/0037-keep-tool-hover-previews-passive.md

@@ -0,0 +1,52 @@
+# 0037 Keep Tool Hover Previews Passive
+
+## Status
+
+Accepted
+
+## Context
+
+Execution rows occur inside the conversation's scrolling surface. A pointer can
+cross a row because content moves beneath it. An interactive hover portal with
+its own scrollbar then becomes the wheel target, changing the meaning of a
+gesture already being used to browse the conversation. A longer delay alone
+does not preserve scrolling once that portal opens.
+
+## Decision
+
+Execution-row hover is a passive quick peek. The plugin owns a compact preview
+with bounded recorded source and result excerpts, explicit truncation text and
+a hint to expand the row. Neither the preview nor its descendants participate
+in pointer hit testing. Its layout uses clipping, not a scroll container. Full
+source, result, Copy and Inspect remain in the explicitly expanded row.
+
+`src/client-tool-hover.js` owns the lifecycle. A shared passive wheel/scroll
+observer cancels pending and visible previews. Scrolling must be idle before a
+fresh pointer movement or entry can start the next dwell; a stationary pointer
+does not reopen a preview after scrolling. Keyboard focus is an explicit
+request to preview. Escape, blur, pointer departure, expansion, touch and
+unmount retain dismissal and original expansion semantics.
+
+Use the platform's manual Popover top layer, with a public React Portal fallback.
+Placement measures only the plugin's anchor, pointer and preview. Prefer the
+right of the pointer when the current viewport has enough room; otherwise
+place above or below the row. Observe live owned-anchor and viewport size changes.
+A default-enabled interface setting controls mouse and keyboard preview without
+removing explicit row expansion. The plugin does not
+inspect or write Host ancestors, cancel scrolling, forward synthetic wheel
+events, patch Host packages or add another authority boundary. The interactive
+public HoverCard remains available to other consumers; it does not own this
+passive tool preview.
+
+## Consequences
+
+Users see a short preview on deliberate hover and browse or copy full content
+by expanding the row. Small viewports may clip more preview text or provide
+insufficient room for a preview; the complete row remains available. Excerpts
+are UI presentation and establish no claim about canonical value completeness,
+model knowledge or state retention.
+
+Browser evidence must use real wheel gestures over a scrollable conversation,
+including pending preview, visible preview footprint and stationary-pointer
+continuation. It must preserve keyboard/touch expansion and complete recorded
+content. Theme and viewport checks cover both native Popover and Portal fallback.

package/docs/adr/0038-freeze-session-capability-plans.md

@@ -0,0 +1,71 @@
+# 0038 Keep Session Capability Plans Stable
+
+## Status
+
+Accepted and integrated through the public prompt and execution seams. Frozen plans, scoped execution projection, shared loaders, persistent family statistics, refresh, description recovery and result previews have focused executable evidence in the [public-interface coverage](../context-public-interface-coverage.md). This ADR does not claim demonstrated ordinary-task token savings; the [implementation plan](../context-optimization-plan.md) distinguishes deterministic implementation from paid task calibration.
+
+## Problem
+
+PTC Plus can improve continuous computation while increasing the context consumed to complete ordinary tasks. Retaining the full native SDK and adding discovery instructions does not itself provide progressive disclosure. Conversely, hiding descriptions without making capabilities discoverable can cause additional exploration or incorrect calls. Shorter individual requests therefore do not establish a useful optimization.
+
+Capabilities also constitute the model's working environment. Redistributing them whenever statistics or saved settings change makes that environment unpredictable, even if each new distribution looks efficient in isolation. A capability advertised as removed must be absent from the supplied discovery and execution surfaces; a callable placeholder that rejects later does not establish that absence.
+
+[ADR 0043](0043-compose-capability-and-context-policies.md) extends new environments with independent availability/disclosure rules, allocation inputs, collection, recovery and preview selections. The contracts below remain the historical v1/v2 recovery basis; freezing, authority and observation boundaries remain applicable.
+
+## Decision
+
+The managed domain is the task capabilities that DSH and its other plugins expose to the model, including tools, Skills and MCP resources or resource templates where public owner surfaces permit consistent integration. JavaScript/TypeScript, Node, the REPL, PTC Plus's own public APIs and Global User Bindings remain outside this management domain. DSH retains authorization, policy, dispatch and lifecycle ownership. The plugin uses published public extensions of the current official Host and does not create a parallel dispatch registry or patch Host packages.
+
+Capability management has a total switch, independent statistics settings and independent manual configuration. There is no separate automatic/manual/off mode state. An explicit per-capability full, on-demand or closed selection wins over statistics. Invalid, disabled or unusable statistics leave manual configuration and its editable baseline effective. Automatic selection can choose full or on-demand disclosure; it cannot close a capability. Turning management off removes this feature's contribution while retaining DSH's authority and PTC Plus's separately configured computation behavior.
+
+Full disclosure supplies the complete owner-defined calling contract. For a Skill it supplies the full catalog description, while the instruction body still loads on use according to the owner's model/user invocation eligibility. A user-only Skill remains configurable but advertises its user slash entry rather than the model loader. On-demand capabilities remain discoverable through bounded navigation and search, with matching full contracts preferably returned in one interaction. Closing a capability consistently removes its descriptions, discovery entries and applicable runtime exposure, including REPL members. Public integration gaps cannot be relabeled as successful closure or filled with a second permission system.
+
+Automatic allocation uses session-family coverage rather than raw call volume. A root session and all its descendant agents contribute at most one use of a given capability. The denominator includes only families in which that capability was actually available. A tool use is a real call admitted to DSH’s around-execution pipeline with a final canonical outcome, including failed calls and valid wrapper-provided outcomes. It does not prove that the registered body ran or that an external effect occurred. Calls without execution admission and explicit pre-dispatch cancellation or unknown-tool outcomes do not create uses. Description inspection and cold replay do not create uses. Each capability and statistical scope uses its most recent configurable N eligible families, without wall-clock decay. Workspace evidence is primary; user-global evidence is a cold-start reference when local evidence is insufficient. An editable initial common set supplies the baseline when useful statistical evidence is absent, without fabricating observations.
+
+Allocation considers both coverage and contract length within a configurable explanation budget. The directory has its own bound; every long-tail name need not remain in the prompt. Explicit full disclosure overrides the explanation budget, with an observable overage rather than silent truncation or demotion. A budget overage does not establish that a request fits a model's physical context limit.
+
+A session capability plan records the effective enablement and disclosure choices when the session begins. Statistics and saved configuration do not redistribute an existing session, including after restoration. A user-triggered slash command explicitly refreshes the session. Refresh synchronizes descriptions, discovery and runtime exposure and supplies a durable, model-visible notification consistent with what actually became effective. A UI receipt alone is insufficient. Refresh uses Host lifecycle boundaries and does not require a paid model request merely to execute the human command. A stored plan cannot preserve a capability that its Host owner has actually removed or forbidden. Symmetrically, a live Host member that the frozen plan has not yet allocated remains declared under the Host's own presentation — or under its explicit availability closure — until refresh folds it into the plan; a pending allocation boundary never removes the member's identity from the declaration, discovery or dispatch surfaces. The frozen choice does not freeze the calling contract. Live parameter, output, instruction-dependency and Skill invocation changes append a validated `ptc-capability-contracts/v1` notification at an accepted step, retaining the original plan digest and current revision vector. Full choices receive complete replacement contracts; on-demand choices receive a revision notice and current discovery; removed capabilities receive a withdrawal. Saved settings and statistics still cannot reallocate that session. Unchanged views do not repeat notifications, and recovery uses visible validated notifications without rewriting the initial plan or prefix.
+
+Explicit session choices and saved choices have separate owners. `/capabilities set session <encoded-id> <full|on-demand|closed|automatic|inherit>` changes only the current session. `automatic` explicitly removes that identity's saved manual override from the effective input; `inherit` removes its temporary override and resumes the adopted source choice. Ordinary `/capabilities refresh` adopts current saved configuration while retaining temporary choices. `/capabilities set global <encoded-id> <full|on-demand|closed|automatic>` saves through the public revision-checked settings writer and updates this session in the same Host maintenance operation, clearing only that identity's temporary choice. Other existing sessions remain frozen. Server choices allow only `closed`, `automatic` and session `inherit`; their closure precedes child choices, and reopening preserves children.
+
+An initialized session publishes the complete new snapshot through its real append-only plan message. Before the protected system head exists, the formal `/capabilities` command returns its validated pending proposal in the structured receipt inside `CommandResult.text`; the Host alone records the paired `command/run` and successful `command/done`. These log-only command facts are not model knowledge. The first accepted step publishes that proposal to the model. Restoration reads successful receipts with exact command identity and raw input pairing, and plan messages, in order after the most recent explicit provider disablement; a routine provider release (`unloaded`) is an infrastructure fact and keeps the recorded plan as the session's restored baseline, so saved configuration still does not redistribute a resumed session. Restoration validates source/effective equality and the planner result, and does not repeat a global write, load a Skill body or execute a historical effect. Failed, cancelled, unpaired or damaged command facts cannot prove a choice; an unconfirmed live proposal is discarded before a later accepted step, and a late handler result cannot revive it. External plugins must not call `appendPluginRecord`, even though it is exported. History observations use the public `sessionQuery` cut; new production reads do not use deprecated synchronous Session readers.
+
+All mutations use public `agent.runMaintenance`, which may reject a busy Agent. The plugin does not queue another session scheduler. Identity, inventory and management preflight precede a global write; the write uses the settings entry's actual namespace and revision. Global saving and session publication are different transactions: a saved choice remains saved if subsequent publication is refused or cancelled, while the old effective environment is retained and the receipt reports saved-but-not-applied. No automatic rollback overwrites a later settings writer. A committed operation followed by lost UI connectivity has an unknown UI outcome, so users inspect the actual plan before retrying. Target-specific read-only catalog commands include closed items for user re-enablement without publishing them to model discovery or counting them as use.
+
+The existing prefix contract remains in force: unchanged configuration, model route and native capability view produce byte-stable plugin system text and ordered tool schemas. Statistical observations and session-plan facts belong in source-backed, reconstructable session contexts; treating a different plan as a new exception to prefix stability is not permitted. Reducing the original native SDK requires an owner-compatible public composition path, not a duplicate catalog appended beneath the unchanged full SDK.
+
+Initial plans retain the v1 format. Explicit session choices use `ptc-capability-environment/v2`: `sourceSettings` is the adopted frozen saved configuration, `sessionOverrides` is the session-only input, and `settings` plus `plan` are validated derivatives. Plans are assembled before the first model request. Through the public accepted-step batch, the initial plan precedes task-dependent messages when no task history has been committed, after the Host-owned protected system head. Bounded navigation uses concise purpose guidance for available capability categories, rather than copying per-capability descriptions or selecting long-tail entries by identity and fit. It depends on configuration and inventory rather than automatic membership. Explicit full contracts precede selected baseline contracts and other automatic additions, with stable identity ordering and shared dependencies supplied once. Statistical counters and source digests do not enter rendered text. This extends reusable prefixes across different tasks and preserves earlier groups when statistics change; it does not promise provider cache hits. Full owner descriptions belong in full disclosure or requested discovery, not in the category directory. Existing sessions remain frozen, refresh and recovery append after retained history. Recovery validates the initial format, derived plan and exact rendered body. New snapshots record their navigation text; existing v1 snapshots without that field retain the previously emitted navigation contract.
+
+After compaction, a separate bounded description-recovery operation may restore recently actually used, previously expanded and still-valid API descriptions. It deduplicates against the model-visible surface, does not redistribute the session plan and does not automatically restore Skill bodies. This is not authorization to add a default REPL state projection or weaken binding provenance requirements.
+
+Large model-facing results and logs use bounded previews with retrieval of retained complete presentation content through existing Host facilities. Omission does not alter canonical program values or turn successful computation into failure, and retrieval does not rerun the original operation. Formatted retained text is not a substitute for canonical typed values.
+
+The acceptance target is non-regressing quality and lower complete-task token consumption than native PTC with PTC Plus disabled on representative ordinary tasks. Accounting includes actual descendant agents, exploration, retries and all observable model requests, with cached input, uncached input and output reported separately. Missing usage remains unknown. Plugin-specific success, fewer prompt bytes and a higher cache-hit rate cannot substitute for this target.
+
+MCP management has two levels. A `mcpServers.<server>: closed` manual control disables that server's tools and resource access before per-member disclosure choices are applied. Removing the server control restores the saved per-tool selections; it does not rewrite them. Membership is captured from the public MCP server directory or attributed MCP sections and the registered qualified tool namespace, and recorded as optional `mcpServer` evidence in the frozen inventory. Ambiguous namespaces cannot be closed by guessing an owner. Previously recorded inventories without this field retain their original per-member semantics. Server controls are configuration identities, not callable capabilities or new tool schemas. Settings can observe the Host's unprojected prompt sections through a plugin-defined public assembly context that bypasses PTC session preparation; observation neither freezes a plan nor loads binding inputs. Saving either level retains the existing new-session/explicit-refresh boundary.
+
+## Alternatives considered
+
+**Keep the full SDK and add more discovery guidance.** This preserves easy direct access, but adds an explanation path without removing the original context cost. Current discovery remains a useful implementation input; its existence is not evidence of progressive disclosure or savings.
+
+**Make every capability on demand.** This minimizes the initial catalog but can force repeated discovery for common work. A bounded common set with manual overrides and measured coverage addresses both initial cost and later interaction cost.
+
+**Continuously redistribute active sessions.** Reacting immediately to statistics or saved settings makes allocation current, but changes the environment beneath ongoing computation and harms prefix stability. New-session planning plus explicit refresh and deliberately scoped human choices preserves predictability.
+
+**Expose three mutually exclusive management modes.** Automatic, manual and off outcomes are already derived from the total switch, statistics and manual settings. Persisting another mode introduces redundant state and obscures the independent validity of manual configuration.
+
+**Hide descriptions and reject later calls.** This leaves the execution environment inconsistent with the advertised absence and adds a policy layer that DSH already owns. Closure requires removal from the supplied surfaces.
+
+**Rank raw calls globally with time decay.** Repeated calls and large agent families can dominate the ranking, project differences disappear, and an idle project loses its baseline without new evidence. Bounded family contributions, workspace-first scopes and eligible-family windows address those specific distortions; they do not claim to measure latent task demand without bias.
+
+**Restore every expanded contract or Skill after compaction.** This can recreate the context growth that compaction removed. Budgeted recovery of actual recent API use retains useful instructions while leaving other descriptions and Skill bodies on demand.
+
+**Lower execution-output limits to constrain prompts.** An execution or transport failure has different consequences from a presentation omission. Separate preview budgets preserve computation and retrieval semantics.
+
+**Conflate temporary choices with saved configuration.** It leaks one session's intent to new sessions and named configuration exports. Separate source settings and explicit temporary inputs preserve scope and reconstructable allocation.
+
+## Consequences
+
+The model receives a more predictable environment and users can inspect and override allocation. Implementation must jointly prove presentation, discovery, execution, refresh and restoration behavior rather than treating prompt editing as sufficient. Skills, shared MCP loaders, scoped tool registrations and retained runtime references require explicit public-surface evidence before complete coverage can be claimed.
+
+Statistics require durable identity, bounded family accounting and a usable fallback. The [component contracts](../capability-planning-components.md) define family settlement and capability revision handling; `/capabilities refresh` implements the explicit session transition, with evidence in the [public-interface coverage](../context-public-interface-coverage.md). Contract budgets and discovery can themselves affect observed usage, so calibration must measure quality and whole-task cost rather than optimize coverage scores alone. Default parameters still require ordinary-task calibration; no unmeasured numeric default is established by this ADR.

package/docs/adr/0039-verify-documentation-without-runtime-suites.md

@@ -0,0 +1,29 @@
+# Verify documentation without runtime suites
+
+## Problem
+
+A document-only commit previously ran every backend and browser test to obtain its source-bound proof. Those suites cannot establish whether prose, links or contributor instructions are correct, and unrelated environment failures can block a documentation correction. Moving procedures out of the default agent entry also has little benefit if every verification action reloads review coordination and release instrumentation details.
+
+## Decision
+
+`check` compares the complete source inventory against HEAD, including additions, deletions, untracked source files and Git modes. Only regular non-executable Markdown changes under `docs/` or in the four root documents `AGENTS.md`, `CONTEXT.md`, `README.md` and `README.en.md` select documentation verification. Every other change, an unborn HEAD or an unchanged candidate selects full verification. Templates and test fixtures are executable inputs to their consumers and are not classified by their Markdown extension alone.
+
+Documentation verification checks diff whitespace, local link target existence and literal npm script references in changed documents and their referrers. It does not execute examples or contact external services. Independent review establishes semantic accuracy, instruction routing and heading-anchor correctness. `verify:docs` exposes this path for development and rejects a mixed candidate before launching any runtime suite. `verify` continues to request full behavioral validation explicitly; `check --full` requests full validation with a source proof even for documentation changes.
+
+Both `check` branches retain ledger readiness and source/`HEAD` stability, but `check` does not enforce independent review or staged-tree identity. `review:finalize` enforces the recorded independent review plan and lane evidence after the proof exists, and pre-commit enforces exact prospective-index identity against the staged tree. The verification proof records the chosen scope as `documentation` or `full`; a documentation proof makes no claim about runtime test success. Existing proof identity and review invalidation rules remain in [ADR 0026](0026-persist-the-delivery-verdict-against-the-verified-candidate.md). This changes the documentation delivery branch of [ADR 0036](0036-separate-focused-development-from-delivery-verification.md); executable changes retain the complete delivery gate.
+
+The default agent entry routes verification selection to `docs/verification.md`, review-state actions to `docs/review-procedure.md`, and release coverage to `docs/release-coverage.md`. Applicable requirements stay mandatory at their action boundary. Old verification section links remain as short forwarding sections. Test descriptions state the operation and observed contract; exact APIs, source fixtures, diagnostics and security properties remain accurate.
+
+## Alternatives considered
+
+**Run all runtime suites for every document change.** This spends time on an unchanged implementation while leaving documentation correctness to the same review still needed afterward.
+
+**Permit manual hook skipping for documentation.** An exception can finish one commit but supplies no durable classification, source proof or repeatable validation path. The scoped check preserves those checks without requiring another exception.
+
+**Classify every Markdown file as documentation, or inspect only the staged diff.** Test fixtures, templates, modes and unstaged source changes can affect executable behavior. The complete source inventory and explicit path boundary keep these changes on full verification.
+
+**Automatically treat all test-name and comment edits as documentation.** Names participate in selectors and fixture exports, and source-looking comments or strings may themselves be test inputs. Development uses focused evidence; test-file changes retain full delivery verification.
+
+## Consequences
+
+Documentation delivery no longer depends on browser, runtime or cross-platform evaluation prerequisites. The checker proves mechanical references only; reviewers still need the affected contract owners. Executable changes can still expose cross-suite failures at the final gate. Reference routing reduces default reading without changing who owns a requirement, and does not establish provider acceptance rates or actual model-token savings.

package/docs/adr/0040-separate-capability-configurations-from-session-observations.md

@@ -0,0 +1,39 @@
+# 0040 Separate Capability Configurations From Session Observations
+
+## Status
+
+Accepted.
+
+## Context
+
+The settings must distinguish reusable user choices, actual statistical evidence and a session’s frozen effective environment. Configuration-only statistics and budgets cannot explain allocation, and a session-plan list alone cannot provide named portable configurations.
+
+[ADR 0043](0043-compose-capability-and-context-policies.md) extends new environments with independent availability/disclosure rules, allocation inputs, collection, recovery and preview selections. The contracts below remain the historical v1/v2 recovery basis; freezing, authority and observation boundaries remain applicable.
+
+## Decision
+
+Named capability configurations are reusable settings, separate from a session's frozen effective plan and from actual usage evidence. The `capabilityProfiles` setting contains a `ptc-capability-profiles/v1` document with a `profiles` array. Each entry has a unique `id`, a unique trimmed `name` of at most 80 characters, and a `configuration` containing only management enablement, manual baseline/overrides, statistics settings and context budgets. The library contains at most 100 entries. The runtime configuration owner validates the format and settings. It contains no session identity, usage observations, program values, messages, provider choices or credentials.
+
+Saving under an existing name explicitly replaces that configuration. Renaming and deleting change the library only. File import validates before writing, assigns fresh identities and disambiguates duplicate names; it never switches the active settings. Export includes the selected configuration or the whole library. Import files are limited to 2 MB. The Client serializes these documents; users do not enter JSON.
+
+Switching a configuration applies its complete capability settings through one public DSH settings mutation. The library itself does not enter capability configuration revisions, system text or model context. Existing sessions retain their frozen plans until an explicit Host-owned refresh. Inspection returns the recorded source settings alongside the effective plan so users can name and save a copy; copying excludes session-only overrides, usage evidence and computation state. The copied source settings remain distinct from the effective settings derived with temporary choices. Settings containing invalid statistical parameters cannot become a reusable configuration until corrected, while runtime allocation retains its existing manual fallback.
+
+The read-only `allocation` operation observes an explicitly selected active PTC session's current public capability inventory and workspace/global statistical coverage, then calls the existing pure capability planner with the settings being previewed. The observation context skips session preparation and binding loading. It does not freeze, publish or refresh a plan, register sample eligibility or use, load Skill bodies, execute capabilities or start model requests. A removed target or cancelled observation cannot publish a preview. Client replies are invalidated when target, settings, visibility or plugin state changes.
+
+Statistics display actual uses and eligible session-family counts, with unavailable and incomplete evidence explicitly distinguished from zero use. Budget preview displays exact shared contract totals, allocation choices and reasons. Per-item body sizes exclude shared dependencies and rendered headings; the overall total includes them. Recovery and result-preview budgets cannot predict future content and are presented as limits, not fabricated forecasts.
+
+## Alternatives considered
+
+**Treat frozen session plans as reusable configurations.** A frozen plan includes inventory revisions and usage-derived choices that are specific to that session. Saving its source settings preserves user choices without presenting old evidence as current.
+
+**Refresh or prepare a session to preview allocation.** Those operations publish model context and register eligibility. Read-only observation through the existing inventory and planner provides the preview without changing the session.
+
+**Apply each configuration field separately.** Intermediate settings can form an unintended combination. One public settings mutation applies the complete configuration together.
+
+## Consequences
+
+Configuration libraries introduce a bounded validated settings format and explicit file import/export. Observation requires an active PTC session to supply its actual inventory and workspace; without one, the UI asks for a target rather than inventing statistics or allocation. Existing sessions still require explicit refresh after settings change.
+
+## Evidence
+
+The configuration, observation, Client lifecycle and browser contracts are exercised by `test/runtime-config.test.js`, `test/capability-environment.test.js`, `test/client-runtime.spec.js` and `scripts/client-fallback-smoke.mjs`. [ADR 0038](0038-freeze-session-capability-plans.md) continues to own freezing, statistics and explicit refresh semantics.

package/docs/adr/0041-record-cell-execution-directories.md

@@ -0,0 +1,65 @@
+# Record Cell Execution Directories
+
+## Problem
+
+DSH's working-directory service owns the current execution directory. The
+immutable Session header still identifies the original project. A persistent
+kernel that uses only that header sends new relative operations to an obsolete
+directory. Resetting the kernel after a change loses continuous computation;
+replaying all old cells from the new directory changes their source meaning.
+
+## Decision
+
+The resolved execution request supplies each live cell's directory. The runtime
+validates it before preparation and retains the header only as the historical
+fallback for hosts without a current-directory request. The kernel's queue
+passes each directory to the compiler and worker without replacing the kernel,
+bindings or module graph. New isolated computations inherit the requesting
+cell's directory. The plugin never changes the Session header, write roots or
+DSH directory state.
+
+Journal v11 adds required `executionCwd`, an absolute string or `null`. New
+cells record their resolved directory; `null` retains the historical
+header/worker fallback when no directory was supplied. Closed v1–v10 inputs
+migrate to `null`, preserving their original source base, language and transform.
+Missing or malformed v11 directory evidence invalidates historical recovery
+under the existing contraction rule. Replay selects each journal's recorded
+directory, independently of the current request.
+
+Stable Node wrappers read the worker execution owner's current directory at
+the operation. Relative filesystem and path operations, `process.cwd()` and
+new child processes follow it; explicit paths/options and already-created
+processes retain their own semantics. An immutable `process.cwd` function can
+report successive recorded directories without replacing its descriptor. A
+confirmed in-cell `tools.working_directory` result is adopted for the remainder
+of that cell, so the cell's relative operations and the Host tools, which
+resolve at call time, share one directory; the journal records the call and its
+result as the transition evidence while `executionCwd` remains the cell's
+starting directory.
+
+Each cell's static adapter, dynamic import environment, synthetic `import.meta`
+and provided `require` capture that cell's module source base. Retained module
+objects and escaped import/require functions keep their bases. Dynamic lexical
+environments propagate their captured importer through activation, parameters,
+eval, context and object scopes. Native module files continue resolving their
+own imports from their actual URL. The shared public Node hook rewrites only
+identified adapters, rather than treating every occurrence of a REPL parent
+URL as the current cell.
+
+Skill inventory reads the public working-directory service after Host prompt
+assembly. Catalog observation and explicit refresh therefore see the current
+directory. A directory change does not reallocate the frozen session plan.
+Usage statistics retain the original project as their workspace scope.
+
+## Evidence
+
+`test/plugin-durability-recovery.test.js` compares two directories with same-name
+files/modules, escaped imports, eval imports, saved require, new child
+computations and continuous bindings; a separate cold replay uses a third
+current directory. The same file verifies that one confirmed in-cell directory
+change rebases relative reads while imports keep the starting directory, that a
+failed change does not rebase, and that cold replay settles the recorded
+transition identically. `test/session-journal.test.js` verifies closed predecessor
+migration and malformed/missing v11 rejection. Capability tests distinguish
+current Skill inventory, frozen plans, explicit refresh and project statistics.
+These focused tests do not establish packed Host or Windows compatibility.

package/docs/adr/0042-persist-provider-availability-and-handback.md

@@ -0,0 +1,41 @@
+# 0042 Persist Provider Availability And Handback
+
+## Status
+
+Accepted.
+
+## Context
+
+Historical capability plans, global API catalogs and computation journals can remain visible after PTC Plus releases its provider. Correct teardown of workers and registrations alone does not tell a later native request that these declarations are historical. A plugin that has already been destroyed cannot notify that request.
+
+## Decision
+
+Provider availability is a source-owned append-only fact, distinct from computation values, configuration receipts and capability-management enablement. A `plugin:ptc-plus` message with `form: runtime-availability` and `state: active | disabled | unloaded` has an exact validated body. Withdrawal makes earlier plugin continuous-computation instructions, capability plans, discovery and calling disclosures, and configured binding references inapplicable to the current runtime. It preserves tasks, Skill bodies, other producers, tool results and historical effects; it does not restore or undo a heap.
+
+The passive runtime-message owner publishes disablement or resumed availability only through a witnessed, accepted, non-aborted Host step. Rejected, paused or cancelled proposals do not become delivery. Existing plugin declarations or a plugin journal namespace establish prior provider participation; journal presence does not prove any binding recoverable, initialized, live or known to the model. Repetition does not append a duplicate withdrawal. Re-enablement cannot restore a capability plan preceding the last validated withdrawal.
+
+Complete plugin release first awaits the existing runtime controller's worker and registration cleanup, then persists unloaded availability while public session services remain available. Loaded sessions use their real Session append and Host flush. Unloaded stored sessions use the public persistence list and exclusive write handle, validate their surface with public pure interpreters, and append their own new withdrawal fact with append/flush/close. No Agent is created, model awakened, effect replayed, event sequence fabricated or second session coordinator introduced.
+
+The lifecycle owner captures the public session, query and persistence services while they exist, rather than looking them up after removal. Loaded history uses a public immutable query cut. Offline handback is a new fact written by the releasing provider, not a Session resume: the exclusive public write handle supplies validated stored events and their next offset; `foldSurface` and `deriveEventMessage` apply installed first-party and live registered pure interpreters; `snapshotSessionEvent` validates the producer's own new `user/message` envelope; the extended surface is validated before `handle.append`, `flush` and `close`. It does not instantiate or publish an offline Session, invent a foreign resume marker, impersonate a user or command, or use deprecated synchronous readers. A loaded session whose query dependencies are already destroyed still reports that failure; retaining a service object does not recreate its dependencies.
+
+Each session is independent. A writer conflict, damaged storage, flush refusal or unavailable public persistence ownership remains a real handback failure; cleanup continues for other sessions and aggregates these failures. The plugin never steals another process's writer. Successful in-memory append alone is not crash-durable evidence. Parent-service shutdown or external ownership can prevent persistence, so complete handback cannot be claimed in those cases. The failure must remain observable to the Host lifecycle owner; no promise is made that a destroyed dependency can still write.
+
+User binding toggles publish a separate configuration receipt only after storage confirms the revision and entry. A public Conversation definition renders the source-validated receipt as its own visible node using current Client locale. The receipt proves saved enablement only; model catalog delivery still follows accepted-step publication and worker initialization still follows actual execution. It has no turn-trigger identity and does not wake a task. Capability command receipts similarly distinguish updated, pending first acceptance, unavailable, invalid usage, and globally saved but not applied states.
+
+## Alternatives considered
+
+**Erase historical messages or bindings on unload.** It destroys audit facts and implies rollback of effects. A new availability fact changes present applicability while retaining history.
+
+**Notify from the next Agent after destruction.** The producer no longer exists; limiting handback to active Agents also misses loaded and offline sessions. Public Session and persistence owners can persist the transition before release without a task wakeup.
+
+**Steal offline ownership or edit JSONL files.** It bypasses the Host's single-writer and validation contracts. Refusal is preserved and reported, not converted to successful handback.
+
+**Use user/command/turn-trigger events for a binding toggle.** It confuses saved configuration with task initiation and may wake a model. A separately sourced fact and public renderer preserve both lifecycle and visibility.
+
+## Consequences
+
+Availability is reconstructable in native sessions after plugin removal without a plugin-specific projection interpreter. A declaration withdrawal cannot preserve the old continuous heap, prove source knowledge, provide missing Host tools or solve the independent top-level editor admission boundary. Persistence failures are explicit partial lifecycle outcomes.
+
+## Evidence
+
+`test/runtime-messages.test.js`, `test/capability-environment.test.js`, `test/user-bindings-owner.test.js` and `test/client-runtime.spec.js` exercise accepted publication, restoration, storage confirmation and locale rendering. Actual public JSONL persistence and full Loader removal require current packed-Host integration evidence; fixtures do not stand in for that boundary.

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

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

package/docs/adr/README.md

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