@unbrained/pm-cli 2026.8.24 → 2026.8.26

package/dist/sdk/read-output/continuation.d.ts

@@ -1,6 +1,19 @@
 import type { PmReadOutputCursorEnvelope, PmReadOutputSurface } from "../read-output-contracts.js";
-/** Fingerprint the complete canonical row snapshot so changed evidence fails closed. */
-export declare function readOutputCollectionFingerprint(path: string, value: unknown[] | Record<string, unknown>): string;
+/** Stable snapshot policy for a read surface whose probes refresh observation metadata. */
+export interface PmReadOutputContinuationFingerprintPolicy {
+    /** Version included in fingerprints so policy changes invalidate older cursors. */
+    version: 3;
+    /** Declared continuation row paths governed by this policy. */
+    paths: readonly string[];
+    /** Exact direct detail fields excluded for each named dynamic row. */
+    ignored_detail_field_names_by_row: Readonly<Record<string, readonly string[]>>;
+    /** Promise that verdicts, stable configuration, and nonvolatile evidence remain bound. */
+    guarantee: "nonvolatile_snapshot_and_stable_configuration";
+}
+/** Command-specific exceptions to complete-row continuation fingerprinting. */
+export declare const PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES: Readonly<Partial<Record<PmReadOutputSurface, PmReadOutputContinuationFingerprintPolicy>>>;
+/** Fingerprint the policy-normalized row snapshot so stable evidence changes fail closed. */
+export declare function readOutputCollectionFingerprint(path: string, value: unknown[] | Record<string, unknown>, command?: PmReadOutputSurface): string;
 /** Encode one stable declared-row continuation for CLI, SDK, and MCP callers. */
 export declare function encodeReadOutputContinuationCursor(cursor: Omit<PmReadOutputCursorEnvelope, "version">): string;
 /** Decode and validate one universal declared-row continuation cursor. */

package/dist/sdk/read-output/continuation.js

@@ -6,7 +6,7 @@
  * resolution and budget policy.
  */
 
-!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]="1c73c31e-6246-5730-8c8a-d3ba7c9ec112")}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]="9e63b4b0-09a5-50bf-9f56-5f239c75ffe5")}catch(e){}}();
 import { createHash } from "node:crypto";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
@@ -14,13 +14,93 @@ import { stableStringify } from "../../core/shared/serialization.js";
 import { resolveReadOutputSurface } from "../read-output-contracts.js";
 import { readOutputContinuationRowCollections, sliceReadOutputRowCollection, } from "../read-output-rows.js";
 const MAX_READ_OUTPUT_CURSOR_LENGTH = 4096;
+const HEALTH_TELEMETRY_VOLATILE_DETAIL_FIELDS = Object.freeze([
+    "queue_draining",
+    "queue_entries",
+    "queue_exists",
+    "queue_high_retry_entries",
+    "queue_invalid_rows",
+    "queue_max_attempts",
+    "queue_rows_total",
+    "queue_size_bytes",
+    "pending_otel_spans",
+    "last_attempted_flush_at",
+    "last_failed_flush_at",
+    "last_otel_attempt_at",
+    "last_otel_failure_at",
+    "last_otel_success_at",
+    "last_successful_flush_at",
+]);
+/** Command-specific exceptions to complete-row continuation fingerprinting. */
+export const PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES = Object.freeze({
+    health: Object.freeze({
+        version: 3,
+        paths: Object.freeze(["checks"]),
+        ignored_detail_field_names_by_row: Object.freeze({
+            telemetry: HEALTH_TELEMETRY_VOLATILE_DETAIL_FIELDS,
+        }),
+        guarantee: "nonvolatile_snapshot_and_stable_configuration",
+    }),
+});
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-/** Fingerprint the complete canonical row snapshot so changed evidence fails closed. */
-export function readOutputCollectionFingerprint(path, value) {
+function normalizeReadOutputFingerprintValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(normalizeReadOutputFingerprintValue);
+    }
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+        key,
+        normalizeReadOutputFingerprintValue(entry),
+    ]));
+}
+function normalizeReadOutputFingerprintRow(value, policy) {
+    if (!isRecord(value))
+        return normalizeReadOutputFingerprintValue(value);
+    const rowName = typeof value.name === "string" ? value.name : undefined;
+    const ignoredDetailFields = rowName !== undefined &&
+        Object.hasOwn(policy.ignored_detail_field_names_by_row, rowName)
+        ? policy.ignored_detail_field_names_by_row[rowName]
+        : undefined;
+    return Object.fromEntries(Object.entries(value)
+        .map(([key, entry]) => {
+        if (key !== "details" || !ignoredDetailFields || !isRecord(entry)) {
+            return [key, normalizeReadOutputFingerprintValue(entry)];
+        }
+        return [
+            key,
+            Object.fromEntries(Object.entries(entry)
+                .filter(([detailKey]) => !ignoredDetailFields.includes(detailKey))
+                .map(([detailKey, detailValue]) => [
+                detailKey,
+                normalizeReadOutputFingerprintValue(detailValue),
+            ])),
+        ];
+    }));
+}
+function normalizeReadOutputFingerprintSnapshot(value, policy) {
+    return Array.isArray(value)
+        ? value.map((row) => normalizeReadOutputFingerprintRow(row, policy))
+        : normalizeReadOutputFingerprintRow(value, policy);
+}
+/** Fingerprint the policy-normalized row snapshot so stable evidence changes fail closed. */
+export function readOutputCollectionFingerprint(path, value, command) {
+    const policy = command
+        ? PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES[command]
+        : undefined;
+    const policyApplies = policy?.paths.includes(path) === true;
     return createHash("sha256")
-        .update(stableStringify({ path, value }))
+        .update(stableStringify({
+        path,
+        value: policyApplies
+            ? normalizeReadOutputFingerprintSnapshot(value, policy)
+            : value,
+        ...(policyApplies
+            ? { fingerprint_policy_version: policy.version }
+            : {}),
+    }))
         .digest("base64url")
         .slice(0, 16);
 }
@@ -105,11 +185,11 @@ export function applyReadOutputContinuation(result, command, cursor) {
     if (!collection ||
         totalRows !== cursor.total_rows ||
         cursor.offset > totalRows ||
-        readOutputCollectionFingerprint(cursor.path, collection.value) !==
+        readOutputCollectionFingerprint(cursor.path, collection.value, command) !==
             cursor.fingerprint) {
         throw new PmCliError("The read-output continuation no longer matches the declared row collection; restart the bounded read.", EXIT_CODE.USAGE, { code: "read_output_cursor_stale" });
     }
     return sliceReadOutputRowCollection(result, cursor.path, cursor.offset);
 }
 //# sourceMappingURL=continuation.js.map
-//# debugId=1c73c31e-6246-5730-8c8a-d3ba7c9ec112
+//# debugId=9e63b4b0-09a5-50bf-9f56-5f239c75ffe5

package/dist/sdk/read-output-contracts.d.ts

@@ -1,6 +1,7 @@
 export { resolveReadOutputRecoveryBudget } from "./read-output-budget.js";
 export type { PmReadOutputRecoveryBudget, PmReadOutputRecoveryBudgetInput, } from "./read-output-budget.js";
-export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, } from "./read-output/continuation.js";
+export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES, readOutputCollectionFingerprint, } from "./read-output/continuation.js";
+export type { PmReadOutputContinuationFingerprintPolicy } from "./read-output/continuation.js";
 import { type PmReadOutputSessionReceipt, type PmReadOutputSessionState } from "./read-output-session.js";
 /** Stable output dimensions shared by every read surface. */
 export declare const PM_READ_OUTPUT_DIMENSIONS: readonly ["include", "amount", "cost", "encoding"];
@@ -61,6 +62,8 @@ export interface PmReadOutputSurfaceContract {
     precedence: readonly ["canonical", "legacy", "intent", "default"];
     /** Stable policy used before budget compaction selects retained rows. */
     budget_retention_policy: "ordered_prefix" | "verdict_priority";
+    /** Exact command-local whole-result modes accepted by `outputInclude`. */
+    projection_modes?: readonly string[];
 }
 /** Source that selected an effective output dimension. */
 export type PmReadOutputDimensionSource = "canonical" | "legacy" | "intent" | "default";

package/dist/sdk/read-output-contracts.js

@@ -5,7 +5,7 @@
  * surface without coupling package authors to command-specific option names.
  */
 
-!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]="76c9c2d0-951d-579e-916e-e8d54d4a8be9")}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]="d084da05-c967-58f1-afe4-069f09838e6f")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { compactReadOutputToBudget, estimateReadOutputTokens, resolveReadOutputRecoveryBudget, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
@@ -13,7 +13,7 @@ export { resolveReadOutputRecoveryBudget } from "./read-output-budget.js";
 import { resolvePmCommandOutputBudget } from "./cli-contracts/agent-output-contracts.js";
 import { boundReadOutputRows, countReadOutputRows, mapReadOutputRows, readOutputBudgetCollections, readOutputContinuationRowCollections, readOutputRowPaths, } from "./read-output-rows.js";
 import { applyReadOutputContinuation, decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, prioritizeAssuranceAssertions, readOutputCollectionFingerprint, } from "./read-output/continuation.js";
-export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, } from "./read-output/continuation.js";
+export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES, readOutputCollectionFingerprint, } from "./read-output/continuation.js";
 import { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 import { decodeQueryCursorEnvelope, encodeQueryCursor } from "./pagination.js";
 /** Stable output dimensions shared by every read surface. */
@@ -205,6 +205,9 @@ function buildSurfaceContract(command) {
         dimensions,
         precedence: READ_OUTPUT_PRECEDENCE,
         budget_retention_policy: command === "assurance" ? "verdict_priority" : "ordered_prefix",
+        projection_modes: Object.freeze([
+            ...readOutputIncludeModeOptions(command).keys(),
+        ]),
     });
 }
 /** Universal output contract for every built-in read surface. */
@@ -1092,7 +1095,7 @@ function rebaseBudgetCompactedCursor(projected, originalItemCount, cursorSource,
     }
     return true;
 }
-function captureReadOutputContinuationState(projected, cursor, options) {
+function captureReadOutputContinuationState(projected, command, cursor, options) {
     const collectionsBeforeBudget = new Map(readOutputContinuationRowCollections(projected).map((collection) => {
         const rows = Array.isArray(collection.value)
             ? collection.value.length
@@ -1106,7 +1109,7 @@ function captureReadOutputContinuationState(projected, cursor, options) {
                 baseOffset: continued ? cursor.offset : 0,
                 fingerprint: continued
                     ? cursor.fingerprint
-                    : readOutputCollectionFingerprint(collection.path, collection.value),
+                    : readOutputCollectionFingerprint(collection.path, collection.value, command),
             },
         ];
     }));
@@ -1154,7 +1157,7 @@ export function applyReadOutputDimensions(command, options, result) {
     const continuationReadyResult = attachValidateDiagnosticRowContract(resolved.command, result);
     const bindingBudget = resolveBindingReadOutputBudget(resolved, session);
     let projected = projectReadOutputRows(continuationReadyResult, resolved, session, cursor);
-    const continuationState = captureReadOutputContinuationState(projected, cursor, options);
+    const continuationState = captureReadOutputContinuationState(projected, resolved.command, cursor, options);
     const receipt = {
         contract_version: 1,
         command: resolved.command,
@@ -1207,4 +1210,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=76c9c2d0-951d-579e-916e-e8d54d4a8be9
+//# debugId=d084da05-c967-58f1-afe4-069f09838e6f

package/dist/sdk/runtime-primitives.d.ts

@@ -13,7 +13,7 @@ export { type ActiveExtensionHookContext, type ExtensionCommandRegistry, type Ex
 export { applyRegisteredItemFieldDefaultsAndValidation, collectRegisteredItemFieldNames, parseRegisteredItemFieldAssignments, } from "../core/extensions/item-fields.js";
 export { resolveExtensionRoots } from "../core/extensions/loader.js";
 export { resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, } from "../core/extensions/runtime-registrations.js";
-export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
+export { isFileMissingError, pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
 export { normalizeBulkIdsValue, parseBulkIdsText, resolveCliBulkIdsInput, type BulkIdsFileReader, type BulkIdsInputReaders, type BulkIdsStdinReader, type BulkIdsValue, } from "../core/io/bulk-ids-input.js";
 export { type HistoryDiffValueEntry, computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";

package/dist/sdk/runtime-primitives.js

@@ -7,7 +7,7 @@
  * prefer the typed operations exported by the main SDK barrel.
  */
 
-!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]="be6f7869-f197-5d38-b8d9-faf8f390cd56")}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]="4be36c51-a9fc-507d-8f13-d764b5668ab9")}catch(e){}}();
 export { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
 export { createUnknownSubcommandError, } from "./agent/subcommand-recovery.js";
@@ -15,7 +15,7 @@ export { activateExtensions, clearActiveExtensionHooks, consumeAfterCommandAffec
 export { applyRegisteredItemFieldDefaultsAndValidation, collectRegisteredItemFieldNames, parseRegisteredItemFieldAssignments, } from "../core/extensions/item-fields.js";
 export { resolveExtensionRoots } from "../core/extensions/loader.js";
 export { resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, } from "../core/extensions/runtime-registrations.js";
-export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
+export { isFileMissingError, pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
 export { normalizeBulkIdsValue, parseBulkIdsText, resolveCliBulkIdsInput, } from "../core/io/bulk-ids-input.js";
 export { computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
@@ -82,4 +82,4 @@ export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";
 export { emitTelemetryErrorEvent, finishTelemetryCommand, startTelemetryCommand, } from "../core/telemetry/runtime.js";
 //# sourceMappingURL=runtime-primitives.js.map
-//# debugId=be6f7869-f197-5d38-b8d9-faf8f390cd56
+//# debugId=4be36c51-a9fc-507d-8f13-d764b5668ab9

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

@@ -220,6 +220,11 @@ declare function copyIntoSandboxIfPresent(sourcePath: string, targetPath: string
 }) => Promise<unknown>): Promise<void>;
 declare function seedLinkedTestSandbox(sandboxPmPath: string, sandboxGlobalPath: string, sourceRoots: LinkedTestSandboxSourceRoots): Promise<void>;
 declare function seedLinkedTestTrackerData(sourceRoot: string, sandboxRoot: string): Promise<void>;
+/**
+ * Create an audited settings snapshot only for source trackers that predate
+ * workspace history, while preserving any existing source history verbatim.
+ */
+declare function seedMissingLinkedTestSettingsHistory(sourceRoot: string, sandboxRoot: string): Promise<void>;
 declare function countLinkedTestItemFiles(pmRoot: string): Promise<number>;
 /** Implements resolve linked test failure exit code for the public runtime surface of this module. */
 export declare function resolveLinkedTestFailureExitCode(execution: Pick<LinkedTestExecutionResult, "exitCode" | "timedOut" | "maxBufferExceeded">): number;
@@ -321,6 +326,7 @@ export declare const _testOnlyTestCommand: {
     resolveTestRunOptions: typeof resolveTestRunOptions;
     resolveTrackedRunId: typeof resolveTrackedRunId;
     runLinkedTestCommand: typeof runLinkedTestCommand;
+    seedMissingLinkedTestSettingsHistory: typeof seedMissingLinkedTestSettingsHistory;
     seedLinkedTestSandbox: typeof seedLinkedTestSandbox;
     seedLinkedTestTrackerData: typeof seedLinkedTestTrackerData;
     segmentInvokesRecursiveTestAll: typeof segmentInvokesRecursiveTestAll;

package/dist/sdk/test/execution.js

@@ -4,14 +4,15 @@
  * Implements the pm test command surface and its agent-facing runtime behavior.
  */
 
-!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]="7659721c-21f5-55da-8cce-31b290de5bfb")}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]="99ce92bb-ed45-5327-b148-b5bb26a0bf05")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm, symlink, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
-import { isFileMissingError, pathExists } from "../../core/fs/fs-utils.js";
+import { isFileMissingError, pathExists, readFileIfExists, } from "../../core/fs/fs-utils.js";
+import { getWorkspaceHistoryPath, writeWorkspaceJsonWithHistory, } from "../../core/history/workspace-history.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
 import { createStdinTokenResolver, parseCsvKv, parseOptionalNumber, } from "../../core/item/parse.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
@@ -1043,6 +1044,31 @@ async function seedLinkedTestTrackerData(sourceRoot, sandboxRoot) {
         }
     }
 }
+/**
+ * Create an audited settings snapshot only for source trackers that predate
+ * workspace history, while preserving any existing source history verbatim.
+ */
+async function seedMissingLinkedTestSettingsHistory(sourceRoot, sandboxRoot) {
+    const sourceSettingsRaw = await readFileIfExists(getSettingsPath(sourceRoot));
+    if (sourceSettingsRaw === null ||
+        (await pathExists(getWorkspaceHistoryPath(sourceRoot)))) {
+        return;
+    }
+    const sandboxSettings = await readSettings(sandboxRoot);
+    await rm(getWorkspaceHistoryPath(sandboxRoot), { force: true });
+    await rm(getSettingsPath(sandboxRoot), { force: true });
+    await writeWorkspaceJsonWithHistory({
+        pmRoot: sandboxRoot,
+        filePath: getSettingsPath(sandboxRoot),
+        raw: sourceSettingsRaw,
+        op: "settings:write",
+        author: resolveAuthor(undefined, sandboxSettings.author_default),
+        lockTtlSeconds: sandboxSettings.locks.ttl_seconds,
+        lockWaitMs: sandboxSettings.locks.wait_ms,
+        recordCreation: true,
+        message: "Seed linked-test tracker settings history",
+    });
+}
 async function countLinkedTestItemFiles(pmRoot) {
     if (!(await pathExists(pmRoot))) {
         return 0;
@@ -1339,6 +1365,8 @@ async function seedLinkedTestSandboxesFromSource(layout, sourceRoots, includeTra
     await seedLinkedTestSandbox(layout.trackerProjectPmPath, layout.trackerGlobalPmPath, sourceRoots);
     await seedLinkedTestTrackerData(sourceRoots.projectPmRoot, layout.trackerProjectPmPath);
     await seedLinkedTestTrackerData(sourceRoots.globalPmRoot, layout.trackerGlobalPmPath);
+    await seedMissingLinkedTestSettingsHistory(sourceRoots.projectPmRoot, layout.trackerProjectPmPath);
+    await seedMissingLinkedTestSettingsHistory(sourceRoots.globalPmRoot, layout.trackerGlobalPmPath);
 }
 function linkedTestsRequireTrackerData(tests, runLevelPmContextMode, options) {
     return tests.some((linkedTest) => {
@@ -2124,6 +2152,7 @@ export const _testOnlyTestCommand = {
     resolveTestRunOptions,
     resolveTrackedRunId,
     runLinkedTestCommand,
+    seedMissingLinkedTestSettingsHistory,
     seedLinkedTestSandbox,
     seedLinkedTestTrackerData,
     segmentInvokesRecursiveTestAll,
@@ -2131,4 +2160,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=7659721c-21f5-55da-8cce-31b290de5bfb
+//# debugId=99ce92bb-ed45-5327-b148-b5bb26a0bf05

package/docs/AGENT_PROVENANCE_ADR.md

@@ -80,11 +80,13 @@ All new history fields are optional. Readers must accept:
 - explicit `model: null`, `effort: null`, or `role: null` observations meaning
   the dimension was declared but unavailable for a detected harness.
 
-MCP clients may supply a bounded `clientInfo.provenance` map during initialize.
+Modern MCP clients may supply a bounded
+`io.modelcontextprotocol/clientInfo.provenance` map in each request's `_meta`.
 The server retains only valid dimension names and trimmed values, then resolves
-that map inside the invocation-scoped identity context for every mutation. A
-missing MCP signal is recorded as explicit `null`; it is never confused with a
-legacy entry that predates the dimension.
+that map inside the invocation-scoped identity context for that request. The
+bounded `2025-06-18` adapter accepts the same map during legacy `initialize`.
+A missing MCP signal is recorded as explicit `null`; it is never confused with
+a legacy entry that predates the dimension.
 
 Unknown provenance dimensions are preserved as data and do not change author
 resolution. Removing a dimension from a descriptor never rewrites existing

package/docs/AGENT_RUNTIME_PRIMITIVES.md

@@ -156,11 +156,12 @@ author literals at read time; every row reports `harness_source` and
 `vocabulary_version`, and unresolved literals remain visible in the bounded
 summary. No history entry is rewritten.
 
-MCP captures `clientInfo.name` and `clientInfo.version` during initialize and
-scopes all later tool calls to that client signal. Optional host-provided
-`model`, `session`, `provenance`, and `episode` fields are supported, but
-version is not
-misclassified as a model or session. Provenance keys must use the bounded
+MCP 2026-07-28 reads `io.modelcontextprotocol/clientInfo` independently from
+every request's `_meta` and scopes only that request to the client signal. The
+bounded legacy adapter still reads `clientInfo` during `2025-06-18`
+`initialize`. Optional host-provided `model`, `session`, `provenance`, and
+`episode` fields are supported, but version is not misclassified as a model or
+session. Provenance keys must use the bounded
 lowercase dimension vocabulary; blank, malformed, and oversized data is
 discarded before mutation context is created. See
 [Agent Provenance ADR Amendment](AGENT_PROVENANCE_ADR.md) for precedence,

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -73,9 +73,10 @@ Add to the project's `.mcp.json`:
 ```
 
 The repo root `.mcp.json` uses this approach and activates automatically when
-Claude Code opens this repository. The MCP initialize handshake supplies the
-client name/version to pm's bounded identity detector, so normal agent
-mutations do not need a hard-wired `PM_AUTHOR`.
+Claude Code opens this repository. Under MCP `2026-07-28`, every request carries
+the protocol version, client capabilities, and client identity in `_meta`, so
+pm's bounded identity detector does not depend on session state and normal
+agent mutations do not need a hard-wired `PM_AUTHOR`.
 
 ## MCP Server Launcher
 
@@ -115,7 +116,10 @@ node scripts/smoke-claude-plugin.mjs
 pnpm smoke:claude-plugin
 ```
 
-Verifies: plugin file structure, manifest name consistency, MCP initialize, 31 tools present, full workflow (init → create → claim → update → link files/docs/tests → get → context → search → validate → health), and session-start hook.
+Verifies: plugin file structure, manifest name consistency, stateless MCP
+discovery for `2026-07-28`, 31 tools present, full workflow (init → create →
+claim → update → link files/docs/tests → get → context → search → validate →
+health), and session-start hook.
 
 ### MCP server smoke test
 
@@ -182,7 +186,10 @@ After installing the plugin:
 
 The authoritative plugin version is `plugins/pm-claude/.claude-plugin/plugin.json`; this row stays on the `1.x` major line so it does not drift with each plugin release.
 
-The MCP server uses JSON-RPC 2.0 over stdio with protocol version `2025-06-18`.
+The MCP server uses JSON-RPC 2.0 over stdio with canonical protocol version
+`2026-07-28`. A bounded legacy path remains for unversioned older hosts, with
+`2025-06-18` initialize available to enrich client identity; current hosts
+discover the server and send metadata on every request.
 
 ## Extension Policy Diagnostics
 

package/docs/DIAGNOSTIC_OUTPUT_CONTRACTS.md

@@ -103,6 +103,14 @@ refusal; schema, items, history, settings, and package state must not change.
 Ephemeral runtime lock/cache directories are excluded from that semantic
 snapshot.
 
+The complete error-code census currently retains executable evidence for 18
+catalog rows across 17 canonical groups. Two of those rows are author-manifest
+schema findings reached through a real `pm health --full --strict-exit --json`
+process: an unknown top-level key and omitted canonical pm version bounds. The
+remaining rows stay explicit `uncovered` obligations in
+[the generated census](generated/REFUSAL_CLOSURE_CENSUS.md); the ratchet does not
+turn partial catalog closure into an approval claim.
+
 Run the focused proof with:
 
 ```bash

package/docs/EXTENSIONS.md

@@ -1,6 +1,6 @@
 # Packages and Extensions
 
-Extension flags declared with `list: true` accumulate repeated long/short alias occurrences and comma-separated values into one array. Dynamic commands preserve flag-like variadic content after `--`, and package handlers can use the public `suppressHostOutput()` protocol when they already emitted streaming, binary, or pre-rendered output. Declarative blueprints are also checked for reserved item-field collisions during SDK lint/preflight and harness activation, so a package cannot pass author-time validation and then fail only when users create or update items. Local archive installation, command ownership, and MCP custom-field diagnostics are tracked by [pm-lw6acw](../.agents/pm/issues/pm-lw6acw.toon), [pm-6z0wzf](../.agents/pm/issues/pm-6z0wzf.toon), and [pm-yfdav2](../.agents/pm/issues/pm-yfdav2.toon). Transactional mutation guards, host-bound command test SDKs, and installed custom-type lifecycle parity are tracked by [pm-hx23u5](../.agents/pm/issues/pm-hx23u5.toon), [pm-wx2lr5](../.agents/pm/issues/pm-wx2lr5.toon), and [pm-scga6k](../.agents/pm/issues/pm-scga6k.toon). Durable migration application, explicit source resolution, and composable preflight ownership are covered in [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
+Extension flags declared with `list: true` accumulate repeated long/short alias occurrences and comma-separated values into one array. Dynamic commands preserve flag-like variadic content after `--`, and package handlers can use the public `suppressHostOutput()` protocol when they already emitted streaming, binary, or pre-rendered output. Declarative blueprints are also checked for reserved item-field collisions during SDK lint/preflight and harness activation, so a package cannot pass author-time validation and then fail only when users create or update items. Local archive installation, command ownership, MCP custom-field diagnostics, and author-manifest schema diagnostics are tracked by [pm-lw6acw](../.agents/pm/issues/pm-lw6acw.toon), [pm-6z0wzf](../.agents/pm/issues/pm-6z0wzf.toon), [pm-yfdav2](../.agents/pm/issues/pm-yfdav2.toon), and [pm-gh1091](../.agents/pm/issues/pm-gh1091.toon). Transactional mutation guards, host-bound command test SDKs, and installed custom-type lifecycle parity are tracked by [pm-hx23u5](../.agents/pm/issues/pm-hx23u5.toon), [pm-wx2lr5](../.agents/pm/issues/pm-wx2lr5.toon), and [pm-scga6k](../.agents/pm/issues/pm-scga6k.toon). Durable migration application, explicit source resolution, and composable preflight ownership are covered in [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
 
 Packages add optional `pm` workflows without changing the core CLI. A package can ship one or more runtime extensions plus metadata such as docs and examples. Prefer the package-first commands in new docs and automation:
 
@@ -191,10 +191,9 @@ useful for agents without inflating context or leaking private item content.
 
 Runnable manifest examples are the source of truth: [starter extension manifest](examples/starter-extension/manifest.json) and [policy-restricted manifest](examples/policy-restricted-extension/manifest.json).
 
-Use [extension-manifest.schema.json](schemas/extension-manifest.schema.json) as the `$schema` value for inline editor validation. The loader ignores `$schema` and tolerates future manifest fields, but the schema documents the fields pm reads.
-
-Rules:
+Use [extension-manifest.schema.json](schemas/extension-manifest.schema.json) as the `$schema` value for inline editor validation. The loader ignores `$schema` and tolerates future manifest fields, but the schema documents the fields pm reads. Rules:
 
+- `manifest.json` is the runtime declaration; package catalog metadata belongs in `package.json#pm`, and a top-level `compatibility` object is ignored. Use the public `inspectExtensionManifestSchema` / `lintExtensionManifestSchema` helpers for schema-only checks. In author workspaces, `pm health --full`, `pm package doctor`, and `pm extension --doctor` expose the same read-only `author_manifest` findings without activating the extension.
 - `entry` must resolve inside the extension directory.
 - `manifest_version` is an optional integer identifying the manifest schema generation. Runtime contracts currently support manifest versions `1` and `2`, and first-party runnable examples use `2`. First-party packages declare it; the manifest governance test requires it on every first-party package.
 - `pm_min_version` is an inclusive minimum pm CLI version. If the running CLI is older, discovery emits `extension_pm_min_version_unmet:<layer>:<name>:required=<version>:current=<version>` and skips the extension before import.

package/docs/MCP_2026_07_28.md

@@ -0,0 +1,138 @@
+# MCP 2026-07-28 Protocol and Compatibility Decision
+
+Tracker references: [pm-sqvshj](../.agents/pm/decisions/pm-sqvshj.toon),
+[pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon), and
+[pm-55yf1t](../.agents/pm/tasks/pm-55yf1t.toon). MRTR, durable tasks,
+and the cache/schema surface are tracked by
+[pm-rz9gep](../.agents/pm/features/pm-rz9gep.toon),
+[pm-rzs24j](../.agents/pm/features/pm-rzs24j.toon), and
+[pm-hv1x1x](../.agents/pm/features/pm-hv1x1x.toon). Subscriptions,
+Streamable HTTP, remote authorization, and the deprecation ratchet are tracked
+by [pm-v7e337](../.agents/pm/features/pm-v7e337.toon),
+[pm-3zh9s4](../.agents/pm/features/pm-3zh9s4.toon), and
+[pm-vzcisw](../.agents/pm/chores/pm-vzcisw.toon).
+
+Status: accepted. MCP `2026-07-28` is pm's canonical protocol revision.
+
+## Decision
+
+The public pm SDK owns protocol versions, request metadata validation,
+capability checks, discovery, result envelopes, error codes, HTTP header
+parity, subscriptions, authorization boundaries, trace isolation, and legacy
+result interpretation. `pm-mcp` is a JSON-RPC/stdio adapter over those
+contracts; `pm-mcp-http` binds the same dispatcher to sessionless Streamable
+HTTP POST.
+
+Modern requests are stateless. Every request carries:
+
+- `io.modelcontextprotocol/protocolVersion` = `2026-07-28`;
+- `io.modelcontextprotocol/clientCapabilities` as an object, including `{}`;
+- optional `io.modelcontextprotocol/clientInfo` with `name` and `version`.
+
+Every modern result carries an explicit `resultType` (`complete`,
+`input_required`, or `task`) and `io.modelcontextprotocol/serverInfo` in
+result `_meta`. The mandatory
+`server/discover` method returns the supported modern revisions, deterministic
+capabilities, public cache policy, server identity, and bounded instructions.
+No modern request reads identity, capabilities, or version from a previous
+request.
+
+## Legacy boundary
+
+The sole supported legacy revision is `2025-06-18`, accepted through the
+existing stdio adapter. Unversioned requests stay on this legacy path because
+they cannot claim the current revision; `initialize` enriches their client
+identity but is not required for compatibility with older pm hosts. The
+adapter has no session id, does not affect modern requests, and is excluded
+from `server/discover`'s `supportedVersions` because it cannot be selected
+through modern per-request metadata.
+
+The adapter is scheduled for removal only after published-client telemetry and
+release probes show no required legacy consumers for two consecutive release
+windows. Removal is a reviewed compatibility change, never a history rewrite.
+
+## Transport behavior
+
+- Stdio modern clients call `server/discover` with current request metadata,
+  then send the same version and capability keys on every request.
+- Stdio legacy clients retain their existing response shapes and may use
+  `initialize` with `2025-06-18` to supply client identity.
+- Streamable HTTP requires `MCP-Protocol-Version` and `Mcp-Method` on every
+  request. `Mcp-Name` is required only for `prompts/get`, `resources/read`, and
+  `tools/call`; other methods omit it. Schema-declared `x-mcp-header` values are
+  encoded, decoded, and compared with tool arguments before dispatch.
+  Header/version mismatch uses code `-32020` and HTTP 400.
+- `subscriptions/listen` is a request-scoped stdio or SSE stream. The first
+  message acknowledges the supported filter; later messages carry its request
+  id as `io.modelcontextprotocol/subscriptionId`. Disconnect deletes the
+  subscription and a caller retries lost work with a new request id.
+- The remote adapter defaults to loopback, enforces exact browser origins,
+  bounds bodies, maps parse/invalid requests to HTTP 400, and can require an
+  issuer-, audience-, and scope-bound bearer token.
+- Unsupported modern versions return `-32022` plus the exact supported modern
+  list. Missing required capabilities return `-32021` with a structured
+  capability map. Malformed metadata uses JSON-RPC Invalid Params `-32602`.
+
+## Removed, migrated, and deprecated behavior
+
+| Prior behavior                                                    | Disposition                                                                                                 |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `initialize` and `notifications/initialized`                      | Legacy stdio adapter only; absent from modern behavior.                                                     |
+| `Mcp-Session-Id` and protocol sessions                            | Removed; explicit application handles are ordinary arguments.                                               |
+| `ping`                                                            | Legacy adapter only; modern calls return Method Not Found.                                                  |
+| `resources/subscribe` and `resources/unsubscribe`                 | Replaced by the implemented `subscriptions/listen` filter.                                                  |
+| SSE event ids and `Last-Event-ID` replay                          | Removed; callers retry with a new request id.                                                               |
+| Reverse `roots/list`, sampling, and elicitation requests          | Migrate to MRTR `input_required` under `pm-rz9gep`.                                                         |
+| Core tasks                                                        | Migrate to `io.modelcontextprotocol/tasks` under `pm-rzs24j`.                                               |
+| `logging/setLevel`                                                | Removed; optional request-local log metadata is never shared, and remote operations use host OpenTelemetry. |
+| Roots, Sampling, Logging, HTTP+SSE, and non-none `includeContext` | Retain only in bounded legacy compatibility while `pm-vzcisw` drives deprecation removal.                   |
+| Dynamic Client Registration                                       | Legacy authorization fallback; Client ID Metadata Documents are canonical under `pm-3zh9s4`.                |
+
+## Rollout, rollback, and proof
+
+Local and hosted gates must prove SDK primitives, direct server calls, real
+stdio, packed artifacts, npx, bunx, and published artifacts agree on discovery
+and the canonical revision. Negative controls cover unsupported versions,
+missing/malformed metadata, missing capabilities, header mismatch, removed
+methods, and omitted modern `resultType`.
+
+Rollback preserves the SDK contract and re-enables only the reviewed legacy
+adapter. It must never reintroduce session ids or make modern behavior depend
+on initialization. Release evidence records exact source, package, tag, and
+consumer revisions separately.
+
+## MRTR, tasks, and cache behavior
+
+An SDK handler that cannot finish without host input throws
+`PmMcpInputRequiredError`. The modern adapter validates the requested
+`elicitation/create`, `roots/list`, or `sampling/createMessage` capability and
+returns `resultType: "input_required"`. Continuation state can be bounded,
+HMAC-sealed, expiry-bound, method-bound, parameter-bound, principal-bound, and
+protected from in-process replay with the public interaction helpers. Retry
+payloads arrive as request-local `inputResponses`; they never depend on a
+protocol session.
+
+Clients negotiate `io.modelcontextprotocol/tasks` in request capabilities.
+Eligible long-running `tools/call` operations can then return a durable task
+handle. `tasks/get`, `tasks/update`, and `tasks/cancel` are principal-scoped,
+persist records atomically under the ignored tracker runtime area, enforce
+immutable terminal states, expire abandoned work deterministically, and turn
+a disappeared worker into an actionable terminal failure. Task state remains
+retrieved through the task methods. Change subscriptions do not become
+task-progress channels, and pm's current handlers do not emit request progress
+or deprecated log-message notifications.
+
+Modern tool, resource, resource-template, and prompt list/read results carry
+explicit `ttlMs` and `cacheScope`. Tool schemas are validated as bounded JSON
+Schema 2020-12 documents before advertisement. Tool and resource data stay
+private; public metadata lists may be cached for their advertised lifetime.
+
+## Public SDK
+
+Use `PM_MCP_PROTOCOL_VERSION`, `resolveMcpRequestContext()`,
+`buildMcpDiscoverResult()`, `buildMcpCompleteResult()`,
+`PmMcpSubscriptionRegistry`, `buildMcpHttpRequestHeaders()`,
+`validateMcpHttpRequestHeaders()`, `buildMcpProtectedResourceMetadata()`, and
+the issuer/trace authorization helpers from `@unbrained/pm-cli/sdk`. See
+[MCP interaction and task SDK](SDK_MCP_INTERACTIONS.md) and
+[remote transport, authorization, and migration](MCP_REMOTE_TRANSPORT_SECURITY.md).