@unbrained/pm-cli 2026.8.23 → 2026.8.25

package/dist/sdk/governance/health.js

@@ -4,7 +4,7 @@
  * Implements the pm health 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]="f7b3ff92-1fc7-55e9-aa76-af956714998f")}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]="5887be76-3d1d-56fb-9cae-cf972f0b73f8")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
@@ -45,7 +45,8 @@ import { buildCapabilityContractMetadata, buildRegistrationCollisionRemediation,
 import { scanStaleInProgressItems, } from "./stale-work.js";
 import { scanTrackedRuntimeCache } from "./tracked-runtime-cache.js";
 import { auditMergeDriverConfiguration, findGitWorkspaceRoot, } from "../merge/install.js";
-import { listMergeReceipts, partitionMergeReceipts, } from "../merge/receipts.js";
+import { inspectMergeReceiptEvidence, partitionMergeReceipts, } from "../merge/receipts.js";
+import { runHistoryRepair } from "../history-repair.js";
 import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
 import { analyzeHierarchyIntegrity, } from "../graph/hierarchy-integrity.js";
 const PM_TELEMETRY_SOURCE_CONTEXT_SET = new Set(PM_TELEMETRY_SOURCE_CONTEXT_VALUES);
@@ -333,6 +334,11 @@ function buildHierarchyIntegrityWarnings(analysis) {
             : `integrity_hierarchy_divergence:${finding.child_id}`),
     ];
 }
+function buildMergeReceiptEvidenceWarnings(invalidEvidenceCount) {
+    return invalidEvidenceCount === 0
+        ? []
+        : [`merge_receipt_evidence_invalid:${invalidEvidenceCount}`];
+}
 async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDrivers, items) {
     const itemScan = await scanItemIntegrity(pmRoot, typeToFolder, schema);
     const historyScan = await scanHistoryIntegrity(pmRoot);
@@ -344,12 +350,11 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
     const mergeDriverAudit = gitWorkspaceRoot === null
         ? null
         : await auditMergeDriverConfiguration(gitWorkspaceRoot);
-    const pendingMergeReceipts = gitWorkspaceRoot === null
-        ? []
-        : await listMergeReceipts(gitWorkspaceRoot, {
-            includeLossless: true,
-            pmRoot,
-        });
+    const mergeReceiptEvidence = await inspectMergeReceiptEvidence(gitWorkspaceRoot ?? pmRoot, {
+        includeLossless: true,
+        pmRoot,
+    });
+    const pendingMergeReceipts = mergeReceiptEvidence.receipts;
     const { pendingDecisions: pendingMergeDecisions, lossless: losslessMergeReceipts, } = partitionMergeReceipts(pendingMergeReceipts);
     const mergeDriverInstallationMissing = mergeDriverAudit?.status === "missing" &&
         mergeDriverAudit.missing_keys.length === 5 &&
@@ -379,6 +384,10 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
         ...(pendingMergeDecisions.length > 0
             ? [`merge_decisions_unreviewed:${pendingMergeDecisions.length}`]
             : []),
+        ...(losslessMergeReceipts.length > 0
+            ? [`merge_receipts_pending:${losslessMergeReceipts.length}`]
+            : []),
+        ...buildMergeReceiptEvidenceWarnings(mergeReceiptEvidence.invalid_evidence_count),
     ];
     const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
     const actionableWarnings = normalizedWarnings.filter((warning) => !warning.startsWith("integrity_legacy_hierarchy_"));
@@ -409,6 +418,7 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                             mergeDriverAudit.drifted_keys.length,
                     pending_merge_decisions: pendingMergeDecisions.length,
                     lossless_merge_receipts: losslessMergeReceipts.length,
+                    invalid_merge_receipt_evidence: mergeReceiptEvidence.invalid_evidence_count,
                 },
                 item_unreadable: itemScan.unreadable,
                 item_conflict_markers: itemScan.conflictMarkers,
@@ -443,6 +453,8 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
             },
         },
         warnings: normalizedWarnings,
+        gitWorkspaceRoot,
+        pendingMergeReceipts,
     };
 }
 /* c8 ignore start -- activate export shape variants are exercised through integration load tests */
@@ -949,6 +961,7 @@ const HEALTH_DETAIL_SUMMARIZERS = {
         checked_items: details.checked_items,
         counts: details.counts,
         drifted_items: summarizeStringList(details.drifted_items, limit),
+        merge_receipt_attributed_items: summarizeStringList(details.merge_receipt_attributed_items, limit),
         missing_streams: summarizeStringList(details.missing_streams, limit),
         unreadable_streams: summarizeStringList(details.unreadable_streams, limit),
         hash_mismatches: summarizeStringList(details.hash_mismatches, limit),
@@ -1922,7 +1935,9 @@ function buildHealthFindings(params) {
 function rewriteBulkHealthRemediation(params) {
     if (params.check.name === "history_drift" && params.historyDriftedCount > 1) {
         for (const code of Object.keys(params.remediationMap)) {
-            params.remediationMap[code] = "pm history-repair --all";
+            if (code !== "history_drift_merge_receipt") {
+                params.remediationMap[code] = "pm history-repair --all";
+            }
         }
     }
     if (params.check.name === "storage" && params.overThresholdCount > 1) {
@@ -1945,6 +1960,67 @@ function attachHealthRemediationMaps(params) {
         }
     }
 }
+async function correlateMergeReceiptHistoryDriftItems(params) {
+    if (params.gitWorkspaceRoot === null ||
+        params.pendingMergeReceipts.length === 0) {
+        return [];
+    }
+    const details = params.historyDriftCheck.check.details;
+    const hashMismatches = Array.isArray(details.hash_mismatches)
+        ? details.hash_mismatches.filter((entry) => typeof entry === "string")
+        : [];
+    const unsafeStreamIds = new Set([
+        details.missing_streams,
+        details.unreadable_streams,
+        details.chain_mismatches,
+    ].flatMap((value) => (Array.isArray(value) ? value : [])));
+    const cloneLocalReceiptsByItem = new Map();
+    for (const receipt of params.pendingMergeReceipts) {
+        if (receipt.evidence_source !== "clone_local")
+            continue;
+        const receipts = cloneLocalReceiptsByItem.get(receipt.item_id) ?? [];
+        receipts.push(receipt);
+        cloneLocalReceiptsByItem.set(receipt.item_id, receipts);
+    }
+    const attributed = [];
+    for (const id of hashMismatches) {
+        if (unsafeStreamIds.has(id))
+            continue;
+        const receipts = cloneLocalReceiptsByItem.get(id);
+        if (!receipts || receipts.length === 0)
+            continue;
+        try {
+            const repair = await runHistoryRepair(id, {
+                dryRun: true,
+                mergeReceiptProof: {
+                    gitWorkspaceRoot: params.gitWorkspaceRoot,
+                    receipts,
+                },
+            }, params.global);
+            if (repair.merge_receipt_proof?.trusted)
+                attributed.push(id);
+        }
+        catch {
+            // Fail closed: generic history-repair guidance remains authoritative.
+        }
+    }
+    return [...new Set(attributed)].sort((left, right) => left.localeCompare(right));
+}
+function applyMergeReceiptHistoryDriftAttribution(historyDriftCheck, attributedItems) {
+    const attributed = new Set(attributedItems);
+    historyDriftCheck.warnings = [
+        ...historyDriftCheck.warnings.filter((warning) => {
+            if (!warning.startsWith("history_drift_hash_mismatch:"))
+                return true;
+            return !attributed.has(warning.slice(warning.indexOf(":") + 1));
+        }),
+        ...attributedItems.map((id) => `history_drift_merge_receipt:${id}`),
+    ].sort((left, right) => left.localeCompare(right));
+    historyDriftCheck.check.details = {
+        ...historyDriftCheck.check.details,
+        merge_receipt_attributed_items: attributedItems,
+    };
+}
 function projectHealthResult(result, options, summaryMode) {
     const warningCount = result.warning_count ?? result.warnings.length;
     const boundedResult = {
@@ -2030,11 +2106,22 @@ export async function runHealth(global, options = {}) {
     const provenanceWarnings = provenanceResolverHealth.warnings;
     const locksCheck = await buildLocksCheck(pmRoot);
     const integrityCheck = skipPolicy.skipIntegrity
-        ? buildSkippedHealthCheck("integrity")
+        ? {
+            ...buildSkippedHealthCheck("integrity"),
+            gitWorkspaceRoot: null,
+            pendingMergeReceipts: [],
+        }
         : await buildIntegrityCheck(pmRoot, typeRegistry.type_to_folder, settings.schema, options.requireMergeDrivers === true, items);
     const historyDriftCheck = skipPolicy.skipDrift
         ? buildSkippedHealthCheck("history_drift")
         : await buildHistoryDriftCheck(pmRoot, itemsWithBody);
+    const mergeReceiptAttributedHistoryDriftItems = await correlateMergeReceiptHistoryDriftItems({
+        gitWorkspaceRoot: integrityCheck.gitWorkspaceRoot,
+        pendingMergeReceipts: integrityCheck.pendingMergeReceipts,
+        historyDriftCheck,
+        global,
+    });
+    applyMergeReceiptHistoryDriftAttribution(historyDriftCheck, mergeReceiptAttributedHistoryDriftItems);
     const vectorizationCheck = skipPolicy.skipVectors
         ? buildSkippedHealthCheck("vectorization")
         : await buildVectorizationCheck(pmRoot, settings, itemsWithBody, refreshPolicy, options.verboseStaleItems === true);
@@ -2142,4 +2229,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=f7b3ff92-1fc7-55e9-aa76-af956714998f
+//# debugId=5887be76-3d1d-56fb-9cae-cf972f0b73f8

package/dist/sdk/governance/validate.js

@@ -4,7 +4,7 @@
  * Implements the pm validate 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]="aca69fd7-c47a-5424-b58f-f305f690edd9")}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]="3d7d6f15-7587-5c22-8deb-373bfd063d2b")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
@@ -34,7 +34,7 @@ import { buildMissingLinkedPathRows, summarizeMissingLinkedPathRows, } from "../
 import { assertProjectionModeChoice, } from "../output-projection.js";
 import { collectDanglingDependencyReferences } from "../graph/assembly.js";
 import { auditMergeAttributeFence, auditMergeDriverConfiguration, findGitWorkspaceRoot, resolveProjectMergeTypeFolders, } from "../merge/install.js";
-import { listMergeReceipts, partitionMergeReceipts, } from "../merge/receipts.js";
+import { inspectMergeReceiptEvidence, partitionMergeReceipts, } from "../merge/receipts.js";
 import { scanStorageIntegrity } from "./storage-integrity.js";
 import { scanTrackedRuntimeCache } from "./tracked-runtime-cache.js";
 import { scanHistoryAuthorAttribution } from "../author-attribution.js";
@@ -1991,6 +1991,11 @@ export const _testOnlyValidateCommand = {
     summarizeDuplicateIssueCodes,
     toMeaningfulString,
 };
+function appendInvalidMergeReceiptEvidenceWarning(warnings, invalidEvidenceCount) {
+    if (invalidEvidenceCount > 0) {
+        warnings.push(`merge_receipt_evidence_invalid:${invalidEvidenceCount}`);
+    }
+}
 /** Build the post-merge storage-integrity check (GH-603/GH-607/GH-609/GH-611): provably corrupted storage — unreadable item documents, on-disk-vs-parsed census mismatches, history conflict markers, resurrected deletes, and unparseable config/schema files — fails validate as an error instead of hiding behind ok:true. The `history_repair_reconciliations` count is informational: it surfaces post-repair divergence without permanently failing repaired workspaces. */
 async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings) {
     const scan = await scanStorageIntegrity(pmRoot, new Set(items.map((item) => item.id)), typeToFolder, {
@@ -2032,16 +2037,16 @@ async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings)
     if (mergeDriverAudit !== null && mergeDriverAudit.status !== "ok") {
         warnings.push(`validate_merge_driver_configuration:${mergeDriverAudit.missing_keys.length + mergeDriverAudit.drifted_keys.length}`);
     }
-    const pendingMergeReceipts = gitWorkspaceRoot === null
-        ? []
-        : await listMergeReceipts(gitWorkspaceRoot, {
-            includeLossless: true,
-            pmRoot,
-        });
+    const mergeReceiptEvidence = await inspectMergeReceiptEvidence(gitWorkspaceRoot ?? pmRoot, {
+        includeLossless: true,
+        pmRoot,
+    });
+    const pendingMergeReceipts = mergeReceiptEvidence.receipts;
     const { pendingDecisions: pendingMergeDecisions, lossless: losslessMergeReceipts, } = partitionMergeReceipts(pendingMergeReceipts);
     if (pendingMergeDecisions.length > 0) {
         warnings.push(`validate_merge_decisions_unreviewed:${pendingMergeDecisions.length}`);
     }
+    appendInvalidMergeReceiptEvidenceWarning(warnings, mergeReceiptEvidence.invalid_evidence_count);
     const status = errorCount > 0 ? "error" : warnings.length > 0 ? "warn" : "ok";
     return {
         check: {
@@ -2060,6 +2065,7 @@ async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings)
                     ...new Set(pendingMergeDecisions.map((receipt) => receipt.item_id)),
                 ].sort((left, right) => left.localeCompare(right)),
                 lossless_merge_receipt_count: losslessMergeReceipts.length,
+                invalid_merge_receipt_evidence_count: mergeReceiptEvidence.invalid_evidence_count,
                 lossless_merge_receipt_items: [
                     ...new Set(losslessMergeReceipts.map((receipt) => receipt.item_id)),
                 ].sort((left, right) => left.localeCompare(right)),
@@ -2280,4 +2286,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=aca69fd7-c47a-5424-b58f-f305f690edd9
+//# debugId=3d7d6f15-7587-5c22-8deb-373bfd063d2b

package/dist/sdk/guide-topics.d.ts

@@ -1,8 +1,3 @@
-/**
- * @module cli/guide-topics
- *
- * Provides CLI runtime support for Guide Topics.
- */
 /** Describes one documentation file surfaced by a progressive-disclosure guide topic. */
 export interface GuideDocReference {
     /** Filesystem path used for path resolution. */

package/dist/sdk/guide-topics.js

@@ -1,9 +1,35 @@
+/**
+ * @module cli/guide-topics
+ *
+ * Provides CLI runtime support for Guide Topics.
+ */
 
-!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]="7be35c3f-df6f-5ed6-b887-a7d8d53910a7")}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]="3e5f92c9-c299-592d-a7ab-a6f9998159f0")}catch(e){}}();
+import { listPmCommandCapabilityGroups } from "./agent-capability-contracts.js";
 function normalizeTopicToken(value) {
     return value.trim().toLowerCase().replaceAll("_", "-");
 }
 const GUIDE_TOPICS = [
+    {
+        id: "capabilities",
+        aliases: ["capability-map", "families", "routing"],
+        title: "Generated Capability Routing",
+        summary: "Route work through command families generated from the canonical agent capability contract.",
+        intent: "Use this as the drift-free entrypoint when selecting a CLI, MCP, completion, documentation, or extension command surface.",
+        commands: listPmCommandCapabilityGroups().flatMap(({ commands }) => commands.map((command) => `pm ${command}`)),
+        workflows: [],
+        docs: [
+            {
+                path: "docs/generated/AGENT_CAPABILITY_ROUTING.md",
+                purpose: "Generated command-to-family routing table.",
+            },
+            {
+                path: "docs/generated/AGENT_COMMAND_SURFACE.md",
+                purpose: "Generated visibility-tier and family table.",
+            },
+        ],
+        related: ["commands", "workflows", "extensions"],
+    },
     {
         id: "quickstart",
         aliases: ["start", "getting-started", "bootstrap"],
@@ -565,4 +591,4 @@ export function resolveGuideTopic(rawTopic) {
     return TOPIC_BY_TOKEN.get(normalized) ?? null;
 }
 //# sourceMappingURL=guide-topics.js.map
-//# debugId=7be35c3f-df6f-5ed6-b887-a7d8d53910a7
+//# debugId=3e5f92c9-c299-592d-a7ab-a6f9998159f0

package/dist/sdk/history-compact.d.ts

@@ -1,4 +1,5 @@
 import { type HistoryCompactBulkSkipReason, type HistoryCompactScope } from "../core/history/history-compact-bulk.js";
+import { type BulkIdsValue } from "../core/io/bulk-ids-input.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";
 /** Documents the history compact command options payload exchanged by command, SDK, and package integrations. */
 export interface HistoryCompactCommandOptions {
@@ -58,7 +59,7 @@ export declare const HISTORY_COMPACT_BULK_DEFAULT_MIN_ENTRIES = 3;
 /** Documents the bulk history compact command options payload exchanged by command, SDK, and package integrations. */
 export interface HistoryCompactBulkCommandOptions {
     /** Value that configures or reports ids for this contract. */
-    ids?: string[];
+    ids?: BulkIdsValue;
     /** Value that configures or reports scope for this contract. */
     scope?: HistoryCompactScope;
     /** Value that configures or reports all over for this contract. */

package/dist/sdk/history-compact.js

@@ -4,7 +4,7 @@
  * Implements the pm history compact 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]="adcf4d1b-689d-52cb-903b-5fba857707f3")}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]="31152621-df59-54a5-a28d-63119e734e6e")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -19,6 +19,7 @@ import { lifecycleClassifierFromStatusRegistry } from "../core/governance/metada
 import { resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
 import { listAllItemMetadataLight } from "../core/store/item-store.js";
 import { pathExists, readFileIfExists } from "../core/fs/fs-utils.js";
+import { normalizeBulkIdsValue, parseBulkIdsText, } from "../core/io/bulk-ids-input.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { nowIso } from "../core/shared/time.js";
@@ -301,6 +302,21 @@ export async function runHistoryCompact(id, options, global) {
 }
 /** Default entry floor below which a stream is treated as already compact. */
 export const HISTORY_COMPACT_BULK_DEFAULT_MIN_ENTRIES = 3;
+function normalizeHistoryCompactBulkOptions(options) {
+    const normalizedIdsText = normalizeBulkIdsValue(options.ids);
+    if (options.ids !== undefined && normalizedIdsText === "") {
+        throw new PmCliError("history-compact ids requires at least one valid item ID.", EXIT_CODE.USAGE, {
+            code: "bulk_ids_input_empty",
+            required: "Provide one or more string or finite numeric IDs; non-finite and unsupported selector values are rejected.",
+        });
+    }
+    return {
+        ...options,
+        ids: normalizedIdsText === undefined
+            ? undefined
+            : parseBulkIdsText(normalizedIdsText),
+    };
+}
 /** Enforce the `pm history-compact` target contract shared by the CLI and MCP surfaces: exactly one selection mode — a single item `<id>`, an explicit `--ids` list, or a scan selector (`--all-over` / `--closed` / `--all-streams`). */
 export function assertHistoryCompactTarget(id, bulk) {
     const hasIds = bulk.ids !== undefined && bulk.ids.length > 0;
@@ -436,6 +452,7 @@ async function runHistoryCompactBulkRow(params) {
  * configured policy drives the sweep.
  */
 export async function runHistoryCompactBulk(options, global) {
+    const normalizedOptions = normalizeHistoryCompactBulkOptions(options);
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
     await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
@@ -445,14 +462,16 @@ export async function runHistoryCompactBulk(options, global) {
         settings,
         typeToFolder: typeRegistry.type_to_folder,
     });
-    const mode = options.ids !== undefined && options.ids.length > 0 ? "ids" : "scan";
+    const mode = normalizedOptions.ids !== undefined && normalizedOptions.ids.length > 0
+        ? "ids"
+        : "scan";
     const minEntries = options.minEntries ?? HISTORY_COMPACT_BULK_DEFAULT_MIN_ENTRIES;
     const policy = settings.history.compact_policy;
     const policyThresholdApplied = mode === "scan" && options.allOver === undefined && policy.enabled;
     const allOver = options.allOver ??
         (policyThresholdApplied ? policy.max_entries : undefined);
     const selection = selectHistoryCompactBulkTargets(candidates, {
-        ids: options.ids,
+        ids: normalizedOptions.ids,
         scope: options.scope,
         minEntries,
         allOver,
@@ -469,7 +488,7 @@ export async function runHistoryCompactBulk(options, global) {
     for (const row of selection) {
         const outcome = await runHistoryCompactBulkRow({
             row,
-            options,
+            options: normalizedOptions,
             dryRun,
             global,
         });
@@ -502,4 +521,4 @@ export async function runHistoryCompactBulk(options, global) {
     };
 }
 //# sourceMappingURL=history-compact.js.map
-//# debugId=adcf4d1b-689d-52cb-903b-5fba857707f3
+//# debugId=31152621-df59-54a5-a28d-63119e734e6e

package/dist/sdk/history-mcp.js

@@ -1,5 +1,6 @@
 
-!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]="f762b5e6-8224-531f-9dd1-f71dc18c3ddf")}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]="4888a558-7f50-5c28-8e29-fcd19180cbd4")}catch(e){}}();
+import { normalizeBulkIdsValue, parseBulkIdsText, } from "../core/io/bulk-ids-input.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { assertHistoryCompactTarget, runHistoryCompact, runHistoryCompactBulk, } from "./history-compact.js";
@@ -17,14 +18,14 @@ export function runMcpHistoryRepairAction(context) {
 /** Dispatch single or bounded bulk history compaction from an MCP payload. */
 export function runMcpHistoryCompactAction(context) {
     const idsSource = context.options.ids;
-    const ids = Array.isArray(idsSource)
-        ? idsSource.map(String).filter((value) => value.trim().length > 0)
-        : typeof idsSource === "string"
-            ? idsSource
-                .split(",")
-                .map((value) => value.trim())
-                .filter(Boolean)
-            : undefined;
+    const normalizedIds = normalizeBulkIdsValue(idsSource);
+    if (idsSource !== undefined && normalizedIds === "") {
+        throw new PmCliError("history-compact ids requires at least one valid item ID.", EXIT_CODE.USAGE, {
+            code: "bulk_ids_input_empty",
+            required: "Provide one or more string or finite numeric IDs; non-finite and unsupported selector values are rejected.",
+        });
+    }
+    const ids = normalizedIds === undefined ? undefined : parseBulkIdsText(normalizedIds);
     const allOver = parseRuntimeInteger(context.options.allOver ?? context.options.all_over, "history-compact allOver");
     const minEntries = parseRuntimeInteger(context.options.minEntries ?? context.options.min_entries, "history-compact minEntries");
     const explicitScope = readRuntimeString(context.options, "scope");
@@ -65,4 +66,4 @@ export function runMcpHistoryCompactAction(context) {
     }, context.global);
 }
 //# sourceMappingURL=history-mcp.js.map
-//# debugId=f762b5e6-8224-531f-9dd1-f71dc18c3ddf
+//# debugId=4888a558-7f50-5c28-8e29-fcd19180cbd4

package/dist/sdk/history-repair.d.ts

@@ -1,6 +1,7 @@
 import { type ReplayDocument } from "../core/history/replay.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { HistoryEntry } from "../types/index.js";
+import { type MergeDecisionReceipt } from "./merge/receipts.js";
 import { type ProvenanceNormalizationReceipt } from "./governance/provenance-health.js";
 /** Documents the history repair command options payload exchanged by command, SDK, and package integrations. */
 export interface HistoryRepairCommandOptions {
@@ -22,6 +23,16 @@ export interface HistoryRepairCommandOptions {
     forceAuditEntry?: boolean;
     /** Remove bounded-domain-invalid provenance observations and record an aggregate privacy-safe audit receipt. */
     normalizeProvenance?: boolean;
+    /** Internal receipt evidence revalidated against the exact item snapshot used by this repair. */
+    mergeReceiptProof?: {
+        gitWorkspaceRoot: string | null;
+        receipts: MergeDecisionReceipt[];
+    };
+    /** Internal per-item receipt proof index used by bounded bulk reconciliation. */
+    mergeReceiptProofById?: Record<string, {
+        gitWorkspaceRoot: string | null;
+        receipts: MergeDecisionReceipt[];
+    }>;
 }
 /** Documents the history repair result payload exchanged by command, SDK, and package integrations. */
 export interface HistoryRepairResult {
@@ -60,11 +71,22 @@ export interface HistoryRepairResult {
     };
     /** Present when reconciling the chain with the on-disk item discards the replayed effect of earlier history events (GH-603): names the reverted fields and the authors whose mutations the reconciliation overwrites, so cross-author data loss after a lossy merge is loud instead of silent. */
     reconciliation?: HistoryRepairReconciliationReport;
+    /** Present when merge reconciliation supplied receipt evidence for this item. */
+    merge_receipt_proof?: MergeReceiptProofResult;
     /** Value that configures or reports warnings for this contract. */
     warnings: string[];
     /** ISO 8601 timestamp recording when generated occurred. */
     generated_at: string;
 }
+/** Fail-closed proof that clone-local driver receipts exactly cover the current reconciliation fields and values. */
+export interface MergeReceiptProofResult {
+    /** Whether exact receipt identity, path, field, and value-hash evidence proves the snapshot. */
+    trusted: boolean;
+    /** Stable explanation for the trust decision. */
+    reason: "trusted_clone_local_driver_evidence" | "git_workspace_unavailable" | "item_path_unavailable" | "no_item_receipts" | "no_receipt_set_proves_snapshot";
+    /** Exact receipt identities accepted as proof; empty when proof is refused. */
+    receipt_ids: string[];
+}
 /** Documents one history event attributed to fields changed by reconciliation. */
 export interface HistoryRepairDiscardedEvent {
     /** 1-based index of the event in the (re-anchored) history stream. */
@@ -121,6 +143,8 @@ export interface HistoryRepairAllStreamResult {
     reconciled_with_item?: boolean;
     /** Cross-author data-loss detail when reconciliation overwrites replayed mutations. */
     reconciliation?: HistoryRepairReconciliationReport;
+    /** Exact receipt proof used to authorize this stream, when supplied. */
+    merge_receipt_proof?: MergeReceiptProofResult;
     /** Stream-specific repair warnings retained by the bulk workflow. */
     warnings?: string[];
     /** Value that configures or reports error for this contract. */