@unbrained/pm-cli 2026.8.31 → 2026.9.1

package/dist/core/history/drift-scan.js

@@ -1,14 +1,14 @@
 
-!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]="65c0fed6-315a-5930-a23f-83996d3f5081")}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]="1c6c65ef-115b-50e2-815e-84f6e91158cd")}catch(e){}}();
 import fs from "node:fs/promises";
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { getHistoryPath } from "../store/paths.js";
 import { isFileMissingError, writeFileAtomic } from "../fs/fs-utils.js";
-import { CURRENT_HISTORY_ITEM_HASH_VERSION, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, hashDocumentForVersion, } from "./history.js";
+import { CURRENT_HISTORY_ITEM_HASH_VERSION, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, hashDocumentVerificationCandidates, } from "./history.js";
 import { verifyHistoryChainWithVersion } from "./replay.js";
 import { getWorkspaceHistoryPath, inspectWorkspaceHistoryState, WORKSPACE_HISTORY_ID, } from "./workspace-history.js";
-const DRIFT_CACHE_VERSION = 7;
+const DRIFT_CACHE_VERSION = 9;
 const DRIFT_CACHE_FILENAME = "history-drift-cache.json";
 function getDriftCachePath(pmRoot) {
     return path.join(pmRoot, "runtime", DRIFT_CACHE_FILENAME);
@@ -237,8 +237,8 @@ async function scanItemHistory(pmRoot, item, cache, accumulator) {
     const { body, ...itemMetadata } = item;
     if (!resolved.verification.latestHashComparable)
         return resolved.cacheDirty;
-    const currentHash = hashDocumentForVersion({ metadata: itemMetadata, body }, resolved.verification.itemHashVersion);
-    if (currentHash !== resolved.verification.latestAfterHash)
+    const currentHashes = hashDocumentVerificationCandidates({ metadata: itemMetadata, body }, resolved.verification.itemHashVersion);
+    if (!currentHashes.includes(resolved.verification.latestAfterHash))
         accumulator.hashMismatches.push(item.id);
     return resolved.cacheDirty;
 }
@@ -330,4 +330,4 @@ export async function scanHistoryDrift(pmRoot, items, options = {}) {
     return { ...accumulator, driftedItems };
 }
 //# sourceMappingURL=drift-scan.js.map
-//# debugId=65c0fed6-315a-5930-a23f-83996d3f5081
+//# debugId=1c6c65ef-115b-50e2-815e-84f6e91158cd

package/dist/core/history/history.d.ts

@@ -12,6 +12,12 @@ declare function isDefinedPointerPath(document: unknown, path: string): boolean;
 export declare function hashDocument(document: ItemDocument): string;
 /** Hash an item with an explicit canonicalization epoch for replay compatibility. */
 export declare function hashDocumentForVersion(document: ItemDocument, version: HistoryItemHashVersion): string;
+/**
+ * Return the ordered hash candidates accepted when verifying one immutable
+ * history epoch. Epoch 2 has both its established expanded hash first and the
+ * earlier field-frozen writer hash second; the other epochs have one form.
+ */
+export declare function hashDocumentVerificationCandidates(document: ItemDocument, version: HistoryItemHashVersion): [string, ...string[]];
 /** Implements hash empty document for the public runtime surface of this module. */
 export declare function hashEmptyDocument(): string;
 /** Implements create history entry for the public runtime surface of this module. */

package/dist/core/history/history.js

@@ -4,7 +4,7 @@
  * Implements append-only history and replay behavior for History.
  */
 
-!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]="8581413f-e74e-5db3-86bf-5e39290de741")}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]="60d6ec0e-a8ed-5a5d-b5bd-d29da8532a79")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { runActiveServiceOverride } from "../extensions/index.js";
@@ -117,7 +117,7 @@ function normalizeHistoryPatchOps(beforeDocument, patch) {
     }
     return normalized;
 }
-function canonicalHashDocument(document, version) {
+function canonicalHashDocument(document, version, legacyV2Fields = false) {
     const hasMetadata = document.metadata && Object.keys(document.metadata).length > 0;
     if (!hasMetadata) {
         return {
@@ -126,12 +126,40 @@ function canonicalHashDocument(document, version) {
         };
     }
     const canonical = canonicalDocument(document);
-    const metadata = version === 1 && canonical.metadata.tests
+    // Epoch 1 and the earliest epoch-2 writer predate linked-test provenance,
+    // workspace isolation, per-execution receipts, and case-preserving
+    // dependency ids. Later epoch-2 writers included those fields without
+    // advancing the marker, so verification must retain both immutable forms.
+    const usesLegacyFields = version === 1 || (version === 2 && legacyV2Fields);
+    const epochMetadata = usesLegacyFields
         ? {
             ...canonical.metadata,
-            tests: [...canonical.metadata.tests].sort(compareLegacyLinkedTests),
+            ...(canonical.metadata.dependencies === undefined
+                ? {}
+                : {
+                    dependencies: canonical.metadata.dependencies.map((dependency) => ({
+                        ...dependency,
+                        id: dependency.id.toLowerCase(),
+                    })),
+                }),
+            ...(canonical.metadata.tests === undefined
+                ? {}
+                : {
+                    tests: canonical.metadata.tests.map(({ workspace_context_mode: _workspaceContextMode, provenance: _provenance, provenance_invalid: _provenanceInvalid, ...test }) => test),
+                }),
+            ...(canonical.metadata.test_runs === undefined
+                ? {}
+                : {
+                    test_runs: canonical.metadata.test_runs.map(({ executions: _executions, ...testRun }) => testRun),
+                }),
         }
         : canonical.metadata;
+    const metadata = version === 1 && epochMetadata.tests
+        ? {
+            ...epochMetadata,
+            tests: [...epochMetadata.tests].sort(compareLegacyLinkedTests),
+        }
+        : epochMetadata;
     const orderedMetadata = orderObject(toItemRecord(metadata), ITEM_METADATA_KEY_ORDER);
     return {
         front_matter: orderedMetadata,
@@ -164,6 +192,20 @@ export function hashDocumentForVersion(document, version) {
     }
     return sha256Hex(stableStringify(canonicalHashDocument(document, version)));
 }
+/**
+ * Return the ordered hash candidates accepted when verifying one immutable
+ * history epoch. Epoch 2 has both its established expanded hash first and the
+ * earlier field-frozen writer hash second; the other epochs have one form.
+ */
+export function hashDocumentVerificationCandidates(document, version) {
+    const canonicalHash = hashDocumentForVersion(document, version);
+    return version === 2
+        ? [
+            canonicalHash,
+            sha256Hex(stableStringify(canonicalHashDocument(document, version, true))),
+        ]
+        : [canonicalHash];
+}
 /** Implements hash empty document for the public runtime surface of this module. */
 export function hashEmptyDocument() {
     return sha256Hex(stableStringify(EMPTY_LEGACY_HASH_DOCUMENT));
@@ -292,4 +334,4 @@ export const _testOnly = {
     isDefinedPointerPath,
 };
 //# sourceMappingURL=history.js.map
-//# debugId=8581413f-e74e-5db3-86bf-5e39290de741
+//# debugId=60d6ec0e-a8ed-5a5d-b5bd-d29da8532a79

package/dist/core/history/replay.d.ts

@@ -21,6 +21,12 @@ export declare const EMPTY_REPLAY_DOCUMENT: ReplayDocument;
 export declare function cloneEmptyReplayDocument(): ReplayDocument;
 /** Implements replay hash for the public runtime surface of this module. */
 export declare function replayHash(document: ReplayDocument, version?: HistoryItemHashVersion): string;
+/**
+ * Return hash candidates that preserve the semantic variant within an epoch.
+ * Duplicate values are intentional: before and after candidates use the same
+ * index when a patch introduces a field that distinguishes legacy epoch 2.
+ */
+export declare function replayHashVerificationCandidates(document: ReplayDocument, version: HistoryItemHashVersion): [string, ...string[]];
 /** Implements replay to item document for the public runtime surface of this module. */
 export declare function replayToItemDocument(document: ReplayDocument): ItemDocument;
 /** Converts a materialized replay document into a canonical item document. Use this when callers have already rejected the empty/deleted replay state and need restored metadata validated through the normal item-metadata rules. */
@@ -98,6 +104,11 @@ export interface ReanchorResult {
     /** Whether rewritten entries explicitly carry the hash epoch field. */
     explicitItemHashVersion: boolean;
 }
+/** Controls whether re-anchoring preserves historical writer transitions or emits one exact hash surface. */
+export interface ReanchorHistoryOptions {
+    /** Keep one semantic hash candidate for the complete rewritten stream so adjacent stored endpoints are identical. */
+    continuousHashSurface?: boolean;
+}
 /**
  * Resolve the hash epoch a repair must retain.
  *
@@ -108,6 +119,6 @@ export interface ReanchorResult {
  */
 export declare function resolveHistoryRepairItemHashVersion(entries: HistoryEntry[]): HistoryItemHashVersion;
 /** Re-anchor a drifted history chain: replay every entry from empty, recompute the before/after hashes, and only rewrite a patch when the original op set no longer strictly applies (legacy drift). Clean entries keep their patch verbatim so the on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain. */
-export declare function reanchorHistoryEntries(entries: HistoryEntry[], itemHashVersion?: 1 | 2 | 3): ReanchorResult;
+export declare function reanchorHistoryEntries(entries: HistoryEntry[], itemHashVersion?: 1 | 2 | 3, options?: ReanchorHistoryOptions): ReanchorResult;
 /** Implements history entries to raw for the public runtime surface of this module. */
 export declare function historyEntriesToRaw(entries: HistoryEntry[]): string;

package/dist/core/history/replay.js

@@ -4,13 +4,13 @@
  * Implements append-only history and replay behavior for Replay.
  */
 
-!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]="c823af51-0cfd-536b-8f85-1f3e72db1c86")}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]="c9488ed4-8228-5e7c-9717-69dd7a3275c4")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { canonicalDocument } from "../item/item-format.js";
 import { toItemRecord } from "../item/item-record.js";
 import { orderObject, sha256Hex, stableStringify, } from "../shared/serialization.js";
-import { CURRENT_HISTORY_ITEM_HASH_VERSION, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, hashDocumentForVersion, } from "./history.js";
+import { CURRENT_HISTORY_ITEM_HASH_VERSION, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, hashDocumentVerificationCandidates, } from "./history.js";
 /** Public contract for empty replay document, shared by SDK and presentation-layer consumers. */
 export const EMPTY_REPLAY_DOCUMENT = {
     metadata: {},
@@ -22,23 +22,42 @@ export function cloneEmptyReplayDocument() {
 }
 /** Implements replay hash for the public runtime surface of this module. */
 export function replayHash(document, version = CURRENT_HISTORY_ITEM_HASH_VERSION) {
+    return replayHashVerificationCandidates(document, version)[0];
+}
+/**
+ * Return hash candidates that preserve the semantic variant within an epoch.
+ * Duplicate values are intentional: before and after candidates use the same
+ * index when a patch introduces a field that distinguishes legacy epoch 2.
+ */
+export function replayHashVerificationCandidates(document, version) {
     if (Object.keys(document.metadata).length === 0 ||
         Array.isArray(document.metadata.tags)) {
         try {
-            return hashDocumentForVersion(replayToItemDocument(document), version);
+            return hashDocumentVerificationCandidates(replayToItemDocument(document), version);
         }
         catch {
             // Fall through when another malformed legacy field cannot be canonicalized.
         }
     }
-    // Preserve the structural hashes recorded before missing tags became safe to
-    // normalize. Pre-create/legacy replay states and other malformed metadata cannot
-    // switch hash algorithms without invalidating immutable history chains.
-    return sha256Hex(stableStringify({
+    const fallback = sha256Hex(stableStringify({
         replay_fallback: true,
         metadata: document.metadata,
         body: document.body,
     }));
+    return version === 2 ? [fallback, fallback] : [fallback];
+}
+/** Match one recorded entry against corresponding before/after hash variants. */
+function matchReplayHashCandidates(before, after, version, entry) {
+    const beforeHashes = replayHashVerificationCandidates(before, version);
+    const afterHashes = replayHashVerificationCandidates(after, version);
+    return {
+        beforeHashes,
+        afterHashes,
+        pairIndex: beforeHashes.findIndex((beforeHash, hashIndex) => beforeHash === entry.before_hash &&
+            afterHashes[hashIndex] === entry.after_hash),
+        beforeIndex: beforeHashes.indexOf(entry.before_hash),
+        afterIndex: afterHashes.indexOf(entry.after_hash),
+    };
 }
 /** Implements replay to item document for the public runtime surface of this module. */
 export function replayToItemDocument(document) {
@@ -156,22 +175,9 @@ export function verifyHistoryChainWithVersion(entries) {
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
         const explicitVersion = entry.item_hash_version;
-        if (isUnsupportedExplicitHistoryItemHashVersion(explicitVersion)) {
+        const unsupportedVersion = isUnsupportedExplicitHistoryItemHashVersion(explicitVersion);
+        if (unsupportedVersion) {
             errors.push(`verify_failed:unsupported_item_hash_version:${String(explicitVersion)}:entry_${index + 1}`);
-            const applied = tryApplyReplayPatch(replay, entry.patch);
-            if (!applied.ok) {
-                return {
-                    ok: false,
-                    errors: [
-                        ...errors,
-                        `verify_failed:patch_apply_failed:entry_${index + 1}`,
-                    ],
-                };
-            }
-            replay = applied.document;
-            detectedVersion = undefined;
-            authoritativeExplicitVersion = undefined;
-            continue;
         }
         const applied = tryApplyReplayPatch(replay, entry.patch);
         if (!applied.ok) {
@@ -183,30 +189,32 @@ export function verifyHistoryChainWithVersion(entries) {
                 ],
             };
         }
+        if (unsupportedVersion) {
+            replay = applied.document;
+            detectedVersion = undefined;
+            authoritativeExplicitVersion = undefined;
+            continue;
+        }
         // Prefer legacy epoch 1 when an unversioned entry is valid under both
         // algorithms, but retain compatibility with transitional epoch-2 writers
         // that shipped before item_hash_version became explicit.
         const candidates = historyEntryHashCandidates(explicitVersion, authoritativeExplicitVersion);
-        const beforeMatches = candidates.filter((version) => replayHash(replay, version) === entry.before_hash);
-        if (beforeMatches.length === 0) {
+        const candidateMatches = candidates.map((version) => ({
+            version,
+            match: matchReplayHashCandidates(replay, applied.document, version, entry),
+        }));
+        const matchingVersion = candidateMatches.find(({ match }) => match.pairIndex >= 0);
+        if (matchingVersion === undefined) {
+            const beforeMatches = candidateMatches.some(({ match }) => match.beforeIndex >= 0);
             return {
                 ok: false,
                 errors: [
                     ...errors,
-                    `verify_failed:before_hash_mismatch:entry_${index + 1}`,
-                ],
-            };
-        }
-        const version = beforeMatches.find((candidate) => replayHash(applied.document, candidate) === entry.after_hash);
-        if (version === undefined) {
-            return {
-                ok: false,
-                errors: [
-                    ...errors,
-                    `verify_failed:after_hash_mismatch:entry_${index + 1}`,
+                    `verify_failed:${beforeMatches ? "after" : "before"}_hash_mismatch:entry_${index + 1}`,
                 ],
             };
         }
+        const version = matchingVersion.version;
         replay = applied.document;
         detectedVersion = version;
         authoritativeExplicitVersion =
@@ -297,7 +305,7 @@ export function resolveHistoryRepairItemHashVersion(entries) {
     return CURRENT_HISTORY_ITEM_HASH_VERSION;
 }
 /** Re-anchor a drifted history chain: replay every entry from empty, recompute the before/after hashes, and only rewrite a patch when the original op set no longer strictly applies (legacy drift). Clean entries keep their patch verbatim so the on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain. */
-export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistoryRepairItemHashVersion(entries)) {
+export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistoryRepairItemHashVersion(entries), options = {}) {
     const unsupportedIndex = entries.findIndex((entry) => isUnsupportedExplicitHistoryItemHashVersion(entry.item_hash_version));
     if (unsupportedIndex >= 0) {
         throw new TypeError(`unsupported_item_hash_version:${String(entries[unsupportedIndex]?.item_hash_version)}:entry_${unsupportedIndex + 1}`);
@@ -309,11 +317,11 @@ export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistory
     let entriesPatchRepaired = 0;
     let convertedReplaceToAdd = 0;
     let skippedOps = 0;
+    let semanticIndex;
     const explicitItemHashVersion = itemHashVersion !== 1 ||
         entries.some((entry) => entry.item_hash_version !== undefined);
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
-        const beforeHash = replayHash(replay, itemHashVersion);
         const strict = tryApplyReplayPatch(replay, entry.patch);
         let next;
         let outPatch;
@@ -335,7 +343,20 @@ export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistory
             skippedOps += entrySkipped;
             entriesPatchRepaired += 1;
         }
-        const afterHash = replayHash(next, itemHashVersion);
+        const hashMatch = matchReplayHashCandidates(replay, next, itemHashVersion, entry);
+        if (semanticIndex === undefined || options.continuousHashSurface !== true) {
+            semanticIndex = [
+                hashMatch.pairIndex,
+                hashMatch.beforeIndex,
+                hashMatch.afterIndex,
+                Math.min(semanticIndex ?? 0, hashMatch.beforeHashes.length - 1),
+            ].find((candidate) => candidate >= 0);
+        }
+        else {
+            semanticIndex = Math.min(semanticIndex, hashMatch.beforeHashes.length - 1);
+        }
+        const beforeHash = hashMatch.beforeHashes[semanticIndex];
+        const afterHash = hashMatch.afterHashes[semanticIndex];
         const rehashed = beforeHash !== entry.before_hash || afterHash !== entry.after_hash;
         if (rehashed) {
             entriesRehashed += 1;
@@ -382,4 +403,4 @@ export function historyEntriesToRaw(entries) {
     return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
 }
 //# sourceMappingURL=replay.js.map
-//# debugId=c823af51-0cfd-536b-8f85-1f3e72db1c86
+//# debugId=c9488ed4-8228-5e7c-9717-69dd7a3275c4

package/dist/mcp/server.d.ts

@@ -21,8 +21,8 @@ declare function nearestDeclaredKey(unexpected: string, declared: string[]): str
 declare function detectUnexpectedTopLevelKeys(toolName: string, args: Record<string, unknown>, toolDeclaredKeys?: Map<string, string[]>): string[];
 declare function collectMutationGuardWarnings(toolName: string, action: string | undefined, args: Record<string, unknown>): Promise<string[]>;
 declare function detectUnexpectedOptionKeys(toolName: string, action: string | undefined, args: Record<string, unknown>): string[];
-declare function resultContent(result: unknown, warnings?: string[], tokenAccounting?: boolean): Record<string, unknown>;
-declare function errorContent(error: unknown): Record<string, unknown>;
+declare function resultContent(result: unknown, warnings?: string[], tokenAccounting?: boolean, canonicalStructuredResult?: boolean): Record<string, unknown>;
+declare function errorContent(error: unknown, canonicalStructuredResult?: boolean): Record<string, unknown>;
 /** Retain at most 32 own, valid provenance values without cloning unbounded input. */
 declare function boundMcpClientProvenance(value: unknown): Record<string, string>;
 declare function emitMcpChangeNotifications(action: string | undefined): Promise<void>;

package/dist/mcp/server.js

@@ -5,7 +5,7 @@
  * Runs the MCP server adapter that exposes pm actions and contracts to external agents.
  */
 
-!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]="77067047-62fc-54e8-9047-ad30580d6125")}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]="71cfdc6b-c990-51b6-a9ae-ed9bf98136f7")}catch(e){}}();
 import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -17,6 +17,7 @@ import { readRequiredString, runAction, runWithActiveExtensions, } from "../sdk/
 import { NARROW_TOOL_ACTIONS, TOOLS } from "./tool-definitions.js";
 import { normalizeWorkspaceToolArguments, resolveMcpToolAccess, resolveMcpToolSurface, } from "./runtime-capabilities.js";
 import { PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, } from "../sdk/agent-capability-contracts.js";
+import { PM_MCP_ENTRY_TOOL_NAMES, PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION, PM_MCP_PROGRESSIVE_DISCOVERY_SERVER_CAPABILITY, discoverPmTools, parsePmToolDiscoveryOptions, } from "../sdk/mcp/discovery.js";
 import { commitItemMutations } from "../sdk/item-transaction.js";
 import { isRuntimeRecord, markMcpMutationTransportInput, } from "../sdk/runtime-input.js";
 import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
@@ -59,6 +60,7 @@ const PM_MCP_SERVER_CAPABILITIES = {
         [PM_MCP_TASKS_EXTENSION]: {},
         [PM_MCP_APPS_EXTENSION]: PM_MCP_APPS_SERVER_CAPABILITY,
         [PM_MCP_SKILLS_EXTENSION]: PM_MCP_SKILLS_SERVER_CAPABILITY,
+        [PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION]: PM_MCP_PROGRESSIVE_DISCOVERY_SERVER_CAPABILITY,
     },
 };
 const PM_MCP_SUBSCRIPTIONS = new Map();
@@ -99,6 +101,7 @@ const PM_MCP_SKILL_METHODS = new Set([
     "resources/directory/read",
 ]);
 const PM_MCP_INSTRUCTIONS = "You have access to native pm CLI tools for git-based project management. " +
+    "When progressive discovery is negotiated, use pm_discover to expand the small entry catalog by intent and request schemas only when needed. " +
     "Use pm_next to pick the next actionable item, or pm_context or pm_search before creating new work. " +
     "Prefer narrow tools (pm_next, pm_context, pm_list, pm_get, pm_search, pm_events, pm_create, pm_mutate, pm_copy, pm_focus, pm_update, pm_append, pm_claim, pm_release, pm_close, pm_comments, pm_files, pm_docs, pm_notes, pm_learnings, pm_deps, pm_graph, pm_test, pm_validate, pm_health, pm_contracts, pm_schema, pm_profile, pm_config, pm_plan) over pm_run when they cover the operation. " +
     "Use pm_plan for agent harness Plan workflows: it provides Codex/Claude/Cursor-style planning with durable steps, dependencies, decisions, discoveries, validation, and materialization. " +
@@ -145,6 +148,17 @@ function nearestDeclaredKey(unexpected, declared) {
 // keys there are by-design rather than typos and must not be flagged.
 const UNEXPECTED_KEY_WARNING_EXEMPT_TOOLS = new Set(["pm_run"]);
 const MCP_RETRY_ARGUMENT_KEYS = new Set(["inputResponses", "requestState"]);
+/** Resolve the optional shared cursor key without exposing it to tool input. */
+function resolveMcpDiscoveryCursorIntegrityKey() {
+    const configuredKey = process.env.PM_MCP_DISCOVERY_CURSOR_KEY;
+    if (configuredKey === undefined)
+        return undefined;
+    const key = Buffer.from(configuredKey, "utf8");
+    if (key.byteLength < 32) {
+        throw new PmCliError("PM_MCP_DISCOVERY_CURSOR_KEY must contain at least 32 UTF-8 bytes.", 64);
+    }
+    return key;
+}
 function detectUnexpectedTopLevelKeys(toolName, args, toolDeclaredKeys = declaredToolKeys()) {
     if (typeof args !== "object" || args === null || Array.isArray(args)) {
         return [];
@@ -171,6 +185,29 @@ function detectUnexpectedTopLevelKeys(toolName, args, toolDeclaredKeys = declare
 }
 const HANDLERS = {
     pm_run: (args) => runMcpAction(args),
+    pm_discover: async (args) => {
+        const surface = await resolveMcpToolSurface(TOOLS, args);
+        const cursorIntegrityKey = resolveMcpDiscoveryCursorIntegrityKey();
+        const discoveryOptions = parsePmToolDiscoveryOptions(args);
+        return discoverPmTools(surface.tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            authorized: true,
+            signals: {
+                freshness: 1,
+                usage: PM_MCP_ENTRY_TOOL_NAMES.includes(tool.name) ? 1 : 0,
+            },
+        })), {
+            ...discoveryOptions,
+            profile: surface.profile,
+            ...(cursorIntegrityKey === undefined
+                ? {}
+                : {
+                    cursorIntegrityKey,
+                }),
+        });
+    },
     pm_mutate: async (args) => {
         const transactionId = readRequiredString(args, "transactionId");
         const controls = parseAtomicMutationControls(args);
@@ -279,7 +316,7 @@ function detectUnexpectedOptionKeys(toolName, action, args) {
     }
     return warnings;
 }
-function resultContent(result, warnings, tokenAccounting = false) {
+function resultContent(result, warnings, tokenAccounting = false, canonicalStructuredResult = false) {
     const effectiveResult = tokenAccounting
         ? attachOutputTokenAccounting(result, (value) => JSON.stringify(value, null, 2))
         : result;
@@ -292,13 +329,15 @@ function resultContent(result, warnings, tokenAccounting = false) {
         content: [
             {
                 type: "text",
-                text: JSON.stringify(effectiveResult, null, 2),
+                text: canonicalStructuredResult
+                    ? "Canonical result: structuredContent.result"
+                    : JSON.stringify(effectiveResult, null, 2),
             },
         ],
         structuredContent,
     };
 }
-function errorContent(error) {
+function errorContent(error, canonicalStructuredResult = false) {
     const code = error instanceof PmCliError ? error.exitCode : 1;
     const message = error instanceof Error ? error.message : String(error);
     const details = error instanceof PmCliError ? error.context : undefined;
@@ -307,7 +346,9 @@ function errorContent(error) {
         content: [
             {
                 type: "text",
-                text: JSON.stringify({ error: message, code, details }, null, 2),
+                text: canonicalStructuredResult
+                    ? "Canonical error: structuredContent"
+                    : JSON.stringify({ error: message, code, details }, null, 2),
             },
         ],
         // Keep `result` present on the error envelope so consumers can read
@@ -369,7 +410,7 @@ async function emitMcpChangeNotifications(action) {
     }
     pruneClosedMcpSubscriptionRegistries();
 }
-async function handleToolCall(paramsInput, clientInfo) {
+async function handleToolCall(paramsInput, clientInfo, progressiveDiscoveryNegotiated = false) {
     return runWithHarnessDetectionSignals({
         env: process.env,
         argv: process.argv,
@@ -386,6 +427,7 @@ async function handleToolCall(paramsInput, clientInfo) {
         const inputResponses = params.inputResponses === undefined
             ? undefined
             : parseMcpInputResponses(params.inputResponses);
+        validateMcpToolArguments(params.arguments);
         const requestedArgs = {
             ...decodeHtmlEntitiesInOptions(asRecordClone(params.arguments)),
             ...(inputResponses ? { inputResponses } : {}),
@@ -394,7 +436,10 @@ async function handleToolCall(paramsInput, clientInfo) {
                 : {}),
         };
         const access = await resolveMcpToolAccess(TOOLS, name, requestedArgs);
-        if (!access.available) {
+        const requiredCustomDiscoveryEntry = progressiveDiscoveryNegotiated &&
+            access.profile === "custom" &&
+            name === "pm_discover";
+        if (!access.available && !requiredCustomDiscoveryEntry) {
             throw new PmCliError(`pm MCP tool "${name}" is unavailable in the ${access.profile} profile.`, 64);
         }
         // pm-ydkl: defensive HTML-entity decode for free-text fields. Claude / the
@@ -426,7 +471,7 @@ async function handleToolCall(paramsInput, clientInfo) {
             // so the chdir/restore is exclusive per request and cannot race a concurrent caller.
             const result = await handler(args);
             void emitMcpChangeNotifications(action);
-            return resultContent(result, warnings, args.tokenAccounting === true);
+            return resultContent(result, warnings, args.tokenAccounting === true, progressiveDiscoveryNegotiated);
         }, { probesEnabled: workspaceIdentity?.probes_enabled });
     });
 }
@@ -484,7 +529,8 @@ export function buildMcpToolCallErrorResult(request, error) {
     if (request.method !== "tools/call" || error instanceof PmMcpProtocolError) {
         return undefined;
     }
-    const content = errorContent(error);
+    const content = errorContent(error, hasMcpProtocolVersionMetadata(request) &&
+        hasMcpClientExtension(resolveMcpRequestContext(request.params), PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION));
     return hasMcpProtocolVersionMetadata(request)
         ? buildMcpCompleteResult(content, PM_MCP_SERVER_INFO)
         : content;
@@ -607,6 +653,12 @@ function mcpTaskStore() {
         owner: "pm-mcp-task-provider",
     });
 }
+/** Rejects malformed MCP tool argument containers before dispatch. */
+function validateMcpToolArguments(value) {
+    if (value !== undefined && !isMcpRecord(value)) {
+        throw new PmCliError("pm MCP tool arguments must be an object.", 64);
+    }
+}
 function shouldCreateMcpTask(params, requestContext) {
     if (!hasMcpClientExtension(requestContext, PM_MCP_TASKS_EXTENSION)) {
         return false;
@@ -633,7 +685,7 @@ async function executeMcpTask(execution, inputResponses) {
         ...(execution.requestState ? { requestState: execution.requestState } : {}),
     };
     try {
-        const result = await handleToolCall(params, execution.context.clientInfo);
+        const result = await handleToolCall(params, execution.context.clientInfo, hasMcpClientExtension(execution.context, PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION));
         await execution.store.complete(execution.taskId, execution.principal, buildMcpCompleteResult(result, PM_MCP_SERVER_INFO));
         PENDING_MCP_TASKS.delete(execution.taskId);
     }
@@ -657,7 +709,7 @@ async function executeMcpTask(execution, inputResponses) {
             });
         }
         else {
-            await execution.store.complete(execution.taskId, execution.principal, buildMcpCompleteResult(errorContent(error), PM_MCP_SERVER_INFO));
+            await execution.store.complete(execution.taskId, execution.principal, buildMcpCompleteResult(errorContent(error, hasMcpClientExtension(execution.context, PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION)), PM_MCP_SERVER_INFO));
         }
         PENDING_MCP_TASKS.delete(execution.taskId);
     }
@@ -726,17 +778,28 @@ async function dispatchMcpTaskMethod(request, requestContext) {
 async function dispatchModernToolMethod(request, requestContext, clientInfo) {
     if (request.method === "tools/list") {
         const surface = await resolveMcpToolSurface(TOOLS, requestWorkspaceArgs(request.params));
+        const progressiveDiscovery = hasMcpClientExtension(requestContext, PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION);
+        const listedTools = progressiveDiscovery
+            ? [
+                ...surface.tools.filter((tool) => PM_MCP_ENTRY_TOOL_NAMES.includes(tool.name)),
+                ...(surface.profile === "custom" &&
+                    !surface.tools.some((tool) => tool.name === "pm_discover")
+                    ? TOOLS.filter((tool) => tool.name === "pm_discover")
+                    : []),
+            ]
+            : surface.tools;
         return buildMcpCompleteResult(withMcpCachePolicy({
             tools: hasCompatiblePmMcpAppsCapability(requestContext)
-                ? decoratePmMcpToolsWithApps(deterministicMcpTools(surface.tools))
-                : deterministicMcpTools(surface.tools),
+                ? decoratePmMcpToolsWithApps(deterministicMcpTools(listedTools))
+                : deterministicMcpTools(listedTools),
         }, PM_MCP_CACHE_POLICIES.tools), PM_MCP_SERVER_INFO);
     }
+    validateMcpToolArguments(request.params?.arguments);
     if (shouldCreateMcpTask(request.params, requestContext)) {
         return createMcpTaskForToolCall(request.params, requestContext);
     }
     try {
-        return buildMcpCompleteResult(await handleToolCall(request.params, clientInfo), PM_MCP_SERVER_INFO);
+        return buildMcpCompleteResult(await handleToolCall(request.params, clientInfo, hasMcpClientExtension(requestContext, PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION)), PM_MCP_SERVER_INFO);
     }
     catch (error) {
         if (!(error instanceof PmMcpInputRequiredError))
@@ -1162,4 +1225,4 @@ if (isInvokedAsMcpMainModule(process.argv[1], import.meta.url)) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=server.js.map
-//# debugId=77067047-62fc-54e8-9047-ad30580d6125
+//# debugId=71cfdc6b-c990-51b6-a9ae-ed9bf98136f7