@unbrained/pm-cli 2026.8.27 → 2026.8.29

package/docs/OUTPUT_TOKEN_ACCOUNTING.md

@@ -1,6 +1,6 @@
 # Output Token Accounting
 
-Tracker references: [pm-t5dt4z](../.agents/pm/tasks/pm-t5dt4z.toon) and [pm-g3n00m](../.agents/pm/stories/pm-g3n00m.toon).
+Tracker references: [pm-t5dt4z](../.agents/pm/tasks/pm-t5dt4z.toon), [pm-g3n00m](../.agents/pm/stories/pm-g3n00m.toon), [pm-8pnj](../.agents/pm/features/pm-8pnj.toon), [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
 
 ## Agent Quick Context
 
@@ -39,20 +39,33 @@ The command still exits with its normal non-zero status; the receipt is additive
 
 ## Release-Level Task Entitlement
 
-[`agent-task-token-baseline.json`](agent-task-token-baseline.json) is the externally shipped release baseline. The gate executes the built CLI in an isolated workspace and covers:
+[`agent-task-transcripts.json`](agent-task-transcripts.json) is the SDK-validated, versioned golden corpus. [`agent-task-token-baseline.json`](agent-task-token-baseline.json) is its externally shipped release ratchet. The gate executes the built CLI against independent, identically seeded accounting-on and accounting-off workspaces. Its five complete workflows cover:
 
-- a small-workspace read;
-- a scaled-workspace context read;
-- a returning-agent item read with a required-field completeness assertion;
-- a failing command with bounded recovery output.
+- bounded triage, scaled-workspace orientation, and returning-agent inspection;
+- a closed-domain refusal followed by the exact advertised shell-free retry;
+- an unknown option after valid flags followed by a corrected command;
+- create, inspect, close, and final-state confirmation through mutation receipts;
+- successful bulk partial-effect and no-effect exits without collapsing them into exit zero.
 
-Each invocation is independently byte-counted, its section sum is checked, and its consumed field is retained. A seeded million-token regression proves the ratchet fails. Run it with:
+Every step verifies its public SDK output family, canonical successful or refusal exit status, required own-property paths, declared `expected_field_values`, and refusal identity where applicable. Recovery steps must declare a successful output family instead of chaining one refusal to another, every refusal in a completed task must have a later successful `recovery_for` step, and every completed task must terminate with successful output. Successful steps cannot carry refusal-only metadata. Dot-separated `required_fields` and `expected_field_values` paths are traversed structurally from the output root, so incidental prose or nested key names cannot satisfy completeness or terminal-state assertions. The report publishes bytes and estimated tokens for each step and completed task, retry counts, corpus digest, and composite cost. Accounting-on application payloads must be byte-equivalent to their independently captured accounting-off payloads after removing only the receipt. Receipt byte and token fields are independently measured rather than trusted. Runtime refusals verify that their self-reported `total_bytes` matches the independent transport and that `total_estimated_tokens` equals `ceil(total_bytes / 4)`; Commander usage refusals that happen before accounting attachment are measured directly from the captured transport and labeled `independent_transport`.
+
+The baseline fails closed on corpus digest, task identity, step identity, missing or non-finite per-step and per-task ceilings, and missing or non-finite composite cost ceilings. A seeded million-token completed-task regression proves the ratchet fails. Run it with:
 
 ```bash
 pnpm quality:agent-task-token
 node scripts/release/agent-task-token-gate.mjs --negative-control
 ```
 
+Package authors can validate their own corpus with the same public contract before replay:
+
+```ts
+import { parsePmAgentTaskTranscriptCorpus } from "@unbrained/pm-cli/sdk/contracts";
+
+const corpus = parsePmAgentTaskTranscriptCorpus(JSON.parse(source));
+```
+
+The parser rejects unknown versions, empty tasks or steps, duplicate identities, output families that disagree with the command contract, refusal-only metadata on successful steps, terminal or otherwise unrecovered refusals, and recovery edges that do not point from a successful step to an earlier refusal.
+
 Refresh the committed ceiling only after an intentional reviewed output change:
 
 ```bash

package/docs/README.md

@@ -68,6 +68,7 @@ pm guide release --json
 - [Recurrence and Executable Recovery Contracts](RECURRENCE_RECOVERY_CONTRACTS.md) - terminal-item recurrence, duplicate-intake routing, capability-aware reindex recovery, and target-aware generated test guidance.
 - [Trustworthy Context and Evidence Contracts](TRUSTWORTHY_CONTEXT_EVIDENCE.md) - full-record assurance, graph composition, boolean health rows, lossless linked-test removal, and role-labelled recovery.
 - [Context Integrity Contracts](CONTEXT_INTEGRITY_CONTRACTS.md) - sparse-read identity, closed extension manifests, lossless remote docs, direction-locked graph impact, and cross-version history epochs.
+- [Context Integrity and Recovery Primitives](CONTEXT_RECOVERY_PRIMITIVES.md) - lossless metadata, write-time link receipts, executed-test evidence, external blockers, npm receipts, history capabilities, and truthful recovery.
 - [SDK Evidence Traceability and Integrity](SDK_EVIDENCE_TRACEABILITY.md) - reverse source-to-item lookup, atomic evidence replacement, no-op history, linked-test collision classification, and telemetry drain receipts.
 - [SDK Context and Evidence Contracts](SDK_CONTEXT_EVIDENCE_CONTRACTS.md) - material omission receipts, scoped preflight activation, truthful merge preference, claim-race classification, and versioned history hashes.
 - [Reproducible Workspaces and Snapshots](REPRODUCIBLE_WORKSPACES.md) - deterministic SDK recipes and content-addressed authoritative tracker restore points.

package/docs/RELEASING.md

@@ -29,6 +29,8 @@ provenance is tracked by [pm-u1baah](../.agents/pm/issues/pm-u1baah.toon), and
 authoritative blocker-recovery run selection by
 [pm-db8onn](../.agents/pm/issues/pm-db8onn.toon), and queued automatic
 same-day recovery by [pm-dm2vfz](../.agents/pm/issues/pm-dm2vfz.toon).
+Bounded Sentry request latency is tracked by
+[pm-b9g2cs](../.agents/pm/issues/pm-b9g2cs.toon).
 
 ## Version Policy
 
@@ -210,6 +212,12 @@ events, and every `generic_failure` or `dependency_failed` remain blocking.
 This keeps rewording independent from release policy and makes stale or broad
 message allowlists impossible.
 
+Sentry API requests use a 120-second deadline by default. Operators can set
+`--sentry-request-timeout-ms` between `1` and `300000` when reproducing
+provider latency, while the emitted gate receipt records the effective value.
+The release workflow pins `120000`; query timeouts remain fail-closed and must
+not be treated as an empty issue set.
+
 If private reliability checks identify repeated user friction, either confirm the current release already contains the remediation with regression coverage or fix it before continuing.
 
 The build writes `dist/cli-bundle/bundle-manifest.json` atomically with SHA-256 digests for every emitted bundle file. At startup, `pm` reports `bundle_integrity_torn_install` only when a module-loader failure is accompanied by manifest proof that an upgrade or rebuild changed, removed, or corrupted the active bundle. Reinstall `@unbrained/pm-cli` and retry after that diagnostic. Ordinary `ERR_MODULE_NOT_FOUND` and export failures with an intact manifest remain unexpected failures and must continue to block reliability gates.
@@ -358,7 +366,7 @@ git push origin v<version>
   tracked source path (apart from managed-extension install metadata).
 - static quality gate (shared complexity, duplication, dead/orphan module, file/folder hygiene, source/exported docstring coverage profile)
 - temporary-project compatibility gate against latest published tracker data
-- reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
+- reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; Sentry requests use the fail-closed bounded `--sentry-request-timeout-ms` contract (default `120000`, maximum `300000`); `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
 - sandboxed `pm` coverage
 - optional Sentry release metadata and sourcemap upload when `SENTRY_AUTH_TOKEN` is configured
 - npm pack dry run and npx tarball smoke test

package/docs/SDK.md

@@ -1512,6 +1512,18 @@ edit/delete semantics, ownership guidance, history mutation metadata, and stable
 list pagination. MCP tool actions intentionally omit file input to prevent host
 filesystem access. Package authors can build custom annotation presentation
 layers without importing CLI modules.
+`CommentsCommandOptions.ifAbsent`, `NotesCommandOptions.ifAbsent`, and
+`LearningsCommandOptions.ifAbsent` give retrying agents one explicit idempotent
+annotation append contract. Equality is evaluated under the item writer lock
+after author resolution and text normalization, using the resolved author plus
+exact stored text. The first append returns `changed: true` and
+`mutation_receipt.changed_count: 1`; an exact retry returns the existing entry,
+`changed: false`, and `changed_count: 0` without changing the item, history, or
+derived search state. Different authors remain distinct, and the default
+without `ifAbsent` continues to append intentional duplicates. The option is
+valid only for append input and fails closed for list, edit, or delete modes.
+CLI `comments|notes|learnings --if-absent` and the corresponding MCP actions
+with `options.ifAbsent: true` are thin transports over this SDK behavior.
 `PmClient.notes` also accepts `addJson` for a validated structured context event. The persisted entry remains backward-readable through canonical `text` while exposing typed `format: "json"`, `data`, and `event_type` fields. `since`, `eventType`, `limit`, and `includeMeta` form the bounded query contract; the collection continues to use field-aware union merge semantics for concurrent branches.
 
 Customization convenience methods are the SDK baseline for project-specific pm

package/docs/SDK_CONTEXT_INTEGRITY.md

@@ -1,6 +1,6 @@
 # SDK Context Integrity
 
-Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-in23qu](../.agents/pm/issues/pm-in23qu.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-okgxwa](../.agents/pm/issues/pm-okgxwa.toon), [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon), [pm-mcxk8v](../.agents/pm/issues/pm-mcxk8v.toon), and [pm-2zkvxm](../.agents/pm/issues/pm-2zkvxm.toon).
+Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-in23qu](../.agents/pm/issues/pm-in23qu.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-okgxwa](../.agents/pm/issues/pm-okgxwa.toon), [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon), [pm-mcxk8v](../.agents/pm/issues/pm-mcxk8v.toon), [pm-2zkvxm](../.agents/pm/issues/pm-2zkvxm.toon), and [pm-ea1yh2](../.agents/pm/issues/pm-ea1yh2.toon).
 
 Current closure tranche: [pm-fs8q9x](../.agents/pm/tasks/pm-fs8q9x.toon), [pm-gy885b](../.agents/pm/issues/pm-gy885b.toon), and [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon).
 
@@ -82,6 +82,17 @@ The structured `option_scope` is `declared_on_path`, `declared_elsewhere`, or
 case, while the third names the nearest current-path spellings and explicitly
 terminates the otherwise-unbounded command search.
 
+## Retry-safe annotation mutations
+
+Comments, notes, and learnings expose one SDK-owned `ifAbsent` append contract.
+The item writer lock compares the resolved author and exact normalized stored
+text, so concurrent retries create one entry and one history event. The winning
+append reports `changed: true` and `mutation_receipt.changed_count: 1`; later
+exact retries return the existing entry with `changed: false` and
+`changed_count: 0`. Default appends remain duplicate-preserving. CLI
+`--if-absent` and MCP `ifAbsent` are thin transports, and `--full-history`
+remains the explicit escape hatch from bounded mutation receipts.
+
 ## Semantic flag and spelling contracts
 
 `listPmFlagLexicon()` classifies flags by meaning rather than spelling alone.

package/docs/SDK_RUNTIME_BOUNDARIES.md

@@ -61,6 +61,16 @@ published error vocabulary while still sharing classification, path redaction,
 and recovery guidance. Workspace snapshots use this compatibility path for
 their stable storage, resource, and permission fault codes.
 
+Package archives use one bounded validation and extraction boundary whether
+they come from a local path or `npm pack`. The SDK rejects links, escaping
+paths, unsupported entry types, oversized archives, and decompression growth
+before extraction. If npm reports an archive it did not create, callers receive
+the path-redacted `npm_package_archive_missing` refusal instead of a raw system
+`tar` exception; an archive reported outside the isolated pack destination is
+rejected as `npm_package_archive_unsafe`. This keeps package install behavior
+portable and prevents an untrusted registry artifact or package-manager result
+from bypassing the local-archive policy.
+
 ## CLI refusal ownership
 
 CLI adapters preserve SDK error codes, exit semantics, and actionable recovery

package/docs/TESTING.md

@@ -2,7 +2,7 @@
 
 This page describes safe local tests, linked tests, coverage, and release-readiness checks.
 
-Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-u42x](../.agents/pm/issues/pm-u42x.toon), [pm-atfm](../.agents/pm/features/pm-atfm.toon), [pm-xmp5](../.agents/pm/tasks/pm-xmp5.toon), [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), [pm-5cgm2z](../.agents/pm/chores/pm-5cgm2z.toon), [pm-avv3wx](../.agents/pm/issues/pm-avv3wx.toon), [pm-rizqb6](../.agents/pm/issues/pm-rizqb6.toon), [pm-95h7pg](../.agents/pm/issues/pm-95h7pg.toon), [pm-giks4s](../.agents/pm/issues/pm-giks4s.toon), [pm-xa3t0o](../.agents/pm/issues/pm-xa3t0o.toon), [pm-e97jyf](../.agents/pm/issues/pm-e97jyf.toon), [pm-efkvdy](../.agents/pm/issues/pm-efkvdy.toon), and [pm-ed28wi](../.agents/pm/issues/pm-ed28wi.toon).
+Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-u42x](../.agents/pm/issues/pm-u42x.toon), [pm-atfm](../.agents/pm/features/pm-atfm.toon), [pm-xmp5](../.agents/pm/tasks/pm-xmp5.toon), [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), [pm-5cgm2z](../.agents/pm/chores/pm-5cgm2z.toon), [pm-avv3wx](../.agents/pm/issues/pm-avv3wx.toon), [pm-rizqb6](../.agents/pm/issues/pm-rizqb6.toon), [pm-95h7pg](../.agents/pm/issues/pm-95h7pg.toon), [pm-giks4s](../.agents/pm/issues/pm-giks4s.toon), [pm-xa3t0o](../.agents/pm/issues/pm-xa3t0o.toon), [pm-e97jyf](../.agents/pm/issues/pm-e97jyf.toon), [pm-efkvdy](../.agents/pm/issues/pm-efkvdy.toon), [pm-ed28wi](../.agents/pm/issues/pm-ed28wi.toon), and [pm-5ug5xq](../.agents/pm/issues/pm-5ug5xq.toon).
 
 ## Agent Quick Context
 
@@ -43,7 +43,11 @@ claims to the same canonical gate IDs. Hosted-only environment isolation and
 tracker-integrity steps remain explicit entries with reasons rather than
 silently disappearing from local parity.
 
-`node scripts/run-tests.mjs` wraps Vitest in temporary tracker roots, then cleans them up.
+`node scripts/run-tests.mjs` wraps Vitest in temporary tracker roots, disables
+external Sentry delivery for the build, test workers, and their nested CLI
+children, then cleans the roots up. Instrumentation tests can still exercise
+Sentry initialization through their mocked module boundary; ordinary negative
+fixtures must never create production incidents from a developer host.
 
 Public SDK changes additionally run semantic surface and import-cost contracts:
 

package/docs/agent-task-token-baseline.json

@@ -1,25 +1,111 @@
 {
-  "version": 1,
+  "version": 3,
+  "transcript_version": 2,
+  "transcript_digest": "sha256:2bf91406426d2a9e5de1da10ba67f7b8e9d4a4baa09eb488fe89ae3925c78f3f",
   "estimator": "ceil(utf8_bytes / 4)",
   "measurement_scope": "output_before_token_accounting",
   "published_with_release": true,
-  "scenarios": [
+  "tasks": [
     {
-      "id": "small-workspace",
-      "max_estimated_tokens": 552
+      "id": "context-bootstrap",
+      "max_estimated_tokens": 1978,
+      "steps": [
+        {
+          "id": "triage",
+          "max_estimated_tokens": 552,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "orient",
+          "max_estimated_tokens": 1055,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "inspect",
+          "max_estimated_tokens": 371,
+          "accounting_mode": "self_reported"
+        }
+      ]
     },
     {
-      "id": "large-workspace",
-      "max_estimated_tokens": 1055
+      "id": "closed-domain-recovery",
+      "max_estimated_tokens": 630,
+      "steps": [
+        {
+          "id": "refuse-intent",
+          "max_estimated_tokens": 259,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "retry-intent",
+          "max_estimated_tokens": 371,
+          "accounting_mode": "self_reported"
+        }
+      ]
     },
     {
-      "id": "returning-agent",
-      "max_estimated_tokens": 371
+      "id": "unknown-option-recovery",
+      "max_estimated_tokens": 585,
+      "steps": [
+        {
+          "id": "refuse-option",
+          "max_estimated_tokens": 422,
+          "accounting_mode": "independent_transport"
+        },
+        {
+          "id": "retry-option",
+          "max_estimated_tokens": 163,
+          "accounting_mode": "self_reported"
+        }
+      ]
     },
     {
-      "id": "failing-command",
-      "max_estimated_tokens": 219
+      "id": "lifecycle-mutation",
+      "max_estimated_tokens": 812,
+      "steps": [
+        {
+          "id": "create",
+          "max_estimated_tokens": 20,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "inspect-open",
+          "max_estimated_tokens": 363,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "close",
+          "max_estimated_tokens": 31,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "inspect-closed",
+          "max_estimated_tokens": 398,
+          "accounting_mode": "self_reported"
+        }
+      ]
+    },
+    {
+      "id": "bulk-effect-outcomes",
+      "max_estimated_tokens": 326,
+      "steps": [
+        {
+          "id": "create-bulk-target",
+          "max_estimated_tokens": 20,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "partial-effect",
+          "max_estimated_tokens": 174,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "no-effect",
+          "max_estimated_tokens": 132,
+          "accounting_mode": "self_reported"
+        }
+      ]
     }
   ],
-  "composite_max_estimated_tokens": 2197
+  "composite_max_estimated_tokens": 4331
 }

package/docs/agent-task-transcripts.json

@@ -0,0 +1,211 @@
+{
+  "version": 2,
+  "tasks": [
+    {
+      "id": "context-bootstrap",
+      "description": "Orient in a scaled workspace and inspect the canonical focus item.",
+      "steps": [
+        {
+          "id": "triage",
+          "args": ["list", "--for", "triage", "--limit", "2"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "collection",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["items"]
+        },
+        {
+          "id": "orient",
+          "args": ["context", "--for", "orient", "--limit", "5"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "diagnostic",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["summary.active_items", "hierarchy", "activity"]
+        },
+        {
+          "id": "inspect",
+          "args": ["get", "$ANCHOR_ID", "--for", "inspect"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "entity",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["item.id"]
+        }
+      ]
+    },
+    {
+      "id": "closed-domain-recovery",
+      "description": "Reject an invalid context intent and execute the advertised shell-free retry.",
+      "steps": [
+        {
+          "id": "refuse-intent",
+          "args": ["get", "$ANCHOR_ID", "--for", "invalid-agent-intent"],
+          "expected_exit_code": 2,
+          "expected_output_kind": "refusal",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["code", "refusal", "recovery"],
+          "expected_error_code": "unknown_context_intent",
+          "expected_refusal_surface": "--for"
+        },
+        {
+          "id": "retry-intent",
+          "args": ["get", "$ANCHOR_ID", "--for", "inspect"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "entity",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["item.id"],
+          "recovery_for": "refuse-intent"
+        }
+      ]
+    },
+    {
+      "id": "unknown-option-recovery",
+      "description": "Identify an unsupported option after valid flags and continue with the corrected command.",
+      "steps": [
+        {
+          "id": "refuse-option",
+          "args": [
+            "search",
+            "agent task",
+            "--status",
+            "open",
+            "--limit",
+            "5",
+            "--include-body"
+          ],
+          "expected_exit_code": 2,
+          "expected_output_kind": "refusal",
+          "expected_accounting_mode": "independent_transport",
+          "required_fields": ["code", "refusal", "recovery"],
+          "expected_error_code": "unknown_option",
+          "expected_refusal_surface": "--include-body"
+        },
+        {
+          "id": "retry-option",
+          "args": ["search", "agent task", "--status", "open", "--limit", "5"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "collection",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["items"],
+          "recovery_for": "refuse-option"
+        }
+      ]
+    },
+    {
+      "id": "lifecycle-mutation",
+      "description": "Create, inspect, close, and confirm a project item through public CLI receipts.",
+      "steps": [
+        {
+          "id": "create",
+          "args": [
+            "create",
+            "--id",
+            "$LIFECYCLE_ID",
+            "--title",
+            "Transcript lifecycle item",
+            "--description",
+            "Golden multi-step lifecycle task",
+            "--type",
+            "Task",
+            "--status",
+            "open",
+            "--create-mode",
+            "progressive"
+          ],
+          "expected_exit_code": 0,
+          "expected_output_kind": "mutation_receipt",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["id", "changed_field_count"]
+        },
+        {
+          "id": "inspect-open",
+          "args": ["get", "$LIFECYCLE_ID", "--for", "inspect"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "entity",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["item.id", "item.status"],
+          "expected_field_values": { "item.status": "open" }
+        },
+        {
+          "id": "close",
+          "args": ["close", "$LIFECYCLE_ID", "Golden task completed"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "mutation_receipt",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["id", "status", "close_reason"]
+        },
+        {
+          "id": "inspect-closed",
+          "args": ["get", "$LIFECYCLE_ID", "--for", "inspect"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "entity",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["item.id", "item.status"],
+          "expected_field_values": { "item.status": "closed" }
+        }
+      ]
+    },
+    {
+      "id": "bulk-effect-outcomes",
+      "description": "Preserve successful partial-effect and no-effect outcomes across a bulk lifecycle task.",
+      "steps": [
+        {
+          "id": "create-bulk-target",
+          "args": [
+            "create",
+            "--id",
+            "$BULK_ID",
+            "--title",
+            "Transcript bulk effect target",
+            "--description",
+            "Golden bulk outcome transcript target",
+            "--type",
+            "Task",
+            "--status",
+            "open",
+            "--create-mode",
+            "progressive"
+          ],
+          "expected_exit_code": 0,
+          "expected_output_kind": "mutation_receipt",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["id", "status", "changed_field_count"]
+        },
+        {
+          "id": "partial-effect",
+          "args": [
+            "close-many",
+            "--ids",
+            "$BULK_ID,pm-transcript-missing",
+            "--reason",
+            "Golden partial-effect transcript",
+            "--validate-close",
+            "off",
+            "--no-checkpoint"
+          ],
+          "expected_exit_code": 7,
+          "expected_output_kind": "collection",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["rows", "outcome", "exit_code"],
+          "expected_field_values": { "outcome": "partial_effect" }
+        },
+        {
+          "id": "no-effect",
+          "args": [
+            "close-many",
+            "--ids",
+            "$BULK_ID",
+            "--reason",
+            "Golden no-effect transcript",
+            "--validate-close",
+            "off",
+            "--no-checkpoint"
+          ],
+          "expected_exit_code": 6,
+          "expected_output_kind": "collection",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["rows", "outcome", "exit_code"],
+          "expected_field_values": { "outcome": "no_effect" }
+        }
+      ]
+    }
+  ]
+}

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -48,9 +48,9 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `close-many` | lifecycle | 72 | 72 |
 | `delete` | lifecycle | 24 | 24 |
 | `append` | evidence | 24 | 24 |
-| `comments` | evidence | 30 | 30 |
-| `notes` | evidence | 34 | 34 |
-| `learnings` | evidence | 26 | 26 |
+| `comments` | evidence | 31 | 31 |
+| `notes` | evidence | 35 | 35 |
+| `learnings` | evidence | 27 | 27 |
 | `files` | evidence | 39 | 39 |
 | `docs` | evidence | 30 | 30 |
 | `deps` | graph | 32 | 32 |

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -4,12 +4,12 @@ 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: 344
+- Catalog error codes: 353
 - 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
+- Uncovered error codes: 334
+- Coverage fraction: 0.053824
 - Closed-domain probes: 19
 - Grammar probes: 94
 
@@ -25,10 +25,12 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `ambiguous_option_combination` | `ambiguous_option_combination` | uncovered | none | 0 |
 | `annotation_alias_conflict` | `annotation_alias_conflict` | uncovered | none | 0 |
 | `annotation_flag_like_value` | `annotation_flag_like_value` | uncovered | none | 0 |
+| `annotation_if_absent_without_append` | `annotation_if_absent_without_append` | uncovered | none | 0 |
 | `annotation_message_without_text` | `annotation_message_without_text` | uncovered | none | 0 |
 | `annotation_transposed_subcommand` | `annotation_transposed_subcommand` | uncovered | none | 0 |
 | `append_empty_body` | `append_empty_body` | uncovered | none | 0 |
 | `assurance_registry_invalid` | `assurance_registry_invalid` | uncovered | none | 0 |
+| `bare_comma_entry_ambiguous` | `bare_comma_entry_ambiguous` | uncovered | none | 0 |
 | `body_file_conflicts_with_body` | `body_file_conflicts_with_body` | uncovered | none | 0 |
 | `body_file_missing_path` | `body_file_missing_path` | uncovered | none | 0 |
 | `body_file_unreadable` | `body_file_unreadable` | uncovered | none | 0 |
@@ -114,6 +116,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `history_drift_merge_receipt` | `history_drift_merge_receipt` | uncovered | none | 0 |
 | `history_drift_missing_stream` | `history_drift_missing_stream` | uncovered | none | 0 |
 | `history_drift_unreadable_stream` | `history_drift_unreadable_stream` | uncovered | none | 0 |
+| `history_drift_version_skew` | `history_drift_version_skew` | uncovered | none | 0 |
 | `history_merge_conflict_markers_detected` | `merge_conflict_markers_detected` | uncovered | none | 0 |
 | `history_stream_over_compact_threshold` | `history_stream_over_compact_threshold` | uncovered | none | 0 |
 | `history_target_out_of_range` | `history_target_out_of_range` | uncovered | none | 0 |
@@ -184,7 +187,6 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `merge_git_config_unwritable` | `merge_git_config_unwritable` | uncovered | none | 0 |
 | `merge_receipt_evidence_invalid` | `merge_receipt_evidence_invalid` | uncovered | none | 0 |
 | `merge_receipts_pending` | `merge_receipts_pending` | uncovered | none | 0 |
-| `merge_reconcile_discards_require_acceptance` | `merge_reconcile_discards_require_acceptance` | uncovered | none | 0 |
 | `merge_reconcile_receipt_evidence_untrusted` | `merge_reconcile_receipt_evidence_untrusted` | uncovered | none | 0 |
 | `merge_root_not_found` | `merge_root_not_found` | uncovered | none | 0 |
 | `missing_allowed_values` | `missing_allowed_values` | uncovered | none | 0 |
@@ -197,6 +199,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `missing_observation` | `missing_observation` | uncovered | none | 0 |
 | `missing_observed_signature` | `missing_observed_signature` | uncovered | none | 0 |
 | `missing_parameter_alias` | `missing_parameter_alias` | uncovered | none | 0 |
+| `missing_positive_execution_receipt` | `missing_positive_execution_receipt` | uncovered | none | 0 |
 | `missing_probe` | `missing_probe` | uncovered | none | 0 |
 | `missing_required_argument` | `missing_required_argument` | executable | grammar | 57 |
 | `missing_required_option` | `missing_required_option` | uncovered | none | 0 |
@@ -213,6 +216,9 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `no_update_fields` | `no_update_fields` | 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_pack_json_shape_unsupported` | `npm_pack_json_shape_unsupported` | uncovered | none | 0 |
+| `npm_package_archive_missing` | `npm_package_archive_missing` | uncovered | none | 0 |
+| `npm_package_archive_unsafe` | `npm_package_archive_unsafe` | 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 |
@@ -246,6 +252,8 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `reopen_reason_required` | `reopen_reason_required` | uncovered | none | 0 |
 | `reopen_receipt_missing` | `reopen_receipt_missing` | uncovered | none | 0 |
 | `reopen_target_status_invalid` | `reopen_target_status_invalid` | uncovered | none | 0 |
+| `reported_zero_passes` | `reported_zero_passes` | uncovered | none | 0 |
+| `reported_zero_tests` | `reported_zero_tests` | uncovered | none | 0 |
 | `reserved_item_field` | `reserved_item_field` | uncovered | none | 0 |
 | `retry_failed` | `retry_failed` | uncovered | none | 0 |
 | `schema_migration_input_required` | `schema_migration_input_required` | uncovered | none | 0 |
@@ -314,6 +322,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `validate_history_drift_hash_mismatches` | `history_drift_hash_mismatch` | uncovered | none | 0 |
 | `validate_history_drift_missing_streams` | `history_drift_missing_stream` | uncovered | none | 0 |
 | `validate_history_drift_unreadable_streams` | `history_drift_unreadable_stream` | uncovered | none | 0 |
+| `validate_history_drift_version_skews` | `history_drift_version_skew` | uncovered | none | 0 |
 | `validate_history_unknown_author_events` | `history_unknown_author_events` | uncovered | none | 0 |
 | `validate_lifecycle_active_closure_like_metadata` | `validate_lifecycle_active_closure_like_metadata` | uncovered | none | 0 |
 | `validate_lifecycle_active_terminal_parent` | `validate_lifecycle_active_terminal_parent` | uncovered | none | 0 |

package/docs/performance/cli-transport-overhead.md

@@ -1,12 +1,20 @@
 # CLI transport overhead
 
-Tracked by [pm-yse5dt](../../.agents/pm/tasks/pm-yse5dt.toon).
+Tracked by [pm-yse5dt](../../.agents/pm/tasks/pm-yse5dt.toon), with RSS
+admission reliability owned by
+[pm-pz49xc](../../.agents/pm/issues/pm-pz49xc.toon).
 
 Each result starts from a fresh isolated workspace containing exactly one item.
 The command runs in a fresh Node v26.5.0 process on
 linux/x64; setup and fixture generation are
 outside the timed interval. Short local gates use the best observed latency,
-while the report retains p50 and p95 evidence.
+while the report retains p50 and p95 evidence. RSS admission uses the measured
+median so one page-level outlier cannot false-fail the gate; the maximum remains
+in the report as diagnostic evidence. Every post-warmup RSS sample must be a
+finite measurement; an unavailable sample makes the admission median unavailable
+and fails closed when a budget exists. Admission adds a fixed 512 KiB noise margin
+without changing the committed budget; a majority persistent increase beyond
+that bounded margin still fails.
 
 | Command   |   best |    p50 |    p95 |
 | --------- | -----: | -----: | -----: |