@unbrained/pm-web 2026.7.25 → 2026.7.27

package/dist/services/mutation-event-watcher.d.ts

@@ -0,0 +1,48 @@
+import { type MutationEvent } from "@unbrained/pm-cli/sdk";
+import { type SSEEvent } from "./sse.js";
+/** Options for the async generator subscription seam. Mirrors the SDK's `SubscribeMutationEventsOptions`. */
+export interface SubscribeOptions {
+    /** Tracker root path (`.agents/pm` under the project directory). */
+    pmRoot: string;
+    /** Opaque cursor or inclusive ISO timestamp lower bound. */
+    since: string;
+    /** Delay between empty catch-up reads. */
+    intervalMs: number;
+    /** Cancellation signal for a long-lived subscription. */
+    signal: AbortSignal;
+}
+/** Result of the subscribe seam — an async generator yielding mutation events. */
+export type SubscribeFn = (options: SubscribeOptions) => AsyncGenerator<MutationEvent, void, void>;
+/** Dependencies for `createMutationEventReconciler`, all injectable for testing. */
+export interface MutationEventWatcherDeps {
+    /** Delay between empty catch-up reads passed to the SDK subscription (default 250, floor 10). */
+    intervalMs?: number;
+    /** Reconcile interval for the periodic sweep (default 2000, floor 500). */
+    reconcileMs?: number;
+    /** Returns the currently active (SSE-connected) project ids. */
+    getActiveProjectIds?: () => string[];
+    /** Resolves a project id to its on-disk directory, or null when the project row is absent. */
+    resolveProjectDir?: (projectId: string) => Promise<string | null>;
+    /** SDK subscription factory; defaults to the real `subscribeMutationEvents`. */
+    subscribe?: SubscribeFn;
+    /** Checks whether an item mutation was already announced by this instance; returns true and consumes it. */
+    consumeSignaledItemMutation?: (projectId: string, itemId: string) => boolean;
+    /** Emits an SSE event to the local clients of one project. */
+    emit?: (projectId: string, event: SSEEvent) => void;
+    /** Error sink for non-abort errors from a subscription loop. */
+    onError?: (err: unknown) => void;
+}
+/**
+ * Pure, testable reconciler. Holds per-project subscription state across
+ * reconcile cycles. Drives the watcher without timers — tests call `reconcile()`
+ * directly. Follows the same dependency-injection style as `createProjectWatchCycle`.
+ */
+export declare function createMutationEventReconciler(deps?: MutationEventWatcherDeps): {
+    reconcile: () => Promise<void>;
+    stopAll: () => Promise<void>;
+};
+/**
+ * Start the mutation-event watcher. Returns a stop function, mirroring
+ * `startProjectWatcher`. Disabled entirely when `PM_REALTIME_MUTATION_EVENTS=false`.
+ */
+export declare function startMutationEventWatcher(deps?: MutationEventWatcherDeps): () => void;

package/dist/services/mutation-event-watcher.js

@@ -0,0 +1,171 @@
+// Per-project mutation-event subscription manager.
+//
+// The primary out-of-band change detector for pm-web. Subscribes to the pm SDK's
+// `subscribeMutationEvents` async generator for each active project, which reads
+// from a persistent derived index of committed mutation facts (NOT a filesystem
+// scan). Another process's mutation appears on this follower within `intervalMs`.
+//
+// Raw file edits that bypass pm (git merge, rsync restore, manual writes) produce
+// NO mutation event — the stream is a committed-mutation fact stream derived from
+// history. The filesystem sweep in project-watcher.ts is therefore KEPT as a safety
+// net for those bypass-pm writes; this module is the primary path for pm-authored
+// mutations.
+//
+// Events are emitted LOCALLY only (deliverProjectEvent, NOT broadcastProjectEvent).
+// Every pm-web instance reads the same shared volume and will independently observe
+// the same mutation events; publishing to the Postgres bus would duplicate them
+// across instances. Each instance dedupes against its own API broadcasts via the
+// per-item signal in sse.ts.
+import path from "node:path";
+import { subscribeMutationEvents } from "@unbrained/pm-cli/sdk";
+import { resolveProjectDir } from "./pm-runner.js";
+import { consumeSignaledItemMutation, deliverProjectEvent, getActiveProjectIds, } from "./sse.js";
+const DEFAULT_INTERVAL_MS = 250;
+const MIN_INTERVAL_MS = 10;
+const DEFAULT_RECONCILE_MS = 2_000;
+const MIN_RECONCILE_MS = 500;
+function positiveIntEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+// Determine whether an error from the subscription loop is an AbortError caused
+// by a deliberate stop (project went inactive or shutdown). Those must NOT be
+// reported as errors — only genuine failures are routed to onError.
+function isAbortError(err) {
+    if (err instanceof Error) {
+        return err.name === "AbortError" || /^aborted/i.test(err.message);
+    }
+    return false;
+}
+/**
+ * Pure, testable reconciler. Holds per-project subscription state across
+ * reconcile cycles. Drives the watcher without timers — tests call `reconcile()`
+ * directly. Follows the same dependency-injection style as `createProjectWatchCycle`.
+ */
+export function createMutationEventReconciler(deps = {}) {
+    const intervalMs = Math.max(MIN_INTERVAL_MS, deps.intervalMs ?? positiveIntEnv("PM_MUTATION_EVENT_INTERVAL_MS", DEFAULT_INTERVAL_MS));
+    const getIds = deps.getActiveProjectIds ?? getActiveProjectIds;
+    const resolveDir = deps.resolveProjectDir ?? resolveProjectDir;
+    const subscribe = deps.subscribe ?? subscribeMutationEvents;
+    const consumeSignal = deps.consumeSignaledItemMutation ?? consumeSignaledItemMutation;
+    const emit = deps.emit ?? deliverProjectEvent;
+    const onError = deps.onError ?? (() => undefined);
+    const subs = new Map();
+    const dirCache = new Map();
+    let inFlight = false;
+    // Start (or restart after error) a detached async loop that consumes the SDK
+    // generator for one project. Runs independently of reconcile; errors abort
+    // the subscription and the next reconcile re-establishes it from the stored cursor.
+    function startLoop(projectId, dir, since) {
+        const controller = new AbortController();
+        const sub = { controller, cursor: since, done: false };
+        subs.set(projectId, sub);
+        const pmRoot = path.join(dir, ".agents", "pm");
+        // Detached async loop — intentionally not awaited by reconcile.
+        void (async () => {
+            try {
+                const gen = subscribe({ pmRoot, since, intervalMs, signal: controller.signal });
+                for await (const event of gen) {
+                    sub.cursor = event.cursor;
+                    // Skip events that this instance's own API already announced (per-item dedupe).
+                    if (consumeSignal(projectId, event.item_id))
+                        continue;
+                    emit(projectId, {
+                        type: "workspace-changed",
+                        data: {
+                            source: "mutation-events",
+                            itemId: event.item_id,
+                            operation: event.type,
+                            author: event.author,
+                        },
+                    });
+                }
+            }
+            catch (err) {
+                if (!isAbortError(err))
+                    onError(err);
+            }
+            finally {
+                sub.done = true;
+            }
+        })();
+    }
+    const reconcile = async () => {
+        if (inFlight)
+            return; // never overlap reconciles
+        inFlight = true;
+        try {
+            const ids = getIds();
+            const active = new Set(ids);
+            // Abort and drop subscriptions for projects no longer active.
+            for (const [id, sub] of subs) {
+                if (!active.has(id)) {
+                    sub.controller.abort();
+                    subs.delete(id);
+                    dirCache.delete(id);
+                }
+            }
+            // Clean up dir cache for inactive projects.
+            for (const id of [...dirCache.keys()])
+                if (!active.has(id))
+                    dirCache.delete(id);
+            for (const projectId of ids) {
+                try {
+                    let dir = dirCache.get(projectId);
+                    if (dir === undefined) {
+                        dir = await resolveDir(projectId);
+                        dirCache.set(projectId, dir);
+                    }
+                    if (!dir)
+                        continue;
+                    const existing = subs.get(projectId);
+                    if (existing) {
+                        // If the loop exited (e.g. after an error), restart from the stored cursor.
+                        if (existing.done) {
+                            startLoop(projectId, dir, existing.cursor);
+                        }
+                        // Otherwise the loop is still running — leave it alone.
+                    }
+                    else {
+                        // Newly-active project: start at the tail (no history replay).
+                        startLoop(projectId, dir, new Date().toISOString());
+                    }
+                }
+                catch (err) {
+                    onError(err);
+                }
+            }
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+    const stopAll = async () => {
+        for (const sub of subs.values())
+            sub.controller.abort();
+        subs.clear();
+        dirCache.clear();
+    };
+    return { reconcile, stopAll };
+}
+/**
+ * Start the mutation-event watcher. Returns a stop function, mirroring
+ * `startProjectWatcher`. Disabled entirely when `PM_REALTIME_MUTATION_EVENTS=false`.
+ */
+export function startMutationEventWatcher(deps = {}) {
+    if (process.env.PM_REALTIME_MUTATION_EVENTS === "false")
+        return () => undefined;
+    const reconcileMs = Math.max(MIN_RECONCILE_MS, deps.reconcileMs ?? positiveIntEnv("PM_MUTATION_EVENT_RECONCILE_MS", DEFAULT_RECONCILE_MS));
+    const onError = deps.onError ?? ((err) => console.error("Mutation-event watcher reconcile failed", err instanceof Error ? err.message : err));
+    const { reconcile, stopAll } = createMutationEventReconciler({ ...deps, onError });
+    const timer = setInterval(() => { void reconcile().catch(onError); }, reconcileMs);
+    timer.unref();
+    return () => {
+        clearInterval(timer);
+        void stopAll();
+    };
+}
+//# sourceMappingURL=mutation-event-watcher.js.map

package/dist/services/mutation-event-watcher.js.map

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

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

@@ -1,5 +1,5 @@
-import { PmCliError, EXIT_CODE, type GetItemAtResult } from "@unbrained/pm-cli/sdk";
-export { PmCliError, EXIT_CODE, type GetItemAtResult };
+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;
@@ -9,6 +9,22 @@ export declare class Semaphore {
 }
 export declare function projectsRoot(): string;
 export declare function getProjectDir(userId: string, slug: string): string;
+/**
+ * Resolve a project id to its on-disk directory, or `null` when the project row
+ * is genuinely absent.
+ *
+ * Shared by both out-of-band change detectors (the mutation-event subscription
+ * and the filesystem safety-net sweep), which each cache the result per active
+ * SSE session. It lives here because this module already owns the
+ * project-id → path mapping via {@link getProjectDir}.
+ *
+ * Database errors are deliberately **not** swallowed: a transient `pool.query`
+ * failure must reach the caller's per-project error handling so the lookup is
+ * retried. Returning `null` on failure would let a caller cache "no such
+ * project" for the whole session and permanently stop watching it. `null`
+ * therefore means "the row is absent", which is safe to cache.
+ */
+export declare function resolveProjectDir(projectId: string): Promise<string | null>;
 export declare function initProject(userId: string, slug: string, prefix: string): Promise<void>;
 export declare function projectExists(userId: string, slug: string): boolean;
 export interface PmRunOptions {
@@ -24,6 +40,8 @@ export interface PmRunResult {
     stderr: string;
     ok: boolean;
     parsed?: unknown;
+    /** pm CLI exit code from either the SDK dispatcher or spawned CLI fallback. */
+    exitCode?: number;
 }
 export interface EnsureGraphExtensionResult {
     ok: boolean;
@@ -32,6 +50,21 @@ export interface EnsureGraphExtensionResult {
     error?: string;
 }
 export declare function ensureGraphExtension(userId: string, slug: string): Promise<EnsureGraphExtensionResult>;
+/**
+ * Return a cached {@link PmClient} for a workspace pm-root, creating one on
+ * first use. The SDK owns extension activation and serialization internally;
+ * caching avoids reconstructing the immutable workspace defaults while each
+ * call still receives the SDK's current extension snapshot. Author identity is
+ * resolved by the SDK's default detection, preserving prior CLI behaviour.
+ */
+export declare function getPmClient(pmRoot: string): PmClient;
+/** Drop a cached client when its workspace is deleted. */
+export declare function evictPmClient(pmRoot: string): void;
+/**
+ * Read a workspace's parsed `settings.json` for the search-tuning resolvers.
+ * Returns `{}` when absent so resolvers fall back to their built-in defaults.
+ */
+export declare function readPmSettings(userId: string, slug: string): unknown;
 export declare function runPm(opts: PmRunOptions): Promise<PmRunResult>;
 /**
  * Reconstruct a single item at a one-based version or ISO timestamp using the

package/dist/services/pm-runner.js

@@ -1,10 +1,11 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { getItemAt, PmCliError, EXIT_CODE, } from "@unbrained/pm-cli/sdk";
+import { pool } from "../db.js";
+import { getItemAt, PM_TOOL_PARAMETERS_SCHEMA, PmClient, PmCliError, isPmCliExpectedError, EXIT_CODE, } from "@unbrained/pm-cli/sdk";
 // 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, EXIT_CODE };
+export { PmCliError, isPmCliExpectedError, EXIT_CODE };
 const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
 const MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
 function positiveInteger(value, fallback) {
@@ -54,6 +55,28 @@ const PM_GRAPH_EXTENSION_PATH = process.env.PM_GRAPH_EXTENSION_PATH ||
 export function getProjectDir(userId, slug) {
     return path.join(projectsRoot(), userId, slug);
 }
+/**
+ * Resolve a project id to its on-disk directory, or `null` when the project row
+ * is genuinely absent.
+ *
+ * Shared by both out-of-band change detectors (the mutation-event subscription
+ * and the filesystem safety-net sweep), which each cache the result per active
+ * SSE session. It lives here because this module already owns the
+ * project-id → path mapping via {@link getProjectDir}.
+ *
+ * Database errors are deliberately **not** swallowed: a transient `pool.query`
+ * failure must reach the caller's per-project error handling so the lookup is
+ * retried. Returning `null` on failure would let a caller cache "no such
+ * project" for the whole session and permanently stop watching it. `null`
+ * therefore means "the row is absent", which is safe to cache.
+ */
+export async function resolveProjectDir(projectId) {
+    const res = await pool.query("SELECT user_id, slug FROM pm_projects WHERE id = $1", [projectId]);
+    const row = res.rows[0];
+    if (!row)
+        return null;
+    return getProjectDir(row.user_id, row.slug);
+}
 let cachedPmCommand;
 function pmCliCommand() {
     if (process.env.PM_CLI_BIN)
@@ -135,6 +158,7 @@ async function runProcess(cwd, args, options = {}) {
                 stdout: Buffer.concat(stdout).toString("utf8"),
                 stderr: failure ? `${stderrText}${stderrText ? "\n" : ""}${failure}` : stderrText,
                 ok: code === 0 && !failure,
+                exitCode: typeof code === "number" ? code : undefined,
             });
         });
         child.stdin.on("error", () => undefined);
@@ -278,15 +302,288 @@ export async function ensureGraphExtension(userId, slug) {
     }
     return { ok: true, installed: true, active: true };
 }
+// ---------------------------------------------------------------------------
+// In-process SDK dispatch
+// ---------------------------------------------------------------------------
+//
+// The per-request `pm` binary spawn was the single biggest scalability defect
+// in this package: every read/write of a workspace forked a node process, ran
+// the CLI bootstrap, and acquired file locks through the OS. The pm CLI SDK
+// (2026.7.26) exposes the same command runners the CLI uses as a typed,
+// in-process `PmClient`. We now dispatch latency-bounded actions through one
+// cached client configuration per workspace pm-root and retain the bounded
+// spawn path for unsupported or potentially long-running actions. The latter
+// prevents the SDK's process-wide activation queue from head-of-line blocking
+// unrelated workspaces (tracked upstream as unbraind/pm-cli#742).
+/**
+ * Actions that cannot be served by `PmClient.run` and must keep using the
+ * `pm` binary spawn. Each is documented with the concrete reason it is kept.
+ */
+const SPAWN_FALLBACK_ACTIONS = new Set([
+    // Semantic search can invoke remote providers. Keep it outside the SDK's
+    // process-wide activation queue until unbraind/pm-cli#742 is resolved.
+    "search",
+    // Bulk updates can touch many items and must not block unrelated workspaces
+    // behind the SDK's process-wide activation queue.
+    "update-many",
+    // Dependency/schema upgrades are long-running maintenance operations.
+    "upgrade",
+    // Linked acceptance suites execute arbitrary project commands and can run for
+    // minutes, so test-all must not occupy the process-wide SDK queue.
+    "test-all",
+    // Full validation, health diagnostics, and garbage collection scan workspace
+    // state and may invoke extension hooks or external checks.
+    "validate",
+    "health",
+    "gc",
+    // `pm guide` is a static help renderer with no SDK action.
+    "guide",
+    // Search-index rebuild is a long-running maintenance command not exposed as an SDK action.
+    "reindex",
+    // Workspace normalization is a maintenance command not exposed as an SDK action.
+    "normalize",
+    // Dedupe audit is a governance report not exposed as an SDK action.
+    "dedupe-audit",
+    // Comments audit is a governance report not exposed as an SDK action.
+    "comments-audit",
+    // Calendar rendering is a presentation command not exposed as an SDK action.
+    "calendar",
+    // Test-runs history is not exposed as an SDK action.
+    "test-runs",
+    // `pm templates list/show` is not a native SDK action.
+    "templates",
+    // `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
+    // out of scope for the spawn-removal hot path; plan stays on the spawn fallback.
+    "plan",
+    // pm-graph is an extension that emits its own JSON to stdout, which the graph
+    // routes `JSON.parse` directly. Running it through `PmClient.run` would change
+    // the result shape the routes depend on, so it stays on the spawn path.
+    "pm-graph",
+]);
+/**
+ * Per-positional option key mapping for actions whose CLI form takes positional
+ * arguments (e.g. `pm get <id>`, `pm restore <id> <target>`). `PmClient.run`
+ * takes a single options bag, so positionals must be mapped onto named keys.
+ * Actions not listed here take options only (positionals are not expected).
+ */
+const POSITIONAL_KEYS = {
+    init: ["prefix"],
+    get: ["id"],
+    update: ["id"],
+    close: ["id", "reason"],
+    delete: ["id"],
+    comments: ["id", "add"],
+    notes: ["id", "add"],
+    learnings: ["id", "add"],
+    test: ["id", "add"],
+    files: ["id"],
+    docs: ["id"],
+    deps: ["id"],
+    append: ["id", "body"],
+    restore: ["id", "target"],
+    claim: ["id"],
+    release: ["id"],
+    copy: ["id"],
+    focus: ["id"],
+    "start-task": ["id"],
+    "pause-task": ["id"],
+    "close-task": ["id", "reason"],
+    history: ["id"],
+    config: ["scope", "configAction", "key", "value"],
+};
+const PM_CLIENT_CACHE_MAX = positiveInteger(process.env.PM_WEB_PM_CLIENT_CACHE_MAX, 256);
+/** Bounded least-recently-used `PmClient` cache keyed by workspace pm-root. */
+const pmClientCache = new Map();
+/**
+ * Return a cached {@link PmClient} for a workspace pm-root, creating one on
+ * first use. The SDK owns extension activation and serialization internally;
+ * caching avoids reconstructing the immutable workspace defaults while each
+ * call still receives the SDK's current extension snapshot. Author identity is
+ * resolved by the SDK's default detection, preserving prior CLI behaviour.
+ */
+export function getPmClient(pmRoot) {
+    let client = pmClientCache.get(pmRoot);
+    if (client) {
+        pmClientCache.delete(pmRoot);
+        pmClientCache.set(pmRoot, client);
+        return client;
+    }
+    if (pmClientCache.size >= PM_CLIENT_CACHE_MAX) {
+        const leastRecentlyUsed = pmClientCache.keys().next().value;
+        if (typeof leastRecentlyUsed === "string")
+            pmClientCache.delete(leastRecentlyUsed);
+    }
+    client = new PmClient({
+        pmRoot,
+        cwd: path.dirname(path.dirname(pmRoot)),
+    });
+    pmClientCache.set(pmRoot, client);
+    return client;
+}
+/** Drop a cached client when its workspace is deleted. */
+export function evictPmClient(pmRoot) {
+    pmClientCache.delete(pmRoot);
+}
+/**
+ * Read a workspace's parsed `settings.json` for the search-tuning resolvers.
+ * Returns `{}` when absent so resolvers fall back to their built-in defaults.
+ */
+export function readPmSettings(userId, slug) {
+    const settingsPath = path.join(getProjectDir(userId, slug), ".agents", "pm", "settings.json");
+    try {
+        return JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Convert a kebab-case CLI flag name to the camelCase SDK option key.
+ *
+ * `PmClient.run` accepts single-word flag names as-is but **silently ignores**
+ * multi-word kebab names (e.g. `dry-run`, `include-body`, `filter-status`),
+ * which is catastrophic for boolean guards like `--dry-run`. The SDK option
+ * contract is camelCase, so `--filter-deadline-before` must become
+ * `filterDeadlineBefore`. Single-word names pass through unchanged.
+ */
+function kebabToCamel(flag) {
+    if (!flag.includes("-"))
+        return flag;
+    return flag.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+}
+/**
+ * Derive boolean option arity from the SDK's canonical action-scoped tool
+ * schema. This keeps the adapter aligned when pm adds an option and lets string
+ * values begin with `--` without being mistaken for another flag.
+ */
+function booleanOptionsByAction() {
+    const result = new Map();
+    const branches = PM_TOOL_PARAMETERS_SCHEMA.oneOf ?? [];
+    for (const branch of branches) {
+        const properties = branch.properties ?? {};
+        const action = properties["action"]?.const;
+        if (typeof action !== "string")
+            continue;
+        const keys = Object.entries(properties)
+            .filter(([, property]) => property.type === "boolean")
+            .map(([key]) => key);
+        result.set(action, new Set(keys));
+    }
+    return result;
+}
+const BOOLEAN_OPTIONS_BY_ACTION = booleanOptionsByAction();
+/**
+ * Parse a CLI-style argv tail (without the leading `--json` injected by the
+ * spawn path) into the action name, a camelCase options bag, and positionals.
+ * `--json` is dropped: the SDK returns structured objects, never JSON text.
+ */
+function parsePmArgs(args) {
+    const action = args[0] ?? "";
+    const booleanOptions = BOOLEAN_OPTIONS_BY_ACTION.get(action) ?? new Set();
+    const options = {};
+    const positionals = [];
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            continue;
+        if (arg === "--") {
+            while (++i < args.length)
+                positionals.push(args[i]);
+            break;
+        }
+        if (arg.startsWith("--no-")) {
+            options[kebabToCamel(arg.slice(5))] = false;
+        }
+        else if (arg.startsWith("--")) {
+            const equalsIndex = arg.indexOf("=");
+            const rawFlag = arg.slice(2, equalsIndex === -1 ? undefined : equalsIndex);
+            const key = kebabToCamel(rawFlag);
+            if (equalsIndex !== -1) {
+                options[key] = arg.slice(equalsIndex + 1);
+                continue;
+            }
+            if (booleanOptions.has(key)) {
+                options[key] = true;
+                continue;
+            }
+            const next = args[i + 1];
+            if (next !== undefined) {
+                options[key] = next;
+                i++;
+            }
+            else {
+                options[key] = true;
+            }
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    return { action, options, positionals };
+}
+/** Merge mapped positionals onto the options bag for `PmClient.run`. */
+function withPositionals(action, positionals, options) {
+    const keys = POSITIONAL_KEYS[action];
+    if (!keys)
+        return options;
+    const merged = { ...options };
+    for (let i = 0; i < keys.length && i < positionals.length; i++) {
+        merged[keys[i]] = positionals[i];
+    }
+    return merged;
+}
+/**
+ * Dispatch a supported action in-process through {@link PmClient}.
+ *
+ * Supported actions go through the generic `client.run(action, {options})`
+ * dispatcher, which accepts native and extension-contributed actions alike.
+ *
+ * The result object is returned both as `parsed` (structured) and stringified
+ * into `stdout`, so routes that read either field keep working.
+ */
+async function runPmInProcess(opts, dir) {
+    const pmRoot = path.join(dir, ".agents", "pm");
+    const client = getPmClient(pmRoot);
+    const { action, options, positionals } = parsePmArgs(opts.args);
+    try {
+        const result = await client.run(action, {
+            options: withPositionals(action, positionals, options),
+        });
+        const stdout = JSON.stringify(result) ?? "";
+        return { stdout, stderr: "", ok: true, parsed: result };
+    }
+    catch (err) {
+        if ((err instanceof PmCliError || isPmCliExpectedError(err)) &&
+            err.message.startsWith("Unsupported native pm action:")) {
+            return null;
+        }
+        if (err instanceof PmCliError || isPmCliExpectedError(err)) {
+            return { stdout: "", stderr: err.message, ok: false, parsed: undefined, exitCode: err.exitCode };
+        }
+        return { stdout: "", stderr: err instanceof Error ? err.message : String(err), ok: false, parsed: undefined };
+    }
+}
 export async function runPm(opts) {
     const dir = getProjectDir(opts.userId, opts.slug);
+    const action = opts.args[0] ?? "";
+    // Supported actions run in-process through the cached PmClient — no spawn.
+    if (!SPAWN_FALLBACK_ACTIONS.has(action) &&
+        opts.input === undefined &&
+        opts.timeoutMs === undefined) {
+        const sdkResult = await runPmInProcess(opts, dir);
+        if (sdkResult)
+            return sdkResult;
+    }
+    // Fallback: spawn the pm binary for actions the SDK dispatcher cannot serve.
     const args = opts.jsonOutput ? ["--json", ...opts.args] : opts.args;
     const result = await runSerialized(dir, () => runProcess(dir, args, {
         input: opts.input,
         timeoutMs: opts.timeoutMs,
         env: { PM_GRAPH_PROJECT_KEY: `${opts.userId}:${opts.slug}` },
     }));
-    const { stdout, stderr, ok } = result;
+    const { stdout, stderr, ok, exitCode } = result;
     let parsed;
     if (opts.jsonOutput && ok && stdout) {
         try {
@@ -296,7 +593,7 @@ export async function runPm(opts) {
             parsed = { raw: stdout };
         }
     }
-    return { stdout, stderr, ok, parsed };
+    return { stdout, stderr, ok, parsed, exitCode };
 }
 /**
  * Reconstruct a single item at a one-based version or ISO timestamp using the
@@ -317,6 +614,7 @@ export async function runGetItemAt(userId, slug, itemId, ref) {
 }
 export function deleteProjectDir(userId, slug) {
     const dir = getProjectDir(userId, slug);
+    evictPmClient(path.join(dir, ".agents", "pm"));
     if (fs.existsSync(dir)) {
         fs.rmSync(dir, { recursive: true, force: true });
     }