@unbrained/pm-cli 2026.9.23 → 2026.9.26

package/docs/SEARCH_QUALITY.md

@@ -0,0 +1,116 @@
+# Semantic Batching and Retrieval Quality
+
+Tracked by [pm-vjgqj5](../.agents/pm/issues/pm-vjgqj5.toon) and
+[pm-p1g43q](../.agents/pm/features/pm-p1g43q.toon).
+
+## Agent Quick Context
+
+Use `pm reindex --mode semantic --progress` to refresh stale embeddings and
+`pm eval --queries ./queries.json --k 10` to measure retrieval. A successful
+index refresh proves that vectors were written, not that relevant items rank
+well. Evaluate quality separately.
+
+## Independent Input and Request Limits
+
+The built-in scheduler preserves `search.embedding_batch_size` as the maximum
+number of input positions per planned batch. Per-input text truncation still
+uses `search.embedding_corpus_max_characters` or the provider default.
+
+Requests additionally have a 256 KiB encoded JSON byte ceiling. This counts
+UTF-8, JSON escaping, array separators, and model metadata; it is independent of
+the per-input character limit. OpenAI's single-string encoding and duplicate
+input elimination can make the actual payload smaller than this conservative
+planning bound. An individual input that cannot fit is refused before any
+request is sent. Empty inputs are also refused rather than silently shifting
+vector positions.
+
+SDK hosts may supply `maxRequestBytes` to
+`executeEmbeddingBatchesWithRetry`, exported by
+`@unbrained/pm-cli/sdk/query`. The request ceiling is a transport
+bound, not a model tokenizer or context-window claim. Model input limits remain
+provider-owned. [Ollama's embedding API](https://docs.ollama.com/api/embed)
+accepts arrays of inputs and describes its own context truncation behavior.
+
+HTTP 413 and timeout failures split a multi-input batch in half. Both halves
+complete in source order. Other failures use the configured bounded retry
+policy. A singleton failure terminates the operation; failed execution never
+returns a partial vector array. Sequential execution avoids creating a burst
+of concurrent requests against a local embedding model.
+
+HTTP status takes precedence over response text: a non-413 error containing
+the word "timeout" does not trigger splitting. For a planned batch of `n`
+positions, binary subdivision creates at most `2n - 1` request nodes, each
+with at most `scanner_max_batch_retries + 1` attempts. SDK hosts accepting
+untrusted workloads should constrain corpus size, retry settings and the
+caller-supplied byte ceiling to their provider budget; this primitive does not
+impose a universal account-level quota.
+
+`pm reindex` exposes `semantic.batching` for built-in providers:
+
+- `planned_batches` counts batches before adaptation;
+- `requests`, `successful_batches`, `split_batches`, and `retries` describe
+  actual execution;
+- `batch_size_histogram` counts successful requests by input positions;
+- `elapsed_ms` and `inputs_per_second` include retry backoff;
+- `provider`, `model`, `max_request_bytes`, and `limit_source` explain the run.
+
+These receipts contain no input text, credentials, or endpoint addresses.
+Empty work retains the existing empty result; extension providers do not
+receive a fabricated built-in batching receipt.
+
+## Per-query Quality Floors
+
+A golden query may declare a `minimum` object containing any of `ndcg`, `mrr`,
+`precision`, and `recall`. Each value must be a finite number in `[0, 1]`.
+Unknown metric names fail validation so a spelling error cannot remove a gate.
+
+```json
+[
+  {
+    "query": "snapshot restore durability",
+    "relevant_ids": ["pm-snapshot", "pm-restore"],
+    "mode": "keyword",
+    "minimum": { "recall": 0.5, "mrr": 0.5 }
+  }
+]
+```
+
+Replace the example IDs with judgments from your workspace. `pm eval` compares
+unrounded scores to these floors and reports `violations` on the affected query.
+It exits nonzero if any floor fails, even when no `--fail-under` is supplied or
+the aggregate nDCG passes. Existing query sets without floors retain their
+aggregate-only behavior. The public query SDK exports `parseEvalMetricFloors`
+and `evaluateMetricFloors` for package-owned evaluations.
+
+The repository's `quality:retrieval-eval` gate also pins floors by query text
+and retrieval mode. Missing, unexpected or duplicated identities and mismatched
+declared row counts fail. Explicit
+`--update` refreshes never lower a prior floor or discard a missing required
+query. A baseline update is a reviewed policy change; it is not permission to
+change relevance judgments until a score turns green.
+
+## Verification Boundaries
+
+Real loopback HTTP tests exercise batching, Unicode payloads, 413 recovery,
+vector ordering, and pre-dispatch refusal. Evaluator tests exercise the case
+where the macro average passes while one query fails. These are transport and
+quality-contract proofs, not measured million-item model throughput, semantic
+ranking improvements, parallel scheduling, or durable partial-run resume.
+Those broader acceptance criteria remain tracked by the linked items.
+
+## Portable Delivery Evidence
+
+Workspace-owned custom types used by delivery records must be declared in the
+tracked project schema. An ignored local extension installation does not make
+its types available to a fresh CI checkout. This repository declares `Changeset`
+in `schema/types.json` through `pm schema add-type`, and verifies changelog output
+in a clean checkout with only the published changelog package installed.
+
+Schema `--dry-run` applies to rename/remap migrations and workflow-policy
+actions. Other schema operations refuse the flag before writing, through the
+shared SDK guard used by CLI and SDK/MCP dispatch. For example,
+`pm schema rename-type Spike --to Experiment --dry-run` previews a migration;
+`pm schema add-type Spike --dry-run` is refused. Adding a type is an explicit
+write operation. Tracked by [pm-s74dca](../.agents/pm/issues/pm-s74dca.toon).
+SDK hosts can reuse `assertSchemaPreviewSupported(subcommand, dryRun)` from
+`@unbrained/pm-cli/sdk` when dispatching built-in schema operations.

package/docs/TESTING.md

@@ -88,6 +88,23 @@ so PR-local CodeFactor maintainability annotations fail locally before commit or
 push. Existing legacy high-complexity test fixtures are tracked separately and
 must not be used as precedent for new changed production/script code.
 
+The same required static gate validates an explicit seven-day Dependabot
+cooldown for every updater and requires both npm and GitHub Actions entries.
+Missing values, semver overrides outside 7–90 days, invalid YAML, removed
+updaters, and include/exclude bypasses fail the gate. The maximum follows
+[GitHub's cooldown limits](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/optimizing-pr-creation-version-updates).
+Security updates retain GitHub's separate security-update behavior.
+The negative controls are tracked by [pm-gkut](../.agents/pm/issues/pm-gkut.toon)
+and [pm-dmo5](../.agents/pm/issues/pm-dmo5.toon).
+
+Release synchronization and commit staging share one distribution manifest
+inventory. The [pm-t4prek regression](../tests/unit/scripts/release/version-manifests.spec.ts)
+bumps versions in a temporary Git repository and reads the resulting commit to
+verify workspace versions and exact plugin runtime pins. The pipeline checks
+version consistency immediately before staging, including required string
+versions and runtime pins in both plugin package manifests; tests of a prepared working
+tree alone cannot establish that the release commit contains those changes.
+
 `lint:duplicates` runs three zero-clone profiles: the broad repository profile,
 the production cross-format profile, and a supplemental long-table profile at
 28 lines / 80 tokens. The last profile detects the historical GH-508 normalizer

package/docs/VALIDATION_PORTABILITY.md

@@ -1,7 +1,8 @@
 # Completion portability and bounded replication checks
 
-Tracked by [pm-t6jl1f](../.agents/pm/issues/pm-t6jl1f.toon) and
-[pm-26y269](../.agents/pm/tasks/pm-26y269.toon).
+Tracked by [pm-t6jl1f](../.agents/pm/issues/pm-t6jl1f.toon),
+[pm-26y269](../.agents/pm/tasks/pm-26y269.toon), and
+[pm-eswzn9](../.agents/pm/tasks/pm-eswzn9.toon).
 
 ## Bash completion data boundary
 
@@ -13,10 +14,15 @@ elements to `COMPREPLY`. Candidates containing shell metacharacters or Unicode
 use portable single-quote syntax, including embedded quote escaping, so accepting
 a candidate and pressing Enter also preserves its literal argument value.
 
-Already quoted or backslash-escaped prefixes return no suggestions before optional
-completion initialization can remove their quoting. This conservative boundary
-avoids inserting an unquoted-context escape inside a different shell quoting
-context. Normal unquoted prefixes retain literal matching.
+The matcher decodes the current Readline word without evaluation. It recognizes
+open single quotes, open double quotes, and backslash-escaped prefixes. Each
+completion is encoded for its insertion context: apostrophes are split safely
+inside single quotes; dollar signs, backticks, backslashes, and double quotes
+are escaped inside double quotes; exclamation marks use a single-quoted segment
+so history expansion cannot change the accepted bytes. Unquoted prefixes keep
+the existing literal single-quote encoding for unsafe candidates. Mixed quoted
+segments whose replacement span is ambiguous, and prefixes containing typed
+backticks, still return no suggestions.
 
 The matcher never evaluates choices as shell programs. Dollar signs, backticks,
 quotes, backslashes, and wildcard characters remain literal. Unicode survives
@@ -37,9 +43,10 @@ and cache policy retain their existing contracts.
 `compgen -W` cannot safely serve as the data transport here: it performs another
 expansion pass, and Bash 3.2 does not round-trip the ANSI-C quoting emitted by
 `printf %q` for Unicode. Unquoted command-substitution arrays can additionally
-expand literal wildcard candidates into filenames. The regression executes the
-generated function and parses its accepted words with the real Bash parser,
-rather than inferring safety from source substrings.
+expand literal wildcard candidates into filenames. The regression checks the
+generated function and uses an interactive pseudo terminal to press Tab and
+Enter in each supported insertion context. It checks the accepted argument
+bytes and verifies that a command-substitution sentinel was not created.
 
 Run the focused native regression after building:
 
@@ -51,8 +58,10 @@ To test another installed Bash version, set `PM_COMPLETION_TEST_BASH` to its
 executable path. This is a test harness input, not a CLI configuration setting.
 The existing macOS runtime-smoke job pins `/bin/bash` so PATH cannot silently
 substitute a newer Homebrew Bash. It runs this regression before merge; Linux
-coverage runs the same matrix. Native Fish and Zsh acceptance remains in the
-required smoke gate.
+coverage runs the same matrix. The macOS test drives Bash through a Python 3
+pseudo terminal because BSD `script` requires terminal stdin; Linux uses
+`script`. Set `PM_COMPLETION_TEST_PTY=python` to exercise the macOS driver on
+Linux. Native Fish and Zsh acceptance remains in the required smoke gate.
 
 ## Replication diff collection
 

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.9.23"
+    "version": "2026.9.26"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.9.23",
+      "version": "2026.9.26",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -123,7 +123,7 @@
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
     "lint:duplicates": "jscpd --config .jscpd.json && jscpd --config .jscpd.source.json && jscpd --config .jscpd.tables.json",
     "lint:codefactor": "pnpm quality:static",
-    "quality:static": "pnpm quality:docstrings && pnpm quality:exports && pnpm lint:eslint && pnpm lint:duplicates && pnpm build && node scripts/contracts-snapshot.mjs --check && node scripts/generate-agent-capability-surfaces.mjs --check && node scripts/generate-error-code-catalog.mjs --check && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs && node scripts/release/refusal-closure-gate.mjs && node scripts/release/agent-task-token-gate.mjs && pnpm quality:mcp-deprecations && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded && pnpm quality:mutation -- --prebuilt",
+    "quality:static": "pnpm quality:docstrings && pnpm quality:exports && pnpm lint:eslint && pnpm lint:duplicates && node scripts/check-workflow-permissions.mjs && node scripts/check-dependency-cooldown.mjs && node scripts/gen-plugin-mcp-wrappers.mjs --check && pnpm build && node scripts/contracts-snapshot.mjs --check && node scripts/generate-agent-capability-surfaces.mjs --check && node scripts/generate-error-code-catalog.mjs --check && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs && node scripts/release/refusal-closure-gate.mjs && node scripts/release/agent-task-token-gate.mjs && pnpm quality:mcp-deprecations && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded && pnpm quality:mutation -- --prebuilt",
     "quality:exports": "knip --no-config-hints && node scripts/run-tests.mjs test -- tests/unit/scripts/release/dead-exports.spec.ts",
     "quality:command-grammar": "pnpm build && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs",
     "quality:recovery-closure": "pnpm build && node scripts/release/refusal-closure-gate.mjs",
@@ -167,6 +167,7 @@
     "smoke:external-packages": "node scripts/smoke-external-packages.mjs",
     "smoke:codex-plugin": "node scripts/smoke-codex-plugin-mcp.mjs",
     "smoke:claude-plugin": "node scripts/smoke-claude-plugin.mjs",
+    "smoke:plugin-cache": "node tests/acceptance/plugin-cache-smoke.mjs",
     "version:check": "node scripts/release-version.mjs check && node scripts/sync-versions.mjs check",
     "version:next": "node scripts/release-version.mjs next",
     "version:sync": "node scripts/sync-versions.mjs apply",
@@ -211,7 +212,7 @@
     "node": ">=22.18.0"
   },
   "dependencies": {
-    "@sentry/node": "10.75.0",
+    "@sentry/node": "10.75.1",
     "@toon-format/toon": "^4.1.1",
     "@types/node": ">=22",
     "commander": "^15.0.0",
@@ -238,13 +239,13 @@
     "fast-check": "^4.10.2",
     "github-slugger": "2.0.0",
     "greptile": "^3.5.3",
-    "jscpd": "^5.3.0",
+    "jscpd": "^5.3.1",
     "knip": "^6.37.0",
     "marked": "18.0.13",
     "parse5": "8.0.1",
     "tsx": "^4.23.15",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.70.0",
+    "typescript-eslint": "^8.70.1",
     "vitest": "^4.1.11"
   }
 }

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-vcs-sdk-exemplar",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",

package/plugins/pm-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pm-claude",
   "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
-  "version": "2026.9.23",
+  "version": "2026.9.26",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

package/plugins/pm-claude/README.md

@@ -11,7 +11,7 @@ Native pm CLI integration for Claude Code. Use pm project management tools direc
 | **14 slash commands** | Full lifecycle coverage — status, start, close, triage, audit, search, new, list, calendar, developer, planner, release, workflow, init |
 | **4 subagents** | `pm-coordinator` (batch/multi-item), `pm-triage-agent` (duplicate-safe item creation), `pm-verification-agent` (evidence + close readiness), and `pm-delivery-chain` (orchestrated delivery) |
 | **Hybrid TUI tracking** | pm items sync to Claude Code's task panel — pm is the persistent store, the task panel is the live session view |
-| **Session hook** | Injects active pm item summary at session start when pm is initialized (uses native modules, no CLI required) |
+| **Session hook** | Injects active pm item summary at session start using the same pinned pm-cli runtime as the MCP server |
 
 ## Installation
 
@@ -192,8 +192,9 @@ All skills and commands implement this pattern for every claimed item:
 
 ## Session Context Injection
 
-At session start, the hook runs the published `pm` CLI without requiring a global install:
-- Uses `npx --yes --package=@unbrained/pm-cli@latest pm context --limit 5 --json`
+At session start, the hook runs the plugin's exact-version `pm` CLI without requiring a global install:
+- Uses the version pinned in `plugins/pm-claude/package.json` and persisted in the plugin data directory
+- Reuses the installed runtime offline on later sessions
 - Injects a compact summary of in-progress/open/blocked items
 
 Example output:
@@ -215,8 +216,8 @@ Use pm_context tool or /pm-status for full details.
 
 ## Requirements
 
-- Node.js ≥ 20
-- pm CLI resolved automatically via local dist (in repo) or `npx --yes @unbrained/pm-cli@latest` (no global install needed)
+- Node.js ≥ 22.18.0
+- pm CLI resolved automatically from the plugin's pinned package installation (no global install needed)
 - Project initialized with `pm init` (or use `/pm-init`)
 
 ## Links

package/plugins/pm-claude/hooks/hooks.json

@@ -7,7 +7,7 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\"",
-            "timeout": 8,
+            "timeout": 130,
             "async": true
           }
         ]

package/plugins/pm-claude/hooks/session-start.mjs

@@ -3,12 +3,13 @@
  * pm-cli Claude Code session-start hook.
  *
  * Injects a brief pm context summary into the session when pm is initialized
- * in the current workspace. Uses the published pm CLI through npx without
+ * in the current workspace. Uses the plugin's exact-version runtime without
  * requiring a global install. Exits silently if pm is not set up.
  */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
+import { resolvePluginRuntime } from "../scripts/plugin-runtime.mjs";
 
 const workspace = process.cwd();
 const pmSettingsPath = join(workspace, ".agents", "pm", "settings.json");
@@ -40,10 +41,12 @@ function formatSummary(ctx) {
   );
 }
 
-function tryNpxContext() {
+async function readContext() {
   try {
-    const raw = execSync(
-      "npx -y --package=@unbrained/pm-cli@latest pm context --limit 5 --json",
+    const runtime = await resolvePluginRuntime();
+    const raw = execFileSync(
+      process.execPath,
+      [runtime.cli, "context", "--limit", "5", "--json"],
       {
         cwd: workspace,
         encoding: "utf-8",
@@ -58,7 +61,7 @@ function tryNpxContext() {
 }
 
 try {
-  const ctx = tryNpxContext();
+  const ctx = await readContext();
   if (!ctx) process.exit(0);
 
   const message = formatSummary(ctx);

package/plugins/pm-claude/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "pm-claude-runtime",
+  "private": true,
+  "type": "module",
+  "version": "2026.9.26",
+  "dependencies": {
+    "@unbrained/pm-cli": "2026.9.26"
+  }
+}

package/plugins/pm-claude/scripts/plugin-runtime.mjs

@@ -0,0 +1,84 @@
+/**
+ * Resolve the exact pm-cli runtime declared by a copied agent plugin.
+ * This file is copied into each plugin by gen-plugin-mcp-wrappers.mjs so a
+ * marketplace cache never needs to reach back into the repository checkout.
+ */
+import { spawnSync } from "node:child_process";
+import { access, mkdir, mkdtemp, readFile, rename, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pluginRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageName = "@unbrained/pm-cli";
+const versionPattern = /^[1-9]\d{3}\.[1-9]\d*\.[1-9]\d*(?:-[1-9]\d*)?$/;
+
+/** Require both the declared version and the executable shipped by that package. */
+async function installedRuntime(root, version) {
+  const packageRoot = path.join(root, "node_modules", "@unbrained", "pm-cli");
+  try {
+    const manifest = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
+    if (manifest.version !== version) return null;
+    const server = path.join(packageRoot, "dist", "mcp", "server.js");
+    const cli = path.join(packageRoot, "dist", "cli.js");
+    await access(server);
+    await access(cli);
+    return { server, cli, version };
+  } catch {
+    return null;
+  }
+}
+
+/** Install into a private staging directory and publish only a complete tree. */
+async function installRuntime(dataRoot, version, installer) {
+  await mkdir(dataRoot, { recursive: true });
+  const finalRoot = path.join(dataRoot, `v${version}`);
+  const existing = await installedRuntime(finalRoot, version);
+  if (existing) return existing;
+  const stagingRoot = await mkdtemp(path.join(dataRoot, `.install-${version}-`));
+  try {
+    const args = ["install", "--prefix", stagingRoot, "--no-save", "--ignore-scripts", "--no-audit", "--no-fund", "--package-lock=false", `${packageName}@${version}`];
+    const windows = process.platform === "win32";
+    // The command text contains only fixed tokens and a validated version.
+    // Put the caller-selected path in the child environment so cmd.exe never
+    // parses path metacharacters as command syntax.
+    const command = windows ? process.env.ComSpec || "cmd.exe" : "npm";
+    const commandArgs = windows
+      ? ["/d", "/v:off", "/s", "/c", `"npm.cmd ${args.map((arg) => arg === stagingRoot ? '"%PM_PLUGIN_STAGING_ROOT%"' : arg).join(" ")}"`]
+      : args;
+    const result = installer(command, commandArgs, {
+      encoding: "utf8", timeout: 120000, stdio: ["ignore", "pipe", "pipe"],
+      ...(windows ? { windowsVerbatimArguments: true, env: { ...process.env, PM_PLUGIN_STAGING_ROOT: stagingRoot } } : {}),
+    });
+    if (result.error || result.status !== 0 || !(await installedRuntime(stagingRoot, version))) {
+      throw new Error(`Cannot install ${packageName}@${version}: ${result.error?.message || result.stderr?.trim() || "incomplete package"}`);
+    }
+    try {
+      await rename(stagingRoot, finalRoot);
+    } catch (error) {
+      if (!(await installedRuntime(finalRoot, version))) {
+        throw new Error(`Plugin runtime at ${finalRoot} is incomplete; remove that directory and retry.`, { cause: error });
+      }
+    }
+    const runtime = await installedRuntime(finalRoot, version);
+    if (!runtime) throw new Error(`Plugin runtime at ${finalRoot} is incomplete; remove that directory and retry.`);
+    return runtime;
+  } finally {
+    await rm(stagingRoot, { recursive: true, force: true });
+  }
+}
+
+/** Resolve a copied plugin's runtime without ever consulting npm's latest tag. */
+export async function resolvePluginRuntime(options = {}) {
+  const root = options.pluginRoot ?? pluginRoot;
+  const plugin = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+  const version = plugin.dependencies?.[packageName];
+  if (typeof version !== "string" || !versionPattern.test(version) || plugin.version !== version) {
+    throw new Error(`Plugin ${plugin.name ?? root} needs an exact pm-cli dependency matching its version.`);
+  }
+  const bundled = await installedRuntime(root, version);
+  if (bundled) return bundled;
+  const dataRoot = process.env.PLUGIN_DATA || process.env.CLAUDE_PLUGIN_DATA ||
+    path.join(os.homedir(), ".cache", "pm-cli", "plugins", path.basename(root));
+  return installRuntime(dataRoot, version, options.installer ?? spawnSync);
+}