@unbrained/pm-cli 2026.8.25 → 2026.8.27

package/docs/SDK_MCP_INTERACTIONS.md

@@ -0,0 +1,227 @@
+# MCP Interaction and Task SDK
+
+Tracker references: [pm-rz9gep](../.agents/pm/features/pm-rz9gep.toon),
+[pm-rzs24j](../.agents/pm/features/pm-rzs24j.toon), and
+[pm-hv1x1x](../.agents/pm/features/pm-hv1x1x.toon). Transport and remote
+trust primitives are tracked by
+[pm-v7e337](../.agents/pm/features/pm-v7e337.toon) and
+[pm-3zh9s4](../.agents/pm/features/pm-3zh9s4.toon).
+
+The aggregate `@unbrained/pm-cli/sdk` entrypoint exposes transport-neutral
+contracts for MCP 2026-07-28 multi round-trip requests (MRTR), explicit cache
+policy, bounded JSON Schema 2020-12 validation, and the official durable tasks
+extension. A custom stdio or HTTP host can reuse these primitives without
+importing pm's executable server.
+
+## Request more host input
+
+Throw `PmMcpInputRequiredError` from domain code. The host adapter converts the
+signal into an `input_required` result after validating request method,
+payload bounds, and the request-local client capability.
+
+```ts
+import {
+  PmMcpInputRequiredError,
+  digestMcpRequestParameters,
+  sealMcpRequestState,
+} from "@unbrained/pm-cli/sdk";
+
+const requestState = sealMcpRequestState(
+  {
+    expiresAt: Date.now() + 5 * 60_000,
+    method: "tools/call",
+    parameterDigest: digestMcpRequestParameters({ name: "pm_mutate" }),
+    principal: "host-user-42",
+    state: { phase: "confirm" },
+  },
+  process.env.MCP_REQUEST_STATE_KEY!, // at least 32 bytes
+);
+
+throw new PmMcpInputRequiredError({
+  requestState,
+  inputRequests: {
+    confirmation: {
+      method: "elicitation/create",
+      params: {
+        mode: "form",
+        message: "Apply the proposed PM mutations?",
+        requestedSchema: {
+          type: "object",
+          properties: { approved: { type: "boolean" } },
+          required: ["approved"],
+        },
+      },
+    },
+  },
+});
+```
+
+Use `openMcpRequestState()` on retry to verify signature, expiry, original
+method, parameter digest, and principal. Call
+`PmMcpRequestStateReplayGuard.consume()` only after successful verification.
+The bundled guard provides bounded single-process replay detection; a
+multi-process host should persist the consumed state digest in its shared
+store. `parseMcpInputResponses()` validates and clones retry responses.
+
+The permitted input request methods are
+`elicitation/create`, `roots/list`, and `sampling/createMessage`. The client
+must advertise the corresponding capability on that same request.
+
+## Validate schemas and attach cache policy
+
+`validateMcpJsonSchema()` accepts object and boolean JSON Schema 2020-12 roots,
+resolves local JSON Pointer references, and applies byte, depth, and node work
+bounds. It returns a clone so callers cannot mutate the validated input by
+alias. External references remain identifiers; this validator does not perform
+network retrieval.
+
+```ts
+import {
+  validateMcpJsonSchema,
+  withMcpCachePolicy,
+} from "@unbrained/pm-cli/sdk";
+
+const inputSchema = validateMcpJsonSchema({
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  properties: { id: { type: "string" } },
+  required: ["id"],
+  additionalProperties: false,
+});
+
+const result = withMcpCachePolicy(
+  { tools: [{ name: "get_item", inputSchema }] },
+  { ttlMs: 30_000, cacheScope: "private" },
+);
+```
+
+Use `cacheScope: "private"` whenever a result depends on a workspace,
+principal, authorization decision, or user data. A `public` result must be
+safe for shared intermediaries and all principals for its full TTL.
+
+## Run durable extension tasks
+
+`createMcpTaskStore()` persists task records below the supplied tracker root's
+ignored `runtime/mcp-tasks` directory. It creates the durable record before
+returning a handle and serializes mutations with pm's cross-process lock.
+
+```ts
+import { createMcpTaskStore } from "@unbrained/pm-cli/sdk";
+
+const tasks = createMcpTaskStore({
+  pmRoot: "/workspace/project/.agents/pm",
+});
+
+const handle = await tasks.create({
+  principal: "host-user-42",
+  ttlMs: 60 * 60_000,
+  statusMessage: "Validating the workspace.",
+});
+
+try {
+  const result = await validateWorkspace();
+  await tasks.complete(handle.taskId, "host-user-42", result);
+} catch (error) {
+  await tasks.fail(handle.taskId, "host-user-42", {
+    code: -32603,
+    message: error instanceof Error ? error.message : "Validation failed",
+  });
+}
+```
+
+The lifecycle is `working` to `input_required`, `completed`, `failed`, or
+`cancelled`. `get()` applies retention expiry and restart recovery;
+`requireInput()` records MRTR requests; `update()` accepts matching responses;
+`takeInputResponses()` transfers them to a resumed worker; and `cancel()` is a
+cooperative state transition. Completed, failed, and cancelled records are
+immutable. Task ids and principal mismatches intentionally return the same
+not-found refusal to avoid disclosing another principal's work.
+
+The bundled `pm-mcp` server negotiates the extension through
+`io.modelcontextprotocol/tasks`. Eligible validation, health, graph, import,
+reindex, and test operations may return a task handle when the client requests
+asynchronous execution. Clients retrieve state with `tasks/get`, provide MRTR
+answers with `tasks/update`, and request cancellation with `tasks/cancel`.
+
+Task progress notifications and cross-transport request-scoped streams are a
+separate concern from change subscriptions. A client polls at `pollIntervalMs`
+for task state; `subscriptions/listen` carries only explicitly acknowledged
+tool, prompt, and resource changes.
+
+## Open change subscriptions
+
+`PmMcpSubscriptionRegistry` is transport-neutral. A stdio or HTTP adapter
+opens a record with the `subscriptions/listen` JSON-RPC id, requested filter,
+and an asynchronous sink. The registry sends the acknowledgment before any
+other notification, intersects filters with advertised server capabilities,
+tags every notification with the subscription id, and awaits each sink so
+transport backpressure is visible.
+
+```ts
+import { PmMcpSubscriptionRegistry } from "@unbrained/pm-cli/sdk";
+
+const subscriptions = new PmMcpSubscriptionRegistry({
+  capabilities: { resources: { listChanged: true, subscribe: true } },
+  serverInfo: { name: "custom-pm-host", version: "1.0.0" },
+});
+
+await subscriptions.open({
+  id: "workspace-changes",
+  notifications: {
+    resourcesListChanged: true,
+    resourceSubscriptions: ["pm://workspace/context"],
+  },
+  sink: async (notification) => sendOnTransport(notification),
+});
+
+await subscriptions.emitResourceUpdated("pm://workspace/context");
+```
+
+Closing returns the final modern result envelope. Abrupt disconnects should
+delete the record without fabricating a replay cursor or redelivery promise.
+
+## Project and validate HTTP headers
+
+`buildMcpHttpRequestHeaders()` constructs the required protocol, method, and
+name headers from a request. `validateMcpHttpRequestHeaders()` checks the
+received headers against both the JSON-RPC body and a tool's input schema.
+`collectMcpHeaderAnnotations()` exposes the validated `x-mcp-header` mapping
+when a custom adapter needs to inspect it.
+
+Header values are strings, numbers, or booleans. The SDK Base64-encodes values
+that cannot be represented unambiguously and rejects control bytes, reserved
+MCP names, duplicate mappings, undeclared arguments, and body/header
+mismatches. Never copy arbitrary client headers into tool arguments.
+
+## Compose remote authorization
+
+Use `buildMcpProtectedResourceMetadata()` for RFC 9728 metadata,
+`buildMcpAuthorizationDiscoveryUrls()` and
+`validateMcpAuthorizationServerMetadata()` for exact issuer discovery, and
+`selectMcpClientRegistrationMode()` to prefer Client ID Metadata Documents
+over deprecated Dynamic Client Registration. Store credentials with
+`PmMcpIssuerCredentialStore`; its exact issuer key prevents cross-issuer
+reuse and its cloned values prevent alias mutation.
+
+At the resource boundary, `authorizeMcpHttpRequest()` accepts bearer tokens
+only in the Authorization header and verifies issuer, audience, and required
+scopes through a host-provided verifier. `extractMcpTraceContext()` validates
+W3C trace fields and retains only allowlisted baggage before
+`runWithMcpTraceContext()` creates a concurrent-request-local scope.
+
+See [MCP remote transport, authorization, and migration](MCP_REMOTE_TRANSPORT_SECURITY.md)
+for executable configuration, lifecycle policy, and the threat model.
+
+## Failure and trust boundaries
+
+- Keep signing keys outside request data and logs; rotate them using a bounded
+  overlap strategy owned by the host.
+- Bind continuation state and tasks to an authenticated principal chosen by
+  the host, never to a caller-supplied display name.
+- Treat `ttlMs` as retention/freshness policy, not proof that underlying data
+  is unchanged.
+- A worker lost across process restart becomes a terminal, non-recoverable task
+  result. Create a new task instead of replaying side effects implicitly.
+- The task store is durable local coordination, not a distributed queue. A
+  multi-host deployment should implement the same public lifecycle on a
+  shared transactional backend.

package/docs/TESTING.md

@@ -443,6 +443,10 @@ context. This preserves source isolation without copying an unrelated tracker
 into constrained temporary storage.
 Capacity, permission, and resource failures while seeding a required tracker
 surface as typed, path-redacted host-environment refusals with recovery steps.
+When a legacy source tracker has settings but no `_workspace` history, tracker
+mode creates the sandbox's initial audited settings snapshot from the exact
+source bytes. Existing source workspace history is copied unchanged, including
+real drift, so linked validation never masks a source integrity failure.
 
 ## Source Workspace Modes
 

package/docs/generated/AGENT_CAPABILITY_ROUTING.md

@@ -14,4 +14,4 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | graph | `graph`, `deps`, `plan` |
 | quality | `test`, `test-all`, `validate`, `assurance`, `contracts` |
 | automation | `meet`, `event`, `remind` |
-| extensions | `extension`, `package`, `packages`, `install`, `upgrade` |
+| extensions | `package` |

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -4,14 +4,14 @@ Tracker: `pm-f05lsg`.
 
 Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.
 
-- Catalog error codes: 342
-- Executable error codes: 16
-- Executable-code ratchet floor: 16
-- Required executable canonical codes: `bulk_ids_input_empty`, `bulk_ids_input_missing_path`, `bulk_ids_input_unreadable`, `invalid_argument_value`, `missing_lifecycle_target`, `missing_required_argument`, `projection_options_mutually_exclusive`, `tracker_not_initialized`, `tracker_root_missing`, `tracker_root_not_directory`, `tracker_root_unreadable`, `unknown_context_intent`, `unknown_field_projection`, `unknown_option`, `unknown_subcommand`
-- Uncovered error codes: 326
-- Coverage fraction: 0.046784
-- Closed-domain probes: 18
-- Grammar probes: 95
+- Catalog error codes: 344
+- Executable error codes: 19
+- Executable-code ratchet floor: 18
+- Required executable canonical codes: `bulk_ids_input_empty`, `bulk_ids_input_missing_path`, `bulk_ids_input_unreadable`, `invalid_argument_value`, `manifest_unknown_key`, `missing_lifecycle_target`, `missing_required_argument`, `no_version_bounds_declared`, `projection_options_mutually_exclusive`, `tracker_not_initialized`, `tracker_root_missing`, `tracker_root_not_directory`, `tracker_root_unreadable`, `unknown_context_intent`, `unknown_field_projection`, `unknown_option`, `unknown_subcommand`
+- Uncovered error codes: 325
+- Coverage fraction: 0.055233
+- Closed-domain probes: 19
+- Grammar probes: 94
 
 | Error code | Canonical code | Disposition | Evidence kinds | Probe count |
 | --- | --- | --- | --- | --- |
@@ -175,9 +175,10 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `locks_unreadable` | `locks_unreadable` | uncovered | none | 0 |
 | `malformed_plan_step_evidence` | `malformed_plan_step_evidence` | uncovered | none | 0 |
 | `manifest_capabilities_absent` | `manifest_capabilities_absent` | uncovered | none | 0 |
-| `manifest_unknown_key` | `manifest_unknown_key` | uncovered | none | 0 |
+| `manifest_unknown_key` | `manifest_unknown_key` | executable | owned_state | 1 |
 | `mcp_annotation_file_unavailable` | `mcp_annotation_file_unavailable` | uncovered | none | 0 |
 | `mcp_stdin_unavailable` | `mcp_stdin_unavailable` | uncovered | none | 0 |
+| `mcp_task_not_found_or_not_authorized` | `mcp_task_not_found_or_not_authorized` | uncovered | none | 0 |
 | `merge_conflict_markers_detected` | `merge_conflict_markers_detected` | uncovered | none | 0 |
 | `merge_decisions_unreviewed` | `merge_decisions_unreviewed` | uncovered | none | 0 |
 | `merge_git_config_unwritable` | `merge_git_config_unwritable` | uncovered | none | 0 |
@@ -197,7 +198,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `missing_observed_signature` | `missing_observed_signature` | uncovered | none | 0 |
 | `missing_parameter_alias` | `missing_parameter_alias` | uncovered | none | 0 |
 | `missing_probe` | `missing_probe` | uncovered | none | 0 |
-| `missing_required_argument` | `missing_required_argument` | executable | grammar | 58 |
+| `missing_required_argument` | `missing_required_argument` | executable | grammar | 57 |
 | `missing_required_option` | `missing_required_option` | uncovered | none | 0 |
 | `missing_suggested_retry` | `missing_suggested_retry` | uncovered | none | 0 |
 | `missing_suggested_retry_args` | `missing_suggested_retry_args` | uncovered | none | 0 |
@@ -210,13 +211,14 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `no_test_files_found` | `no_test_files_found` | uncovered | none | 0 |
 | `no_tests_found` | `no_tests_found` | uncovered | none | 0 |
 | `no_update_fields` | `no_update_fields` | uncovered | none | 0 |
-| `no_version_bounds_declared` | `no_version_bounds_declared` | uncovered | none | 0 |
+| `no_version_bounds_declared` | `no_version_bounds_declared` | executable | owned_state | 1 |
 | `non_refusal_exit` | `non_refusal_exit` | uncovered | none | 0 |
 | `npm_package_not_found` | `npm_package_not_found` | uncovered | none | 0 |
 | `ownership_conflict` | `ownership_conflict` | uncovered | none | 0 |
 | `ownership_dependency_bypass_restricted_options` | `ownership_dependency_bypass_restricted_options` | uncovered | none | 0 |
 | `ownership_metadata_bypass_restricted_options` | `ownership_metadata_bypass_restricted_options` | uncovered | none | 0 |
 | `package_spec_empty` | `package_spec_empty` | uncovered | none | 0 |
+| `package_upgrade_modes_mutually_exclusive` | `package_upgrade_modes_mutually_exclusive` | executable | closed_domain | 1 |
 | `positional_shape_budget_exceeded` | `positional_shape_budget_exceeded` | uncovered | none | 0 |
 | `positional_signature_mismatch` | `positional_signature_mismatch` | uncovered | none | 0 |
 | `profile_name_empty` | `profile_name_empty` | uncovered | none | 0 |

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.8.25"
+    "version": "2026.8.27"
   },
   "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.8.25",
+      "version": "2026.8.27",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.25",
+  "version": "2026.8.27",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -16,7 +16,8 @@
   "bin": {
     "pm-cli": "dist/cli.js",
     "pm": "dist/cli.js",
-    "pm-mcp": "dist/mcp/server.js"
+    "pm-mcp": "dist/mcp/server.js",
+    "pm-mcp-http": "dist/mcp/http-server.js"
   },
   "types": "dist/sdk/index.d.ts",
   "exports": {
@@ -103,6 +104,7 @@
     "scripts/finalize-build.mjs",
     "scripts/install.sh",
     "scripts/install.ps1",
+    ".agents/skills/**",
     "scripts/prepare-build-cache.mjs",
     "marketplace.json"
   ],
@@ -120,7 +122,7 @@
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
     "lint:duplicates": "jscpd --config .jscpd.json",
     "lint:codefactor": "pnpm quality:static",
-    "quality:static": "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 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",
+    "quality:static": "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 && 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",
     "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",
     "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
@@ -139,6 +141,7 @@
     "quality:absence-tolerance": "node scripts/release/absence-tolerance-gate.mjs",
     "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
     "quality:docs-links": "node scripts/release/docs-skills-gate.mjs --links-only",
+    "quality:mcp-deprecations": "node --input-type=module --eval 'import { main } from \"./scripts/release/mcp-deprecation-inventory.mjs\"; await main()'",
     "quality:defect-evidence": "pnpm build && node scripts/release/defect-evidence-gate.mjs",
     "quality:hosted-analysis": "node scripts/release/hosted-analysis-gate.mjs",
     "benchmark:scale:generate": "node scripts/bench/scale-workspace.mjs",
@@ -165,7 +168,7 @@
     "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",
-    "changelog:pm:install": "node dist/cli.js install npm:pm-changelog --project",
+    "changelog:pm:install": "node dist/cli.js package install npm:pm-changelog --project",
     "changelog:pm": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --exclude-tag changelog-exclude --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 --exclude-tag changelog-exclude --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm --check",
     "release:notes": "node scripts/generate-release-notes.mjs",
@@ -203,24 +206,26 @@
     "node": ">=22.18.0"
   },
   "dependencies": {
-    "@sentry/node": "10.70.0",
+    "@sentry/node": "10.71.0",
     "@toon-format/toon": "^4.1.1",
     "@types/node": ">=22",
     "commander": "^15.0.0",
     "fast-glob": "^3.3.3",
     "fast-json-patch": "^3.1.1",
     "npm-package-arg": "^13.0.2",
-    "tar": "7.5.22"
+    "tar": "7.5.22",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
+    "@modelcontextprotocol/ext-apps": "1.7.5",
     "@codspeed/vitest-plugin": "^5.7.1",
     "@eslint/js": "^10.0.1",
     "@sentry/cli": "^3.6.2",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.3.0",
     "@types/npm-package-arg": "^6.1.4",
     "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "0.28.2",
-    "eslint": "^10.9.0",
+    "eslint": "^10.9.1",
     "eslint-plugin-sonarjs": "^4.2.0",
     "eslint-plugin-unicorn": "^73.0.0",
     "fast-check": "^4.9.0",
@@ -228,8 +233,7 @@
     "jscpd": "^5.0.16",
     "tsx": "^4.23.12",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.67.0",
-    "vitest": "^4.1.11",
-    "yaml": "^2.9.0"
+    "typescript-eslint": "^8.68.0",
+    "vitest": "^4.1.11"
   }
 }

package/packages/pm-beads/README.md

@@ -1,10 +1,16 @@
 # pm Beads Package
 
-First-party pm package for importing Beads JSONL records.
+First-party pm package for lossless Beads migration through public pm SDK
+contracts. The importer preserves issue identity, comments, structured events,
+relationships, labels, and terminal closure evidence before reporting a
+complete count-parity receipt.
 
-```bash
-pm install ./packages/pm-beads --project
-pm beads import --file .beads/issues.jsonl
-```
+## Migration
 
-The package exposes the `beads import` extension command through the `pm.extensions` package manifest. Runtime sources are authored in TypeScript and shipped with JavaScript entry artifacts for Node extension loading.
+Use a current portable backup for lossless relational migration. The focused
+[migration guide](docs/MIGRATION.md) covers installation, source validation,
+ID preservation, legacy exports, parity receipts, and post-import checks.
+
+The package exposes the `beads import` extension command through the
+`pm.extensions` package manifest. Runtime sources are TypeScript and use only
+the published `@unbrained/pm-cli/sdk` surface.

package/packages/pm-beads/docs/MIGRATION.md

@@ -0,0 +1,53 @@
+# Beads Migration
+
+Tracker: [pm-tpwde6](../../../.agents/pm/issues/pm-tpwde6.toon)
+
+## Lossless portable-backup migration
+
+Install the package, create a current Beads portable backup, and import the
+backup directory without modifying the source project:
+
+```bash
+pm package install ./packages/pm-beads --project
+bd backup --force
+pm beads import --backup-dir .beads/backup --preserve-source-ids
+```
+
+Current Beads backups contain relational `issues.jsonl`, `comments.jsonl`,
+`events.jsonl`, `dependencies.jsonl`, and `labels.jsonl` files plus
+`backup_state.json`. The importer validates those files, their foreign keys,
+the backup counts, source-ID collisions, and every issue before the first pm
+write. Structural source failures therefore cannot leave a partially imported
+tracker; each later item commit also retains pm's normal lock and rollback
+guarantees.
+
+Successful output includes `complete: true`, source and imported counts for
+each relation, and an exact `id_mapping`. Source IDs are preserved only when
+they are safe path identifiers and do not collide case-insensitively with one
+another or with the target tracker. Comments remain comments, Beads events are
+stored as structured JSON notes, dependencies retain their source identity,
+label text is normalized to canonical lowercase pm tags, and a
+terminal Beads close reason becomes the pm resolution when no explicit source
+resolution exists.
+
+Verify representative records and the final tracker after import:
+
+```bash
+pm get Tokenwerk-A1
+pm comments Tokenwerk-A1
+pm validate --check-resolution --check-history-drift
+```
+
+## Legacy single-file import
+
+Older JSON/JSONL exports with embedded `comments`, `events`, `dependencies`,
+and `labels` remain supported:
+
+```bash
+pm beads import --file .beads/issues.jsonl
+```
+
+A current plain `bd export` that advertises `comment_count` but omits comment
+bodies is intentionally rejected before any write. Run `bd backup --force` and
+use `--backup-dir` instead so the migration cannot silently lose discussion or
+event history.

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

@@ -37,6 +37,7 @@ function toBeadsImportOptions(
 ): BeadsImportOptions {
   return {
     file: asOptionalString(options.file),
+    backupDir: asOptionalString(options.backupDir),
     author: global.author,
     message: asOptionalString(options.message),
     preserveSourceIds: asBoolean(options.preserveSourceIds),
@@ -69,6 +70,13 @@ export function activate(api: ExtensionApi): void {
           value_type: "string",
           description: "Path to the Beads JSONL source file.",
         },
+        {
+          long: "--backup-dir",
+          value_name: "path",
+          value_type: "string",
+          description:
+            "Path to a complete bd portable-backup directory with issue, event, comment, dependency, label, and count files.",
+        },
         {
           long: "--message",
           value_name: "text",