@unbrained/pm-cli 2026.7.5 → 2026.7.7

package/dist/sdk/runtime.js

@@ -4,13 +4,27 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="9ed0f12b-4f84-58a2-86c7-aff1a8b86f0a")}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]="89db1e15-b152-57e2-910d-64ed77eb540b")}catch(e){}}();
 import path from "node:path";
-import { activateExtensions, loadExtensions, } from "../core/extensions/index.js";
+import { createEmptyExtensionCommandRegistry, createEmptyExtensionHookRegistry, createEmptyExtensionParserRegistry, createEmptyExtensionPreflightRegistry, createEmptyExtensionRegistrationRegistry, createEmptyExtensionRendererRegistry, createEmptyExtensionServiceRegistry, } from "../core/extensions/extension-registries.js";
+import { activateExtensions, deactivateExtensions, loadExtensions, runActiveCommandHandler, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, } from "../core/extensions/index.js";
+import { pathExists } from "../core/fs/fs-utils.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
+import { projectMutationResult } from "../core/output/mutation-projection.js";
+import { withQuerySummary } from "../core/output/query-summary.js";
+import { PmCliError } from "../core/shared/errors.js";
+import { asRecordClone } from "../core/shared/primitives.js";
+import { createSerialQueue } from "../core/shared/serial-queue.js";
 import { resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
+import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
+import { normalizeListOptions, normalizeUpdateOptions } from "../cli/registration-helpers.js";
+import { UPDATE_COMMANDER_STRING_OPTION_CONTRACTS } from "./cli-contracts/commander-mutation-options.js";
+import { clearWorkspaceContractsCache, memoizeWorkspaceExtensionRegistrations, } from "./workspace-contracts-cache.js";
+export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";
+import { assertHistoryRepairTarget, runActivity, runAggregate, runAppend, runClaim, runClose, runCloseMany, runComments, runConfig, runContext, runCopy, runCreate, runDelete, runDeps, runDocs, runExtension, runFiles, runFilesDiscover, runFocus, runGc, runGet, runHealth, runHistory, runHistoryCompact, runHistoryRedact, runHistoryRepair, runHistoryRepairAll, runInit, runLearnings, runList, runNext, runNotes, runPlan, runProfileApply, runProfileLint, runProfileList, runProfileShow, runRestore, runRelease, runSchemaAddField, runSchemaAddStatus, runSchemaAddType, runSchemaApplyPreset, runSchemaInferTypes, runSchemaList, runSchemaListFields, runSchemaRemoveField, runSchemaRemoveStatus, runSchemaRemoveType, runSchemaShow, runSchemaShowField, runSchemaShowStatus, runSearch, runStats, runTelemetry, runTest, runTestAll, runUpdate, runUpdateMany, runUpgrade, runValidate, } from "../cli/commands/index.js";
 import { runContracts, } from "../cli/commands/contracts.js";
+import { resolveStartTaskInProgressStatus } from "./start-task-status.js";
 export { getActiveExtensionRegistrations, runActiveOnReadHooks, runActiveOnWriteHooks, } from "../core/extensions/index.js";
 export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic } from "../core/fs/fs-utils.js";
 export { appendHistoryEntry, createHistoryEntry } from "../core/history/history.js";
@@ -31,6 +45,13 @@ export { isTimestampLiteral, nowIso } from "../core/shared/time.js";
 export { listAllFrontMatter, locateItem, readLocatedItem } from "../core/store/item-store.js";
 export { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 export { readSettings } from "../core/store/settings.js";
+export { runAggregate, } from "../cli/commands/aggregate.js";
+export { CONTEXT_OUTPUT_VALUES, runContext, } from "../cli/commands/context.js";
+export { runGet, } from "../cli/commands/get.js";
+export { runList, } from "../cli/commands/list.js";
+export { NEXT_OUTPUT_VALUES, runNext, } from "../cli/commands/next.js";
+export { runSearch, } from "../cli/commands/search.js";
+export { runStats, } from "../cli/commands/stats.js";
 export { renderCalendarMarkdown, renderCalendarToon, resolveCalendarOutputFormat, runCalendar, } from "../cli/commands/calendar.js";
 export { renderGuideMarkdown, resolveGuideOutputFormat, runGuide, } from "../cli/commands/guide.js";
 export { runCompletion } from "../cli/commands/completion.js";
@@ -39,10 +60,291 @@ export { runDedupeAudit, } from "../cli/commands/dedupe-audit.js";
 export { runDedupeMerge, } from "../cli/commands/dedupe-merge.js";
 export { runNormalize } from "../cli/commands/normalize.js";
 export { runReindex } from "../cli/commands/reindex.js";
-export { runSearch } from "../cli/commands/search.js";
 export { loadCreateTemplateOptions, runTemplatesList, runTemplatesSave, runTemplatesShow, } from "../cli/commands/templates.js";
 export { runTestRunsList, runTestRunsLogs, runTestRunsResume, runTestRunsStatus, runTestRunsStop, } from "../cli/commands/test-runs.js";
 export { CONFIDENCE_TEXT_VALUES, DEPENDENCY_KIND_VALUES, BUILTIN_ITEM_TYPE_VALUES, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, RISK_VALUES, STATUS_VALUES, } from "../types/index.js";
+function splitClientMutationOptions(options) {
+    const { fullChangedFields, idOnly, ...runnerOptions } = options;
+    return {
+        ...(fullChangedFields === undefined ? {} : { fullChangedFields }),
+        ...(idOnly === undefined ? {} : { idOnly }),
+        options: runnerOptions,
+    };
+}
+/**
+ * Programmatic pm client for custom tools, CI jobs, bots, and embedded runtimes.
+ *
+ * Action execution shares the same process-wide extension activation queue used
+ * by MCP. Concurrent calls from one process are serialized across extension
+ * load, activation, dispatch, cleanup, and deactivate so active registries cannot
+ * interleave.
+ *
+ * Convenience methods accept command options only. Use {@link PmClient.run} for
+ * per-call runtime overrides such as `cwd`, `path`, or `noExtensions`.
+ */
+export class PmClient {
+    defaults;
+    /**
+     * Create a client with workspace, author, and extension-loading defaults.
+     */
+    constructor(options = {}) {
+        this.defaults = {
+            ...(options.pmRoot === undefined ? {} : { path: options.pmRoot }),
+            ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+            ...(options.author === undefined ? {} : { author: options.author }),
+            ...(options.noExtensions === undefined ? {} : { noExtensions: options.noExtensions }),
+        };
+    }
+    /**
+     * Run any native or extension-contributed action through the SDK dispatcher.
+     */
+    run(action, args = {}) {
+        return runAction({ ...this.defaults, ...args, action });
+    }
+    runTyped(action, args = {}) {
+        return this.run(action, args);
+    }
+    /**
+     * Return the same context snapshot produced by `pm context`.
+     */
+    context(options = {}) {
+        return this.runTyped("context", { options });
+    }
+    /**
+     * List items with the MCP/agent compact defaults.
+     */
+    list(options = {}) {
+        return this.runTyped("list", { options });
+    }
+    /**
+     * Search items with the MCP/agent compact defaults.
+     */
+    search(query, options = {}) {
+        return this.runTyped("search", { query, options });
+    }
+    /**
+     * Read one item by id.
+     */
+    get(id, options = {}) {
+        return this.runTyped("get", { id, options });
+    }
+    /**
+     * Return the ranked next-work recommendation produced by `pm next`.
+     */
+    next(options = {}) {
+        return this.runTyped("next", { options });
+    }
+    /**
+     * Group matching items with the same semantics as `pm aggregate`.
+     */
+    aggregate(options = {}) {
+        return this.runTyped("aggregate", { options });
+    }
+    /**
+     * Return project tracker statistics with the same sections as `pm stats`.
+     */
+    stats(options = {}) {
+        return this.runTyped("stats", { options });
+    }
+    /**
+     * Create an item using the same mutation path as `pm create`.
+     */
+    create(options = {}) {
+        return this.run("create", splitClientMutationOptions(options));
+    }
+    /**
+     * Update an item using the same mutation path as `pm update`.
+     */
+    update(id, options = {}) {
+        return this.run("update", { id, ...splitClientMutationOptions(options) });
+    }
+    /**
+     * Close an item using the same mutation path as `pm close`.
+     */
+    close(id, reason, options = {}) {
+        return this.run("close", { id, reason, ...splitClientMutationOptions(options) });
+    }
+    /**
+     * Claim an item using the same mutation path as `pm claim`.
+     */
+    claim(id, options = {}) {
+        return this.run("claim", { id, ...splitClientMutationOptions(options) });
+    }
+    /**
+     * Release an item's active claim using the same mutation path as `pm release`.
+     */
+    release(id, options = {}) {
+        return this.run("release", { id, ...splitClientMutationOptions(options) });
+    }
+    /**
+     * Copy an item using the same mutation path as `pm copy`.
+     */
+    copy(id, options = {}) {
+        return this.run("copy", { id, ...splitClientMutationOptions(options) });
+    }
+    /**
+     * Delete an item using the same mutation path as `pm delete`.
+     */
+    delete(id, options = {}) {
+        return this.run("delete", { id, ...splitClientMutationOptions(options) });
+    }
+    /**
+     * Restore an item to a history version or timestamp using `pm restore`.
+     */
+    restore(id, target, options = {}) {
+        const { fullChangedFields, idOnly, ...runnerOptions } = options;
+        return this.run("restore", {
+            ...(fullChangedFields === undefined ? {} : { fullChangedFields }),
+            ...(idOnly === undefined ? {} : { idOnly }),
+            id,
+            options: { ...runnerOptions, target },
+        });
+    }
+    /**
+     * Set, clear, or read workspace focus using the same path as `pm focus`.
+     */
+    focus(id, options = {}) {
+        return this.run("focus", { ...(id === undefined ? {} : { id }), ...splitClientMutationOptions(options) });
+    }
+    /**
+     * Claim an item and transition it to the workspace in-progress status.
+     */
+    startTask(id, options = {}) {
+        return this.run("start-task", { id, ...splitClientMutationOptions(options) });
+    }
+    /**
+     * Move an item back to the workspace open status and release the claim.
+     */
+    pauseTask(id, options = {}) {
+        return this.run("pause-task", { id, ...splitClientMutationOptions(options) });
+    }
+    /**
+     * Close an item and release its active assignment.
+     */
+    closeTask(id, reason, options = {}) {
+        return this.run("close-task", { id, reason, ...splitClientMutationOptions(options) });
+    }
+}
+/**
+ * Return the same context snapshot produced by `pm context` without constructing
+ * a reusable client.
+ */
+export function context(options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).context(options);
+}
+/**
+ * List items with the MCP/agent compact defaults without constructing a
+ * reusable client.
+ */
+export function list(options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).list(options);
+}
+/**
+ * Search items with the MCP/agent compact defaults without constructing a
+ * reusable client.
+ */
+export function search(query, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).search(query, options);
+}
+/**
+ * Read one item by id without constructing a reusable client.
+ */
+export function get(id, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).get(id, options);
+}
+/**
+ * Return the ranked next-work recommendation produced by `pm next` without
+ * constructing a reusable client.
+ */
+export function next(options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).next(options);
+}
+/**
+ * Group matching items with the same semantics as `pm aggregate` without
+ * constructing a reusable client.
+ */
+export function aggregate(options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).aggregate(options);
+}
+/**
+ * Return project tracker statistics with the same sections as `pm stats`
+ * without constructing a reusable client.
+ */
+export function stats(options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).stats(options);
+}
+/**
+ * Create an item without constructing a reusable client.
+ */
+export function create(options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).create(options);
+}
+/**
+ * Update an item without constructing a reusable client.
+ */
+export function update(id, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).update(id, options);
+}
+/**
+ * Close an item without constructing a reusable client.
+ */
+export function close(id, reason, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).close(id, reason, options);
+}
+/**
+ * Claim an item without constructing a reusable client.
+ */
+export function claim(id, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).claim(id, options);
+}
+/**
+ * Release an item's active claim without constructing a reusable client.
+ */
+export function release(id, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).release(id, options);
+}
+/**
+ * Copy an item without constructing a reusable client.
+ */
+export function copy(id, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).copy(id, options);
+}
+/**
+ * Delete an item without constructing a reusable client.
+ */
+export function deleteItem(id, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).delete(id, options);
+}
+/**
+ * Restore an item without constructing a reusable client.
+ */
+export function restore(id, target, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).restore(id, target, options);
+}
+/**
+ * Set, clear, or read workspace focus without constructing a reusable client.
+ */
+export function focus(id, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).focus(id, options);
+}
+/**
+ * Claim an item and transition it to in-progress without constructing a client.
+ */
+export function startTask(id, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).startTask(id, options);
+}
+/**
+ * Move an item to open and release it without constructing a client.
+ */
+export function pauseTask(id, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).pauseTask(id, options);
+}
+/**
+ * Close an item and release its active assignment without constructing a client.
+ */
+export function closeTask(id, reason, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).closeTask(id, reason, options);
+}
 /**
  * Process-lifetime memo of activated extension registrations, keyed by resolved
  * pm root + cwd + extension settings. `getWorkspaceContracts` is frequently
@@ -57,8 +359,6 @@ export { CONFIDENCE_TEXT_VALUES, DEPENDENCY_KIND_VALUES, BUILTIN_ITEM_TYPE_VALUE
  * toggling extensions or editing settings. Settings themselves are re-read on
  * every call — only the extension load+activate step is memoized.
  */
-const WORKSPACE_CONTRACTS_CACHE_LIMIT = 50;
-const workspaceExtensionRegistrationsCache = new Map();
 function buildWorkspaceExtensionRegistrationsCacheKey(pmRoot, settings, cwd) {
     return JSON.stringify([
         path.resolve(pmRoot),
@@ -68,27 +368,9 @@ function buildWorkspaceExtensionRegistrationsCacheKey(pmRoot, settings, cwd) {
         settings.extensions.policy,
     ]);
 }
-/**
- * Drop all memoized workspace extension registrations so the next
- * `getWorkspaceContracts` call re-loads and re-activates extensions from disk.
- * Long-lived hosts should call this after any extension or settings mutation.
- */
-export function clearWorkspaceContractsCache() {
-    workspaceExtensionRegistrationsCache.clear();
-}
 async function resolveWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     const cacheKey = buildWorkspaceExtensionRegistrationsCacheKey(pmRoot, settings, cwd);
-    const cached = workspaceExtensionRegistrationsCache.get(cacheKey);
-    if (cached !== undefined) {
-        return cached;
-    }
-    if (workspaceExtensionRegistrationsCache.size >= WORKSPACE_CONTRACTS_CACHE_LIMIT) {
-        const oldestKey = workspaceExtensionRegistrationsCache.keys().next().value;
-        workspaceExtensionRegistrationsCache.delete(oldestKey);
-    }
-    const registrations = loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd);
-    workspaceExtensionRegistrationsCache.set(cacheKey, registrations);
-    return registrations;
+    return memoizeWorkspaceExtensionRegistrations(cacheKey, () => loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd));
 }
 /**
  * Implements get workspace contracts for the public runtime surface of this module.
@@ -124,6 +406,1079 @@ export async function getContracts(pmRootOrOptions, options = {}) {
     };
     return runContracts(resolvedOptions, global);
 }
+function readString(args, key) {
+    const value = args[key];
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function readScalarString(args, key) {
+    const value = args[key];
+    if (typeof value === "string") {
+        return value.trim().length > 0 ? value : undefined;
+    }
+    return typeof value === "number" && Number.isFinite(value) ? String(value) : undefined;
+}
+function readScalarStringAllowBlank(args, key) {
+    const value = args[key];
+    if (typeof value === "string") {
+        return value;
+    }
+    return typeof value === "number" && Number.isFinite(value) ? String(value) : undefined;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Read a required non-empty string from an action argument bag.
+ */
+export function readRequiredString(args, key) {
+    const value = readString(args, key);
+    if (!value) {
+        throw new PmCliError(`Missing required argument: ${key}`, 64);
+    }
+    return value;
+}
+function globalOptions(args) {
+    return {
+        json: true,
+        quiet: true,
+        path: readString(args, "path"),
+        noExtensions: args.noExtensions === true || args.no_extensions === true,
+        noPager: true,
+    };
+}
+const ARRAY_TO_CSV_FIELDS = new Set(["tags", "blockedBy", "blocked_by", "skills", "fields"]);
+const SCALAR_TO_ARRAY_FIELDS = new Set([
+    "comment",
+    "note",
+    "learning",
+    "reminder",
+    "event",
+    "dep",
+    "depRemove",
+    "dep_remove",
+    "file",
+    "doc",
+    "test",
+    "unset",
+    "addGlob",
+    "add_glob",
+    "migrate",
+    "envSet",
+    "env_set",
+    "envClear",
+    "env_clear",
+]);
+// Actions where the linked-resource fields `add` and `remove` are string[] arrays.
+// For other actions (comments/notes/learnings) `add` and `remove` are scalar strings
+// and must NOT be auto-promoted.
+const ARRAY_ADD_REMOVE_ACTIONS = new Set([
+    "files",
+    "files-discover",
+    "docs",
+    "test",
+    "test-all",
+]);
+const LIFECYCLE_AUTHOR_ALIAS_ACTIONS = new Set([
+    "claim",
+    "release",
+    "start-task",
+    "pause-task",
+    "close-task",
+]);
+function normalizeMcpOptionsArrays(options, action) {
+    const result = {};
+    const promoteAddRemove = action !== undefined && ARRAY_ADD_REMOVE_ACTIONS.has(action);
+    for (const [key, value] of Object.entries(options)) {
+        if (Array.isArray(value) && ARRAY_TO_CSV_FIELDS.has(key)) {
+            result[key] = value.join(",");
+            continue;
+        }
+        if (typeof value === "string" && SCALAR_TO_ARRAY_FIELDS.has(key)) {
+            result[key] = [value];
+            continue;
+        }
+        if (typeof value === "string" && promoteAddRemove && (key === "add" || key === "remove")) {
+            result[key] = [value];
+            continue;
+        }
+        result[key] = value;
+    }
+    return result;
+}
+function optionsWithAuthor(args, action) {
+    const baseOptions = asRecordClone(args.options);
+    const hoistedTopLevel = {};
+    const hoistKey = (key) => {
+        if (baseOptions[key] !== undefined || args[key] === undefined) {
+            return;
+        }
+        hoistedTopLevel[key] = args[key];
+    };
+    if (action === "list") {
+        hoistKey("status");
+        hoistKey("type");
+        hoistKey("tag");
+        hoistKey("priority");
+        hoistKey("limit");
+        hoistKey("offset");
+    }
+    else if (action === "search") {
+        hoistKey("mode");
+        hoistKey("status");
+        hoistKey("type");
+        hoistKey("tag");
+        hoistKey("priority");
+        hoistKey("limit");
+    }
+    else if (action === "create") {
+        hoistKey("title");
+        hoistKey("type");
+        hoistKey("status");
+        hoistKey("description");
+        hoistKey("body");
+        hoistKey("priority");
+        hoistKey("tags");
+        hoistKey("parent");
+        hoistKey("createMode");
+        hoistKey("create_mode");
+        hoistKey("allowMissingParent");
+    }
+    else if (action === "close") {
+        hoistKey("duplicateOf");
+    }
+    else if (action === "append") {
+        // pm-7u9j: the narrow pm_append tool declares `body` top-level; runAppend
+        // reads it from options, so hoist unless options.body already wins.
+        // (pm_schema/pm_config top-level args are consumed directly by runAction's
+        // schema/config cases, which read args before options — no hoist needed.)
+        hoistKey("body");
+    }
+    const options = normalizeMcpOptionsArrays({ ...hoistedTopLevel, ...baseOptions }, action);
+    const author = readString(args, "author");
+    const authorFromAssignee = action !== undefined && LIFECYCLE_AUTHOR_ALIAS_ACTIONS.has(action) ? readString(args, "assignee") ?? readString(options, "assignee") : undefined;
+    if (author && options.author === undefined) {
+        return { ...options, author };
+    }
+    if (authorFromAssignee && options.author === undefined) {
+        return { ...options, author: authorFromAssignee };
+    }
+    return options;
+}
+// GH-170 (pm-pfnx): the narrow pm_files/pm_docs tools spell the CLI --note flag
+// as `addNote` (the shared `note` parameter is the array-typed create/update
+// note seed). Translate it onto the runner's `note` option; an explicit
+// options.note (pm_run callers) wins.
+function withAddNoteOption(options) {
+    if (options.addNote === undefined) {
+        return options;
+    }
+    const next = { ...options };
+    if (next.note === undefined && typeof next.addNote === "string") {
+        next.note = next.addNote;
+    }
+    delete next.addNote;
+    return next;
+}
+function withFilesDiscoveryOptions(options) {
+    const next = { ...options };
+    if (next.discoveryNote !== undefined && next.note === undefined && typeof next.discoveryNote === "string") {
+        next.note = next.discoveryNote;
+    }
+    delete next.discover;
+    delete next.discoveryNote;
+    return next;
+}
+function normalizeActionName(value) {
+    const chunks = [];
+    let lastWasSeparator = true;
+    for (const character of value.trim().toLowerCase()) {
+        const isAlphaNumeric = (character >= "a" && character <= "z") || (character >= "0" && character <= "9");
+        if (isAlphaNumeric) {
+            chunks.push(character);
+            lastWasSeparator = false;
+            continue;
+        }
+        if (!lastWasSeparator) {
+            chunks.push("-");
+            lastWasSeparator = true;
+        }
+    }
+    if (chunks.at(-1) === "-") {
+        chunks.pop();
+    }
+    return chunks.join("");
+}
+function normalizeCommandPath(value) {
+    return value.trim().toLowerCase().split(/\s+/).filter(Boolean).join(" ");
+}
+function readStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((entry) => String(entry)).filter((entry) => entry.length > 0);
+}
+function extensionOptionsFromArgs(args, options) {
+    const reserved = new Set([
+        "action",
+        "args",
+        "author",
+        "cwd",
+        "fullChangedFields",
+        "id",
+        "options",
+        "path",
+        "query",
+        "reason",
+        "target",
+    ]);
+    const passthrough = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (!reserved.has(key)) {
+            passthrough[key] = value;
+        }
+    }
+    const normalizedOptions = { ...passthrough, ...options };
+    delete normalizedOptions.args;
+    return normalizedOptions;
+}
+// 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 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 () => explicitCwd === undefined
+        ? await withActiveExtensionsExclusively(global, resolutionCwd, run)
+        : await withCwd(explicitCwd, () => withActiveExtensionsExclusively(global, resolutionCwd, run)));
+}
+/**
+ * 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. MCP and
+ * PmClient callers reload + reactivate 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) {
+        resetActiveExtensionRegistries();
+        return run(null);
+    }
+    const pmRoot = resolvePmRoot(cwd, global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        resetActiveExtensionRegistries();
+        return run(null);
+    }
+    let active = null;
+    let activated;
+    try {
+        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);
+        setActiveExtensionPreflight(activationResult.preflight);
+        setActiveExtensionServices(activationResult.services);
+        setActiveExtensionRenderers(activationResult.renderers);
+        setActiveExtensionRegistrations(activationResult.registrations);
+        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-sdk] extension activation failed; continuing without active extensions:", error);
+    }
+    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
+        // (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);
+        }
+    }
+}
+/**
+ * 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 {
+        return await run();
+    }
+    finally {
+        process.chdir(previous);
+    }
+}
+/**
+ * Mutation tools (create/update/close/append/update-many) return a verbose
+ * `changed_fields` array. On the agent path we drop it to a `changed_field_count`
+ * by default for token efficiency, restoring the full array only when the caller
+ * explicitly passes the MCP-level fullChangedFields=true control. Mutation options
+ * 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 } };
+}
+function mutationListOptions(options) {
+    return {
+        type: readScalarString(options, "filterType"),
+        tag: readScalarString(options, "filterTag"),
+        priority: readScalarString(options, "filterPriority"),
+        deadlineBefore: readScalarString(options, "filterDeadlineBefore"),
+        deadlineAfter: readScalarString(options, "filterDeadlineAfter"),
+        updatedAfter: readScalarString(options, "filterUpdatedAfter"),
+        updatedBefore: readScalarString(options, "filterUpdatedBefore"),
+        createdAfter: readScalarString(options, "filterCreatedAfter"),
+        createdBefore: readScalarString(options, "filterCreatedBefore"),
+        ids: readScalarStringAllowBlank(options, "ids"),
+        assignee: readScalarString(options, "filterAssignee"),
+        assigneeFilter: readScalarString(options, "filterAssigneeFilter") ?? readScalarString(options, "filterAssignee_filter"),
+        parent: readScalarString(options, "filterParent"),
+        sprint: readScalarString(options, "filterSprint"),
+        release: readScalarString(options, "filterRelease"),
+        limit: readScalarString(options, "limit"),
+        offset: readScalarString(options, "offset"),
+    };
+}
+function closeManyOptionsFromFlat(options) {
+    return {
+        status: readString(options, "filterStatus"),
+        list: isRecord(options.list) ? normalizeListOptions(options.list) : mutationListOptions(options),
+        reason: readString(options, "reason"),
+        resolution: readString(options, "resolution"),
+        expectedResult: readString(options, "expectedResult") ?? readString(options, "expected_result") ?? readString(options, "expected"),
+        actualResult: readString(options, "actualResult") ?? readString(options, "actual_result") ?? readString(options, "actual"),
+        validateClose: readString(options, "validateClose") ?? readString(options, "validate_close"),
+        author: readString(options, "author"),
+        message: readString(options, "message"),
+        force: options.force === true ? true : undefined,
+        dryRun: options.dryRun === true || options.dry_run === true ? true : undefined,
+        rollback: readString(options, "rollback"),
+        checkpoint: options.checkpoint === false || options.noCheckpoint === true || options.no_checkpoint === true ? false : undefined,
+    };
+}
+const UPDATE_MANY_FLAT_CONTROL_KEYS = new Set([
+    "filterStatus",
+    "filterType",
+    "filterTag",
+    "filterPriority",
+    "filterDeadlineBefore",
+    "filterDeadlineAfter",
+    "filterUpdatedAfter",
+    "filterUpdatedBefore",
+    "filterCreatedAfter",
+    "filterCreatedBefore",
+    "filterAssignee",
+    "filterAssigneeFilter",
+    "filterAssignee_filter",
+    "filterParent",
+    "filterSprint",
+    "filterRelease",
+    "ids",
+    "list",
+    "update",
+    "limit",
+    "offset",
+    "dryRun",
+    "dry_run",
+    "rollback",
+    "checkpoint",
+    "noCheckpoint",
+    "no_checkpoint",
+]);
+function updateManyUpdateOptionsFromFlat(options) {
+    const update = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (UPDATE_MANY_FLAT_CONTROL_KEYS.has(key)) {
+            continue;
+        }
+        update[key] = value;
+    }
+    return normalizeMcpUpdateOptions(update);
+}
+function normalizeMcpUpdateOptions(options) {
+    const normalizedInput = normalizeMcpOptionsArrays(options, "update-many");
+    for (const contract of UPDATE_COMMANDER_STRING_OPTION_CONTRACTS) {
+        for (const key of contract.keys) {
+            const value = normalizedInput[key];
+            if (typeof value === "number" && Number.isFinite(value)) {
+                normalizedInput[key] = String(value);
+            }
+        }
+    }
+    return normalizeUpdateOptions(normalizedInput);
+}
+function updateManyOptionsFromFlat(options) {
+    if (isRecord(options.list) || isRecord(options.update)) {
+        const updateSource = isRecord(options.update) ? options.update : updateManyUpdateOptionsFromFlat(options);
+        return {
+            status: readScalarString(options, "filterStatus"),
+            list: isRecord(options.list) ? normalizeListOptions(options.list) : mutationListOptions(options),
+            update: normalizeMcpUpdateOptions(updateSource),
+            dryRun: options.dryRun === true || options.dry_run === true ? true : undefined,
+            rollback: readString(options, "rollback"),
+            checkpoint: options.checkpoint === false || options.noCheckpoint === true || options.no_checkpoint === true ? false : undefined,
+        };
+    }
+    return {
+        status: readScalarString(options, "filterStatus"),
+        list: mutationListOptions(options),
+        update: updateManyUpdateOptionsFromFlat(options),
+        dryRun: options.dryRun === true || options.dry_run === true ? true : undefined,
+        rollback: readString(options, "rollback"),
+        checkpoint: options.checkpoint === false || options.noCheckpoint === true || options.no_checkpoint === true ? false : undefined,
+    };
+}
+const WORKSPACE_CONTRACTS_CACHE_PRESERVING_ACTIONS = new Set([
+    "activity",
+    "aggregate",
+    "context",
+    "contracts",
+    "deps",
+    "files-discover",
+    "get",
+    "health",
+    "history",
+    "list",
+    "next",
+    "search",
+    "stats",
+    "telemetry",
+    "validate",
+]);
+const LIST_ACTION_ALIASES = {
+    "list-all": { action: "list", options: { excludeTerminal: false } },
+    "list-draft": { action: "list", options: { status: "draft", excludeTerminal: false } },
+    "list-open": { action: "list", options: { status: "open", excludeTerminal: false } },
+    "list-in-progress": { action: "list", options: { status: "in_progress", excludeTerminal: false } },
+    "list-blocked": { action: "list", options: { status: "blocked", excludeTerminal: false } },
+    "list-closed": { action: "list", options: { status: "closed", excludeTerminal: false } },
+    "list-canceled": { action: "list", options: { status: "canceled", excludeTerminal: false } },
+};
+const EXTENSION_ACTION_ALIASES = {
+    "extension-init": { action: "extension", options: { init: true } },
+    "extension-install": { action: "extension", options: { install: true } },
+    "extension-uninstall": { action: "extension", options: { uninstall: true } },
+    "extension-explore": { action: "extension", options: { explore: true } },
+    "extension-manage": { action: "extension", options: { manage: true } },
+    "extension-describe": { action: "extension", options: { describe: true } },
+    "extension-reload": { action: "extension", options: { reload: true } },
+    "extension-doctor": { action: "extension", options: { doctor: true } },
+    "extension-catalog": { action: "extension", options: { catalog: true } },
+    "extension-adopt": { action: "extension", options: { adopt: true } },
+    "extension-adopt-all": { action: "extension", options: { adoptAll: true } },
+    "extension-activate": { action: "extension", options: { activate: true } },
+    "extension-deactivate": { action: "extension", options: { deactivate: true } },
+};
+const PACKAGE_ACTION_ALIASES = {
+    "package-init": { action: "package", options: { init: true, vocabulary: "package" } },
+    "package-install": { action: "package", options: { install: true, vocabulary: "package" } },
+    "package-uninstall": { action: "package", options: { uninstall: true, vocabulary: "package" } },
+    "package-explore": { action: "package", options: { explore: true, vocabulary: "package" } },
+    "package-manage": { action: "package", options: { manage: true, vocabulary: "package" } },
+    "package-describe": { action: "package", options: { describe: true, vocabulary: "package" } },
+    "package-reload": { action: "package", options: { reload: true, vocabulary: "package" } },
+    "package-doctor": { action: "package", options: { doctor: true, vocabulary: "package" } },
+    "package-catalog": { action: "package", options: { catalog: true, vocabulary: "package" } },
+    "package-adopt": { action: "package", options: { adopt: true, vocabulary: "package" } },
+    "package-adopt-all": { action: "package", options: { adoptAll: true, vocabulary: "package" } },
+    "package-activate": { action: "package", options: { activate: true, vocabulary: "package" } },
+    "package-deactivate": { action: "package", options: { deactivate: true, vocabulary: "package" } },
+};
+const SDK_ACTION_ALIASES = {
+    ctx: { action: "context" },
+    ...LIST_ACTION_ALIASES,
+    ...EXTENSION_ACTION_ALIASES,
+    ...PACKAGE_ACTION_ALIASES,
+};
+function resolveSdkActionInput(args) {
+    const rawAction = readRequiredString(args, "action");
+    const normalizedAction = normalizeActionName(rawAction);
+    const alias = getOwnHandler(SDK_ACTION_ALIASES, normalizedAction);
+    const action = alias?.action ?? normalizedAction;
+    const resolvedArgs = { ...args, action };
+    if (alias?.options !== undefined) {
+        resolvedArgs.options = { ...alias.options, ...asRecordClone(args.options) };
+    }
+    return { action, args: resolvedArgs };
+}
+function shouldInvalidateWorkspaceContractsCacheAfterAction(action) {
+    return !WORKSPACE_CONTRACTS_CACHE_PRESERVING_ACTIONS.has(normalizeActionName(action));
+}
+/**
+ * Execute one native or extension-contributed pm action in-process.
+ */
+export async function runAction(args) {
+    const resolved = resolveSdkActionInput(args);
+    const global = globalOptions(resolved.args);
+    const invalidateWorkspaceContractsCache = shouldInvalidateWorkspaceContractsCacheAfterAction(resolved.action);
+    // 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(resolved.args, "cwd");
+    const resolutionCwd = explicitCwd ?? process.cwd();
+    try {
+        return await withActiveExtensions(global, explicitCwd, resolutionCwd, (activeExtensions) => dispatchAction(resolved.action, resolved.args, global, activeExtensions));
+    }
+    finally {
+        if (invalidateWorkspaceContractsCache) {
+            clearWorkspaceContractsCache();
+        }
+    }
+}
+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") ?? readString(listOptions, "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";
+        }
+    }
+    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);
+        }
+        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);
+        }
+        return parsed;
+    }
+    return undefined;
+}
+function parseMcpIntegerPrefix(value, label) {
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || !Number.isInteger(value)) {
+            throw new PmCliError(`${label} must be a finite integer.`, 64);
+        }
+        return value;
+    }
+    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);
+        }
+        const parsed = Number.parseInt(trimmed, 10);
+        if (!Number.isInteger(parsed)) {
+            throw new PmCliError(`${label} must be a finite integer.`, 64);
+        }
+        return parsed;
+    }
+    return undefined;
+}
+function runMcpPlanAction(ctx) {
+    const subcommand = readString(ctx.args, "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);
+        }
+        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 });
+}
+async function runMcpRestoreAction(ctx) {
+    const { changedFields, idOnly, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
+    const target = readString(runnerOptions, "target") ?? readRequiredString(ctx.args, "target");
+    return projectMutationResult(await runRestore(requireMcpItemId(ctx, runnerOptions), target, runnerOptions, ctx.global), {
+        changedFields,
+        idOnly,
+    });
+}
+function withoutLifecycleAssigneeAlias(options) {
+    const updateOptions = { ...options };
+    delete updateOptions.assignee;
+    return updateOptions;
+}
+async function runMcpStartTaskAction(ctx) {
+    const pmRoot = resolvePmRoot(process.cwd(), ctx.global.path);
+    const settings = await readSettings(pmRoot);
+    const inProgressStatus = resolveStartTaskInProgressStatus(resolveRuntimeStatusRegistry(settings.schema));
+    const id = requireMcpItemId(ctx);
+    const claimResult = await runClaim(id, ctx.force, ctx.global, ctx.options);
+    const updateResult = await runUpdate(id, { ...withoutLifecycleAssigneeAlias(ctx.options), status: inProgressStatus, force: ctx.force }, ctx.global);
+    return { id, action: "start_task", claim: claimResult, update: updateResult };
+}
+async function runMcpPauseTaskAction(ctx) {
+    const pmRoot = resolvePmRoot(process.cwd(), ctx.global.path);
+    const settings = await readSettings(pmRoot);
+    const id = requireMcpItemId(ctx);
+    const openStatus = resolveRuntimeStatusRegistry(settings.schema).open_status;
+    const updateResult = await runUpdate(id, { ...withoutLifecycleAssigneeAlias(ctx.options), status: openStatus, force: ctx.force }, ctx.global);
+    const releaseResult = await runRelease(id, ctx.force, ctx.global, ctx.options);
+    return { id, action: "pause_task", update: updateResult, release: releaseResult };
+}
+async function runMcpCloseTaskAction(ctx) {
+    const id = requireMcpItemId(ctx);
+    const closeReason = readString(ctx.args, "reason") ??
+        readString(ctx.args, "text") ??
+        readString(ctx.options, "reason") ??
+        readString(ctx.options, "text");
+    const closeResult = await runClose(id, closeReason, { ...ctx.options, force: ctx.force }, ctx.global);
+    const releaseResult = await runRelease(id, ctx.force, ctx.global, ctx.options);
+    return { id, action: "close_task", close: closeResult, release: releaseResult };
+}
+const SDK_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,
+    restore: runMcpRestoreAction,
+    claim: (ctx) => runClaim(requireMcpItemId(ctx), ctx.force, ctx.global, ctx.options),
+    release: (ctx) => runRelease(requireMcpItemId(ctx), ctx.force, ctx.global, ctx.options),
+    "start-task": runMcpStartTaskAction,
+    "pause-task": runMcpPauseTaskAction,
+    "close-task": runMcpCloseTaskAction,
+    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),
+    package: (ctx) => runExtension(readMcpTarget(ctx), ctx.options, ctx.global),
+    install: (ctx) => runExtension(readMcpTarget(ctx), { ...ctx.options, install: true }, 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 || options.force === true,
+        global,
+        activeExtensions,
+    };
+    const handler = getOwnHandler(SDK_ACTION_HANDLERS, action);
+    return handler ? handler(ctx) : dispatchActiveExtensionAction(action, args, options, global, activeExtensions);
+}
+const actionRunnerTestHooks = {
+    closeManyOptionsFromFlat,
+    extensionOptionsFromArgs,
+    globalOptions,
+    mutationListOptions,
+    normalizeActionName,
+    normalizeCommandPath,
+    normalizeMcpUpdateOptions,
+    normalizeMcpOptionsArrays,
+    optionsWithAuthor,
+    readRequiredString,
+    readScalarString,
+    readScalarStringAllowBlank,
+    readStringArray,
+    updateManyOptionsFromFlat,
+    withAddNoteOption,
+    withFilesDiscoveryOptions,
+    withMutationCompaction,
+};
+if (process.env.NODE_ENV === "test" || process.env.VITEST !== undefined || process.env.VITEST_WORKER_ID !== undefined) {
+    globalThis.__pmCliActionRunnerTestHooks = actionRunnerTestHooks;
+}
 async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     const loadResult = await loadExtensions({
         pmRoot,
@@ -132,7 +1487,17 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
         noExtensions: false,
     });
     const activationResult = await activateExtensions(loadResult);
-    return activationResult.registrations;
+    try {
+        return activationResult.registrations;
+    }
+    finally {
+        try {
+            await deactivateExtensions(loadResult, activationResult);
+        }
+        catch {
+            // Workspace contract reads should stay best-effort even if teardown itself fails.
+        }
+    }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=9ed0f12b-4f84-58a2-86c7-aff1a8b86f0a
+//# debugId=89db1e15-b152-57e2-910d-64ed77eb540b