@unbrained/pm-cli 2026.8.25 → 2026.8.26

package/docs/MCP_2026_07_28.md

@@ -0,0 +1,138 @@
+# MCP 2026-07-28 Protocol and Compatibility Decision
+
+Tracker references: [pm-sqvshj](../.agents/pm/decisions/pm-sqvshj.toon),
+[pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon), and
+[pm-55yf1t](../.agents/pm/tasks/pm-55yf1t.toon). MRTR, durable tasks,
+and the cache/schema surface are tracked 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). Subscriptions,
+Streamable HTTP, remote authorization, and the deprecation ratchet are tracked
+by [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).
+
+Status: accepted. MCP `2026-07-28` is pm's canonical protocol revision.
+
+## Decision
+
+The public pm SDK owns protocol versions, request metadata validation,
+capability checks, discovery, result envelopes, error codes, HTTP header
+parity, subscriptions, authorization boundaries, trace isolation, and legacy
+result interpretation. `pm-mcp` is a JSON-RPC/stdio adapter over those
+contracts; `pm-mcp-http` binds the same dispatcher to sessionless Streamable
+HTTP POST.
+
+Modern requests are stateless. Every request carries:
+
+- `io.modelcontextprotocol/protocolVersion` = `2026-07-28`;
+- `io.modelcontextprotocol/clientCapabilities` as an object, including `{}`;
+- optional `io.modelcontextprotocol/clientInfo` with `name` and `version`.
+
+Every modern result carries an explicit `resultType` (`complete`,
+`input_required`, or `task`) and `io.modelcontextprotocol/serverInfo` in
+result `_meta`. The mandatory
+`server/discover` method returns the supported modern revisions, deterministic
+capabilities, public cache policy, server identity, and bounded instructions.
+No modern request reads identity, capabilities, or version from a previous
+request.
+
+## Legacy boundary
+
+The sole supported legacy revision is `2025-06-18`, accepted through the
+existing stdio adapter. Unversioned requests stay on this legacy path because
+they cannot claim the current revision; `initialize` enriches their client
+identity but is not required for compatibility with older pm hosts. The
+adapter has no session id, does not affect modern requests, and is excluded
+from `server/discover`'s `supportedVersions` because it cannot be selected
+through modern per-request metadata.
+
+The adapter is scheduled for removal only after published-client telemetry and
+release probes show no required legacy consumers for two consecutive release
+windows. Removal is a reviewed compatibility change, never a history rewrite.
+
+## Transport behavior
+
+- Stdio modern clients call `server/discover` with current request metadata,
+  then send the same version and capability keys on every request.
+- Stdio legacy clients retain their existing response shapes and may use
+  `initialize` with `2025-06-18` to supply client identity.
+- Streamable HTTP requires `MCP-Protocol-Version` and `Mcp-Method` on every
+  request. `Mcp-Name` is required only for `prompts/get`, `resources/read`, and
+  `tools/call`; other methods omit it. Schema-declared `x-mcp-header` values are
+  encoded, decoded, and compared with tool arguments before dispatch.
+  Header/version mismatch uses code `-32020` and HTTP 400.
+- `subscriptions/listen` is a request-scoped stdio or SSE stream. The first
+  message acknowledges the supported filter; later messages carry its request
+  id as `io.modelcontextprotocol/subscriptionId`. Disconnect deletes the
+  subscription and a caller retries lost work with a new request id.
+- The remote adapter defaults to loopback, enforces exact browser origins,
+  bounds bodies, maps parse/invalid requests to HTTP 400, and can require an
+  issuer-, audience-, and scope-bound bearer token.
+- Unsupported modern versions return `-32022` plus the exact supported modern
+  list. Missing required capabilities return `-32021` with a structured
+  capability map. Malformed metadata uses JSON-RPC Invalid Params `-32602`.
+
+## Removed, migrated, and deprecated behavior
+
+| Prior behavior                                                    | Disposition                                                                                                 |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `initialize` and `notifications/initialized`                      | Legacy stdio adapter only; absent from modern behavior.                                                     |
+| `Mcp-Session-Id` and protocol sessions                            | Removed; explicit application handles are ordinary arguments.                                               |
+| `ping`                                                            | Legacy adapter only; modern calls return Method Not Found.                                                  |
+| `resources/subscribe` and `resources/unsubscribe`                 | Replaced by the implemented `subscriptions/listen` filter.                                                  |
+| SSE event ids and `Last-Event-ID` replay                          | Removed; callers retry with a new request id.                                                               |
+| Reverse `roots/list`, sampling, and elicitation requests          | Migrate to MRTR `input_required` under `pm-rz9gep`.                                                         |
+| Core tasks                                                        | Migrate to `io.modelcontextprotocol/tasks` under `pm-rzs24j`.                                               |
+| `logging/setLevel`                                                | Removed; optional request-local log metadata is never shared, and remote operations use host OpenTelemetry. |
+| Roots, Sampling, Logging, HTTP+SSE, and non-none `includeContext` | Retain only in bounded legacy compatibility while `pm-vzcisw` drives deprecation removal.                   |
+| Dynamic Client Registration                                       | Legacy authorization fallback; Client ID Metadata Documents are canonical under `pm-3zh9s4`.                |
+
+## Rollout, rollback, and proof
+
+Local and hosted gates must prove SDK primitives, direct server calls, real
+stdio, packed artifacts, npx, bunx, and published artifacts agree on discovery
+and the canonical revision. Negative controls cover unsupported versions,
+missing/malformed metadata, missing capabilities, header mismatch, removed
+methods, and omitted modern `resultType`.
+
+Rollback preserves the SDK contract and re-enables only the reviewed legacy
+adapter. It must never reintroduce session ids or make modern behavior depend
+on initialization. Release evidence records exact source, package, tag, and
+consumer revisions separately.
+
+## MRTR, tasks, and cache behavior
+
+An SDK handler that cannot finish without host input throws
+`PmMcpInputRequiredError`. The modern adapter validates the requested
+`elicitation/create`, `roots/list`, or `sampling/createMessage` capability and
+returns `resultType: "input_required"`. Continuation state can be bounded,
+HMAC-sealed, expiry-bound, method-bound, parameter-bound, principal-bound, and
+protected from in-process replay with the public interaction helpers. Retry
+payloads arrive as request-local `inputResponses`; they never depend on a
+protocol session.
+
+Clients negotiate `io.modelcontextprotocol/tasks` in request capabilities.
+Eligible long-running `tools/call` operations can then return a durable task
+handle. `tasks/get`, `tasks/update`, and `tasks/cancel` are principal-scoped,
+persist records atomically under the ignored tracker runtime area, enforce
+immutable terminal states, expire abandoned work deterministically, and turn
+a disappeared worker into an actionable terminal failure. Task state remains
+retrieved through the task methods. Change subscriptions do not become
+task-progress channels, and pm's current handlers do not emit request progress
+or deprecated log-message notifications.
+
+Modern tool, resource, resource-template, and prompt list/read results carry
+explicit `ttlMs` and `cacheScope`. Tool schemas are validated as bounded JSON
+Schema 2020-12 documents before advertisement. Tool and resource data stay
+private; public metadata lists may be cached for their advertised lifetime.
+
+## Public SDK
+
+Use `PM_MCP_PROTOCOL_VERSION`, `resolveMcpRequestContext()`,
+`buildMcpDiscoverResult()`, `buildMcpCompleteResult()`,
+`PmMcpSubscriptionRegistry`, `buildMcpHttpRequestHeaders()`,
+`validateMcpHttpRequestHeaders()`, `buildMcpProtectedResourceMetadata()`, and
+the issuer/trace authorization helpers from `@unbrained/pm-cli/sdk`. See
+[MCP interaction and task SDK](SDK_MCP_INTERACTIONS.md) and
+[remote transport, authorization, and migration](MCP_REMOTE_TRANSPORT_SECURITY.md).

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/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/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"
+      }
     }
   }
 }