@unbrained/pm-cli 2026.9.2 → 2026.9.3

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

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

@@ -829,6 +829,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. */

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]="668a8823-62c4-5c69-9b9b-0c72d6d94b2b")}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=668a8823-62c4-5c69-9b9b-0c72d6d94b2b

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

package/docs/PERFORMANCE.md

@@ -12,7 +12,7 @@ Every measured CLI and SDK operation targets:
 - default output at or below 5,000 estimated tokens;
 - no feature, flag, output, history, or validation loss.
 
-The committed regression budgets in [`scripts/bench/scale-budgets.json`](../scripts/bench/scale-budgets.json) protect the current baseline while the product targets stay fixed. Short local checks use the best observed latency as a regression floor; statistically meaningful runs of 20 or more use p95. Both receive 25% baseline headroom plus a 25 ms scheduler/filesystem noise margin. Reports always retain min/p50/p95, and product-target status always uses p95. This lets a busy workstation detect deterministic code slowdowns without pretending that three samples produce a meaningful p95 or hiding the real tail-latency target.
+The committed regression budgets in [`scripts/bench/scale-budgets.json`](../scripts/bench/scale-budgets.json) protect the current baseline while the product targets stay fixed. Baseline refreshes use the Node major pinned by release and primary CI workflows (currently Node 24); newer supported runtimes remain compatibility targets, but their startup and memory characteristics must not silently rewrite the release baseline. Short local checks use the best observed latency as a regression floor; statistically meaningful runs of 20 or more use p95. Both receive 25% baseline headroom plus a 25 ms scheduler/filesystem noise margin. Reports always retain min/p50/p95, and product-target status always uses p95. This lets a busy workstation detect deterministic code slowdowns without pretending that three samples produce a meaningful p95 or hiding the real tail-latency target.
 
 ## Reproducible fixtures
 
@@ -92,7 +92,10 @@ probe off and performs no query on the create path; advisory/strict modes reuse
 one dependency-light SDK scorer with the package-owned dedupe audit. Mutation
 history events use a separate rebuildable ordered SQLite projection so
 `pm events --since <cursor>` catch-up cost follows new history rows instead of
-workspace size. See [SDK Context Coordination](SDK_CONTEXT_COORDINATION.md).
+workspace size. Its v5 schema also indexes the declared substantive-versus-
+maintenance event class, allowing context recency to fetch only the latest
+substantive row per requested stream instead of folding complete histories on
+each read. See [SDK Context Coordination](SDK_CONTEXT_COORDINATION.md).
 
 SDK hosts that commit authoritative item documents outside the stock mutation
 commands use `acquireItemMetadataDerivedIndexLock` and
@@ -127,7 +130,7 @@ To refresh a baseline after an intentional, measured improvement:
 pnpm benchmark:scale --items ci --iterations 5 --transport both --update --headroom 1.25
 ```
 
-Review the report and budget diff together. Never update a budget merely to silence a regression.
+Review the report and budget diff together. Before a refresh, compare the delivery head with its exact base commit using the same runtime, fixture shape, and transport set; retain that evidence on the owning PM item. Never update a budget merely to silence a regression.
 
 ## Startup and observability
 

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-oahhyc](../.agents/pm/issues/pm-oahhyc.toon), [pm-q4isdq](../.agents/pm/issues/pm-q4isdq.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon), and [pm-xam9bt](../.agents/pm/issues/pm-xam9bt.toon).
+Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-wv47pf](../.agents/pm/issues/pm-wv47pf.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-oahhyc](../.agents/pm/issues/pm-oahhyc.toon), [pm-q4isdq](../.agents/pm/issues/pm-q4isdq.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon), and [pm-xam9bt](../.agents/pm/issues/pm-xam9bt.toon).
 
 ## Agent Quick Context
 
@@ -153,6 +153,14 @@ pm contracts --full --json
 
 Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed option provenance, deterministic estimated token count, string/row compaction signals, and budget outcome. When canonical controls are present, `canonical_options_used` records spellings such as `--output-include`; the optional field is omitted when no canonical control was supplied so minimum-budget session receipts remain compact. `legacy_aliases_used` and `migration_hints` record only compatibility flags the caller actually supplied. A command-local flag synthesized internally to execute a canonical projection mode is therefore never misreported as deprecated syntax. When both spellings are supplied, both provenance arrays report that mixed invocation. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
 
+For `context` and `next`, that final projection is also the usage-feedback
+delivery boundary. The SDK carries a JSON-invisible serve receipt through
+intent and universal output projection, then appends the final omitted decision
+and exact emitted item ids. An infeasible output budget records zero delivered
+rows; it can never leave the packer's earlier inclusions marked as served.
+`PmClient` finalizes the receipt before resolving, while the CLI finalizes it
+from the exact active result passed to telemetry and after-command hooks.
+
 When rows are dropped to satisfy a ceiling, the result also carries `output_budget_truncation`, naming the binding budget and its source, any explicitly requested dimension the budget overrode, every compacted collection path, and executable CLI/SDK/MCP recovery options — a default ceiling can override an explicit `--output-limit unbounded`, and that override is reported rather than silent. If a producer supplied an opaque item-page cursor, compaction rebases it to the last row actually returned and reports `continuation_cursor_rebased: true`; following the cursor therefore cannot skip rows removed from the middle of a producer page. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result, a compact `{ outputBudget: "unbounded" }` recovery object, and `omitted_result_estimated_tokens`, the last useful-result estimate before omission; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
 
 Cursor recovery carries the opaque value once in `recovery.cursor` and declares

package/docs/SDK.md

@@ -1773,14 +1773,17 @@ For persistent derived signals, use `ContextSignalStore` with a caller-owned
 `ContextSignalStoreAdapter`, or use `JsonFileContextSignalStoreAdapter` for a
 same-directory atomic JSON snapshot. Each snapshot carries both a
 `format_version` and `signal_set_version`, the authoritative history or index
-`source_cursor`, the stable caller clock, and whether its items came from the
-`derived_index` or `scan_fallback` path. Item rows are deterministic and sorted;
-the snapshot never replaces item or history data.
-
-`readOrRebuild(items, options)` reuses a snapshot only when the cursor and
-complete item-id set match. Missing, stale, version-incompatible, or corrupt
-state is rebuilt from the authoritative items and atomically replaced. The
-result reports `cache_status` and non-fatal `context_signal_store_stale`,
+`source_cursor`, a deterministic `recency_evidence_fingerprint`, the stable
+caller clock, and whether its items came from the `derived_index` or
+`scan_fallback` path. Item rows are deterministic and sorted; the snapshot never
+replaces item or history data.
+
+`readOrRebuild(items, options)` reuses a snapshot only when its format and
+signal-set metadata are supported, its item source matches, and its cursor,
+complete item-id set, and substantive recency-evidence fingerprint match.
+Missing, stale, version-incompatible, or corrupt state is rebuilt from the
+authoritative items and atomically replaced. The result reports `cache_status`
+and non-fatal `context_signal_store_stale`,
 `context_signal_store_invalid`, or `context_signal_store_write_failed`
 warnings. A write failure still serves the in-memory rebuilt candidates because
 the snapshot is derived, never authoritative. Optional maps for activity density,

package/docs/SDK_CONTEXT.md

@@ -31,6 +31,13 @@ stale, or unwritable snapshots return a stable warning, its meaning, an
 executable recovery command, and the expected effect. Re-running `pm context`
 confirms a successful rebuild as fresh.
 
+Recency uses the public `classifyHistoryEvent()` contract and the most recent
+substantive immutable event, with release-cohort and `created_at` fallbacks.
+Explained ranking carries the selected coordinate, operation, and class.
+`recordContextUsageServing()` plus `recordContextUsageDelivery()` expose the
+same two-phase feedback boundary used by CLI and `PmClient`, so custom hosts can
+correlate propensity rows with the exact result delivered after output budgets.
+
 See [Context relevance and packing](CONTEXT_RELEVANCE.md) for signal and token
 budgets, and [context coordination](SDK_CONTEXT_COORDINATION.md) for cursored
 events and duplicate governance.

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -4,12 +4,12 @@ Tracker: `pm-f05lsg`.
 
 Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.
 
-- Catalog error codes: 355
+- Catalog error codes: 356
 - Executable error codes: 19
 - Executable-code ratchet floor: 18
 - Required executable canonical codes: `bulk_ids_input_empty`, `bulk_ids_input_missing_path`, `bulk_ids_input_unreadable`, `invalid_argument_value`, `manifest_unknown_key`, `missing_lifecycle_target`, `missing_required_argument`, `no_version_bounds_declared`, `projection_options_mutually_exclusive`, `tracker_not_initialized`, `tracker_root_missing`, `tracker_root_not_directory`, `tracker_root_unreadable`, `unknown_context_intent`, `unknown_field_projection`, `unknown_option`, `unknown_subcommand`
-- Uncovered error codes: 336
-- Coverage fraction: 0.053521
+- Uncovered error codes: 337
+- Coverage fraction: 0.053371
 - Closed-domain probes: 19
 - Grammar probes: 94
 
@@ -120,6 +120,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `history_merge_conflict_markers_detected` | `merge_conflict_markers_detected` | uncovered | none | 0 |
 | `history_stream_over_compact_threshold` | `history_stream_over_compact_threshold` | uncovered | none | 0 |
 | `history_target_out_of_range` | `history_target_out_of_range` | uncovered | none | 0 |
+| `history_timestamp_invalid` | `history_timestamp_invalid` | uncovered | none | 0 |
 | `history_unknown_author_events` | `history_unknown_author_events` | uncovered | none | 0 |
 | `host_environment_capacity_fault` | `host_environment_capacity_fault` | uncovered | none | 0 |
 | `host_environment_operation_invalid` | `host_environment_operation_invalid` | uncovered | none | 0 |

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.9.2"
+    "version": "2026.9.3"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.9.2",
+      "version": "2026.9.3",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -206,7 +206,7 @@
     "node": ">=22.18.0"
   },
   "dependencies": {
-    "@sentry/node": "10.72.0",
+    "@sentry/node": "10.73.0",
     "@toon-format/toon": "^4.1.1",
     "@types/node": ">=22",
     "commander": "^15.0.0",
@@ -230,10 +230,10 @@
     "eslint-plugin-unicorn": "74.0.0",
     "fast-check": "^4.9.0",
     "greptile": "^3.4.2",
-    "jscpd": "^5.0.16",
+    "jscpd": "^5.1.1",
     "tsx": "^4.23.13",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.68.0",
+    "typescript-eslint": "^8.69.0",
     "vitest": "^4.1.11"
   }
 }

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-vcs-sdk-exemplar",
-  "version": "2026.9.2",
+  "version": "2026.9.3",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",