@unbrained/pm-cli 2026.8.25 → 2026.8.27

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/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]="d084da05-c967-58f1-afe4-069f09838e6f")}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]="2103a4dc-3037-5768-b2c7-5964de4ac86b")}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";
@@ -388,7 +388,20 @@ export function applyReadOutputIncludeModes(command, includeValue, commandOption
         modes.push(token);
         canonicalModes.add(token);
     }
-    if (modes.length > 0) {
+    const forwardedGetFieldSelectors = resolveReadOutputSurface(command) === "get"
+        ? selectors.filter((selector) => selector !== "item")
+        : [];
+    const forwardedGetFields = forwardedGetFieldSelectors.length > 0;
+    if (forwardedGetFields) {
+        commandOptions.fields = [
+            ...new Set([
+                ...(stringList(commandOptions.fields) ?? []),
+                ...forwardedGetFieldSelectors,
+            ]),
+        ].join(",");
+        canonicalModes.add("fields");
+    }
+    if (modes.length > 0 || forwardedGetFields) {
         optionsWithProvenance[READ_OUTPUT_INVOCATION_PROVENANCE] = {
             canonical_include_modes: [...canonicalModes],
             explicit_legacy_aliases: [...explicitLegacyAliases],
@@ -1210,4 +1223,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=d084da05-c967-58f1-afe4-069f09838e6f
+//# debugId=2103a4dc-3037-5768-b2c7-5964de4ac86b

package/dist/sdk/runtime-action-aliases.js

@@ -4,8 +4,8 @@
  * Declares canonical native-action routes for public SDK aliases.
  */
 
-!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]="6f62939a-7b99-5687-93ae-834e0032f1d5")}catch(e){}}();
-import { PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS } from "./cli-contracts/enum-contracts.js";
+!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]="1ff4005f-be23-5dcf-9834-dbd7d083b76d")}catch(e){}}();
+import { PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_PACKAGE_ONLY_ACTION_SUBCOMMANDS, } from "./cli-contracts/enum-contracts.js";
 const LIST_ACTION_ALIASES = {
     "list-all": { action: "list", options: { excludeTerminal: false } },
     "list-draft": {
@@ -51,6 +51,10 @@ export const SDK_ACTION_ALIASES = {
     ...LIST_ACTION_ALIASES,
     ...buildExtensionPackageActionAliases("extension"),
     ...buildExtensionPackageActionAliases("package"),
+    ...Object.fromEntries(PM_PACKAGE_ONLY_ACTION_SUBCOMMANDS.map((subcommand) => [
+        `package-${subcommand}`,
+        { action: subcommand },
+    ])),
 };
 //# sourceMappingURL=runtime-action-aliases.js.map
-//# debugId=6f62939a-7b99-5687-93ae-834e0032f1d5
+//# debugId=1ff4005f-be23-5dcf-9834-dbd7d083b76d

package/dist/sdk/runtime-input.js

@@ -5,7 +5,7 @@
  * primitives are shared by native action dispatchers and MCP-specific adapters.
  */
 
-!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]="2a1e986f-304d-50f6-a405-6afc221bdad5")}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]="7949205a-ab1b-5457-961c-593498aff88b")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { asRecordClone } from "../core/shared/primitives.js";
@@ -202,6 +202,15 @@ const HOISTED_ACTION_OPTION_KEYS = {
     update: ["parent", "allowMissingParent", "completedAt"],
     copy: ["allowDuplicate"],
     close: ["duplicateOf", "completedAt"],
+    upgrade: [
+        "scope",
+        "dryRun",
+        "cliOnly",
+        "packagesOnly",
+        "repair",
+        "tag",
+        "packageName",
+    ],
     // pm-7u9j: the narrow pm_append tool declares `body` top-level; runAppend
     // reads it from options, while schema/config consume their top-level values
     // directly in runAction and therefore need no hoisting.
@@ -232,8 +241,7 @@ export function normalizeMcpOptionsArrays(options, action = "") {
             result[key] = value;
             continue;
         }
-        if (typeof value === "string" &&
-            scalarToArrayFields.has(key)) {
+        if (typeof value === "string" && scalarToArrayFields.has(key)) {
             result[key] = [value];
             continue;
         }
@@ -578,4 +586,4 @@ export function updateManyOptionsFromFlat(options) {
     };
 }
 //# sourceMappingURL=runtime-input.js.map
-//# debugId=2a1e986f-304d-50f6-a405-6afc221bdad5
+//# debugId=7949205a-ab1b-5457-961c-593498aff88b

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";
@@ -75,7 +75,7 @@ export { migrateItemFilesToFormat } from "../core/store/item-format-migration.js
 export { type CachedDocumentCandidate, listAllDocumentCandidatesCached, } from "../core/store/item-metadata-cache.js";
 export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, mutateItemWithHistoryContext, readLocatedItem, } from "../core/store/item-store.js";
 export { isTerminalPlanMode, shouldCompletePlanOnClose, } from "../core/item/plan-lifecycle.js";
-export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
+export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, resolveWorkspaceRoot, } from "../core/store/paths.js";
 export { persistSelectedItemFormat, readSettings, readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";
 export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { type TelemetryCommandResolution, type TelemetryResolutionStage, deriveTelemetryCommandResolution, } from "../core/telemetry/observability.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]="d45775e5-6826-521b-80b3-429ed22947d9")}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";
@@ -76,10 +76,10 @@ export { migrateItemFilesToFormat } from "../core/store/item-format-migration.js
 export { listAllDocumentCandidatesCached, } from "../core/store/item-metadata-cache.js";
 export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, mutateItemWithHistoryContext, readLocatedItem, } from "../core/store/item-store.js";
 export { isTerminalPlanMode, shouldCompletePlanOnClose, } from "../core/item/plan-lifecycle.js";
-export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
+export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, resolveWorkspaceRoot, } from "../core/store/paths.js";
 export { persistSelectedItemFormat, readSettings, readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";
 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=d45775e5-6826-521b-80b3-429ed22947d9

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,