@unbrained/pm-cli 2026.5.24 → 2026.5.27

package/docs/COMMANDS.md

@@ -6,15 +6,13 @@ This is a task-oriented command guide. For exact flags, use runtime help because
 pm <command> --help
 pm <command> --help --json
 pm contracts --command <command> --flags-only --json
-pm install guide-shell --project
-pm guide commands --depth standard
 ```
 
 ## Agent Quick Context
 
 - Prefer `pm context`, `pm search`, and narrow list commands before mutation.
 - Prefer TOON for reading and `--json` for strict parsing.
-- Use `pm install guide-shell --project` before `pm guide <topic>` when local docs routing is needed.
+- Use the [guide topic map](README.md#guide-topic-map) when optional `pm guide` local docs routing is needed.
 - Use `pm contracts` for machine clients.
 - Every mutation writes history.
 
@@ -82,6 +80,14 @@ pm dedupe-audit --mode parent_scope --limit 20
 
 Use `context` first for a compact active-work snapshot. Use `search` when the request names a concept, component, or prior issue.
 
+`--sort` accepts `priority|deadline|updated_at|created_at|title|parent`, plus the convenience aliases `updated` (→ `updated_at`) and `created` (→ `created_at`):
+
+```bash
+pm list-all --sort updated --order desc
+```
+
+When a flag is rejected with `Unknown option`, the error guidance now suggests the nearest supported flag (including abbreviations like `--desc` → `--description`) and notes when the flag is valid on a different command (for example `--type` on `test-all` points to `create`/`list`).
+
 ## Create and Update
 
 Shortest agent-friendly create (positional title + defaults to `Task` type):
@@ -121,6 +127,8 @@ pm create \
   --message "Create restore replay issue"
 ```
 
+Repeated singular/plural list flags now accumulate, so `--tag a --tag b` is equivalent to `--tags a,b` (the same holds for `--status` and `--fields` on read commands). Earlier versions silently kept only the last value.
+
 Update existing work:
 
 ```bash
@@ -130,6 +138,14 @@ pm update <id> --parent <parent-id>
 pm append <id> --body "Detailed implementation notes."
 ```
 
+Mutation commands (`create`/`update`/`close`/`append`/...) echo a `changed_fields` array. In high-volume agent loops that array is mostly redundant with the item echo above it, so pass the global `--no-changed-fields` flag to replace it with a compact `changed_field_count`:
+
+```bash
+pm --no-changed-fields create "Probe item"   # output keeps changed_field_count, drops the array
+```
+
+Over MCP the mutation tools (`pm_create`/`pm_update`/`pm_close`/`pm_run` append/update-many) are compact by default; pass `options.full=true` to restore the full `changed_fields` delta.
+
 ## Templates
 
 After `pm install templates --project`, `pm templates` lists both saved templates and built-in starters:

package/docs/CONFIGURATION.md

@@ -21,6 +21,21 @@ pm config project set item-format --format toon
 pm config project set test-result-tracking --policy enabled
 ```
 
+`config set <key> <value>` also accepts the value as a positional argument; pm routes
+it to the right typed flag based on the key (so `--policy`/`--format`/`--criterion`
+remain optional for single values):
+
+```bash
+pm config set telemetry-tracking off          # off|on|true|false map to disabled|enabled
+pm config set item-format toon                # same as --format toon
+pm config set governance-preset strict        # same as --policy strict
+pm config set definition-of-done "Tests pass" # same as --criterion "Tests pass"
+```
+
+The `context` key has no single value and still uses `--default-depth`,
+`--activity-limit`, `--stale-threshold-days`, and `--section-<name>` flags. Use
+`--criterion` (repeatable) to set more than one criteria-list value at once.
+
 Scopes:
 
 - `project` updates `.agents/pm/settings.json`.

package/docs/EXTENSIONS.md

@@ -130,44 +130,10 @@ export default defineExtension({
 
 ## Extension Manifest
 
-Manifest v1 is supported:
+Runnable manifest examples are the source of truth:
 
-```json
-{
-  "name": "my-ext",
-  "version": "0.1.0",
-  "entry": "./index.js",
-  "priority": 100,
-  "capabilities": ["commands"]
-}
-```
-
-Manifest v2 is recommended when governance, trust, or sandbox metadata matters:
-
-```json
-{
-  "name": "my-ext",
-  "version": "0.2.0",
-  "entry": "./index.js",
-  "priority": 100,
-  "manifest_version": 2,
-  "trusted": true,
-  "provenance": {
-    "source": "github://org/repo/path",
-    "verified": true
-  },
-  "sandbox_profile": "restricted",
-  "permissions": {
-    "fs_read": true,
-    "fs_write": false,
-    "network": false,
-    "env_read": true,
-    "env_write": false,
-    "process_spawn": false
-  },
-  "capabilities": ["commands", "schema"]
-}
-```
+- [starter extension manifest](examples/starter-extension/manifest.json)
+- [policy-restricted manifest](examples/policy-restricted-extension/manifest.json)
 
 Rules:
 
@@ -190,32 +156,7 @@ Supported capabilities:
 
 ## Governance Policy
 
-Governance policy is configured in `settings.json` under `extensions.policy`:
-
-```json
-{
-  "extensions": {
-    "policy": {
-      "mode": "enforce",
-      "trust_mode": "warn",
-      "require_provenance": true,
-      "default_sandbox_profile": "restricted",
-      "allowed_extensions": [],
-      "blocked_extensions": [],
-      "allowed_capabilities": [],
-      "blocked_capabilities": ["services"],
-      "allowed_surfaces": [],
-      "blocked_surfaces": ["commands.override"],
-      "allowed_commands": [],
-      "blocked_commands": ["dangerous command"],
-      "allowed_actions": [],
-      "blocked_actions": [],
-      "allowed_services": [],
-      "blocked_services": []
-    }
-  }
-}
-```
+Governance policy is configured in `settings.json` under `extensions.policy`. The runnable [policy-restricted example](examples/policy-restricted-extension/README.md) owns the complete policy snippet and expected behavior.
 
 Policy modes:
 

package/docs/RELEASING.md

@@ -53,7 +53,7 @@ Policy:
 - release at most once per UTC day by default
 - same-day follow-up release (`YYYY.M.D-N`) is manual-only via `allow_same_day_release=true`
 - release preparation must pass all quality and compatibility gates before commit+tag push
-- `CHANGELOG.pm.md` is generated by the latest npm `pm-changelog` package (`pm install npm:pm-changelog --project`, then `pm changelog generate`) from closed tracker items and checked in CI; do not edit it by hand
+- `CHANGELOG.md` is generated by the latest npm `pm-changelog` package (`pm install npm:pm-changelog --project`, then `pm changelog generate --mode replace --all-release-tags`) from closed tracker items across git release tag windows and checked in CI; do not edit it by hand
 - external Sentry checks run when a Sentry token is configured; local maintainers should run private reliability checks separately and keep raw operational details in ignored local notes
 - after creating and pushing a new tag, auto-release dispatches `.github/workflows/release.yml` with that tag and waits for the publish workflow to finish, because GitHub does not start normal push/tag workflows from `GITHUB_TOKEN` pushes
 
@@ -66,13 +66,13 @@ node scripts/release/run-release-pipeline.mjs
 The pipeline performs:
 
 1. change detection + one-release-per-day guard
-2. version bump + changelog promotion from `[Unreleased]`
-3. latest `pm-changelog` install and tracker changelog refresh through `pm changelog generate`
+2. version bump
+3. latest `pm-changelog` install and main changelog refresh through package-owned full-history generation; the release pipeline passes `--release-version` with `--all-release-tags` so the pending release section matches post-tag CI checks
 4. strict gates (build, typecheck, docs/skills freshness, coverage, static quality, compatibility, security, smoke checks, reliability gate)
 5. release note generation from changelog + pm evidence
 6. commit and tag creation (plus optional push)
 
-If commits since the last tag touch source, package, script, or workflow files, an empty `[Unreleased]` section is a release blocker. The pipeline exits nonzero and reports `changelog_required_files` plus `release_changelog_required:source_or_package_changes_without_unreleased_entry` so the missing release note is visible in automation instead of becoming a green no-op.
+The generated changelog includes clickable pm item links to the tracked `.toon` files. Missing release evidence should be fixed in pm item history, not by hand-editing `CHANGELOG.md`.
 
 ## Local Release Parity Checklist
 

package/marketplace.json

@@ -1,16 +1,19 @@
 {
   "name": "pm",
-  "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
   "owner": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"
   },
+  "metadata": {
+    "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
+    "version": "1.4.0"
+  },
   "plugins": [
     {
       "name": "pm-claude",
+      "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 18 MCP tools, 5 workflow skills, 14 slash commands, 3 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
       "version": "1.4.0",
-      "source": "./plugins/pm-claude",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"
@@ -28,7 +31,8 @@
         "git-native",
         "task-tracker",
         "ai"
-      ]
+      ],
+      "category": "productivity"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.5.24",
+  "version": "2026.5.27",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -28,6 +28,11 @@
       "import": "./dist/sdk/index.js",
       "default": "./dist/sdk/index.js"
     },
+    "./sdk/runtime": {
+      "types": "./dist/sdk/runtime.d.ts",
+      "import": "./dist/sdk/runtime.js",
+      "default": "./dist/sdk/runtime.js"
+    },
     "./cli": {
       "types": "./dist/cli/main.d.ts",
       "import": "./dist/cli/main.js",
@@ -44,7 +49,6 @@
     "CODE_OF_CONDUCT.md",
     "LICENSE",
     "AGENTS.md",
-    "PRD.md",
     "docs/**",
     ".claude-plugin/**",
     "plugins/**",
@@ -70,10 +74,9 @@
     "version:check": "node scripts/release-version.mjs check",
     "version:next": "node scripts/release-version.mjs next",
     "changelog:pm:install": "node dist/cli.js install npm:pm-changelog --project",
-    "changelog:pm": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.pm.md --title \"pm Tracker Changelog\" --group-by release --status closed",
-    "changelog:pm:check": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.pm.md --title \"pm Tracker Changelog\" --group-by release --status closed --check",
+    "changelog:pm": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm",
+    "changelog:pm:check": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm --check",
     "release:notes": "node scripts/generate-release-notes.mjs",
-    "release:changelog": "node scripts/release/changelog-promote.mjs",
     "release:gates": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",
     "release:pipeline": "node scripts/release/run-release-pipeline.mjs",
     "release:pipeline:dry-run": "node scripts/release/run-release-pipeline.mjs --dry-run",
@@ -111,7 +114,7 @@
     }
   },
   "dependencies": {
-    "@sentry/node": "^10.51.0",
+    "@sentry/node": "^10.54.0",
     "@toon-format/toon": "^2.3.0",
     "commander": "^14.0.3",
     "fast-glob": "^3.3.3",

package/packages/pm-beads/extensions/beads/index.js

@@ -1,7 +1,4 @@
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
-const CURRENT_EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
+import { loadPackageRuntimeModule } from "./runtime-loader.js";
 export const manifest = {
     name: "builtin-beads-import",
     version: "0.1.0",
@@ -23,52 +20,8 @@ function toBeadsImportOptions(options) {
         preserveSourceIds: asBoolean(options.preserveSourceIds),
     };
 }
-function resolvePackageRootCandidates() {
-    const candidates = [];
-    const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
-    if (typeof envRoot === "string" && envRoot.trim().length > 0) {
-        candidates.push(path.resolve(envRoot.trim()));
-    }
-    const argvEntry = typeof process.argv[1] === "string" ? process.argv[1].trim() : "";
-    if (argvEntry.length > 0) {
-        const resolvedEntry = path.resolve(argvEntry);
-        const entryDir = path.dirname(resolvedEntry);
-        candidates.push(path.resolve(entryDir, ".."));
-        candidates.push(path.resolve(entryDir, "../.."));
-        candidates.push(path.resolve(entryDir, "../../.."));
-    }
-    return [...new Set(candidates)];
-}
-async function loadRuntimeModule() {
-    const attempted = [];
-    for (const packageRoot of resolvePackageRootCandidates()) {
-        const modulePaths = [
-            path.join(packageRoot, ".agents", "pm", "extensions", "beads", "runtime.js"),
-            path.join(packageRoot, "packages", "pm-beads", "extensions", "beads", "runtime.js"),
-        ];
-        for (const modulePath of modulePaths) {
-            attempted.push(modulePath);
-            try {
-                return await import(pathToFileURL(modulePath).href);
-            }
-            catch {
-                // Try the next package-root candidate.
-            }
-        }
-    }
-    const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.js");
-    attempted.push(localRuntimePath);
-    try {
-        return await import(pathToFileURL(localRuntimePath).href);
-    }
-    catch {
-        // Fall through to the diagnostic below.
-    }
-    throw new Error("Unable to resolve packaged beads extension runtime module. " +
-        `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.js or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`);
-}
 async function runBeadsImportFromRuntime(options, global) {
-    const runtime = await loadRuntimeModule();
+    const runtime = await loadPackageRuntimeModule();
     if (typeof runtime.runBeadsImport !== "function") {
         throw new Error("Bundled beads runtime module is missing runBeadsImport().");
     }

package/packages/pm-beads/extensions/beads/index.ts

@@ -1,10 +1,6 @@
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
 import type { CommandDefinition, ExtensionApi, GlobalOptions } from "../../../../src/sdk/index.js";
 import type { BeadsImportOptions, BeadsImportResult } from "./runtime.js";
-
-const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
-const CURRENT_EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
+import { loadPackageRuntimeModule } from "./runtime-loader.js";
 
 export const manifest = {
   name: "builtin-beads-import",
@@ -35,56 +31,8 @@ function toBeadsImportOptions(options: Record<string, unknown>): BeadsImportOpti
   };
 }
 
-function resolvePackageRootCandidates(): string[] {
-  const candidates: string[] = [];
-  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
-  if (typeof envRoot === "string" && envRoot.trim().length > 0) {
-    candidates.push(path.resolve(envRoot.trim()));
-  }
-  const argvEntry = typeof process.argv[1] === "string" ? process.argv[1].trim() : "";
-  if (argvEntry.length > 0) {
-    const resolvedEntry = path.resolve(argvEntry);
-    const entryDir = path.dirname(resolvedEntry);
-    candidates.push(path.resolve(entryDir, ".."));
-    candidates.push(path.resolve(entryDir, "../.."));
-    candidates.push(path.resolve(entryDir, "../../.."));
-  }
-  return [...new Set(candidates)];
-}
-
-async function loadRuntimeModule(): Promise<RuntimeModule> {
-  const attempted: string[] = [];
-  for (const packageRoot of resolvePackageRootCandidates()) {
-    const modulePaths = [
-      path.join(packageRoot, ".agents", "pm", "extensions", "beads", "runtime.js"),
-      path.join(packageRoot, "packages", "pm-beads", "extensions", "beads", "runtime.js"),
-    ];
-    for (const modulePath of modulePaths) {
-      attempted.push(modulePath);
-      try {
-        return await import(pathToFileURL(modulePath).href) as RuntimeModule;
-      } catch {
-        // Try the next package-root candidate.
-      }
-    }
-  }
-
-  const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.js");
-  attempted.push(localRuntimePath);
-  try {
-    return await import(pathToFileURL(localRuntimePath).href) as RuntimeModule;
-  } catch {
-    // Fall through to the diagnostic below.
-  }
-
-  throw new Error(
-    "Unable to resolve packaged beads extension runtime module. " +
-      `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.js or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`,
-  );
-}
-
 async function runBeadsImportFromRuntime(options: BeadsImportOptions, global: GlobalOptions): Promise<BeadsImportResult> {
-  const runtime = await loadRuntimeModule();
+  const runtime = await loadPackageRuntimeModule() as RuntimeModule;
   if (typeof runtime.runBeadsImport !== "function") {
     throw new Error("Bundled beads runtime module is missing runBeadsImport().");
   }

package/packages/pm-beads/extensions/beads/runtime-loader.js

@@ -0,0 +1,86 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/**
+ * GENERATED by scripts/gen-package-runtime-loaders.mjs - do not edit directly.
+ * This file is shipped with the package extension and intentionally avoids
+ * static SDK imports so project-local installed extensions can load it.
+ */
+
+const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+const CURRENT_EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const EXTENSION_NAME = "beads";
+const PACKAGE_NAME = "pm-beads";
+const DIAGNOSTIC_NAME = "beads";
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+function isMissingRuntimeModuleError(error, modulePath) {
+  if (!isRecord(error) || error.code !== "ERR_MODULE_NOT_FOUND") {
+    return false;
+  }
+  const message = typeof error.message === "string" ? error.message : "";
+  const moduleUrl = pathToFileURL(modulePath).href;
+  return message.includes(modulePath) || message.includes(moduleUrl);
+}
+
+function resolvePackageRootCandidates() {
+  const candidates = [];
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot === "string" && envRoot.trim().length > 0) {
+    candidates.push(path.resolve(envRoot.trim()));
+  }
+  const argvEntry = typeof process.argv[1] === "string" ? process.argv[1].trim() : "";
+  if (argvEntry.length > 0) {
+    const resolvedEntry = path.resolve(argvEntry);
+    const entryDir = path.dirname(resolvedEntry);
+    candidates.push(path.resolve(entryDir, ".."));
+    candidates.push(path.resolve(entryDir, "../.."));
+    candidates.push(path.resolve(entryDir, "../../.."));
+  }
+  return [...new Set(candidates)];
+}
+
+export async function loadPackageRuntimeModule() {
+  const attempted = [];
+  for (const packageRoot of resolvePackageRootCandidates()) {
+    const modulePaths = [
+      path.join(packageRoot, ".agents", "pm", "extensions", EXTENSION_NAME, "runtime.js"),
+      path.join(packageRoot, "packages", PACKAGE_NAME, "extensions", EXTENSION_NAME, "runtime.js"),
+    ];
+    for (const modulePath of modulePaths) {
+      attempted.push(modulePath);
+      if (!existsSync(modulePath)) {
+        continue;
+      }
+      try {
+        return await import(pathToFileURL(modulePath).href);
+      } catch (error) {
+        if (isMissingRuntimeModuleError(error, modulePath)) {
+          continue;
+        }
+        throw error;
+      }
+    }
+  }
+
+  const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.js");
+  attempted.push(localRuntimePath);
+  if (existsSync(localRuntimePath)) {
+    try {
+      return await import(pathToFileURL(localRuntimePath).href);
+    } catch (error) {
+      if (!isMissingRuntimeModuleError(error, localRuntimePath)) {
+        throw error;
+      }
+    }
+  }
+
+  throw new Error(
+    `Unable to resolve packaged ${DIAGNOSTIC_NAME} extension runtime module. ` +
+      `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.js or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`,
+  );
+}

package/packages/pm-beads/extensions/beads/runtime-loader.ts

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/**
+ * GENERATED by scripts/gen-package-runtime-loaders.mjs - do not edit directly.
+ * This file is shipped with the package extension and intentionally avoids
+ * static SDK imports so project-local installed extensions can load it.
+ */
+
+const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+const CURRENT_EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const EXTENSION_NAME = "beads";
+const PACKAGE_NAME = "pm-beads";
+const DIAGNOSTIC_NAME = "beads";
+
+export type PackageRuntimeModule = Record<string, unknown>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isMissingRuntimeModuleError(error: unknown, modulePath: string): boolean {
+  if (!isRecord(error) || error.code !== "ERR_MODULE_NOT_FOUND") {
+    return false;
+  }
+  const message = typeof error.message === "string" ? error.message : "";
+  const moduleUrl = pathToFileURL(modulePath).href;
+  return message.includes(modulePath) || message.includes(moduleUrl);
+}
+
+function resolvePackageRootCandidates(): string[] {
+  const candidates: string[] = [];
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot === "string" && envRoot.trim().length > 0) {
+    candidates.push(path.resolve(envRoot.trim()));
+  }
+  const argvEntry = typeof process.argv[1] === "string" ? process.argv[1].trim() : "";
+  if (argvEntry.length > 0) {
+    const resolvedEntry = path.resolve(argvEntry);
+    const entryDir = path.dirname(resolvedEntry);
+    candidates.push(path.resolve(entryDir, ".."));
+    candidates.push(path.resolve(entryDir, "../.."));
+    candidates.push(path.resolve(entryDir, "../../.."));
+  }
+  return [...new Set(candidates)];
+}
+
+export async function loadPackageRuntimeModule(): Promise<PackageRuntimeModule> {
+  const attempted: string[] = [];
+  for (const packageRoot of resolvePackageRootCandidates()) {
+    const modulePaths = [
+      path.join(packageRoot, ".agents", "pm", "extensions", EXTENSION_NAME, "runtime.js"),
+      path.join(packageRoot, "packages", PACKAGE_NAME, "extensions", EXTENSION_NAME, "runtime.js"),
+    ];
+    for (const modulePath of modulePaths) {
+      attempted.push(modulePath);
+      if (!existsSync(modulePath)) {
+        continue;
+      }
+      try {
+        return await import(pathToFileURL(modulePath).href) as PackageRuntimeModule;
+      } catch (error: unknown) {
+        if (isMissingRuntimeModuleError(error, modulePath)) {
+          continue;
+        }
+        throw error;
+      }
+    }
+  }
+
+  const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.js");
+  attempted.push(localRuntimePath);
+  if (existsSync(localRuntimePath)) {
+    try {
+      return await import(pathToFileURL(localRuntimePath).href) as PackageRuntimeModule;
+    } catch (error: unknown) {
+      if (!isMissingRuntimeModuleError(error, localRuntimePath)) {
+        throw error;
+      }
+    }
+  }
+
+  throw new Error(
+    `Unable to resolve packaged ${DIAGNOSTIC_NAME} extension runtime module. ` +
+      `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.js or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`,
+  );
+}