@unbrained/pm-cli 2026.8.25 → 2026.8.26

package/dist/sdk/mcp/transport.js

@@ -0,0 +1,261 @@
+/**
+ * @module sdk/mcp/transport
+ *
+ * Implements MCP 2026-07-28 Streamable HTTP header encoding, schema-derived
+ * custom header extraction, and body/header parity validation.
+ */
+
+!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]="5ffe7128-0fbb-59af-89ef-74d5d799a00d")}catch(e){}}();
+import { PM_MCP_ERROR_CODES, PM_MCP_PROTOCOL_VERSION, PmMcpProtocolError, isMcpRecord, resolveMcpRequestContext, } from "./protocol.js";
+const BASE64_SENTINEL_PATTERN = /^=\?base64\?([A-Za-z0-9+/]*={0,2})\?=$/u;
+const HEADER_NAME_TOKEN_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
+const PLAIN_HEADER_VALUE_PATTERN = /^[\t\x20-\x7E]*$/u;
+const REQUIRED_NAME_METHODS = new Set([
+    "prompts/get",
+    "resources/read",
+    "tools/call",
+]);
+function normalizedHeaders(headers) {
+    const normalized = new Map();
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        const entry = typeof value === "string" ? value : value.join(", ");
+        normalized.set(name.toLowerCase(), entry);
+    }
+    return normalized;
+}
+function failHeader(message, header) {
+    throw new PmMcpProtocolError(message, PM_MCP_ERROR_CODES.headerMismatch, {
+        header,
+    });
+}
+/** Encode a name or primitive parameter into the protocol's safe header form. */
+export function encodeMcpHttpHeaderValue(value) {
+    const serialized = typeof value === "boolean" ? String(value).toLowerCase() : String(value);
+    if (serialized.length > 0 &&
+        serialized.trim() === serialized &&
+        PLAIN_HEADER_VALUE_PATTERN.test(serialized) &&
+        !BASE64_SENTINEL_PATTERN.test(serialized)) {
+        return serialized;
+    }
+    return `=?base64?${Buffer.from(serialized, "utf8").toString("base64")}?=`;
+}
+/** Decode and validate a mirrored MCP header value. */
+export function decodeMcpHttpHeaderValue(value, header) {
+    const sentinel = BASE64_SENTINEL_PATTERN.exec(value);
+    if (sentinel) {
+        const encoded = sentinel[1];
+        const decoded = Buffer.from(encoded, "base64");
+        if (decoded.toString("base64") !== encoded || decoded.length === 0) {
+            return failHeader("Malformed MCP Base64 header value", header);
+        }
+        return decoded.toString("utf8");
+    }
+    if (value.length === 0 ||
+        value.trim() !== value ||
+        !PLAIN_HEADER_VALUE_PATTERN.test(value)) {
+        return failHeader("Malformed MCP header value", header);
+    }
+    return value;
+}
+function containsHeaderAnnotation(value) {
+    if (Array.isArray(value))
+        return value.some(containsHeaderAnnotation);
+    if (!isMcpRecord(value))
+        return false;
+    return (Object.prototype.hasOwnProperty.call(value, "x-mcp-header") ||
+        Object.values(value).some(containsHeaderAnnotation));
+}
+/** Validate and normalize one schema-derived custom-header annotation. */
+function parseMcpHeaderAnnotation(propertySchema, propertyPath, names) {
+    const annotation = propertySchema["x-mcp-header"];
+    if (annotation === undefined)
+        return undefined;
+    const type = propertySchema.type;
+    if (typeof annotation !== "string" ||
+        !HEADER_NAME_TOKEN_PATTERN.test(annotation) ||
+        !["boolean", "integer", "string"].includes(String(type)) ||
+        names.has(annotation.toLowerCase())) {
+        throw new PmMcpProtocolError("Invalid MCP x-mcp-header annotation", PM_MCP_ERROR_CODES.invalidParams, { field: propertyPath.join("."), annotation });
+    }
+    names.add(annotation.toLowerCase());
+    return {
+        name: annotation,
+        path: propertyPath,
+        type: type,
+    };
+}
+/** Parse valid statically reachable custom-header annotations from a tool schema. */
+export function collectMcpHeaderAnnotations(schema) {
+    if (!isMcpRecord(schema)) {
+        throw new PmMcpProtocolError("Invalid MCP tool schema", PM_MCP_ERROR_CODES.invalidParams, { field: "inputSchema", expected: "object" });
+    }
+    const annotations = [];
+    const names = new Set();
+    const visitProperties = (node, path) => {
+        const properties = node.properties;
+        if (properties === undefined)
+            return;
+        if (!isMcpRecord(properties)) {
+            throw new PmMcpProtocolError("Invalid MCP tool schema properties", PM_MCP_ERROR_CODES.invalidParams, { field: "inputSchema.properties" });
+        }
+        for (const [property, propertySchema] of Object.entries(properties)) {
+            if (!isMcpRecord(propertySchema))
+                continue;
+            const propertyPath = [...path, property];
+            const annotation = parseMcpHeaderAnnotation(propertySchema, propertyPath, names);
+            if (annotation)
+                annotations.push(annotation);
+            for (const [keyword, nested] of Object.entries(propertySchema)) {
+                if (keyword !== "properties" &&
+                    keyword !== "x-mcp-header" &&
+                    containsHeaderAnnotation(nested)) {
+                    throw new PmMcpProtocolError("MCP x-mcp-header is not statically reachable", PM_MCP_ERROR_CODES.invalidParams, { field: propertyPath.join("."), keyword });
+                }
+            }
+            visitProperties(propertySchema, propertyPath);
+        }
+    };
+    for (const [keyword, nested] of Object.entries(schema)) {
+        if (keyword !== "properties" && containsHeaderAnnotation(nested)) {
+            throw new PmMcpProtocolError("MCP x-mcp-header is not statically reachable", PM_MCP_ERROR_CODES.invalidParams, { field: "inputSchema", keyword });
+        }
+    }
+    visitProperties(schema, []);
+    return annotations;
+}
+function valueAtPath(value, path) {
+    let current = value;
+    for (const part of path) {
+        if (!isMcpRecord(current))
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function mirroredName(method, params) {
+    const value = method === "resources/read" ? params.uri : params.name;
+    return typeof value === "string" ? value : undefined;
+}
+function buildMcpCustomRequestHeaders(params, toolSchema) {
+    const argumentsValue = isMcpRecord(params.arguments) ? params.arguments : {};
+    const headers = {};
+    for (const annotation of collectMcpHeaderAnnotations(toolSchema)) {
+        const value = valueAtPath(argumentsValue, annotation.path);
+        if (value === undefined || value === null)
+            continue;
+        const valid = (annotation.type === "integer" &&
+            typeof value === "number" &&
+            Number.isSafeInteger(value)) ||
+            (annotation.type === "boolean" && typeof value === "boolean") ||
+            (annotation.type === "string" && typeof value === "string");
+        if (!valid) {
+            throw new PmMcpProtocolError("Invalid MCP custom header argument", PM_MCP_ERROR_CODES.invalidParams, { field: annotation.path.join("."), expected: annotation.type });
+        }
+        headers[`Mcp-Param-${annotation.name}`] = encodeMcpHttpHeaderValue(value);
+    }
+    return headers;
+}
+/** Build required Streamable HTTP headers for one modern client request. */
+export function buildMcpHttpRequestHeaders(input) {
+    const params = isMcpRecord(input.request.params)
+        ? input.request.params
+        : undefined;
+    const context = resolveMcpRequestContext(params);
+    const method = input.request.method;
+    if (typeof method !== "string" || method.length === 0) {
+        return failHeader("Missing MCP request method", "Mcp-Method");
+    }
+    const headers = {
+        Accept: "application/json, text/event-stream",
+        "Content-Type": "application/json",
+        "MCP-Protocol-Version": context.protocolVersion,
+        "Mcp-Method": method,
+    };
+    const name = mirroredName(method, params);
+    if (REQUIRED_NAME_METHODS.has(method)) {
+        if (name === undefined)
+            return failHeader("Missing MCP request name", "Mcp-Name");
+        headers["Mcp-Name"] = encodeMcpHttpHeaderValue(name);
+    }
+    if (method === "tools/call" && input.toolSchema !== undefined) {
+        Object.assign(headers, buildMcpCustomRequestHeaders(params, input.toolSchema));
+    }
+    return headers;
+}
+function validateMcpRequiredRequestHeaders(headers, request) {
+    const method = request.method;
+    if (typeof method !== "string" || method.length === 0) {
+        failHeader("Missing MCP request method", "Mcp-Method");
+    }
+    const params = isMcpRecord(request.params) ? request.params : undefined;
+    const expectedProtocol = resolveMcpRequestContext(params).protocolVersion;
+    if (headers.get("mcp-protocol-version") !== expectedProtocol) {
+        failHeader("MCP protocol header does not match request metadata", "MCP-Protocol-Version");
+    }
+    if (headers.get("mcp-method") !== method) {
+        failHeader("MCP method header does not match request body", "Mcp-Method");
+    }
+    if (REQUIRED_NAME_METHODS.has(method)) {
+        const headerName = headers.get("mcp-name");
+        const name = mirroredName(method, params);
+        if (headerName === undefined ||
+            name === undefined ||
+            decodeMcpHttpHeaderValue(headerName, "Mcp-Name") !== name) {
+            failHeader("MCP name header does not match request body", "Mcp-Name");
+        }
+    }
+    if (headers.has("last-event-id")) {
+        // The preceding match is an mcp-deprecation-negative-control: no resume/redelivery.
+        failHeader("MCP SSE resumability is not supported", "Last-Event-ID");
+    }
+}
+function customHeaderMatches(annotation, value, decoded) {
+    if (annotation.type === "integer") {
+        return (typeof value === "number" &&
+            Number.isSafeInteger(value) &&
+            Number(decoded) === value);
+    }
+    if (annotation.type === "boolean") {
+        return typeof value === "boolean" && decoded === String(value);
+    }
+    return typeof value === "string" && decoded === value;
+}
+function validateMcpCustomRequestHeaders(input) {
+    const argumentsValue = isMcpRecord(input.params.arguments)
+        ? input.params.arguments
+        : {};
+    for (const annotation of collectMcpHeaderAnnotations(input.toolSchema)) {
+        const value = valueAtPath(argumentsValue, annotation.path);
+        const header = `Mcp-Param-${annotation.name}`;
+        const mirrored = input.headers.get(header.toLowerCase());
+        if (value === undefined || value === null) {
+            if (mirrored !== undefined)
+                failHeader("Unexpected MCP parameter header", header);
+            continue;
+        }
+        if (mirrored === undefined)
+            failHeader("Missing MCP parameter header", header);
+        if (!customHeaderMatches(annotation, value, decodeMcpHttpHeaderValue(mirrored, header))) {
+            failHeader("MCP parameter header does not match request body", header);
+        }
+    }
+}
+/** Validate required Streamable HTTP headers against the JSON-RPC body. */
+export function validateMcpHttpRequestHeaders(input) {
+    const headers = normalizedHeaders(input.headers);
+    const method = typeof input.request.method === "string" ? input.request.method : "";
+    validateMcpRequiredRequestHeaders(headers, input.request);
+    if (method !== "tools/call" || input.toolSchema === undefined)
+        return;
+    validateMcpCustomRequestHeaders({
+        headers,
+        params: input.request.params,
+        toolSchema: input.toolSchema,
+    });
+}
+/** Required protocol version exposed for clients constructing headers manually. */
+export const PM_MCP_HTTP_PROTOCOL_VERSION = PM_MCP_PROTOCOL_VERSION;
+//# sourceMappingURL=transport.js.map
+//# debugId=5ffe7128-0fbb-59af-89ef-74d5d799a00d

package/dist/sdk/merge/receipts.d.ts

@@ -77,6 +77,17 @@ export interface MergeReceiptEvidenceScan {
     /** Number of JSON receipt candidates that could not be validated safely. */
     invalid_evidence_count: number;
 }
+declare function prepareReceiptSettlement(params: {
+    receiptPath: string;
+    receiptId: string;
+    evidenceSource: "clone_local" | "durable";
+    reconciledAt: string;
+    readReceipt?: (receiptPath: string) => Promise<string | null>;
+}): Promise<{
+    path: string;
+    content: string;
+    fingerprint: string;
+} | null>;
 /** Convert a raw receipt into privacy-safe history context. */
 export declare function summarizeMergeReceipt(receipt: MergeDecisionReceipt): MergeDecisionReceiptSummary;
 /** Persist one item-driver outcome in the clone-local Git directory. */
@@ -123,3 +134,8 @@ export declare function runMergeReceiptReport(options: {
     /** Repository directory to inspect; defaults to the process working directory. */
     cwd?: string;
 }): Promise<MergeReceiptReport>;
+/** Test-only seams for deterministic receipt-boundary fault coverage. */
+export declare const _testOnlyMergeReceipts: {
+    prepareReceiptSettlement: typeof prepareReceiptSettlement;
+};
+export {};

package/dist/sdk/merge/receipts.js

@@ -7,7 +7,7 @@
  * value for the coordinator that performed the merge.
  */
 
-!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]="5add49c0-25be-5159-abfc-6c7ae9272f6b")}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]="145a6d31-5e14-5b0b-95fb-6f837d11e2f4")}catch(e){}}();
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { readdir } from "node:fs/promises";
@@ -222,7 +222,7 @@ async function readBoundedRegularReceiptFile(receiptPath) {
 async function prepareReceiptSettlement(params) {
     let raw;
     try {
-        raw = await readBoundedRegularReceiptFile(params.receiptPath);
+        raw = await (params.readReceipt ?? readBoundedRegularReceiptFile)(params.receiptPath);
     }
     catch (error) {
         if (isFileAbsentError(error))
@@ -467,6 +467,10 @@ export async function markMergeReceiptReconciled(cwd, receipt, options = {}) {
         }
         return;
     }
+    const receiptEvidenceSource = receipt.evidence_source ?? "clone_local";
+    if (!isMergeDecisionReceipt(receipt, receiptEvidenceSource)) {
+        throw new Error("Merge receipt trusted settlement input failed schema validation.");
+    }
     const reconciledAt = nowIso();
     const localPath = path.join(directory, receiptFileName(receipt.id));
     const trackerRoot = await resolveTrackerRootFromItemPath(cwd, receipt.item_path);
@@ -498,11 +502,6 @@ export async function markMergeReceiptReconciled(cwd, receipt, options = {}) {
         }
         return;
     }
-    const receiptEvidenceSource = receipt.evidence_source ?? "clone_local";
-    const trustedReceiptId = receipt.id;
-    if (!isMergeDecisionReceipt(receipt, receiptEvidenceSource)) {
-        throw new Error(`Receipt ${trustedReceiptId} trusted settlement input failed schema validation.`);
-    }
     const expectedFingerprint = receiptProvenanceFingerprint(receipt);
     if (new Set([expectedFingerprint, ...writes.map((write) => write.fingerprint)])
         .size !== 1) {
@@ -525,5 +524,7 @@ export async function runMergeReceiptReport(options) {
         generated_at: nowIso(),
     };
 }
+/** Test-only seams for deterministic receipt-boundary fault coverage. */
+export const _testOnlyMergeReceipts = { prepareReceiptSettlement };
 //# sourceMappingURL=receipts.js.map
-//# debugId=5add49c0-25be-5159-abfc-6c7ae9272f6b
+//# debugId=145a6d31-5e14-5b0b-95fb-6f837d11e2f4

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.