@unbrained/pm-cli 2026.10.7 → 2026.10.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +32 -0
  3. package/dist/cli/register-list-query.js +2 -2
  4. package/dist/cli-bundle/bundle-manifest.json +154 -154
  5. package/dist/cli-bundle/chunks/{chunk-DWH555SN.js → chunk-55MK3QQM.js} +30 -30
  6. package/dist/cli-bundle/chunks/chunk-5MOFELIF.js +3 -0
  7. package/dist/cli-bundle/chunks/{chunk-TON7H63A.js → chunk-5NR6TDYB.js} +53 -52
  8. package/dist/cli-bundle/chunks/chunk-5TCQ5J3V.js +234 -0
  9. package/dist/cli-bundle/chunks/{chunk-TG3IOQUG.js → chunk-CPZOW6L2.js} +2 -2
  10. package/dist/cli-bundle/chunks/chunk-E4XR5LKU.js +8 -0
  11. package/dist/cli-bundle/chunks/{chunk-MOXX7D3F.js → chunk-KOGF6O6W.js} +3 -3
  12. package/dist/cli-bundle/chunks/chunk-N7GKWO4G.js +2 -0
  13. package/dist/cli-bundle/chunks/{chunk-VU77O6HC.js → chunk-NIF7JOPW.js} +2 -2
  14. package/dist/cli-bundle/chunks/{chunk-N2PFAWVV.js → chunk-P5NS7EFC.js} +3 -3
  15. package/dist/cli-bundle/chunks/{chunk-A4QWRU7D.js → chunk-QQHNXCO3.js} +5 -5
  16. package/dist/cli-bundle/chunks/chunk-XW3BLWFF.js +20 -0
  17. package/dist/cli-bundle/chunks/chunk-ZNXRGATT.js +2 -0
  18. package/dist/cli-bundle/chunks/register-list-query-2YOWMNWY.js +11 -0
  19. package/dist/cli-bundle/chunks/{register-mutation-JRH6EGSE.js → register-mutation-ILOWFMTV.js} +2 -2
  20. package/dist/cli-bundle/chunks/register-operations-BMK65YM3.js +2 -0
  21. package/dist/cli-bundle/chunks/register-setup-24TFFK6N.js +2 -0
  22. package/dist/cli-bundle/focused-chunks/{chunk-7X3QD5V4.js → chunk-2ATAD56F.js} +2 -2
  23. package/dist/cli-bundle/focused-chunks/{chunk-PBNQZV33.js → chunk-2CJWTLQG.js} +2 -2
  24. package/dist/cli-bundle/focused-chunks/{chunk-XIGFEA3W.js → chunk-362645PL.js} +2 -2
  25. package/dist/cli-bundle/focused-chunks/{chunk-4FKCHJGV.js → chunk-AU6VJGTY.js} +2 -2
  26. package/dist/cli-bundle/focused-chunks/{chunk-QY4Z23QC.js → chunk-B3YW6H2I.js} +17 -21
  27. package/dist/cli-bundle/focused-chunks/{chunk-3NSZ5C4A.js → chunk-DMSADMEU.js} +2 -2
  28. package/dist/cli-bundle/focused-chunks/chunk-DSLNUL2Q.js +20 -0
  29. package/dist/cli-bundle/focused-chunks/{chunk-EPOCI7ZX.js → chunk-EZ4367G4.js} +2 -2
  30. package/dist/cli-bundle/focused-chunks/{chunk-FWWFCLDM.js → chunk-IARAEFMA.js} +60 -59
  31. package/dist/cli-bundle/focused-chunks/{chunk-SIR5RFJX.js → chunk-MCVWZUGK.js} +27 -27
  32. package/dist/cli-bundle/focused-chunks/chunk-PBCYGO7X.js +3 -0
  33. package/dist/cli-bundle/focused-chunks/{chunk-NRSA5ZB2.js → chunk-PLTTMQAW.js} +2 -2
  34. package/dist/cli-bundle/focused-chunks/{chunk-HMG5F5EC.js → chunk-SAN3KPX4.js} +2 -2
  35. package/dist/cli-bundle/focused-chunks/{chunk-3BKRCR57.js → chunk-W5AE7GKZ.js} +2 -2
  36. package/dist/cli-bundle/focused-chunks/{chunk-QEYEDXRI.js → chunk-WAOXID5J.js} +2 -2
  37. package/dist/cli-bundle/focused-chunks/{chunk-2YICTWWA.js → chunk-WOEZJUA2.js} +2 -2
  38. package/dist/cli-bundle/main.js +2 -2
  39. package/dist/cli-bundle/sdk-authoring.js +1 -1
  40. package/dist/cli-bundle/sdk-contracts.js +1 -1
  41. package/dist/cli-bundle/sdk-core.js +22 -22
  42. package/dist/cli-bundle/sdk-governance.js +1 -1
  43. package/dist/cli-bundle/sdk-graph.js +1 -1
  44. package/dist/cli-bundle/sdk-merge.js +51 -50
  45. package/dist/cli-bundle/sdk-query.js +1 -1
  46. package/dist/cli-bundle/sdk-runtime.js +1 -1
  47. package/dist/cli-bundle/sdk-testing.js +1 -1
  48. package/dist/cli-bundle/sdk.js +7 -7
  49. package/dist/core/extensions/item-fields.d.ts +6 -1
  50. package/dist/core/extensions/item-fields.js +1 -1
  51. package/dist/core/fs/fs-utils.d.ts +19 -4
  52. package/dist/core/fs/fs-utils.js +2 -2
  53. package/dist/core/history/event-index.d.ts +1 -2
  54. package/dist/core/history/event-index.js +2 -2
  55. package/dist/core/lock/lock.d.ts +9 -2
  56. package/dist/core/lock/lock.js +2 -2
  57. package/dist/core/output/output.d.ts +16 -14
  58. package/dist/core/output/output.js +6 -10
  59. package/dist/core/store/item-metadata-query-index.d.ts +1 -2
  60. package/dist/core/store/item-metadata-query-index.js +1 -1
  61. package/dist/core/store/settings.js +2 -2
  62. package/dist/core/store/sqlite-runtime.d.ts +15 -0
  63. package/dist/core/store/sqlite-runtime.js +2 -0
  64. package/dist/core/telemetry/runtime.d.ts +1 -1
  65. package/dist/core/telemetry/runtime.js +4 -4
  66. package/dist/sdk/generated/generated-error-code-catalog-part-2.js +1 -1
  67. package/dist/sdk/governance/health.js +2 -2
  68. package/dist/sdk/history-repair.js +1 -1
  69. package/dist/sdk/item-transaction.js +1 -1
  70. package/dist/sdk/merge/abandoned-receipts.js +1 -1
  71. package/dist/sdk/merge/driver.js +1 -1
  72. package/dist/sdk/merge/install.js +3 -2
  73. package/dist/sdk/merge/receipt-operation.d.ts +5 -5
  74. package/dist/sdk/merge/receipt-operation.js +1 -1
  75. package/dist/sdk/merge/receipts.d.ts +1 -1
  76. package/dist/sdk/merge/receipts.js +3 -3
  77. package/dist/sdk/merge/worktree-config.d.ts +2 -0
  78. package/dist/sdk/merge/worktree-config.js +1 -1
  79. package/dist/sdk/output/table-rows.d.ts +37 -0
  80. package/dist/sdk/output/table-rows.js +2 -0
  81. package/dist/sdk/output.d.ts +1 -0
  82. package/dist/sdk/output.js +2 -2
  83. package/dist/sdk/public-surface.json +1 -1
  84. package/dist/sdk/read-output-contracts.d.ts +3 -3
  85. package/dist/sdk/read-output-contracts.js +1 -1
  86. package/dist/sdk/test/workspace-snapshot.d.ts +1 -1
  87. package/dist/sdk/test/workspace-snapshot.js +1 -1
  88. package/docs/AGENT_OUTPUT_ENCODINGS.md +119 -0
  89. package/docs/BUILD_AND_RELEASE_ACCEPTANCE.md +36 -100
  90. package/docs/MERGE_SAFETY.md +61 -6
  91. package/docs/PACKAGE_GATE_ACCEPTANCE.md +56 -0
  92. package/docs/PACKED_FIRST_RUN.md +26 -42
  93. package/docs/README.md +3 -0
  94. package/docs/SDK_AUDITED_MUTATIONS.md +18 -0
  95. package/docs/SDK_STORAGE_LIFECYCLE.md +35 -0
  96. package/docs/TESTING.md +11 -3
  97. package/docs/generated/REFUSAL_CLOSURE_CENSUS.md +4 -3
  98. package/marketplace.json +2 -2
  99. package/package.json +1 -1
  100. package/packages/pm-beads/package.json +1 -1
  101. package/packages/pm-calendar/package.json +1 -1
  102. package/packages/pm-command-kit/package.json +1 -1
  103. package/packages/pm-digital-twin/package.json +1 -1
  104. package/packages/pm-governance-audit/package.json +1 -1
  105. package/packages/pm-guide-shell/package.json +1 -1
  106. package/packages/pm-kanban/package.json +1 -1
  107. package/packages/pm-lifecycle-hooks/package.json +1 -1
  108. package/packages/pm-linked-test-adapters/package.json +1 -1
  109. package/packages/pm-search-advanced/package.json +1 -1
  110. package/packages/pm-templates/package.json +1 -1
  111. package/packages/pm-todos/package.json +1 -1
  112. package/packages/pm-vcs/package.json +1 -1
  113. package/plugins/pm-claude/.claude-plugin/plugin.json +1 -1
  114. package/plugins/pm-claude/package.json +2 -2
  115. package/plugins/pm-codex/.codex-plugin/plugin.json +1 -1
  116. package/plugins/pm-codex/package.json +2 -2
  117. package/plugins/pm-codex/plugin.json +1 -1
  118. package/runtime-dependencies.json +2 -2
  119. package/dist/cli-bundle/chunks/chunk-754AV3DC.js +0 -8
  120. package/dist/cli-bundle/chunks/chunk-CEM35QB2.js +0 -2
  121. package/dist/cli-bundle/chunks/chunk-CMIU2NDK.js +0 -20
  122. package/dist/cli-bundle/chunks/chunk-GJ2OJKRM.js +0 -238
  123. package/dist/cli-bundle/chunks/chunk-GSQK3VUT.js +0 -2
  124. package/dist/cli-bundle/chunks/chunk-WUOFG4JY.js +0 -3
  125. package/dist/cli-bundle/chunks/register-list-query-CBJELTDX.js +0 -11
  126. package/dist/cli-bundle/chunks/register-operations-FYV7CUBF.js +0 -2
  127. package/dist/cli-bundle/chunks/register-setup-M5VO6JUH.js +0 -2
  128. package/dist/cli-bundle/focused-chunks/chunk-3RJ4VK7U.js +0 -3
  129. package/dist/cli-bundle/focused-chunks/chunk-H5VREEUE.js +0 -20
@@ -74,7 +74,18 @@ Health and validation name `pm merge install` as the repair command for missing
74
74
  or drifted drivers. This upgrade behavior is tracked by
75
75
  [pm-rcjyft](../.agents/pm/issues/pm-rcjyft.toon).
76
76
 
77
- The installer publishes the shared `.gitattributes` fence only after the clone-local driver commands are configured. If the repository Git config is read-only or another Git process holds its lock, the command returns the stable `merge_git_config_unwritable` error with recovery guidance and leaves an absent fence absent. Use `pm merge install --dry-run --json` to inspect the contract in intentionally read-only workspaces.
77
+ The installer publishes the shared `.gitattributes` fence only after the
78
+ clone-local driver commands are configured. Matching definitions are read
79
+ without rewriting Git configuration. Concurrent pm installers coordinate
80
+ through a clone-local lock shared by its worktrees. Each required Git write
81
+ waits up to five seconds for Git's native config-file lock, with capped backoff;
82
+ it never removes another writer's lock. Persistent contention, malformed
83
+ configuration, and permission failures return the stable
84
+ `merge_git_config_unwritable` error with recovery guidance and leave an absent
85
+ fence absent. This behavior is tracked by
86
+ [pm-gh1424](../.agents/pm/issues/pm-gh1424.toon).
87
+ Use `pm merge install --dry-run --json` to inspect the contract in
88
+ intentionally read-only workspaces.
78
89
 
79
90
  ### Independent worktree runtimes
80
91
 
@@ -177,7 +188,20 @@ and `hash_only`, while the clone-local receipt remains `clone_local`. This lets
177
188
  a fresh-clone reviewer recover ordinary control-plane decisions without
178
189
  publishing titles, descriptions, custom statuses, or other potentially private
179
190
  content. When both copies exist the SDK deduplicates them and prefers the
180
- locally recoverable copy:
191
+ locally recoverable values. After immutable provenance matches, durable
192
+ reconciled state takes precedence over a stale clone-local pending copy only
193
+ when verified item history contains a sealed `merge_reconcile` event with the
194
+ same complete receipt summary and disposition. An absent, unreadable, invalid,
195
+ unsealed, or mismatched audit keeps the receipt pending in memory; inspection
196
+ rewrites neither receipt nor history. History is verified once per affected
197
+ item in each receipt scan.
198
+ Copy provenance includes normalized `requested_preference_applied`, so copies
199
+ that disagree on whether preference participated cannot share lifecycle state
200
+ even if history matches one copy. Inspection reports `copy_provenance_mismatch`,
201
+ and settlement refuses before either receipt is written. Legacy omission uses
202
+ the declared conflict policy's default participation value.
203
+ A local reconciled copy paired with a pending durable copy remains pending,
204
+ so an interrupted settlement can finish its durable write:
181
205
 
182
206
  ```bash
183
207
  pm merge report
@@ -249,18 +273,33 @@ does not recover the original private value.
249
273
 
250
274
  ## Receipts from an aborted rebase
251
275
 
252
- Tracked by [pm-466m0j](../.agents/pm/issues/pm-466m0j.toon). New receipts
253
- created during a rebase capture only its original commit and item blob in the
254
- typed `MergeReceiptOperation` contract. After aborting, run:
276
+ Tracked by [pm-466m0j](../.agents/pm/issues/pm-466m0j.toon) and
277
+ [pm-gh1405](../.agents/pm/issues/pm-gh1405.toon). New receipts created during a
278
+ merge or rebase capture only its operation kind, original commit, and item blob
279
+ in the typed `MergeReceiptOperation` contract. A plain merge captures these
280
+ before Git publishes `MERGE_HEAD`: Git must supply its `GITHEAD_<incoming object
281
+ ID>` driver environment signal, `HEAD` must equal `ORIG_HEAD`, and the
282
+ driver's ours input must hash to the item blob at that commit. Missing or
283
+ ambiguous coordinates are omitted. Matching origin references and bytes alone
284
+ cannot identify a plain merge: cherry-pick and revert also invoke content
285
+ drivers. Without Git's incoming-head signal, those receipts remain unresolved
286
+ and cannot receive a plain-merge abandonment audit. Branch labels from the
287
+ driver environment are never persisted. After aborting, run:
255
288
 
256
289
  ```bash
257
290
  pm merge reconcile --dry-run --json
258
- pm merge reconcile --message "Record restored original rebase state" --json
291
+ pm merge reconcile --message "Record restored original Git state" --json
259
292
  ```
260
293
 
294
+ SDK consumers that exhaustively handle `MergeReceiptOperation.kind` must
295
+ accept both `rebase` and `merge`. Existing rebase coordinates and receipt
296
+ version remain valid; no stored receipt migration is required.
297
+
261
298
  Settlement requires Git to have left every active merge/rebase/cherry-pick/revert
262
299
  operation, HEAD to match the original commit, and the item in HEAD, index, and
263
300
  working tree to match the original blob. The item history must already be clean.
301
+ Requiring the original HEAD also rules out a new commit incorporating the
302
+ abandoned merge's other branch.
264
303
  The history transaction rechecks the proof against its exact protected item
265
304
  snapshot. Apply appends an explicit `merge_reconcile` event with
266
305
  `abandoned_receipts` and the reason `original_git_state_restored`; it then marks
@@ -271,6 +310,22 @@ If receipt persistence fails after the audit commits, retry reuses the identical
271
310
  verified disposition and finishes the receipt writes without appending another
272
311
  audit event. An unrelated earlier audit does not satisfy this check.
273
312
 
313
+ The driver-created `merge-receipts/<receipt-id>.json` sidecar can remain
314
+ untracked after Git aborts. After reviewed settlement, commit that privacy-safe
315
+ sidecar together with the item's new history audit. Reconciliation preserves
316
+ the durable evidence for other worktrees instead of deleting the sidecar.
317
+
318
+ Applied-merge settlement has the same retry contract, tracked by
319
+ [pm-gh1390](../.agents/pm/issues/pm-gh1390.toon). The current item must still
320
+ satisfy authoritative receipt proof; only an identical receipt context in a
321
+ sealed event from reanchored, verified history suppresses a repeated provenance
322
+ event. Matching unsealed legacy context receives a new sealed audit while its
323
+ original entry remains intact. This also works with
324
+ durable-only evidence in another worktree. Once that worktree commits the
325
+ settled sidecar and history, a receiving worktree's stale local pending receipt
326
+ cannot reopen it. A subsequent `pm merge reconcile` leaves all three files
327
+ unchanged.
328
+
274
329
  Old receipts without operation coordinates remain pending for ordinary review.
275
330
  Tracked `merge-receipts/` sidecars are durable provenance and must remain tracked.
276
331
  Deleting or ignoring them would lose the evidence needed by other clones.
@@ -0,0 +1,56 @@
1
+ # Faithful package acceptance
2
+
3
+ Tracked by [pm-gh1391](../.agents/pm/issues/pm-gh1391.toon),
4
+ [pm-aiqmgj](../.agents/pm/issues/pm-aiqmgj.toon), and
5
+ [pm-dqej6b](../.agents/pm/issues/pm-dqej6b.toon), with scratch ancestry protection
6
+ tracked by [pm-runner-ancestor-tracker](../.agents/pm/issues/pm-runner-ancestor-tracker.toon).
7
+
8
+ Package tests that create their own disposable projects need an unset `PM_PATH`.
9
+ Otherwise a nested `pm init` follows the inherited tracker override and writes
10
+ outside the intended fixture. Use the shared SDK linked-test runner with a
11
+ disposable source snapshot:
12
+
13
+ ```bash
14
+ pm test <item-id> --add-json '{"command":"npm run release:check","pm_context_mode":"none","workspace_context_mode":"snapshot","timeout_seconds":900}'
15
+ pm test <item-id> --run --progress
16
+ ```
17
+
18
+ The same fields are supported by the SDK's `runTest` and MCP. See
19
+ [Testing](TESTING.md) for trust acknowledgements, assertions and run receipts.
20
+
21
+ Snapshots copy the current source files and keep root and nested `node_modules`
22
+ at their original relative paths. A Git workspace additionally receives an
23
+ independent clone of commit and tag objects, so release-tag checks and dependency
24
+ resolution work together. The clone uses no shared objects or source hooks,
25
+ does not inherit source-local Git configuration, and has no origin remote.
26
+ The internal remote name is explicit even with a custom `clone.defaultRemoteName`.
27
+ Its Git objects remain readable after the source checkout is removed.
28
+
29
+ The working tree excludes tracker and generated build/report directories.
30
+ Git objects contain repository history, including any historically tracked
31
+ files; a snapshot is an execution-isolation boundary, not a redaction mechanism.
32
+ Source aliases remain subject to containment checks. Installed dependency
33
+ directories are shared, so dependency-mutating tests need a separate installation.
34
+ Tests that depend on absolute checkout paths, source-local Git configuration,
35
+ submodule configuration, or exact dirty-status output must declare those
36
+ requirements separately. Cloning failures fail the linked run rather than
37
+ silently certifying a partial Git identity.
38
+
39
+ `PM_GLOBAL_PATH` remains isolated. `none` with a live source workspace and direct
40
+ PM commands remains refused. Existing command provenance and clone-local trust
41
+ checks still apply. The runner records the effective workspace and tracker
42
+ context on each execution so a green linked receipt identifies its boundary.
43
+ Repository acceptance also refuses scratch roots beneath any initialized
44
+ ancestor tracker before allocating fixtures, including external roots and
45
+ root-layout trackers. Choose a temporary hierarchy without workspace ancestry.
46
+
47
+ The optional SQLite accelerator filters Node's exact experimental announcement
48
+ only during synchronous native loading. Every other warning retains its original
49
+ arguments, and normal warning delivery is restored immediately, including after
50
+ a failed optional load. JSON refusals and clean mutation stderr therefore remain
51
+ usable on Node 22 and Node 24 without disabling application diagnostics.
52
+
53
+ The repository's scratch lifecycle keeps its original 15-second latency and
54
+ 3,000-token output limits. Vitest schedules it in a separate project after the
55
+ parallel contract suite. Functional assertions and the all-source coverage
56
+ denominator stay intact; a real latency regression still fails admission.
@@ -1,50 +1,34 @@
1
1
  # Packed First-Run Acceptance
2
2
 
3
- Tracked by [pm-ygli86](../.agents/pm/tasks/pm-ygli86.toon),
4
- [pm-rcjyft](../.agents/pm/issues/pm-rcjyft.toon), and
5
- [pm-07m41m](../.agents/pm/issues/pm-07m41m.toon).
3
+ Trackers: [pm-ygli86](../.agents/pm/tasks/pm-ygli86.toon),
4
+ [pm-rcjyft](../.agents/pm/issues/pm-rcjyft.toon),
5
+ [pm-07m41m](../.agents/pm/issues/pm-07m41m.toon),
6
+ [pm-p5u6](../.agents/pm/chores/pm-p5u6.toon).
6
7
 
7
- The `Packed first run` CI matrix installs the same tarball globally into an
8
- isolated npm prefix on Ubuntu, macOS, and Windows, using Node 22.18.0 and Node 24.
9
- It executes the installed `pm` shim before passing the installed package directory
10
- to the acceptance harness:
8
+ CI globally installs one tarball in isolated npm prefixes on Ubuntu/macOS/Windows
9
+ with Node 22.18.0 and 24, runs the installed `pm` shim, then invokes:
11
10
 
12
11
  ```bash
13
12
  node scripts/release/packed-first-run.mjs /path/to/installed/@unbrained/pm-cli
14
13
  ```
15
14
 
16
- The harness extracts the first three commands from the installed README's
17
- `60 Second Example` section. It executes `init`, `create`, and `list` in a
18
- temporary Git workspace, requires nonempty output below 4,096 characters per
19
- command, and checks that the created item was persisted. Missing sections,
20
- reordered commands, unsupported shell expressions, and unbalanced quotes fail.
21
- Arguments are passed directly to the installed CLI without a shell.
22
-
23
- Two branches then append independent comments through that CLI. A real Git merge
24
- must preserve both comments and their history. The installed reconciliation and
25
- strict history verifier must succeed. The installed MCP server must complete an
26
- initialize round trip and advertise the installed package version. An additional
27
- mutation enables telemetry only against a loopback HTTP collector. The harness
28
- acknowledges detached delivery batches until it receives `command_finish`, then
29
- verifies the physical queue is empty and a successful flush is recorded.
30
- One 30-second deadline covers the entire collection, including incomplete request
31
- bodies; an initial `command_start` batch alone cannot satisfy acceptance.
32
- It removes inherited inline-flush and
33
- test-runner overrides so this exercises the real detached process. Other commands
34
- and MCP keep telemetry disabled; the install and workspace use isolated home
35
- and global tracker directories.
36
-
37
- MCP cleanup waits for process closure before removing its workspace. It allows
38
- five seconds after SIGTERM, then sends SIGKILL and allows five more seconds. If
39
- the child still does not close, the harness fails with captured diagnostics and
40
- retains that workspace rather than attempting removal while it is in use.
41
-
42
- The separate runtime-upgrade regression installs drivers through an absolute
43
- runtime symlink, removes the original runtime directory, retargets the symlink,
44
- and performs a real Git merge. It verifies the upgrade failure from GitHub #1248
45
- without altering any developer runtime or repository.
46
-
47
- This matrix proves the packed artifact's first-run behavior. Registry propagation,
48
- npm/Bun installed agent sessions, npx/bunx execution, production telemetry, and
49
- previous-release compatibility remain separate acceptance claims under the
50
- [release workflow](RELEASING.md).
15
+ | Journey | Required observation |
16
+ | --- | --- |
17
+ | Installed README | Ordered init/create/list from `60 Second Example`; missing/reordered commands, unsupported expressions or unbalanced quotes fail. No shell execution. |
18
+ | Persistence | Each command returns nonempty output below 4,096 characters; the created item exists. |
19
+ | Branch merge | Independent comments survive a real Git merge; reconciliation and strict history verification succeed. |
20
+ | MCP | Initialization advertises the installed version. |
21
+ | Telemetry | A loopback collector receives detached `command_finish`; queue empties and successful flush persists. One 90-second deadline includes incomplete bodies; start alone cannot pass. |
22
+
23
+ Detached delivery removes inherited inline/test overrides; other commands/MCP
24
+ disable telemetry. Home/global roots are isolated. Interrupts stop stage admission
25
+ and collection, waiting five seconds for disposal. CLI errors await actual closure.
26
+ MCP waits five seconds after SIGTERM, then SIGKILL plus five more; failure retains
27
+ storage/diagnostics. [Storage lifecycle](SDK_STORAGE_LIFECYCLE.md) defines ownership
28
+ and abrupt-exit limits.
29
+
30
+ A separate #1248 regression removes/retargets an owned runtime symlink and performs
31
+ a real Git merge, preserving developer runtimes.
32
+
33
+ Registry propagation, npm/Bun sessions, npx/bunx, production telemetry and previous
34
+ compatibility have separate [release acceptance](BUILD_AND_RELEASE_ACCEPTANCE.md).
package/docs/README.md CHANGED
@@ -35,6 +35,7 @@ pm guide release --json
35
35
  - [Onboarding](ONBOARDING.md) - first-two-hours maintainer and contributor setup.
36
36
  - [Agent Guide](AGENT_GUIDE.md) - canonical agent loop, tracker linking, and token-minimal command choices.
37
37
  - [Agent Read and Test Receipts](AGENT_READ_AND_TEST_RECEIPTS.md) - JSON help provenance, linked-test persistence, and history diff continuation.
38
+ - [Fact-preserving Agent Output](AGENT_OUTPUT_ENCODINGS.md) - lossless SDK table cells, measured token ratchets, count aliases, and whole-response context budgets.
38
39
  - [Agent Evidence Consistency](AGENT_EVIDENCE_CONSISTENCY.md) - literal annotations, concurrent history validation, and declared recovery help.
39
40
  - [Actionable Item-read Evidence](GET_READ_EVIDENCE.md) - declared blocker status, historical separation, and truthful schedule/artifact omission receipts.
40
41
  - [Command Reference](COMMANDS.md) - command families with examples and when to use each family.
@@ -43,6 +44,7 @@ pm guide release --json
43
44
  - [Configuration](CONFIGURATION.md) - settings, storage formats, output, search, validation, and environment variables.
44
45
  - [Semantic Batching and Retrieval Quality](SEARCH_QUALITY.md) - independent request bounds, execution receipts, and per-query quality floors.
45
46
  - [Testing](TESTING.md) - sandbox-safe local tests and linked-test orchestration.
47
+ - [Faithful Package Acceptance](PACKAGE_GATE_ACCEPTANCE.md) - self-isolating package gates, independent Git snapshots, native diagnostics and isolated timing admission.
46
48
  - [Completion Portability and Bounded Replication Checks](VALIDATION_PORTABILITY.md) - literal Bash choices across versions and locales, and semantic Git diff collection.
47
49
  - [Build and Release Acceptance](BUILD_AND_RELEASE_ACCEPTANCE.md) - complete-build leases and cross-platform registry installation controls.
48
50
  - [Security Governance](SECURITY_GOVERNANCE.md) - vulnerability reporting, review discipline, property fuzzing, and OpenSSF limitations.
@@ -98,6 +100,7 @@ pm guide release --json
98
100
  - [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md) - source identity, durable migrations, and scoped preflight ownership.
99
101
  - [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md) - the stability guarantees and contract surface package authors build against.
100
102
  - [SDK](SDK.md) - public import surfaces and typed authoring examples.
103
+ - [SDK Storage Lifecycle](SDK_STORAGE_LIFECYCLE.md) - existing-parent writes, background worker lifetimes, and temporary acceptance producers.
101
104
  - [SDK Item Creation and Recovery](SDK_CREATE_AND_RECOVERY.md) - typed deterministic conflicts, resolved identity, actionable refusals, and amount-limited producer cursors.
102
105
  - [Audited SDK Settings and Item Updates](SDK_AUDITED_MUTATIONS.md) - extension-owned settings changes, replay-safe previews, and full-item JSON annotation integrity.
103
106
  - [SDK execution and recovery contracts](SDK_EXECUTION_CONTRACTS.md): schema-driven scheduling, handoff, and command recovery.
@@ -4,6 +4,24 @@ The extension settings contract is tracked by
4
4
  [pm-wtqltn](../.agents/pm/issues/pm-wtqltn.toon). Full-item JSON annotation
5
5
  integrity is tracked by [pm-2589e6](../.agents/pm/issues/pm-2589e6.toon).
6
6
  Canonical previews are tracked by [pm-2sef82](../.agents/pm/features/pm-2sef82.toon).
7
+ Preview path refusals are tracked by
8
+ [pm-preview-path-refusal](../.agents/pm/issues/pm-preview-path-refusal.toon).
9
+
10
+ ## Transaction preview storage
11
+
12
+ Item mutation and completion previews inspect a staged copy of the configured
13
+ tracker storage without changing source items or bootstrapping source schemas.
14
+ Linked entries, special files and directories configured as files are refused
15
+ with `transaction_preview_non_regular_file` (CLI exit `2`). SDK callers receive
16
+ a `PmCliError` with the same code and repair guidance in `context.nextSteps`.
17
+ The producer diagnostic omits discovered filesystem paths. Inspect the configured
18
+ settings, schema, session and item storage, restore the intended regular files and directories,
19
+ then retry the original dry run.
20
+
21
+ Entry and opened-descriptor checks enforce the same contract. Persistent native
22
+ filesystem failures, including missing link targets and permission errors, keep
23
+ their original codes. These checks require stable, trusted ancestors; they do
24
+ not guarantee protection against hostile concurrent path redirection.
7
25
 
8
26
  ## Extension settings
9
27
 
@@ -0,0 +1,35 @@
1
+ # SDK Storage Lifecycle
2
+
3
+ Tracked by [pm-p5u6](../.agents/pm/chores/pm-p5u6.toon).
4
+
5
+ Detached telemetry reads existing settings without scaffolding schemas/identity.
6
+ Locks, queue/state rewrites and event/OTLP completion preserve owner-removed
7
+ storage. Delivery stays best effort/nonblocking; foreground defaults create parents.
8
+
9
+ ```typescript
10
+ import { acquireLock, writeFileAtomic } from "@unbrained/pm-cli/sdk";
11
+
12
+ const policy = { createParentDirectories: false };
13
+ const release = await acquireLock(root, "job", 60, "worker", false, true, 5000, policy);
14
+ try {
15
+ await writeFileAtomic(resultPath, serializedResult, policy);
16
+ } finally {
17
+ await release();
18
+ }
19
+ ```
20
+
21
+ Owners initialize lock/result parents; absence fails without recreation. The
22
+ policy cannot pin identity or prevent symlink/replacement races. Extension lock
23
+ overrides own their lifecycle.
24
+
25
+ Async scripts use `registerTempOperation`: signal children, check after
26
+ uncancellable SDK work, `finish` after finally disposal. Interrupts close admission
27
+ and await completion; timeout retains evidence. Sync scripts use
28
+ `registerTempCleanup`. Normal failure, SIGINT/SIGTERM (130/143), explicit retention
29
+ and caller-owned roots are covered; unrelated roots survive. Abrupt exits retain
30
+ async work. SIGKILL/power loss/Windows forced termination cannot run handlers.
31
+ Unix tests cover signals; Windows covers callbacks/normal exit.
32
+
33
+ Real storage, HTTP/OTLP, Git and subprocess regressions complement
34
+ [build/registry acceptance](BUILD_AND_RELEASE_ACCEPTANCE.md) and
35
+ [packed first run](PACKED_FIRST_RUN.md).
package/docs/TESTING.md CHANGED
@@ -57,8 +57,12 @@ fixtures must never create production incidents from a developer host.
57
57
 
58
58
  Temporary directories must live outside the checkout and outside any ancestor
59
59
  workspace with initialized tracker data. The runner rejects a checkout-local
60
- temporary root, including a symlink alias, before starting build or test
61
- processes ([pm-bukwmy](../.agents/pm/issues/pm-bukwmy.toon)). If the default
60
+ temporary root and every initialized standard or root-layout ancestor tracker,
61
+ including physical symlink aliases, before allocating fixtures or starting build
62
+ or test processes ([pm-bukwmy](../.agents/pm/issues/pm-bukwmy.toon),
63
+ [pm-runner-ancestor-tracker](../.agents/pm/issues/pm-runner-ancestor-tracker.toon)).
64
+ Unrelated valid settings files remain admissible; unreadable or invalid ancestor
65
+ settings refuse ancestry certification. If the default
62
66
  temporary filesystem is full, set `TMPDIR` (or `TEMP`/`TMP` on Windows) to an
63
67
  existing isolated scratch directory; an ignored directory inside the repository
64
68
  is not isolated. Filesystem fixtures must honor `node:os`'s `tmpdir()` and remove
@@ -549,7 +553,11 @@ pm test <item-id> --run --workspace-context snapshot --override-linked-workspace
549
553
  copy, and binds its `.agents/pm` path to the selected temporary tracker.
550
554
  `.git`, `.agents`, coverage output, and common cache directories are excluded
551
555
  at every directory depth, with reserved names matched case-insensitively for
552
- portable admission. Each existing root or nested `node_modules`
556
+ portable admission. Git sources receive an independent commit/tag object store
557
+ with fresh configuration, no source hooks, and no origin remote. Repository
558
+ history remains available; this is execution isolation, not history redaction.
559
+ See [Faithful package acceptance](PACKAGE_GATE_ACCEPTANCE.md) for limits.
560
+ Each existing root or nested `node_modules`
553
561
  directory is linked at its original relative path, including installations
554
562
  already represented by directory symlinks. This preserves independent
555
563
  monorepo dependency versions without copying dependency trees. Dependency
@@ -4,12 +4,12 @@ Tracker: `pm-f05lsg`.
4
4
 
5
5
  Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.
6
6
 
7
- - Catalog error codes: 395
7
+ - Catalog error codes: 396
8
8
  - Executable error codes: 19
9
9
  - Executable-code ratchet floor: 18
10
10
  - 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`
11
- - Uncovered error codes: 376
12
- - Coverage fraction: 0.048101
11
+ - Uncovered error codes: 377
12
+ - Coverage fraction: 0.047980
13
13
  - Closed-domain probes: 19
14
14
  - Grammar probes: 117
15
15
 
@@ -324,6 +324,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
324
324
  | `tracker_root_not_directory` | `tracker_root_not_directory` | executable | owned_state | 1 |
325
325
  | `tracker_root_unreadable` | `tracker_root_unreadable` | executable | owned_state | 1 |
326
326
  | `transaction_preview_external_schema` | `transaction_preview_external_schema` | uncovered | none | 0 |
327
+ | `transaction_preview_non_regular_file` | `transaction_preview_non_regular_file` | uncovered | none | 0 |
327
328
  | `transaction_preview_snapshot_changed` | `transaction_preview_snapshot_changed` | uncovered | none | 0 |
328
329
  | `type_duplicate` | `type_duplicate` | uncovered | none | 0 |
329
330
  | `type_invalid` | `type_invalid` | uncovered | none | 0 |
package/marketplace.json CHANGED
@@ -5,13 +5,13 @@
5
5
  "url": "https://github.com/unbraind/pm-cli"
6
6
  },
7
7
  "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
8
- "version": "2026.10.7",
8
+ "version": "2026.10.9",
9
9
  "plugins": [
10
10
  {
11
11
  "name": "pm-claude",
12
12
  "source": "./plugins/pm-claude",
13
13
  "description": "Native pm CLI integration for Claude Code — 32 MCP tools, 14 workflow skills with slash invocations, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
14
- "version": "2026.10.7",
14
+ "version": "2026.10.9",
15
15
  "author": {
16
16
  "name": "unbrained",
17
17
  "url": "https://github.com/unbraind/pm-cli"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-cli",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "description": "Git-native project management CLI for humans and agents.",
5
5
  "type": "module",
6
6
  "packageManager": "pnpm@11.10.0",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-beads",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for importing Beads JSONL records.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-calendar",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for calendar and agenda views.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-command-kit",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-digital-twin",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-governance-audit",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for governance audit and normalization workflows.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-guide-shell",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for guide and shell completion workflows.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-kanban",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-lifecycle-hooks",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package demonstrating safe lifecycle hook registration.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-linked-test-adapters",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for optional linked-test run management adapters and reporters.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-search-advanced",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-templates",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for reusable create templates.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-todos",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for Todo markdown import and export.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-vcs-sdk-exemplar",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",
@@ -3,7 +3,7 @@
3
3
  "name": "pm-claude",
4
4
  "displayName": "pm CLI",
5
5
  "description": "Native pm CLI integration for Claude Code — 32 MCP tools, 14 skills with slash invocations, 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.",
6
- "version": "2026.10.7",
6
+ "version": "2026.10.9",
7
7
  "author": {
8
8
  "name": "unbrained",
9
9
  "url": "https://github.com/unbraind/pm-cli"
@@ -2,8 +2,8 @@
2
2
  "name": "pm-claude-runtime",
3
3
  "private": true,
4
4
  "type": "module",
5
- "version": "2026.10.7",
5
+ "version": "2026.10.9",
6
6
  "dependencies": {
7
- "@unbrained/pm-cli": "2026.10.7"
7
+ "@unbrained/pm-cli": "2026.10.9"
8
8
  }
9
9
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pm-codex",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
5
5
  "author": {
6
6
  "name": "unbrained",
@@ -2,8 +2,8 @@
2
2
  "name": "pm-codex-runtime",
3
3
  "private": true,
4
4
  "type": "module",
5
- "version": "2026.10.7",
5
+ "version": "2026.10.9",
6
6
  "dependencies": {
7
- "@unbrained/pm-cli": "2026.10.7"
7
+ "@unbrained/pm-cli": "2026.10.9"
8
8
  }
9
9
  }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "pm-codex",
4
- "version": "2026.10.7",
4
+ "version": "2026.10.9",
5
5
  "description": "Repository-native project context workflows and a version-pinned pm MCP server for Codex.",
6
6
  "author": {
7
7
  "name": "unbrained",
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "@unbrained/pm-cli",
3
- "version": "2026.10.7",
3
+ "version": "2026.10.9",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "@unbrained/pm-cli",
9
- "version": "2026.10.7",
9
+ "version": "2026.10.9",
10
10
  "dependencies": {
11
11
  "@sentry/node": "10.75.1",
12
12
  "@toon-format/toon": "^4.1.1",