@unbrained/pm-cli 2026.9.1 → 2026.9.3

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="8a1a02de-32cb-5714-b950-6041ae8ce229")}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]="62e450f7-9ed9-5855-923a-7b2ffb8b49f4")}catch(e){}}();
 export { PM_COMMAND_CAPABILITY_CONTRACTS, PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForFamily, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./mcp/protocol.js";
 export * from "./mcp/interactions.js";
@@ -78,6 +78,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";
@@ -91,6 +92,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, } from "../core/history/event-classification.js";
 export * from "./dependency-provenance.js";
 export * from "./duplicates.js";
 export * from "./lifecycle/reopen.js";
@@ -177,4 +179,4 @@ export * from "./mcp/discovery.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=8a1a02de-32cb-5714-b950-6041ae8ce229
+//# debugId=62e450f7-9ed9-5855-923a-7b2ffb8b49f4

package/dist/sdk/init.d.ts

@@ -5,6 +5,8 @@ import type { GovernancePreset, PmSettings } from "../types/index.js";
 import { type ExtensionCommandResult } from "./extension.js";
 import { type InitAgentGuidanceMode, type InitAgentGuidanceSummary } from "./init-agent-guidance.js";
 import { installMergeFence } from "./merge/install.js";
+/** Symbol key for the captured working directory of an in-process init call. */
+export declare const INIT_INVOCATION_CWD: unique symbol;
 /** Documents the init installed packages summary payload exchanged by command, SDK, and package integrations. */
 export interface InitInstalledPackagesSummary {
     /** Value that configures or reports installed all for this contract. */

package/dist/sdk/init.js

@@ -4,7 +4,7 @@
  * Implements the pm init 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]="75c0d2d2-6a89-508f-b7dd-b43d55978b44")}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]="d06d4db7-8ab7-5a9f-84df-508bd305ea23")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import readline from "node:readline/promises";
@@ -27,6 +27,8 @@ import { renderPmCommand } from "./command-line.js";
 import { runExtension } from "./extension.js";
 import { INIT_AGENT_GUIDANCE_MODE_VALUES, runInitAgentGuidance, } from "./init-agent-guidance.js";
 import { findGitWorkspaceRoot, installMergeFence } from "./merge/install.js";
+/** Symbol key for the captured working directory of an in-process init call. */
+export const INIT_INVOCATION_CWD = Symbol.for("pm.sdk.init-invocation-cwd");
 /** Implements summarize init result for the public runtime surface of this module. */
 export function summarizeInitResult(result) {
     return {
@@ -709,9 +711,21 @@ async function installInitMergeFence(pmRoot, gitWorkspaceRoot, warnings, install
         warnings.push(`merge_fence_skipped:install_failed:${error.context.code ?? "pm_error"}:${error.message}:run pm merge install after resolving the Git repository error`);
     }
 }
+async function ensureInitWorkspaceGitignore(workspaceRoot, pmRoot, agentGuidanceMode, warnings) {
+    if (workspaceRoot === undefined ||
+        workspaceRoot === null ||
+        agentGuidanceMode === "status") {
+        return;
+    }
+    const gitignore = await ensurePmGitignore(workspaceRoot, { pmRoot });
+    if (gitignore.changed) {
+        warnings.push(`updated:gitignore:${gitignore.path}`);
+    }
+}
 /** Implements run init for the public runtime surface of this module. */
 export async function runInit(prefixArg, global, options = {}) {
-    const cwd = process.cwd();
+    const invocationCwd = global[INIT_INVOCATION_CWD];
+    const cwd = typeof invocationCwd === "string" ? invocationCwd : process.cwd();
     const invocation = resolveInitInvocation(cwd, global, prefixArg, options.workspace);
     const pmRoot = invocation.pmRoot;
     prefixArg = resolveInitPrefixInput(invocation.prefixArg, options.idPrefix);
@@ -773,12 +787,7 @@ export async function runInit(prefixArg, global, options = {}) {
         settings = await readSettings(pmRoot);
     }
     await ensureInitTypeDirectories({ pmRoot, settings, createdDirs, warnings });
-    if (workspaceRoot && normalizedOptions.agentGuidanceMode !== "status") {
-        const gitignore = await ensurePmGitignore(workspaceRoot, { pmRoot });
-        if (gitignore.changed) {
-            warnings.push(`updated:gitignore:${gitignore.path}`);
-        }
-    }
+    await ensureInitWorkspaceGitignore(workspaceRoot, pmRoot, normalizedOptions.agentGuidanceMode, warnings);
     if (!settingsExists &&
         options.mergeFence !== false &&
         normalizedOptions.agentGuidanceMode !== "status") {
@@ -809,4 +818,4 @@ export async function runInit(prefixArg, global, options = {}) {
     };
 }
 //# sourceMappingURL=init.js.map
-//# debugId=75c0d2d2-6a89-508f-b7dd-b43d55978b44
+//# debugId=d06d4db7-8ab7-5a9f-84df-508bd305ea23

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

@@ -7,7 +7,7 @@
  * this module so packages and hosts can reuse the same merge behavior.
  */
 export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, type HistoryMergeResult, type HistoryMergeStrategy, type ItemDocumentMergeResult, type JsonDocumentMergeResult, type ItemMergeConflictDecision, type MergePreferredSide, type RelationshipStreamMergeResult, } from "./three-way.js";
-export { inspectMergeReceiptEvidence, listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptEvidenceReport, runMergeReceiptReport, summarizeMergeReceipt, type MergeDecisionReceipt, type MergeDecisionReceiptSummary, type MergeReceiptEvidenceReport, type MergeReceiptEvidenceScan, type MergeReceiptReport, } from "./receipts.js";
+export { inspectMergeReceiptEvidence, listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptEvidenceReport, runMergeReceiptReport, summarizeMergeReceipt, type MergeDecisionReceipt, type MergeDecisionReceiptSummary, type MergeReceiptEvidenceReport, type MergeReceiptEvidenceScan, type MergeReceiptInvalidEvidence, type MergeReceiptReport, } from "./receipts.js";
 export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, type MergeDriverArtifact, type MergeDriverOptions, type MergeDriverResult, } from "./driver.js";
 export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, PM_GITATTRIBUTES_V2_END, PM_GITATTRIBUTES_V2_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, type MergeFenceAuditResult, type MergeDriverConfigurationAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallContextResolution, type MergeInstallResult, } from "./install.js";
 export { runMergeReconcile, type MergeReconcileOptions, type MergeReconcileResult, } from "./reconcile.js";

package/dist/sdk/merge/index.js

@@ -7,11 +7,11 @@
  * this module so packages and hosts can reuse the same merge 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]="a26f1126-3c87-5b0d-8712-2846fc9dcbb3")}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]="0a17e896-d54a-5796-8be3-535179c4d6e0")}catch(e){}}();
 export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, } from "./three-way.js";
 export { inspectMergeReceiptEvidence, listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptEvidenceReport, runMergeReceiptReport, summarizeMergeReceipt, } from "./receipts.js";
 export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, } from "./driver.js";
 export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, PM_GITATTRIBUTES_V2_END, PM_GITATTRIBUTES_V2_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, } from "./install.js";
 export { runMergeReconcile, } from "./reconcile.js";
 //# sourceMappingURL=index.js.map
-//# debugId=a26f1126-3c87-5b0d-8712-2846fc9dcbb3
+//# debugId=0a17e896-d54a-5796-8be3-535179c4d6e0

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

@@ -1,4 +1,7 @@
+import type { Stats } from "node:fs";
 import type { ItemMergeConflictDecision, MergePreferredSide } from "./three-way.js";
+/** Return whether a receipt id is safe to expose in cleartext diagnostics. */
+export declare function isSafeReceiptId(value: string): boolean;
 /** One clone-local merge receipt with recoverable branch values. */
 export interface MergeDecisionReceipt {
     /** Receipt schema version. */
@@ -80,6 +83,10 @@ export interface MergeReceiptEvidenceReport {
     count: number;
     /** Number of candidates rejected by bounded-file, schema, identity, or copy-consistency validation. */
     invalid_evidence_count: number;
+    /** Bounded privacy-safe identities and reason codes for rejected evidence. */
+    invalid_evidence: MergeReceiptInvalidEvidence[];
+    /** Whether additional rejected evidence was omitted from the bounded detail list. */
+    invalid_evidence_truncated: boolean;
     /** Whether the clone-local Git receipt directory was resolved successfully; always emitted by current implementations and optional for structural compatibility. */
     clone_local_evidence_resolved?: boolean;
     /** Receipts including recoverable values from the local clone only. */
@@ -93,9 +100,24 @@ export interface MergeReceiptEvidenceScan {
     receipts: MergeDecisionReceipt[];
     /** Number of JSON receipt candidates that could not be validated safely. */
     invalid_evidence_count: number;
+    /** Bounded privacy-safe identities and reason codes for rejected evidence. */
+    invalid_evidence: MergeReceiptInvalidEvidence[];
+    /** Whether additional rejected evidence was omitted from the bounded detail list. */
+    invalid_evidence_truncated: boolean;
     /** Whether the clone-local Git receipt directory was resolved successfully; always emitted by current implementations and optional for structural compatibility. */
     clone_local_evidence_resolved?: boolean;
 }
+/** Stable privacy-safe classification for one rejected receipt candidate or source. */
+export interface MergeReceiptInvalidEvidence {
+    /** Evidence store that produced the rejected candidate. */
+    evidence_source: "clone_local" | "durable" | "clone_local_and_durable";
+    /** Stable failure class suitable for remediation routing and graph analytics. */
+    reason: "directory_unreadable" | "candidate_not_bounded_regular_file" | "candidate_unreadable" | "candidate_invalid_json" | "schema_or_identity_invalid" | "copy_provenance_mismatch";
+    /** Receipt identity when the bounded filename itself is a valid receipt id. */
+    receipt_id?: string;
+    /** SHA-256 locator for an unsafe or malformed candidate filename. */
+    candidate_name_hash?: string;
+}
 declare function prepareReceiptSettlement(params: {
     receiptPath: string;
     receiptId: string;
@@ -120,6 +142,7 @@ export declare function writeMergeReceipt(params: {
     mergedFieldHashes?: Record<string, string>;
     decisions: ItemMergeConflictDecision[];
 }): Promise<MergeDecisionReceipt | null>;
+declare function receiptDirectoryFailureMeansAbsent(directory: string, error: unknown, inspectAncestor?: (ancestor: string) => Promise<Pick<Stats, "isDirectory">>): Promise<boolean>;
 /** Inspect valid receipts and count invalid evidence without returning untrusted file contents. */
 export declare function inspectMergeReceiptEvidence(cwd: string, options?: {
     /** Include receipts whose reconciliation state is already settled. */
@@ -163,5 +186,6 @@ export declare function runMergeReceiptEvidenceReport(options: {
 /** Test-only seams for deterministic receipt-boundary fault coverage. */
 export declare const _testOnlyMergeReceipts: {
     prepareReceiptSettlement: typeof prepareReceiptSettlement;
+    receiptDirectoryFailureMeansAbsent: typeof receiptDirectoryFailureMeansAbsent;
 };
 export {};

package/dist/sdk/merge/receipts.js

@@ -7,10 +7,10 @@
  * 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]="624fc190-4c46-5a55-b757-72e621aec35d")}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]="df7d5bd9-8381-5961-bda1-9e8ed335afc9")}catch(e){}}();
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { readdir } from "node:fs/promises";
+import { readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import { ensureDir, isFileAbsentError, isFileMissingError, pathExists, writeFileAtomic, } from "../../core/fs/fs-utils.js";
@@ -24,6 +24,7 @@ const RECEIPT_FIELD_MAX = 2_048;
 const RECEIPT_FILE_MAX_BYTES = 16 * 1024 * 1024;
 const RECEIPT_VALUE_MAX_DEPTH = 64;
 const RECEIPT_VALUE_MAX_NODES = 100_000;
+const RECEIPT_INVALID_EVIDENCE_DETAIL_LIMIT = 100;
 const RECEIPT_KEYS = new Set([
     "version",
     "id",
@@ -42,6 +43,10 @@ const RECEIPT_KEYS = new Set([
     "value_availability",
     "evidence_source",
 ]);
+/** Return whether a receipt id is safe to expose in cleartext diagnostics. */
+export function isSafeReceiptId(value) {
+    return RECEIPT_ID_PATTERN.test(value);
+}
 const RECEIPT_DECISION_KEYS = new Set([
     "field",
     "base",
@@ -163,7 +168,7 @@ function hasValidReceiptIdentity(value) {
     return !hasOnlyKeys(value, RECEIPT_KEYS) || value.version !== 1
         ? false
         : typeof value.id === "string" &&
-            RECEIPT_ID_PATTERN.test(value.id) &&
+            isSafeReceiptId(value.id) &&
             typeof value.item_id === "string" &&
             RECEIPT_ITEM_ID_PATTERN.test(value.item_id) &&
             isSafeReceiptItemPath(value.item_path, value.item_id);
@@ -372,54 +377,115 @@ async function readReceiptsFromDirectory(directory, evidenceSource) {
         names = await readdir(directory);
     }
     catch (error) {
+        const absent = await receiptDirectoryFailureMeansAbsent(directory, error);
         return {
             receipts: [],
-            invalid_evidence_count: isFileMissingError(error) ? 0 : 1,
+            invalid_evidence_count: absent ? 0 : 1,
+            invalid_evidence: absent
+                ? []
+                : [{ evidence_source: evidenceSource, reason: "directory_unreadable" }],
+            invalid_evidence_truncated: false,
         };
     }
     const receipts = [];
     let invalidEvidenceCount = 0;
+    const invalidEvidence = [];
+    const recordInvalidEvidence = (name, reason) => {
+        invalidEvidenceCount += 1;
+        if (invalidEvidence.length >= RECEIPT_INVALID_EVIDENCE_DETAIL_LIMIT)
+            return;
+        const receiptId = name.slice(0, -".json".length);
+        invalidEvidence.push({
+            evidence_source: evidenceSource,
+            reason,
+            ...(isSafeReceiptId(receiptId)
+                ? { receipt_id: receiptId }
+                : { candidate_name_hash: sha256Hex(name) }),
+        });
+    };
     for (const name of names.sort((left, right) => left.localeCompare(right))) {
         if (!name.endsWith(".json"))
             continue;
+        const candidate = await inspectReceiptCandidate(directory, name, evidenceSource);
+        if (candidate.receipt !== undefined) {
+            receipts.push(candidate.receipt);
+        }
+        else {
+            recordInvalidEvidence(name, candidate.reason);
+        }
+    }
+    return {
+        receipts,
+        invalid_evidence_count: invalidEvidenceCount,
+        invalid_evidence: invalidEvidence,
+        invalid_evidence_truncated: invalidEvidenceCount > invalidEvidence.length,
+    };
+}
+async function receiptDirectoryFailureMeansAbsent(directory, error, inspectAncestor = stat) {
+    if (!isFileMissingError(error))
+        return false;
+    let ancestor = directory;
+    while (true) {
         try {
-            const receiptPath = path.join(directory, name);
-            const raw = await readBoundedRegularReceiptFile(receiptPath);
-            if (raw === null) {
-                invalidEvidenceCount += 1;
-                continue;
-            }
-            const parsed = JSON.parse(raw);
-            if (!isMergeDecisionReceipt(parsed, evidenceSource) ||
-                name !== receiptFileName(parsed.id)) {
-                invalidEvidenceCount += 1;
-                continue;
-            }
-            const { preferred: legacyPreference, evidence_source: _serializedEvidenceSource, ...receiptWithoutRuntimeKeys } = parsed;
-            const normalizedReceipt = {
-                ...receiptWithoutRuntimeKeys,
-                requested_preference: parsed.requested_preference ?? legacyPreference ?? "ours",
-                conflict_resolution: parsed.conflict_resolution ?? "preferred_side",
-                evidence_source: evidenceSource,
-            };
-            receipts.push(normalizedReceipt);
+            return (await inspectAncestor(ancestor)).isDirectory();
         }
-        catch {
-            invalidEvidenceCount += 1;
+        catch (ancestorError) {
+            if (!isFileMissingError(ancestorError))
+                return false;
+            const parent = path.dirname(ancestor);
+            if (parent === ancestor)
+                return true;
+            ancestor = parent;
         }
     }
-    return { receipts, invalid_evidence_count: invalidEvidenceCount };
+}
+async function inspectReceiptCandidate(directory, name, evidenceSource) {
+    let raw;
+    try {
+        raw = await readBoundedRegularReceiptFile(path.join(directory, name));
+    }
+    catch {
+        return { reason: "candidate_unreadable" };
+    }
+    if (raw === null)
+        return { reason: "candidate_not_bounded_regular_file" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { reason: "candidate_invalid_json" };
+    }
+    if (!isMergeDecisionReceipt(parsed, evidenceSource) ||
+        name !== receiptFileName(parsed.id)) {
+        return { reason: "schema_or_identity_invalid" };
+    }
+    const { preferred: legacyPreference, evidence_source: _serializedEvidenceSource, ...receiptWithoutRuntimeKeys } = parsed;
+    return {
+        receipt: {
+            ...receiptWithoutRuntimeKeys,
+            requested_preference: parsed.requested_preference ?? legacyPreference ?? "ours",
+            conflict_resolution: parsed.conflict_resolution ?? "preferred_side",
+            evidence_source: evidenceSource,
+        },
+    };
 }
 /** Inspect valid receipts and count invalid evidence without returning untrusted file contents. */
 export async function inspectMergeReceiptEvidence(cwd, options = {}) {
     const directory = await resolveReceiptDirectory(cwd);
     const local = directory === null
-        ? { receipts: [], invalid_evidence_count: 0 }
+        ? {
+            receipts: [],
+            invalid_evidence_count: 0,
+            invalid_evidence: [],
+            invalid_evidence_truncated: false,
+        }
         : await readReceiptsFromDirectory(directory, "clone_local");
     const trackerRoot = options.pmRoot ?? path.join(cwd, ".agents", "pm");
     const durable = await readReceiptsFromDirectory(durableReceiptDirectory(trackerRoot), "durable");
     const receipts = new Map(durable.receipts.map((receipt) => [receipt.id, receipt]));
     let divergentCopyCount = 0;
+    const divergentCopyEvidence = [];
     for (const receipt of local.receipts) {
         const durableCopy = receipts.get(receipt.id);
         if (durableCopy !== undefined &&
@@ -427,6 +493,16 @@ export async function inspectMergeReceiptEvidence(cwd, options = {}) {
                 receiptProvenanceFingerprint(receipt)) {
             receipts.delete(receipt.id);
             divergentCopyCount += 1;
+            if (local.invalid_evidence.length +
+                durable.invalid_evidence.length +
+                divergentCopyEvidence.length <
+                RECEIPT_INVALID_EVIDENCE_DETAIL_LIMIT) {
+                divergentCopyEvidence.push({
+                    evidence_source: "clone_local_and_durable",
+                    reason: "copy_provenance_mismatch",
+                    receipt_id: receipt.id,
+                });
+            }
             continue;
         }
         receipts.set(receipt.id, durableCopy === undefined
@@ -441,6 +517,17 @@ export async function inspectMergeReceiptEvidence(cwd, options = {}) {
         invalid_evidence_count: local.invalid_evidence_count +
             durable.invalid_evidence_count +
             divergentCopyCount,
+        invalid_evidence: [
+            ...local.invalid_evidence,
+            ...durable.invalid_evidence,
+            ...divergentCopyEvidence,
+        ].slice(0, RECEIPT_INVALID_EVIDENCE_DETAIL_LIMIT),
+        invalid_evidence_truncated: local.invalid_evidence_truncated ||
+            durable.invalid_evidence_truncated ||
+            local.invalid_evidence_count +
+                durable.invalid_evidence_count +
+                divergentCopyCount >
+                RECEIPT_INVALID_EVIDENCE_DETAIL_LIMIT,
         clone_local_evidence_resolved: directory !== null,
     };
 }
@@ -538,12 +625,17 @@ export async function runMergeReceiptEvidenceReport(options) {
         complete,
         count: evidence.receipts.length,
         invalid_evidence_count: evidence.invalid_evidence_count,
+        invalid_evidence: evidence.invalid_evidence,
+        invalid_evidence_truncated: evidence.invalid_evidence_truncated,
         clone_local_evidence_resolved: evidence.clone_local_evidence_resolved,
         receipts: evidence.receipts,
         generated_at: nowIso(),
     };
 }
 /** Test-only seams for deterministic receipt-boundary fault coverage. */
-export const _testOnlyMergeReceipts = { prepareReceiptSettlement };
+export const _testOnlyMergeReceipts = {
+    prepareReceiptSettlement,
+    receiptDirectoryFailureMeansAbsent,
+};
 //# sourceMappingURL=receipts.js.map
-//# debugId=624fc190-4c46-5a55-b757-72e621aec35d
+//# debugId=df7d5bd9-8381-5961-bda1-9e8ed335afc9

package/dist/sdk/query/context.d.ts

@@ -7,7 +7,7 @@ import { type GlobalOptions, type RuntimeStatusRegistry } from "../runtime-primi
 import type { ContextDepth, ContextSectionName, ContextSettings, ItemMetadata, ItemStatus, PmSettings } from "../../types/index.js";
 import { type CalendarRow } from "./calendar.js";
 import { type CompactActivityEntry } from "./activity.js";
-import { type ContextRelevanceContributions, type ContextRelevanceReport, type ContextRelevanceSignalName } from "../context-relevance.js";
+import { type ContextRelevanceContributions, type ContextRecencyEvidence, type ContextRelevanceReport, type ContextRelevanceSignalName } from "../context-relevance.js";
 export { buildItemContextRelevanceCandidates } from "../context-relevance.js";
 import { type ContextPackingReport } from "../context-packing.js";
 import { type ContextSignalStoreReadResult } from "../context-signal-store.js";
@@ -398,6 +398,8 @@ export interface ContextRankingSummary {
         baseline_rank: number;
         score: number;
         contributions: ContextRelevanceContributions;
+        /** Authoritative temporal source used for the recency contribution. */
+        recency?: ContextRecencyEvidence;
     }>;
     /** Number of candidates considered before answer-sized projection. */
     candidate_count: number;

package/dist/sdk/query/context.js

@@ -4,7 +4,7 @@
  * Implements the pm context 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]="a870e3ac-f731-5cbf-a66e-38d1d5b1d0aa")}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]="56205e5f-fc26-59ab-abdf-45bdcaf1c263")}catch(e){}}();
 import { SETTINGS_DEFAULTS, EXIT_CODE, PmCliError, compareTimestampStrings, nowIso, isTerminalStatus, normalizeStatusForRegistry, normalizeStatusInput, resolveRuntimeStatusRegistry, resolvePmRoot, readSettings, resolveAuthor, discoverExtensions, } from "../runtime-primitives.js";
 import { collectDependencyBlockedIds, resolveItemBlockers, } from "../actionability.js";
 import { CONTEXT_DEPTH_VALUES, CONTEXT_SECTION_VALUES, } from "../../types/index.js";
@@ -17,7 +17,7 @@ export { buildItemContextRelevanceCandidates } from "../context-relevance.js";
 import { createQueryFingerprint, encodeQueryCursor, resolveQueryCursorStart, selectCursorSemanticOptions, } from "../pagination.js";
 import { CONTEXT_FLAG_CONTRACTS } from "../cli-contracts/flag-contracts.js";
 import { packContextCandidates, } from "../context-packing.js";
-import { readContextUsageAffinity, recordContextUsageServing, } from "../context-usage.js";
+import { attachContextUsageServingReceipt, collectContextUsageDeliveredItemIds, readContextUsageAffinity, recordContextUsageServing, } from "../context-usage.js";
 import { readWorkspaceContextSignals, } from "../context-signal-store.js";
 import { readWorkspaceMemory, selectWorkspaceMemory, } from "../workspace-memory.js";
 import { detectAgentIdentity } from "../../core/shared/author.js";
@@ -465,6 +465,9 @@ export function toContextRankingSummary(report, featureStore, servedItemIds) {
             baseline_rank: entry.baseline_rank,
             score: entry.score,
             contributions: entry.contributions,
+            ...(entry.signal_provenance === undefined
+                ? {}
+                : { recency: entry.signal_provenance.recency }),
         })),
         candidate_count: report.ranked.length,
         omitted_count: report.ranked.length - ranked.length,
@@ -1512,18 +1515,27 @@ function maybeAttachEmptyContextSuggestions(result, activeItems, blockedItems) {
 async function attachContextUsageFeedback(result, focusGroups, pmRoot, author) {
     try {
         const included = new Set(focusGroups.packing.included.map((entry) => entry.id));
-        await recordContextUsageServing({
+        const rows = focusGroups.ranking.ranked.map((entry) => ({
+            id: entry.id,
+            rank: entry.rank,
+            included: included.has(entry.id),
+        }));
+        const rankedIds = new Set(rows.map((row) => row.id));
+        for (const id of collectContextUsageDeliveredItemIds(result, "context")) {
+            if (!rankedIds.has(id)) {
+                rows.push({ id, rank: rows.length + 1, included: false });
+                rankedIds.add(id);
+            }
+        }
+        const receipt = await recordContextUsageServing({
             pmRoot,
             author,
             surface: "context",
             profile: focusGroups.packing.profile,
-            rows: focusGroups.ranking.ranked.map((entry) => ({
-                id: entry.id,
-                rank: entry.rank,
-                included: included.has(entry.id),
-            })),
+            rows,
             enabled: process.env.PM_CONTEXT_USAGE_DISABLED !== "1",
         });
+        attachContextUsageServingReceipt(result, receipt);
     }
     catch {
         result.warnings = mergeSortedWarnings(result.warnings, [
@@ -1676,4 +1688,4 @@ export async function runContext(options, global) {
     return result;
 }
 //# sourceMappingURL=context.js.map
-//# debugId=a870e3ac-f731-5cbf-a66e-38d1d5b1d0aa
+//# debugId=56205e5f-fc26-59ab-abdf-45bdcaf1c263

package/dist/sdk/query/next.js

@@ -9,14 +9,14 @@
  * re-deriving readiness from a full `pm context` snapshot every turn.
  */
 
-!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]="9b788e0a-f4ac-5c6e-bf52-0ef0519d6925")}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]="b0f3d72c-ff0b-59bb-a6bc-8476eb9fb6c1")}catch(e){}}();
 import { collectBlockedByIds, computeActionabilityReport, } from "../actionability.js";
 import { resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, nowIso, normalizeStatusInput, normalizeStatusForRegistry, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { parseIntegerLimit } from "./parsers.js";
 import { buildChildrenByParent, collectSubtreeIds, compareCriticalItems, mergeSortedWarnings, packRankedContextItems, resolveContextTokenBudget, toContextPackingSummary, toContextRankingSummary, toContextFocusItem, } from "./context.js";
 import { runList } from "./list.js";
 import { scoreContextCandidatesWithActiveExtensions } from "../context-relevance.js";
-import { readContextUsageAffinity, recordContextUsageServing, } from "../context-usage.js";
+import { attachContextUsageServingReceipt, collectContextUsageDeliveredItemIds, readContextUsageAffinity, recordContextUsageServing, } from "../context-usage.js";
 import { readWorkspaceContextSignals, } from "../context-signal-store.js";
 /** Supported values accepted by the next output contract. */
 export const NEXT_OUTPUT_VALUES = ["markdown", "toon", "json"];
@@ -228,18 +228,27 @@ function buildNextTruncation(decisionCount, heldCount, limit) {
 async function attachNextUsageFeedback(params) {
     try {
         const included = new Set(params.packing.included.map((entry) => entry.id));
-        await recordContextUsageServing({
+        const rows = params.ranking.ranked.map((entry) => ({
+            id: entry.id,
+            rank: entry.rank,
+            included: included.has(entry.id),
+        }));
+        const rankedIds = new Set(rows.map((row) => row.id));
+        for (const id of collectContextUsageDeliveredItemIds(params.result, "next")) {
+            if (!rankedIds.has(id)) {
+                rows.push({ id, rank: rows.length + 1, included: false });
+                rankedIds.add(id);
+            }
+        }
+        const receipt = await recordContextUsageServing({
             pmRoot: params.pmRoot,
             author: params.author,
             surface: "next",
             profile: params.packing.profile,
-            rows: params.ranking.ranked.map((entry) => ({
-                id: entry.id,
-                rank: entry.rank,
-                included: included.has(entry.id),
-            })),
+            rows,
             enabled: process.env.PM_CONTEXT_USAGE_DISABLED !== "1",
         });
+        attachContextUsageServingReceipt(params.result, receipt);
     }
     catch {
         params.result.warnings = mergeSortedWarnings(params.result.warnings, [
@@ -479,4 +488,4 @@ function formatNextLine(item) {
     return `${rankToken}${item.id} p${item.priority} ${item.status} ${item.type} deadline:${deadlineToken}${parentToken}${unblocksToken} ${item.title}`;
 }
 //# sourceMappingURL=next.js.map
-//# debugId=9b788e0a-f4ac-5c6e-bf52-0ef0519d6925
+//# debugId=b0f3d72c-ff0b-59bb-a6bc-8476eb9fb6c1

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

@@ -31,6 +31,8 @@ export declare function withAddNoteOption(options: Record<string, unknown>): Rec
 export declare function withFilesDiscoveryOptions(options: Record<string, unknown>): Record<string, unknown>;
 /** Canonicalize one action name into lower-kebab-case tokens. */
 export declare function normalizeActionName(value: string): string;
+/** Return whether an action can change workspace extension contracts. */
+export declare function shouldInvalidateWorkspaceContractsCacheAfterAction(action: string): boolean;
 /** Canonicalize one space-separated command path for lookup comparisons. */
 export declare function normalizeCommandPath(value: string): string;
 /** Coerce an unknown payload value into a non-empty string array. */

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]="fde4fea5-94d6-53e2-bfbc-bff71d828c01")}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]="d42d5fb1-eebc-5549-ae88-dc923d9d3696")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { asRecordClone } from "../core/shared/primitives.js";
@@ -14,6 +14,25 @@ import { UPDATE_COMMANDER_STRING_OPTION_CONTRACTS } from "./cli-contracts/comman
 import { normalizeBulkIdsValue, } from "../core/io/bulk-ids-input.js";
 import { overlayMutationStdinTokenPolicy, preserveMutationStdinTokenLiterals, transferMutationStdinTokenPolicy, } from "../core/item/parse.js";
 const MCP_MUTATION_TRANSPORT = Symbol("pm.mcp-mutation-transport");
+const WORKSPACE_CONTRACTS_CACHE_PRESERVING_ACTIONS = new Set([
+    "activity",
+    "aggregate",
+    "context",
+    "contracts",
+    "deps",
+    "files-discover",
+    "files-lookup",
+    "get",
+    "graph",
+    "health",
+    "history",
+    "list",
+    "next",
+    "search",
+    "stats",
+    "telemetry",
+    "validate",
+]);
 /** Mark an action object decoded from the MCP JSON-RPC transport. */
 export function markMcpMutationTransportInput(input) {
     Object.defineProperty(input, MCP_MUTATION_TRANSPORT, {
@@ -353,6 +372,10 @@ export function normalizeActionName(value) {
     }
     return chunks.join("");
 }
+/** Return whether an action can change workspace extension contracts. */
+export function shouldInvalidateWorkspaceContractsCacheAfterAction(action) {
+    return !WORKSPACE_CONTRACTS_CACHE_PRESERVING_ACTIONS.has(normalizeActionName(action));
+}
 /** Canonicalize one space-separated command path for lookup comparisons. */
 export function normalizeCommandPath(value) {
     return value.trim().toLowerCase().split(/\s+/).filter(Boolean).join(" ");
@@ -589,4 +612,4 @@ export function updateManyOptionsFromFlat(options) {
     };
 }
 //# sourceMappingURL=runtime-input.js.map
-//# debugId=fde4fea5-94d6-53e2-bfbc-bff71d828c01
+//# debugId=d42d5fb1-eebc-5549-ae88-dc923d9d3696

package/dist/sdk/runtime.d.ts

@@ -66,6 +66,7 @@ export type { ClaimResult, CloseResult, CreateResult, ReleaseResult, UpdateResul
 export { getActiveExtensionRegistrations, runActiveOnReadHooks, runActiveOnWriteHooks, } from "../core/extensions/index.js";
 export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
 export { appendHistoryEntry, createHistoryEntry, } from "../core/history/history.js";
+export { classifyHistoryEvent, HISTORY_EVENT_CLASSIFICATION_VERSION, MAINTENANCE_HISTORY_OPERATIONS, SUBSTANTIVE_HISTORY_OPERATIONS, type HistoryEventClass } from "../core/history/event-classification.js";
 export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/item/id.js";
 export { readBooleanOption, readCsvListOption, readStringOption, } from "./package-runtime-options.js";
 export { PM_CLI_EXPECTED_ERROR_NAME, createPmCliExpectedError, isPmCliExpectedError, type CreatePmCliExpectedErrorOptions, type PmCliExpectedError, } from "./errors.js";