@unbrained/pm-cli 2026.8.21 → 2026.8.23

package/docs/DIAGNOSTIC_OUTPUT_CONTRACTS.md

@@ -0,0 +1,115 @@
+# Diagnostic Output Contracts
+
+Tracker references: [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon), and [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon).
+
+## Agent Quick Context
+
+Failures are context-management surfaces. Every diagnostic family now declares
+a format-aware token ceiling and one degradation ladder in the public SDK:
+
+| Class                | Text | JSON | Corrective action that survives degradation |
+| -------------------- | ---: | ---: | ------------------------------------------- |
+| `error`              |  768 | 2000 | required action, retry/domain, or next step |
+| `warning`            |  768 | 2000 | required action, retry/domain, or next step |
+| `validation_summary` | 1500 | 3000 | required action, retry/domain, or next step |
+| `recovery_bundle`    |  768 | 2000 | required action, retry/domain, or next step |
+
+The smallest explicit ceiling is 192 estimated tokens. At that floor, the
+projector may reduce the diagnostic to its code, required action, compact
+recovery, and exit status. It never removes the first corrective action.
+
+## SDK Contract
+
+Use the public contract surface rather than maintaining a package-local error
+budget:
+
+```ts
+import {
+  PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS,
+  projectPmDiagnosticOutput,
+  projectPmDiagnosticText,
+  resolvePmDiagnosticOutputBudget,
+} from "@unbrained/pm-cli/sdk/contracts";
+
+const contract = resolvePmDiagnosticOutputBudget("error");
+const projected = projectPmDiagnosticOutput(
+  {
+    code: "invalid_argument_value",
+    required: "Use --status open and retry.",
+    recovery: { suggested_retry: "pm list --status open" },
+    detail: "The supplied status is not declared.",
+    exit_code: 2,
+  },
+  { maxEstimatedTokens: contract.minimum_max_estimated_tokens },
+);
+
+const text = projectPmDiagnosticText(
+  "A long rendered diagnostic",
+  "Use --status open and retry.",
+).output;
+```
+
+The JSON projector orders `code`, `required`, recovery, and next steps before
+explanation. Untruncated diagnostics add no per-call receipt overhead; their
+binding declaration is discoverable from `pm contracts --full --json` under
+`diagnostic_output_contracts`. When degradation occurs, the returned
+`diagnostic_output` receipt records the effective budget, original and emitted
+estimates, applied stages, and omitted top-level fields. Minimal fallbacks bound
+the named omission list and disclose any additional count through
+`omitted_fields_overflow_count`.
+
+Structured CLI refusals also include a compact `refusal` identity with the
+failing command/flag/operand surface, rejected scalar when observable, complete
+legal domain when one exists, and the process exit code. Recovery-bearing
+errors use the `recovery_bundle` diagnostic class. Collection degradation may
+compact explanatory domains inside `recovery`, but `refusal.legal_domain`
+remains complete and `recovery.suggested_retry_args` is atomic: the projector
+either retains the executable argv or removes the recovery rather than slicing
+it into a dead command.
+
+The deterministic ladder is:
+
+1. full diagnostic;
+2. omit explanation;
+3. limit diagnostic collections;
+4. compact recovery to actionable keys;
+5. retain the action-only envelope.
+
+Human diagnostics lead with `What is required` and next steps before explaining
+what happened. If their declared ceiling binds, the compact text still begins
+with the required action and points to structured JSON for the bounded recovery
+envelope.
+
+## Executable Assurance
+
+`pnpm quality:recovery-closure` builds the current CLI and replays 117 refusal
+contracts in isolated trackers: 18 closed-domain rows, 88 required-argument
+omissions derived from core executable positional signatures, seven
+closed-action families, and four tracker-preflight states. Package-owned
+commands enter executable coverage when their package runtime is active rather
+than being misreported as core. Ten representative, high-frequency failure
+paths are also ratcheted by
+`scripts/release/diagnostic-output-baseline.json`. The gate requires every row
+to remain within the SDK-declared JSON ceiling and retain a mechanically
+actionable correction. It reports the aggregate original and emitted token
+estimates without claiming a reduction when no degradation was required.
+
+The baseline is a coverage ratchet, not permission to weaken a ceiling. Its
+negative control requires a missing baseline probe to fail. The existing
+refusal-closure negative controls independently prove that incomplete domains,
+broken retries, and malformed recovery envelopes remain blocking findings.
+The grammar corpus additionally hashes authoritative tracker state around each
+refusal; schema, items, history, settings, and package state must not change.
+Ephemeral runtime lock/cache directories are excluded from that semantic
+snapshot.
+
+Run the focused proof with:
+
+```bash
+pnpm build
+node scripts/release/refusal-closure-gate.mjs
+node scripts/run-tests.mjs test -- \
+  tests/unit/sdk/agent-output-contracts.spec.ts \
+  tests/unit/cli/error-guidance.spec.ts \
+  tests/unit/scripts/refusal-closure-gate.spec.ts
+```

package/docs/EXTENSIONS.md

@@ -45,6 +45,7 @@ pm install kanban --project
 External registry packages are installed by exact package name. If `npm:<name>` returns a registry 404, JSON error output includes `fallback_candidates` and `next_best_command`; unpublished first-party packages fall back to `pm install --project github.com/unbraind/<name>`. Install results include package-owned `command_paths`, `action_paths`, `contributions`, `command_discovery`, and a light `verification` block covering the target tracker, activation status, registered commands/actions/item types, and health verdict. Agents should consume those fields instead of guessing from the package name or immediately spending another invocation on doctor. A successful activation persists the versioned contribution inventory in `.managed-extensions.json`; subsequent discovery can enumerate command handlers, hooks, parser/renderer targets, schema names, and the other registered surfaces without importing the package module. A failed runtime activation returns `ok: false`, `activated: false`, a non-zero CLI exit, and actionable diagnostics; missing SDK resolution adds an explicit dependency recovery step. Local installs are containment-safe when the extension destination is nested inside the source checkout: pm stages the package outside the source and prunes the destination, `.agents`, `node_modules`, and install-backup directories before copying, so reinstalling cannot recursively copy tracker history, host dependencies, or prior backups.
 Local `.tgz` and `.tar.gz` npm archives are inspected and extracted in an isolated temporary directory without invoking a shell. Archives must contain one `package/package.json` root, regular files/directories only, and bounded entry and expanded-byte totals. Absolute paths, traversal, alternate roots, links, device entries, oversized entries, and decompression-ratio abuse fail before installation. The managed source remains the original archive path, so reload and upgrade provenance do not point at a temporary extraction directory.
 Registry dependency names and versions are parsed as npm package specs before the install subprocess starts. Leading-option names and shell control syntax are rejected. npm reads those validated dependencies from an isolated runtime-only manifest; no caller-controlled spec is forwarded through the Windows command shell, and the fixed invocation still ends option parsing with `--`. Runtime verification then activates a temporary snapshot of the complete installed extension directory, so an upgrade cannot silently reuse stale transitive ESM dependencies from the current process. Successful install details expose `module_graph_verification: "fresh_snapshot"` for this check.
+pm-owned npm subprocesses clear any inherited, case-insensitive `npm_config_allow_scripts` value while retaining registry, auth, proxy, and executable-path environment; `--ignore-scripts` remains authoritative. Tracked by [pm-gh1072](../.agents/pm/issues/pm-gh1072.toon).
 An explicit `--pm-path` scopes project installs to that tracker root, including extension files, managed state, settings, type-folder scaffolding, and verification output. This is the safe form for temporary package testing from inside another repository checkout.
 
 ```bash
@@ -308,7 +309,7 @@ Common APIs:
 - `api.registerMigration(definition)` adds schema migrations.
 - `api.registerProfile(profile)` contributes a project profile — a declarative archetype bundling item types, statuses, fields, per-type workflows, config, templates, and package recommendations. Once active it resolves by name through `pm profile list/show/apply` alongside the core `agile`/`ops`/`research` archetypes (built-in names are reserved; a colliding registration is ignored with a warning). Requires the `schema` capability.
 - `api.registerAssuranceMeasurementProvider(provider)` contributes typed measurements to assurance. It requires `services`; network providers also require manifest `permissions.network: true`. Gates allow providers and cost/network limits per trigger. See [Project Assurance Primitives](ASSURANCE.md#extension-measurement-providers) for examples.
-- `api.registerService("output_format", handler)` customizes output formatting through the service override API. Use `handleServiceOverride(result)` to claim a payload and return the scaffold-compatible literal `{ handled: false }` (or `declineServiceOverride()`) for commands the extension does not own. Legacy `null`/`undefined` declines remain supported; returning the original payload is now an unambiguous handled result.
+- `api.registerService("output_format", handler, ownership?)` customizes output formatting through the service override API. Use `handleServiceOverride(result)` to claim a payload and return the scaffold-compatible literal `{ handled: false }` (or `declineServiceOverride()`) for commands the extension does not own. An override that is unconditionally inert can declare `{ passThrough: true }`; the host then ignores and diagnoses any handled result, and package doctor treats the registration as statically safe. Legacy `null`/`undefined` declines remain supported; returning the original payload is now an unambiguous handled result. Tracked by [pm-gh1074](../.agents/pm/issues/pm-gh1074.toon).
 - `api.registerRenderer("toon" | "json", renderer, ownership?)` adds format-specific renderers. Scope ownership with `commands` and/or a `resultDiscriminator`; the host checks both before invoking the renderer and falls back to native rendering for unrelated output. The legacy unscoped callback remains supported, but doctor warns because package ownership cannot be proven statically.
 - `suppressHostOutput(result?)` from `@unbrained/pm-cli/sdk` marks commands that already wrote output, preventing a second CLI payload while retaining the optional result for hooks, telemetry, and embedded hosts.
 - `api.hooks.beforeCommand(handler)`, `api.hooks.beforeMutation(handler)`, `api.hooks.afterCommand(handler)`, `api.hooks.onWrite(handler)`, `api.hooks.onRead(handler)`, and `api.hooks.onIndex(handler)` add lifecycle hooks.

package/docs/MERGE_SAFETY.md

@@ -1,6 +1,6 @@
 # Multi-Branch Tracker Merge Safety
 
-Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fresh-init fence ownership is tracked by [pm-1w3ljt](../.agents/pm/issues/pm-1w3ljt.toon); runtime-cache index governance by [pm-hous](../.agents/pm/issues/pm-hous.toon); local allocation safety by [pm-khdq](../.agents/pm/issues/pm-khdq.toon); fence-coverage completeness and drift detection by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); package-defined item coverage by [pm-5rexki](../.agents/pm/issues/pm-5rexki.toon); non-item JSON coverage by [pm-gjicmx](../.agents/pm/issues/pm-gjicmx.toon); portable driver identity by [pm-w91mvg](../.agents/pm/issues/pm-w91mvg.toon); pending receipt validation by [pm-ysqb6n](../.agents/pm/issues/pm-ysqb6n.toon); receipt classification by [pm-jtwsct](../.agents/pm/issues/pm-jtwsct.toon); direction-independent item conflict selection by [pm-dlx7v7](../.agents/pm/issues/pm-dlx7v7.toon); corrected reconciliation guidance by [pm-lwmstb](../.agents/pm/issues/pm-lwmstb.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); auditable merge history by [pm-9j2r3b](../.agents/pm/tasks/pm-9j2r3b.toon); durable conflict decisions by [pm-rh98vo](../.agents/pm/issues/pm-rh98vo.toon); continuous conformance by [pm-76dnfg](../.agents/pm/tasks/pm-76dnfg.toon); workspace-wide CI enforcement by [pm-pdr8t1](../.agents/pm/tasks/pm-pdr8t1.toon); post-merge reconciliation by [pm-mfkv92](../.agents/pm/issues/pm-mfkv92.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
+Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fresh-init fence ownership is tracked by [pm-1w3ljt](../.agents/pm/issues/pm-1w3ljt.toon); runtime-cache index governance by [pm-hous](../.agents/pm/issues/pm-hous.toon); local allocation safety by [pm-khdq](../.agents/pm/issues/pm-khdq.toon); fence-coverage completeness and drift detection by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); package-defined item coverage by [pm-5rexki](../.agents/pm/issues/pm-5rexki.toon); non-item JSON coverage by [pm-gjicmx](../.agents/pm/issues/pm-gjicmx.toon); portable driver identity by [pm-w91mvg](../.agents/pm/issues/pm-w91mvg.toon); pending receipt validation by [pm-ysqb6n](../.agents/pm/issues/pm-ysqb6n.toon); receipt classification by [pm-jtwsct](../.agents/pm/issues/pm-jtwsct.toon); direction-independent item conflict selection by [pm-dlx7v7](../.agents/pm/issues/pm-dlx7v7.toon); corrected reconciliation guidance by [pm-lwmstb](../.agents/pm/issues/pm-lwmstb.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); auditable merge history by [pm-9j2r3b](../.agents/pm/tasks/pm-9j2r3b.toon); durable conflict decisions by [pm-rh98vo](../.agents/pm/issues/pm-rh98vo.toon); continuous conformance by [pm-76dnfg](../.agents/pm/tasks/pm-76dnfg.toon); workspace-wide CI enforcement by [pm-pdr8t1](../.agents/pm/tasks/pm-pdr8t1.toon); post-merge reconciliation by [pm-mfkv92](../.agents/pm/issues/pm-mfkv92.toon); linked-command execution trust by [pm-ed28wi](../.agents/pm/issues/pm-ed28wi.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
 
 pm stores project context as reviewable repository files. Concurrent agents can therefore use ordinary branches and worktrees, but tracker artifacts need semantic merge behavior: raw line merging cannot preserve TOON collection counts, JSON object structure, or append-only history hash chains.
 
@@ -61,6 +61,20 @@ pm merge install --dry-run --json
 | tracker `**/*.jsonl` except the later `history/*.jsonl` override | `pm-relationship`                   | Covers default and package-owned custom relationship event paths, unions divergent suffixes by `eventId` (timestamp-ordered, ours-first on ties), and renumbers `sequence` consecutively so the strict-sequence store loader accepts the merged stream. |
 | root `settings.json` and nested `**/*.json`                      | `pm-json`                           | Recursively merges objects per key. Arrays compose when both branches preserve the base and add distinct entries, so independent extension installs and evaluation additions merge without weakening edit/removal conflict detection.                   |
 
+The `tests` collection has an additional execution-safety rule. Its semantic
+identity excludes provenance so the same command/context does not duplicate
+when branches record different authorship metadata. A test definition newly
+contributed by the other merge side is persisted with
+`provenance.source_kind=merge_union` while retaining its author, creation time,
+and source ref. `pm test --run` and `pm test-all` refuse that command before
+spawning a process until the receiving clone acknowledges its fingerprint or
+uses the two-part project-policy plus per-run override documented in
+[Testing](TESTING.md#linked-test-command-trust). `pm validate
+--check-command-references` reports outstanding entries. This is the threat
+boundary for append-like data that becomes executable after a merge; ordinary
+notes, files, and other non-executable collections retain normal set-union
+behavior.
+
 When both sides change the same item scalar differently, the driver writes the same stable value regardless of which branch Git labels ours or theirs, but exits nonzero. Item results and receipts expose the caller's `requested_preference`; the per-decision `retained` and `discarded` values or hashes are authoritative because stable value order can retain either side. Readers normalize the legacy receipt key `preferred`, while new receipts no longer emit it. JSON leaf conflicts retain the explicit preferred-side policy. Git keeps either path conflicted so a human or coordinating agent must review the discarded value and explicitly `git add` the resolution. This correction is tracked by [pm-qckpnq](../.agents/pm/issues/pm-qckpnq.toon).
 
 The driver result's `guidance` always points unresolved conflicts to `pm merge report`. When a clone-local receipt exists, guidance includes its privacy-safe receipt and item ids for exact correlation; discarded values remain confined to the local receipt and never appear in generic logs or tracker history. Tracked by [pm-fbrz7p](../.agents/pm/issues/pm-fbrz7p.toon).

package/docs/README.md

@@ -51,6 +51,7 @@ pm guide release --json
 - [SDK Context Platform](SDK_CONTEXT.md) - task-oriented entry point for authoritative reads, ranking, package workflows, diagnostics, recovery, and verification.
 - [Self-Describing Context Contracts](SELF_DESCRIBING_CONTEXT_CONTRACTS.md) - intent-scoped reads, semantic flag invocation metadata, visibility parity, and generated error vocabulary.
 - [Universal Read Output Contracts](READ_OUTPUT_CONTRACTS.md) - cross-command include, amount, cost, and encoding controls for CLI, SDK, MCP, and packages.
+- [Diagnostic Output Contracts](DIAGNOSTIC_OUTPUT_CONTRACTS.md) - action-first error budgets, deterministic degradation, SDK projection, and executable refusal assurance.
 - [Mutation Integrity](MUTATION_INTEGRITY.md) - shared CLI/SDK/MCP author, secret, append-only disposition, and stale-work guardrails.
 - [Agent Provenance ADR Amendment](AGENT_PROVENANCE_ADR.md) - extensible model, effort, role, and host provenance with privacy and compatibility boundaries.
 - [SDK Agent Session and Episode Context](SDK_AGENT_SESSION_CONTEXT.md) - inherited role/topic context, cross-process episode identity, and deterministic history grouping.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), and [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon).
+Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon), and [pm-xam9bt](../.agents/pm/issues/pm-xam9bt.toon).
 
 ## Agent Quick Context
 
@@ -140,7 +140,7 @@ pm stats --output-row-contract
 pm contracts --full --json
 ```
 
-Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed compatibility aliases, deterministic estimated token count, string/row compaction signals, and budget outcome. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
+Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed option provenance, deterministic estimated token count, string/row compaction signals, and budget outcome. When canonical controls are present, `canonical_options_used` records spellings such as `--output-include`; the optional field is omitted when no canonical control was supplied so minimum-budget session receipts remain compact. `legacy_aliases_used` and `migration_hints` record only compatibility flags the caller actually supplied. A command-local flag synthesized internally to execute a canonical projection mode is therefore never misreported as deprecated syntax. When both spellings are supplied, both provenance arrays report that mixed invocation. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
 
 When rows are dropped to satisfy a ceiling, the result also carries `output_budget_truncation`, naming the binding budget and its source, any explicitly requested dimension the budget overrode, every compacted collection path, and executable CLI/SDK/MCP recovery options — a default ceiling can override an explicit `--output-limit unbounded`, and that override is reported rather than silent. If a producer supplied an opaque item-page cursor, compaction rebases it to the last row actually returned and reports `continuation_cursor_rebased: true`; following the cursor therefore cannot skip rows removed from the middle of a producer page. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result, a compact `{ outputBudget: "unbounded" }` recovery object, and `omitted_result_estimated_tokens`, the last useful-result estimate before omission; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
 
@@ -164,6 +164,16 @@ an unbounded multi-megabyte response;
 `recovery_budget_multiplier: 1` declares that each next page retains the same
 useful-result ceiling.
 
+When compaction affects a nested collection that is not declared resumable,
+the recovery budget is derived from the larger of the binding ceiling plus one
+and the measured pre-compaction result. The SDK adds a 25% envelope margin and
+rounds up to 100 tokens. The CLI, SDK, and MCP bindings therefore receive the
+same finite value, which is strictly larger than the request that already
+truncated. If safe-integer arithmetic cannot represent that value, recovery
+uses `unbounded` explicitly. `resolveReadOutputRecoveryBudget()` exposes the
+versioned pure calculation to package authors; there is no hard-coded smaller
+retry and no recovery cycle.
+
 Assurance declares `budget_retention_policy: verdict_priority`: failing block,
 warn, and observe rows precede retired and passing rows while preserving order
 within each class. `assertions_total` remains the pre-projection denominator,
@@ -179,6 +189,13 @@ key. Health retains at most 100 warning rows and reports `warning_count`,
 projection unless `--full` is explicit, keeping the failing check identities
 and warning codes inside the ordinary budget.
 
+Failure transports use the companion
+[Diagnostic Output Contracts](DIAGNOSTIC_OUTPUT_CONTRACTS.md). Those contracts
+bind errors, warnings, validation summaries, and recovery bundles independently
+from successful command results. Corrective actions precede explanation and
+survive every degradation stage, while untruncated JSON avoids a per-call
+receipt tax.
+
 ## SDK and Package Usage
 
 Typed `PmClient` read methods accept `PmReadOutputOptions` directly:

package/docs/RELATIONSHIP_GRAPH.md

@@ -314,9 +314,12 @@ outcome milestones are roots, not work subjects, and are excluded from those
 populations. Rate or
 all-status floors are lifecycle-stable; an absolute active-population floor is
 invalid because completing reachable work legitimately moves it into the
-terminal population. `finding_subjects_by_code` includes every known finding
-code even when its population is zero, so assurance selectors never confuse a
-clean class with a missing contract field.
+terminal population. Detailed output's nested SDK profile census,
+`finding_subjects_by_code`, includes every known finding code even when its
+population is zero, so assurance selectors never confuse a clean class with a
+missing contract field. The top-level audit and persisted-baseline census is
+`affected_subjects_by_code`; both fields count affected subjects, but their
+locations and consumers differ and neither is an alias for the other.
 
 ```ts
 import {

package/docs/REPRODUCIBLE_WORKSPACES.md

@@ -1,7 +1,8 @@
 # Reproducible Workspaces and Snapshots
 
-Tracked by [pm-rbcvt2](../.agents/pm/features/pm-rbcvt2.toon) and
-[pm-dkrmzv](../.agents/pm/features/pm-dkrmzv.toon).
+Tracked by [pm-rbcvt2](../.agents/pm/features/pm-rbcvt2.toon),
+[pm-dkrmzv](../.agents/pm/features/pm-dkrmzv.toon), and
+[pm-gh1089](../.agents/pm/issues/pm-gh1089.toon).
 
 These SDK primitives make a pm workspace reproducible without changing normal
 interactive behavior. Recipes control time and identifier entropy only inside
@@ -22,9 +23,7 @@ const recipe: WorkspaceRecipe = {
   seed: "example-fixture-v1",
   clock: "2026-07-28T10:00:00.000Z",
   tickMs: 1,
-  operations: [
-    { action: "create", input: { title: "Deterministic task" } },
-  ],
+  operations: [{ action: "create", input: { title: "Deterministic task" } }],
 };
 
 const results = await executeWorkspaceRecipe(
@@ -36,9 +35,9 @@ const results = await executeWorkspaceRecipe(
 The caller owns action dispatch. pm owns the deterministic execution context:
 `nowIso()` advances from `clock` by `tickMs`, and generated item identifiers
 derive from `seed`. Async scopes are isolated with `AsyncLocalStorage`, so
-concurrent recipes do not share counters. Outside `runWithWorkspaceRecipe` or
-`executeWorkspaceRecipe`, the CLI continues using the system clock and
-cryptographic randomness.
+concurrent recipes do not share counters. Normal CLI and MCP execution still
+uses the system clock and cryptographic randomness unless the process opts in
+through the environment contract below.
 
 `defineWorkspaceRecipe` immediately validates the clock, seed, tick, schema,
 operation actions, and recursively JSON-compatible inputs. Its TypeScript
@@ -51,6 +50,41 @@ Seeds are reproducibility inputs, not secrets. A replay is byte-identical only
 when it begins from equivalent authoritative state and invokes the same ordered
 operations with the same recipe.
 
+## CLI and MCP process configuration
+
+Shell-based harnesses can install the same SDK-owned deterministic context for
+the `pm` and `pm-mcp` processes without patching JavaScript globals:
+
+```bash
+PM_CLOCK=2026-07-28T10:00:00.000Z \
+PM_CLOCK_TICK_MS=1 \
+PM_SEED=example-fixture-v1 \
+pm create --title "Deterministic task" --type Task --json
+```
+
+`PM_CLOCK` and `PM_SEED` are required together. `PM_CLOCK` must be an ISO-8601
+instant with `Z` or a numeric UTC offset; timezone-less and non-ISO inputs are
+rejected so separate hosts cannot interpret the same configuration differently.
+`PM_CLOCK_TICK_MS` is optional, defaults to `1`, and must be a non-negative integer. Partial or invalid input
+fails before command dispatch with the stable
+`invalid_reproducible_process_environment` code and recovery that names the
+missing or invalid variable. Unset all three variables for normal interactive
+behavior.
+
+Every CLI process invocation begins a fresh deterministic scope. A workflow
+that launches several CLI processes must derive a stable, distinct seed for
+each ordered step; reusing one seed intentionally reproduces the same entropy
+sequence and can reproduce an existing generated identifier. A long-lived MCP
+server instead owns one process-lifetime sequence and advances it across its
+serialized JSON-RPC requests. Two equivalent servers therefore produce the
+same files without generating duplicate identifiers inside either server.
+
+The public SDK exports `PM_REPRODUCIBLE_PROCESS_ENV`,
+`resolveReproducibleProcessEnvironment`,
+`runWithReproducibleProcessEnvironment`, and
+`createReproducibleProcessRunner` for custom one-shot and long-lived process
+transports.
+
 ## Content-addressed snapshots
 
 The SDK exports:

package/docs/SDK.md

@@ -1702,6 +1702,15 @@ const telemetry = await runTelemetry(
 global tracker roots. `pm_context_mode`, run-level overrides, automatic tracker
 context, assertion requirements, empty-run detection, and failure categories are
 part of the SDK result contract rather than presentation-layer behavior.
+Workspace results distinguish the run-level requested mode from the effective
+per-test mode. `isolated` executes from an empty disposable directory;
+`snapshot` executes from a filtered disposable workspace. Trust preflight
+failures report `trust_refusal`, while malformed or incomplete provenance uses
+the additive `provenance_invalid` storage marker and fail-closed
+`invalid_provenance` trust reason. Package mutation adapters can call
+`attachLinkedTestMutationProvenance` so Git inspection occurs only when commands
+are added; `resolveLinkedTestSourceWorkspaceRoot` keeps their source-ref lookup
+aligned with CLI execution and `PM_SOURCE_WORKSPACE_ROOT` overrides.
 When item test-result tracking is enabled, `measure` persists typed numeric
 evidence on the producing run. Each entry has a stable name, finite numeric
 value, optional unit and threshold, and the run timestamp. Run history remains

package/docs/SDK_AGENT_SESSION_CONTEXT.md

@@ -6,7 +6,8 @@ Tracker references: [pm-9wbiye](../.agents/pm/issues/pm-9wbiye.toon),
 [pm-3zgh2c](../.agents/pm/features/pm-3zgh2c.toon),
 [pm-eq9dlw](../.agents/pm/issues/pm-eq9dlw.toon), and
 [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), plus
-[pm-5q8wa0](../.agents/pm/issues/pm-5q8wa0.toon).
+[pm-5q8wa0](../.agents/pm/issues/pm-5q8wa0.toon) and
+[pm-c0lrdm](../.agents/pm/features/pm-c0lrdm.toon).
 
 Project management is context management. The public SDK therefore carries a
 session's purpose and episode boundary through the same immutable history that
@@ -128,9 +129,10 @@ public SDK exports for custom hosts.
 the bounded built-in resolver. It never contains environment values, session
 paths, prompts, or file contents.
 
-New mutation history records failed resolver outcomes under
-`context.agent_provenance_outcomes`; ordinary unavailable dimensions retain
-the compact legacy-compatible null projection. A resolver is only counted as
+New mutation history records failed or explicitly unavailable configured
+resolver outcomes under `context.agent_provenance_outcomes`; dimensions with
+no configured resolver retain the compact legacy-compatible null projection.
+A resolver is only counted as
 attempted when its required input belongs to the detected harness; a foreign
 host's shared `AI_AGENT` value is not Codex input. Consequently `pm health` can report
 `provenance_resolver_zero_success:<harness>:<dimension>:<resolver>:<attempts>`

package/docs/SDK_EVIDENCE_TRACEABILITY.md

@@ -111,7 +111,7 @@ pair pre-redaction item content with post-redaction history during validation.
 
 ## Operational receipts
 
-Linked tests recognize compound acquisition failures such as “could not acquire … lock” together with contention context such as “already running” or “held by another” as `infra_collision`. Generic assertion text mentioning a lock or timeout remains `assertion_failure`, preventing false infrastructure classifications.
+Linked tests recognize compound acquisition failures such as “could not acquire … lock” together with contention context such as “already running” or “held by another” as `infra_collision`. Generic assertion text mentioning a lock or timeout remains `assertion_failure`, preventing false infrastructure classifications. A command refused by clone-local provenance policy is classified separately as `trust_refusal`, so reports do not misstate a pre-execution safety decision as an assertion failure.
 
 Telemetry flush receipts distinguish progress from completion:
 

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).
+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).
 
 ## Agent Quick Context
 
@@ -366,6 +366,21 @@ The manifest records baseline bytes and estimated tokens for visible review
 deltas. Updating it cannot raise answer ceilings, which remain owned by
 `PM_COMMAND_OUTPUT_BUDGET_CONTRACTS`.
 
+Diagnostic ceilings share the executable refusal gate:
+
+```bash
+pnpm quality:recovery-closure
+```
+
+The gate replays 117 refusal contracts: 18 closed-domain rows, 88
+grammar-derived required-argument omissions, seven closed positional-action
+families, and four tracker-preflight states. It also ratchets ten representative
+failure paths against `PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS`. Every diagnostic
+must fit its declared JSON ceiling and preserve a mechanically actionable
+correction; executable retry argv is never collection-truncated. The
+missing-probe negative control and the authoritative tracker-state snapshot
+prove that the corpus cannot silently shrink or turn a refusal into a mutation.
+
 The gate derives every supported harness, model, session, and provenance
 environment key from the SDK-owned harness descriptor registry. It deletes
 those host inputs before each fixture invocation, then supplies only the
@@ -429,6 +444,69 @@ 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.
 
+## Source Workspace Modes
+
+Linked tests have a separate source-workspace contract. Store a default on one
+entry with `workspace_context_mode`, or choose a run-level mode with
+`--workspace-context`:
+
+```bash
+pm test <item-id> --add-json '{"command":"pnpm quality:static","workspace_context_mode":"isolated"}'
+pm test <item-id> --run --workspace-context snapshot --override-linked-workspace-context
+```
+
+- `source` (default) runs in the source checkout and exposes its read-only
+  source-context environment, preserving existing linked-test behavior.
+- `isolated` runs from an empty disposable directory and removes
+  `PM_SOURCE_WORKSPACE_ROOT`, `PM_SOURCE_PM_PATH`, and the source-context access
+  declaration. Use it only for commands that do not require checkout files.
+- `snapshot` copies the workspace into the linked-test sandbox, runs from that
+  copy, and binds its `.agents/pm` path to the selected temporary tracker.
+  `.git`, `.agents`, `node_modules`, coverage output, and common cache
+  directories are excluded at every directory depth; an existing top-level
+  `node_modules` is linked read-only by convention. Built output remains
+  available so linked commands such as `node dist/cli.js` keep working. Writes
+  therefore land in the disposable snapshot rather than the source checkout.
+
+Every result reports the requested/effective workspace mode, working
+directory, exposed source root, and trust decision. Recorded `test_runs` retain
+the effective workspace mode and trust reason beside the command.
+
+## Linked-Test Command Trust
+
+Linked commands are stored shell programs, so merge-unioned tracker data is an
+execution boundary. New command entries record author, creation time, source
+branch when available, and whether the item merge driver introduced the entry.
+Locally created commands keep their previous run behavior. Commands marked as
+merge-unioned or carrying a different source ref fail before process creation.
+Malformed provenance is sanitized to the additive `provenance_invalid` marker
+and receives the same fail-closed treatment; it is never normalized into a
+trusted legacy command.
+These pre-execution refusals use the `trust_refusal` failure category, separate
+from command or assertion failures.
+
+Choose one explicit recovery:
+
+```bash
+# Review and trust the item's current command fingerprints in this clone.
+pm test <item-id> --acknowledge-linked-tests
+
+# Or permit a single reviewed run. Both controls are required.
+pm config project set untrusted-linked-test-execution enabled
+pm test <item-id> --run --allow-untrusted-linked-tests
+```
+
+Acknowledgments live in the clone-local ignored runtime directory and bind to
+the full command, tracker/workspace context, environment controls, host-safety
+mode, and provenance fingerprint; editing any of those fields requires a new
+review. Enabling the project policy alone never executes
+an untrusted command, and the per-run flag alone is also refused. Inspect all
+unacknowledged entries without executing them with:
+
+```bash
+pm validate --check-command-references --verbose-diagnostics
+```
+
 Use explicit modes when needed:
 
 ```bash
@@ -480,6 +558,10 @@ pm test <item-id> --metric-below coverage=100 --metric-diff p95_latency
 
 Measurements are stored on the producing `test_runs` row, retained with the
 bounded run history, and exposed consistently by CLI, SDK, MCP, and contracts.
+Each recorded row also keeps a bounded `executions` list with the exact linked
+command, requested/effective `pm_context_mode`, effective workspace mode, and
+trust reason, so tracker-backed verification remains attributable after the
+transient process logs are gone.
 
 ## Linked-Test Assertions
 

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

@@ -18,8 +18,8 @@
     },
     {
       "id": "failing-command",
-      "max_estimated_tokens": 200
+      "max_estimated_tokens": 219
     }
   ],
-  "composite_max_estimated_tokens": 2178
+  "composite_max_estimated_tokens": 2197
 }

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -55,8 +55,8 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `docs` | evidence | 30 | 30 |
 | `deps` | graph | 32 | 32 |
 | `plan` | graph | 109 | 109 |
-| `test` | quality | 48 | 48 |
-| `test-all` | quality | 37 | 37 |
+| `test` | quality | 52 | 52 |
+| `test-all` | quality | 40 | 40 |
 | `telemetry` | workspace | 21 | 21 |
 | `stats` | context | 29 | 29 |
 | `health` | workspace | 36 | 36 |

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.21",
+  "version": "2026.8.23",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -220,7 +220,7 @@
     "@types/npm-package-arg": "^6.1.4",
     "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "0.28.2",
-    "eslint": "^10.8.1",
+    "eslint": "^10.9.0",
     "eslint-plugin-sonarjs": "^4.2.0",
     "eslint-plugin-unicorn": "^73.0.0",
     "fast-check": "^4.9.0",

package/packages/pm-beads/package.json

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

package/packages/pm-calendar/package.json

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

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

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

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

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

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

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

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

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

package/packages/pm-kanban/package.json

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