dsh-ptc-plus 0.4.8 → 0.5.0

package/cordis.patch.yml

@@ -1,5 +1,16 @@
-# Attach the session REPL after both the tools registry and Code Runtime exist.
-# The plugin adds a virtual rejected-cell edit transport beside DSH's run_code.
+- id: ptc-runtime
+  isolate:
+    ptcRuntime: ptc-plus-original
+
 - insert:
+    - id: ptc-plus-execution
+      name: dsh-ptc-plus/execution-provider
+      intercept:
+        loader:
+          await: false
+      config:
+        originalEntryId: ptc-runtime
+        serviceName: ptcRuntime
+        isolation: ptc-plus-original
     - id: ptc-plus
       name: dsh-ptc-plus

package/docs/README.md

@@ -6,10 +6,12 @@
 - [Global binding guide](user-bindings.en.md) ([中文](user-bindings.md)): author, review, save, configure, and test reusable helpers.
 - [Runtime Reference](runtime-reference.md): cell behavior, capability discovery, configuration, diagnostics, and limits.
 - [Evaluation](evaluation.md): paired ordinary-task protocol, metrics, configuration, and limitations.
+- [Command Goat / DeepSeek V4.1 Flash evaluation](evaluations/command-goat-deepseek-v4.1-flash.md): paid main/child acceptance, two retained A/B cohorts, independent audits, measured benefits and limits.
 
 ## Design
 
 - [Architecture](architecture.md): ownership boundaries, prompt-prefix stability, runtime lifecycle, journals, and recovery.
+- [Context management](context-management.md): model-facing layers, evidence limits, progressive disclosure, and measured optimization rules.
 - [Capability Surface](capability-projection.md): typed program bindings and progressive discovery.
 - [Program Data Plane](program-data-plane.md): canonical values and result completeness.
 - [Durable / Volatile Recovery](durability-design.md): replay model and external-input boundaries.
@@ -22,9 +24,12 @@
 
 ## Maintenance
 
-- [Deterministic Verification](verification.md): complete checks, backend test concurrency, coverage, and focused diagnostics.
+- [Verification selection](verification.md): documentation checks, selection-required diagnostics and complete behavioral validation; read the applicable procedure before its action as routed by [the agent contract](../AGENTS.md).
+- [Findings and independent review](review-procedure.md): findings lifecycle, lane evidence, source proof and commit authorization.
+- [Release coverage](release-coverage.md): release-only coverage commands and verification implementation details.
+- [Client Visual Contract](client-visual-contract.md): browser prerequisites, control and state coverage, fault counterexamples, and packed Host evidence boundaries.
 - [Incremental Review Verdict](adr/0026-persist-the-delivery-verdict-against-the-verified-candidate.md): predeclared parallel lanes, dependency-scoped invalidation, and the composite commit verdict.
-- [Focused Verification](verification-optimization-work.md): bounded coverage diagnostics and their relationship to the final verification gate.
+- [Focused Verification](verification-optimization-work.md): bounded coverage diagnostics during new-version release preparation.
 - [Semantic Validation](semantic-validation.md): pinned Test262 cases, dialect contracts, native differential matrices and their limits.
 - [Publishing](publishing.md): release checks, package contents, permissions, and platform validation.
 - [GitHub Release Notes](release-notes.md): user-perspective priority order, required sections, bilingual style, and a worked example for release notes.

package/docs/adr/0005-temporary-rejected-cell-edit-transport.md

@@ -1,189 +1,41 @@
-# Register Edit And Run As A Truthful Composite Tool
+# Execute Rejected-Cell Edits Through The PTC Program SDK
 
-A small correction to a long `run_code` cell should not require the model to emit the complete
-source again. This applies both to cells rejected by the runtime and to cells that completed but did
-not achieve the intended result. PTC Plus therefore registers `edit_run_code` as a real DSH tool:
+A small correction to a long `run_code` cell should require only a delta. The official PTC presentation admits `run_code` as its sole top-level tool and exposes registered native tools inside its program SDK. PTC Plus registers `edit_run_code` in the agent scope before the first prompt assembly. Models call it through `tools.edit_run_code` in any ordinary JavaScript expression inside a `run_code` cell; aliases and computed member access retain the same meaning. The plugin does not use the unpublished `both` presentation or add a top-level editor schema.
 
 ```ts
-edit_run_code({
-  edits: Array<{ old_string: string; new_string: string }>,
-  expected_target_call_seq?: number
-})
-
-edit_run_code({
-  regex_edits: Array<{
-    pattern: string
-    flags: string
-    replacement: string
-    expected_matches: number
-  }>,
-  expected_target_call_seq?: number
+await tools.edit_run_code({
+  edits: [{ old_string: 'value >= 8', new_string: 'value >= 10' }],
+  expected_target_call_seq: 12, // optional stale-target guard
 })
 ```
 
-PTC mode requests using the code-only direct-tool projection expose `[run_code, edit_run_code]` in
-that order. The first conclusive prompt assembly creates one per-agent composition owner before any
-plugin-owned presentation effect changes the nearest DSH scope. A non-empty `tools:ptc-only`
-section proves `ptc`, an empty section proves `both`, and the preceding generation's
-`tools:code-only` alias proves the same composition; the current section wins when both appear, and
-only a missing owner signal permits a tool-shape inference. For a code composition, the same owner
-registers `edit_run_code` through `agent.ctx.tools.register()` and uses the same scope's
-`tools.presentAs('both')` to admit both direct calls. It retains both exact disposers and releases
-registration and presentation together with the owning session, agent, or plugin. Native-mode and unrelated agent
-scopes never inherit the tool. Unrelated native tools remain in the program SDK. A top-level native call is outside that
-valid direct protocol. The stream canonicalizer may deliberately replace it with the equivalent
-`run_code` transport when the live schema uniquely proves the native member; otherwise the call
-remains unchanged for host diagnosis. A nested native call from a cell continues through the
-ordinary DSH pipeline. Each assembly derives its `native`, `code`, or `both` presentation from the
-lifecycle owner rather than inferring composition mode again from the plugin-modified scope. Only
-`code` collapses direct tools, normalizes top-level native calls, or
-rejects native dispatch. Both PTC presentations adapt `run_code`, append the program SDK, and
-project session runtime contexts, while `both` also preserves native direct calls. The initial
-transport-only shape may bootstrap the first scoped registration, but the resulting
-`tools.presentAs('both')` declaration is only the executor-enabling effect for the two transports
-and cannot become a second mode owner. Each completed prompt assembly therefore preserves the
-agent composition's direct projection without releasing the per-agent registration. The
-model stream binds every complete tool call's session and call ID to that assembly policy, and
-execution consumes this stable relation even when another public wrapper replaces the cancellation
-signal. A settled result retires the relation. The retained registration does not authorize the
-tool outside a code composition, and one shared session lifecycle revokes outstanding request and
-call records on session, agent, or plugin disposal.
-
-`edit_run_code` targets the most recent editable cell in the current turn when its persisted
-`tool/call` event is recorded. Execution resolves that snapshot through the event sequence rather
-than reading the latest target when the handler begins. Intervening inspection tools do not erase
-the target, and later settlements or handler scheduling do not retarget the in-flight edit. A call
-that could otherwise edit a cell but lacks a unique persisted event is rejected instead of using
-the latest target. The derived cell enters replay history at the outer `tool/result` event, so a
-delayed handler is recovered after every cell that settled before it executed. A successful edit
-creates a new derived cell, which
-becomes the next editable source, so successive small adjustments do not require a full resend.
-Invalid edit arguments return `{ edited: false, reason }` and leave the target unchanged.
-Process-local target claims distinguish executing and settled derived dispatches. A rejection,
-cancellation, or result without a valid PTC journal releases the claim because no owned fact proves
-that the derived cell entered the runtime. A journaled dispatch retains the claim through outer
-result projection, closing the interval before the session log exposes the derived edit as the new
-target. If final policy removes that private metadata, `tools/result` releases the claim. The
-session-log projection captures the eligible target at the edit call event and accepts a derived
-source only when its target sequence matches that snapshot and its journal is valid and non-noop,
-so live and recovered eligibility derive from the same persisted relation.
-
-The public schema is one closed object with optional `edits`, `regex_edits`, and
-`expected_target_call_seq` properties, avoiding duplicated object alternatives in the provider
-prompt. Runtime validation still requires exactly one of `edits` or `regex_edits`, plus an optional
-non-negative `expected_target_call_seq` precondition. The precondition must equal the call sequence of the target
-captured for the persisted edit event; a mismatch returns an unedited result before derived
-dispatch. Ordinary model-authored edits omit it and retain latest-target selection. Exact edits
-contain at most 16 items; each
-non-empty `old_string` must differ from `new_string` and occur exactly once in the target. Regular
-expression edits also contain at most 16 items, use unique `gimsu` flags, reject zero-length matches,
-and require an exact `expected_matches` count. All ranges resolve against the original target and
-must not overlap. Search work, match count, capture records, replacement templates, expansion,
-materialized replacement text, final source size, and regular-expression CPU time have fixed
-budgets.
-
-`internal/rejected-cell-editor.js` owns the schema, validation, range collection, replacement
-semantics, budgets, and atomic linear assembly. The registered tool passes the materialized source
-to DSH's public `tools.execute()` as a derived `run_code`. DSH remains the owner of validation,
-authorization, scheduling, cancellation, execution, and result projection.
-
-The session history preserves the model-authored call:
-
-```text
-assistant/tool-call: edit_run_code(delta)
-tool/result:          { edited: true, value?, error?, logs }
-```
+## Public integration status
+
+DSH's published `ptc` mode owns the top-level `run_code` transport and the nested tool scheduler. The editor's registration is agent-scoped, and the official SDK includes its schema before the first model request. Nested dispatch passes the original tool name and JSON arguments through DSH validation, policy, scheduling, cancellation and result projection. The same configured agent has a stable `run_code`-only direct schema across requests. The first and later prompt assemblies must expose the same editor SDK contract.
+
+## Edit and settlement
+
+The editor captures the most recent eligible cell at the persisted `tool/ptc-dispatch-start` event. It identifies that event by root, parent and sub-call IDs, exact arguments and sequence. Intervening native calls do not change the target. An optional `expected_target_call_seq` must match the captured target. An unavailable target, invalid edit or mismatched guard returns `{ accepted: false, scheduled: false, reason }`; no derived source executes.
+
+The editor accepts exactly one `edits` or `regex_edits` array. Exact edits require unique nonempty `old_string` matches. Each regex edit requires `pattern`, `flags`, `replacement` and `expected_matches`; replacement uses JavaScript `$1`, `$<name>` and `$$` syntax. At most 16 nonoverlapping edits are applied atomically. `internal/rejected-cell-editor.js` owns matching, expansion and CPU/source budgets.
+
+For an accepted edit, the nested SDK call returns `{ accepted: true, scheduled: true, target_call_seq }`. This is an acceptance receipt, not the revised computation's value or an idempotence promise. The current outer cell continues with its existing state and original return value or error. After that cell releases its worker, but before its top-level `run_code` result settles, PTC Plus dispatches the complete revised source through DSH's real `tools.execute({ name: 'run_code', ... })` pipeline. The root result retains that outer canonical value or error and forwards the derived result's Host-rendered content, images, additional contexts and, for a successful root result, turn-conclusion flag. The definition-owned `projectContent` callback is installed before dispatch starts, so derived content reaches root post-policy; `exec.deferContext` and `exec.concludeTurn` carry contexts and the successful root conclusion. Root policy may replace or block that presentation. The runtime bridge preserves existing callbacks and their property descriptors, restores only its own installed callbacks on disposal, and unwinds partial installation on failure. The next cell sees the revised bindings. A nested receipt rejected or changed before acceptance prevents dispatch; cancellation or disposal before dispatch does likewise. Removal of the final root metadata after a derived run has executed invalidates recovery evidence but cannot undo its effects.
+
+The model-authored outer `run_code` remains the sole top-level call in assistant history. Official nested events retain the editor's real name, arguments and settled receipt. The plugin records its actual derived `tools.execute` call through public `Session.append`: the start carries losslessly detached arguments, a distinct sub-call identity, the original root ID and that still-running root's ID as its parent. The actual execution uses the root's real token as `parent`. Its settled event records the canonical error status and metadata; rendered content passes through the public scoped `tools/ptc-dispatch-log` waterfall with the real root execution. A throwing log projector falls back to the original settled content. These records describe actual executions and do not invent an assistant call, parent or completion. Recovery proves exactly one start and one later settlement for each editor and actual derived sub-call identity within its root-call/final-result window. A metadata start sequence alone cannot resolve duplicate dispatch identities; settled ID reuse outside that window remains independent.
+
+If the public Host never invokes `presentationMeta` for this owned nested success, the bridge may capture its canonical frozen value and tentative settlement through the read-only pre-policy `projectContent` callback. Private evidence is admissible only for the exact execution token, session, parent and continuation, with no initial plugin journal, no subsequent projector call, unchanged base metadata, final success and the same canonical value object. Host value replacement, block/error, missing capture or removal of already projected metadata rejects it. The sidecar supplies only the plugin-owned actual derived settlement and root relation; it never changes the Host result or restores pre-policy content. Final root metadata remains required. The proof comes from public canonical value identity and the before/after policy callbacks, without a Host version branch.
+
+
+The root result's private `dshPtcPlusPostEdit` evidence keeps the editor cause in `startSeq` and the actual derived execution in `executionStartSeq`, alongside the derived source, journal and target sequence. Recovery validates both start/settle pairs, the root journal's accepted editor arguments and receipt, the canonical derived outcome and the transform against the captured target. It folds the derived journal after the root cell using the actual execution-start sequence. Model-visible provenance comes from the root source and the original target's source; raw dispatch records alone do not prove it. Losing either source or a required execution fact contracts the derived binding frontier. A failed start append prevents dispatch; a failed settlement append invalidates future recovery evidence without repeating or undoing an execution. Cold replay uses recorded nested results and does not redispatch the editor or repeat external effects. A successfully published derived source becomes the next editable target through its own execution-start sequence.
+
+The derived source itself may contain an editor call. Such a call does not gain a fresh root edit authority during the derived execution: it receives an unavailable receipt rather than recursively scheduling another derived run. Each model-authored root call can accept at most one deferred edit. This bounds recursion and prevents a derived call from resetting the root edit lifecycle.
+
+## Provider and diagnostic handling
+
+The stream adapter only repairs an exact invalid-tool-JSON `MALFORMED_RESPONSE`. A trusted complete `run_code` block may lose one extra final `}` when the resulting object passes its live schema. Otherwise complete consistent calls keep their identity and arguments for DSH validation. Incomplete or inconsistent buffered tool material becomes a deterministic schema-rejected `run_code` call, allowing the model another step without executing partial code. This rule never promotes an undeclared top-level `edit_run_code` into an executable call.
 
-The complete derived source, its journal, and its target call sequence are stored only in private tool-result metadata, including
-when the derived cell fails after entering the runtime. Cold
-recovery folds that explicitly marked derived run into the durable REPL history. The source is not
-copied into the model-visible edit result. Valid assistant stream chunks for the two declared
-transports pass through unchanged.
-Consequently the UI and later model requests do not attribute a generated `run_code` call to the
-model.
-
-The stream owner handles one bounded provider protocol failure before DSH assembles the assistant
-message. It buffers tool-call material until the terminal event. If the response reports the exact
-invalid-tool-JSON `MALFORMED_RESPONSE` as a terminal chunk or stream exception, it changes that
-terminal reason to `tool-calls`.
-DSH's existing Agent Loop
-then preserves an unparseable argument as a string and routes it through ordinary tool validation,
-execution, and result recording, after which the model receives another step. A malformed tool argument therefore
-cannot become a turn-ending provider failure merely because this adapter parses it earlier than the
-Agent Loop.
-
-The stream owner preserves calls only when the buffered body consists entirely of
-tool-call-specific framing plus at most one `usage` event. When that trusted body contains exactly
-one complete, internally consistent declared `run_code` or `edit_run_code` block, the stream owner
-first considers one correction: delete exactly one final `}`. The block index, call ID, name,
-concatenated deltas, and final arguments must agree, and the candidate must parse as an object
-accepted by that request's live direct-tool schema. A successful correction changes the final delta
-and final block arguments before the same `tool-calls` settlement. Without that proof, trusted
-internally consistent complete blocks retain their original identity and argument bytes for the
-ordinary tool-error path. The owner re-emits those calls with canonical
-`block-start`, full-argument delta, and `block-end` framing so provider variants tolerated by the
-assembler also satisfy DSH's stream invariant. A final `block-end` is canonical even when the
-provider emitted no deltas; when deltas exist, their supplied identity fields and accumulated
-arguments must agree with it. An already visible open text or reasoning block is closed from its
-accumulated content before the synthetic call. If any tool block is incomplete or inconsistent, or no tool block was
-emitted, more than one usage event appears, or any other event occurs in the buffered body, the owner
-removes unsafe block and unknown events, retains at most the first protocol-valid `usage`, and emits
-one deterministic `run_code` call with an argument string that cannot parse as a JSON object. That
-call can only fail DSH's ordinary schema
-validation, so no untrusted partial call executes and the model still receives another step. Valid streams and every
-other provider failure pass through unchanged. The rule does not insert missing delimiters, search
-arbitrary edits, reinterpret native calls, or retry effects.
-
-No edit-specific runtime context is emitted. The truthful call/result pair already carries the
-operation and outcome; changing an aggregate runtime-context snapshot merely to restate that fact
-would repeat unrelated policy context. Rewrite feedback and unrelated recovery tips retain their
-own independently justified lifecycles.
-
-A live `PTC-C001` at the exact source EOF may carry a validated one-call repair. The analyzer tries
-only the 12 suffixes of one or two closing tokens drawn from `}`, `)`, and `]` against the same
-binding catalog, reserved bindings, redeclaration mode, rewrite policy, and import state as the
-rejected cell. Exactly one candidate across both lengths must complete preparation without a binding
-collision, and the existing exact editor must be able to express it from a bounded unique source suffix. The rejected call must also have a
-persistent event sequence. The diagnostic then renders those already-validated
-`edit_run_code({ edits: [...], expected_target_call_seq })` arguments on one help line. At dispatch,
-the precondition binds the proof to that rejected cell even if another matching source has become
-editable. This evidence takes precedence over the generic source-length recommendation, but remains
-conditional on
-`edit_run_code` being declared for that request. Zero or multiple candidates, non-EOF errors,
-editor budget failures, missing target identity, and candidates rejected later in preparation
-retain the generic guidance.
-The plugin never applies this repair itself: syntax/preflight acceptance does not prove model
-intent, and explicit edit dispatch preserves DSH authority and truthful history.
-
-## Alternatives considered
-
-**Rewrite `edit_run_code` to `run_code` before persistence.** This reuses DSH's default `run_code`-only
-transport, but falsifies the model-authored history, duplicates complete source in model context,
-and requires later prose to reinterpret the stored call. It is rejected.
-
-**Return the materialized source in the edit result.** This makes the derivation visible, but sends
-the same large source back into the next model request. Private derived metadata gives recovery the
-required bytes without paying that context cost.
-
-**Limit editing to pre-execution failures.** That avoids retrying an effectful failed cell, but it
-also prevents the common case where execution succeeded and only the intended result needs a small
-adjustment. The tool edits the recorded source and performs a new explicit execution; it does not
-claim that the earlier execution was undone or idempotent.
-
-**Forbid all stream normalization.** A valid declared call and an invalid
-out-of-surface call are different protocol facts. Rewriting a real `edit_run_code` destroys a valid
-identity; normalizing a live-schema-proven native miscall to the declared `run_code` transport gives
-an otherwise invalid call its executable representation. Native-call canonicalization therefore
-remains available. The bounded malformed-input correction likewise retains a declared call's identity.
-Fallback settlement preserves arguments for trusted complete internally consistent blocks. Unsafe,
-partial, or mixed buffered material is replaced by a validation-rejected `run_code` call only after
-the provider itself reports the exact terminal protocol failure.
+At exact source EOF, a `PTC-C001` diagnostic may prove one closing-delimiter correction using the current preparation context and editor budget. It reports `tools.edit_run_code({ edits: [...], expected_target_call_seq })` arguments for use inside a new `run_code` cell. The correction is advisory: the model still selects whether to rerun a possibly effectful target. A failed or cancelled historical effect is neither undone nor safe to retry merely because the edit is syntactically valid.
 
 ## Consequences
 
-Tool name, schema, and order remain stable regardless of target availability. `edit_run_code` is a
-normal provider tool call, not a synthetic wire alias. The derived run is auditable and replayable,
-but is explicitly host-generated and excluded from model-visible history. This adds no editor DSL,
-authority layer, or retry guarantee; it only avoids re-emitting source already owned by the session.
-Provable top-level native-call repair remains a separate, intentionally history-normalizing transport
-feature.
+DSH retains authority over tools and the top-level PTC transport. The editor receipt is intentionally distinct from the later derived computation, and only the latter may establish revised bindings. The private evidence links source, nested dispatch, journal and model-visible ancestry without duplicating the full revised source in the model request.

package/docs/adr/0008-define-agent-operating-contract.md

@@ -6,7 +6,7 @@ PTC Plus needs a tracked instruction surface for product boundaries, source owne
 
 ## Decision
 
-`AGENTS.md` contains only obligations whose subject is PTC Plus: DSH authority, runtime and journal invariants, public source ownership, checkout-local review state, deterministic verification, documentation parity, generated-material exclusions, and delivery safety. It links the canonical product and architecture documents rather than duplicating their detailed behavior.
+`AGENTS.md` contains only obligations whose subject is PTC Plus: DSH authority, runtime and journal invariants, public source ownership, checkout-local review state, deterministic verification, documentation parity, generated-material exclusions, and delivery safety. It links the canonical product and architecture documents rather than duplicating their detailed behavior. The default entry retains invariant summaries, common focused commands, and explicit read-before-action links. [Verification](../verification.md) selects checks by change scope, [review procedures](../review-procedure.md) own findings and commit authorization, and [release coverage](../release-coverage.md) owns release diagnostics; paid evaluation setup lives in [evaluation](../evaluation.md). Their requirements apply whenever the corresponding action is taken, including documentation-only work. Loading is conditional on the task; applicability is not optional.
 
 Reusable maintenance methods remain outside tracked project sources. Local editor state and branch topology also remain checkout-owned. They may guide an individual maintainer, but project code, tests, hooks, and acceptance do not require their names, installation, or presence.
 
@@ -20,6 +20,10 @@ The tracked findings-ledger and review-plan templates and their lifecycle script
 
 **Keep generic methods as optional tracked references.** Optional wording does not change their public ownership or maintenance cost. Methods without a PTC Plus-specific executable consequence stay outside the repository.
 
+**Repeat every procedure in the default entry.** This loads review-state internals and release diagnostics into unrelated development tasks and gives the same procedure multiple maintenance locations. Explicit entry conditions keep the required procedure reachable before its first action.
+
 ## Consequences
 
 Contributors can determine the obligations needed to preserve PTC Plus without adopting a maintainer's agent stack, editor, model route, or branch workflow. Product semantics retain their canonical owners, while the public operating contract remains small enough to audit for contradictions and private-environment leakage.
+
+Task context names the concrete language or runtime operation and preserves exact interfaces and relevant failure evidence. Less repeated reference text reduces default context size; it does not establish model-token savings, task-quality gains, or a change in provider acceptance behavior. Those claims require their own observations.

package/docs/adr/0009-bound-expensive-acceptance-default.md

@@ -10,9 +10,9 @@ Each descriptor in `scripts/expensive-acceptance-scenarios.json` owns whether it
 
 Every expensive scenario and A/B task declares machine budgets for model requests, direct calls, source characters, repeated source, result characters, assistant characters, token traffic, and aggregate runtime-context characters. A model request is one logical loop step recorded by durable `step/start`; `request/header` records an initial, resume, or changed header epoch and is counted separately. Neither metric claims to count provider adapter attempts, because retries can make multiple attempts within one logical step without a distinct durable event. The shared acceptance contract treats an exceeded budget as a failure. It also attributes every aggregate runtime snapshot by named section, enforces allowed PTC Plus contribution names and bounds, and verifies required append, update, and clearance transitions. Edit-specific narration is never allowed.
 
-For a trajectory whose configuration, model route, and native capability view remain stable, the shared acceptance contract canonicalizes every `request/header` by DSH rules and compares exact system text and ordered complete tool schemas. An initial epoch establishes the baseline, an equal resume epoch reaffirms it, and every unapproved change epoch fails acceptance. A scenario that changes route, configuration, or capability declares the exact condition and epoch in `headerPolicy.allowedTransitions`; a scenario that replaces history declares the exact `headerPolicy.historyReplacements` count without relaxing header equality. Fingerprints are report metadata only; acceptance compares the canonical values and reports the first differing field.
+For a trajectory whose configuration, model route, and native capability view remain stable, the shared acceptance contract compares exact ordered system text from the public message surface and canonicalizes every `request/header` to compare ordered complete tool schemas. Current system text is carried by formal `system/message`, independently of header epochs; historical `header.system` is evidence only for its recorded older Session format. An initial epoch establishes the header baseline, an equal resume epoch reaffirms it, and every unapproved change fails acceptance. A scenario that changes route, configuration, or capability declares the exact condition and epoch in `headerPolicy.allowedTransitions`; a scenario that replaces history declares the exact `headerPolicy.historyReplacements` count without relaxing header or system-text equality. Fingerprints are report metadata only; acceptance compares the canonical values and reports the first differing field. [Evaluation](../evaluation.md) owns the current restoration, projection and request-boundary evidence details.
 
-The edit canary covers both a completed cell whose result needs adjustment and a runtime-rejected cell in one session. It requires the model-visible direct sequence `[run_code, edit_run_code, run_code, edit_run_code]`, each exact delta, private target and derived-run metadata, and no model-authored retransmission of either materialized source. Successful static-import and mixed-redeclaration rewrites retain result provenance without creating runtime-context transitions. The typed program-surface task requires focused discovery, schema inspection, native reading, and isolated execution in that order while rejecting unrelated capability expansion.
+The edit canary covers both a completed cell whose result needs adjustment and a runtime-rejected cell in one session. The current canary requires four model-visible `run_code` calls: execute each source, then invoke `tools.edit_run_code` once inside the following program. Each edit must preserve its exact delta, accepted nested receipt, actual derived execution pair, private target and derived-run metadata, without model-authored retransmission of either materialized source. The earlier direct-editor sequence remains historical transport evidence. Successful static-import and mixed-redeclaration rewrites retain result provenance without creating runtime-context transitions. The typed program-surface task requires focused discovery, schema inspection, native reading, and isolated execution in that order while rejecting unrelated capability expansion.
 
 Both model-backed runners complete keyless verification and resolved-config validation before model invocation. They then run one complete representative canary sequentially and audit its process result, session log, tool transport, runtime contexts, budgets, and task oracle before scheduling broader scenarios, replicates, or concurrency. A canary failure stops the run without starting the remaining paid work. Deterministic tests remain the authority for AST rewrite variants and the acceptance contract itself. The ordinary-task A/B canary is the stable fixture's fixed, cheap, machine-checkable transport task rather than a full repository test run; see ADR 0018.
 

package/docs/adr/0016-archive-resolved-review-findings.md

@@ -10,7 +10,7 @@ An ignored root `REVIEW_FINDINGS.md` prevents unresolved review findings from be
 
 Review output and ledger mutation follow task authority. A read-only review reports records in the ledger's semantic fields without writing checkout state. Every implementation preserves an active ledger, but an ordinary change with no finding does not create one. `npm run review:new` creates the ignored root ledger only when a task authorizes capture or resolution of at least one finding; implementation imports those findings before editing their fixes. Archives move under Git's local `review-findings/archive` metadata path, so they cannot enter a commit and remain associated with the checkout.
 
-Ledger validation, readiness, deterministic verification, archive, and commit proof are distinct states with one implementation. `npm run review:validate` checks schema and tracked-file safety while accepting a valid open ledger. `npm run review:gate` is read-only: it blocks an open ledger, validates durable owners for accepted findings, and never archives. `npm run verify` performs schema validation before syntax and coverage checks, so open-ledger work can collect evidence. `npm run check` applies the readiness gate first, then materializes the current tracked and non-ignored checkout through Git's clean and index semantics in a temporary Git administrative directory. Git selects that directory's default index through `--git-dir` and reads the target checkout through `--work-tree`; it never receives an alternate-index environment path that could fall back to the real repository index. The temporary object database reads the repository's objects through a relative alternates entry and stores new fingerprint objects locally. The resulting tree object ID includes canonical blobs, symlink identity, and file modes while remaining independent of staged content. Sparse checkouts retain skip-worktree paths from the `HEAD` baseline and apply clean conversion only to materialized paths, so an absent out-of-cone file is neither lost nor mistaken for a deletion. Every path discovered by Git is reapplied through NUL-delimited literal input. The command separately snapshots the ignored ledger, runs `verify`, rejects changed source or ledger state, and refreshes the proof before archiving a resolved ledger. Repository scripts that launch npm as a child use one command resolver: an invoking npm process supplies its CLI path and Node executable, while direct script invocation falls back to the platform npm executable. A successful later check without an active ledger also refreshes an older proof. The pre-commit hook rejects open and unverified resolved ledgers, requires a verification proof for the current `HEAD`, requires equal source and index tree fingerprints, and requires the composite independent-review plan, lane verdicts, and final verdict defined by ADR 0026. Staging the complete verified tree permits repeated commit attempts; partial staging, additional staged content, mode-only changes, later checkout changes, uncovered paths, or invalidated lane dependencies require reconciliation before commit.
+Ledger validation, readiness, deterministic verification, archive, and commit proof are distinct states with one implementation. `npm run review:validate` checks schema and tracked-file safety while accepting a valid open ledger. `npm run review:gate` is read-only: it blocks an open ledger, validates durable owners for accepted findings, and never archives. `npm run verify` performs schema validation before syntax and complete backend checks without coverage (coverage scheduling is owned by [ADR 0035](0035-run-coverage-only-before-a-new-release.md)), so open-ledger work can collect evidence. `npm run check` applies the readiness gate first, then materializes the current tracked and non-ignored checkout through Git's clean and index semantics in a temporary Git administrative directory. Git selects that directory's default index through `--git-dir` and reads the target checkout through `--work-tree`; it never receives an alternate-index environment path that could fall back to the real repository index. The temporary object database reads the repository's objects through a relative alternates entry and stores new fingerprint objects locally. The resulting tree object ID includes canonical blobs, symlink identity, and file modes while remaining independent of staged content. Sparse checkouts retain skip-worktree paths from the `HEAD` baseline and apply clean conversion only to materialized paths, so an absent out-of-cone file is neither lost nor mistaken for a deletion. Every path discovered by Git is reapplied through NUL-delimited literal input. The command separately snapshots the ignored ledger, selects documentation checks or full `verify` under [ADR 0039](0039-verify-documentation-without-runtime-suites.md), rejects changed source, HEAD or ledger state, and refreshes the proof before archiving a resolved ledger. Repository scripts that launch npm as a child use one command resolver: an invoking npm process supplies its CLI path and Node executable, while direct script invocation falls back to the platform npm executable. A successful later check without an active ledger also refreshes an older proof. The pre-commit hook rejects open and unverified resolved ledgers, requires a verification proof for the current `HEAD`, requires equal source and index tree fingerprints, and requires the composite independent-review plan, lane verdicts, and final verdict defined by ADR 0026. Staging the complete verified tree permits repeated commit attempts; partial staging, additional staged content, mode-only changes, later checkout changes, uncovered paths, or invalidated lane dependencies require reconciliation before commit.
 
 Hook installation is explicit. `npm run hooks:install` selects the tracked hook path only when the effective `core.hooksPath` is unset or already `.githooks`. Before the first switch from Git's default hooks directory, installation rejects any non-sample hook file there; it also rejects an incompatible configured path instead of disabling another hook owner. Dependency installation has no Git-configuration side effect.
 

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

@@ -10,9 +10,9 @@ PTC Plus must remain independently installable on unmodified official DSH distri
 
 The compatibility target is the latest available DSH release. Production behavior, configuration, tests, installation guidance, and current compatibility claims depend on public extension contracts and observed live schemas, never on a DSH version allowlist or comparison. An upstream default projection is not an extension ceiling: when public scoped registration and presentation support a plugin-owned capability, PTC Plus preserves that capability and its model-visible identity instead of deleting or renaming it to match the default. Deterministic normalization remains valid for a call that is outside the declared direct surface when the live schema proves one native target and the lowering preserves arguments, call identity, authority, and result semantics. Deterministic tests exercise the consumed contracts; model-backed and packaging acceptance runners use the installed DSH and record `dsh --version` in generated reports so failures remain attributable without turning the observed value into policy. Concrete DSH release numbers may appear only in source comments that identify historical integration or evaluation evidence and cannot influence execution or acceptance.
 
-Release discovery is separated from candidate verification. The root manifest declares the official `next` channel for the DSH packages used by development and freezes the resolved cohort in the root lockfile. `compat/latest` declares only the official DSH meta-package on `latest` and freezes that complete graph in its own lockfile. Resolved versions in these generated lock snapshots are reproducibility evidence selected by the channel declarations; they are not compatibility allowlists or runtime branches. Ordinary `verify` and `check` runs make no registry request and fail quickly when the installed root graph differs from the root lock.
+Release discovery is separated from candidate verification. The root manifest declares the official `next` channel for the DSH packages used by development and freezes the resolved cohort in the root lockfile. `compat/latest` declares only the official DSH meta-package on `latest` and freezes that complete graph in its own lockfile. Resolved versions in these generated lock snapshots are reproducibility evidence selected by the channel declarations; they are not compatibility allowlists or runtime branches. `compat/current` separately freezes the cohort of the newest published official GitHub release, including prereleases. Its generated manifest selects the matching official npm channel, and `release.json` records the discovery provenance. This published-release identity, rather than a fixed list of channel names, owns the current target. Ordinary `verify` and the full branch of `check` make no registry request and fail quickly when the installed root graph differs from the root lock; they also validate the published cohort against its frozen provenance.
 
-The scheduled baseline refresh queries the official registry. When either channel moves, it updates both lock snapshots on an automation-owned branch, opens or updates one pull request, and dispatches the normal CI workflow once for that frozen candidate. GitHub suppresses workflow runs from branch and pull-request events produced by the workflow's `GITHUB_TOKEN`, so the explicit dispatch is the candidate's only CI run. If neither tag moved, it does not resolve or install the dependency graph. The Host contract suite tests the packed plugin against the root `next` graph and creates a repository-external consumer from the tracked `latest` lock. That consumer exposes the public packages from the selected Host graph to the plugin and runs the execution-seam, RPC-codec, and compressed Session persistence contracts. No compatibility run independently selects tags for DSH service packages, because their dist-tags need not move as one cohort.
+The scheduled baseline refresh queries the official registry. It also queries official GitHub releases and matches the newest non-draft DSH release to the official meta-package dist-tags. A missing distribution fails discovery instead of silently using an older Host. When either channel or the published-release cohort moves, it updates the affected lock snapshots on an automation-owned branch, opens or updates one pull request, and dispatches the normal CI workflow once for that frozen candidate. GitHub suppresses workflow runs from branch and pull-request events produced by the workflow's `GITHUB_TOKEN`, so the explicit dispatch is the candidate's only CI run. If neither tag nor the published-release cohort moved, it does not resolve or install the dependency graph. The Host contract suite tests the packed plugin against the root `next` graph and creates a repository-external consumer from the tracked `latest` lock. That consumer exposes the public packages from the selected Host graph to the plugin and runs the execution-seam, RPC-codec, and compressed Session persistence contracts. The suite also creates a repository-external consumer from `compat/current` and tests the packed plugin on that unmodified published graph. `npm run test:host-contract -- current` selects this object alone. No compatibility run independently selects tags for DSH service packages, because their dist-tags need not move as one cohort.
 
 Preceding public contracts remain supported where capability detection is
 unambiguous. Tools presentation is selected by the installed public schema;

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

@@ -14,11 +14,13 @@ PTC Plus 0.1.0 deliberately had no Client UI. The runtime surface was the DSH PT
 
 PTC Plus registers one DSH settings namespace `ptc-plus` with the same field list, defaults and validation as the Host Config schema. The field definitions live once in `internal/config-spec.js`; `index.js` builds the Cordis Config schema from it, and the esbuild client bundle imports the same module so the UI does not copy defaults or validation.
 
-The settings card belongs to plugin configuration. Current DSH renders a bundle's own configuration on the sidebar Plugins → Installed page through `plugins.row.config` (keyed, root) as `<bundle package name>#<row id>` and reserves `plugins.item` for the host-plane pages DSH itself ships. Preceding Hosts use `settings.plugin.item` (keyed, root) in the Settings panel, keyed by the served namespace. `src/client-host-compat.js` publishes to these plugin configuration seats through `ctx.slots.inject`, which waits until the owning page declares its slot. General settings may coexist with plugin configuration and is not a seat for this card. The composer shortcut opens an application-modal rendering of the same complete form, so direct access does not depend on a host page's component-local navigation state; its hover hint names the observed native plugin configuration seat. The package's top-level `icon` field points to a packaged SVG; DSH owns loading and displaying it on the installed bundle and row pages.
+The settings card belongs to plugin configuration. Current DSH renders a bundle's own configuration on the sidebar Plugins → Installed page through `plugins.row.config` (keyed, root) as `<bundle package name>#<row id>` and reserves `plugins.item` for the host-plane pages DSH itself ships. Historical, unfrozen Hosts use `settings.plugin.item` (keyed, root) in the Settings panel, keyed by the served namespace. `src/client-host-compat.js` publishes to these plugin configuration seats through `ctx.slots.inject`, which waits until the owning page declares its slot. General settings may coexist with plugin configuration and is not a seat for this card. The composer shortcut opens an application-modal rendering of the same complete form, so direct access does not depend on a host page's component-local navigation state; its hover hint names the observed native plugin configuration seat. The package's top-level `icon` field points to a packaged SVG; DSH owns loading and displaying it on the installed bundle and row pages.
 
-The settings card places the plugin switch first, then groups controls by purpose: tool call tolerance, REPL syntax, state and recovery, tool extensions, interface display, and resource limits. Recovery tips and their thresholds stay together, and global binding management appears directly below its enable switch. `CONFIG_GROUPS` owns this presentation order independently of Host schema field order and defaults. `autoDescribeRunCode` defaults to true and controls only a request-bound local execution policy. When enabled, a call that omits the outer `description` uses derived arguments for local DSH validation, and the fallback summary enters presentation metadata only; when disabled, DSH validates the original arguments. Both states produce byte-stable model-visible tool schemas, order, and system sections with the required `description` declaration. Original call arguments, explicit summaries, cell source, and nested native-tool arguments remain unchanged.
+The settings form groups controls into core workspace (REPL syntax, state and recovery), extensions and tolerance (tool extensions, tool call tolerance), interface and resources (interface display, resource limits), and experimental (capabilities and context). Page and dialog navigation integrate the single main switch into a borderless PTC Plus title row without a duplicate enabled badge; static module captions differ from section links with icons, arrows and selected markers. The legacy disclosure card retains its first switch section. Experimental controls remain last and carry an explicit marker. The wide settings dialog presents the groups as a two-column workbench with independently scrolling navigation and content; settings wheel scrolling and section selection leave the rail and shared modal frame in place. Narrow viewports use horizontal navigation above independently scrolling content. Recovery tips and their thresholds stay together, and global binding management appears directly below its enable switch. `CONFIG_MODULES` and `CONFIG_GROUPS` own this presentation grouping and order independently of Host schema field order and defaults. The session capability-plan section inside capabilities and context shows effective selections and pending configuration changes only while capability management is enabled; disabling it cancels plan inspection and discards stale replies while manual configuration and catalog reads remain available. Capabilities and context uses four tabs for manual preferences, statistics, budgets and session plans. MCP lists group tools/resources under a server master switch; closing the server preserves child strategies and takes precedence when the frozen plan is derived. Typed catalog rows keep common preferences, manual strategies and selected frozen-session results separate, with source/strategy/common/availability filters and stable within-group sorting. Display names and source metadata belong only to the catalog RPC view: Skill provider/source and public MCP server directory and captured MCP owner sections supply evidence, while ordinary tools are attributed to the Host registry without guessing their package origin. Catalog errors preserve last-observed entries as unconfirmed, and unavailable saved preferences remain editable/removable. The core execution surface is read-only. Capability controls serialize structured selections and retain invalid numeric drafts without committing them; saving capability settings affects new sessions, while existing sessions retain their frozen plan until `/capabilities refresh` as defined by [ADR 0038](0038-freeze-session-capability-plans.md). The sparkle menu refreshes its current session through the authenticated Host command; settings require an explicit target from a read-only active-PTC identity view. This identity view does not prepare or inspect plans and remains available with capability management off so users can synchronize the disabled configuration. Reloading catalog/plans is read-only. Global binding disablement hides binding actions while settings and capability refresh remain accessible; the plugin switch and configured sparkle visibility still gate the menu. Refresh receipts preserve Host outcomes, and cancellation stops waiting without claiming rollback. `autoDescribeRunCode` defaults to true and controls only a request-bound local execution policy. When enabled, a call that omits the outer `description` uses derived arguments for local DSH validation, and the fallback summary enters presentation metadata only; when disabled, DSH validates the original arguments. Both states produce byte-stable model-visible tool schemas, order, and system sections with the required `description` declaration. Original call arguments, explicit summaries, cell source, and nested native-tool arguments remain unchanged.
 
-The configurable set is the Host runtime configuration plus `enabled: boolean` (default true). `enabled` is the kill switch: when false the Host keeps the settings namespace, client card, and passive message cleanup defined in [ADR 0010](0010-session-log-derived-recovery-tips.md). The next permitted accepted step may clear earlier PTC declarations. It does not install the runtime bridge, edit transport, direct-surface owner, system prompt section, tool registrations, or execution hooks, and does not read binding storage. When true the same runtime as pre-settings PTC Plus is installed. On the generations that expose a section installer, every field is live when its owner can reconcile it: the Host observes the settings scope and installs, uninstalls, or reconfigures owners without replacing existing session-bound bindings. The newest settings generation exposes no section installer and serves only fields marked volatile in the plugin's exported `Config`; the Host provides the form and commits volatile-only changes into the live references, notifying the owning fiber through the public `loader/volatile-update` event. The plugin subscribes and reconciles through its existing update path instead of running a per-field settings watch. Node fixes a worker's V8 `maxOldGenerationSizeMb` limit at construction, so changing that field while a session worker is active is rejected and the settings provider is restored to the previous value; other reconfiguration failures use the same compensation path. The TypeScript language check occurs at activation, allowing disabled settings to load on a host using another code runtime while rejecting and rolling back an enable attempt. If the settings service is absent, the Host falls back to composition config and enables the runtime.
+The configurable set is the Host runtime configuration plus `enabled: boolean` (default true). `enabled` is the kill switch: when false the Host keeps the settings namespace, client card, and passive message cleanup defined in [ADR 0010](0010-session-log-derived-recovery-tips.md). The next permitted accepted step may clear earlier PTC declarations. It does not install the runtime bridge, edit transport, direct-surface owner, system prompt section, tool registrations, or execution hooks, and does not read binding storage. When true the same runtime as pre-settings PTC Plus is installed. On the generations that expose a section installer, every field is live when its owner can reconcile it: the Host observes the settings scope and installs, uninstalls, or reconfigures owners without replacing existing session-bound bindings. The volatile-only settings shape exposed by both frozen Host graphs has no section installer and serves only fields marked volatile in the plugin's exported `Config`; the Host provides the form and commits volatile-only changes into the live references, notifying the owning fiber through the public `loader/volatile-update` event. The plugin subscribes and reconciles through its existing update path instead of running a per-field settings watch. Node fixes a worker's V8 `maxOldGenerationSizeMb` limit at construction, so changing that field while a session worker is active or a submitted cell is preparing to execute is rejected and the settings provider is restored to the previous value; other reconfiguration failures use the same compensation path. The TypeScript language check occurs at activation, allowing disabled settings to load on a host using another code runtime while rejecting and rolling back an enable attempt. If the settings service is absent, the Host falls back to composition config and enables the runtime.
+
+The host-only log-fact projection remains owned by the plugin/controller lifecycle when the runtime is disabled, as specified in [ADR 0032](0032-own-session-log-facts-in-a-host-only-projection.md). It supports passive message cleanup without retaining a worker, tool or default model-visible state projection.
 
 Every settings-card and PTC Plus tool-row string is registered into the DSH client locale namespace `settings.ptcPlus` and follows the active DSH client locale. Field copy exists in both locales from the single `internal/config-spec.js` source (`label`/`labelEn`, `description`/`descriptionEn`); display chrome copy is owned by the Client half. The stable REPL guidance remains plugin-owned protocol text without UI branding. The transport names remain `run_code`/`edit_run_code`; DSH owns their identity.
 
@@ -34,6 +36,15 @@ Feature notices name actual per-result events rather than configuration defaults
 
 Runtime activation is transactional. If a live enable cannot complete, every owner acquired before the failing setup step is disposed, the failure is logged, and the settings provider is asked to persist `enabled: false`; a failed compensating write remains an explicit activation diagnostic rather than an unreported state mismatch.
 
+The settings compatibility owner binds the write identity when the provider
+appears. A Host-owned `Config` document is addressed by its owning Loader
+entry's profile ID; a historical section installer is addressed by its section
+namespace. Enable-failure and live-reconfiguration compensation use that same
+bound writer, not a fixed namespace substituted for the owning entry. The
+writer and page policy are released with the settings provider.
+
+Compatibility evidence and the consequences of removing historical branches are bounded by [Installation: Compatibility Evidence](../installation.md#compatibility-evidence). The two frozen graphs do not establish full Host coverage of the section-installer or settingsScope shapes.
+
 ## Alternatives Considered
 
 1. Keep no Client UI. Rejected: PTC Plus requires a settings surface and a kill switch. Away from settings, users cannot tell whether PTC Plus is actively installed because the only marker is application behavior.

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

@@ -20,11 +20,11 @@ The Skill provider and official Cordis child fiber form one reversible mount. Bo
 
 The official plugin also registers Host inspect providers in the process-global `cordisInspect` service. Per-agent fibers therefore acquire owner-scoped leases for identical provider manifests instead of registering the same provider ID independently. Queries delegate to a registration from a still-live official fiber, and the process-global provider is removed when the final lease is released. A manifest mismatch remains a configuration error rather than silently choosing one contract.
 
-Cordis tools remain native program bindings under `tools.*`. The PTC code-only direct-tool projection remains exactly `[run_code, edit_run_code]`; native agents and unrelated scopes do not inherit this option.
+Cordis tools remain native program bindings under `tools.*`. The PTC code-only direct-tool projection remains exactly `[run_code]`, with the registered editor called through `tools.edit_run_code` in the program SDK; native agents and unrelated scopes do not inherit this option.
 
 Cordis definitions and Runs are process-local, while PTC journals replay every settled program binding as a recorded value without redispatch. On the first prompt for an agent or a new Cordis enable generation, PTC Plus derives whether normalized journals contain a Cordis transcript. If they do, it emits the fixed `tools:ptc-plus-cordis-recovery` runtime context: recorded values remain journal data, but the model must perform a live read-only Cordis Inspect before relying on prior IDs, state, approvals, or capability observations. The context remains until a newly settled successful `cordis_inspect*` call appears in the session log. It neither asserts that live state was lost nor reruns a mutating call.
 
-Companion Skill resolution is capability-based. A generation that publishes an absolute composition path for the shipped `cordis` preset uses its sibling `skills` root. For a pathless generation, PTC Plus asks the Host's public `pluginPackages.packageOf` service for the active installation's `@deepseek-ai/dsh-agent-preset` or `@deepseek-ai/dsh-agent-presets` resource, then selects that generation's known Skill layout. Older generations that do not publish `pluginPackages` may resolve only the historical plural package from the Host's `ctx.baseUrl`; this compatibility path is disabled whenever the service exists, including when it returns no package. It never uses plugin-anchored ambient Node lookup, because a profile or Desktop installation may contain a stale package from another Host generation. PTC Plus accepts a root only when it contains the exact `cordis-plugin-development/SKILL.md`; it does not infer support from a package name or directory alone. An unusable preset (`broken`) is reported as unavailable before path or package resolution, while an invalid published path remains a host contradiction rather than falling through to a different generation.
+Companion Skill resolution is capability-based. A generation that publishes an absolute composition path for the shipped `cordis` preset uses its sibling `skills` root. For a pathless generation, PTC Plus asks the Host's public `pluginPackages.packageOf` service for the active installation's `@deepseek-ai/dsh-agent-preset` or `@deepseek-ai/dsh-agent-presets` resource, then selects that generation's known Skill layout. Each resolution reads the current service after preset resolution; owner creation does not fix later mounts to an earlier service or its absence. Older generations that do not publish `pluginPackages` may resolve only the historical plural package from the Host's `ctx.baseUrl`; this compatibility path is disabled whenever the service exists, including when it returns no package. It never uses plugin-anchored ambient Node lookup, because a profile or Desktop installation may contain a stale package from another Host generation. PTC Plus accepts a root only when it contains the exact `cordis-plugin-development/SKILL.md`; it does not infer support from a package name or directory alone. An unusable preset (`broken`) is reported as unavailable before path or package resolution, while an invalid published path remains a host contradiction rather than falling through to a different generation.
 
 ## Alternatives Considered
 

package/docs/adr/0022-stage-npm-releases-with-oidc.md

@@ -8,7 +8,9 @@ The npm registry is retiring long-lived bypass-2FA credentials as a direct publi
 
 The `Release` GitHub Actions workflow is the only automated npm publication path. A maintainer explicitly dispatches it from an annotated `v<package.version>` tag ref; there is no independent tag input. Before obtaining npm authority, the workflow proves that its `GITHUB_REF`, provenance-bearing `GITHUB_SHA`, annotated tag target, checked-out commit, manifest version, and the successful `main` push run of `.github/workflows/ci.yml` all identify the same commit. Normal CI does not run for tag pushes.
 
-The npm Trusted Publisher is bound to the exact repository, `release.yml` workflow filename, and `npm-release` GitHub environment. Its allowed action is only `npm stage publish`; direct `npm publish` and reusable npm write tokens are absent from the workflow. The package uses npm's most restrictive recommended publishing-access policy even when npm documentation and the live UI use different labels for it. After the OIDC staging path is proven, maintainers revoke every remaining reusable token capable of publishing or staging this package rather than treating the selected UI label as evidence that no such credentials remain. The release job receives only `contents: read` and `id-token: write`, uses a GitHub-hosted runner without a package-manager cache, revalidates the dispatch ref and SHA after the environment boundary, builds and smoke-tests one tarball, and sends that same file to npm staging with provenance.
+The npm Trusted Publisher is bound to the exact repository, `release.yml` workflow filename, and `npm-release` GitHub environment. Its allowed action is only `npm stage publish`; direct `npm publish` and reusable npm write tokens are absent from the workflow. The package uses npm's most restrictive recommended publishing-access policy even when npm documentation and the live UI use different labels for it. After the OIDC staging path is proven, maintainers revoke every remaining reusable token capable of publishing or staging this package rather than treating the selected UI label as evidence that no such credentials remain. The release job receives only `contents: read` and `id-token: write`, uses a GitHub-hosted runner without a package-manager cache, revalidates the dispatch ref and SHA after the environment boundary, runs the release-only coverage gate from [ADR 0035](0035-run-coverage-only-before-a-new-release.md), builds and smoke-tests one tarball against the installed frozen Host peer cohort, and sends that same file to npm staging with provenance.
+
+The clean-consumer install supplies the exact versions of required peers resolved from the verified installed Host alongside the tarball in one npm transaction. Independent dist-tag resolution of shared service packages can mix incompatible cohorts and is not release evidence. This constrains the verification consumer, while the plugin keeps unrestricted required peer ranges and Host-owned service instances.
 
 Promotion is separate from staging. A maintainer reviews the staged metadata and downloadable tarball, then approves or rejects it through npm with interactive 2FA. A successful approval is not treated as immediate availability because npm publish-time scanning may delay or block registry visibility. GitHub Release publication follows observed availability of the exact npm version.
 
@@ -20,7 +22,7 @@ npm 12 install-time restrictions remain enabled for the release job. The manifes
 
 **Publish directly with OIDC after a GitHub Environment approval.** This removes long-lived credentials but substitutes a GitHub approval for npm proof-of-presence. Stage-only authority keeps CI compromise from making a version public and remains compatible with npm's dual-use publication requirements if they apply.
 
-**Run the full platform matrix again inside the release workflow.** Revalidation of an immutable SHA repeats expensive deterministic work without changing the artifact identity. The release workflow instead verifies the successful CI run for that exact SHA, then performs npm 12 installation, build, package lint, audit, pack, checksum, and clean-consumer smoke on the release artifact.
+**Run the full platform matrix again inside the release workflow.** Revalidation of an immutable SHA repeats expensive deterministic work without changing the artifact identity. The release workflow instead verifies the successful CI run for that exact SHA, then performs npm 12 installation, build, release-only coverage, package lint, audit, pack, checksum, and clean-consumer smoke on the release artifact.
 
 **Publish a locally generated tarball after CI.** Interactive local publishing provides 2FA but separates the published bytes from the workflow identity and makes provenance, repeatability, and artifact review depend on workstation state.
 

package/docs/adr/0023-global-user-bindings.md

@@ -69,7 +69,7 @@ An enabled agent whose effective public tool view contains `run_code` receives `
 
 Either command appends complete authoring instructions through `agent.steer` and completes admission once the normal Agent turn has been requested. Admission means authoring started, not that a candidate exists. Under enabled configuration, `code.submitBindingDraft({requestId, entry})` is a stable program SDK member, including its discovery schema. It uses the ordinary cell lease and program-call transcript. The Host captures the exact active request at cell creation and checks agent identity, request ID, generation, and single-submission eligibility before and after asynchronous validation. Acceptance, turn stop, error, cancellation, replacement, disablement, or disposal revokes submission eligibility without changing the declaration. No request-specific tool or Skill registration changes the system prefix. Cold replay returns a recorded receipt without submitting again or restoring writable access.
 
-The schema, SDK and authoring instructions include both `modelContext` fields. Authoring asks for a declaration-injection choice and a usage prompt containing only information missing from the interface; when types and API comments suffice, the prompt is empty. Edits preserve existing prompt preferences unless the requirement changes them. The workbench exposes both controls directly, without requiring source-edit mode; changes enter an unsaved draft with save and cancel actions. The input-dock review exposes accepted prompt metadata before a user saves it; the command card retains read-only history. Saving as disabled does not add configured API text to ordinary requests.
+The schema, SDK and authoring instructions include both `modelContext` fields. Authoring asks for a declaration-injection choice and a usage prompt containing only information missing from the interface; when types and API comments suffice, the prompt is empty. Edits preserve existing prompt preferences unless the requirement changes them. The workbench exposes both controls directly, without requiring source-edit mode; changes enter an unsaved draft with save and cancel actions. The input-dock review exposes accepted prompt metadata before a user saves it; a zero-height plugin-owned anchor positions a portaled floating preview so disclosure does not resize the transcript or composer. An enlarged public Modal (or its plugin fallback) renders the same candidate and actions, with independently scrolling content and fixed header/footer. Returning to the preview changes only display; the portal yields when the composer entry is not reachable. The preview measures only its own anchor and visual viewport while visible, avoiding Host clipping/stacking without ancestor writes. In very limited space it shows the header and enlarge action. Neither presentation creates another review controller or write authority; the command card retains read-only history. Saving as disabled does not add configured API text to ordinary requests.
 
 Authoring uses ordinary `run_code` cells to develop and test pure logic with in-memory inputs, assertions and substitutes. Temporary session variables are permitted; the task prohibits test effects on external files and services. Imports and initializers with unknown effects are reviewed without execution. Tests can guide corrections and comparisons before the final source, exports, types and usage prompt are checked together. The answer reports verified behavior and untested integration, without requiring reasoning transcripts or a fixed number of calls. This is task guidance under DSH authority, not a sandbox or an additional permission mechanism. It does not expose the workbench's candidate runner to the Agent.
 
@@ -77,6 +77,8 @@ The existing REPL supplies execution feedback; the handoff accepts final source
 
 The first validated candidate becomes one disabled memory draft. Private `dshPtcPlusBindingDraft` metadata version 2 contains the generation, opaque locator, and the accepted candidate with request ID, command ID, version, mode, and complete source-owned entry. Later results carry `candidate: null`; version 1 remains readable. The `ptcPlusBindingDraft` projection, state version 4, pairs command and turn lifecycle with acceptance, retains read-only history across seeds and owner generations, and never revives a historical locator. Malformed historical presentation cannot block subsequent valid execution. The management Remote uses the authenticated Host Gateway and provides no caller/session identity, so draft operations require the locator rather than a payload session ID. The `draft-review` endpoint serves the accepted source and any completed action while its owning lifecycle remains available.
 
+Confirmed enable/disable of a saved binding prepares a separate `ptc-binding-toggle/v1` receipt. If the Session already has its Host system head, the owner appends it through public `Session.append('user/message', message, {surfaceOp: 'append'})`; otherwise it supplies the pending receipt only with an accepted `agent/pre-step` message batch, after the Host establishes its first system node. Rejected or cancelled steps do not publish it, and the public `session/event` commit notification retires each pending receipt by message identity, so later compaction cannot resurrect it. The receipt describes configuration persistence, never catalog delivery or worker initialization, and never wakes an Agent. Before first acceptance the management result supplies immediate UI feedback; pending history is process-local and does not claim durability before publication. Storage failure emits no success receipt.
+
 After a user save or discard completes, the Host consumes the writable locator and appends a structured plugin notice through public `Session.append('user/message', ..., {surfaceOp: 'append', sourceEventSeqs: [acceptingResultSeq]})`. The notice contains only request ID, entry ID, saved/discarded state, and enabled state. It asserts persistence, never session activation, and contains no source or locator. The projection accepts it only when identity and the accepting source relation match. Card remounts use this historical source and action, never a later store entry with the same ID. A failed notice append cannot undo the write or restore save eligibility; missing durable evidence remains unknown after restart. In-flight storage settlement cannot resurrect a locator already revoked by lifecycle cleanup. Clearing an unsaved draft alone does not append a persistence notice.
 
 Catalog revision conflicts refresh the catalog, draft, and review independently. A still-valid draft stays inspectable and retryable by the user; an authoritative empty draft revokes the actions. No conflict automatically repeats a write. Agent disposal invalidates only that exact Agent's locators and in-memory reviews; session disposal, feature disablement, and owner disposal revoke all affected access. Durable history proves a past action, not current activation or model knowledge.

package/docs/adr/0026-persist-the-delivery-verdict-against-the-verified-candidate.md

@@ -18,6 +18,8 @@ After all lanes are effective, `npm run check` produces the existing whole-sourc
 
 `REVIEW_FINDINGS.md`, `REVIEW_PLAN.json`, reports, lane records, plans, proofs, and aggregate verdicts remain checkout-local. The two root working files are installed into `.git/info/exclude`; reports must stay outside the checkout or be ignored. The old `dsh-review-verdict/v1` single-report format and `verdict` command are rejected rather than treated as composite evidence.
 
+[ADR 0039](0039-verify-documentation-without-runtime-suites.md) selects documentation or full behavioral verification within `check`. Both scopes keep the proof, review and index identities defined here; documentation proof does not establish runtime test success. The action-specific commands live in [review procedures](../review-procedure.md).
+
 ## Alternatives considered
 
 **Repeat one complete-tree review after every fix.** This binds review to exact bytes but discards unaffected independent evidence and serializes work that has explicit semantic boundaries.