@unbrained/pm-cli 2026.9.1 → 2026.9.3

package/dist/sdk/context-usage.js

@@ -6,7 +6,7 @@
  * intents; it never enters item history and is safe to delete or rebuild.
  */
 
-!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]="5f4ccd28-a001-54aa-8378-893025c69b96")}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]="997a09a2-cf0c-5384-b457-d9627d465b71")}catch(e){}}();
 import { randomUUID } from "node:crypto";
 import { appendFile, mkdir, readFile, rename, stat, writeFile, } from "node:fs/promises";
 import path from "node:path";
@@ -16,6 +16,154 @@ const DEFAULT_RETENTION_DAYS = 30;
 const DAY_MS = 86_400_000;
 const DEFAULT_COMPACTION_BYTES = 262_144;
 const CONTEXT_USAGE_LOCK_ID = "context-usage-ledger";
+const CONTEXT_USAGE_SERVING_RECEIPT = Symbol.for("@unbrained/pm-cli/context-usage-serving-receipt");
+function asObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Attach a JSON-invisible serving receipt to a result for later egress. */
+export function attachContextUsageServingReceipt(result, receipt) {
+    const record = asObjectRecord(result);
+    if (record !== null && receipt !== null) {
+        record[CONTEXT_USAGE_SERVING_RECEIPT] = receipt;
+    }
+}
+/** Copy an attached serving receipt across a result projection boundary. */
+export function propagateContextUsageServingReceipt(source, target) {
+    const sourceRecord = asObjectRecord(source);
+    const targetRecord = asObjectRecord(target);
+    const receipt = sourceRecord?.[CONTEXT_USAGE_SERVING_RECEIPT];
+    if (targetRecord !== null && receipt !== undefined) {
+        targetRecord[CONTEXT_USAGE_SERVING_RECEIPT] = receipt;
+    }
+}
+function receiptFromResult(result) {
+    return (asObjectRecord(result)?.[CONTEXT_USAGE_SERVING_RECEIPT] ?? null);
+}
+function resultReceiptSaysOmitted(result) {
+    const record = asObjectRecord(result);
+    for (const key of ["read_output", "context_intent"]) {
+        const receipt = asObjectRecord(record?.[key]);
+        if (receipt?.result_omitted === true)
+            return true;
+    }
+    return false;
+}
+function addContextUsageId(ids, value) {
+    if (typeof value === "string" && value.trim().length > 0) {
+        ids.add(value.trim());
+    }
+}
+function addContextUsageDirectRows(ids, value) {
+    if (!Array.isArray(value))
+        return;
+    for (const row of value) {
+        addContextUsageId(ids, asObjectRecord(row)?.id);
+    }
+}
+function addContextUsageIdList(ids, value) {
+    if (!Array.isArray(value))
+        return;
+    for (const itemId of value)
+        addContextUsageId(ids, itemId);
+}
+function collectNextResultItemIds(record, ids) {
+    const rows = [
+        ...(asObjectRecord(record.recommended) === null
+            ? []
+            : [record.recommended]),
+        ...(Array.isArray(record.ready) ? record.ready : []),
+        ...(Array.isArray(record.decision_needed) ? record.decision_needed : []),
+        ...(Array.isArray(record.blocked) ? record.blocked : []),
+        ...(Array.isArray(record.held_by_others) ? record.held_by_others : []),
+    ];
+    for (const value of rows) {
+        const row = asObjectRecord(value);
+        addContextUsageId(ids, row?.id);
+        for (const blocker of Array.isArray(row?.blockers) ? row.blockers : []) {
+            addContextUsageId(ids, asObjectRecord(blocker)?.id);
+        }
+        for (const unblockedId of Array.isArray(row?.unblocks)
+            ? row.unblocks
+            : []) {
+            addContextUsageId(ids, unblockedId);
+        }
+    }
+}
+function collectContextResultItemIds(record, ids) {
+    for (const key of [
+        "high_level",
+        "low_level",
+        "blocked_fallback",
+        "recently_created",
+        "unparented",
+        "activity",
+        "progress",
+        "blockers",
+        "staleness",
+    ]) {
+        addContextUsageDirectRows(ids, record[key]);
+    }
+    for (const value of Array.isArray(record.blockers)
+        ? record.blockers
+        : []) {
+        addContextUsageId(ids, asObjectRecord(value)?.blocked_by);
+    }
+    collectContextNestedItemIds(record, ids);
+}
+function collectContextNestedItemIds(record, ids) {
+    for (const value of Array.isArray(record.hierarchy)
+        ? record.hierarchy
+        : []) {
+        const node = asObjectRecord(value);
+        addContextUsageId(ids, node?.id);
+        addContextUsageDirectRows(ids, node?.children);
+    }
+    for (const key of ["files", "workload"]) {
+        for (const value of Array.isArray(record[key]) ? record[key] : []) {
+            addContextUsageIdList(ids, asObjectRecord(value)?.items);
+        }
+    }
+    const agenda = asObjectRecord(record.agenda);
+    for (const value of Array.isArray(agenda?.events) ? agenda.events : []) {
+        addContextUsageId(ids, asObjectRecord(value)?.item_id);
+    }
+    const tests = asObjectRecord(record.tests);
+    addContextUsageIdList(ids, tests?.items_failing);
+}
+/**
+ * Collect every item identifier visible in a final context or next result.
+ * The traversal is shape-aware so summary counters and unrelated identifier
+ * fields cannot enter the privacy-minimal usage ledger.
+ */
+export function collectContextUsageDeliveredItemIds(result, surface) {
+    const record = asObjectRecord(result);
+    if (record === null || resultReceiptSaysOmitted(result))
+        return [];
+    const ids = new Set();
+    if (surface === "next") {
+        collectNextResultItemIds(record, ids);
+    }
+    else {
+        collectContextResultItemIds(record, ids);
+    }
+    return [...ids];
+}
+/** Resolve and append one post-egress decision carried by a context result. */
+export async function finalizeContextUsageDelivery(options) {
+    const receipt = receiptFromResult(options.result);
+    if (receipt === null)
+        return false;
+    const resultOmitted = resultReceiptSaysOmitted(options.result);
+    await recordContextUsageDelivery({
+        pmRoot: options.pmRoot,
+        receipt,
+        deliveredItemIds: collectContextUsageDeliveredItemIds(options.result, receipt.surface),
+        resultOmitted,
+    });
+    return true;
+}
 /** Named validation failure emitted by context-usage SDK inputs. */
 export class ContextUsageValidationError extends TypeError {
     /** Stable machine-readable error code for package and CLI hosts. */
@@ -61,7 +209,7 @@ async function readEvents(options) {
         return [];
     }
 }
-async function appendEvents(options, events) {
+async function appendEvents(options, events, deliveryServeId) {
     const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;
     const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
     if (!Number.isInteger(maxEvents) ||
@@ -75,6 +223,10 @@ async function appendEvents(options, events) {
     const releaseLock = await acquireLock(options.pmRoot, CONTEXT_USAGE_LOCK_ID, 30, `context-usage:${process.pid}`, false, false, 3_000);
     try {
         await mkdir(runtimeDirectory, { recursive: true });
+        if (deliveryServeId !== undefined &&
+            (await readEvents(options)).some((event) => event.kind === "delivery" && event.serve_id === deliveryServeId)) {
+            return;
+        }
         await appendFile(target, events.map((event) => `${JSON.stringify(event)}\n`).join(""), "utf8");
         const customBounds = options.maxEvents !== undefined || options.retentionDays !== undefined;
         if (!customBounds && (await stat(target)).size <= DEFAULT_COMPACTION_BYTES)
@@ -93,21 +245,70 @@ async function appendEvent(options, event) {
 }
 /** Records a propensity-complete context/next serving event. */
 export async function recordContextUsageServing(options) {
-    if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" ||
-        options.enabled === false)
-        return;
+    if ([
+        process.env.PM_CONTEXT_USAGE_DISABLED === "1",
+        options.enabled === false,
+    ].includes(true))
+        return null;
     if (!options.author.trim() ||
         options.rows.some((row) => !row.id.trim() || !Number.isInteger(row.rank) || row.rank < 1)) {
         throw new ContextUsageValidationError("Context usage serving requires an author and valid ranked rows");
     }
+    const normalizedRows = options.rows.map((row) => ({
+        ...row,
+        id: row.id.trim(),
+    }));
+    if (new Set(normalizedRows.map((row) => row.id)).size !== normalizedRows.length) {
+        throw new ContextUsageValidationError("Context usage serving requires unique normalized row ids");
+    }
+    const receipt = {
+        serve_id: randomUUID(),
+        author: options.author.trim(),
+        surface: options.surface,
+        rows: normalizedRows,
+    };
     await appendEvent(options, {
         kind: "serve",
+        schema_version: 2,
+        serve_id: receipt.serve_id,
         at: resolveNow(options).iso,
         author: options.author.trim(),
         surface: options.surface,
         profile: options.profile.trim() || "balanced",
-        rows: options.rows,
+        rows: receipt.rows.map((row) => ({ ...row })),
+        result_omitted: false,
+        packed_item_ids: receipt.rows
+            .filter((row) => row.included)
+            .map((row) => row.id),
     });
+    return receipt;
+}
+/** Append the exact post-egress delivery decision for one serving receipt. */
+export async function recordContextUsageDelivery(options) {
+    if (options.receipt === null ||
+        process.env.PM_CONTEXT_USAGE_DISABLED === "1" ||
+        options.enabled === false) {
+        return;
+    }
+    const rankedIds = new Set(options.receipt.rows.map((row) => row.id));
+    const deliveredItemIds = [
+        ...new Set(options.deliveredItemIds.map((id) => id.trim())),
+    ];
+    if (deliveredItemIds.some((id) => id.length === 0 || !rankedIds.has(id)) ||
+        (options.resultOmitted && deliveredItemIds.length > 0)) {
+        throw new ContextUsageValidationError("Context usage delivery requires emitted ranked ids and zero ids for an omitted result");
+    }
+    const delivery = {
+        kind: "delivery",
+        schema_version: 2,
+        serve_id: options.receipt.serve_id,
+        at: resolveNow(options).iso,
+        author: options.receipt.author,
+        surface: options.receipt.surface,
+        result_omitted: options.resultOmitted,
+        delivered_item_ids: deliveredItemIds,
+    };
+    await appendEvents(options, [delivery], delivery.serve_id);
 }
 /** Records one subsequent item read or mutation outcome. */
 export async function recordContextUsageTouch(options) {
@@ -165,6 +366,18 @@ function findTouchTimeInHorizon(touches, itemId, servedAt, horizonMs) {
         time >= servedAt &&
         time - servedAt <= horizonMs)?.time;
 }
+function firstDeliveriesByServeId(events, author) {
+    const deliveries = new Map();
+    for (const event of events) {
+        if (event.kind === "delivery" &&
+            event.schema_version === 2 &&
+            event.author === author &&
+            !deliveries.has(event.serve_id)) {
+            deliveries.set(event.serve_id, event);
+        }
+    }
+    return deliveries;
+}
 /**
  * Derives decayed served-then-touched affinity. A small exploration floor keeps
  * ignored and unseen items eligible, preventing a popularity feedback lock-in.
@@ -172,26 +385,41 @@ function findTouchTimeInHorizon(touches, itemId, servedAt, horizonMs) {
 export async function readContextUsageAffinity(options) {
     if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" ||
         options.enabled === false)
-        return { affinity: {}, positive_judgments: 0, serving_events: 0 };
+        return {
+            affinity: {},
+            positive_judgments: 0,
+            serving_events: 0,
+            untrusted_serving_events: 0,
+        };
     const events = await readEvents(options);
     const now = resolveNow(options).ms;
     const horizonMs = (options.horizonHours ?? 24) * 3_600_000;
-    if (!Number.isFinite(horizonMs) || horizonMs <= 0)
+    if (![Number.isFinite(horizonMs), horizonMs > 0].every(Boolean))
         throw new ContextUsageValidationError("Context usage horizonHours must be positive");
     const author = options.author.trim();
     const touches = events
-        .filter((event) => event.kind === "touch" && event.author === author)
+        .filter((event) => event.kind === "touch")
+        .filter((event) => event.author === author)
         .map((entry) => ({ entry, time: Date.parse(entry.at) }));
     const scores = new Map();
     let servingEvents = 0;
+    let untrustedServingEvents = 0;
     let positiveJudgments = 0;
-    for (const event of events) {
-        if (event.kind !== "serve" || event.author !== author)
-            continue;
+    const deliveries = firstDeliveriesByServeId(events, author);
+    events
+        .filter((event) => event.kind === "serve")
+        .filter((event) => event.author === author)
+        .forEach((event) => {
+        if (![event.schema_version === 2, Boolean(event.serve_id)].every(Boolean)) {
+            untrustedServingEvents += 1;
+            return;
+        }
         servingEvents += 1;
         const servedAt = Date.parse(event.at);
+        const delivery = deliveries.get(event.serve_id);
+        const deliveredIds = new Set(delivery?.delivered_item_ids ?? []);
         for (const row of event.rows) {
-            if (!row.included)
+            if (!deliveredIds.has(row.id))
                 continue;
             const touchTime = findTouchTimeInHorizon(touches, row.id, servedAt, horizonMs);
             if (touchTime === undefined)
@@ -200,17 +428,18 @@ export async function readContextUsageAffinity(options) {
             const ageDays = Math.max(0, (now - touchTime) / DAY_MS);
             scores.set(row.id, (scores.get(row.id) ?? 0) + Math.exp(-ageDays / 14));
         }
-    }
+    });
     const maximum = Math.max(0, ...scores.values());
     const affinity = Object.fromEntries([...scores.entries()].map(([id, score]) => [
         id,
-        0.05 + 0.95 * (maximum > 0 ? score / maximum : 0),
+        maximum === 0 ? 0.05 : 0.05 + (0.95 * score) / maximum,
     ]));
     return {
         affinity,
         positive_judgments: positiveJudgments,
         serving_events: servingEvents,
+        untrusted_serving_events: untrustedServingEvents,
     };
 }
 //# sourceMappingURL=context-usage.js.map
-//# debugId=5f4ccd28-a001-54aa-8378-893025c69b96
+//# debugId=997a09a2-cf0c-5384-b457-d9627d465b71

package/dist/sdk/generated/generated-error-code-catalog-part-1.js

@@ -1,6 +1,6 @@
 /** Generated partition 1 of the exhaustive error-code catalog. */
 
-!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]="0823f083-1719-5ec2-9f7e-43bd86a2a3a2")}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]="0a4690e9-4cde-5218-81fb-5d59807fa344")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_1 = [
     {
         code: "acceptance_criteria_mutation_conflict",
@@ -1271,6 +1271,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "history_target_out_of_range",
         aliases: [],
     },
+    {
+        code: "history_timestamp_invalid",
+        meaning: "History timestamp invalid condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/history/event-index.ts", "core/history/history.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "history_timestamp_invalid",
+        aliases: [],
+    },
     {
         code: "history_unknown_author_events",
         meaning: "History unknown author events condition.",
@@ -2076,6 +2088,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "merge_receipt_evidence_invalid",
         aliases: [],
     },
+    {
+        code: "merge_receipt_history_reference_missing",
+        meaning: "Merge receipt history reference missing condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/diagnostics/remediation.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "merge_receipt_history_reference_missing",
+        aliases: [],
+    },
     {
         code: "merge_receipts_pending",
         meaning: "Merge receipts pending condition.",
@@ -2136,18 +2160,6 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "missing_budget",
         aliases: [],
     },
-    {
-        code: "missing_cli_flag",
-        meaning: "Missing cli flag condition.",
-        stability: "provisional",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/cli-contracts/tool-option-contracts.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "missing_cli_flag",
-        aliases: [],
-    },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-1.js.map
-//# debugId=0823f083-1719-5ec2-9f7e-43bd86a2a3a2
+//# debugId=0a4690e9-4cde-5218-81fb-5d59807fa344

package/dist/sdk/generated/generated-error-code-catalog-part-2.js

@@ -1,7 +1,19 @@
 /** Generated partition 2 of the exhaustive error-code catalog. */
 
-!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]="41e6f81d-ccb5-546c-9b26-3b78027528b5")}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]="5d5a1c08-21ed-5823-8c1b-15f7907ab3b5")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_2 = [
+    {
+        code: "missing_cli_flag",
+        meaning: "Missing cli flag condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/tool-option-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_cli_flag",
+        aliases: [],
+    },
     {
         code: "missing_destination",
         meaning: "Missing destination condition.",
@@ -2174,4 +2186,4 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
     },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-2.js.map
-//# debugId=41e6f81d-ccb5-546c-9b26-3b78027528b5
+//# debugId=5d5a1c08-21ed-5823-8c1b-15f7907ab3b5

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]="76693c03-9395-5bbf-bcc8-fa15e408f30f")}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]="f27cb24d-f2c8-5034-b655-84c577de7a16")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
@@ -28,6 +28,7 @@ import { EXIT_CODE, PM_CORE_REQUIRED_SUBDIRS, TYPE_TO_FOLDER, } from "../../core
 import { findFirstMergeConflictMarker } from "../../core/shared/conflict-markers.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
+import { sha256Hex } from "../../core/shared/serialization.js";
 import { nowIso } from "../../core/shared/time.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
 import { effectiveItemFormatVersion, scanItemFormatVersions, } from "../../core/item/item-format-version.js";
@@ -46,7 +47,7 @@ import { buildCapabilityContractMetadata, buildRegistrationCollisionRemediation,
 import { scanStaleInProgressItems, } from "./stale-work.js";
 import { scanTrackedRuntimeCache } from "./tracked-runtime-cache.js";
 import { auditMergeDriverConfiguration, findGitWorkspaceRoot, } from "../merge/install.js";
-import { inspectMergeReceiptEvidence, partitionMergeReceipts, } from "../merge/receipts.js";
+import { inspectMergeReceiptEvidence, isSafeReceiptId, partitionMergeReceipts, } from "../merge/receipts.js";
 import { runHistoryRepair } from "../history-repair.js";
 import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
 import { analyzeHierarchyIntegrity, } from "../graph/hierarchy-integrity.js";
@@ -278,11 +279,41 @@ async function scanItemIntegrity(pmRoot, typeToFolder, schema) {
     }
     return { paths, unreadable, conflictMarkers, parseFailures, formatVersions };
 }
+function mergeReceiptIdsFromHistoryEntry(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return [];
+    }
+    const context = value.context;
+    if (typeof context !== "object" ||
+        context === null ||
+        Array.isArray(context)) {
+        return [];
+    }
+    const merge = context.merge;
+    if (typeof merge !== "object" || merge === null || Array.isArray(merge)) {
+        return [];
+    }
+    const receipts = merge.receipts;
+    if (!Array.isArray(receipts))
+        return [];
+    return receipts.flatMap((receipt) => {
+        if (typeof receipt !== "object" ||
+            receipt === null ||
+            Array.isArray(receipt)) {
+            return [];
+        }
+        const receiptId = receipt.receipt_id;
+        return typeof receiptId === "string" && receiptId.length > 0
+            ? [receiptId]
+            : [];
+    });
+}
 async function scanHistoryIntegrity(pmRoot) {
     const historyDir = path.join(pmRoot, "history");
     const unreadable = [];
     const conflictMarkers = [];
     const invalidJson = [];
+    const mergeReceiptReferences = [];
     let files = [];
     try {
         files = (await fs.readdir(historyDir))
@@ -314,14 +345,25 @@ async function scanHistoryIntegrity(pmRoot) {
             if (!line.trim())
                 return;
             try {
-                JSON.parse(line);
+                const parsed = JSON.parse(line);
+                mergeReceiptReferences.push(...mergeReceiptIdsFromHistoryEntry(parsed).map((receiptId) => ({
+                    itemId,
+                    line: index + 1,
+                    receiptId,
+                })));
             }
             catch {
                 invalidJson.push({ id: itemId, line: index + 1 });
             }
         });
     }
-    return { files, unreadable, conflictMarkers, invalidJson };
+    return {
+        files,
+        unreadable,
+        conflictMarkers,
+        invalidJson,
+        mergeReceiptReferences,
+    };
 }
 function buildHierarchyIntegrityWarnings(analysis) {
     return [
@@ -336,10 +378,15 @@ function buildHierarchyIntegrityWarnings(analysis) {
             : `integrity_hierarchy_divergence:${finding.child_id}`),
     ];
 }
-function buildMergeReceiptEvidenceWarnings(invalidEvidenceCount) {
-    return invalidEvidenceCount === 0
-        ? []
-        : [`merge_receipt_evidence_invalid:${invalidEvidenceCount}`];
+function buildMergeReceiptEvidenceWarnings(params) {
+    const warnings = [];
+    if (params.invalidEvidenceCount > 0) {
+        warnings.push(`merge_receipt_evidence_invalid:${params.invalidEvidenceCount}`);
+    }
+    if (params.missingHistoryReferenceCount > 0) {
+        warnings.push(`merge_receipt_history_reference_missing:${params.missingHistoryReferenceCount}`);
+    }
+    return warnings;
 }
 async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDrivers, items) {
     const itemScan = await scanItemIntegrity(pmRoot, typeToFolder, schema);
@@ -353,10 +400,21 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
         ? null
         : await auditMergeDriverConfiguration(gitWorkspaceRoot);
     const mergeReceiptEvidence = await inspectMergeReceiptEvidence(gitWorkspaceRoot ?? pmRoot, {
+        includeReconciled: true,
         includeLossless: true,
         pmRoot,
     });
-    const pendingMergeReceipts = mergeReceiptEvidence.receipts;
+    const availableMergeReceiptIds = new Set(mergeReceiptEvidence.receipts.map((receipt) => receipt.id));
+    const missingMergeReceiptReferences = historyScan.mergeReceiptReferences
+        .filter((reference) => !availableMergeReceiptIds.has(reference.receiptId))
+        .map((reference) => ({
+        item_id: reference.itemId,
+        history_line: reference.line,
+        ...(isSafeReceiptId(reference.receiptId)
+            ? { receipt_id: reference.receiptId }
+            : { receipt_reference_hash: sha256Hex(reference.receiptId) }),
+    }));
+    const pendingMergeReceipts = mergeReceiptEvidence.receipts.filter((receipt) => receipt.state === "pending");
     const { pendingDecisions: pendingMergeDecisions, lossless: losslessMergeReceipts, } = partitionMergeReceipts(pendingMergeReceipts);
     const mergeDriverInstallationMissing = mergeDriverAudit?.status === "missing" &&
         mergeDriverAudit.missing_keys.length === 5 &&
@@ -389,7 +447,10 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
         ...(losslessMergeReceipts.length > 0
             ? [`merge_receipts_pending:${losslessMergeReceipts.length}`]
             : []),
-        ...buildMergeReceiptEvidenceWarnings(mergeReceiptEvidence.invalid_evidence_count),
+        ...buildMergeReceiptEvidenceWarnings({
+            invalidEvidenceCount: mergeReceiptEvidence.invalid_evidence_count,
+            missingHistoryReferenceCount: missingMergeReceiptReferences.length,
+        }),
     ];
     const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
     const actionableWarnings = normalizedWarnings.filter((warning) => !warning.startsWith("integrity_legacy_hierarchy_"));
@@ -421,6 +482,7 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                     pending_merge_decisions: pendingMergeDecisions.length,
                     lossless_merge_receipts: losslessMergeReceipts.length,
                     invalid_merge_receipt_evidence: mergeReceiptEvidence.invalid_evidence_count,
+                    missing_merge_receipt_history_references: missingMergeReceiptReferences.length,
                 },
                 item_unreadable: itemScan.unreadable,
                 item_conflict_markers: itemScan.conflictMarkers,
@@ -452,6 +514,10 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                 lossless_merge_receipt_items: [
                     ...new Set(losslessMergeReceipts.map((receipt) => receipt.item_id)),
                 ].sort((left, right) => left.localeCompare(right)),
+                invalid_merge_receipt_evidence_details: mergeReceiptEvidence.invalid_evidence,
+                invalid_merge_receipt_evidence_details_truncated: mergeReceiptEvidence.invalid_evidence_truncated,
+                missing_merge_receipt_history_reference_details: missingMergeReceiptReferences.slice(0, HEALTH_WARNING_LIMIT),
+                missing_merge_receipt_history_reference_details_truncated: missingMergeReceiptReferences.length > HEALTH_WARNING_LIMIT,
             },
         },
         warnings: normalizedWarnings,
@@ -2309,4 +2375,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=76693c03-9395-5bbf-bcc8-fa15e408f30f
+//# debugId=f27cb24d-f2c8-5034-b655-84c577de7a16

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]="cde10e58-cfeb-5718-a471-3e4acf46cfe7")}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]="0d466293-869d-54bb-b07d-facb3be51e8c")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
@@ -2053,6 +2053,8 @@ async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings)
                 ].sort((left, right) => left.localeCompare(right)),
                 lossless_merge_receipt_count: losslessMergeReceipts.length,
                 invalid_merge_receipt_evidence_count: mergeReceiptEvidence.invalid_evidence_count,
+                invalid_merge_receipt_evidence_details: mergeReceiptEvidence.invalid_evidence,
+                invalid_merge_receipt_evidence_details_truncated: mergeReceiptEvidence.invalid_evidence_truncated,
                 lossless_merge_receipt_items: [
                     ...new Set(losslessMergeReceipts.map((receipt) => receipt.item_id)),
                 ].sort((left, right) => left.localeCompare(right)),
@@ -2273,4 +2275,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=cde10e58-cfeb-5718-a471-3e4acf46cfe7
+//# debugId=0d466293-869d-54bb-b07d-facb3be51e8c

package/dist/sdk/index.d.ts

@@ -81,6 +81,7 @@ export * from "./environment/source-context.js";
 export * from "./environment/host-environment-errors.js";
 export * from "./cli-contracts/command-exit-contracts.js";
 export * from "./context-relevance.js";
+export * from "./context/recency.js";
 export * from "./context-intent-contracts.js";
 export * from "./context-intent-runtime.js";
 export * from "./context-signal-store.js";
@@ -94,6 +95,7 @@ export * from "./read-output-session.js";
 export * from "./output-token-accounting.js";
 export * from "./context-packing.js";
 export * from "./context-usage.js";
+export { classifyHistoryEvent, HISTORY_EVENT_CLASSIFICATION_VERSION, MAINTENANCE_HISTORY_OPERATIONS, SUBSTANTIVE_HISTORY_OPERATIONS, type HistoryEventClass, } from "../core/history/event-classification.js";
 export * from "./dependency-provenance.js";
 export * from "./duplicates.js";
 export * from "./lifecycle/reopen.js";