@unbrained/pm-cli 2026.8.22 → 2026.8.23

package/dist/sdk/test/trust.d.ts

@@ -0,0 +1,33 @@
+import type { LinkedTest } from "../../types/index.js";
+/** Classification of one linked-test command against the current clone. */
+export interface LinkedTestTrustDecision {
+    /** Stable hash binding the decision to command, context, and provenance. */
+    fingerprint: string;
+    /** Whether execution may proceed without an untrusted-command override. */
+    trusted: boolean;
+    /** Machine-readable reason for the decision. */
+    reason: "legacy" | "local_mutation" | "local_source_ref" | "acknowledged" | "invalid_provenance" | "foreign_source_ref";
+    /** Source ref recorded when the command entered tracker data. */
+    source_ref?: string;
+    /** Current source ref used for the local decision. */
+    current_source_ref?: string;
+}
+/** Resolve the current Git branch without invoking a shell. */
+export declare function resolveLinkedTestSourceRef(cwd?: string): Promise<string | undefined>;
+/** Resolve the source checkout shared by linked-test provenance and execution. */
+export declare function resolveLinkedTestSourceWorkspaceRoot(cwd?: string): string;
+/** Attach immutable author/time/ref provenance to newly stored commands. */
+export declare function attachLinkedTestProvenance(tests: LinkedTest[] | undefined, author: string, createdAt: string, sourceRef: string | undefined): LinkedTest[] | undefined;
+/** Attach provenance while avoiding Git inspection for an empty mutation. */
+export declare function attachLinkedTestMutationProvenance(tests: LinkedTest[] | undefined, author: string, createdAt: string): Promise<LinkedTest[] | undefined>;
+/** Produce the clone-local trust identity for one linked-test entry. */
+export declare function linkedTestTrustFingerprint(test: LinkedTest): string;
+/** Resolve whether one stored command is trusted by this clone. */
+export declare function resolveLinkedTestTrust(pmRoot: string, test: LinkedTest, currentSourceRef?: string): Promise<LinkedTestTrustDecision>;
+/** Resolve a collection with one ledger read for validation and batch runs. */
+export declare function resolveLinkedTestTrustBatch(pmRoot: string, tests: LinkedTest[], currentSourceRef?: string): Promise<LinkedTestTrustDecision[]>;
+/** Persist explicit clone-local acknowledgement for selected linked tests. */
+export declare function acknowledgeLinkedTests(pmRoot: string, tests: LinkedTest[], acknowledgedAt: string): Promise<{
+    acknowledged: number;
+    fingerprints: string[];
+}>;

package/dist/sdk/test/trust.js

@@ -0,0 +1,207 @@
+/**
+ * @module sdk/test/trust
+ *
+ * Provides provenance and clone-local trust decisions for stored linked-test
+ * commands. Tracker items remain portable while execution acknowledgements stay
+ * outside the merge-unioned project record.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="30a61f26-5db8-50ba-af37-1990a4742ce8")}catch(e){}}();
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { ensureDir, writeFileAtomic, } from "../../core/fs/fs-utils.js";
+import { sha256Hex, stableStringify } from "../../core/shared/serialization.js";
+import { isTimestampLiteral } from "../../core/shared/time.js";
+import { getRuntimePath } from "../../core/store/paths.js";
+const execFileAsync = promisify(execFile);
+const LINKED_TEST_TRUST_LEDGER_VERSION = 1;
+const LINKED_TEST_TRUST_LEDGER_FILE = "linked-test-trust.json";
+function trustLedgerPath(pmRoot) {
+    return path.join(getRuntimePath(pmRoot), LINKED_TEST_TRUST_LEDGER_FILE);
+}
+function emptyTrustLedger() {
+    return { version: LINKED_TEST_TRUST_LEDGER_VERSION, acknowledged: {} };
+}
+async function readTrustLedger(pmRoot) {
+    try {
+        const parsed = JSON.parse(await readFile(trustLedgerPath(pmRoot), "utf8"));
+        if (parsed.version !== LINKED_TEST_TRUST_LEDGER_VERSION ||
+            typeof parsed.acknowledged !== "object" ||
+            parsed.acknowledged === null ||
+            Array.isArray(parsed.acknowledged)) {
+            return emptyTrustLedger();
+        }
+        return {
+            version: LINKED_TEST_TRUST_LEDGER_VERSION,
+            acknowledged: parsed.acknowledged,
+        };
+    }
+    catch {
+        // A missing, corrupt, or unreadable ledger grants no acknowledgements.
+        // The local/source-ref provenance checks remain independent of this file.
+        return emptyTrustLedger();
+    }
+}
+/** Resolve the current Git branch without invoking a shell. */
+export async function resolveLinkedTestSourceRef(cwd = process.cwd()) {
+    const hostedRef = process.env.GITHUB_HEAD_REF?.trim() || process.env.GITHUB_REF_NAME?.trim();
+    if (hostedRef && hostedRef !== "merge") {
+        return hostedRef;
+    }
+    try {
+        const { stdout } = await execFileAsync("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd, encoding: "utf8", windowsHide: true, timeout: 10_000 });
+        const ref = stdout.trim();
+        /* c8 ignore start -- successful git symbolic-ref output is non-empty by contract */
+        if (ref.length === 0)
+            return undefined;
+        /* c8 ignore stop */
+        return ref;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolve the source checkout shared by linked-test provenance and execution. */
+export function resolveLinkedTestSourceWorkspaceRoot(cwd = process.cwd()) {
+    return process.env.PM_SOURCE_WORKSPACE_ROOT?.trim() || cwd;
+}
+function hasValidLinkedTestProvenance(provenance) {
+    if (provenance === null || typeof provenance !== "object")
+        return false;
+    return (typeof provenance.author === "string" &&
+        provenance.author.trim().length > 0 &&
+        typeof provenance.created_at === "string" &&
+        isTimestampLiteral(provenance.created_at) &&
+        (provenance.source_kind === "local_mutation" ||
+            provenance.source_kind === "merge_union"));
+}
+/** Build the optional ref portion shared by clone-local trust decisions. */
+function linkedTestTrustRefs(sourceRef, currentSourceRef) {
+    return {
+        ...(sourceRef ? { source_ref: sourceRef } : {}),
+        ...(currentSourceRef ? { current_source_ref: currentSourceRef } : {}),
+    };
+}
+/** Attach immutable author/time/ref provenance to newly stored commands. */
+export function attachLinkedTestProvenance(tests, author, createdAt, sourceRef) {
+    return tests?.map((test) => test.command && !test.provenance
+        ? {
+            ...test,
+            provenance: {
+                author,
+                created_at: createdAt,
+                source_kind: "local_mutation",
+                ...(sourceRef ? { source_ref: sourceRef } : {}),
+            },
+        }
+        : test);
+}
+/** Attach provenance while avoiding Git inspection for an empty mutation. */
+export async function attachLinkedTestMutationProvenance(tests, author, createdAt) {
+    if (!tests || tests.length === 0)
+        return tests;
+    const sourceWorkspaceRoot = resolveLinkedTestSourceWorkspaceRoot();
+    return attachLinkedTestProvenance(tests, author, createdAt, await resolveLinkedTestSourceRef(sourceWorkspaceRoot));
+}
+/** Produce the clone-local trust identity for one linked-test entry. */
+export function linkedTestTrustFingerprint(test) {
+    return sha256Hex(stableStringify({
+        command: test.command ?? null,
+        path: test.path ?? null,
+        scope: test.scope,
+        pm_context_mode: test.pm_context_mode ?? null,
+        workspace_context_mode: test.workspace_context_mode ?? null,
+        env_set: test.env_set ?? null,
+        env_clear: test.env_clear ?? null,
+        shared_host_safe: test.shared_host_safe ?? null,
+        provenance: test.provenance ?? null,
+        provenance_invalid: test.provenance_invalid ?? null,
+    }));
+}
+/** Resolve whether one stored command is trusted by this clone. */
+export async function resolveLinkedTestTrust(pmRoot, test, currentSourceRef) {
+    const ledger = await readTrustLedger(pmRoot);
+    return resolveLinkedTestTrustFromLedger(test, currentSourceRef, ledger);
+}
+function resolveLinkedTestTrustFromLedger(test, currentSourceRef, ledger) {
+    const fingerprint = linkedTestTrustFingerprint(test);
+    const sourceRef = test.provenance?.source_ref;
+    if (test.provenance === undefined &&
+        test.provenance_invalid !== true) {
+        return { fingerprint, trusted: true, reason: "legacy" };
+    }
+    const acknowledged = Object.hasOwn(ledger.acknowledged, fingerprint);
+    if (test.provenance_invalid === true ||
+        !hasValidLinkedTestProvenance(test.provenance)) {
+        if (acknowledged) {
+            return {
+                fingerprint,
+                trusted: true,
+                reason: "acknowledged",
+                ...linkedTestTrustRefs(undefined, currentSourceRef),
+            };
+        }
+        return {
+            fingerprint,
+            trusted: false,
+            reason: "invalid_provenance",
+            ...linkedTestTrustRefs(undefined, currentSourceRef),
+        };
+    }
+    if (test.provenance.source_kind === "local_mutation" &&
+        sourceRef === undefined) {
+        return {
+            fingerprint,
+            trusted: true,
+            reason: "local_mutation",
+            ...linkedTestTrustRefs(undefined, currentSourceRef),
+        };
+    }
+    if (test.provenance.source_kind === "local_mutation" &&
+        sourceRef !== undefined &&
+        sourceRef === currentSourceRef) {
+        return {
+            fingerprint,
+            trusted: true,
+            reason: "local_source_ref",
+            source_ref: sourceRef,
+            current_source_ref: currentSourceRef,
+        };
+    }
+    if (acknowledged) {
+        return {
+            fingerprint,
+            trusted: true,
+            reason: "acknowledged",
+            ...linkedTestTrustRefs(sourceRef, currentSourceRef),
+        };
+    }
+    return {
+        fingerprint,
+        trusted: false,
+        reason: "foreign_source_ref",
+        ...linkedTestTrustRefs(sourceRef, currentSourceRef),
+    };
+}
+/** Resolve a collection with one ledger read for validation and batch runs. */
+export async function resolveLinkedTestTrustBatch(pmRoot, tests, currentSourceRef) {
+    const ledger = await readTrustLedger(pmRoot);
+    return tests.map((test) => resolveLinkedTestTrustFromLedger(test, currentSourceRef, ledger));
+}
+/** Persist explicit clone-local acknowledgement for selected linked tests. */
+export async function acknowledgeLinkedTests(pmRoot, tests, acknowledgedAt) {
+    const ledger = await readTrustLedger(pmRoot);
+    const fingerprints = tests
+        .filter((test) => typeof test.command === "string" && test.command.length > 0)
+        .map(linkedTestTrustFingerprint);
+    for (const fingerprint of fingerprints) {
+        ledger.acknowledged[fingerprint] = { acknowledged_at: acknowledgedAt };
+    }
+    await ensureDir(path.dirname(trustLedgerPath(pmRoot)));
+    await writeFileAtomic(trustLedgerPath(pmRoot), `${JSON.stringify(ledger, null, 2)}\n`);
+    return { acknowledged: fingerprints.length, fingerprints };
+}
+//# sourceMappingURL=trust.js.map
+//# debugId=30a61f26-5db8-50ba-af37-1990a4742ce8

package/dist/types.d.ts

@@ -166,6 +166,17 @@ export interface LinkedFile {
     /** Value that configures or reports note for this contract. */
     note?: string;
 }
+/** Valid immutable provenance captured when a linked command enters tracker data. */
+export interface LinkedTestProvenance {
+    /** Author identity recorded by the originating mutation. */
+    author: string;
+    /** ISO 8601 time at which the command entered tracker data. */
+    created_at: string;
+    /** Mutation path that introduced the command. */
+    source_kind: "local_mutation" | "merge_union";
+    /** Best-effort Git branch or hosted head ref of the originating mutation. */
+    source_ref?: string;
+}
 /** Documents the linked test payload exchanged by command, SDK, and package integrations. */
 export interface LinkedTest {
     /** Value that configures or reports command for this contract. */
@@ -178,6 +189,12 @@ export interface LinkedTest {
     timeout_seconds?: number;
     /** Strategy used to control pm context behavior. */
     pm_context_mode?: "schema" | "tracker" | "auto";
+    /** Strategy used for source-workspace visibility and command working directory. */
+    workspace_context_mode?: "source" | "isolated" | "snapshot";
+    /** Immutable provenance captured when the linked command enters tracker data. */
+    provenance?: LinkedTestProvenance;
+    /** Explicit fail-closed marker retained when stored provenance is malformed. */
+    provenance_invalid?: true;
     /** Value that configures or reports env set for this contract. */
     env_set?: Record<string, string>;
     /** Value that configures or reports env clear for this contract. */
@@ -566,6 +583,10 @@ export interface ItemTestRunExecution {
     requested_pm_context_mode?: "schema" | "tracker" | "auto";
     /** Effective context mode used by the linked command. */
     pm_context_mode?: "schema" | "tracker" | "auto";
+    /** Effective source-workspace mode used by the linked command. */
+    workspace_context_mode?: "source" | "isolated" | "snapshot";
+    /** Trust classification applied before execution. */
+    trust_reason?: "legacy" | "local_mutation" | "local_source_ref" | "acknowledged" | "invalid_provenance" | "foreign_source_ref";
 }
 /** Documents the item test run summary payload exchanged by command, SDK, and package integrations. */
 export interface ItemTestRunSummary {
@@ -1121,6 +1142,8 @@ export interface PmSettings {
     /** Value that configures or reports testing for this contract. */
     testing: {
         record_results_to_items: boolean;
+        /** Permit explicit one-shot execution of commands not yet trusted by this clone. */
+        allow_untrusted_linked_tests: boolean;
     };
     /** Value that configures or reports telemetry for this contract. */
     telemetry: {

package/dist/types.js

@@ -5,7 +5,7 @@
  */
 /** Supported values accepted by the builtin item type contract. */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="13c65470-8f5f-59ca-acb5-50c926c68870")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="64223a83-1287-57ac-915d-dbd5e375a6eb")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -243,4 +243,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=13c65470-8f5f-59ca-acb5-50c926c68870
+//# debugId=64223a83-1287-57ac-915d-dbd5e375a6eb

package/docs/AGENT_PROVENANCE_ADR.md

@@ -10,7 +10,10 @@ Implementation lineage:
 resolution and patch-free historical reads implemented by
 [pm-ffz0a9](../.agents/pm/issues/pm-ffz0a9.toon),
 [pm-v8gfi7](../.agents/pm/issues/pm-v8gfi7.toon), and
-[pm-3yxwv5](../.agents/pm/issues/pm-3yxwv5.toon).
+[pm-3yxwv5](../.agents/pm/issues/pm-3yxwv5.toon). Cross-harness adapters and
+operator-managed probe/vocabulary controls are tracked by
+[pm-c0lrdm](../.agents/pm/features/pm-c0lrdm.toon) and
+[pm-yds9dt](../.agents/pm/chores/pm-yds9dt.toon).
 
 Status: accepted amendment to
 [pm-qwuber](../.agents/pm/decisions/pm-qwuber.toon). The original stable-author
@@ -51,10 +54,13 @@ Provenance values are descriptive context, never authentication or
 authorization principals. Values are trimmed, length-bounded, and obtained only
 from literal descriptor keys, trusted caller data, or a named bounded resolver.
 Detection does not spawn processes, traverse process trees, evaluate user
-regexes, or access the network. The built-in Claude resolver may read only the
-tail of the current session's harness-owned JSONL file to recover its recorded
-model/version. It caps file bytes, lines, and line length, extracts only those
-two allow-listed values, and fails closed. `agent_identity.probes_enabled` or
+regexes, or access the network. The built-in Claude and Codex resolvers read
+only bounded windows of the current session's harness-owned JSONL file. Claude
+uses the recent tail to recover its recorded model/version. Codex uses the
+recent tail plus a bounded initial-head fallback for oversized sessions to
+recover allow-listed `turn_context.model` and `turn_context.effort` values.
+Both cap traversal, file bytes, lines, and line length, ignore all other fields,
+never follow symlinks, and fail closed. `agent_identity.probes_enabled` or
 `PM_AGENT_PROBES=off` disables every local resolver without disabling ordinary
 environment, argv, client, or host detection.
 
@@ -113,6 +119,11 @@ fabricate precision that was never captured.
 The aggregate and core SDK entrypoints export:
 
 - `AGENT_PROVENANCE_DIMENSIONS`;
+- `BUILTIN_AGENT_PROVENANCE_ADAPTERS`,
+  `listAgentProvenanceAdapters()`, and
+  `registerAgentProvenanceAdapters()`;
+- `normalizeAgentProvenanceAdapterValue()` for stable model-family and effort
+  vocabulary projections that retain the bounded raw observation;
 - `detectAgentIdentity()` and `detectHarnessIdentity()`;
 - `analyzeAgentProvenanceDescriptorCoverage()` for the descriptor capability
   matrix and negative controls;
@@ -138,6 +149,31 @@ Legacy author interpretation is workspace-owned data under
 version and whether a harness was `recorded`, resolved by `vocabulary`, or
 remains `unresolved`; immutable authors and hashes are never rewritten.
 
+`pm config get agent-identity-vocabulary`, `config list`, and `config export`
+publish only its `version` and `alias_count`. Typed mutations use the existing
+config transport:
+
+```bash
+pm config set agent-identity-probes-enabled false
+pm config set agent-identity-vocabulary --policy preview-add \
+  --value "Legacy Codex=codex" --criterion "Legacy Codex" --criterion "Alice"
+pm config set agent-identity-vocabulary --policy add \
+  --value "Legacy Codex=codex"
+pm config set agent-identity-vocabulary --policy remove --value "Legacy Codex"
+```
+
+`preview-*` policies perform no write and report the exact residual unique
+author count without returning author spellings. Real add/remove/clear changes
+bump the vocabulary revision once; identical adds and absent removes are
+idempotent. Aliases for already canonical `harness:<name>` authors fail closed.
+
+Every built-in interactive harness has a contract-versioned adapter with an
+implementation version, priority, covered dimensions, source classes,
+normalization revisions, confidence, waivers, and immutable probe bounds.
+Packages may register a new namespace or explicitly replace a built-in only at
+a higher priority. Equal-priority ambiguity and descriptor mismatch fail
+closed, and the disposer restores the prior adapter.
+
 The SDK/CLI matrix classifies every input as shared, positional, transport,
 presentation, local adapter, scope selector, compatibility alias, or SDK-native.
 An unknown CLI flag fails closed as `unclassified`. Committed test baselines cap

package/docs/CONFIGURATION.md

@@ -29,6 +29,7 @@ pm config project export --json
 pm config project get item-format --json
 pm config project set item-format --format toon
 pm config project set test-result-tracking --policy enabled
+pm config project set untrusted-linked-test-execution --policy disabled
 ```
 
 `config set <key> <value>` also accepts the value as a positional argument; pm routes
@@ -85,6 +86,7 @@ When `settings.json` cannot be loaded, `pm` falls back to built-in defaults and
 | `history.compact_policy.max_entries`       | when the policy is enabled, the entry count above which a stream is flagged by `pm health` and the default `pm history-compact --all-over` threshold (default `500`)                                  |
 | `history.compact_policy.trigger`           | policy intent when enabled: `health_warn` (advisory only) or `auto` (scheduled sweeps expected)                                                                                                       |
 | `testing.record_results_to_items`          | persist bounded linked-test summaries                                                                                                                                                                 |
+| `testing.allow_untrusted_linked_tests`     | permit the explicit `pm test --allow-untrusted-linked-tests` one-run override (default `false`; does not trust or execute commands by itself)                                                         |
 | `validation.sprint_release_format`         | `warn` or `strict_error`                                                                                                                                                                              |
 | `validation.parent_reference`              | `warn` or `strict_error` (`strict_error` is the built-in default; `pm create --allow-missing-parent` is the explicit escape hatch)                                                                    |
 | `item_types.definitions[]`                 | custom item types and type options                                                                                                                                                                    |
@@ -115,6 +117,7 @@ pm config project set schema_unknown_field_policy reject   # (schema.unknown_fie
 pm config project set governance-duplicate-detection-mode strict         # (governance.duplicate_detection_mode) off | advisory | strict
 pm config project set governance-duplicate-detection-threshold 0.8       # (governance.duplicate_detection_threshold) ratio 0..1
 pm config project set governance-duplicate-detection-limit 3             # (governance.duplicate_detection_limit) integer 0..20
+pm config project set untrusted-linked-test-execution disabled            # (testing.allow_untrusted_linked_tests) enabled | disabled
 ```
 
 Duplicate governance uses the shared SDK scorer and bounded metadata query
@@ -227,6 +230,7 @@ pm config project set sprint-release-format-policy --policy warn
 pm config project set parent-reference-policy --policy strict_error
 pm config project set history-missing-stream-policy --policy auto_create
 pm config project set test-result-tracking --policy enabled
+pm config project set untrusted-linked-test-execution --policy disabled
 ```
 
 Use standalone checks when validating a repository:

package/docs/DIAGNOSTIC_OUTPUT_CONTRACTS.md

@@ -58,6 +58,15 @@ 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;
@@ -73,8 +82,12 @@ envelope.
 
 ## Executable Assurance
 
-`pnpm quality:recovery-closure` builds the current CLI and replays 22 refusal
-contracts in isolated trackers. Ten representative, high-frequency failure
+`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
@@ -85,6 +98,10 @@ 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:
 

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/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-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), 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
 
@@ -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,

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>`