@unbrained/pm-cli 2026.6.24 → 2026.7.1

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]="ad8d2ba8-8a0e-5d5e-b4d2-00e538908f91")}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]="28140feb-d035-55d6-bd6a-d90ed2c41f26")}catch(e){}}();
 import { realpathSync } from "node:fs";
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
@@ -26,7 +26,7 @@ import { normalizeListOptions, normalizeUpdateOptions } from "../cli/registratio
 import { UPDATE_COMMANDER_STRING_OPTION_CONTRACTS } from "../sdk/cli-contracts/commander-mutation-options.js";
 import { clearWorkspaceContractsCache } from "../sdk/runtime.js";
 import { TOOLS } from "./tool-definitions.js";
-import { runActivity, runAggregate, runAppend, runClaim, runClose, runCloseMany, runComments, runContracts, runContext, runCreate, runCopy, runFocus, runConfig, runDelete, runDeps, runDocs, runExtension, runFiles, runFilesDiscover, runGc, runGet, runHealth, runHistory, runHistoryCompact, runHistoryRedact, runHistoryRepair, runHistoryRepairAll, assertHistoryRepairTarget, runInit, runLearnings, runList, runNotes, runPlan, runRelease, runSchemaAddStatus, runSchemaAddType, runSchemaAddField, runSchemaApplyPreset, runSchemaInferTypes, runSchemaList, runSchemaListFields, runSchemaRemoveStatus, runSchemaRemoveType, runSchemaRemoveField, runSchemaShow, runSchemaShowField, runSchemaShowStatus, runSearch, runStats, runTelemetry, runTest, runTestAll, runUpdate, runUpdateMany, runUpgrade, runValidate, } from "../cli/commands/index.js";
+import { runActivity, runAggregate, runAppend, runClaim, runClose, runCloseMany, runComments, runContracts, runContext, runCreate, runCopy, runFocus, runConfig, runDelete, runDeps, runDocs, runExtension, runFiles, runFilesDiscover, runGc, runGet, runHealth, runHistory, runHistoryCompact, runHistoryRedact, runHistoryRepair, runHistoryRepairAll, assertHistoryRepairTarget, runInit, runLearnings, runList, runNext, runNotes, runPlan, runRelease, runSchemaAddStatus, runSchemaAddType, runSchemaAddField, runSchemaApplyPreset, runSchemaInferTypes, runSchemaList, runSchemaListFields, runSchemaRemoveStatus, runSchemaRemoveType, runSchemaRemoveField, runSchemaShow, runSchemaShowField, runSchemaShowStatus, runProfileApply, runProfileLint, runProfileList, runProfileShow, runSearch, runStats, runTelemetry, runTest, runTestAll, runUpdate, runUpdateMany, runUpgrade, runValidate, } from "../cli/commands/index.js";
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 function resolvePmPackageRoot() {
     return fileURLToPath(new URL("../..", import.meta.url));
@@ -287,63 +287,95 @@ function extensionOptionsFromArgs(args, options) {
     delete normalizedOptions.args;
     return normalizedOptions;
 }
-// pm-bl6m: runDynamicExtensionAction mutates the process-global active extension
-// registries (set globals -> run handler -> clear globals in a finally). The stdio
-// transport already processes JSON-RPC lines sequentially, but handleRequest is a
-// public entry point (tests, future concurrent transports) — if two native-action
-// requests ever ran concurrently, the newer request would overwrite the globals
-// mid-flight and whichever finished first would clear them out from under the
-// other (its lazily-read hooks/overrides would silently vanish). Serialize the
-// whole activation cycle (load -> activate -> set -> run -> clear -> deactivate)
-// on a dedicated FIFO queue so the critical section can never interleave. Full
+// pm-bl6m / pm-zumn: every native MCP action runs inside an activation cycle that
+// mutates the process-global active extension registries (set globals -> run -> clear
+// globals in a finally). The stdio transport already processes JSON-RPC lines
+// sequentially, but handleRequest is a public entry point (tests, future concurrent
+// transports) — if two requests ever ran concurrently, the newer one would overwrite
+// the globals mid-flight and whichever finished first would clear them out from under
+// the other (its lazily-read hooks/overrides would silently vanish). Serialize the
+// whole activation cycle (load -> activate -> set -> run -> clear -> deactivate) on a
+// dedicated FIFO queue so the critical section can never interleave. Full
 // request-scoped registry plumbing remains possible later if true intra-server
 // concurrency is ever needed.
-const dynamicExtensionActionQueue = createSerialQueue();
-async function runDynamicExtensionAction(action, args, options, global) {
-    if (global.noExtensions) {
-        throw new PmCliError(`Unsupported native pm action: ${action}`, 64);
-    }
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Unsupported native pm action: ${action}`, 64);
-    }
-    return dynamicExtensionActionQueue.enqueue(async () => {
+const extensionActivationQueue = createSerialQueue();
+/**
+ * Publishes empty active extension registries so built-in fallback actions cannot
+ * observe stale or partially published extension state from a failed activation cycle.
+ */
+function resetActiveExtensionRegistries() {
+    setActiveExtensionHooks(createEmptyExtensionHookRegistry());
+    setActiveExtensionCommands(createEmptyExtensionCommandRegistry());
+    setActiveExtensionParsers(createEmptyExtensionParserRegistry());
+    setActiveExtensionPreflight(createEmptyExtensionPreflightRegistry());
+    setActiveExtensionServices(createEmptyExtensionServiceRegistry());
+    setActiveExtensionRenderers(createEmptyExtensionRendererRegistry());
+    setActiveExtensionRegistrations(createEmptyExtensionRegistrationRegistry());
+}
+/**
+ * Run `run` with workspace extensions loaded, activated, and published to the
+ * process-global active registries, then torn down afterwards. pm-zumn: built-in native
+ * actions (pm_list/pm_profile/pm_schema/pm_create/...) read
+ * `getActiveExtensionRegistrations()` for custom item types, fields, and profiles, so
+ * they must activate extensions exactly like the CLI (main.ts activates for every
+ * command). Previously only the dynamic-extension dispatch activated, leaving
+ * extension-contributed schema and profiles invisible over MCP for every built-in
+ * action. Activation is skipped (`run` receives `null`) when extensions are disabled or
+ * no workspace exists yet (for example `init`). EVERY action — activating or not — is
+ * serialized on {@link extensionActivationQueue} so a built-in action's reads of the
+ * process-global active registries can never interleave with another request's
+ * activation cycle; per-request isolation therefore holds even if a truly concurrent
+ * transport is added later (not just because the stdio transport is sequential today).
+ */
+async function withActiveExtensions(global, explicitCwd, resolutionCwd, run) {
+    // Run the whole cycle on the queue so registry mutations never interleave. Only an
+    // EXPLICIT cwd mutates process.cwd() — pinned inside this serialized slot so the chdir
+    // can't be clobbered mid-flight and the built-in handler resolves against it too. A
+    // request without an explicit cwd runs in the server's current directory and never
+    // touches process.cwd() (important so concurrent direct callers can't corrupt a shared
+    // cwd). Either way activation resolves against resolutionCwd, the entry-time snapshot,
+    // so it never depends on a deferred process.cwd() read.
+    return extensionActivationQueue.enqueue(async () => {
         try {
-            return await runDynamicExtensionActionExclusively(action, args, options, global, pmRoot);
+            return explicitCwd === undefined
+                ? await withActiveExtensionsExclusively(global, resolutionCwd, run)
+                : await withCwd(explicitCwd, () => withActiveExtensionsExclusively(global, resolutionCwd, run));
         }
         finally {
             clearWorkspaceContractsCache();
         }
     });
 }
-// Body of the dynamic-action activation cycle. Must only ever run under
-// dynamicExtensionActionQueue (see runDynamicExtensionAction above): it is the
-// exclusive owner of the process-global active extension registries while it runs.
-async function runDynamicExtensionActionExclusively(action, args, options, global, pmRoot) {
-    const settings = await readSettings(pmRoot);
-    const loadResult = await loadExtensions({
-        pmRoot,
-        settings,
-        cwd: process.cwd(),
-        noExtensions: false,
-    });
-    // This MCP server reloads + reactivates extensions per native-action request,
-    // so each request is a fresh activation cycle. Run the extension teardown
-    // lifecycle in a finally to release any resources opened during activate(),
-    // matching the long-running-server reload contract (pm-k1e4).
-    let activationResult;
+/**
+ * Body of the activation cycle. Must only ever run under {@link extensionActivationQueue}
+ * (see {@link withActiveExtensions}): it is the exclusive owner of the process-global
+ * active extension registries while it runs. Returns early with `run(null)` — still
+ * inside the serialized critical section — when extensions are disabled or no workspace
+ * exists yet, so those built-in actions also observe a stable (empty) registry. This MCP
+ * server reloads + reactivates extensions per request, so each call is a fresh cycle with
+ * teardown in a finally to release resources opened during activate() (the
+ * long-running-server reload contract, pm-k1e4). Load/activate failures are swallowed and
+ * `run` is invoked with `null`, mirroring the CLI's resilient snapshot loader
+ * (loadRuntimeExtensionSnapshot) so a broken extension can never break a built-in action.
+ */
+async function withActiveExtensionsExclusively(global, cwd, run) {
+    if (global.noExtensions) {
+        return run(null);
+    }
+    const pmRoot = resolvePmRoot(cwd, global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        return run(null);
+    }
+    let active = null;
+    let activated;
     try {
-        activationResult = await activateExtensions({
-            ...loadResult,
-            loaded: loadResult.loaded,
-        });
-        const normalizedAction = normalizeActionName(action);
-        const definition = activationResult.registrations.commands.find((entry) => normalizeActionName(entry.action) === normalizedAction);
-        const command = definition?.command ??
-            activationResult.commands.handlers.find((entry) => normalizeActionName(entry.command) === normalizedAction)?.command;
-        if (!command) {
-            throw new PmCliError(`Unsupported native pm action: ${action}`, 64);
-        }
+        const settings = await readSettings(pmRoot);
+        const loadResult = await loadExtensions({ pmRoot, settings, cwd, noExtensions: false });
+        const activationResult = await activateExtensions({ ...loadResult, loaded: loadResult.loaded });
+        // Record the teardown handle BEFORE publishing the registries so a throw from any
+        // setActive* setter still runs deactivateExtensions for resources opened during
+        // activate() instead of silently leaking them.
+        activated = { loadResult, activationResult };
         setActiveExtensionHooks(activationResult.hooks);
         setActiveExtensionCommands(activationResult.commands);
         setActiveExtensionParsers(activationResult.parsers);
@@ -351,42 +383,68 @@ async function runDynamicExtensionActionExclusively(action, args, options, globa
         setActiveExtensionServices(activationResult.services);
         setActiveExtensionRenderers(activationResult.renderers);
         setActiveExtensionRegistrations(activationResult.registrations);
-        const handlerResult = await runActiveCommandHandler({
-            command: normalizeCommandPath(command),
-            args: readStringArray(options.args ?? args.args),
-            options: extensionOptionsFromArgs(args, options),
-            global,
-            pm_root: pmRoot,
-        });
-        if (!handlerResult.handled) {
-            const suffix = handlerResult.warnings.length > 0 ? ` (${handlerResult.warnings.join(", ")})` : "";
-            throw new PmCliError(`Unsupported native pm action: ${action}${suffix}`, 64);
-        }
-        return handlerResult.result;
+        active = { registrations: activationResult.registrations, commands: activationResult.commands, pmRoot };
+    }
+    catch (error) {
+        resetActiveExtensionRegistries();
+        // CLI parity (loadRuntimeExtensionSnapshot): a load/activate failure must never
+        // break a built-in action — fall back to running with no active extensions. Surface
+        // the cause on stderr so a broken extension is diagnosable instead of being silently
+        // indistinguishable from a workspace that simply has no extensions.
+        console.error("[pm-mcp] extension activation failed; continuing without active extensions:", error);
+        active = null;
+    }
+    try {
+        return await run(active);
     }
     finally {
         // Reset the process-global active registries FIRST so a torn-down extension's
         // overrides/hooks cannot leak into a later request in this long-running server
-        // (e.g. a subsequent pm_list/pm_create) even if teardown below misbehaves.
-        setActiveExtensionHooks(createEmptyExtensionHookRegistry());
-        setActiveExtensionCommands(createEmptyExtensionCommandRegistry());
-        setActiveExtensionParsers(createEmptyExtensionParserRegistry());
-        setActiveExtensionPreflight(createEmptyExtensionPreflightRegistry());
-        setActiveExtensionServices(createEmptyExtensionServiceRegistry());
-        setActiveExtensionRenderers(createEmptyExtensionRendererRegistry());
-        setActiveExtensionRegistrations(createEmptyExtensionRegistrationRegistry());
-        // Best-effort teardown of extensions that activated successfully. Skip
-        // entirely if activation itself never produced a result (nothing was set
-        // up), and guard so an unexpected throw cannot escape the finally.
-        if (activationResult) {
-            await deactivateExtensions(loadResult, activationResult).catch(() => undefined);
+        // (for example a subsequent pm_list/pm_create) even if teardown below misbehaves.
+        resetActiveExtensionRegistries();
+        // Best-effort teardown of extensions that activated successfully. Skipped when
+        // activation never completed (nothing was set up); guarded so an unexpected throw
+        // cannot escape the finally.
+        if (activated) {
+            await deactivateExtensions(activated.loadResult, activated.activationResult).catch(() => undefined);
         }
     }
 }
-async function withCwd(cwd, run) {
-    if (typeof cwd !== "string" || cwd.trim().length === 0) {
-        return run();
+/**
+ * Resolve `action` against the active extension command registrations and dispatch it.
+ * Reached by runAction's default case for dynamic (non-built-in) actions after
+ * {@link withActiveExtensions} has published the active registries. `active` is `null`
+ * when no extensions are active (disabled, no workspace, or activation failed), in
+ * which case no extension command can match and the action is reported unsupported.
+ */
+async function dispatchActiveExtensionAction(action, args, options, global, active) {
+    if (!active) {
+        throw new PmCliError(`Unsupported native pm action: ${action}`, 64);
+    }
+    const normalizedAction = normalizeActionName(action);
+    const definition = active.registrations.commands.find((entry) => normalizeActionName(entry.action) === normalizedAction);
+    const command = definition?.command ??
+        active.commands.handlers.find((entry) => normalizeActionName(entry.command) === normalizedAction)?.command;
+    if (!command) {
+        throw new PmCliError(`Unsupported native pm action: ${action}`, 64);
+    }
+    const handlerResult = await runActiveCommandHandler({
+        command: normalizeCommandPath(command),
+        args: readStringArray(options.args ?? args.args),
+        options: extensionOptionsFromArgs(args, options),
+        global,
+        pm_root: active.pmRoot,
+    });
+    if (!handlerResult.handled) {
+        const suffix = handlerResult.warnings.length > 0 ? ` (${handlerResult.warnings.join(", ")})` : "";
+        throw new PmCliError(`Unsupported native pm action: ${action}${suffix}`, 64);
     }
+    return handlerResult.result;
+}
+async function withCwd(cwd, run) {
+    // Only ever called with an explicit, non-empty cwd (readString filters blanks), from
+    // inside the serialized activation queue, so the chdir/restore is exclusive per request
+    // and can never be clobbered by a concurrent caller.
     const previous = process.cwd();
     process.chdir(cwd);
     try {
@@ -404,7 +462,7 @@ async function withCwd(cwd, run) {
  * are forwarded unchanged so runtime fields named `full` remain valid user data.
  */
 function withMutationCompaction(args, options) {
-    return { changedFields: args.fullChangedFields === true ? "full" : "compact", idOnly: args.idOnly === true, runnerOptions: { ...(options ?? {}) } };
+    return { changedFields: args.fullChangedFields === true ? "full" : "compact", idOnly: args.idOnly === true, runnerOptions: { ...options } };
 }
 function mutationListOptions(options) {
     return {
@@ -519,355 +577,414 @@ function updateManyOptionsFromFlat(options) {
 async function runAction(args) {
     const action = readRequiredString(args, "action");
     const global = globalOptions(args);
-    const options = optionsWithAuthor(args, action);
-    const id = readString(args, "id");
-    const force = args.force === true;
-    switch (action) {
-        case "init":
-            return runInit(readString(args, "prefix"), global, options);
-        case "context":
-            return runContext(options, global);
-        case "list": {
-            const listOptions = { ...options };
-            if (listOptions.compact === undefined &&
-                listOptions.brief === undefined &&
-                listOptions.fields === undefined &&
-                listOptions.includeBody === undefined) {
-                listOptions.compact = true;
-            }
-            // pm-rmjy: echo the applied filters + resolved projection mode so agents
-            // get structured confirmation of what the server actually ran.
-            return withQuerySummary((await runList(readString(args, "status"), listOptions, global)), listOptions);
-        }
-        case "get":
-            return runGet(id ?? readRequiredString(options, "id"), global, options);
-        case "search": {
-            const searchOptions = { ...options };
-            if (searchOptions.compact === undefined &&
-                searchOptions.full === undefined &&
-                searchOptions.fields === undefined) {
-                searchOptions.compact = true;
-            }
-            // pm-rmjy: echo the applied filters + resolved projection mode (see list).
-            return withQuerySummary((await runSearch(readRequiredString(args, "query"), searchOptions, global)), searchOptions);
-        }
-        case "create": {
-            const { changedFields, idOnly, runnerOptions } = withMutationCompaction(args, options);
-            return projectMutationResult(await runCreate(runnerOptions, global), { changedFields, idOnly });
-        }
-        case "copy": {
-            const { changedFields, idOnly, runnerOptions } = withMutationCompaction(args, options);
-            const copyOptions = {
-                ...runnerOptions,
-                ...(runnerOptions.title === undefined && typeof args.title === "string" ? { title: args.title } : {}),
-                ...(runnerOptions.message === undefined && typeof args.message === "string" ? { message: args.message } : {}),
-            };
-            return projectMutationResult(await runCopy(id ?? readRequiredString(copyOptions, "id"), copyOptions, global), { changedFields, idOnly });
-        }
-        case "focus": {
-            const clear = options.clear === true || args.clear === true;
-            return runFocus(id, { clear }, global);
-        }
-        case "update": {
-            const { changedFields, idOnly, runnerOptions } = withMutationCompaction(args, options);
-            return projectMutationResult(await runUpdate(id ?? readRequiredString(runnerOptions, "id"), runnerOptions, global), { changedFields, idOnly });
-        }
-        case "claim":
-            return runClaim(id ?? readRequiredString(options, "id"), force, global, options);
-        case "release":
-            return runRelease(id ?? readRequiredString(options, "id"), force, global, options);
-        case "close": {
-            const { changedFields, idOnly, runnerOptions } = withMutationCompaction(args, options);
-            const closeReason = readString(args, "reason") ??
-                readString(args, "text") ??
-                readString(runnerOptions, "reason") ??
-                readString(runnerOptions, "text");
-            return projectMutationResult(await runClose(id ?? readRequiredString(runnerOptions, "id"), closeReason, runnerOptions, global), { changedFields, idOnly });
-        }
-        case "comments": {
-            const commentOptions = { ...options };
-            const isListing = commentOptions.add === undefined &&
-                commentOptions.stdin === undefined &&
-                commentOptions.file === undefined &&
-                commentOptions.edit === undefined &&
-                commentOptions.delete === undefined;
-            if (isListing) {
-                commentOptions.includeMeta = true;
-                if (commentOptions.limit === undefined && commentOptions.full !== true) {
-                    commentOptions.limit = "20";
-                }
-            }
-            delete commentOptions.full;
-            return runComments(id ?? readRequiredString(options, "id"), commentOptions, global);
-        }
-        case "notes":
-            return runNotes(id ?? readRequiredString(options, "id"), options, global);
-        case "learnings":
-            return runLearnings(id ?? readRequiredString(options, "id"), options, global);
-        case "files": {
-            const fileId = id ?? readRequiredString(options, "id");
-            if (options.discover === true) {
-                return runFilesDiscover(fileId, withFilesDiscoveryOptions(options), global);
-            }
-            return runFiles(fileId, withAddNoteOption(options), global);
-        }
-        case "docs":
-            return runDocs(id ?? readRequiredString(options, "id"), withAddNoteOption(options), global);
-        case "test":
-            return runTest(id ?? readRequiredString(options, "id"), options, global);
-        case "test-all":
-            return runTestAll(options, global);
-        case "telemetry":
-            return runTelemetry({
-                subcommand: readString(args, "subcommand") ?? readString(options, "subcommand"),
-                limit: typeof args.limit === "number" && Number.isFinite(args.limit)
-                    ? args.limit
-                    : typeof options.limit === "number" && Number.isFinite(options.limit)
-                        ? options.limit
-                        : readString(args, "limit") ?? readString(options, "limit"),
-            }, global);
-        case "validate":
-            return runValidate(options, global);
-        case "health": {
-            // Default to the compact `summary` projection for agents (ok + per-check
-            // status + warning samples; ~22x smaller than the full payload). Callers
-            // opt into detail with brief/summary/full or the deep remediation payload
-            // via full=true. Mirrors the compact-by-default list/search behavior (F2).
-            const healthOptions = { ...options };
-            if (healthOptions.brief === undefined &&
-                healthOptions.summary === undefined &&
-                healthOptions.full === undefined) {
-                healthOptions.summary = true;
-            }
-            return runHealth(global, healthOptions);
-        }
-        case "contracts":
-            return runContracts(options, global);
-        case "config": {
-            // pm-v68d: the narrow pm_config tool declares configAction top-level;
-            // options.configAction/options.action remain accepted for pm_run parity.
-            const configAction = readString(args, "configAction") ?? readString(options, "configAction") ?? readString(options, "action");
-            if (configAction === undefined) {
-                throw new PmCliError("Missing required argument: configAction", 64);
-            }
-            return runConfig(readString(args, "scope") ?? readString(options, "scope") ?? "project", configAction, readString(args, "key") ?? readString(options, "key"), options, global, readString(args, "value") ?? readString(options, "value"));
-        }
-        case "activity": {
-            const activityOptions = { ...options };
-            if (activityOptions.compact === undefined) {
-                activityOptions.compact = activityOptions.full === true ? false : true;
-            }
-            delete activityOptions.full;
-            return runActivity(activityOptions, global);
+    // pm-zumn: dispatch every action (built-in and dynamic) inside one extension
+    // activation cycle so built-in actions see extension-contributed item types, fields,
+    // and profiles, consistent with the CLI. Snapshot the effective resolution cwd HERE,
+    // at request entry (the explicit args.cwd, else the server's current directory), so the
+    // queued cycle resolves against the directory the request arrived in rather than a value
+    // process.cwd() might hold by the time the task runs. Only an explicit cwd additionally
+    // pins process.cwd() (inside the serialized slot) for the built-in handler.
+    const explicitCwd = readString(args, "cwd");
+    const resolutionCwd = explicitCwd ?? process.cwd();
+    return withActiveExtensions(global, explicitCwd, resolutionCwd, (activeExtensions) => dispatchAction(action, args, global, activeExtensions));
+}
+function getOwnHandler(handlers, key) {
+    return Object.prototype.hasOwnProperty.call(handlers, key) ? handlers[key] : undefined;
+}
+function readMcpTarget(ctx) {
+    return readString(ctx.args, "target") ?? readString(ctx.options, "target");
+}
+function requireMcpItemId(ctx, source = ctx.options) {
+    return ctx.id ?? readRequiredString(source, "id");
+}
+async function runMcpListAction(ctx) {
+    const listOptions = { ...ctx.options };
+    if (listOptions.compact === undefined &&
+        listOptions.brief === undefined &&
+        listOptions.fields === undefined &&
+        listOptions.includeBody === undefined) {
+        listOptions.compact = true;
+    }
+    // pm-rmjy: echo applied filters + projection mode so agents get structured confirmation.
+    return withQuerySummary((await runList(readString(ctx.args, "status"), listOptions, ctx.global)), listOptions);
+}
+async function runMcpSearchAction(ctx) {
+    const searchOptions = { ...ctx.options };
+    if (searchOptions.compact === undefined && searchOptions.full === undefined && searchOptions.fields === undefined) {
+        searchOptions.compact = true;
+    }
+    return withQuerySummary((await runSearch(readRequiredString(ctx.args, "query"), searchOptions, ctx.global)), searchOptions);
+}
+async function runMcpCreateAction(ctx) {
+    const { changedFields, idOnly, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
+    return projectMutationResult(await runCreate(runnerOptions, ctx.global), { changedFields, idOnly });
+}
+async function runMcpCopyAction(ctx) {
+    const { changedFields, idOnly, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
+    const copyOptions = {
+        ...runnerOptions,
+        ...(runnerOptions.title === undefined && typeof ctx.args.title === "string" ? { title: ctx.args.title } : {}),
+        ...(runnerOptions.message === undefined && typeof ctx.args.message === "string" ? { message: ctx.args.message } : {}),
+    };
+    return projectMutationResult(await runCopy(requireMcpItemId(ctx, copyOptions), copyOptions, ctx.global), {
+        changedFields,
+        idOnly,
+    });
+}
+async function runMcpUpdateAction(ctx) {
+    const { changedFields, idOnly, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
+    return projectMutationResult(await runUpdate(requireMcpItemId(ctx, runnerOptions), runnerOptions, ctx.global), {
+        changedFields,
+        idOnly,
+    });
+}
+async function runMcpCloseAction(ctx) {
+    const { changedFields, idOnly, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
+    const closeReason = readString(ctx.args, "reason") ??
+        readString(ctx.args, "text") ??
+        readString(runnerOptions, "reason") ??
+        readString(runnerOptions, "text");
+    return projectMutationResult(await runClose(requireMcpItemId(ctx, runnerOptions), closeReason, runnerOptions, ctx.global), { changedFields, idOnly });
+}
+function runMcpCommentsAction(ctx) {
+    const commentOptions = { ...ctx.options };
+    const isListing = commentOptions.add === undefined &&
+        commentOptions.stdin === undefined &&
+        commentOptions.file === undefined &&
+        commentOptions.edit === undefined &&
+        commentOptions.delete === undefined;
+    if (isListing) {
+        commentOptions.includeMeta = true;
+        if (commentOptions.limit === undefined && commentOptions.full !== true) {
+            commentOptions.limit = "20";
         }
-        case "aggregate":
-            return runAggregate(options, global);
-        case "extension":
-            return runExtension(readString(args, "target") ?? readString(options, "target"), options, global);
-        case "extension-reload":
-            return runExtension(undefined, { ...options, reload: true }, global);
-        case "package":
-            return runExtension(readString(args, "target") ?? readString(options, "target"), options, global);
-        case "package-install":
-        case "install":
-            return runExtension(readString(args, "target") ?? readString(options, "target"), { ...options, install: true }, global);
-        case "package-catalog":
-            return runExtension(undefined, { ...options, catalog: true, vocabulary: "package" }, global);
-        case "upgrade":
-            return runUpgrade(readString(args, "target") ?? readString(options, "target"), options, global);
-        case "delete":
-            return runDelete(id ?? readRequiredString(options, "id"), options, global);
-        case "deps":
-            return runDeps(id ?? readRequiredString(options, "id"), options, global);
-        case "files-discover":
-            return runFilesDiscover(id ?? readRequiredString(options, "id"), options, global);
-        case "history":
-            return runHistory(id ?? readRequiredString(options, "id"), options, global);
-        case "history-redact":
-            return runHistoryRedact(id ?? readRequiredString(options, "id"), options, global);
-        case "history-repair": {
-            const repairAll = options.all === true;
-            const repairId = id ?? readString(options, "id");
-            assertHistoryRepairTarget(repairId, repairAll);
-            return repairAll ? runHistoryRepairAll(options, global) : runHistoryRepair(repairId, options, global);
+    }
+    delete commentOptions.full;
+    return runComments(requireMcpItemId(ctx), commentOptions, ctx.global);
+}
+function runMcpFilesAction(ctx) {
+    const fileId = requireMcpItemId(ctx);
+    return ctx.options.discover === true
+        ? runFilesDiscover(fileId, withFilesDiscoveryOptions(ctx.options), ctx.global)
+        : runFiles(fileId, withAddNoteOption(ctx.options), ctx.global);
+}
+function runMcpTelemetryAction(ctx) {
+    return runTelemetry({
+        subcommand: readString(ctx.args, "subcommand") ?? readString(ctx.options, "subcommand"),
+        limit: resolveMcpTelemetryLimit(ctx.args, ctx.options),
+    }, ctx.global);
+}
+function resolveMcpTelemetryLimit(args, options) {
+    if (typeof args.limit === "number" && Number.isFinite(args.limit)) {
+        return args.limit;
+    }
+    if (typeof options.limit === "number" && Number.isFinite(options.limit)) {
+        return options.limit;
+    }
+    return readString(args, "limit") ?? readString(options, "limit");
+}
+function runMcpHealthAction(ctx) {
+    const healthOptions = { ...ctx.options };
+    if (healthOptions.brief === undefined && healthOptions.summary === undefined && healthOptions.full === undefined) {
+        healthOptions.summary = true;
+    }
+    return runHealth(ctx.global, healthOptions);
+}
+function runMcpConfigAction(ctx) {
+    const configAction = readString(ctx.args, "configAction") ?? readString(ctx.options, "configAction") ?? readString(ctx.options, "action");
+    if (configAction === undefined) {
+        throw new PmCliError("Missing required argument: configAction", 64);
+    }
+    return runConfig(readString(ctx.args, "scope") ?? readString(ctx.options, "scope") ?? "project", configAction, readString(ctx.args, "key") ?? readString(ctx.options, "key"), ctx.options, ctx.global, readString(ctx.args, "value") ?? readString(ctx.options, "value"));
+}
+function runMcpActivityAction(ctx) {
+    const activityOptions = { ...ctx.options };
+    if (activityOptions.compact === undefined) {
+        activityOptions.compact = activityOptions.full === true ? false : true;
+    }
+    delete activityOptions.full;
+    return runActivity(activityOptions, ctx.global);
+}
+function runMcpHistoryRepairAction(ctx) {
+    const repairAll = ctx.options.all === true;
+    const repairId = ctx.id ?? readString(ctx.options, "id");
+    assertHistoryRepairTarget(repairId, repairAll);
+    return repairAll ? runHistoryRepairAll(ctx.options, ctx.global) : runHistoryRepair(repairId, ctx.options, ctx.global);
+}
+function parseMcpInteger(value, label) {
+    if (typeof value === "number") {
+        if (!Number.isInteger(value)) {
+            throw new PmCliError(`${label} must be a finite integer.`, 64);
         }
-        case "history-compact":
-            return runHistoryCompact(id ?? readRequiredString(options, "id"), options, global);
-        case "plan": {
-            const subcommand = readRequiredString(options, "subcommand");
-            const planRecord = options;
-            const reorderToken = planRecord.reorderTo ?? args.reorderTo;
-            const reorderTo = typeof reorderToken === "number" && Number.isFinite(reorderToken)
-                ? reorderToken
-                : typeof reorderToken === "string" && reorderToken.trim().length > 0
-                    ? Number.parseInt(reorderToken, 10)
-                    : undefined;
-            const stepRef = typeof planRecord.stepRef === "string"
-                ? planRecord.stepRef
-                : typeof args.stepRef === "string"
-                    ? args.stepRef
-                    : undefined;
-            return runPlan({
-                subcommand: subcommand,
-                id: typeof id === "string" ? id : typeof planRecord.id === "string" ? planRecord.id : undefined,
-                stepRef,
-                reorderTo,
-                options: options,
-                global,
-            });
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed)) {
+            throw new PmCliError(`${label} must be a finite integer.`, 64);
         }
-        case "schema": {
-            // subcommand/name are top-level fields in the published action contract,
-            // so accept them from args first and fall back to options for parity.
-            const subcommand = readString(args, "subcommand") ?? readRequiredString(options, "subcommand");
-            const normalizedSubcommand = subcommand.trim().toLowerCase();
-            const schemaName = readString(args, "name") ?? readString(options, "name");
-            const schemaAuthor = readString(args, "author") ?? readString(options, "author");
-            const schemaForce = args.force === true || options.force === true;
-            if (normalizedSubcommand === "list") {
-                return runSchemaList(global);
-            }
-            if (normalizedSubcommand === "show") {
-                return runSchemaShow(schemaName, global);
-            }
-            if (normalizedSubcommand === "show-status") {
-                return runSchemaShowStatus(schemaName, global);
-            }
-            if (normalizedSubcommand === "list-fields") {
-                return runSchemaListFields(global);
-            }
-            if (normalizedSubcommand === "show-field") {
-                return runSchemaShowField(schemaName, global);
-            }
-            if (normalizedSubcommand === "remove-type") {
-                return runSchemaRemoveType(schemaName, { author: schemaAuthor, force: schemaForce }, global);
-            }
-            if (normalizedSubcommand === "remove-field") {
-                return runSchemaRemoveField(schemaName, { author: schemaAuthor, force: schemaForce }, global);
-            }
-            if (normalizedSubcommand === "apply-preset") {
-                const presetSource = readString(args, "typePreset") ?? readString(options, "typePreset");
-                return runSchemaApplyPreset(presetSource, { author: schemaAuthor, force: schemaForce }, global);
-            }
-            const aliasSource = args.alias ?? options.alias;
-            const aliases = aliasSource === undefined ? undefined : readStringArray(aliasSource);
-            if (normalizedSubcommand === "add-field") {
-                const commandsSource = args.commands ?? options.commands;
-                const commands = commandsSource === undefined ? undefined : readStringArray(commandsSource);
-                const requiredTypesSource = args.requiredTypes ?? options.requiredTypes;
-                const requiredTypes = requiredTypesSource === undefined ? undefined : readStringArray(requiredTypesSource);
-                return runSchemaAddField(schemaName, {
-                    type: readString(args, "fieldType") ?? readString(options, "fieldType"),
-                    commands,
-                    description: readString(args, "description") ?? readString(options, "description"),
-                    cliFlag: readString(args, "cliFlag") ?? readString(options, "cliFlag"),
-                    alias: aliases,
-                    required: args.required === true || options.required === true,
-                    requiredOnCreate: args.requiredOnCreate === true || options.requiredOnCreate === true,
-                    // allow_unset defaults true; only an explicit false disables it.
-                    allowUnset: !(args.allowUnset === false || options.allowUnset === false),
-                    requiredTypes,
-                    author: schemaAuthor,
-                    force: schemaForce,
-                }, global);
-            }
-            if (normalizedSubcommand === "add-status") {
-                const roleSource = args.role ?? options.role;
-                const roles = roleSource === undefined ? undefined : readStringArray(roleSource);
-                const orderSource = args.order ?? options.order;
-                let order;
-                if (typeof orderSource === "number") {
-                    if (!Number.isInteger(orderSource)) {
-                        throw new PmCliError("schema add-status order must be a finite integer.", 64);
-                    }
-                    order = orderSource;
-                }
-                else if (typeof orderSource === "string" && orderSource.trim().length > 0) {
-                    const parsed = Number(orderSource);
-                    if (!Number.isInteger(parsed)) {
-                        throw new PmCliError("schema add-status order must be a finite integer.", 64);
-                    }
-                    order = parsed;
-                }
-                return runSchemaAddStatus(schemaName, {
-                    role: roles,
-                    alias: aliases,
-                    description: readString(args, "description") ?? readString(options, "description"),
-                    order,
-                    author: schemaAuthor,
-                    force: schemaForce,
-                }, global);
-            }
-            if (normalizedSubcommand === "remove-status") {
-                return runSchemaRemoveStatus(schemaName, { author: schemaAuthor, force: schemaForce }, global);
-            }
-            if (normalizedSubcommand !== "add-type") {
-                throw new PmCliError(`Unknown pm schema subcommand "${subcommand}". Allowed: add-type, remove-type, add-status, remove-status, add-field, remove-field, list-fields, show-field, apply-preset, list, show, show-status`, 64);
-            }
-            if (args.infer === true || options.infer === true) {
-                const minCountSource = args.minCount ?? options.minCount;
-                const minCount = typeof minCountSource === "number"
-                    ? minCountSource
-                    : typeof minCountSource === "string" && minCountSource.trim().length > 0
-                        ? Number(minCountSource)
-                        : undefined;
-                return runSchemaInferTypes({
-                    minCount,
-                    apply: args.apply === true || options.apply === true,
-                    author: schemaAuthor,
-                    force: schemaForce,
-                }, global);
-            }
-            return runSchemaAddType(schemaName, {
-                description: readString(args, "description") ?? readString(options, "description"),
-                defaultStatus: readString(args, "defaultStatus") ??
-                    readString(args, "default_status") ??
-                    readString(options, "defaultStatus") ??
-                    readString(options, "default_status"),
-                folder: readString(args, "folder") ?? readString(options, "folder"),
-                alias: aliases,
-                author: schemaAuthor,
-                force: schemaForce,
-            }, global);
+        return parsed;
+    }
+    return undefined;
+}
+function parseMcpIntegerPrefix(value, label) {
+    if (typeof value === "number") {
+        const parsed = Number.parseInt(String(value), 10);
+        if (!Number.isInteger(parsed)) {
+            throw new PmCliError(`${label} must be a finite integer.`, 64);
         }
-        case "stats":
-            return runStats(global, {
-                storage: options.storage === true,
-                metadataCoverage: options.metadataCoverage === true,
-                fieldUtilization: options.fieldUtilization === true,
-                byAssignee: options.byAssignee === true,
-                byTag: options.byTag === true,
-                byPriority: options.byPriority === true,
-                tagPrefix: typeof options.tagPrefix === "string" ? options.tagPrefix : undefined,
-            });
-        case "append": {
-            const { changedFields, runnerOptions } = withMutationCompaction(args, options);
-            return projectMutationResult(await runAppend(id ?? readRequiredString(runnerOptions, "id"), runnerOptions, global), { changedFields });
+        return parsed;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const trimmed = value.trim();
+        if (!/^[+-]?\d+(?:st|nd|rd|th)?$/i.test(trimmed)) {
+            throw new PmCliError(`${label} must be a finite integer.`, 64);
         }
-        case "update-many": {
-            const { changedFields, runnerOptions } = withMutationCompaction(args, options);
-            return projectMutationResult(await runUpdateMany(updateManyOptionsFromFlat(runnerOptions), global), { changedFields });
+        const parsed = Number.parseInt(trimmed, 10);
+        if (!Number.isInteger(parsed)) {
+            throw new PmCliError(`${label} must be a finite integer.`, 64);
         }
-        case "close-many": {
-            const { changedFields, runnerOptions } = withMutationCompaction(args, options);
-            const topLevelReason = readString(args, "reason");
-            const closeManyRunnerOptions = topLevelReason !== undefined && runnerOptions.reason === undefined
-                ? { ...runnerOptions, reason: topLevelReason }
-                : { ...runnerOptions };
-            if (force && closeManyRunnerOptions.force === undefined) {
-                closeManyRunnerOptions.force = true;
-            }
-            return projectMutationResult(await runCloseMany(closeManyOptionsFromFlat(closeManyRunnerOptions), global), { changedFields });
+        return parsed;
+    }
+    return undefined;
+}
+function runMcpPlanAction(ctx) {
+    const subcommand = readRequiredString(ctx.options, "subcommand");
+    const planRecord = ctx.options;
+    return runPlan({
+        subcommand: subcommand,
+        id: typeof ctx.id === "string" ? ctx.id : typeof planRecord.id === "string" ? planRecord.id : undefined,
+        stepRef: readMcpPlanStepRef(ctx),
+        reorderTo: parseMcpIntegerPrefix(planRecord.reorderTo ?? ctx.args.reorderTo, "plan reorderTo"),
+        options: ctx.options,
+        global: ctx.global,
+    });
+}
+function readMcpPlanStepRef(ctx) {
+    return typeof ctx.options.stepRef === "string"
+        ? ctx.options.stepRef
+        : typeof ctx.args.stepRef === "string"
+            ? ctx.args.stepRef
+            : undefined;
+}
+function createMcpSchemaContext(ctx) {
+    const subcommand = readString(ctx.args, "subcommand") ?? readRequiredString(ctx.options, "subcommand");
+    const aliasSource = ctx.args.alias ?? ctx.options.alias;
+    return {
+        ctx,
+        subcommand: subcommand.trim().toLowerCase(),
+        name: readString(ctx.args, "name") ?? readString(ctx.options, "name"),
+        author: readString(ctx.args, "author") ?? readString(ctx.options, "author"),
+        force: ctx.args.force === true || ctx.options.force === true,
+        aliases: aliasSource === undefined ? undefined : readStringArray(aliasSource),
+    };
+}
+function runMcpSchemaReadOrRemoveAction(schema) {
+    const { ctx, subcommand, name, author, force } = schema;
+    const simpleHandlers = {
+        list: () => runSchemaList(ctx.global),
+        show: () => runSchemaShow(name, ctx.global),
+        "show-status": () => runSchemaShowStatus(name, ctx.global),
+        "list-fields": () => runSchemaListFields(ctx.global),
+        "show-field": () => runSchemaShowField(name, ctx.global),
+        "remove-type": () => runSchemaRemoveType(name, { author, force }, ctx.global),
+        "remove-field": () => runSchemaRemoveField(name, { author, force }, ctx.global),
+        "remove-status": () => runSchemaRemoveStatus(name, { author, force }, ctx.global),
+        "apply-preset": () => runSchemaApplyPreset(readString(ctx.args, "typePreset") ?? readString(ctx.options, "typePreset"), { author, force }, ctx.global),
+    };
+    const handler = getOwnHandler(simpleHandlers, subcommand);
+    return handler ? handler() : null;
+}
+function runMcpSchemaAddFieldAction(schema) {
+    const { ctx, name, author, force, aliases } = schema;
+    const commandsSource = ctx.args.commands ?? ctx.options.commands;
+    const requiredTypesSource = ctx.args.requiredTypes ?? ctx.options.requiredTypes;
+    return runSchemaAddField(name, {
+        type: readString(ctx.args, "fieldType") ?? readString(ctx.options, "fieldType"),
+        commands: commandsSource === undefined ? undefined : readStringArray(commandsSource),
+        description: readString(ctx.args, "description") ?? readString(ctx.options, "description"),
+        cliFlag: readString(ctx.args, "cliFlag") ?? readString(ctx.options, "cliFlag"),
+        alias: aliases,
+        required: ctx.args.required === true || ctx.options.required === true,
+        requiredOnCreate: ctx.args.requiredOnCreate === true || ctx.options.requiredOnCreate === true,
+        allowUnset: !(ctx.args.allowUnset === false || ctx.options.allowUnset === false),
+        requiredTypes: requiredTypesSource === undefined ? undefined : readStringArray(requiredTypesSource),
+        author,
+        force,
+    }, ctx.global);
+}
+function runMcpSchemaAddStatusAction(schema) {
+    const { ctx, name, author, force, aliases } = schema;
+    const roleSource = ctx.args.role ?? ctx.options.role;
+    return runSchemaAddStatus(name, {
+        role: roleSource === undefined ? undefined : readStringArray(roleSource),
+        alias: aliases,
+        description: readString(ctx.args, "description") ?? readString(ctx.options, "description"),
+        order: parseMcpInteger(ctx.args.order ?? ctx.options.order, "schema add-status order"),
+        author,
+        force,
+    }, ctx.global);
+}
+function runMcpSchemaAddTypeAction(schema) {
+    const { ctx, name, author, force, aliases } = schema;
+    return runSchemaAddType(name, {
+        description: readString(ctx.args, "description") ?? readString(ctx.options, "description"),
+        defaultStatus: readString(ctx.args, "defaultStatus") ??
+            readString(ctx.args, "default_status") ??
+            readString(ctx.options, "defaultStatus") ??
+            readString(ctx.options, "default_status"),
+        folder: readString(ctx.args, "folder") ?? readString(ctx.options, "folder"),
+        alias: aliases,
+        author,
+        force,
+    }, ctx.global);
+}
+function runMcpSchemaAction(ctx) {
+    const schema = createMcpSchemaContext(ctx);
+    const simpleResult = runMcpSchemaReadOrRemoveAction(schema);
+    if (simpleResult !== null) {
+        return simpleResult;
+    }
+    if (schema.subcommand === "add-field") {
+        return runMcpSchemaAddFieldAction(schema);
+    }
+    if (schema.subcommand === "add-status") {
+        return runMcpSchemaAddStatusAction(schema);
+    }
+    if (schema.subcommand === "add-type") {
+        if (ctx.args.infer === true || ctx.options.infer === true) {
+            return runSchemaInferTypes({
+                minCount: parseMcpInteger(ctx.args.minCount ?? ctx.options.minCount, "schema infer minCount"),
+                apply: ctx.args.apply === true || ctx.options.apply === true,
+                author: schema.author,
+                force: schema.force,
+            }, ctx.global);
         }
-        case "gc":
-            return runGc(global, options);
-        default:
-            return runDynamicExtensionAction(action, args, options, global);
+        return runMcpSchemaAddTypeAction(schema);
+    }
+    throw new PmCliError(`Unknown pm schema subcommand "${schema.subcommand}". Allowed: add-type, remove-type, add-status, remove-status, add-field, remove-field, list-fields, show-field, apply-preset, list, show, show-status`, 64);
+}
+function runMcpProfileAction(ctx) {
+    const subcommand = readString(ctx.args, "subcommand") ?? readRequiredString(ctx.options, "subcommand");
+    const normalizedSubcommand = subcommand.trim().toLowerCase();
+    const profileName = readString(ctx.args, "name") ?? readString(ctx.options, "name");
+    const handlers = {
+        list: () => runProfileList(),
+        show: () => runProfileShow(profileName),
+        lint: () => runProfileLint(profileName),
+        apply: () => runProfileApply(profileName, {
+            dryRun: ctx.args.dryRun === true || ctx.options.dryRun === true,
+            author: readString(ctx.args, "author") ?? readString(ctx.options, "author"),
+            force: ctx.args.force === true || ctx.options.force === true,
+        }, ctx.global),
+    };
+    const handler = getOwnHandler(handlers, normalizedSubcommand);
+    if (!handler) {
+        throw new PmCliError(`Unknown pm profile subcommand "${subcommand}". Allowed: list, show, apply, lint`, 64);
+    }
+    return handler();
+}
+function runMcpStatsAction(ctx) {
+    return runStats(ctx.global, {
+        storage: ctx.options.storage === true,
+        metadataCoverage: ctx.options.metadataCoverage === true,
+        fieldUtilization: ctx.options.fieldUtilization === true,
+        byAssignee: ctx.options.byAssignee === true,
+        byTag: ctx.options.byTag === true,
+        byPriority: ctx.options.byPriority === true,
+        tagPrefix: typeof ctx.options.tagPrefix === "string" ? ctx.options.tagPrefix : undefined,
+    });
+}
+async function runMcpAppendAction(ctx) {
+    const { changedFields, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
+    return projectMutationResult(await runAppend(requireMcpItemId(ctx, runnerOptions), runnerOptions, ctx.global), {
+        changedFields,
+    });
+}
+async function runMcpUpdateManyAction(ctx) {
+    const { changedFields, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
+    return projectMutationResult(await runUpdateMany(updateManyOptionsFromFlat(runnerOptions), ctx.global), { changedFields });
+}
+async function runMcpCloseManyAction(ctx) {
+    const { changedFields, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
+    const topLevelReason = readString(ctx.args, "reason");
+    const closeManyRunnerOptions = topLevelReason !== undefined && runnerOptions.reason === undefined
+        ? { ...runnerOptions, reason: topLevelReason }
+        : { ...runnerOptions };
+    if (ctx.force && closeManyRunnerOptions.force === undefined) {
+        closeManyRunnerOptions.force = true;
     }
+    return projectMutationResult(await runCloseMany(closeManyOptionsFromFlat(closeManyRunnerOptions), ctx.global), { changedFields });
+}
+const MCP_ACTION_HANDLERS = {
+    init: (ctx) => runInit(readString(ctx.args, "prefix"), ctx.global, ctx.options),
+    context: (ctx) => runContext(ctx.options, ctx.global),
+    next: (ctx) => runNext(ctx.options, ctx.global),
+    list: runMcpListAction,
+    get: (ctx) => runGet(requireMcpItemId(ctx), ctx.global, ctx.options),
+    search: runMcpSearchAction,
+    create: runMcpCreateAction,
+    copy: runMcpCopyAction,
+    focus: (ctx) => runFocus(ctx.id, { clear: ctx.options.clear === true || ctx.args.clear === true }, ctx.global),
+    update: runMcpUpdateAction,
+    claim: (ctx) => runClaim(requireMcpItemId(ctx), ctx.force, ctx.global, ctx.options),
+    release: (ctx) => runRelease(requireMcpItemId(ctx), ctx.force, ctx.global, ctx.options),
+    close: runMcpCloseAction,
+    comments: runMcpCommentsAction,
+    notes: (ctx) => runNotes(requireMcpItemId(ctx), ctx.options, ctx.global),
+    learnings: (ctx) => runLearnings(requireMcpItemId(ctx), ctx.options, ctx.global),
+    files: runMcpFilesAction,
+    docs: (ctx) => runDocs(requireMcpItemId(ctx), withAddNoteOption(ctx.options), ctx.global),
+    test: (ctx) => runTest(requireMcpItemId(ctx), ctx.options, ctx.global),
+    "test-all": (ctx) => runTestAll(ctx.options, ctx.global),
+    telemetry: runMcpTelemetryAction,
+    validate: (ctx) => runValidate(ctx.options, ctx.global),
+    health: runMcpHealthAction,
+    contracts: (ctx) => runContracts(ctx.options, ctx.global),
+    config: runMcpConfigAction,
+    activity: runMcpActivityAction,
+    aggregate: (ctx) => runAggregate(ctx.options, ctx.global),
+    extension: (ctx) => runExtension(readMcpTarget(ctx), ctx.options, ctx.global),
+    "extension-reload": (ctx) => runExtension(undefined, { ...ctx.options, reload: true }, ctx.global),
+    package: (ctx) => runExtension(readMcpTarget(ctx), ctx.options, ctx.global),
+    "package-install": (ctx) => runExtension(readMcpTarget(ctx), { ...ctx.options, install: true }, ctx.global),
+    install: (ctx) => runExtension(readMcpTarget(ctx), { ...ctx.options, install: true }, ctx.global),
+    "package-catalog": (ctx) => runExtension(undefined, { ...ctx.options, catalog: true, vocabulary: "package" }, ctx.global),
+    upgrade: (ctx) => runUpgrade(readMcpTarget(ctx), ctx.options, ctx.global),
+    delete: (ctx) => runDelete(requireMcpItemId(ctx), ctx.options, ctx.global),
+    deps: (ctx) => runDeps(requireMcpItemId(ctx), ctx.options, ctx.global),
+    "files-discover": (ctx) => runFilesDiscover(requireMcpItemId(ctx), ctx.options, ctx.global),
+    history: (ctx) => runHistory(requireMcpItemId(ctx), ctx.options, ctx.global),
+    "history-redact": (ctx) => runHistoryRedact(requireMcpItemId(ctx), ctx.options, ctx.global),
+    "history-repair": runMcpHistoryRepairAction,
+    "history-compact": (ctx) => runHistoryCompact(requireMcpItemId(ctx), ctx.options, ctx.global),
+    plan: runMcpPlanAction,
+    schema: runMcpSchemaAction,
+    profile: runMcpProfileAction,
+    stats: runMcpStatsAction,
+    append: runMcpAppendAction,
+    "update-many": runMcpUpdateManyAction,
+    "close-many": runMcpCloseManyAction,
+    gc: (ctx) => runGc(ctx.global, ctx.options),
+};
+async function dispatchAction(action, args, global, activeExtensions) {
+    const options = optionsWithAuthor(args, action);
+    const ctx = {
+        action,
+        args,
+        options,
+        id: readString(args, "id"),
+        force: args.force === true,
+        global,
+        activeExtensions,
+    };
+    const handler = getOwnHandler(MCP_ACTION_HANDLERS, action);
+    return handler ? handler(ctx) : dispatchActiveExtensionAction(action, args, options, global, activeExtensions);
 }
 const HANDLERS = {
     pm_run: (args) => runAction(args),
     pm_context: (args) => runAction({ ...args, action: "context" }),
+    pm_next: (args) => runAction({ ...args, action: "next" }),
     pm_search: (args) => runAction({ ...args, action: "search" }),
     pm_list: (args) => runAction({ ...args, action: "list" }),
     pm_get: (args) => runAction({ ...args, action: "get" }),
@@ -890,6 +1007,7 @@ const HANDLERS = {
     pm_health: (args) => runAction({ ...args, action: "health" }),
     pm_contracts: (args) => runAction({ ...args, action: "contracts" }),
     pm_schema: (args) => runAction({ ...args, action: "schema" }),
+    pm_profile: (args) => runAction({ ...args, action: "profile" }),
     pm_config: (args) => runAction({ ...args, action: "config" }),
     pm_plan: (args) => runAction({ ...args, action: "plan" }),
 };
@@ -939,8 +1057,8 @@ export async function handleRequest(request) {
             capabilities: { tools: {} },
             serverInfo: { name: "pm-mcp", version: PM_MCP_SERVER_VERSION },
             instructions: "You have access to native pm CLI tools for git-based project management. " +
-                "Use pm_context or pm_search before creating new work. " +
-                "Prefer narrow tools (pm_context, pm_list, pm_get, pm_search, pm_create, 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_test, pm_validate, pm_health, pm_contracts, pm_schema, pm_config, pm_plan) over pm_run when they cover the operation. " +
+                "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_create, 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_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. " +
                 "Use pm_schema and pm_config for workspace configuration: pm_schema manages custom item types/statuses and pm_config reads or writes settings keys. " +
                 "Use pm_run with an explicit action for package-owned operations (calendar/templates/guide/dedupe-audit/normalize/reindex/comments-audit/completion/test-runs-list/test-runs-status/test-runs-logs/test-runs-stop/test-runs-resume), plus activity, aggregate, history, stats, test-all, and gc. " +
@@ -955,7 +1073,7 @@ export async function handleRequest(request) {
     if (request.method === "tools/call") {
         const params = asRecordClone(request.params);
         const name = readRequiredString(params, "name");
-        const handler = HANDLERS[name];
+        const handler = getOwnHandler(HANDLERS, name);
         if (!handler) {
             throw new PmCliError(`Unknown pm MCP tool: ${name}`, 64);
         }
@@ -972,7 +1090,9 @@ export async function handleRequest(request) {
         for (const warning of warnings) {
             console.error(`[pm-mcp] ${warning}`);
         }
-        const result = await withCwd(args.cwd, () => handler(args));
+        // cwd is applied inside the serialized activation cycle (see withActiveExtensions),
+        // so the chdir/restore is exclusive per request and cannot race a concurrent caller.
+        const result = await handler(args);
         return resultContent(result, warnings);
     }
     throw new PmCliError(`Unsupported MCP method: ${request.method ?? "(missing)"}`, 64);
@@ -1093,4 +1213,4 @@ if (isInvokedAsMcpMainModule(process.argv[1], import.meta.url)) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=server.js.map
-//# debugId=ad8d2ba8-8a0e-5d5e-b4d2-00e538908f91
+//# debugId=28140feb-d035-55d6-bd6a-d90ed2c41f26