@unbrained/pm-web 2026.7.27 → 2026.7.29

package/dist/services/package-catalog.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The set of capabilities a pm package can declare, mirrored verbatim from
+ * each package's `manifest.json` `capabilities` array. The union is kept
+ * open-ended as a string array (not a closed enum) because the pm extension
+ * contract may add new capability kinds upstream; pinning a closed list here
+ * would reject a future package that uses a capability we have not enumerated.
+ */
+export type PackageCapability = string;
+/**
+ * Catalog grouping: user-facing product extensions vs. authoring reference
+ * templates.
+ *
+ * - `"extension"` — a product extension a user installs for its functionality
+ *   (e.g. pm-graph, pm-jira). This is the default and the only category the
+ *   catalog originally carried.
+ * - `"template"` — a reference/scaffold extension that a user installs to
+ *   learn the extension API. It registers real commands (it ships
+ *   `manifest.json` + `dist/` and calls `registerCommand`), so installing it
+ *   is a genuine operation, but its purpose is to be read and copied — it is
+ *   the reference implementation covering every capability type. The UI
+ *   badges template entries so a user can tell a learning scaffold from a
+ *   product extension.
+ */
+export type PackageCategory = "extension" | "template";
+/**
+ * Honest gating metadata so the UI can tell a user what they must configure
+ * before a package is useful. Both fields are OPTIONAL — most packages work
+ * with no external setup.
+ *
+ * - `requiresService`: a backing service the package talks to (e.g. Neo4j for
+ *   pm-graph's sync). When set, the UI explains that the package's
+ *   service-dependent features will not work until the service is reachable.
+ *   `optional: true` means the package is still useful without the service
+ *   (e.g. pm-graph's offline export/analyze work without Neo4j).
+ *
+ * - `requiresCredentials`: human-supplied secrets the package needs for its
+ *   network-mutating commands (e.g. JIRA_API_TOKEN, LINEAR_API_KEY,
+ *   PM_SLACK_WEBHOOK, GITHUB_TOKEN). Each entry names the env var(s) and a
+ *   short human description. The UI must not pretend these are one-click; it
+ *   surfaces the variables the user must set.
+ */
+export interface ServiceRequirement {
+    /** Display name of the backing service, e.g. "Neo4j". */
+    name: string;
+    /** True when the package is useful without the service (best-effort). */
+    optional?: boolean;
+}
+export interface CredentialRequirement {
+    /** Display label for what the credentials unlock, e.g. "Jira sync". */
+    label: string;
+    /** Environment variable(s) the package reads for the credentials. */
+    envVars: string[];
+    /**
+     * True when the package is partially usable without the credentials (e.g.
+     * `--dry-run` paths, unauthenticated reads). When false, the package is
+     * inert until the credentials are configured.
+     */
+    optional?: boolean;
+}
+export interface PackageCatalogEntry {
+    /** Canonical npm package name, e.g. `pm-graph`. */
+    readonly name: string;
+    /** The install spec passed to `pm install`, always `npm:<name>`. */
+    readonly npmSpec: string;
+    /** Human-friendly title, e.g. `Graph`. */
+    readonly title: string;
+    /** One-line description, mirrored from the package's manifest/package.json. */
+    readonly description: string;
+    /** Capabilities declared in the package manifest. */
+    readonly capabilities: readonly PackageCapability[];
+    /**
+     * Whether this is a user-facing product extension (`"extension"`) or an
+     * authoring reference template (`"template"`). The UI badges template
+     * entries so a user can distinguish a learning scaffold from a product
+     * extension. See {@link PackageCategory}.
+     */
+    readonly category: PackageCategory;
+    /** Backing service the package needs (optional). */
+    readonly requiresService?: ServiceRequirement;
+    /** Credentials the user must configure (optional). */
+    readonly requiresCredentials?: readonly CredentialRequirement[];
+}
+/**
+ * The catalog. Order is the display order in the UI. The list is exhaustive
+ * over every published pm package except `pm-web` itself (it is the host and
+ * cannot install itself). The {@link PackageCategory} field on each entry
+ * distinguishes user-facing product extensions from authoring reference
+ * templates; the two starter packages sort last so product extensions appear
+ * first.
+ */
+export declare const PACKAGE_CATALOG: readonly PackageCatalogEntry[];
+/**
+ * Look up a catalog entry by package name. Returns the entry or `undefined`
+ * when the name is not in the catalog. This is the security-critical gate:
+ * route handlers MUST call this and reject with 400 on a miss BEFORE passing
+ * the name to any pm command, so a user-supplied string can never be
+ * interpolated into an install target.
+ */
+export declare function findCatalogEntry(name: string): PackageCatalogEntry | undefined;
+/**
+ * Resolve a package name to its verified npm install spec
+ * (`npm:<name>`), or `null` when the name is not in the catalog. Route
+ * handlers use this to obtain the spawn argument without ever building an
+ * install target from a raw user string.
+ */
+export declare function resolveNpmSpec(name: string): string | null;
+/** The immutable list of catalog package names, in display order. */
+export declare function catalogNames(): readonly string[];

package/dist/services/package-catalog.js

@@ -0,0 +1,256 @@
+// ═══════════════════════════════════════════════════════════════
+// PACKAGE CATALOG — the typed, immutable list of every installable pm package
+// ═══════════════════════════════════════════════════════════════
+//
+// pm-web used to ship exactly one pm package — a vendored copy of pm-graph
+// pinned to an old CLI — and offered no way to install any other. This
+// catalog is the single source of truth for the per-project "Packages" view
+// and the extensions routes: every package the UI can install is declared
+// here, and every `:name` route parameter is validated against it BEFORE a
+// pm command is ever spawned. A user-supplied name can never reach an install
+// target — a catalog lookup miss must 400 before any process spawn.
+//
+// The catalog is exhaustive over every published pm package except `pm-web`
+// itself (this package IS the host, so it cannot install itself). The
+// `category` field distinguishes user-facing product extensions
+// (`"extension"`) from authoring reference templates (`"template"`): the
+// starters are real, published npm packages that ship `manifest.json` +
+// `dist/` and call `registerCommand`, so installing them genuinely registers
+// working commands — they exist to be read and copied as reference
+// implementations covering every capability type, and the UI badges them so a
+// user can tell a learning scaffold from a product extension.
+//
+// Truthfulness contract: the catalog mirrors each package's real
+// `manifest.json` (name, capabilities) and README (gating). Do NOT invent
+// capabilities or hide requirements here — the UI surfaces `requiresService`
+// and `requiresCredentials` so users are not promised a one-click install for
+// a package that needs a Neo4j instance or an API token. The
+// `test/catalog.test.ts` suite asserts that every entry's declared capabilities
+// match the on-disk `manifest.json` under fleet/<pkg>/manifest.json, so a
+// drift between this catalog and the packages is a failing test, not a silent
+// UI lie.
+/**
+ * The catalog. Order is the display order in the UI. The list is exhaustive
+ * over every published pm package except `pm-web` itself (it is the host and
+ * cannot install itself). The {@link PackageCategory} field on each entry
+ * distinguishes user-facing product extensions from authoring reference
+ * templates; the two starter packages sort last so product extensions appear
+ * first.
+ */
+export const PACKAGE_CATALOG = [
+    {
+        name: "pm-graph",
+        npmSpec: "npm:pm-graph",
+        title: "Graph",
+        description: "Knowledge graph and dependency graph extension for pm CLI workspaces, with optional Neo4j sync.",
+        capabilities: ["commands", "importers", "services"],
+        category: "extension",
+        requiresService: { name: "Neo4j", optional: true },
+    },
+    {
+        name: "pm-beads",
+        npmSpec: "npm:pm-beads",
+        title: "Beads",
+        description: "Beads JSONL importer/exporter. Import work items from the Beads JSONL format into pm and export pm items back to Beads JSONL, preserving ids and dependency edges.",
+        capabilities: ["commands", "schema", "importers"],
+        category: "extension",
+    },
+    {
+        name: "pm-brief",
+        npmSpec: "npm:pm-brief",
+        title: "Brief",
+        description: "Token-budgeted agent briefs and next-work plans for pm workspaces",
+        capabilities: ["commands", "renderers", "schema"],
+        category: "extension",
+    },
+    {
+        name: "pm-changelog",
+        npmSpec: "npm:pm-changelog",
+        title: "Changelog",
+        description: "Generate CHANGELOG.md release notes from pm-cli items",
+        capabilities: ["commands", "schema", "importers", "renderers"],
+        category: "extension",
+    },
+    {
+        name: "pm-context",
+        npmSpec: "npm:pm-context",
+        title: "Context",
+        description: "Generate deterministic pm context packs for agent handoffs, reviews, and status briefs",
+        capabilities: ["commands", "renderers", "schema"],
+        category: "extension",
+    },
+    {
+        name: "pm-csv",
+        npmSpec: "npm:pm-csv",
+        title: "CSV",
+        description: "CSV importer and exporter for pm-cli",
+        capabilities: ["commands", "importers", "schema"],
+        category: "extension",
+    },
+    {
+        name: "pm-gantt-chart",
+        npmSpec: "npm:pm-gantt-chart",
+        title: "Gantt Chart",
+        description: "ASCII Gantt chart renderer + multi-format exporter for pm-cli",
+        capabilities: ["commands", "schema", "importers", "preflight"],
+        category: "extension",
+    },
+    {
+        name: "pm-github",
+        npmSpec: "npm:pm-github",
+        title: "GitHub",
+        description: "GitHub Issues + Projects v2 integration. Imports issues as pm items (`pm github import`), exports pm items as GitHub issues, syncs issue state, and bidirectionally syncs pm items with a GitHub Projects v2 board (`pm github project import/sync/list/fields`) — mapping pm status to the board Status column with idempotent, no-data-loss provenance.",
+        capabilities: ["commands", "importers", "schema", "hooks", "preflight", "search"],
+        category: "extension",
+        requiresCredentials: [
+            {
+                label: "GitHub token (for private repos, 5000 req/hr, and export/push)",
+                envVars: ["GITHUB_TOKEN", "GH_TOKEN"],
+                optional: true,
+            },
+        ],
+    },
+    {
+        name: "pm-jira",
+        npmSpec: "npm:pm-jira",
+        title: "Jira",
+        description: "Jira issue sync for pm-cli",
+        capabilities: ["commands", "schema", "importers", "hooks", "preflight"],
+        category: "extension",
+        requiresCredentials: [
+            {
+                label: "Jira API credentials (for live sync, import, and export --push)",
+                envVars: ["JIRA_BASE_URL", "JIRA_EMAIL", "JIRA_API_TOKEN"],
+            },
+        ],
+    },
+    {
+        name: "pm-linear",
+        npmSpec: "npm:pm-linear",
+        title: "Linear",
+        description: "Linear.app issue sync for pm-cli",
+        capabilities: ["commands", "schema", "importers", "preflight"],
+        category: "extension",
+        requiresCredentials: [
+            {
+                label: "Linear API key (for live import/export and validate --check-network)",
+                envVars: ["LINEAR_API_KEY"],
+            },
+        ],
+    },
+    {
+        name: "pm-ops",
+        npmSpec: "npm:pm-ops",
+        title: "Ops",
+        description: "Multi-repo fleet operations for pm-cli",
+        capabilities: ["commands", "renderers", "schema", "parser"],
+        category: "extension",
+    },
+    {
+        name: "pm-presets",
+        npmSpec: "npm:pm-presets",
+        title: "Presets",
+        description: "All 7 official pm-cli workspace presets in one package: bug-triage, indie-dev, open-source, software-sprint, startup-roadmap, kanban, agent-workflow",
+        capabilities: ["commands", "schema"],
+        category: "extension",
+    },
+    {
+        name: "pm-slack",
+        npmSpec: "npm:pm-slack",
+        title: "Slack",
+        description: "Slack notifications for pm item lifecycle events",
+        capabilities: ["commands", "hooks", "schema", "preflight"],
+        category: "extension",
+        requiresCredentials: [
+            {
+                label: "Slack webhook (for posting notifications)",
+                envVars: ["PM_SLACK_WEBHOOK"],
+            },
+        ],
+    },
+    {
+        name: "pm-slack-standup",
+        npmSpec: "npm:pm-slack-standup",
+        title: "Slack Standup",
+        description: "Post pm context as a Slack standup message",
+        capabilities: ["commands", "schema", "importers", "preflight", "services"],
+        category: "extension",
+        requiresCredentials: [
+            {
+                label: "Slack webhook (for posting the standup)",
+                envVars: ["PM_SLACK_WEBHOOK"],
+            },
+        ],
+    },
+    {
+        name: "pm-todos",
+        npmSpec: "npm:pm-todos",
+        title: "Todos",
+        description: "TODO round-trip. Import/export/sync markdown checkboxes, todo.txt, jsonl, checkbox, and pi coding-agent todo JSON as pm items.",
+        capabilities: ["commands", "schema", "importers", "preflight"],
+        category: "extension",
+    },
+    {
+        name: "pm-starter",
+        npmSpec: "npm:pm-starter",
+        title: "Starter",
+        description: "Complete starter/scaffold extension for pm-cli showing all capability types",
+        capabilities: [
+            "commands",
+            "renderers",
+            "hooks",
+            "schema",
+            "importers",
+            "search",
+            "parser",
+            "preflight",
+            "services",
+        ],
+        category: "template",
+    },
+    {
+        name: "pm-ts-starter",
+        npmSpec: "npm:pm-ts-starter",
+        title: "TypeScript Starter",
+        description: "TypeScript reference extension for pm-cli covering all capability types",
+        capabilities: [
+            "commands",
+            "renderers",
+            "hooks",
+            "schema",
+            "importers",
+            "search",
+            "parser",
+            "preflight",
+            "services",
+        ],
+        category: "template",
+    },
+];
+/** A frozen map keyed by package name for O(1) catalog lookup. */
+const CATALOG_BY_NAME = new Map(PACKAGE_CATALOG.map((entry) => [entry.name, entry]));
+/**
+ * Look up a catalog entry by package name. Returns the entry or `undefined`
+ * when the name is not in the catalog. This is the security-critical gate:
+ * route handlers MUST call this and reject with 400 on a miss BEFORE passing
+ * the name to any pm command, so a user-supplied string can never be
+ * interpolated into an install target.
+ */
+export function findCatalogEntry(name) {
+    return CATALOG_BY_NAME.get(name);
+}
+/**
+ * Resolve a package name to its verified npm install spec
+ * (`npm:<name>`), or `null` when the name is not in the catalog. Route
+ * handlers use this to obtain the spawn argument without ever building an
+ * install target from a raw user string.
+ */
+export function resolveNpmSpec(name) {
+    const entry = CATALOG_BY_NAME.get(name);
+    return entry ? entry.npmSpec : null;
+}
+/** The immutable list of catalog package names, in display order. */
+export function catalogNames() {
+    return PACKAGE_CATALOG.map((entry) => entry.name);
+}
+//# sourceMappingURL=package-catalog.js.map

package/dist/services/package-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-catalog.js","sourceRoot":"","sources":["../../src/services/package-catalog.ts"],"names":[],"mappings":"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"}

package/dist/services/pm-runner.d.ts

@@ -1,9 +1,9 @@
 import { PmClient, PmCliError, isPmCliExpectedError, EXIT_CODE, type GetItemAtResult } from "@unbrained/pm-cli/sdk";
 export { PmCliError, isPmCliExpectedError, EXIT_CODE, type GetItemAtResult };
 export declare class Semaphore {
-    private readonly limit;
     private active;
     private readonly waiting;
+    private readonly limit;
     constructor(limit: number);
     acquire(): Promise<() => void>;
 }
@@ -49,6 +49,71 @@ export interface EnsureGraphExtensionResult {
     active: boolean;
     error?: string;
 }
+/**
+ * The per-extension state shape emitted by `pm extension --json`. Only the
+ * fields consumers read are typed; the command emits far more (triage, policy,
+ * diagnostics) which is deliberately dropped.
+ */
+export interface ExtensionState {
+    name: string;
+    version?: string;
+    active?: boolean;
+    enabled?: boolean;
+    runtime_active?: boolean;
+    activation_status?: string;
+    managed?: boolean;
+    source?: {
+        kind?: string;
+        input?: string;
+    };
+}
+/**
+ * Outcome of reading per-project extension state.
+ *
+ * `ok` distinguishes "the command ran and this is the state" from "the command
+ * failed, so we know nothing" — a distinction both previous copies of this
+ * parser collapsed, reporting a failed `pm extension --json` identically to a
+ * project with nothing installed.
+ */
+export interface ExtensionStatesResult {
+    ok: boolean;
+    states: Map<string, ExtensionState>;
+    error?: string;
+}
+/**
+ * Read the per-project extension state from `pm extension --json`, returning a
+ * map keyed by extension name. Used both by {@link ensureGraphExtension} and
+ * the extensions routes' catalog join.
+ */
+export declare function readProjectExtensionStates(projectDir: string): Promise<ExtensionStatesResult>;
+/**
+ * Timeout for package installs, which resolve and download from the npm
+ * registry rather than only touching local state.
+ *
+ * The 30s default is sized for local commands and leaves too thin a margin
+ * here. Measured on this host: a warm-cache install is ~2s, and a cold-cache
+ * install of the heaviest catalog package (pm-graph, which pulls
+ * `neo4j-driver`) is ~10s. That is only a 3x margin on a fast connection,
+ * before accounting for a container sharing bandwidth or a slow registry —
+ * and the failure mode is a project create or package install that dies
+ * mid-download. A hung install still terminates, just later.
+ */
+export declare const INSTALL_COMMAND_TIMEOUT_MS = 180000;
+/**
+ * Ensure the pm-graph package is installed and active for a project.
+ *
+ * This used to install a *vendored* copy of pm-graph from
+ * `extensions/pm-graph/` (a stale fork pinned to pm-cli `^2026.7.5`). The
+ * vendored fork is gone; pm-graph is now installed from npm through the same
+ * generic catalog path as every other pm package
+ * (src/services/package-catalog.ts). The npm spec is resolved from the catalog
+ * — never built from a user-supplied string — so the install target is always
+ * the verified `npm:pm-graph` constant.
+ *
+ * The graph routes in src/routes/pm.ts call this before `pm pm-graph export`,
+ * and {@link initProject} calls it on project creation, so the user-facing
+ * graph behaviour is unchanged.
+ */
 export declare function ensureGraphExtension(userId: string, slug: string): Promise<EnsureGraphExtensionResult>;
 /**
  * Return a cached {@link PmClient} for a workspace pm-root, creating one on

package/dist/services/pm-runner.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { pool } from "../db.js";
 import { getItemAt, PM_TOOL_PARAMETERS_SCHEMA, PmClient, PmCliError, isPmCliExpectedError, EXIT_CODE, } from "@unbrained/pm-cli/sdk";
+import { resolveNpmSpec } from "./package-catalog.js";
 // Re-exported so route handlers and tests can reference the verified projection
 // shape and the typed error class without reaching into the SDK package map.
 export { PmCliError, isPmCliExpectedError, EXIT_CODE };
@@ -13,9 +14,9 @@ function positiveInteger(value, fallback) {
     return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
 }
 export class Semaphore {
-    limit;
     active = 0;
     waiting = [];
+    limit;
     constructor(limit) {
         this.limit = limit;
     }
@@ -50,8 +51,6 @@ const OLLAMA_BASE_URL = process.env.OLLAMA_BASE_URL ||
 const OLLAMA_EMBEDDING_MODEL = process.env.PM_OLLAMA_MODEL ||
     "qwen3-embedding:0.6b";
 const OLLAMA_API_KEY = process.env.OLLAMA_API_KEY || "";
-const PM_GRAPH_EXTENSION_PATH = process.env.PM_GRAPH_EXTENSION_PATH ||
-    path.join(process.cwd(), "extensions", "pm-graph");
 export function getProjectDir(userId, slug) {
     return path.join(projectsRoot(), userId, slug);
 }
@@ -224,82 +223,102 @@ export function projectExists(userId, slug) {
     const dir = getProjectDir(userId, slug);
     return fs.existsSync(path.join(dir, ".agents", "pm", "settings.json"));
 }
-function readJsonFile(filePath) {
-    try {
-        return JSON.parse(fs.readFileSync(filePath, "utf8"));
-    }
-    catch {
-        return null;
+/**
+ * Read the per-project extension state from `pm extension --json`, returning a
+ * map keyed by extension name. Used both by {@link ensureGraphExtension} and
+ * the extensions routes' catalog join.
+ */
+export async function readProjectExtensionStates(projectDir) {
+    const result = await runSerialized(projectDir, () => runProcess(projectDir, ["extension", "--json"], { timeoutMs: 15_000 }));
+    const states = new Map();
+    if (!result.ok || !result.stdout) {
+        return { ok: false, states, error: result.stderr || "pm extension --json failed" };
     }
-}
-function bundledGraphExtensionManifest() {
-    const manifestPath = path.join(PM_GRAPH_EXTENSION_PATH, "manifest.json");
-    if (!fs.existsSync(manifestPath))
-        return null;
-    return readJsonFile(manifestPath);
-}
-function projectGraphExtensionManifest(projectDir) {
-    return readJsonFile(path.join(projectDir, ".agents", "pm", "extensions", "pm-graph", "manifest.json"));
-}
-async function graphExtensionIsActive(projectDir) {
-    const result = await runSerialized(projectDir, () => runProcess(projectDir, ["extension", "explore", "--project", "--json"], { timeoutMs: 15_000 }));
-    if (!result.ok || !result.stdout)
-        return false;
     try {
         const parsed = JSON.parse(result.stdout);
-        return Boolean(parsed.details?.extensions?.some((extension) => extension.name === "pm-graph" && extension.active && extension.enabled));
+        const extensions = parsed.details?.extensions;
+        if (!Array.isArray(extensions)) {
+            return { ok: false, states, error: "pm extension --json returned no extension list" };
+        }
+        for (const ext of extensions) {
+            if (ext && typeof ext.name === "string")
+                states.set(ext.name, ext);
+        }
     }
     catch {
-        return false;
+        return { ok: false, states, error: "pm extension --json returned malformed JSON" };
     }
+    return { ok: true, states };
 }
-async function runExtensionCommand(projectDir, args) {
-    return runSerialized(projectDir, () => runProcess(projectDir, args));
+/**
+ * Timeout for package installs, which resolve and download from the npm
+ * registry rather than only touching local state.
+ *
+ * The 30s default is sized for local commands and leaves too thin a margin
+ * here. Measured on this host: a warm-cache install is ~2s, and a cold-cache
+ * install of the heaviest catalog package (pm-graph, which pulls
+ * `neo4j-driver`) is ~10s. That is only a 3x margin on a fast connection,
+ * before accounting for a container sharing bandwidth or a slow registry —
+ * and the failure mode is a project create or package install that dies
+ * mid-download. A hung install still terminates, just later.
+ */
+export const INSTALL_COMMAND_TIMEOUT_MS = 180_000;
+async function runExtensionCommand(projectDir, args, timeoutMs) {
+    return runSerialized(projectDir, () => runProcess(projectDir, args, { timeoutMs }));
 }
+/**
+ * Ensure the pm-graph package is installed and active for a project.
+ *
+ * This used to install a *vendored* copy of pm-graph from
+ * `extensions/pm-graph/` (a stale fork pinned to pm-cli `^2026.7.5`). The
+ * vendored fork is gone; pm-graph is now installed from npm through the same
+ * generic catalog path as every other pm package
+ * (src/services/package-catalog.ts). The npm spec is resolved from the catalog
+ * — never built from a user-supplied string — so the install target is always
+ * the verified `npm:pm-graph` constant.
+ *
+ * The graph routes in src/routes/pm.ts call this before `pm pm-graph export`,
+ * and {@link initProject} calls it on project creation, so the user-facing
+ * graph behaviour is unchanged.
+ */
 export async function ensureGraphExtension(userId, slug) {
     const dir = getProjectDir(userId, slug);
-    const bundledManifest = bundledGraphExtensionManifest();
-    if (!bundledManifest) {
+    // Resolve the verified npm install spec from the catalog — never a raw path.
+    const npmSpec = resolveNpmSpec("pm-graph");
+    if (!npmSpec) {
         return {
             ok: false,
             installed: false,
             active: false,
-            error: `Bundled pm-graph extension not found at ${PM_GRAPH_EXTENSION_PATH}`,
+            error: "pm-graph is not present in the package catalog.",
         };
     }
-    const projectManifest = projectGraphExtensionManifest(dir);
-    const needsInstall = !projectManifest || projectManifest.version !== bundledManifest.version;
-    if (needsInstall) {
-        const install = await runExtensionCommand(dir, ["install", PM_GRAPH_EXTENSION_PATH, "--project"]);
+    const { states } = await readProjectExtensionStates(dir);
+    const graphState = states.get("pm-graph");
+    const installed = Boolean(graphState);
+    const active = Boolean(graphState?.active && graphState?.enabled);
+    if (!installed) {
+        const install = await runExtensionCommand(dir, ["install", npmSpec, "--project"], INSTALL_COMMAND_TIMEOUT_MS);
         if (!install.ok) {
             return {
                 ok: false,
-                installed: Boolean(projectManifest),
+                installed: false,
                 active: false,
-                error: install.stderr || install.stdout || "Failed to install bundled pm-graph extension.",
+                error: install.stderr || install.stdout || "Failed to install pm-graph from npm.",
             };
         }
     }
-    if (!(await graphExtensionIsActive(dir))) {
+    if (!active) {
         const activate = await runExtensionCommand(dir, ["extension", "activate", "pm-graph", "--project"]);
         if (!activate.ok) {
             return {
                 ok: false,
                 installed: true,
                 active: false,
-                error: activate.stderr || activate.stdout || "Failed to activate bundled pm-graph extension.",
+                error: activate.stderr || activate.stdout || "Failed to activate pm-graph.",
             };
         }
     }
-    const ping = await runExtensionCommand(dir, ["pm-graph", "ping", "--json"]);
-    if (!ping.ok) {
-        return {
-            ok: false,
-            installed: true,
-            active: false,
-            error: ping.stderr || ping.stdout || "Bundled pm-graph extension is installed but did not activate at runtime.",
-        };
-    }
     return { ok: true, installed: true, active: true };
 }
 // ---------------------------------------------------------------------------
@@ -352,6 +371,16 @@ const SPAWN_FALLBACK_ACTIONS = new Set([
     "test-runs",
     // `pm templates list/show` is not a native SDK action.
     "templates",
+    // Extension management (`pm install <source> --project`, `pm extension
+    // activate|deactivate|uninstall <name> --project`) takes a positional source
+    // or subcommand that `PmClient.run(action, {options})` drops — the SDK's
+    // `client.run("install", ...)` raises "requires extension source input" and
+    // `client.run("extension", ...)` only performs the default explore, ignoring
+    // activate/deactivate/uninstall. The per-project package catalog routes depend
+    // on these positionals, so install + extension stay on the spawn fallback (the
+    // verified `pm install npm:<pkg> --project` mechanism).
+    "install",
+    "extension",
     // `PmClient.run("plan", {options:{subcommand,id}})` does not accept the plan id
     // as an option key (only the typed convenience methods `planShow(id)` /
     // `planAddStep(id,...)` do). Converting all ~17 plan routes to typed methods is
@@ -391,6 +420,13 @@ const POSITIONAL_KEYS = {
     "pause-task": ["id"],
     "close-task": ["id", "reason"],
     history: ["id"],
+    // `pm schema [subcommand] [name]` — e.g. `schema add-type Spike`. Without this
+    // mapping both positionals are dropped and the SDK rejects the call with
+    // "Missing required argument: subcommand".
+    schema: ["subcommand", "name"],
+    // `pm history-repair [id]` — omitted only when `--all` is passed, which the
+    // per-item route never does.
+    "history-repair": ["id"],
     config: ["scope", "configAction", "key", "value"],
 };
 const PM_CLIENT_CACHE_MAX = positiveInteger(process.env.PM_WEB_PM_CLIENT_CACHE_MAX, 256);