@unbrained/pm-cli 2026.8.30 → 2026.9.1

package/dist/mcp/legacy-adapter.js

@@ -1,13 +1,34 @@
 /**
  * @module mcp/legacy-adapter
  *
- * Isolates the bounded MCP 2025-06-18 stdio compatibility surface from the
+ * Isolates the bounded initialize-era stdio compatibility surface from the
  * canonical stateless dispatcher. No modern transport imports policy from it.
  */
 
-!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]="6a1d9bca-7dac-5537-9930-a12d8049c8b8")}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]="75228af6-d015-596d-ac32-4f5e78cb3916")}catch(e){}}();
 import { PmCliError } from "../sdk/runtime-primitives.js";
 import { PM_MCP_ERROR_CODES, PM_MCP_LEGACY_PROTOCOL_VERSIONS, PM_MCP_PROTOCOL_VERSION, PmMcpProtocolError, } from "../sdk/mcp/protocol.js";
+/**
+ * Resolve the legacy revision a handshake negotiates, or refuse with the full
+ * supported set.
+ *
+ * A legacy client has no fall-forward mechanism, so the refusal names every
+ * accepted legacy revision alongside the canonical modern one: the error text
+ * is the only diagnostic such a client can surface.
+ */
+export function resolveLegacyProtocolVersion(requestedVersion) {
+    if (requestedVersion === undefined || requestedVersion === null) {
+        return PM_MCP_LEGACY_PROTOCOL_VERSIONS[0];
+    }
+    const accepted = PM_MCP_LEGACY_PROTOCOL_VERSIONS.find((candidate) => candidate === requestedVersion);
+    if (accepted)
+        return accepted;
+    throw new PmMcpProtocolError("Unsupported legacy MCP protocol version", PM_MCP_ERROR_CODES.unsupportedProtocolVersion, {
+        supported: [...PM_MCP_LEGACY_PROTOCOL_VERSIONS],
+        requested: requestedVersion,
+        modern: PM_MCP_PROTOCOL_VERSION,
+    });
+}
 /** Explicit compatibility adapter with no cross-process or modern-session role. */
 export class LegacyMcpAdapter {
     #options;
@@ -23,17 +44,10 @@ export class LegacyMcpAdapter {
     /** Validate and answer the historical initialize handshake. */
     initialize(params) {
         const requestedVersion = params?.protocolVersion;
-        if (typeof requestedVersion === "string" &&
-            !PM_MCP_LEGACY_PROTOCOL_VERSIONS.includes(requestedVersion)) {
-            throw new PmMcpProtocolError("Unsupported legacy MCP protocol version", PM_MCP_ERROR_CODES.unsupportedProtocolVersion, {
-                supported: [...PM_MCP_LEGACY_PROTOCOL_VERSIONS],
-                requested: requestedVersion,
-                modern: PM_MCP_PROTOCOL_VERSION,
-            });
-        }
+        const negotiatedVersion = resolveLegacyProtocolVersion(requestedVersion);
         this.#clientInfo = this.#options.parseClientInfo(params?.clientInfo);
         return {
-            protocolVersion: PM_MCP_LEGACY_PROTOCOL_VERSIONS[0],
+            protocolVersion: negotiatedVersion,
             capabilities: structuredClone(this.#options.capabilities),
             serverInfo: { ...this.#options.serverInfo },
             instructions: this.#options.instructions,
@@ -61,4 +75,4 @@ export class LegacyMcpAdapter {
     }
 }
 //# sourceMappingURL=legacy-adapter.js.map
-//# debugId=6a1d9bca-7dac-5537-9930-a12d8049c8b8
+//# debugId=75228af6-d015-596d-ac32-4f5e78cb3916

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

package/dist/mcp/tool-definitions.js

@@ -4,7 +4,7 @@
  * Defines the Tool Definitions module for pm CLI source.
  */
 
-!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]="41396cb5-7faf-5642-8746-8d94edb01d86")}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]="5ceccf7d-78cb-5750-8e4b-793efa6e716c")}catch(e){}}();
 import { GRAPH_SUBCOMMAND_VALUES, PM_DISCOVERABLE_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.js";
 import { buildPmActionToolInputSchema } from "../sdk/cli-contracts/tool-schema.js";
 import { RUNTIME_STATUS_ROLE_VALUES } from "../types.js";
@@ -149,6 +149,60 @@ const RAW_TOOLS = [
             ...READ_OUTPUT_TOOL_PROPERTIES,
         }, ["action"]),
     },
+    {
+        name: "pm_discover",
+        description: "Discover the smallest relevant authorized pm tool catalog under an explicit token budget. " +
+            "Ranking is deterministic and returns public lexical, semantic, graph, permission, freshness, and usage signal explanations. " +
+            "Continue with next_cursor; set includeSchema=true only when complete input schemas are needed.",
+        inputSchema: objectSchema({
+            query: {
+                type: "string",
+                maxLength: 4096,
+                description: "Free-text capability intent. Empty text lists by stable policy order.",
+            },
+            family: {
+                type: "string",
+                enum: [
+                    "workspace",
+                    "intake",
+                    "context",
+                    "lifecycle",
+                    "evidence",
+                    "graph",
+                    "quality",
+                    "automation",
+                    "extensions",
+                    "internal",
+                ],
+                description: "Optional stable capability-family filter.",
+            },
+            tier: {
+                type: "string",
+                enum: ["core", "standard", "full"],
+                description: "Maximum command visibility tier included in results.",
+            },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                maximum: 100,
+                description: "Maximum result rows; defaults to 10.",
+            },
+            cursor: {
+                type: "string",
+                minLength: 1,
+                maxLength: 4096,
+                description: "Opaque next_cursor from an equivalent discovery request.",
+            },
+            includeSchema: {
+                type: "boolean",
+                description: "Include complete tool input schemas; false by default.",
+            },
+            outputBudget: {
+                anyOf: [{ type: "integer", minimum: 128 }, { const: "unbounded" }],
+                description: "Estimated-token ceiling; defaults to 1200.",
+            },
+        }),
+    },
     {
         name: "pm_context",
         description: "Return the agent-oriented project context snapshot. " +
@@ -748,4 +802,4 @@ export function buildMcpToolContracts() {
     }).sort((left, right) => left.name.localeCompare(right.name));
 }
 //# sourceMappingURL=tool-definitions.js.map
-//# debugId=41396cb5-7faf-5642-8746-8d94edb01d86
+//# debugId=5ceccf7d-78cb-5750-8e4b-793efa6e716c

package/dist/sdk/agent-capability-contracts.js

@@ -5,7 +5,7 @@
  * surfaces from one public SDK contract.
  */
 
-!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]="d8f3f734-9adf-56f3-a5ba-c8b6407c4a89")}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]="f3f07ca8-7823-536d-b523-6d8f87c35f4a")}catch(e){}}();
 import { PM_CORE_COMMAND_NAMES } from "./cli-contracts/enum-contracts.js";
 const CORE_COMMANDS = new Set([
     "claim",
@@ -176,6 +176,7 @@ export const PM_CORE_HELP_BUDGET = Object.freeze({
 /** Root options retained in the compact progressive-disclosure help screen. */
 export const PM_CORE_HELP_OPTION_FLAGS = Object.freeze([
     "-V, --version",
+    "--all",
     "--json",
     "--output-include <fields>",
     "--output-limit <count>",
@@ -277,6 +278,7 @@ export const PM_MCP_TOOL_COMMAND_CONTRACTS = Object.freeze({
     pm_copy: "copy",
     pm_create: "create",
     pm_deps: "deps",
+    pm_discover: "help",
     pm_docs: "docs",
     pm_events: "history",
     pm_files: "files",
@@ -424,4 +426,4 @@ export function renderPmCapabilityRoutingMarkdown(contracts = PM_COMMAND_CAPABIL
     ].join("\n");
 }
 //# sourceMappingURL=agent-capability-contracts.js.map
-//# debugId=d8f3f734-9adf-56f3-a5ba-c8b6407c4a89
+//# debugId=f3f07ca8-7823-536d-b523-6d8f87c35f4a

package/dist/sdk/cli-contracts/flag-contracts.d.ts

@@ -207,6 +207,8 @@ export declare const GRAPH_FLAG_CONTRACTS: CliFlagContract[];
 export declare const EVAL_FLAG_CONTRACTS: CliFlagContract[];
 /** Public contract for guarded portable workspace snapshot command paths. */
 export declare const WORKSPACE_FLAG_CONTRACTS: CliFlagContract[];
+/** Flagless bounded workspace position read. */
+export declare const WORKSPACE_POSITION_FLAG_CONTRACTS: CliFlagContract[];
 /** Public contract for next flag contracts, shared by SDK and presentation-layer consumers. */
 export declare const NEXT_FLAG_CONTRACTS: CliFlagContract[];
 /** Public contract for search flag contracts, shared by SDK and presentation-layer consumers. */

package/dist/sdk/cli-contracts/flag-contracts.js

@@ -7,7 +7,7 @@
  * flag surface stays single-sourced across the CLI, SDK, and MCP boundaries.
  */
 
-!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]="bd6c497f-9fb0-5c47-a677-9dd6636dba02")}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]="789faf62-dfbf-56ff-9412-55adc5c12d3d")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 import { PM_POSITIONAL_ACTION_CONTRACTS, } from "./grammar-contracts.js";
@@ -1555,6 +1555,8 @@ export const WORKSPACE_FLAG_CONTRACTS = [
     { flag: "--author" },
     { flag: "--message" },
 ];
+/** Flagless bounded workspace position read. */
+export const WORKSPACE_POSITION_FLAG_CONTRACTS = [];
 /** Public contract for next flag contracts, shared by SDK and presentation-layer consumers. */
 export const NEXT_FLAG_CONTRACTS = [
     { flag: "--for", value_name: "intent" },
@@ -1709,6 +1711,7 @@ const ASSURANCE_FLAG_CONTRACT_INDEX = indexCliFlagContracts(ASSURANCE_FLAG_CONTR
 const POSITIONAL_ACTION_FLAG_INDEX_BY_PARENT = new Map([
     ["assurance", ASSURANCE_FLAG_CONTRACT_INDEX],
     ["plan", PLAN_FLAG_CONTRACT_INDEX],
+    ["workspace", indexCliFlagContracts(WORKSPACE_POSITION_FLAG_CONTRACTS)],
     ["workspace snapshot", indexCliFlagContracts(WORKSPACE_FLAG_CONTRACTS)],
 ]);
 /** Resolve every positional action's accepted flags against one parent contract. */
@@ -1770,6 +1773,7 @@ const SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map([
     ["next", NEXT_FLAG_CONTRACTS],
     ["eval", EVAL_FLAG_CONTRACTS],
     ["workspace", WORKSPACE_FLAG_CONTRACTS],
+    ["workspace position", WORKSPACE_POSITION_FLAG_CONTRACTS],
     ["workspace snapshot", WORKSPACE_FLAG_CONTRACTS],
     ["workspace snapshot create", WORKSPACE_FLAG_CONTRACTS],
     ["workspace snapshot list", WORKSPACE_FLAG_CONTRACTS],
@@ -1915,4 +1919,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=bd6c497f-9fb0-5c47-a677-9dd6636dba02
+//# debugId=789faf62-dfbf-56ff-9412-55adc5c12d3d

package/dist/sdk/cli-contracts/grammar-contracts.d.ts

@@ -53,7 +53,7 @@ export interface PmCommandPositionalContract {
 /** Discoverable positional action projected through help, contracts, and completion. */
 export interface PmPositionalActionContract extends PmCommandPositionalContract {
     /** Commander command that dispatches the action positionally. */
-    parent: "assurance" | "plan" | "workspace snapshot";
+    parent: "assurance" | "plan" | "workspace" | "workspace snapshot";
     /** Literal action token accepted in the parent's first positional slot. */
     action: string;
     /** Canonical flags applicable to this action-specific view. */

package/dist/sdk/cli-contracts/grammar-contracts.js

@@ -7,7 +7,7 @@
  * cannot silently bypass the architecture decision.
  */
 
-!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]="d0f4c030-0028-5acb-a438-210666118074")}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]="4efc5934-7d1b-517b-8b5e-eb2fe14379f2")}catch(e){}}();
 import { resolvePmCommandAlias, } from "./command-aliases.js";
 /** Canonical top-level domains an agent must retain to route pm operations. */
 export const PM_CLI_GRAMMAR_NOUNS = [
@@ -314,6 +314,15 @@ export const PM_POSITIONAL_ACTION_CONTRACTS = [
         description: "Analyze bounded defect-recurrence risk for a proposed change.",
         example: 'pm assurance risk --definition \'{"change":{"files":[]}}\'',
     },
+    {
+        command: "workspace position",
+        parent: "workspace",
+        action: "position",
+        slots: [],
+        accepted_flags: [],
+        description: "Read bounded merge-fence, receipt, history-drift, and next-action readiness.",
+        example: "pm workspace position",
+    },
     {
         command: "workspace snapshot create",
         parent: "workspace snapshot",
@@ -638,6 +647,7 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
     ]),
     ...destinationRows("workspace", "workspace", "target_noun", "pm-pbyu", [
         "workspace",
+        "workspace position",
         "workspace snapshot",
         "workspace snapshot create",
         "workspace snapshot delete",
@@ -965,4 +975,4 @@ export function verifyPmCliGrammar(commands, aliases = [], destinations = PM_COM
     };
 }
 //# sourceMappingURL=grammar-contracts.js.map
-//# debugId=d0f4c030-0028-5acb-a438-210666118074
+//# debugId=4efc5934-7d1b-517b-8b5e-eb2fe14379f2

package/dist/sdk/cli-contracts/runtime-contracts.js

@@ -4,7 +4,7 @@
  * Implements the pm contracts command surface and its agent-facing runtime behavior.
  */
 
-!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]="a4c43fa6-9f2e-515c-ab47-d21ef5d7878e")}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]="1506e8bc-3350-5ef5-a40a-44509eb59317")}catch(e){}}();
 import { EXIT_CODE, SETTINGS_DEFAULTS, PmCliError, activateExtensions, getActiveExtensionRegistrations, loadExtensions, pathExists, commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 import { buildMcpToolContracts, } from "../../mcp/tool-definitions.js";
 import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_REOPEN_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_OUTPUT_DEGRADATION_STEPS, PLAN_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_DEPRECATED_TOOL_ACTIONS, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, compactFlagAliasContracts, PM_COMMAND_ALIAS_CONTRACTS, PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS, resolvePmCommandOutputBudget, } from "../cli-contracts.js";
@@ -367,6 +367,7 @@ const CORE_COMMAND_FLAG_CONTRACT_ENTRIES = [
     ["search", SEARCH_FLAG_CONTRACTS],
     ["eval", EVAL_FLAG_CONTRACTS],
     ["workspace", WORKSPACE_FLAG_CONTRACTS],
+    ["workspace position", []],
     ["workspace snapshot", WORKSPACE_FLAG_CONTRACTS],
     ["workspace snapshot create", WORKSPACE_FLAG_CONTRACTS],
     ["workspace snapshot list", WORKSPACE_FLAG_CONTRACTS],
@@ -2084,4 +2085,4 @@ export const _testOnlyContractsCommand = {
     toRuntimeShortFlagToken,
 };
 //# sourceMappingURL=runtime-contracts.js.map
-//# debugId=a4c43fa6-9f2e-515c-ab47-d21ef5d7878e
+//# debugId=1506e8bc-3350-5ef5-a40a-44509eb59317

package/dist/sdk/cli-contracts/tool-schema.js

@@ -7,7 +7,7 @@
  * consumers from a single source of truth.
  */
 
-!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]="91de08b8-ad0b-5c61-a272-3c18cd3f083b")}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]="b81a68c1-565d-56f6-a0eb-35d2c737bdb7")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { TOOL_CREATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, } from "./tool-option-contracts.js";
@@ -567,8 +567,9 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
         ],
     },
     workspace: {
-        required: ["subcommand", "snapshotAction"],
+        required: ["subcommand"],
         optional: [
+            "snapshotAction",
             "name",
             "target",
             "dryRun",
@@ -578,6 +579,13 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "lockTtlSeconds",
             "lockWaitMs",
         ],
+        conditionalRequired: [
+            {
+                property: "subcommand",
+                value: "snapshot",
+                required: ["snapshotAction"],
+            },
+        ],
     },
     meet: SCHEDULING_ACTION_SCHEMA_CONTRACT,
     event: SCHEDULING_ACTION_SCHEMA_CONTRACT,
@@ -1629,4 +1637,4 @@ export const _testOnlyCliContracts = {
     withFlagAliasMetadata,
 };
 //# sourceMappingURL=tool-schema.js.map
-//# debugId=91de08b8-ad0b-5c61-a272-3c18cd3f083b
+//# debugId=b81a68c1-565d-56f6-a0eb-35d2c737bdb7

package/dist/sdk/generated/generated-error-code-catalog-part-2.js

@@ -1,6 +1,6 @@
 /** Generated partition 2 of the exhaustive error-code catalog. */
 
-!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]="015f826a-6490-56d1-8e26-131e5503d8f1")}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]="41e6f81d-ccb5-546c-9b26-3b78027528b5")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_2 = [
     {
         code: "missing_destination",
@@ -919,6 +919,18 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
         canonical_code: "status_invalid",
         aliases: [],
     },
+    {
+        code: "status_lifecycle_role_required",
+        meaning: "Status lifecycle role required condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/schema.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "status_lifecycle_role_required",
+        aliases: [],
+    },
     {
         code: "stdin_json_invalid",
         meaning: "Stdin json invalid condition.",
@@ -2162,4 +2174,4 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
     },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-2.js.map
-//# debugId=015f826a-6490-56d1-8e26-131e5503d8f1
+//# debugId=41e6f81d-ccb5-546c-9b26-3b78027528b5