@unbrained/pm-cli 2026.9.1 → 2026.9.3

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_RECOVERY_PRIMITIVES.md

@@ -1,6 +1,6 @@
 # Context Integrity and Recovery Primitives
 
-Tracker: [pm-hu92i3](../.agents/pm/issues/pm-hu92i3.toon), [pm-nc94mk](../.agents/pm/issues/pm-nc94mk.toon), [pm-xrjy8o](../.agents/pm/issues/pm-xrjy8o.toon), [pm-f60039](../.agents/pm/issues/pm-f60039.toon), [pm-2qahia](../.agents/pm/issues/pm-2qahia.toon), [pm-z1z96w](../.agents/pm/issues/pm-z1z96w.toon), [pm-yhle2e](../.agents/pm/issues/pm-yhle2e.toon), [pm-t7wl00](../.agents/pm/issues/pm-t7wl00.toon), [pm-hiqlkh](../.agents/pm/issues/pm-hiqlkh.toon), [pm-ntnv4k](../.agents/pm/issues/pm-ntnv4k.toon), [pm-sxg7wl](../.agents/pm/issues/pm-sxg7wl.toon), [pm-xspd](../.agents/pm/chores/pm-xspd.toon)
+Tracker: [pm-dn8rwl](../.agents/pm/issues/pm-dn8rwl.toon), [pm-r97901](../.agents/pm/issues/pm-r97901.toon), [pm-hu92i3](../.agents/pm/issues/pm-hu92i3.toon), [pm-nc94mk](../.agents/pm/issues/pm-nc94mk.toon), [pm-xrjy8o](../.agents/pm/issues/pm-xrjy8o.toon), [pm-f60039](../.agents/pm/issues/pm-f60039.toon), [pm-2qahia](../.agents/pm/issues/pm-2qahia.toon), [pm-z1z96w](../.agents/pm/issues/pm-z1z96w.toon), [pm-yhle2e](../.agents/pm/issues/pm-yhle2e.toon), [pm-t7wl00](../.agents/pm/issues/pm-t7wl00.toon), [pm-hiqlkh](../.agents/pm/issues/pm-hiqlkh.toon), [pm-ntnv4k](../.agents/pm/issues/pm-ntnv4k.toon), [pm-sxg7wl](../.agents/pm/issues/pm-sxg7wl.toon), [pm-xspd](../.agents/pm/chores/pm-xspd.toon)
 
 `project management = context management`: a successful command is useful only when the context it records and later returns is truthful, lossless, and actionable. These SDK-owned primitives are shared by the CLI and package integrations.
 
@@ -59,7 +59,16 @@ history.
 
 Health keeps the metadata-only cache path for clean history streams. A cached hash mismatch, chain mismatch, or writer-version skew is only a candidate: health rereads canonical item sources and verifies stream content hashes before reporting corruption. The `history_drift` details expose `cache_confirmation` candidate, confirmed, and resolved-false-positive item sets, while `cache_hit_verification: metadata_then_content_hash` identifies the authoritative fallback. Drift-cache envelopes carry both their schema version and the current item-hash capability, so changing legacy canonicalization invalidates prior verdicts and a runtime with incompatible hash semantics rebuilds the cache instead of trusting it.
 
-Merge reconciliation may consume a durable hash-only receipt without `--force` only when its canonical item path, complete declared-field set, and every merged-value hash exactly match the current item snapshot. Raw discarded values remain clone-local. Any incomplete or mismatched proof fails closed. SDK gates use `inspectMergeReceiptEvidence` or `runMergeReceiptEvidenceReport` to retain the distinction between no evidence, rejected evidence, and clone-local evidence whose Git directory could not be resolved; `clone_local_evidence_resolved=false` makes the loss-aware report incomplete. The list-only and legacy report compatibility projections intentionally return valid receipts only. Diverged history unions also fail closed when deterministic suffix ordering would make any patch operation inapplicable, instead of publishing a rehashed stream with a skipped branch effect.
+Merge reconciliation may consume a durable hash-only receipt without `--force` only when its canonical item path, complete declared-field set, and every merged-value hash exactly match the current item snapshot. Raw discarded values remain clone-local. Any incomplete or mismatched proof fails closed. SDK gates use `inspectMergeReceiptEvidence` or `runMergeReceiptEvidenceReport` to retain the distinction between no evidence, rejected evidence, and clone-local evidence whose Git directory could not be resolved; `clone_local_evidence_resolved=false` makes the loss-aware report incomplete. Rejected evidence carries bounded privacy-safe source, reason, and receipt-id-or-hash locators, while the exact count and truncation receipt preserve completeness under an agent token budget. Cross-platform ancestor inspection distinguishes an absent receipt store from an unreadable or non-directory root. The list-only and legacy report compatibility projections intentionally return valid receipts only. Diverged history unions also fail closed when deterministic suffix ordering would make any patch operation inapplicable, instead of publishing a rehashed stream with a skipped branch effect.
+
+History receipt summaries are durable references, not cleanup hints. Health
+checks each `context.merge.receipts[].receipt_id` against valid pending and
+reconciled authoritative evidence. A missing reference is returned with its
+item id and one-based history line; unsafe identifiers are SHA-256 locators
+rather than echoed content. Detail is capped at 100 while the exact count and a
+truncation receipt preserve loss awareness. Recovery means restoring the named
+receipt from an authoritative clone or backup. Rewriting append-only history or
+deleting sibling evidence is never an automatic remediation.
 
 ## Strict-create recovery
 

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/MERGE_SAFETY.md

@@ -105,8 +105,22 @@ whose candidates were all rejected. Gates and diagnostic integrations should
 use `inspectMergeReceiptEvidence`, whose `invalid_evidence_count` preserves
 that distinction without returning malformed contents.
 `runMergeReceiptEvidenceReport` and `pm merge report --json` expose the same
-loss-aware contract through `complete`, `invalid_evidence_count`, and
-`clone_local_evidence_resolved`; the CLI
+loss-aware contract through `complete`, `invalid_evidence_count`, bounded
+`invalid_evidence[]`, `invalid_evidence_truncated`, and
+`clone_local_evidence_resolved`. Each rejected candidate reports a stable
+reason plus its `clone_local`, `durable`, or copy-consistency source. A safe
+receipt filename is returned as `receipt_id`; unsafe candidate names are
+represented only by `candidate_name_hash`, and malformed contents are never
+returned. The detail list is capped at 100 rows while the count remains exact,
+so automated gates stay token-bounded. Directory traversal distinguishes a
+truly absent store from a non-directory or unreadable ancestor on Windows and
+POSIX instead of treating platform-specific `ENOENT`/`ENOTDIR` spellings as
+equivalent. Full health also cross-checks the privacy-safe receipt summaries in
+append-only history against valid pending and reconciled evidence. Missing
+evidence emits `merge_receipt_history_reference_missing:<n>` with bounded item,
+history-line, and receipt-id-or-hash coordinates. Its remediation enumerates
+the exact references and directs recovery from an authoritative clone or
+backup; it never recommends deleting receipts or rewriting history. The CLI
 exits nonzero when evidence is incomplete, even when the valid-receipt count is
 zero. Current SDK implementations always emit the new field, while its optional
 type preserves structural compatibility for existing typed adapters and test

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: 354
+- 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: 335
-- Coverage fraction: 0.053672
+- 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 |
@@ -186,6 +187,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `merge_decisions_unreviewed` | `merge_decisions_unreviewed` | uncovered | none | 0 |
 | `merge_git_config_unwritable` | `merge_git_config_unwritable` | uncovered | none | 0 |
 | `merge_receipt_evidence_invalid` | `merge_receipt_evidence_invalid` | uncovered | none | 0 |
+| `merge_receipt_history_reference_missing` | `merge_receipt_history_reference_missing` | uncovered | none | 0 |
 | `merge_receipts_pending` | `merge_receipts_pending` | uncovered | none | 0 |
 | `merge_reconcile_receipt_evidence_untrusted` | `merge_reconcile_receipt_evidence_untrusted` | uncovered | none | 0 |
 | `merge_root_not_found` | `merge_root_not_found` | 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.1"
+    "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.1",
+      "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.",

package/plugins/pm-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pm-claude",
   "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
-  "version": "2026.9.1",
+  "version": "2026.9.3",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

package/plugins/pm-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-codex",
-  "version": "2026.9.1",
+  "version": "2026.9.3",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",