@unbrained/pm-cli 2026.9.2 → 2026.9.4

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-primitives.d.ts

@@ -17,10 +17,10 @@ export { isFileMissingError, pathExists, readFileIfExists, removeFileIfExists, w
 export { normalizeBulkIdsValue, parseBulkIdsText, resolveCliBulkIdsInput, type BulkIdsFileReader, type BulkIdsInputReaders, type BulkIdsStdinReader, type BulkIdsValue, } from "../core/io/bulk-ids-input.js";
 export { type HistoryDiffValueEntry, computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
-export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, type HistoryItemHashVersion, } from "../core/history/history.js";
+export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, CURRENT_HISTORY_RECORD_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, hashHistoryPatch, hashHistoryRecord, hashHistoryStream, resealHistoryRewrite, sealHistoryRecord, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, SUPPORTED_HISTORY_RECORD_HASH_VERSIONS, verifyHistoryRecordHash, verifyHistoryRewriteEvidence, type HistoryItemHashVersion, type HistoryRecordHashVersion, } from "../core/history/history.js";
 export { readHistoryEntries } from "../core/history/read.js";
 export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceHistoryStateAgreement, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonReconciliationOptions, type WorkspaceJsonRestoreOptions, type WorkspaceJsonRestoreResult, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
-export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
+export { normalizeReplayPatchOps, reanchorHistoryEntries, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 export { resolveBodyFileContent } from "../core/io/body-file.js";
 export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/item/id.js";
 export { canonicalDocument, normalizeItemMetadata, parseItemDocument, serializeItemDocument, } from "../core/item/item-format.js";

package/dist/sdk/runtime-primitives.js

@@ -7,7 +7,7 @@
  * prefer the typed operations exported by the main SDK barrel.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d45775e5-6826-521b-80b3-429ed22947d9")}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]="aba5403c-0694-5c51-95a8-ae7e7575347b")}catch(e){}}();
 export { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
 export { createUnknownSubcommandError, } from "./agent/subcommand-recovery.js";
@@ -19,10 +19,10 @@ export { isFileMissingError, pathExists, readFileIfExists, removeFileIfExists, w
 export { normalizeBulkIdsValue, parseBulkIdsText, resolveCliBulkIdsInput, } from "../core/io/bulk-ids-input.js";
 export { computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
-export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, } from "../core/history/history.js";
+export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, CURRENT_HISTORY_RECORD_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, hashHistoryPatch, hashHistoryRecord, hashHistoryStream, resealHistoryRewrite, sealHistoryRecord, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, SUPPORTED_HISTORY_RECORD_HASH_VERSIONS, verifyHistoryRecordHash, verifyHistoryRewriteEvidence, } from "../core/history/history.js";
 export { readHistoryEntries } from "../core/history/read.js";
 export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
-export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
+export { normalizeReplayPatchOps, reanchorHistoryEntries, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 export { resolveBodyFileContent } from "../core/io/body-file.js";
 export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/item/id.js";
 export { canonicalDocument, normalizeItemMetadata, parseItemDocument, serializeItemDocument, } from "../core/item/item-format.js";
@@ -82,4 +82,4 @@ export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";
 export { emitTelemetryErrorEvent, finishTelemetryCommand, startTelemetryCommand, } from "../core/telemetry/runtime.js";
 //# sourceMappingURL=runtime-primitives.js.map
-//# debugId=d45775e5-6826-521b-80b3-429ed22947d9
+//# debugId=aba5403c-0694-5c51-95a8-ae7e7575347b

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";

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="b67ba0fe-bbca-57ab-b3be-a4a028f21de4")}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]="099c7cda-4a92-553c-ad60-00e185b5971b")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 export * from "./cli-contracts/agent-output-contracts.js";
@@ -33,6 +33,7 @@ import { SDK_ACTION_ALIASES } from "./runtime-action-aliases.js";
 import { createExtensionCommandSdk } from "./extension-command-context.js";
 import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 import { applyContextIntentProjection, attachReadOutputContracts, } from "./context-intent-contracts.js";
+import { finalizeContextUsageEgress } from "./context/usage-egress.js";
 import { runWithDiscoveredContextIntentContracts, } from "./context-intent-runtime.js";
 import { normalizeReadOutputIncludeModeOptions, validateReadOutputOptions, } from "./read-output-contracts.js";
 export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";
@@ -65,14 +66,14 @@ import { runHealth, } from "./governance/health.js";
 import { runValidate, } from "./governance/validate.js";
 import { runExtension, } from "./extension.js";
 import { runConfig } from "./config.js";
-import { runInit } from "./init.js";
+import { INIT_INVOCATION_CWD, runInit } from "./init.js";
 import { runRuntimeEvalAction, runRuntimeEventsAction, runRuntimeMergeAction, runRuntimeSchedulingAction, runRuntimeWorkspaceAction, } from "./runtime-extended-actions.js";
 import { acknowledgeUnknownAuthorHistoryEventsFromTransport, } from "./author-attribution.js";
 import { PROFILE_SUBCOMMANDS, runProfileApply, runProfileLint, runProfileList, runProfileShow, } from "./profile.js";
 import { runHistoryRedact, } from "./history-redact.js";
 import { runMcpHistoryCompactAction, runMcpHistoryRepairAction, } from "./history-mcp.js";
 import { runMcpCloseAction, runMcpReopenAction } from "./lifecycle/mcp-actions.js";
-import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, mutationOptionsWithOverrides, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, readRuntimeStringArray as readStringArray, resolveRuntimeLimit, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction, } from "./runtime-input.js";
+import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, mutationOptionsWithOverrides, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, readRuntimeStringArray as readStringArray, resolveRuntimeLimit, shouldInvalidateWorkspaceContractsCacheAfterAction, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction, } from "./runtime-input.js";
 import { runDeps } from "./dependencies.js";
 import { runDocs } from "./docs.js";
 import { runGraph, } from "./graph/run.js";
@@ -92,6 +93,7 @@ import { SCHEMA_SUBCOMMANDS, runSchemaAddField, runSchemaAddStatus, runSchemaAdd
 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 } 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, } from "./errors.js";
@@ -1276,24 +1278,6 @@ async function withCwd(cwd, run) {
         process.chdir(previous);
     }
 }
-const WORKSPACE_CONTRACTS_CACHE_PRESERVING_ACTIONS = new Set([
-    "activity",
-    "aggregate",
-    "context",
-    "contracts",
-    "deps",
-    "files-discover",
-    "get",
-    "graph",
-    "health",
-    "history",
-    "list",
-    "next",
-    "search",
-    "stats",
-    "telemetry",
-    "validate",
-]);
 function resolveSdkActionInput(args) {
     const rawAction = readRequiredString(args, "action");
     const normalizedAction = normalizeActionName(rawAction);
@@ -1311,9 +1295,6 @@ function resolveSdkActionInput(args) {
     }
     return { action, args: resolvedArgs };
 }
-function shouldInvalidateWorkspaceContractsCacheAfterAction(action) {
-    return !WORKSPACE_CONTRACTS_CACHE_PRESERVING_ACTIONS.has(normalizeActionName(action));
-}
 /** Execute one native or extension-contributed pm action in-process. */
 export async function runAction(args) {
     const resolved = resolveSdkActionInput(args);
@@ -1328,6 +1309,14 @@ export async function runAction(args) {
     // pins process.cwd() (inside the serialized slot) for the built-in handler.
     const explicitCwd = readString(resolved.args, "cwd");
     const resolutionCwd = explicitCwd ?? process.cwd();
+    if (resolved.action === "init") {
+        global[INIT_INVOCATION_CWD] = resolutionCwd;
+    }
+    if (resolved.action !== "init" ||
+        global.path !== undefined ||
+        (process.env.PM_PATH?.trim().length ?? 0) > 0) {
+        global.path = resolvePmRoot(resolutionCwd, global.path);
+    }
     try {
         if (args[ACTIVE_EXTENSION_HOST_CONTEXT] === true ||
             activeExtensionScope.getStore() === true) {
@@ -1886,7 +1875,9 @@ async function dispatchAction(action, args, global, activeExtensions) {
         ? await handler(ctx)
         : await dispatchActiveExtensionAction(action, args, options, global, activeExtensions);
     options.resolvedOutputFormat = "json";
-    return attachReadOutputContracts(action, options, result);
+    const projected = attachReadOutputContracts(action, options, result);
+    await finalizeContextUsageEgress(resolvePmRoot(process.cwd(), global.path), projected);
+    return projected;
 }
 const actionRunnerTestHooks = {
     closeManyOptionsFromFlat,
@@ -1933,4 +1924,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=b67ba0fe-bbca-57ab-b3be-a4a028f21de4
+//# debugId=099c7cda-4a92-553c-ad60-00e185b5971b

package/dist/types.d.ts

@@ -789,6 +789,25 @@ export interface HistoryPatchOp {
     /** Value that configures or reports value for this contract. */
     value?: unknown;
 }
+/** Immutable evidence retained whenever history maintenance replaces anchors or patch operations. */
+export interface HistoryReanchorEvidence {
+    /** Before-state anchor present on the record before re-anchoring. */
+    before_hash: string;
+    /** After-state anchor present on the record before re-anchoring. */
+    after_hash: string;
+    /** Item hash epoch present before re-anchoring. */
+    item_hash_version?: number;
+    /** Hash of the original patch, retained even when redaction forbids retaining its values. */
+    patch_hash: string;
+    /** Original patch operations when repair replaced or skipped recorded intent. */
+    patch?: HistoryPatchOp[];
+    /** Record-integrity epoch protecting the pre-re-anchor record. */
+    record_hash_version?: number;
+    /** Record hash protecting the pre-re-anchor attribution and operation metadata. */
+    record_hash?: string;
+    /** Exact prior sealed record when maintenance can retain its non-sensitive payload. */
+    record?: HistoryEntry;
+}
 /** Documents the history entry payload exchanged by command, SDK, and package integrations. */
 export interface HistoryEntry {
     /** Value that configures or reports ts for this contract. */
@@ -829,6 +848,8 @@ export interface HistoryEntry {
     };
     /** Value that configures or reports op for this contract. */
     op: string;
+    /** Declared semantic effect used by recency consumers. Absent on legacy entries. */
+    event_class?: "substantive" | "maintenance";
     /** Value that configures or reports patch for this contract. */
     patch: HistoryPatchOp[];
     /** Value that configures or reports before hash for this contract. */
@@ -837,6 +858,12 @@ export interface HistoryEntry {
     after_hash: string;
     /** Version of the item canonicalization used by before_hash and after_hash. Absent on legacy streams. */
     item_hash_version?: number;
+    /** Version of the canonical immutable-record envelope. Absent on legacy entries whose coverage is item-state-only. */
+    record_hash_version?: number;
+    /** SHA-256 hash covering this event's immutable metadata, patch, and item anchors. */
+    record_hash?: string;
+    /** Append-only evidence for every prior anchor or patch representation replaced by maintenance. */
+    reanchor_evidence?: HistoryReanchorEvidence[];
     /** Human-readable explanation suitable for logs and agent-facing output. */
     message?: string;
     /** Structured audit metadata that does not alter replayed item state. */

package/dist/types.js

@@ -5,7 +5,7 @@
  */
 /** Supported values accepted by the builtin item type contract. */
 
-!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]="64223a83-1287-57ac-915d-dbd5e375a6eb")}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]="4ee067ac-f28d-5411-9ac7-c92112384a64")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -243,4 +243,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=64223a83-1287-57ac-915d-dbd5e375a6eb
+//# debugId=4ee067ac-f28d-5411-9ac7-c92112384a64

package/docs/AGENT_ENVIRONMENTS.md

@@ -0,0 +1,47 @@
+# SDK Agent Environments
+
+Tracker: [pm-e1vkee](../.agents/pm/features/pm-e1vkee.toon), [pm-gd6vnn](../.agents/pm/features/pm-gd6vnn.toon), [pm-li2fj5](../.agents/pm/features/pm-li2fj5.toon), [pm-t8a0x1](../.agents/pm/features/pm-t8a0x1.toon)
+
+## Agent Quick Context
+
+`@unbrained/pm-cli/sdk` provides three composable contracts for building reproducible project-management environments without a machine-learning runtime dependency:
+
+- an observation contract declares every read ceiling, emitted-byte calibration, corpus-size dependence, and an ordered degradation ladder;
+- a verdict contract evaluates named, versioned predicates over recorded state and returns `satisfied`, `violated`, or `not_applicable` without producing a reward signal;
+- an episode specification combines a deterministic workspace recipe, canonical task items, observable and withheld fields, hard limits, and an adapter for ordinary `PmClient` actions.
+
+The executable [public-SDK example](examples/sdk-agent-environment/README.md) runs the complete reset → observe → act → verdict → close loop in a temporary pm workspace.
+
+## Contract Boundaries
+
+Observation cost is knowable before a read. `describeObservationCost()` returns the sum of the declared read ceilings plus the calibrated expected emitted bytes. `serveDeclaredObservation()` measures stable serialized bytes, attempts tiers in declaration order, names the served tier, and returns a payload-free refusal if no tier fits.
+
+Verdicts only inspect the adapter's `WorkspaceRecordedState`. Evidence identifies the exact snapshot and JSON pointer while a digest avoids copying field values into the result. The interpreter is deterministic and read-only; `policy: "verdict_only_no_reward"` makes the non-reward boundary machine-readable.
+
+Episodes never grant a second mutation vocabulary. The adapter's `execute()` method should call ordinary public `PmClient` methods, so lifecycle validation, history, extensions, and policy remain authoritative. Each session owns its counters and trajectory, allowing concurrent runs without shared episode state.
+
+Withheld grading fields cannot also be observable. Every tier field must be declared observable, and projection copies only the selected tier fields. Hard action and observation limits fail closed.
+
+## Minimal Shape
+
+```ts
+import {
+  defineEpisodeSpecification,
+  openPmEpisode,
+  type EpisodeRuntimeAdapter,
+} from "@unbrained/pm-cli/sdk";
+
+const specification = defineEpisodeSpecification({
+  // Versioned recipe, task set, observation, verdict, and limits.
+});
+const session = await openPmEpisode(
+  specification,
+  adapter satisfies EpisodeRuntimeAdapter<MyAction>,
+);
+
+await session.observe();
+await session.step({ kind: "close" });
+const evidence = await session.close();
+```
+
+Use the same specification and adapter boundary for benchmarks, evaluations, training data collection, or scale-transfer experiments. Consumer intent changes through `mode`; the pm action and evidence contracts do not.

package/docs/AGENT_PROVENANCE_ADR.md

@@ -10,7 +10,9 @@ Implementation lineage:
 resolution and patch-free historical reads implemented by
 [pm-ffz0a9](../.agents/pm/issues/pm-ffz0a9.toon),
 [pm-v8gfi7](../.agents/pm/issues/pm-v8gfi7.toon), and
-[pm-3yxwv5](../.agents/pm/issues/pm-3yxwv5.toon). Cross-harness adapters and
+[pm-3yxwv5](../.agents/pm/issues/pm-3yxwv5.toon). Stable Claude session
+discovery across child working directories is tracked by
+[pm-l7m7k5](../.agents/pm/issues/pm-l7m7k5.toon). Cross-harness adapters and
 operator-managed probe/vocabulary controls are tracked by
 [pm-c0lrdm](../.agents/pm/features/pm-c0lrdm.toon) and
 [pm-yds9dt](../.agents/pm/chores/pm-yds9dt.toon).
@@ -56,7 +58,13 @@ from literal descriptor keys, trusted caller data, or a named bounded resolver.
 Detection does not spawn processes, traverse process trees, evaluate user
 regexes, or access the network. The built-in Claude and Codex resolvers read
 only bounded windows of the current session's harness-owned JSONL file. Claude
-uses the recent tail to recover its recorded model/version. Codex uses the
+resolves an explicitly supplied transcript first, then the direct workspace
+coordinate, then performs a deterministic scan of at most 512 immediate
+project directories for the unique stable session id. This keeps provenance
+attached when the invocation cwd moves into a child package. No match is
+reported as `resolver_input_missing`; multiple matches are ambiguous and remain
+`resolver_failed` instead of selecting an arbitrary transcript. Claude uses the
+bounded session window to recover its recorded model/version. Codex uses the
 recent tail plus a bounded initial-head fallback for oversized sessions to
 recover allow-listed `turn_context.model` and `turn_context.effort` values.
 Both cap traversal, file bytes, lines, and line length, ignore all other fields,
@@ -70,6 +78,13 @@ the existing domain-separated, truncated `agent_instance` digest. Public
 telemetry continues to use installation-scoped hashes or presence booleans; it
 does not export raw provenance values.
 
+Health counts resolvers with an available input, plus failed or ambiguous
+resolution attempts, as attempts. A sustained attempted-but-zero-success series
+remains advisory: it truthfully identifies parser, filesystem, ambiguity, or
+provider-shape drift without treating missing descriptive metadata as
+authorization or item-state corruption. Missing-input and probes-disabled
+events are classified separately and do not inflate that warning.
+
 ## Compatibility
 
 All new history fields are optional. Readers must accept:

package/docs/CONTEXT_INTEGRITY_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Context Integrity Contracts
 
-Tracker references: [pm-4fwgaz](../.agents/pm/issues/pm-4fwgaz.toon), [pm-qqoumq](../.agents/pm/issues/pm-qqoumq.toon), [pm-fpdk37](../.agents/pm/issues/pm-fpdk37.toon), [pm-jn1x30](../.agents/pm/issues/pm-jn1x30.toon), and [pm-0wfdim](../.agents/pm/issues/pm-0wfdim.toon).
+Tracker references: [pm-4fwgaz](../.agents/pm/issues/pm-4fwgaz.toon), [pm-qqoumq](../.agents/pm/issues/pm-qqoumq.toon), [pm-fpdk37](../.agents/pm/issues/pm-fpdk37.toon), [pm-jn1x30](../.agents/pm/issues/pm-jn1x30.toon), [pm-0wfdim](../.agents/pm/issues/pm-0wfdim.toon), [pm-javbsq](../.agents/pm/issues/pm-javbsq.toon), and [pm-aka8m7](../.agents/pm/issues/pm-aka8m7.toon).
 
 ## Agent Quick Context
 
@@ -53,6 +53,43 @@ History writers using item-hash epoch 2 always emit `item_hash_version: 2`. An e
 
 Repair keeps implicit legacy streams implicit and byte-stable when no drift exists. Unsupported explicit epochs still fail with a typed `unsupported_item_hash_version` diagnostic instead of being rewritten.
 
+| Writer/runtime range                     | Item-hash output | Read contract                                                                                                                  |
+| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Legacy writers before an explicit marker | implicit epoch 1 | Modern readers retain legacy canonicalization candidates.                                                                      |
+| Observed 2026.8.24 through 2026.8.28     | explicit epoch 2 | Modern readers accept both field-frozen and expanded epoch-2 forms without mixing forms inside one entry.                      |
+| 2026.8.31 and newer                      | explicit epoch 3 | Exact pins and bounded ranges that cannot select an epoch-3 reader cause current runtimes to reject the write before mutation. |
+
+The table records confirmed release boundaries rather than inventing an exact
+first release for legacy epoch 1 or epoch 2. The SDK exports
+`HISTORY_ITEM_HASH_VERSION_3_INTRODUCED_IN`, and runtime compatibility checks
+use that boundary for package-manager-neutral write refusal.
+
+## Whole-Record History Integrity
+
+Item anchors prove the replayed project state; they do not prove who recorded an
+event, when it happened, which operation produced it, or which provenance and
+context were attached. New events therefore use a separate record-integrity
+epoch. `record_hash_version: 1` seals every immutable field while preserving the
+item-hash epoch as an independent compatibility contract.
+
+`verifyHistoryRecordHash()` reports `record_and_item_state` for a valid sealed
+event and `item_state_only` for a legacy event with neither record-envelope
+field. Half-present, unsupported, and mismatched envelopes fail closed. The
+public SDK also exports the record and patch hashing, sealing,
+`verifyHistoryRewriteEvidence()`, rewrite-resealing, stream-digest, and
+reanchoring primitives so packages and embedded hosts do not need private core
+imports or their own canonicalization.
+
+Maintenance retains prior anchors and patch digests in `reanchor_evidence`.
+When policy permits, it also retains the exact prior sealed record so
+metadata-only rewrites remain independently verifiable. Privacy-sensitive
+redaction and provenance normalization deliberately retain digest-only evidence
+instead of embedding the removed value. This separates two claims: the current
+chain is replay-consistent, and a rewrite preserved evidence of what it
+replaced. Compaction records a digest of its pruned prefix and explicitly states
+that individual pruned entries require the pre-compaction stream; it never
+upgrades intentional information loss into a stronger assurance claim.
+
 ## Verification Boundary
 
 The regression suite covers each contract at its public SDK or command boundary. Release verification additionally installs the packed package into a temporary project and exercises sparse reads, remote docs, graph impact, extension diagnostics, and history repair without touching the repository tracker.

package/docs/CONTEXT_RELEVANCE.md

@@ -1,6 +1,6 @@
 # Context relevance and packing
 
-Tracked by [pm-4k6b](../.agents/pm/features/pm-4k6b.toon), [pm-3hps](../.agents/pm/tasks/pm-3hps.toon), and [pm-801d](../.agents/pm/features/pm-801d.toon).
+Tracked by [pm-4k6b](../.agents/pm/features/pm-4k6b.toon), [pm-07pt16](../.agents/pm/issues/pm-07pt16.toon), [pm-wv47pf](../.agents/pm/issues/pm-wv47pf.toon), [pm-3hps](../.agents/pm/tasks/pm-3hps.toon), and [pm-801d](../.agents/pm/features/pm-801d.toon).
 
 `pm context` and `pm next` share one public SDK relevance pipeline. The built-in
 commands assemble authoritative item metadata, load rebuildable signal rows,
@@ -73,6 +73,49 @@ Graph proximity normalizes parent and dependency degree. SDK hosts can supply
 their own pre-normalized signal maps when their project model has richer
 activity, graph, semantic, or usage data.
 
+### Substantive recency
+
+Recency is a property of what happened, not of the last file write. Every new
+history entry declares `event_class: substantive|maintenance` through the
+versioned `classifyHistoryEvent()` SDK contract. Legacy entries are classified
+by the same declared operation and patch-field policy; unknown operations fail
+closed as substantive. Package and extension scorers can therefore reuse the
+core vocabulary instead of maintaining private operation lists.
+
+The signal selects the most recent substantive history event, then a stamped
+calendar release cohort such as `v2026.7.20`, then `created_at`. It never ranks
+bare `updated_at`, so release attribution, relationship enrichment,
+normalization, linked-artifact updates, and history maintenance cannot promote
+otherwise unchanged work. The rebuildable v5 history-event index stores the
+declared class and retrieves one latest substantive row per requested stream;
+individual immutable streams remain the authoritative fallback. Rebuilds,
+indexed validation reads, and compliant indexed appends share one cross-process
+coordination lock; indexed appends commit their projection row and stream size
+in one SQLite transaction. A lock-conflict fallback append writes authoritative
+history without committing projection data in that transaction, publishes an
+invalidation marker when possible, and discards the derived projection. The
+index must validate or rebuild before serving that append.
+
+Explained ranking includes `recency.source`, `coordinate`, and, for history,
+`history_op` plus `event_class` on every served scorer row. Signal snapshots
+persist that evidence alongside the normalized value so a fresh snapshot keeps
+the same explanation as the ranking it serves.
+
+### Delivered usage feedback
+
+Usage affinity learns from post-egress delivery rather than pre-budget packing.
+A versioned serve event records the full propensity rows and a correlation id;
+CLI and `PmClient` egress append a delivery event containing the final
+`result_omitted` decision and exact emitted item ids. A whole-result omission
+therefore delivers zero items even when the packer selected rows earlier.
+
+Direct `runContext` and `runNext` calls record only their assembled rows on a
+serve event; they do not claim delivery or train affinity by themselves. A
+later CLI or `PmClient` projection appends the correlated delivery decision.
+Legacy serve events have no correlation marker, so the affinity reader ignores
+their inclusion flags and reports them as `untrusted_serving_events` instead of
+training on unverifiable phantom serves.
+
 For corpora of at least 10,000 items, `context` automatically allocates a
 bounded fraction of its token budget to recent calendar-epoch and epic-lineage
 rollups. `search` attaches only matching rollups. The projection contains