@unbrained/pm-cli 2026.8.24 → 2026.8.26

package/docs/MCP_2026_07_28_CONFORMANCE.md

@@ -0,0 +1,30 @@
+# MCP 2026-07-28 Conformance Matrix
+
+Tracker: [pm-55yf1t](../.agents/pm/tasks/pm-55yf1t.toon). The official
+2026-07-28 schema and key-changes document are normative; this matrix assigns
+every revision-level change to one canonical pm owner and records executable
+evidence or an explicit open obligation.
+
+| Requirement family                                                                                 | Canonical owner                                     | Current disposition                                                                                                      | Executable evidence                                                                       |
+| -------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| Stateless per-request version, client capabilities, and identity                                   | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented                                                                                                              | `tests/unit/sdk/mcp/protocol.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts` |
+| Mandatory `server/discover`, deterministic capabilities and identity                               | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented                                                                                                              | direct SDK/server tests plus plugin and release real-process probes                       |
+| Unsupported version `-32022`                                                                       | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented                                                                                                              | SDK and server negative controls                                                          |
+| Header mismatch `-32020` and missing capability `-32021`                                           | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented in SDK, stdio, and Streamable HTTP                                                                            | SDK negative controls and `tests/integration/mcp-streamable-http.spec.ts`                 |
+| Required result `resultType`; legacy omission means complete only at compatibility boundary        | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented for modern pm results                                                                                        | SDK unit and modern direct-server tests                                                   |
+| No modern initialize, initialized notification, ping, or protocol session                          | [pm-sqvshj](../.agents/pm/decisions/pm-sqvshj.toon) | Implemented with bounded legacy stdio adapter                                                                            | modern removed-method and legacy handshake tests                                          |
+| MRTR `input_required`, retry state, and reverse-request removal                                    | [pm-rz9gep](../.agents/pm/features/pm-rz9gep.toon)  | Implemented for SDK and stateless stdio adapter                                                                          | `tests/unit/sdk/mcp/interactions.spec.ts`; direct server negative controls                |
+| `subscriptions/listen`, request-scoped streams, no SSE resumability                                | [pm-v7e337](../.agents/pm/features/pm-v7e337.toon)  | Implemented locally; packed and published proof follows merge                                                            | subscription SDK, stdio, HTTP, backpressure, disconnect, and retry tests                  |
+| Official `io.modelcontextprotocol/tasks` extension                                                 | [pm-rzs24j](../.agents/pm/features/pm-rzs24j.toon)  | Implemented for eligible tool calls, durable lifecycle, and stdio methods; notifications remain with subscriptions owner | `tests/unit/sdk/mcp/tasks.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts`    |
+| Cacheable list/read results, deterministic tools, JSON Schema 2020-12, any JSON structured content | [pm-hv1x1x](../.agents/pm/features/pm-hv1x1x.toon)  | Implemented for current pm tool/resource/prompt surfaces                                                                 | SDK schema/cache tests and direct modern server surface suite                             |
+| Issuer-bound authorization, client metadata documents, consent, headers, OpenTelemetry             | [pm-3zh9s4](../.agents/pm/features/pm-3zh9s4.toon)  | Implemented locally; deployment verifier integration remains host-owned                                                   | authorization SDK adversarial tests, real HTTP bearer suite, and threat model             |
+| Core extension negotiation and official extension fallback                                         | [pm-pznhee](../.agents/pm/features/pm-pznhee.toon)  | Open                                                                                                                     | owner acceptance criteria and release matrix                                              |
+| Skills over MCP                                                                                    | [pm-8nzivt](../.agents/pm/features/pm-8nzivt.toon)  | Open                                                                                                                     | owner acceptance criteria define capability and token-budget proof                        |
+| Deprecated Roots, Sampling, Logging, HTTP+SSE, `includeContext`, dynamic registration              | [pm-vzcisw](../.agents/pm/chores/pm-vzcisw.toon)    | Canonical source ratcheted; bounded stdio adapter and dated migration policy remain                                      | generated inventory, negative controls, adapter tests, and migration guide                |
+| Official schema, real stdio/HTTP, packed/published, npx/bunx, negative controls                    | [pm-55yf1t](../.agents/pm/tasks/pm-55yf1t.toon)     | Foundation implemented; remains open until every owner above closes                                                      | SDK/server suites, plugin smokes, published-release verifier                              |
+
+The programme gate remains intentionally incomplete while any row says `Open`
+or while local-only rows lack their packed and published evidence. Provider
+silence, a successful legacy initialize, or source-only unit coverage cannot
+promote such a row. Completion requires the owner's positive and negative
+tests plus exact packed and published consumer proof.

package/docs/MCP_REMOTE_TRANSPORT_SECURITY.md

@@ -0,0 +1,180 @@
+# MCP Remote Transport, Authorization, and Migration
+
+Tracker references: [pm-v7e337](../.agents/pm/features/pm-v7e337.toon),
+[pm-3zh9s4](../.agents/pm/features/pm-3zh9s4.toon), and
+[pm-vzcisw](../.agents/pm/chores/pm-vzcisw.toon).
+
+pm exposes the same MCP 2026-07-28 dispatcher through two adapters:
+
+- `pm-mcp` is the local JSON-RPC/stdio process. It retains a bounded
+  `2025-06-18` compatibility adapter for existing local consumers.
+- `pm-mcp-http` is the canonical sessionless Streamable HTTP POST process. It
+  accepts only modern request-local protocol metadata and never creates an
+  MCP session.
+
+The public `@unbrained/pm-cli/sdk` entrypoint owns subscription filtering,
+HTTP header projection, authorization discovery and validation, issuer-keyed
+credentials, bearer enforcement, and trace-context isolation. Adapters remain
+thin bindings over those contracts.
+
+## Run the HTTP adapter
+
+The safe default binds only `127.0.0.1:3000`:
+
+```bash
+pm-mcp-http
+```
+
+Configuration is explicit and environment-only:
+
+| Variable                      | Meaning                                             | Default            |
+| ----------------------------- | --------------------------------------------------- | ------------------ |
+| `PM_MCP_HTTP_HOST`            | Bind host                                           | `127.0.0.1`        |
+| `PM_MCP_HTTP_PORT`            | Bind port, including `0` for an ephemeral test port | `3000`             |
+| `PM_MCP_HTTP_ALLOWED_ORIGINS` | Comma-separated exact browser origins               | none               |
+| `PM_MCP_HTTP_BEARER_TOKEN`    | Opaque deployment token for the bundled verifier    | none               |
+| `PM_MCP_HTTP_AUTH_ISSUER`     | Exact HTTPS authorization-server issuer             | none               |
+| `PM_MCP_HTTP_RESOURCE`        | Canonical MCP resource/audience URI                 | none               |
+| `PM_MCP_HTTP_SCOPES`          | Space-separated consent scopes                      | `pm:read pm:write` |
+
+A non-loopback bind fails closed unless token, issuer, and resource are all
+present. Production deployments should normally call
+`createPmMcpHttpServer()` with an OAuth access-token verifier backed by their
+authorization server instead of using the executable's single opaque-token
+bootstrap verifier.
+
+For example, this starts a deliberately local protected endpoint without
+placing a real credential in documentation:
+
+```bash
+PM_MCP_HTTP_BEARER_TOKEN='<deployment-secret>' \
+PM_MCP_HTTP_AUTH_ISSUER='https://auth.example.test' \
+PM_MCP_HTTP_RESOURCE='http://127.0.0.1:3000/mcp' \
+pm-mcp-http
+```
+
+The adapter serves RFC 9728 protected-resource metadata at both
+`/.well-known/oauth-protected-resource` and the path-qualified
+`/.well-known/oauth-protected-resource/mcp` location.
+
+## Stream and header contract
+
+Every HTTP request is a POST to `/mcp` and negotiates both
+`application/json` and `text/event-stream`. Normal finite requests return
+JSON. `subscriptions/listen` returns an SSE response whose first message is
+`notifications/subscriptions/acknowledged`; every later subscription
+notification carries the listen request's JSON-RPC id in
+`io.modelcontextprotocol/subscriptionId`.
+
+The supported opt-ins are tool-list, prompt-list, resource-list, and exact
+resource-update notifications. Each stream serializes writes and drops a sink
+that fails or remains backpressured beyond the bounded write deadline; tool
+calls do not await subscriber delivery. Disconnecting deletes the
+request-scoped subscription. A broken stream has no replay cursor: there are no
+SSE event ids and `Last-Event-ID` is rejected. The caller retries the lost
+operation with a new JSON-RPC request id.
+
+`MCP-Protocol-Version` and `Mcp-Method` are built and validated against every
+JSON-RPC request body. `Mcp-Name` is required only for `prompts/get`,
+`resources/read`, and `tools/call`; methods such as `tools/list` omit it. Tool
+properties may declare `x-mcp-header` in their JSON Schema; the SDK validates
+the header name, rejects reserved or duplicate mappings, encodes non-ASCII and
+ambiguous values with the MCP Base64 sentinel, and compares the decoded header
+with the argument value before dispatch. CR/LF and control-character values
+are always rejected.
+
+Current pm handlers do not emit request progress or deprecated MCP log-message
+notifications. A `progressToken` or request-local
+`io.modelcontextprotocol/logLevel` is therefore never promoted to a shared
+subscription. Work that returns a durable task remains observable through the
+task lifecycle; remote operational logging belongs in the deployment's
+OpenTelemetry pipeline.
+
+## Authorization lifecycle
+
+Remote hosts can compose the public SDK primitives into a complete OAuth
+client/resource lifecycle:
+
+1. Build or read protected-resource metadata and choose an advertised
+   authorization-server issuer.
+2. Probe OAuth and OpenID discovery URLs in the specified order. Require the
+   metadata `issuer` to match exactly and require S256 PKCE.
+3. Prefer a pre-registered client, then a validated Client ID Metadata
+   Document, then bounded Dynamic Client Registration, and finally explicit
+   user-supplied registration.
+4. Validate a returned `iss` when present or advertised, bind stored
+   credentials to the exact issuer, and never reuse them across issuers.
+5. Request only the scopes needed for the operation. The resource verifies
+   bearer location, issuer, audience, and every required consent scope before
+   MCP dispatch.
+6. Replace an issuer's stored credential after refresh. Delete only that
+   issuer's entry on revocation, invalid grant, or re-registration; discovery
+   and consent then run again without affecting other issuers.
+
+`PmMcpIssuerCredentialStore` deliberately provides cloned `set`, `get`, and
+`delete` operations rather than owning token refresh network traffic. This
+keeps refresh, revocation, persistence encryption, and user interaction in the
+host that owns the authorization relationship.
+
+## Trace and privacy boundary
+
+Modern request `_meta` may carry W3C `traceparent`, `tracestate`, and baggage.
+The SDK validates syntax and byte bounds, drops every baggage member that is
+not on the host-provided allowlist, and stores the resulting context in an
+`AsyncLocalStorage` scope for only that request. Concurrent requests cannot
+inherit one another's trace context. Raw bearer tokens are hashed for
+constant-time comparison by the bundled verifier and are never included in
+claims, errors, traces, or JSON-RPC result data.
+
+| Threat                         | Enforced boundary                                                               |
+| ------------------------------ | ------------------------------------------------------------------------------- |
+| DNS rebinding/browser drive-by | Loopback default plus exact `Origin` allowlist                                  |
+| Token passthrough              | Bearer is verified at pm and never forwarded to another service                 |
+| Issuer mix-up                  | Exact discovery/response issuer checks and issuer-keyed credentials             |
+| Confused audience              | Exact protected-resource audience check                                         |
+| Excess authority               | Required-scope intersection before dispatch                                     |
+| Query/log credential leak      | Query tokens rejected; challenges and errors omit token material                |
+| Header injection               | Schema-derived allowlist, reserved-name checks, control-byte rejection          |
+| Trace privacy leak             | Syntax/size validation, baggage-key allowlist, request-local storage            |
+| Proxy cache disclosure         | MCP and metadata errors use explicit content types; MCP results use `no-store`  |
+| Replay after disconnect        | No session, event id, resume cursor, or redelivery; retry uses a new request id |
+
+## Deprecated-feature inventory and sunset
+
+Run the generated ratchet locally or in CI:
+
+```bash
+pnpm quality:mcp-deprecations
+```
+
+The inventory classifies every match as canonical source, the isolated legacy
+adapter, migration documentation, a negative control, or
+`bounded_source_control`. The last disposition applies only to exact,
+single-use source lines in the reviewed fixed allowlist; an adjacent marker or
+an unlisted source path cannot create that exemption. Any canonical match for a
+removed method, session header, SSE resume mechanism, legacy
+resource-subscription method, or deprecated server policy fails the gate.
+
+The compatibility adapter supports only protocol `2025-06-18` on local stdio.
+It may be removed after telemetry and installed-consumer probes show no
+required legacy clients for two consecutive release windows. Deprecated
+2026-07-28 fields remain available only where the normative registry requires
+its minimum compatibility period; no pm sunset occurs earlier than
+2027-07-28. A removal is always a reviewed release change with packed and
+published consumer proof.
+
+## Verification
+
+Focused release evidence is reproducible with:
+
+```bash
+node scripts/run-tests.mjs test -- tests/unit/sdk/mcp/subscriptions.spec.ts
+node scripts/run-tests.mjs test -- tests/unit/sdk/mcp/transport.spec.ts
+node scripts/run-tests.mjs test -- tests/unit/sdk/mcp/authorization.spec.ts
+node scripts/run-tests.mjs test -- tests/integration/mcp-streamable-http.spec.ts
+node scripts/run-tests.mjs test -- tests/unit/scripts/release/mcp-deprecation-gate.spec.ts
+pnpm quality:mcp-deprecations
+```
+
+The full release gates, packed artifact probes, installed `npx`/`bunx`
+consumers, and published artifact checks remain distinct closeout evidence.

package/docs/MERGE_SAFETY.md

@@ -2,6 +2,9 @@
 
 Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fresh-init fence ownership is tracked by [pm-1w3ljt](../.agents/pm/issues/pm-1w3ljt.toon); runtime-cache index governance by [pm-hous](../.agents/pm/issues/pm-hous.toon); local allocation safety by [pm-khdq](../.agents/pm/issues/pm-khdq.toon); fence-coverage completeness and drift detection by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); package-defined item coverage by [pm-5rexki](../.agents/pm/issues/pm-5rexki.toon); non-item JSON coverage by [pm-gjicmx](../.agents/pm/issues/pm-gjicmx.toon); portable driver identity by [pm-w91mvg](../.agents/pm/issues/pm-w91mvg.toon); pending receipt validation by [pm-ysqb6n](../.agents/pm/issues/pm-ysqb6n.toon); receipt classification by [pm-jtwsct](../.agents/pm/issues/pm-jtwsct.toon); direction-independent item conflict selection by [pm-dlx7v7](../.agents/pm/issues/pm-dlx7v7.toon); corrected reconciliation guidance by [pm-lwmstb](../.agents/pm/issues/pm-lwmstb.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); auditable merge history by [pm-9j2r3b](../.agents/pm/tasks/pm-9j2r3b.toon); durable conflict decisions by [pm-rh98vo](../.agents/pm/issues/pm-rh98vo.toon); continuous conformance by [pm-76dnfg](../.agents/pm/tasks/pm-76dnfg.toon); workspace-wide CI enforcement by [pm-pdr8t1](../.agents/pm/tasks/pm-pdr8t1.toon); post-merge reconciliation by [pm-mfkv92](../.agents/pm/issues/pm-mfkv92.toon); linked-command execution trust by [pm-ed28wi](../.agents/pm/issues/pm-ed28wi.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
 
+Lossless receipt health gating is tracked by
+[pm-baksix](../.agents/pm/issues/pm-baksix.toon).
+
 pm stores project context as reviewable repository files. Concurrent agents can therefore use ordinary branches and worktrees, but tracker artifacts need semantic merge behavior: raw line merging cannot preserve TOON collection counts, JSON object structure, or append-only history hash chains.
 
 ## Install the repository merge contract
@@ -118,11 +121,37 @@ pm merge reconcile --force --message "Accept reviewed merge decisions" --json
 ```
 
 The preview reports every drifted stream and pending receipt without mutation.
-Lossless receipts are reported as provenance but do not become blocking merge
-decisions. Receipts with discarded scalar values remain blocking and the apply
-pass refuses them unless the coordinator explicitly supplies `--force` after
-review. This prevents a routine history repair from silently accepting data
-loss while preserving a zero-noise path for merges that retained both changes.
+Lossless receipts do not become discarded-value decisions and reconcile without
+`--force`, but `pm health` reports `merge_receipts_pending:<n>` and remains
+non-green until the apply pass settles them. `pm history-repair` cannot clear
+that receipt finding. When a drifted item also has a pending receipt, the
+`history_drift` remediation map prioritizes `pm merge reconcile --dry-run` only
+when canonical item path, changed-field, and merged-value hash evidence all
+attribute that finding to one or more receipts loaded from the clone-local Git
+evidence store. Every field declared by each receipt must match its current merged-value
+hash, even when only a subset appears in the history reconciliation diff.
+Disjoint valid receipts may collectively cover a multi-field reconciliation;
+the audit and settlement then retain every individually proven receipt id.
+Serialized source claims are ignored. Receipt readers validate the complete
+bounded schema, safe identifiers, filename and item-path identity, timestamps,
+and bounded decision structure before a sidecar enters health or
+reconciliation. Reads use size-preflighted, no-follow regular-file descriptors;
+durable decisions must retain hash-only values. Legacy or durable-only receipts,
+receipts whose declared fields disagree with their hashes, same-item tampering,
+and drift on unrelated items fail closed to the normal `pm history-repair`
+guidance. Health indexes clone-local evidence once by item and reconciliation
+uses the same per-item groups with a fixed receipt-only worker pool, so committed
+sidecars cannot amplify drift scans into unbounded parallel repair work.
+Apply-mode reconciliation repeats the same proof against the exact
+item snapshot used by the audited history rewrite. The audit event and
+settlement include only the individually proven receipt id, so one valid receipt
+cannot authorize an untrusted same-item sibling. Failed or unproven receipts
+remain pending unless the coordinator explicitly reviews and supplies `--force`.
+Receipts with discarded scalar values retain the distinct
+`merge_decisions_unreviewed:<n>` finding, and the apply pass refuses them unless
+the coordinator explicitly supplies `--force` after review. This prevents a
+routine history repair from hiding unfinished reconciliation or silently
+accepting data loss.
 It exits nonzero while either merge-critical validation check is non-green, so
 CI and explicit post-merge hooks cannot approve unresolved receipts or drift.
 The apply pass uses the audited history rewrite boundary to append a

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -16,7 +16,10 @@ selectors are tracked by
 and canonical TOON tables are tracked by
 [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon) and
 [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon). Nested evidence continuation
-is tracked by [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon).
+is tracked by [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon) and
+[pm-oahhyc](../.agents/pm/issues/pm-oahhyc.toon). Exact command-local
+projection discovery is tracked by
+[pm-q4isdq](../.agents/pm/issues/pm-q4isdq.toon).
 
 ## Agent Quick Context
 
@@ -112,6 +115,15 @@ machine-iterable without a command-specific selector. `fields` is always explici
 shape. NDJSON event streams do not carry an envelope and therefore do not
 publish a row contract.
 
+Projection mode discovery is command-local even though the compatibility
+degradation ladder is global. Read
+`output_projection_contracts.commands` from a command-scoped contracts call or
+the full contracts matrix before selecting a whole-result mode. The
+contract labels the global ladder `union_not_per_command`, so clients cannot
+infer that `list` accepts `summary` or that `health` accepts `compact`.
+`PM_READ_OUTPUT_SURFACE_CONTRACTS[].projection_modes` provides the identical
+canonical matrix to SDK and package consumers.
+
 SDK and package authors can import `PM_READ_ROW_CONTRACTS`,
 `PM_READ_ROW_JQ_SELECTOR`, and `resolveReadRowContract` from
 `@unbrained/pm-cli/sdk`. Existing package declarations are preserved only

package/docs/README.md

@@ -44,6 +44,10 @@ pm guide release --json
 - [SDK Primitive Inventory](SDK_PRIMITIVE_INVENTORY.md) - SDK-first migration map and private-import ratchet for CLI/MCP layering.
 - [Package SDK Contract Conformance](PACKAGE_SDK_CONTRACT_CONFORMANCE.md) - authoritative public types, `typeof` module derivation, and the first-party parity gate.
 - [SDK Action and Boundary Conformance](SDK_ACTION_CONFORMANCE.md) - derived CLI/SDK/MCP action vocabulary, public-import ratchets, intent budget diagnostics, and package-runner proof.
+- [MCP 2026-07-28 Protocol Decision](MCP_2026_07_28.md) - stateless request metadata, discovery, result envelopes, explicit legacy boundary, and migration policy.
+- [MCP 2026-07-28 Conformance Matrix](MCP_2026_07_28_CONFORMANCE.md) - official revision changes mapped to canonical owners and executable evidence.
+- [MCP Interaction and Task SDK](SDK_MCP_INTERACTIONS.md) - public MRTR continuation, cache/schema validation, and durable task-store contracts.
+- [MCP Remote Transport, Authorization, and Migration](MCP_REMOTE_TRANSPORT_SECURITY.md) - Streamable HTTP operation, subscriptions, OAuth and trace boundaries, threat model, and deprecated-feature ratchet.
 - [SDK Artifact Output Contracts](SDK_ARTIFACT_OUTPUT.md) - clean stdout/file exporter channels, bounded receipts, binary-safe delivery, and shared NDJSON terminal framing.
 - [Context Relevance and Packing](CONTEXT_RELEVANCE.md) - shared CLI/SDK signals, derived-store provenance, ranking explanations, and token budgets.
 - [Output Projection and Omission Contracts](OUTPUT_PROJECTION_CONTRACTS.md) - explicit withheld-field receipts, mode-paired row keys, and completion resolver outcomes.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon), and [pm-xam9bt](../.agents/pm/issues/pm-xam9bt.toon).
+Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-oahhyc](../.agents/pm/issues/pm-oahhyc.toon), [pm-q4isdq](../.agents/pm/issues/pm-q4isdq.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon), and [pm-xam9bt](../.agents/pm/issues/pm-xam9bt.toon).
 
 ## Agent Quick Context
 
@@ -60,6 +60,17 @@ removing spelling receipts and volatile run metadata. A selector that matches
 neither a declared mode nor any field on any returned row is refused with the
 legal domain, rather than returning rows with every field removed.
 
+Runtime discovery publishes the same exact vocabulary before invocation.
+`pm contracts --command <command> --summary` returns
+`output_projection_contracts.commands`, while
+`output_projection_contracts.global_ladder_scope: "union_not_per_command"`
+explicitly marks `output_policy.degradation_ladder` as a cross-command union,
+not a promise that every member is accepted by the selected command. For
+example, `list` declares `brief`, `compact`, and `full`; `health` declares
+`brief`, `full`, and `summary`. The full `read_output_dimensions` matrix also
+includes `projection_modes` for every canonical read surface, including an
+explicit empty array when a surface has no whole-result modes.
+
 ## Cross-Call Context Sessions
 
 `--output-session <json>` / `outputSession` composes the four per-call
@@ -164,6 +175,18 @@ an unbounded multi-megabyte response;
 `recovery_budget_multiplier: 1` declares that each next page retains the same
 useful-result ceiling.
 
+Health continuation fingerprints use a versioned nonvolatile-snapshot policy
+for the `checks` row. Command-lifecycle telemetry may refresh timestamps, queue
+counters, and pending spans between pages, so the policy excludes only those
+explicit direct fields from the `telemetry` row's `details`. The row identity,
+verdict, enabled state, capture level, endpoint, environment overrides, probe
+result, and failure errors remain fingerprinted. Every other health check also
+remains fully fingerprinted; changing storage, integrity, history, or another
+stable check fails closed. `PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES`
+publishes the exact ignored detail fields per dynamic row. Other commands still
+fingerprint every field, including fields with the same spelling, and any
+policy-version change fails closed against an older cursor.
+
 When compaction affects a nested collection that is not declared resumable,
 the recovery budget is derived from the larger of the binding ceiling plus one
 and the measured pre-compaction result. The SDK adds a 25% envelope margin and
@@ -221,7 +244,7 @@ const result = await pm.list({
 });
 ```
 
-Package authors should use the exported read-output contracts instead of inventing package-local limit or projection vocabularies. `PM_READ_OUTPUT_SURFACE_CONTRACTS` is the machine-readable matrix and `resolveReadOutputDimensions` plus `applyReadOutputDimensions` are the shared execution primitives.
+Package authors should use the exported read-output contracts instead of inventing package-local limit or projection vocabularies. `PM_READ_OUTPUT_SURFACE_CONTRACTS` is the machine-readable matrix, `PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES` declares stable-snapshot exceptions, and `resolveReadOutputDimensions` plus `applyReadOutputDimensions` are the shared execution primitives.
 
 ## Drift Gates
 

package/docs/RELEASING.md

@@ -386,8 +386,9 @@ git push origin v<version>
   Bun caches plus an empty npm user config so maintainer credentials and cached
   metadata cannot mask a public-registry outage. The verifier dispatches a real
   `pm contracts` command through both explicit-bin and package-default
-  invocations, performs a JSON-RPC initialize handshake against the
-  symlink-resolved `pm-mcp` bin under both npx and bunx, derives bin coverage
+  invocations, performs stateless JSON-RPC `server/discover` against the
+  symlink-resolved `pm-mcp` bin under both npx and bunx, requires canonical
+  `2026-07-28` metadata/result envelopes, derives bin coverage
   from `package.json`, and proves missing-bin and missing-command controls fail.
 - exact-package installed acceptance through
   `scripts/release/verify-installed-agent-session.mjs`. Separate npm and Bun

package/docs/SDK.md

@@ -62,6 +62,13 @@ Terminal recurrence and executable recovery are tracked by
 
 Use it for extension authoring, package authoring, command/action contract discovery, and deterministic app or CI automation. Do not import private `src/core/...` modules from external integrations or packages.
 
+MCP hosts can build on the public stateless protocol, MRTR, cache/schema, and
+durable task primitives described in
+[MCP Interaction and Task SDK](SDK_MCP_INTERACTIONS.md). Those contracts are
+owned by [pm-rz9gep](../.agents/pm/features/pm-rz9gep.toon),
+[pm-rzs24j](../.agents/pm/features/pm-rzs24j.toon), and
+[pm-hv1x1x](../.agents/pm/features/pm-hv1x1x.toon).
+
 ## Install
 
 ```bash
@@ -244,6 +251,7 @@ Common authoring exports:
   the same remediation used by runtime activation.
 - `renderExtensionSurfaceMarkdown` (render a describe summary to a drift-free Markdown reference doc for a package README)
 - `checkExtensionManifestCompatibility` (author-time `pm_min_version`/`pm_max_version` check against a target pm version)
+- `inspectExtensionManifestSchema` / `lintExtensionManifestSchema` (pure raw-manifest schema inspection and actionable finding boundary)
 - `preflightExtension` (one-call capstone: lint + manifest synthesis + version-compat in a single consolidated report)
 - `RESERVED_ITEM_FIELD_NAMES` (the shared runtime/authoring denylist); `lintExtensionBlueprint`, preflight, and the test harness reject blueprint item fields that shadow these metadata keys before publication
 - `EXTENSION_CAPABILITIES`
@@ -2783,8 +2791,18 @@ bound, a `pm_min_version` the target is below, or a `block`-mode `pm_max_version
 the target exceeds) and stays quiet on advisory `*_unchecked` / `*_exceeded_warn`
 warnings, which still load:
 
+Use `lintExtensionManifestSchema(manifest)` when only the manifest vocabulary is
+in scope. It returns stable `manifest_unknown_key` and
+`no_version_bounds_declared` findings without requiring a target pm version.
+Compatibility results retain the existing combined `findings` array, while the
+dedicated lint result gives SDK, CLI, and MCP adapters a stable schema-only
+boundary.
+
 ```ts
-import { checkExtensionManifestCompatibility } from "@unbrained/pm-cli/sdk";
+import {
+  checkExtensionManifestCompatibility,
+  lintExtensionManifestSchema,
+} from "@unbrained/pm-cli/sdk";
 import { assertExtensionManifestCompatible } from "@unbrained/pm-cli/sdk/testing";
 
 // Inspect every bound outcome against a target version…
@@ -2793,6 +2811,9 @@ const report = checkExtensionManifestCompatibility(manifest, {
 });
 //   report.compatible === false, report.findings[0].code === "pm_min_version_unmet", …
 
+const schema = lintExtensionManifestSchema(manifest);
+//   schema.ok === false, schema.findings[0].path === "compatibility", …
+
 // …or fail the package's own suite when a bound would block the load.
 assertExtensionManifestCompatible(manifest, { pmVersion: "2026.6.23" });
 ```

package/docs/SDK_AGENT_SESSION_CONTEXT.md

@@ -152,22 +152,27 @@ invalid values.
 
 ## Cross an MCP boundary
 
-An embedding MCP client can add bounded `provenance` and `episode` fields to
-its initialize `clientInfo`. The server retains only those fields and applies
-them to later tool calls from that initialized client.
+An embedding MCP 2026-07-28 client can add bounded `provenance` and `episode`
+fields to request-local `io.modelcontextprotocol/clientInfo`. The server
+retains only those fields while processing that request; no later request
+inherits them.
 
 ```json
 {
-  "clientInfo": {
-    "name": "agent-host",
-    "version": "1.0.0",
-    "provenance": {
-      "role": "implementer",
-      "topic": "release readiness"
-    },
-    "episode": {
-      "id": "release-2026-08-01",
-      "label": "Release readiness"
+  "_meta": {
+    "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+    "io.modelcontextprotocol/clientCapabilities": {},
+    "io.modelcontextprotocol/clientInfo": {
+      "name": "agent-host",
+      "version": "1.0.0",
+      "provenance": {
+        "role": "implementer",
+        "topic": "release readiness"
+      },
+      "episode": {
+        "id": "release-2026-08-01",
+        "label": "Release readiness"
+      }
     }
   }
 }