@unbrained/pm-cli 2026.8.31 → 2026.9.1

package/dist/sdk/merge/three-way.js

@@ -9,7 +9,7 @@
  * definition for multi-branch agent workflows.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="393f6460-bf8b-5479-8e3e-cac6f2680823")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7e8fcddf-09fe-5979-b23a-78915bf7f896")}catch(e){}}();
 import { historyEntriesToRaw, reanchorHistoryEntries, } from "../../core/history/replay.js";
 import { canonicalDocument, parseItemDocument, serializeItemDocument, } from "../../core/item/item-format.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
@@ -69,7 +69,9 @@ function commonHistoryPrefixLength(ours, theirs) {
  * hash re-anchored so the resulting chain verifies again. No side's events are
  * ever discarded: content divergence is preserved for the post-merge
  * reconciliation pass (`pm validate` + `pm history-repair`) instead of being
- * silently resolved by last-writer-wins.
+ * silently resolved by last-writer-wins. If either suffix cannot apply after
+ * deterministic ordering, the merge fails closed instead of publishing a
+ * hash-valid stream that omitted a branch effect.
  */
 export function mergeHistoryStreams(baseRaw, oursRaw, theirsRaw) {
     parseHistoryJsonl(baseRaw, "base");
@@ -126,10 +128,10 @@ export function mergeHistoryStreams(baseRaw, oursRaw, theirsRaw) {
         }
         return historyEntryIdentity(left).localeCompare(historyEntryIdentity(right));
     });
-    const reanchored = reanchorHistoryEntries([
-        ...ours.slice(0, shared),
-        ...mergedSuffix,
-    ]);
+    const reanchored = reanchorHistoryEntries([...ours.slice(0, shared), ...mergedSuffix], undefined, { continuousHashSurface: true });
+    if (reanchored.skippedOps > 0) {
+        throw new PmCliError(`History union cannot preserve ${reanchored.skippedOps} patch operation(s) after deterministic suffix ordering; leave the file unresolved for manual recovery.`, EXIT_CODE.GENERIC_FAILURE);
+    }
     return {
         merged: historyEntriesToRaw(reanchored.entries),
         strategy: "union_reanchor",
@@ -704,4 +706,4 @@ export function mergeJsonDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
     };
 }
 //# sourceMappingURL=three-way.js.map
-//# debugId=393f6460-bf8b-5479-8e3e-cac6f2680823
+//# debugId=7e8fcddf-09fe-5979-b23a-78915bf7f896

package/dist/sdk/runtime-extended-actions.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="95e9def9-3f48-5108-8a17-0747fcf64f2d")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="41227e35-6354-5208-997b-e8a1cf696bf9")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { transferMutationStdinTokenPolicy } from "./runtime-primitives.js";
@@ -9,7 +9,7 @@ import { runEval } from "./eval.js";
 import { runMergeDriver } from "./merge/driver.js";
 import { runMergeInstall } from "./merge/install.js";
 import { runMergeReconcile } from "./merge/reconcile.js";
-import { runMergeReceiptReport } from "./merge/receipts.js";
+import { runMergeReceiptEvidenceReport } from "./merge/receipts.js";
 import { listMutationEvents } from "./mutation-events.js";
 import { parseRuntimeInteger, readRuntimeString, readRuntimeStringArray, } from "./runtime-input.js";
 import { runEvent, runMeet, runRemind, } from "./scheduling-shortcuts.js";
@@ -87,7 +87,7 @@ export function runRuntimeMergeAction(context) {
         }, context.global);
     }
     if (subcommand === "report") {
-        return runMergeReceiptReport({
+        return runMergeReceiptEvidenceReport({
             includeReconciled: input.includeReconciled === true,
             cwd: readRuntimeString(input, "cwd"),
         });
@@ -175,4 +175,4 @@ export function runRuntimeSchedulingAction(context) {
     return runRemind(title, input, context.global);
 }
 //# sourceMappingURL=runtime-extended-actions.js.map
-//# debugId=95e9def9-3f48-5108-8a17-0747fcf64f2d
+//# debugId=41227e35-6354-5208-997b-e8a1cf696bf9

package/docs/AGENT_GUIDE.md

@@ -4,18 +4,25 @@ This guide is optimized for coding agents that need to understand and mutate rep
 
 ## Agent Quick Context
 
-Run this before heavy work:
+Run this before heavy work. The first call is the canonical cold start. Then run the request-specific duplicate and ownership checks before item mutation:
 
 ```bash
-pm context --limit 10
+pm context --limit 10 --for orient
 pm search "<request keywords>" --limit 10
 pm list --status open --limit 20
 pm list --status in_progress --limit 20
+```
+
+Run the optional guidance setup commands only when needed:
+
+```bash
 pm init --agent-guidance status
 pm package install guide-shell --project
 pm guide workflows
 ```
 
+The completed-task replay gate selects that one-call protocol from equivalent fixed-corpus candidates: 1,055 estimated tokens versus 2,293 for the historical four-read sequence and 4,798 for `contracts --summary` plus `next`. The reviewed numbers and per-step receipts live in [the published token baseline](agent-task-token-baseline.json).
+
 If a relevant item exists, reuse it. If not, create a parent lineage, then create and claim the child implementation item.
 When AGENTS/CLAUDE guidance is missing, use `pm init --agent-guidance add` to inject compact workflow guardrails, or `pm init --agent-guidance skip` to persist an explicit decline.
 
@@ -26,7 +33,7 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 1. **Orient**
 
 ```bash
-pm context --limit 10
+pm context --limit 10 --for orient
 pm search "<keywords>" --limit 10
 pm list --status open --limit 20
 pm list --status in_progress --limit 20
@@ -108,6 +115,7 @@ pm release <item-id>
 | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | The single next action + why         | `pm next` (concrete ready leaves first; completed-container closeout rows surface only when no leaf work is ready; `--ready-only` for the tightest output) |
 | Next ready work in one epic          | `pm next --parent <id>`                                                                                                                                    |
+| Canonical cold-start orientation     | `pm context --limit 10 --for orient` (1,055 estimated tokens on the fixed 101-item replay corpus)                                                          |
 | Next work and agenda                 | `pm context --limit 10`                                                                                                                                    |
 | Comprehensive whole-tracker snapshot | `pm context --depth full` (every section, no per-section row cap)                                                                                          |
 | Status of one epic/subtree           | `pm context --parent <id> --depth deep`                                                                                                                    |

package/docs/ARCHITECTURE.md

@@ -56,9 +56,12 @@ src/
     shared/
   mcp/
     server.ts
+    tool-definitions.ts
   sdk/
     cli-contracts.ts
     index.ts
+    mcp/
+      discovery.ts
   types/
 tests/
   unit/
@@ -287,6 +290,8 @@ allowance file:
 Do not add new CLI/MCP behavior by deep-importing `src/core`. Add or extend an
 SDK primitive first, then consume that SDK surface from the presentation layer.
 
+Progressive tool discovery follows this boundary directly: `src/sdk/mcp/discovery.ts` owns ranking, authorization filtering, budgets, cursors, omissions, cache identity, and the canonical result contract. `src/mcp/server.ts` only negotiates the extension, selects the entry catalog, and adapts compatibility text. See [Progressive Tool Discovery](PROGRESSIVE_TOOL_DISCOVERY.md).
+
 ## Telemetry Schema Negotiation
 
 Telemetry preserves wire compatibility through an explicit client/server negotiation split:

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -55,7 +55,7 @@ This clones the repo, reads `.claude-plugin/marketplace.json` at the root, insta
 claude mcp add --transport stdio pm-mcp -- npx -y --package=@unbrained/pm-cli@latest pm-mcp
 ```
 
-Gives you the 31 MCP tools without skills or slash commands.
+Gives you the 32 MCP tools without skills or slash commands.
 
 ### 3. Direct project `.mcp.json` (project-scoped MCP only)
 
@@ -117,7 +117,7 @@ pnpm smoke:claude-plugin
 ```
 
 Verifies: plugin file structure, manifest name consistency, stateless MCP
-discovery for `2026-07-28`, 31 tools present, full workflow (init → create →
+discovery for `2026-07-28`, 32 tools present, full workflow (init → create →
 claim → update → link files/docs/tests → get → context → search → validate →
 health), and session-start hook.
 

package/docs/CONTEXT_RECOVERY_PRIMITIVES.md

@@ -46,11 +46,20 @@ When multiple entries exist, the SDK selects the requested package by key or `na
 
 ## History and merge recovery
 
-History hash capability 3 distinguishes the current canonical writer surface from older epoch-2 writers while retaining readers for epochs 1 and 2. An unsupported epoch is version skew, not permission to reinterpret or silently normalize history.
-
-Health keeps the metadata-only cache path for clean history streams. A cached hash mismatch, chain mismatch, or writer-version skew is only a candidate: health rereads canonical item sources and verifies stream content hashes before reporting corruption. The `history_drift` details expose `cache_confirmation` candidate, confirmed, and resolved-false-positive item sets, while `cache_hit_verification: metadata_then_content_hash` identifies the authoritative fallback. Drift-cache envelopes also carry the current item-hash capability, so a runtime with incompatible hash semantics rebuilds the cache instead of trusting it.
-
-Merge reconciliation may consume a durable hash-only receipt without `--force` only when its canonical item path, complete declared-field set, and every merged-value hash exactly match the current item snapshot. Raw discarded values remain clone-local. Any incomplete or mismatched proof fails closed.
+History hash capability 3 distinguishes the current canonical writer surface
+from older writers while retaining frozen readers for epochs 1 and 2. Two
+writer surfaces were historically emitted under epoch 2: its earlier form
+excluded linked-test workspace/provenance fields and test-run execution
+receipts while normalizing dependency ids; its later form included those
+fields. Verification recognizes both immutable forms and requires each entry's
+before/after hashes to use one consistent form. Current-document verification
+selects the candidate that matches the verified chain head. An unsupported
+epoch is version skew, not permission to reinterpret or silently normalize
+history.
+
+Health keeps the metadata-only cache path for clean history streams. A cached hash mismatch, chain mismatch, or writer-version skew is only a candidate: health rereads canonical item sources and verifies stream content hashes before reporting corruption. The `history_drift` details expose `cache_confirmation` candidate, confirmed, and resolved-false-positive item sets, while `cache_hit_verification: metadata_then_content_hash` identifies the authoritative fallback. Drift-cache envelopes carry both their schema version and the current item-hash capability, so changing legacy canonicalization invalidates prior verdicts and a runtime with incompatible hash semantics rebuilds the cache instead of trusting it.
+
+Merge reconciliation may consume a durable hash-only receipt without `--force` only when its canonical item path, complete declared-field set, and every merged-value hash exactly match the current item snapshot. Raw discarded values remain clone-local. Any incomplete or mismatched proof fails closed. SDK gates use `inspectMergeReceiptEvidence` or `runMergeReceiptEvidenceReport` to retain the distinction between no evidence, rejected evidence, and clone-local evidence whose Git directory could not be resolved; `clone_local_evidence_resolved=false` makes the loss-aware report incomplete. The list-only and legacy report compatibility projections intentionally return valid receipts only. Diverged history unions also fail closed when deterministic suffix ordering would make any patch operation inapplicable, instead of publishing a rehashed stream with a skipped branch effect.
 
 ## Strict-create recovery
 

package/docs/MCP_2026_07_28.md

@@ -12,7 +12,9 @@ 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). Skills and Apps are tracked
 by [pm-8nzivt](../.agents/pm/features/pm-8nzivt.toon) and
-[pm-pznhee](../.agents/pm/features/pm-pznhee.toon).
+[pm-pznhee](../.agents/pm/features/pm-pznhee.toon). Progressive tool discovery
+and canonical model-facing results are tracked by
+[pm-3g3f8z](../.agents/pm/features/pm-3g3f8z.toon).
 
 Status: accepted. MCP `2026-07-28` is pm's canonical protocol revision.
 
@@ -39,16 +41,18 @@ capabilities, public cache policy, server identity, and bounded instructions.
 No modern request reads identity, capabilities, or version from a previous
 request.
 
+The optional `dev.unbrained.pm/progressive-tool-discovery` extension is also request-local. Negotiated clients receive a stable five-tool entry catalog and expand it with `pm_discover`; unnegotiated clients retain the complete profile-selected list. Negotiated tool results designate `structuredContent.result` as canonical and use text content only as a pointer, while the isolated compatibility adapter retains duplicated JSON text for existing clients. The public SDK owns ranking, cursor binding, token and omission receipts, and cache invalidation. See [Progressive Tool Discovery](PROGRESSIVE_TOOL_DISCOVERY.md).
+
 ## Legacy boundary
 
 Legacy means every revision that establishes a session with an `initialize`
 handshake, which the canonical revision defines as `2025-11-25` and earlier.
 The stdio adapter therefore accepts the full initialize-era set, newest first:
 
-| Revision | Accepted at `initialize` | Notes |
-|----------|--------------------------|-------|
-| `2025-11-25` | yes | Final legacy revision; offered when a client omits `protocolVersion` |
-| `2025-06-18` | yes | Earlier legacy revision retained for existing consumers |
+| Revision     | Accepted at `initialize` | Notes                                                                |
+| ------------ | ------------------------ | -------------------------------------------------------------------- |
+| `2025-11-25` | yes                      | Final legacy revision; offered when a client omits `protocolVersion` |
+| `2025-06-18` | yes                      | Earlier legacy revision retained for existing consumers              |
 
 `initialize` answers with the revision the client requested, because a legacy
 client has no fall-forward mechanism and treats the answered version as the

package/docs/MCP_CAPABILITY_SURFACES.md

@@ -1,6 +1,6 @@
 # Runtime capability surfaces
 
-Tracker: [pm-xwah](../.agents/pm/chores/pm-xwah.toon), [pm-kxci8x](../.agents/pm/tasks/pm-kxci8x.toon), [pm-mu8m](../.agents/pm/tasks/pm-mu8m.toon), [pm-9k90](../.agents/pm/features/pm-9k90.toon), [pm-m4ikkz](../.agents/pm/features/pm-m4ikkz.toon), [pm-yf07b7](../.agents/pm/features/pm-yf07b7.toon)
+Tracker: [pm-xwah](../.agents/pm/chores/pm-xwah.toon), [pm-kxci8x](../.agents/pm/tasks/pm-kxci8x.toon), [pm-mu8m](../.agents/pm/tasks/pm-mu8m.toon), [pm-9k90](../.agents/pm/features/pm-9k90.toon), [pm-m4ikkz](../.agents/pm/features/pm-m4ikkz.toon), [pm-yf07b7](../.agents/pm/features/pm-yf07b7.toon), and [pm-3g3f8z](../.agents/pm/features/pm-3g3f8z.toon).
 
 The SDK exports one agent capability contract for command visibility, MCP tool profiles, resources, and workflow prompts. CLI-facing generators and MCP hosts should project from these contracts instead of maintaining independent allowlists.
 
@@ -15,6 +15,12 @@ Set `PM_MCP_PROFILE` for the `pm-mcp` process:
 
 An activated extension command makes `pm_run` discoverable outside a custom profile. Its action is added to the live `pm_run` action enumeration. Custom profiles remain exact allowlists.
 
+## Progressive discovery
+
+Modern clients may negotiate `dev.unbrained.pm/progressive-tool-discovery`. Their initial `tools/list` response is the stable five-tool entry catalog, and `pm_discover` expands authorized tools by intent, family, and tier under explicit row and token ceilings. Unnegotiated and initialize-era clients retain the full selected profile.
+
+The SDK ranks with visible lexical, semantic, graph, permission, freshness, and usage signals, binds cursors to all ranking inputs, and emits omission recovery plus cache invalidation metadata. Negotiated tool calls make `structuredContent.result` canonical and replace duplicated JSON text with a pointer; compatibility clients retain the old representation. See [Progressive Tool Discovery](PROGRESSIVE_TOOL_DISCOVERY.md).
+
 Package authors can declare `tier: "core" | "standard" | "full" | "internal"` on `registerCommand()` definitions. The default is `standard`; `internal` commands remain callable by native dispatch but are not advertised by normal MCP profiles.
 
 ## Workspace schema projection

package/docs/MCP_REMOTE_TRANSPORT_SECURITY.md

@@ -1,6 +1,7 @@
 # MCP Remote Transport, Authorization, and Migration
 
-Tracker references: [pm-v7e337](../.agents/pm/features/pm-v7e337.toon),
+Tracker references: [pm-3g3f8z](../.agents/pm/features/pm-3g3f8z.toon),
+[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).
 
@@ -36,6 +37,7 @@ Configuration is explicit and environment-only:
 | `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` |
+| `PM_MCP_DISCOVERY_CURSOR_KEY` | Shared 32-byte-or-longer secret for discovery pages | process-local key  |
 
 A non-loopback bind fails closed unless token, issuer, and resource are all
 present. Production deployments should normally call
@@ -50,9 +52,17 @@ placing a real credential in documentation:
 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_DISCOVERY_CURSOR_KEY='<32-byte-or-longer-random-secret>' \
 pm-mcp-http
 ```
 
+Single-process deployments may omit the discovery cursor key. That selects a
+random process-local HMAC key and deliberately makes pagination process-affine:
+a restart or another worker rejects the cursor as stale. Multi-worker or
+restart-continuous deployments must provide the same high-entropy value to
+every worker. Rotating it invalidates outstanding discovery cursors without
+exposing the key in MCP input, output, errors, traces, or cache identities.
+
 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.

package/docs/MERGE_SAFETY.md

@@ -97,7 +97,20 @@ pm merge report
 pm merge report --include-reconciled
 ```
 
-The underlying public SDK exports are `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, `runMergeInstall`, `installMergeFence`, `findGitWorkspaceRoot`, `runMergeReconcile`, `runMergeReceiptReport`, `listMergeReceipts`, `auditMergeDriverConfiguration`, `refreshMergeAttributeFenceIfInstalled`, `buildMergeAttributePatterns`, and `auditMergeAttributeFence` from `@unbrained/pm-cli/sdk`. `installMergeFence` accepts explicit tracker and workspace roots, so custom init hosts do not depend on process cwd or CLI globals.
+The underlying public SDK exports are `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, `runMergeInstall`, `installMergeFence`, `findGitWorkspaceRoot`, `runMergeReconcile`, `runMergeReceiptReport`, `runMergeReceiptEvidenceReport`, `inspectMergeReceiptEvidence`, `listMergeReceipts`, `auditMergeDriverConfiguration`, `refreshMergeAttributeFenceIfInstalled`, `buildMergeAttributePatterns`, and `auditMergeAttributeFence` from `@unbrained/pm-cli/sdk`. `installMergeFence` accepts explicit tracker and workspace roots, so custom init hosts do not depend on process cwd or CLI globals.
+
+`listMergeReceipts` is the compatibility projection for callers that only need
+validated receipts. It cannot distinguish an empty evidence store from a store
+whose candidates were all rejected. Gates and diagnostic integrations should
+use `inspectMergeReceiptEvidence`, whose `invalid_evidence_count` preserves
+that distinction without returning malformed contents.
+`runMergeReceiptEvidenceReport` and `pm merge report --json` expose the same
+loss-aware contract through `complete`, `invalid_evidence_count`, and
+`clone_local_evidence_resolved`; the CLI
+exits nonzero when evidence is incomplete, even when the valid-receipt count is
+zero. Current SDK implementations always emit the new field, while its optional
+type preserves structural compatibility for existing typed adapters and test
+fixtures. `runMergeReceiptReport` remains the compatible valid-only report.
 
 ## Cross-branch id collision safety
 
@@ -189,7 +202,22 @@ pm merge reconcile --dry-run --json
 
 `history-repair` records the reconciliation patch and classifies its changed fields against the final item. Append-only collection unions and deterministic reordering are reported as preserved context without a data-loss warning. Fields whose replayed values are actually removed or replaced remain loud with discarded event authors/operations and recovery guidance. Re-apply any intended losing mutation as a normal `pm update` so it remains explicit and auditable.
 
-History events now declare an item-hash epoch. The current epoch preserves linked-test insertion order; unversioned streams are verified against both the legacy sorted-test canonicalization and the order-preserving canonicalization. An unknown explicit epoch is reported as `unsupported_item_hash_version` and repair refuses to guess. This keeps version incompatibility distinct from item corruption and is tracked by [pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon).
+History events now declare an item-hash epoch. Epochs are immutable writer
+contracts, not aliases for the current item serializer: epoch 1 sorts linked
+tests; epoch 2 preserves their insertion order and has both an earlier
+field-frozen form and a later expanded form because the writer surface grew
+before the marker advanced; epoch 3 is the current form. Verification accepts
+both recorded epoch-2 forms without allowing one entry to mix them, and repair
+preserves the form evidenced by each event. Unversioned streams are verified
+against the supported legacy canonicalizations. Current-document comparison
+selects the resolved epoch candidate that matches the chain head. A union merge
+may consume suffixes written by both epoch-2 forms, but its synthesized output
+uses one form for the complete re-anchored stream so every stored `after_hash`
+is exactly the next stored `before_hash`. An unknown explicit epoch is
+reported as `unsupported_item_hash_version` and repair refuses to guess. This
+keeps version incompatibility distinct from item corruption and is tracked by
+[pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon) and
+[pm-2qahia](../.agents/pm/issues/pm-2qahia.toon).
 
 ## Delete versus modify policy
 

package/docs/OUTPUT_TOKEN_ACCOUNTING.md

@@ -1,6 +1,6 @@
 # Output Token Accounting
 
-Tracker references: [pm-t5dt4z](../.agents/pm/tasks/pm-t5dt4z.toon), [pm-g3n00m](../.agents/pm/stories/pm-g3n00m.toon), [pm-8pnj](../.agents/pm/features/pm-8pnj.toon), [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
+Tracker references: [pm-t5dt4z](../.agents/pm/tasks/pm-t5dt4z.toon), [pm-g3n00m](../.agents/pm/stories/pm-g3n00m.toon), [pm-8pnj](../.agents/pm/features/pm-8pnj.toon), [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), and [pm-jjqyzd](../.agents/pm/issues/pm-jjqyzd.toon).
 
 ## Agent Quick Context
 
@@ -39,7 +39,9 @@ The command still exits with its normal non-zero status; the receipt is additive
 
 ## Release-Level Task Entitlement
 
-[`agent-task-transcripts.json`](agent-task-transcripts.json) is the SDK-validated, versioned golden corpus. [`agent-task-token-baseline.json`](agent-task-token-baseline.json) is its externally shipped release ratchet. The gate executes the built CLI against independent, identically seeded accounting-on and accounting-off workspaces. Its five complete workflows cover:
+[`agent-task-transcripts.json`](agent-task-transcripts.json) is the SDK-validated, versioned golden corpus. [`agent-task-token-baseline.json`](agent-task-token-baseline.json) is its externally shipped release ratchet. The gate executes the built CLI against independent, identically seeded accounting-on and accounting-off workspaces. Its eight complete workflows cover:
+
+- three equivalent cold-start protocols and a fail-closed rule that the documented canonical protocol must remain the measured winner: `context --for orient` at 1,055 estimated tokens, the historical four-read sequence at 2,293, and `contracts --summary` plus `next` at 4,798 on the fixed 101-item corpus;
 
 - bounded triage, scaled-workspace orientation, and returning-agent inspection;
 - a closed-domain refusal followed by the exact advertised shell-free retry;
@@ -49,7 +51,7 @@ The command still exits with its normal non-zero status; the receipt is additive
 
 Every step verifies its public SDK output family, canonical successful or refusal exit status, required own-property paths, declared `expected_field_values`, and refusal identity where applicable. Recovery steps must declare a successful output family instead of chaining one refusal to another, every refusal in a completed task must have a later successful `recovery_for` step, and every completed task must terminate with successful output. Successful steps cannot carry refusal-only metadata. Dot-separated `required_fields` and `expected_field_values` paths are traversed structurally from the output root, so incidental prose or nested key names cannot satisfy completeness or terminal-state assertions. The report publishes bytes and estimated tokens for each step and completed task, retry counts, corpus digest, and composite cost. Accounting-on application payloads must be byte-equivalent to their independently captured accounting-off payloads after removing only the receipt. Receipt byte and token fields are independently measured rather than trusted. Runtime refusals verify that their self-reported `total_bytes` matches the independent transport and that `total_estimated_tokens` equals `ceil(total_bytes / 4)`; Commander usage refusals that happen before accounting attachment are measured directly from the captured transport and labeled `independent_transport`.
 
-The baseline fails closed on corpus digest, task identity, step identity, missing or non-finite per-step and per-task ceilings, and missing or non-finite composite cost ceilings. A seeded million-token completed-task regression proves the ratchet fails. Run it with:
+The baseline fails closed on corpus digest, task identity, step identity, the canonical orientation winner and its ceiling, missing or non-finite per-step and per-task ceilings, and missing or non-finite composite cost ceilings. A seeded million-token completed-task regression proves the ratchet fails. Run it with:
 
 ```bash
 pnpm quality:agent-task-token

package/docs/PROGRESSIVE_TOOL_DISCOVERY.md

@@ -0,0 +1,42 @@
+# Progressive Tool Discovery
+
+Tracker: [pm-3g3f8z](../.agents/pm/features/pm-3g3f8z.toon).
+
+`pm` exposes a public SDK discovery engine and an opt-in MCP extension for large tool catalogs. The design keeps the full legacy-compatible catalog available while allowing capable clients to attach only a small entry surface and expand it by intent.
+
+## Negotiation and entry catalog
+
+`server/discover` advertises the namespaced `dev.unbrained.pm/progressive-tool-discovery` extension. A client opts in by returning that extension in the request-local MCP capabilities on every modern request. Negotiated `tools/list` responses contain the stable entry catalog:
+
+- `pm_discover` for bounded capability expansion;
+- `pm_next` and `pm_context` for action and workspace orientation;
+- `pm_search` and `pm_get` for targeted retrieval.
+
+Clients that do not negotiate the extension receive the complete profile-selected tool list. Legacy initialize-era clients are unchanged.
+
+## Public SDK contract
+
+`discoverPmTools()` accepts an authorization-filtered candidate catalog plus query, family, tier, limit, cursor, schema projection, profile, output-budget, and optional host-owned cursor-integrity-key options. It returns:
+
+- deterministic score-then-name ordering;
+- lexical, semantic, graph, permission, freshness, and usage scores with public weights and source provenance;
+- a tamper-evident cursor bound to query, filters, schemas, authorization-filtered catalog, ranking inputs, and either the private discovery process or an explicit shared host key;
+- exact estimated token cost and a fail-closed `within_budget` verdict;
+- explicit schema, row-limit, and token-budget omission receipts with recovery;
+- a private cache key, 30-second TTL, and named invalidation events.
+
+Hosts may supply normalized semantic, graph, freshness, and usage signals. Missing host values use documented deterministic fallbacks, and the result identifies every signal source; the formula never changes implicitly.
+
+SDK hosts that route pages across processes or restarts must pass the same random, secret `cursorIntegrityKey` of at least 32 bytes on every call. Omitting it deliberately selects a random process-local key: that securely enforces process affinity, and a cursor reaching another process fails closed as stale. The bundled MCP adapter reads the shared key from `PM_MCP_DISCOVERY_CURSOR_KEY`; local stdio needs no override, while multi-worker or restart-continuous HTTP deployments must configure one shared high-entropy value.
+
+## Canonical tool results
+
+Negotiated clients treat `structuredContent.result` as the single canonical model-facing application result. The text content becomes a stable pointer instead of a second JSON serialization. Errors use the same rule through `structuredContent`.
+
+Unnegotiated and legacy clients retain the prior duplicated JSON text plus structured result. That compatibility behavior is isolated at the MCP adapter boundary; domain operations and SDK results do not branch on transport generation.
+
+## Scale and change safety
+
+The discovery quality gate exercises selection, deterministic pagination, stale-cursor refusal, permission filtering, schema recovery, and token ceilings at 100, 1,000, and 10,000 candidate tools. Contract snapshots cover the tool schema, and modern MCP integration tests prove both negotiated and compatibility modes.
+
+Any tool-definition, workspace-extension, profile, authorization, ranking-signal, or cursor-key change invalidates prior cursors and cache entries. Process-local cursors also expire when that process exits. Clients restart discovery without a cursor after an explicit stale-cursor refusal.

package/docs/README.md

@@ -45,6 +45,7 @@ pm guide release --json
 - [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.
+- [Progressive Tool Discovery](PROGRESSIVE_TOOL_DISCOVERY.md) - opt-in bounded MCP catalogs, public SDK ranking and pagination, canonical results, and compatibility isolation.
 - [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 Skills and Apps](MCP_SKILLS_AND_APPS.md) - negotiated draft workflow discovery, stable interactive views, digests, provenance, accessibility, and trust boundaries.

package/docs/agent-task-token-baseline.json

@@ -1,11 +1,165 @@
 {
-  "version": 3,
+  "version": 4,
   "transcript_version": 2,
-  "transcript_digest": "sha256:2bf91406426d2a9e5de1da10ba67f7b8e9d4a4baa09eb488fe89ae3925c78f3f",
+  "transcript_digest": "sha256:4f9e96bb6ce12bbbeb2514e4bd5958d201c4e62e95083bcbebd749d1e48cc82d",
   "estimator": "ceil(utf8_bytes / 4)",
   "measurement_scope": "output_before_token_accounting",
   "published_with_release": true,
+  "orientation": {
+    "canonical_task_id": "orientation-context-intent",
+    "required_capabilities": [
+      "actionable_work",
+      "active_ownership",
+      "workspace_state"
+    ],
+    "measured_winner_tokens": 1055,
+    "protocols": [
+      {
+        "task_id": "orientation-context-intent",
+        "command_count": 1,
+        "estimated_tokens": 1055,
+        "capabilities": [
+          "actionable_work",
+          "active_ownership",
+          "workspace_state"
+        ],
+        "capability_evidence": {
+          "actionable_work": [
+            {
+              "step_id": "context",
+              "field_path": "hierarchy"
+            }
+          ],
+          "active_ownership": [
+            {
+              "step_id": "context",
+              "field_path": "activity"
+            }
+          ],
+          "workspace_state": [
+            {
+              "step_id": "context",
+              "field_path": "summary.active_items"
+            }
+          ]
+        }
+      },
+      {
+        "task_id": "orientation-operating-rules",
+        "command_count": 4,
+        "estimated_tokens": 2293,
+        "capabilities": [
+          "actionable_work",
+          "active_ownership",
+          "workspace_state"
+        ],
+        "capability_evidence": {
+          "actionable_work": [
+            {
+              "step_id": "open",
+              "field_path": "items"
+            }
+          ],
+          "active_ownership": [
+            {
+              "step_id": "in-progress",
+              "field_path": "items"
+            }
+          ],
+          "workspace_state": [
+            {
+              "step_id": "context",
+              "field_path": "summary.active_items"
+            }
+          ]
+        }
+      },
+      {
+        "task_id": "orientation-contracts-next",
+        "command_count": 2,
+        "estimated_tokens": 4798,
+        "capabilities": [
+          "actionable_work",
+          "active_ownership",
+          "workspace_state"
+        ],
+        "capability_evidence": {
+          "actionable_work": [
+            {
+              "step_id": "next",
+              "field_path": "recommended.id"
+            }
+          ],
+          "active_ownership": [
+            {
+              "step_id": "next",
+              "field_path": "held_by_others"
+            }
+          ],
+          "workspace_state": [
+            {
+              "step_id": "next",
+              "field_path": "summary.in_progress"
+            }
+          ]
+        }
+      }
+    ]
+  },
   "tasks": [
+    {
+      "id": "orientation-context-intent",
+      "max_estimated_tokens": 1055,
+      "steps": [
+        {
+          "id": "context",
+          "max_estimated_tokens": 1055,
+          "accounting_mode": "self_reported"
+        }
+      ]
+    },
+    {
+      "id": "orientation-contracts-next",
+      "max_estimated_tokens": 4798,
+      "steps": [
+        {
+          "id": "contracts",
+          "max_estimated_tokens": 4111,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "next",
+          "max_estimated_tokens": 687,
+          "accounting_mode": "self_reported"
+        }
+      ]
+    },
+    {
+      "id": "orientation-operating-rules",
+      "max_estimated_tokens": 2293,
+      "steps": [
+        {
+          "id": "context",
+          "max_estimated_tokens": 1055,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "search",
+          "max_estimated_tokens": 164,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "open",
+          "max_estimated_tokens": 878,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "in-progress",
+          "max_estimated_tokens": 196,
+          "accounting_mode": "self_reported"
+        }
+      ]
+    },
     {
       "id": "context-bootstrap",
       "max_estimated_tokens": 1978,
@@ -107,5 +261,5 @@
       ]
     }
   ],
-  "composite_max_estimated_tokens": 4331
+  "composite_max_estimated_tokens": 12477
 }