@unbrained/pm-cli 2026.8.10 → 2026.8.12

package/dist/sdk/query/get.js

@@ -4,7 +4,7 @@
  * Implements the SDK-owned item query shared by every surface.
  */
 
-!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]="f68f4074-51ba-5065-8cca-fe16acd48927")}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]="89176e36-40ea-5ec2-b291-d1cf042c4140")}catch(e){}}();
 import { pathExists, getActiveExtensionRegistrations, toItemRecord, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, TYPE_TO_FOLDER, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, getHistoryPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { readHistoryEntries } from "../history-read.js";
 import { recordContextUsageTouches } from "../context-usage.js";
@@ -13,6 +13,7 @@ import { buildItemSchedule, } from "../item-schedule.js";
 import { getItemAt } from "../history-read.js";
 import { parseIntegerLimit } from "./parsers.js";
 import { runList } from "./list.js";
+import { registerOutputMaterialFieldGroups } from "../output-projection.js";
 const GET_DEPTH_VALUES = ["brief", "standard", "deep"];
 const AUTOMATIC_CHILD_ROLLUP_TYPES = new Set([
     "epic",
@@ -38,6 +39,21 @@ function itemCollectionCounts(item) {
     ]));
     return lengths;
 }
+function itemMaterialFieldGroups(item, body) {
+    const collectionCounts = itemCollectionCounts(item);
+    return [
+        ...(body.length > 0 ? ["body"] : []),
+        ...Object.entries(collectionCounts).flatMap(([name, count]) => count > 0 ? [name] : []),
+        ...(collectionCounts.files + collectionCounts.tests + collectionCounts.docs > 0
+            ? ["linked"]
+            : []),
+        "children",
+        ...(typeof item.assignee === "string" && item.assignee.trim().length > 0
+            ? ["claim_state"]
+            : []),
+        ...(buildItemSchedule(item) ? ["schedule"] : []),
+    ];
+}
 /** Decide whether a normal read should pay for a workspace-wide child projection. */
 function shouldAutoIncludeGetChildren(itemType) {
     const normalizedType = itemType.trim().toLowerCase();
@@ -414,6 +430,7 @@ export async function runGet(id, global, options = {}) {
             // Derived usage feedback must never make the source-of-truth read fail.
         }
     }
+    registerOutputMaterialFieldGroups(result, itemMaterialFieldGroups(context.metadata, context.body));
     return result;
 }
 /** Public contract for test-only get command policy helpers. */
@@ -421,4 +438,4 @@ export const _testOnlyGetCommand = {
     shouldAutoIncludeGetChildren,
 };
 //# sourceMappingURL=get.js.map
-//# debugId=f68f4074-51ba-5065-8cca-fe16acd48927
+//# debugId=89176e36-40ea-5ec2-b291-d1cf042c4140

package/dist/sdk/read-output-contracts.d.ts

@@ -19,6 +19,8 @@ export interface PmReadOutputOptions {
     outputFormat?: "json" | "toon";
     /** Caller-carried cross-call budget and served-fact state. */
     outputSession?: string | PmReadOutputSessionState;
+    /** Include row selector and encoding discovery metadata. */
+    outputRowContract?: boolean;
 }
 /** Compatibility spelling retained for a command-specific output control. */
 export interface PmReadOutputLegacyAlias {
@@ -130,7 +132,7 @@ export type PmReadOutputResultFor<Result, Options> = "outputBudget" extends keyo
 /** Canonical CLI flags that opt a read invocation into universal output shaping. */
 export declare const PM_READ_OUTPUT_OPTION_FLAGS: readonly string[];
 /** Canonical control that composes the four per-call dimensions across reads. */
-export declare const PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS: readonly ["--output-session"];
+export declare const PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS: readonly ["--output-session", "--output-row-contract"];
 /** Universal output contract for every built-in read surface. */
 export declare const PM_READ_OUTPUT_SURFACE_CONTRACTS: readonly PmReadOutputSurfaceContract[];
 /** Resolve a command or list/context alias to its canonical read-output surface. */
@@ -139,6 +141,8 @@ export declare function resolveReadOutputSurface(command: string): PmReadOutputS
 export declare function validateReadOutputOptions(command: string, options: Record<string, unknown>): void;
 /** Resolve canonical and compatibility controls into the universal dimension set. */
 export declare function resolveReadOutputDimensions(command: string, options: Record<string, unknown>): PmResolvedReadOutputDimensions | undefined;
+/** Recompute read and optional session receipts after a final envelope projection. */
+export declare function stabilizeReadOutputReceiptEstimates(result: Record<string, unknown>, options: Record<string, unknown>): Record<string, unknown>;
 /** Apply universal field, row, and token bounds and attach an exact receipt. */
 export declare function applyReadOutputDimensions<Result extends Record<string, unknown>>(command: string, options: Record<string, unknown>, result: Result): PmReadOutputResult<Result>;
 /** Narrow a universal read result to its budget-omission branch. */

package/dist/sdk/read-output-contracts.js

@@ -5,7 +5,7 @@
  * surface without coupling package authors to command-specific option names.
  */
 
-!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]="819ac44d-0add-581c-90e8-ac6e8247b04b")}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]="0ab0c72c-cac0-5670-93d1-7a446f8a2301")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { compactReadOutputToBudget, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
@@ -58,6 +58,7 @@ export const PM_READ_OUTPUT_OPTION_FLAGS = Object.freeze(PM_READ_OUTPUT_DIMENSIO
 /** Canonical control that composes the four per-call dimensions across reads. */
 export const PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS = Object.freeze([
     "--output-session",
+    "--output-row-contract",
 ]);
 const LEGACY_FLAGS_BY_COMMAND = {
     list: {
@@ -216,6 +217,8 @@ const CANONICAL_OPTION_KEYS = [
     "output_format",
     "outputSession",
     "output_session",
+    "outputRowContract",
+    "output_row_contract",
 ];
 const HYBRID_READ_MUTATION_KEYS = {
     comments: ["add", "body", "stdin", "file", "edit", "delete"],
@@ -580,6 +583,18 @@ function attachReadOutputSessionContracts(result, state, receipt) {
     }
     return withSession;
 }
+/** Recompute read and optional session receipts after a final envelope projection. */
+export function stabilizeReadOutputReceiptEstimates(result, options) {
+    if (!isRecord(result.read_output))
+        return result;
+    const receipt = result.read_output;
+    const session = parseReadOutputSession(options.outputSession ?? options.output_session);
+    if (session === undefined) {
+        updateReadOutputReceiptEstimate(result, receipt);
+        return result;
+    }
+    return attachReadOutputSessionContracts(result, session, receipt);
+}
 /** Apply field, amount, and repeat projections to every declared row path. */
 function projectReadOutputRows(result, resolved, session) {
     let projected = { ...result };
@@ -695,4 +710,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=819ac44d-0add-581c-90e8-ac6e8247b04b
+//# debugId=0ab0c72c-cac0-5670-93d1-7a446f8a2301

package/dist/sdk/read-output-session.d.ts

@@ -46,6 +46,8 @@ export interface PmReadOutputSessionReceipt {
     seen_before_count: number;
     /** Number of newly delivered item facts retained in this envelope. */
     new_item_count: number;
+    /** Newly delivered identities omitted from next_state after its capacity filled. */
+    seen_item_overflow_count?: number;
     /** Number of repeated item rows replaced by references. */
     suppressed_repeat_count: number;
     /** Stable reference syntax used by suppressed rows. */

package/dist/sdk/read-output-session.js

@@ -5,7 +5,7 @@
  * budgets and resolvable references to item facts served by earlier reads.
  */
 
-!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]="04ad0d11-1fb7-5eb4-8ff0-d81a7090c4ff")}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]="642f6dec-c0b2-5377-a401-dfa4f8ef6a2a")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { mapReadOutputRows, readOutputRowCollections, } from "./read-output-rows.js";
@@ -141,9 +141,13 @@ export function applyReadOutputSessionReferences(result, state) {
 /** Attach a fixed-point session receipt and return the exact charged tokens. */
 export function attachReadOutputSessionReceipt(result, state) {
     const { deliveredIds, suppressedRepeatCount } = summarizeReadOutputSessionRows(result);
-    const nextSeen = [
-        ...new Set([...state.seen_item_ids, ...deliveredIds]),
-    ].sort();
+    const alreadySeen = new Set(state.seen_item_ids);
+    const newlySeen = [...deliveredIds]
+        .filter((id) => !alreadySeen.has(id))
+        .sort();
+    const retainedNewIds = newlySeen.slice(0, PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS - state.seen_item_ids.length);
+    const nextSeen = [...state.seen_item_ids, ...retainedNewIds].sort();
+    const seenItemOverflowCount = newlySeen.length - retainedNewIds.length;
     const receipt = {
         contract_version: 1,
         id: state.id,
@@ -158,6 +162,9 @@ export function attachReadOutputSessionReceipt(result, state) {
         exhausted: false,
         seen_before_count: state.seen_item_ids.length,
         new_item_count: deliveredIds.size,
+        ...(seenItemOverflowCount === 0
+            ? {}
+            : { seen_item_overflow_count: seenItemOverflowCount }),
         suppressed_repeat_count: suppressedRepeatCount,
         reference_format: "session:<session-id>:<item-id>",
         restore_reference_with: "pm get <item-id> --brief",
@@ -197,4 +204,4 @@ export function readOutputSessionRemainingTokens(state) {
     return Math.max(0, state.token_budget - state.spent_tokens);
 }
 //# sourceMappingURL=read-output-session.js.map
-//# debugId=04ad0d11-1fb7-5eb4-8ff0-d81a7090c4ff
+//# debugId=642f6dec-c0b2-5377-a401-dfa4f8ef6a2a

package/dist/sdk/runtime-extended-actions.js

@@ -1,7 +1,8 @@
 
-!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]="f8cd69db-ec70-560f-a8c2-2d8d4be75459")}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]="37ac2a74-f150-5b9d-96d6-d9cc441215be")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
+import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 import { resolvePmRoot } from "../core/store/paths.js";
 import { runEval } from "./eval.js";
 import { runMergeDriver } from "./merge/driver.js";
@@ -92,14 +93,24 @@ export function runRuntimeMergeAction(context) {
             prefer: readRuntimeString(input, "prefer"),
         }, context.global);
     }
-    throw new PmCliError(`Unknown merge subcommand "${subcommand}".`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
+    throw createUnknownSubcommandError({
+        command_path: "merge",
+        token: subcommand,
+        allowed: ["install", "reconcile", "report", "driver"],
+        display_name: "merge",
+    });
 }
 /** Dispatch guarded workspace snapshot operations. */
 export function runRuntimeWorkspaceAction(context) {
     const input = mergedInput(context);
     const subcommand = requiredString(input, "subcommand");
     if (subcommand !== "snapshot") {
-        throw new PmCliError(`Unknown workspace subcommand "${subcommand}".`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
+        throw createUnknownSubcommandError({
+            command_path: "workspace",
+            token: subcommand,
+            allowed: ["snapshot"],
+            display_name: "workspace",
+        });
     }
     const snapshotAction = readRuntimeString(input, "snapshotAction") ??
         requiredString(input, "snapshot_action");
@@ -129,7 +140,13 @@ export function runRuntimeWorkspaceAction(context) {
                 lockWaitMs: parseRuntimeInteger(input.lockWaitMs, "lockWaitMs"),
             });
     }
-    throw new PmCliError(`Unknown workspace snapshot action "${snapshotAction}".`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
+    throw createUnknownSubcommandError({
+        command_path: "workspace snapshot",
+        token: snapshotAction,
+        allowed: ["create", "list", "inspect", "restore", "delete"],
+        display_name: "workspace snapshot",
+        token_kind: "action",
+    });
 }
 /** Dispatch meeting, event, and reminder shortcuts through SDK-owned creation. */
 export function runRuntimeSchedulingAction(context) {
@@ -144,4 +161,4 @@ export function runRuntimeSchedulingAction(context) {
     return runRemind(title, input, context.global);
 }
 //# sourceMappingURL=runtime-extended-actions.js.map
-//# debugId=f8cd69db-ec70-560f-a8c2-2d8d4be75459
+//# debugId=37ac2a74-f150-5b9d-96d6-d9cc441215be

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

@@ -8,6 +8,7 @@
  */
 export { type MutationCheckpointItem, createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
+export { createUnknownSubcommandError, type UnknownSubcommandErrorOptions, } from "./agent/subcommand-recovery.js";
 export { type ActiveExtensionHookContext, type ExtensionCommandRegistry, type ExtensionDiscoveryResult, type ExtensionHookRegistry, type ExtensionParserRegistry, type ExtensionPreflightRegistry, type ExtensionRegistrationRegistry, type ExtensionRendererRegistry, type ExtensionServiceRegistry, type FlagDefinition, type PreflightRuntimeDecision, type RegisteredExtensionCommandDefinition, type RegisteredExtensionFlagDefinitions, type RegisteredExtensionSchemaMigrationDefinition, activateExtensions, clearActiveExtensionHooks, consumeAfterCommandAffectedItems, createCoreCommandHookContext, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, resetActiveExtensionRuntimeState, runActiveCommandHandler, runActiveBeforeMutationHooks, runActiveOnIndexHooks, runActiveOnReadHooks, runActiveOnWriteHooks, runActiveParserOverride, runActivePreflightOverride, runActiveServiceOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandContext, setActiveCommandResult, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, } from "../core/extensions/index.js";
 export { applyRegisteredItemFieldDefaultsAndValidation, collectRegisteredItemFieldNames, parseRegisteredItemFieldAssignments, } from "../core/extensions/item-fields.js";
 export { resolveExtensionRoots } from "../core/extensions/loader.js";
@@ -15,9 +16,10 @@ export { resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, }
 export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
 export { type HistoryDiffValueEntry, computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
-export { appendHistoryEntry, createHistoryEntry, hashDocument, hashEmptyDocument, } from "../core/history/history.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 { readHistoryEntries } from "../core/history/read.js";
 export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
-export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
+export { normalizeReplayPatchOps, 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";
@@ -70,7 +72,7 @@ export { splitCommaList } from "../core/shared/split-comma-list.js";
 export { compareTimestampStrings, nowIso, resolveIsoOrRelative, } from "../core/shared/time.js";
 export { migrateItemFilesToFormat } from "../core/store/item-format-migration.js";
 export { type CachedDocumentCandidate, listAllDocumentCandidatesCached, } from "../core/store/item-metadata-cache.js";
-export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
+export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
 export { isTerminalPlanMode, shouldCompletePlanOnClose, } from "../core/item/plan-lifecycle.js";
 export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 export { persistSelectedItemFormat, readSettings, readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";

package/dist/sdk/runtime-primitives.js

@@ -7,9 +7,10 @@
  * 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]="17358714-bb54-58e5-bba0-61bfd1323ec2")}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]="78779372-1987-54d0-9ae4-775b52641a26")}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";
 export { activateExtensions, clearActiveExtensionHooks, consumeAfterCommandAffectedItems, createCoreCommandHookContext, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, resetActiveExtensionRuntimeState, runActiveCommandHandler, runActiveBeforeMutationHooks, runActiveOnIndexHooks, runActiveOnReadHooks, runActiveOnWriteHooks, runActiveParserOverride, runActivePreflightOverride, runActiveServiceOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandContext, setActiveCommandResult, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, } from "../core/extensions/index.js";
 export { applyRegisteredItemFieldDefaultsAndValidation, collectRegisteredItemFieldNames, parseRegisteredItemFieldAssignments, } from "../core/extensions/item-fields.js";
 export { resolveExtensionRoots } from "../core/extensions/loader.js";
@@ -17,9 +18,10 @@ export { resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, }
 export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
 export { computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
-export { appendHistoryEntry, createHistoryEntry, hashDocument, hashEmptyDocument, } from "../core/history/history.js";
+export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, } from "../core/history/history.js";
+export { readHistoryEntries } from "../core/history/read.js";
 export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
-export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
+export { normalizeReplayPatchOps, 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";
@@ -71,7 +73,7 @@ export { splitCommaList } from "../core/shared/split-comma-list.js";
 export { compareTimestampStrings, nowIso, resolveIsoOrRelative, } from "../core/shared/time.js";
 export { migrateItemFilesToFormat } from "../core/store/item-format-migration.js";
 export { listAllDocumentCandidatesCached, } from "../core/store/item-metadata-cache.js";
-export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
+export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
 export { isTerminalPlanMode, shouldCompletePlanOnClose, } from "../core/item/plan-lifecycle.js";
 export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 export { persistSelectedItemFormat, readSettings, readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";
@@ -79,4 +81,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=17358714-bb54-58e5-bba0-61bfd1323ec2
+//# debugId=78779372-1987-54d0-9ae4-775b52641a26

package/dist/sdk/runtime-stats-options.js

@@ -1,9 +1,10 @@
 
-!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]="dbabff08-1bb7-539b-b1c1-c10584aa0a67")}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]="0e63298a-d2d7-5217-af50-a206348b4cd4")}catch(e){}}();
 import { readRuntimeString, readRuntimeStringArray } from "./runtime-input.js";
 /** Convert a flat runtime option bag into the canonical typed stats payload. */
 export function statsCommandOptionsFromRuntime(options) {
     return {
+        includeEmpty: options.includeEmpty === true,
         storage: options.storage === true,
         metadataCoverage: options.metadataCoverage === true,
         fieldUtilization: options.fieldUtilization === true,
@@ -35,4 +36,4 @@ export function statsCommandOptionsFromRuntime(options) {
     };
 }
 //# sourceMappingURL=runtime-stats-options.js.map
-//# debugId=dbabff08-1bb7-539b-b1c1-c10584aa0a67
+//# debugId=0e63298a-d2d7-5217-af50-a206348b4cd4

package/dist/sdk/runtime.d.ts

@@ -15,6 +15,8 @@ export type { PmReadOutputSessionReceipt, PmReadOutputSessionState, } from "./re
 export type { PmContextIntentContract } from "./context-intent-contracts.js";
 export type { PmErrorCodeContract } from "./error-code-catalog.js";
 export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";
+import { type AssuranceActionInput, type AssuranceActionResult } from "./governance/assurance-action.js";
+export type * from "./governance/assurance-action-contracts.js";
 import { type AggregateOptions, type AggregateResult } from "./query/aggregate.js";
 import { type UpgradeCommandOptions, type UpgradeResult } from "./governance/upgrade.js";
 import { type CreateResult } from "./lifecycle/create.js";
@@ -235,6 +237,8 @@ export declare class PmClient {
     health<Options extends ReadOptions<RunHealthOptions> = RunHealthOptions>(options?: Options): ReadPromise<HealthResult, Options>;
     /** Run tracker cache/runtime garbage collection. */
     gc(options?: GcCommandOptions): Promise<GcResult>;
+    /** Declare, inspect, or evaluate a project assurance contract. */
+    assurance(input: AssuranceActionInput): Promise<AssuranceActionResult>;
     /** Redact sensitive values while preserving an audited, verified history chain. */
     historyRedact(id: string, options: HistoryRedactCommandOptions): Promise<HistoryRedactResult>;
     /** Repair and re-anchor one drifted history stream. */

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]="70ce3cab-35f0-508b-9348-2f8479495946")}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]="7c27b516-1714-5f2b-8304-98e8372280be")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -28,11 +28,13 @@ import { PM_TOOL_ACTIONS } from "./cli-contracts/enum-contracts.js";
 import { clearWorkspaceContractsCache, memoizeWorkspaceExtensionRegistrations, } from "./workspace-contracts-cache.js";
 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 { runWithDiscoveredContextIntentContracts, } from "./context-intent-runtime.js";
 import { validateReadOutputOptions, } from "./read-output-contracts.js";
 export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";
-import { runActivity } from "./query/activity.js";
+import { normalizeActivityProjectionOptions, runActivity, } from "./query/activity.js";
+import { runAssuranceDispatch } from "./governance/assurance-action.js";
 import { runAggregate, } from "./query/aggregate.js";
 import { runAppend } from "./lifecycle/append.js";
 import { runClaim, runClaimNext, runRelease } from "./lifecycle/claim.js";
@@ -63,7 +65,7 @@ import { runConfig } from "./config.js";
 import { runInit } from "./init.js";
 import { runRuntimeEvalAction, runRuntimeEventsAction, runRuntimeMergeAction, runRuntimeSchedulingAction, runRuntimeWorkspaceAction, } from "./runtime-extended-actions.js";
 import { acknowledgeUnknownAuthorHistoryEventsFromTransport, } from "./author-attribution.js";
-import { runProfileApply, runProfileLint, runProfileList, runProfileShow, } from "./profile.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 { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, 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";
@@ -71,6 +73,7 @@ import { runDeps } from "./dependencies.js";
 import { runDocs } from "./docs.js";
 import { runGraph, } from "./graph/run.js";
 import { runFiles, runFilesDiscover, runFilesLookup } from "./files.js";
+import { runtimeFilesLookupOptions } from "./traceability/runtime-files-lookup.js";
 import { runContracts, } from "./cli-contracts/runtime-contracts.js";
 import { runList } from "./query/list.js";
 import { runSearch, } from "./query/search.js";
@@ -81,7 +84,7 @@ import { runTelemetry } from "./telemetry.js";
 import { runTest } from "./test/execution.js";
 import { runTestAll } from "./test/batch.js";
 import { resolveStartTaskInProgressStatus } from "./start-task-status.js";
-import { runSchemaAddField, runSchemaAddStatus, runSchemaAddType, runSchemaApplyPreset, runSchemaInferTypes, runSchemaList, runSchemaListFields, runSchemaEvolutionMigration, runSchemaRemoveField, runSchemaRemoveStatus, runSchemaRemoveType, runSchemaShow, runSchemaShowField, runSchemaShowStatus, } from "./schema.js";
+import { SCHEMA_SUBCOMMANDS, runSchemaAddField, runSchemaAddStatus, runSchemaAddType, runSchemaApplyPreset, runSchemaInferTypes, runSchemaList, runSchemaListFields, runSchemaEvolutionMigration, runSchemaRemoveField, runSchemaRemoveStatus, runSchemaRemoveType, runSchemaShow, runSchemaShowField, runSchemaShowStatus, } from "./schema.js";
 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";
@@ -408,6 +411,10 @@ export class PmClient {
     gc(options = {}) {
         return this.runTyped("gc", { options });
     }
+    /** Declare, inspect, or evaluate a project assurance contract. */
+    assurance(input) {
+        return this.runTyped("assurance", { options: { ...input, subcommand: input.action } });
+    }
     /** Redact sensitive values while preserving an audited, verified history chain. */
     historyRedact(id, options) {
         return this.runTyped("history-redact", { id, options });
@@ -1401,25 +1408,20 @@ function runMcpCommentsAction(ctx) {
         commentOptions.delete === undefined;
     if (isListing) {
         commentOptions.includeMeta = true;
-        if (commentOptions.limit === undefined && commentOptions.fullHistory !== true) {
+        if (commentOptions.limit === undefined &&
+            commentOptions.fullHistory !== true) {
             commentOptions.limit = "20";
         }
     }
     return runComments(requireMcpItemId(ctx), commentOptions, ctx.global);
 }
+function runMcpFilesLookupAction(ctx, paths) {
+    return runFilesLookup(runtimeFilesLookupOptions(ctx.options, paths, parseMcpInteger), ctx.global);
+}
 function runMcpFilesAction(ctx) {
     const lookupPaths = readStringArray(ctx.options.lookupPath);
     if (lookupPaths && lookupPaths.length > 0) {
-        return runFilesLookup({
-            paths: lookupPaths,
-            scope: ctx.options.scope === "project" || ctx.options.scope === "global"
-                ? ctx.options.scope
-                : undefined,
-            limit: parseMcpInteger(ctx.options.limit, "files lookup limit"),
-            offset: parseMcpInteger(ctx.options.offset, "files lookup offset"),
-            noTruncate: ctx.options.noTruncate === true,
-            strictRead: ctx.options.strictRead === true,
-        }, ctx.global);
+        return runMcpFilesLookupAction(ctx, lookupPaths);
     }
     const fileId = requireMcpItemId(ctx);
     return ctx.options.discover === true
@@ -1454,12 +1456,8 @@ function runMcpConfigAction(ctx) {
         "project", configAction, readString(ctx.args, "key") ?? readString(ctx.options, "key"), ctx.options, ctx.global, readString(ctx.args, "value") ?? readString(ctx.options, "value"));
 }
 function runMcpActivityAction(ctx) {
-    const activityOptions = { ...ctx.options };
-    if (activityOptions.compact === undefined) {
-        activityOptions.compact = activityOptions.full === true ? false : true;
-    }
-    delete activityOptions.full;
-    return runActivity(activityOptions, ctx.global);
+    const options = ctx.options;
+    return runActivity(normalizeActivityProjectionOptions(options), ctx.global);
 }
 function parseMcpIntegerPrefix(value, label) {
     if (typeof value === "number") {
@@ -1644,7 +1642,12 @@ function runMcpSchemaAction(ctx) {
         }
         return runMcpSchemaAddTypeAction(schema);
     }
-    throw new PmCliError(`Unknown pm schema subcommand "${schema.subcommand}". Allowed: add-type, remove-type, add-status, remove-status, add-field, remove-field, rename-type, rename-field, remap-status, list-fields, show-field, apply-preset, list, show, show-status`, 64);
+    throw createUnknownSubcommandError({
+        command_path: "schema",
+        token: schema.subcommand,
+        allowed: SCHEMA_SUBCOMMANDS,
+        exit_code: 64,
+    });
 }
 function runMcpProfileAction(ctx) {
     const subcommand = readString(ctx.args, "subcommand") ??
@@ -1663,7 +1666,12 @@ function runMcpProfileAction(ctx) {
     };
     const handler = getOwnHandler(handlers, normalizedSubcommand);
     if (!handler) {
-        throw new PmCliError(`Unknown pm profile subcommand "${subcommand}". Allowed: list, show, apply, lint`, 64);
+        throw createUnknownSubcommandError({
+            command_path: "profile",
+            token: subcommand,
+            allowed: PROFILE_SUBCOMMANDS,
+            exit_code: 64,
+        });
     }
     return handler();
 }
@@ -1813,6 +1821,7 @@ const SDK_ACTION_HANDLERS = {
         runUpdate: (id, options, global) => runUpdate(id, options, global),
     }),
     health: runMcpHealthAction,
+    assurance: (ctx) => runAssuranceDispatch(ctx.args, ctx.options, ctx.global),
     contracts: (ctx) => runContracts(ctx.options, ctx.global),
     config: runMcpConfigAction,
     activity: runMcpActivityAction,
@@ -1825,16 +1834,7 @@ const SDK_ACTION_HANDLERS = {
     deps: (ctx) => runDeps(requireMcpItemId(ctx), ctx.options, ctx.global),
     graph: runMcpGraphAction,
     "files-discover": (ctx) => runFilesDiscover(requireMcpItemId(ctx), ctx.options, ctx.global),
-    "files-lookup": (ctx) => runFilesLookup({
-        paths: readStringArray(ctx.options.paths),
-        scope: ctx.options.scope === "project" || ctx.options.scope === "global"
-            ? ctx.options.scope
-            : undefined,
-        limit: parseMcpInteger(ctx.options.limit, "files lookup limit"),
-        offset: parseMcpInteger(ctx.options.offset, "files lookup offset"),
-        noTruncate: ctx.options.noTruncate === true,
-        strictRead: ctx.options.strictRead === true,
-    }, ctx.global),
+    "files-lookup": (ctx) => runMcpFilesLookupAction(ctx, readStringArray(ctx.options.paths)),
     history: (ctx) => runHistory(requireMcpItemId(ctx), ctx.options, ctx.global),
     "history-redact": (ctx) => runHistoryRedact(requireMcpItemId(ctx), ctx.options, ctx.global),
     "history-repair": runMcpHistoryRepairAction,
@@ -1930,4 +1930,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=70ce3cab-35f0-508b-9348-2f8479495946
+//# debugId=7c27b516-1714-5f2b-8304-98e8372280be

package/dist/sdk/stats.d.ts

@@ -1,5 +1,5 @@
 import { type ContentFieldUtilizationReport } from "../core/governance/content-fields.js";
-import { type GroupedBreakdown, type MetadataCoverageReport } from "../core/governance/metadata-coverage.js";
+import { type CoverageItem, type GroupedBreakdown, type LifecycleClassifier, type MetadataCoverageReport } from "../core/governance/metadata-coverage.js";
 import { type HistoryStorageStats } from "../core/history/history-storage-stats.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { ItemStatus, ItemType } from "../types/index.js";
@@ -7,6 +7,8 @@ import { type ImprovementDirection, type ImprovementLedgerResult, type RecordImp
 import { type FleetAttributionAnalytics, type ProvenanceCoverageAnalytics } from "./history-analytics.js";
 /** Documents the stats command options payload exchanged by command, SDK, and package integrations. */
 export interface StatsCommandOptions {
+    /** Restore zero-count item-type and status buckets for schema-governance dashboards. */
+    includeEmpty?: boolean;
     /** Include aggregate per-stream history storage metrics (sizes, depth, oldest/newest). */
     storage?: boolean;
     /** Include metadata coverage percentages (AC, estimates, resolution, tags, parent) overall and by type. */
@@ -52,6 +54,29 @@ export interface StatsCommandOptions {
     /** Minimum close or explicit-value denominator required for rates. */
     minimumSample?: number;
 }
+/** Compact, tabular lifecycle row used by the default stats type distribution. */
+export interface StatsTypeLifecycleRow {
+    /** Item type represented by this row. */
+    type: string;
+    /** Total items of this type across every lifecycle bucket. */
+    total: number;
+    /** Items in the default open lifecycle bucket. */
+    open: number;
+    /** Items in active non-default lifecycle states. */
+    in_progress: number;
+    /** Items in blocked lifecycle states. */
+    blocked: number;
+    /** Items in draft lifecycle states. */
+    draft: number;
+    /** Items in completed lifecycle states. */
+    closed: number;
+    /** Items in canceled lifecycle states. */
+    canceled: number;
+    /** Items whose custom status is outside the recognized lifecycle buckets. */
+    other: number;
+}
+/** Screen-sized type distribution rendered as one canonical TOON table. */
+export type StatsTypeBreakdown = StatsTypeLifecycleRow[];
 /** Documents the stats result payload exchanged by command, SDK, and package integrations. */
 export interface StatsResult {
     /** Value that configures or reports totals for this contract. */
@@ -61,9 +86,11 @@ export interface StatsResult {
         history_entries: number;
     };
     /** Schema type that determines the shape and validation rules for this value. */
-    by_type: Record<ItemType, number>;
+    by_type: StatsTypeBreakdown;
     /** Item counts grouped by lifecycle status. */
-    by_status: Record<ItemStatus, number>;
+    by_status: Partial<Record<ItemStatus, number>>;
+    /** Total zero-count type and status buckets omitted from the default projection. */
+    omitted_zero_buckets: number;
     /** Present only with --metadata-coverage: per-field coverage overall and by type. */
     metadata_coverage?: MetadataCoverageReport;
     /** Present only with --by-assignee/--by-tag/--by-priority: lifecycle-bucketed group breakdowns. */
@@ -89,6 +116,11 @@ export interface StatsResult {
 }
 declare function zeroByType(itemTypes: string[]): Record<ItemType, number>;
 declare function zeroByStatus(statuses: string[]): Record<ItemStatus, number>;
+declare function projectStatsDistributions(items: readonly CoverageItem[], itemTypes: readonly string[], statuses: readonly string[], classifier: LifecycleClassifier, includeEmpty: boolean): {
+    byType: StatsTypeBreakdown;
+    byStatus: Partial<Record<ItemStatus, number>>;
+    omitted: number;
+};
 declare function countNonEmptyLines(raw: string): number;
 declare function readHistoryStreamContents(pmRoot: string): Promise<Array<{
     id: string;
@@ -100,6 +132,7 @@ export declare const _testOnly: {
     zeroByStatus: typeof zeroByStatus;
     countNonEmptyLines: typeof countNonEmptyLines;
     readHistoryStreamContents: typeof readHistoryStreamContents;
+    projectStatsDistributions: typeof projectStatsDistributions;
 };
 /** Implements run stats for the public runtime surface of this module. */
 export declare function runStats(global: GlobalOptions, options?: StatsCommandOptions): Promise<StatsResult>;