@unbrained/pm-cli 2026.8.13 → 2026.8.14

package/dist/sdk/graph/remediation.js

@@ -1,5 +1,5 @@
 
-!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]="9b8e22ad-6268-515d-994e-6b98a062ba93")}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]="1eb0e2cb-084a-5a54-b41c-29dfdd6d2f34")}catch(e){}}();
 import { findRedundantRelationshipEdges } from "./analytics.js";
 import { auditWorkspaceRelationshipGraph, collectDuplicateRelationshipEdgeGroups, formatDuplicateEdgeGroup, } from "./governance.js";
 /** Per-finding-code operation template applied to every sampled subject. */
@@ -29,6 +29,16 @@ const FINDING_STEP_TEMPLATES = {
         confidence: "high",
         rationale: "Terminal-only ordering cycles have no scheduling effect; repairing them would mutate closed history (changelog drag).",
     },
+    ordering_storage_contradiction: {
+        op: "remove",
+        confidence: "high",
+        rationale: "The structured ordering row asserts the opposite precedence from the same-target scalar blocker; remove that exact dependency row or replace both representations with one unambiguous edge.",
+    },
+    legacy_ordering_storage_contradiction: {
+        op: "remove",
+        confidence: "high",
+        rationale: "The terminal holder contains a proven contradictory structured ordering row; remove it in a dedicated changelog-safe batch while preserving the scalar blocker as history.",
+    },
     // duplicate_edge findings are expanded into per-stored-edge remove steps by
     // the planner itself (see stepsFromDuplicateGroup); this template documents
     // the family for exhaustiveness and backs any future sample-only fallback.
@@ -155,4 +165,4 @@ export function planRelationshipRemediation(assembly, options = {}) {
     };
 }
 //# sourceMappingURL=remediation.js.map
-//# debugId=9b8e22ad-6268-515d-994e-6b98a062ba93
+//# debugId=1eb0e2cb-084a-5a54-b41c-29dfdd6d2f34

package/dist/sdk/history-read.d.ts

@@ -37,6 +37,14 @@ export interface HistoryVerificationResult {
     current_item_hash?: string;
     /** Whether the supplied document matches the newest history hash. */
     current_matches_latest?: boolean;
+    /** Whether every governed workspace singleton matches the latest replayed state. */
+    workspace_state_matches_latest?: boolean;
+    /** Governed singleton paths whose JSON differs from the replayed value. */
+    workspace_state_mismatches?: string[];
+    /** Governed singleton paths absent from disk. */
+    workspace_state_missing?: string[];
+    /** Governed singleton paths unreadable as safe workspace-local JSON. */
+    workspace_state_unreadable?: string[];
 }
 /**
  * Verify a history chain and optionally compare it with a current document.

package/dist/sdk/history-read.js

@@ -7,7 +7,7 @@
  * systems without acquiring locks or appending history.
  */
 
-!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]="bccbd81b-988f-569d-8dbf-c0998d813953")}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]="04f5d4d2-4021-5ce2-b35a-2134d98d2ad7")}catch(e){}}();
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { pathExists } from "../core/fs/fs-utils.js";
 import { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, replayHistoryToTarget, resolveHistoryTarget, } from "../core/history/projection.js";
@@ -85,4 +85,4 @@ export async function getItemAt(id, target, options = {}) {
 }
 export { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, readHistoryEntries, replayHistoryToTarget, resolveHistoryTarget, };
 //# sourceMappingURL=history-read.js.map
-//# debugId=bccbd81b-988f-569d-8dbf-c0998d813953
+//# debugId=04f5d4d2-4021-5ce2-b35a-2134d98d2ad7

package/dist/sdk/index.d.ts

@@ -84,7 +84,7 @@ export * from "./history-compact.js";
 export * from "./history-read.js";
 export * from "./history-provenance.js";
 export * from "./mutation-events.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 { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceHistoryStateAgreement, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonReconciliationOptions, type WorkspaceJsonRestoreOptions, type WorkspaceJsonRestoreResult, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
 export * from "./history-redact.js";
 export { _testOnly } from "./history-redact.js";
 export * from "./history-repair.js";

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8664ab01-dc47-5344-b2d7-9ac315e8a74b")}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]="a05170b2-a48d-5275-ac04-aafc9f8315b2")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
@@ -82,7 +82,7 @@ export * from "./history-compact.js";
 export * from "./history-read.js";
 export * from "./history-provenance.js";
 export * from "./mutation-events.js";
-export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
+export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
 export * from "./history-redact.js";
 export { _testOnly } from "./history-redact.js";
 export * from "./history-repair.js";
@@ -151,4 +151,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=8664ab01-dc47-5344-b2d7-9ac315e8a74b
+//# debugId=a05170b2-a48d-5275-ac04-aafc9f8315b2

package/dist/sdk/query/history.js

@@ -4,8 +4,8 @@
  * Implements the pm history command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1638ef81-7558-5d51-8561-99c958de2d03")}catch(e){}}();
-import { pathExists, computeHistoryDiff, patchPathToChangedField, normalizeReplayPatchOps, verifyHistoryChain, enforceHistoryStreamPolicyForItem, EXIT_CODE, PmCliError, getActiveExtensionRegistrations, normalizeItemId, resolveItemTypeRegistry, locateItem, readLocatedItem, getHistoryPath, getWorkspaceHistoryPath, getSettingsPath, resolvePmRoot, readSettings, WORKSPACE_HISTORY_ID, } from "../runtime-primitives.js";
+!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]="f18d7526-01eb-593b-bf50-788c08a35e5d")}catch(e){}}();
+import { pathExists, computeHistoryDiff, patchPathToChangedField, normalizeReplayPatchOps, verifyHistoryChain, enforceHistoryStreamPolicyForItem, EXIT_CODE, PmCliError, getActiveExtensionRegistrations, normalizeItemId, resolveItemTypeRegistry, locateItem, readLocatedItem, getHistoryPath, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, getSettingsPath, resolvePmRoot, readSettings, WORKSPACE_HISTORY_ID, } from "../runtime-primitives.js";
 import { readHistoryEntries, verifyHistoryEntries, } from "../history-read.js";
 export { readHistoryEntries } from "../history-read.js";
 import { parseLimit } from "./parsers.js";
@@ -140,8 +140,25 @@ export async function runHistory(id, options, global) {
             })).document
             : undefined;
         result.verification = verifyHistoryEntries(fullHistory, currentDocument);
+        if (resolvedId === WORKSPACE_HISTORY_ID && result.verification.ok) {
+            const agreement = await inspectWorkspaceHistoryState(resolvePmRoot(process.cwd(), global.path));
+            result.verification = {
+                ...result.verification,
+                ok: agreement.ok,
+                errors: agreement.ok
+                    ? result.verification.errors
+                    : [
+                        ...result.verification.errors,
+                        "verify_failed:workspace_state_mismatch",
+                    ],
+                workspace_state_matches_latest: agreement.ok,
+                workspace_state_mismatches: agreement.mismatched_documents,
+                workspace_state_missing: agreement.missing_documents,
+                workspace_state_unreadable: agreement.unreadable_documents,
+            };
+        }
     }
     return result;
 }
 //# sourceMappingURL=history.js.map
-//# debugId=1638ef81-7558-5d51-8561-99c958de2d03
+//# debugId=f18d7526-01eb-593b-bf50-788c08a35e5d

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

@@ -5,6 +5,8 @@
  * read-output contract without expanding its public declaration module.
  */
 import type { PmReadOutputReceipt } from "./read-output-contracts.js";
+/** Estimate the conservative token cost of a JSON-shaped result. */
+export declare function estimateReadOutputTokens(result: unknown): number;
 /** Update a receipt to the fixed-point estimate of the result containing it. */
 export declare function updateReadOutputReceiptEstimate(result: Record<string, unknown>, receipt: PmReadOutputReceipt): void;
 /** Compact strings and rows in place, then return the final exact estimate. */

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

@@ -1,8 +1,12 @@
 
-!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]="1726fdce-dc71-5707-ae75-b588691e813d")}catch(e){}}();
-import { countReadOutputRows, readOutputRowCollections, } from "./read-output-rows.js";
+!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]="cc595424-0176-5920-8f4c-d935e6a546ce")}catch(e){}}();
+import { countReadOutputRows, readOutputBudgetCollections, } from "./read-output-rows.js";
 const MAX_ESTIMATE_ITERATIONS = 8;
 const MAX_COMPACTION_ITERATIONS = 64;
+/** Estimate the conservative token cost of a JSON-shaped result. */
+export function estimateReadOutputTokens(result) {
+    return Math.ceil(Buffer.byteLength(JSON.stringify(result), "utf8") / 4);
+}
 /** Return whether a value is a non-array object record. */
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -30,7 +34,7 @@ export function updateReadOutputReceiptEstimate(result, receipt) {
     let estimate = receipt.estimated_tokens;
     for (let iteration = 0; iteration < MAX_ESTIMATE_ITERATIONS; iteration += 1) {
         receipt.estimated_tokens = estimate;
-        const measured = Math.ceil(Buffer.byteLength(JSON.stringify(result), "utf8") / 4);
+        const measured = estimateReadOutputTokens(result);
         if (measured === estimate)
             return;
         estimate = measured;
@@ -43,7 +47,7 @@ function compactRowsToBudget(result, receipt, budget) {
         updateReadOutputReceiptEstimate(result, receipt);
         if (receipt.estimated_tokens <= budget)
             return;
-        const candidate = readOutputRowCollections(result)
+        const candidate = readOutputBudgetCollections(result)
             .filter((collection) => (Array.isArray(collection.value)
             ? collection.value.length
             : Object.keys(collection.value).length) > 1)
@@ -67,6 +71,9 @@ function compactRowsToBudget(result, receipt, budget) {
             }
         }
         receipt.rows_compacted = true;
+        receipt.compacted_row_paths = [
+            ...new Set([...(receipt.compacted_row_paths ?? []), candidate.path]),
+        ].sort((left, right) => left.localeCompare(right));
         result.has_more = true;
         result.truncated = true;
         if (typeof result.count === "number") {
@@ -85,4 +92,4 @@ export function compactReadOutputToBudget(result, receipt, budget) {
     return compacted;
 }
 //# sourceMappingURL=read-output-budget.js.map
-//# debugId=1726fdce-dc71-5707-ae75-b588691e813d
+//# debugId=cc595424-0176-5920-8f4c-d935e6a546ce

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

@@ -4,7 +4,7 @@ export declare const PM_READ_OUTPUT_DIMENSIONS: readonly ["include", "amount", "
 /** One member of the universal read-output dimension set. */
 export type PmReadOutputDimension = (typeof PM_READ_OUTPUT_DIMENSIONS)[number];
 /** Built-in command roots whose primary operation is a read. */
-export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "package-manage"];
+export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "package-manage", "comments-audit", "assurance"];
 /** Built-in read command supported by the universal output contract. */
 export type PmReadOutputSurface = (typeof PM_READ_OUTPUT_SURFACES)[number];
 /** Canonical output controls accepted by every built-in read action. */
@@ -13,8 +13,8 @@ export interface PmReadOutputOptions {
     outputInclude?: string | string[];
     /** Maximum rows retained, or `unbounded` to disable the shared row ceiling. */
     outputLimit?: string | number | "unbounded";
-    /** Maximum estimated result tokens. */
-    outputBudget?: string | number;
+    /** Maximum estimated result tokens, or `unbounded` to disable the default ceiling. */
+    outputBudget?: string | number | "unbounded";
     /** Requested static renderer encoding; streaming remains a command behavior. */
     outputFormat?: "json" | "toon";
     /** Caller-carried cross-call budget and served-fact state. */
@@ -26,6 +26,8 @@ export interface PmReadOutputOptions {
 export interface PmReadOutputLegacyAlias {
     /** Historical CLI spelling. */
     flag: string;
+    /** Strength of the migration promise carried by this alias. */
+    semantics?: "replacement" | "behavior_preserving";
     /** One-line migration instruction for agents and help generators. */
     migration_hint: string;
     /** Compatibility aliases are accepted but omitted from the canonical vocabulary. */
@@ -70,8 +72,8 @@ export interface PmResolvedReadOutputDimensions {
     include?: PmResolvedReadOutputDimension<string[]>;
     /** Requested row ceiling. */
     amount?: PmResolvedReadOutputDimension<number | "unbounded">;
-    /** Requested estimated-token ceiling. */
-    cost?: PmResolvedReadOutputDimension<number>;
+    /** Requested estimated-token ceiling or explicit opt-out. */
+    cost?: PmResolvedReadOutputDimension<number | "unbounded">;
     /** Requested static encoding or a retained legacy streaming behavior. */
     encoding?: PmResolvedReadOutputDimension<"json" | "toon" | "stream">;
     /** Compatibility flags observed on the invocation. */
@@ -89,6 +91,10 @@ export interface PmReadOutputReceipt {
     command: PmReadOutputSurface;
     /** Dimensions explicitly or compatibly requested by the invocation. */
     requested_dimensions: PmReadOutputDimension[];
+    /** Layer that supplied an automatically applied token ceiling. */
+    budget_source?: "default";
+    /** Automatically applied token ceiling; explicit/session budgets already disclose their value. */
+    budget_tokens?: number;
     /** Deterministic precedence used during resolution. */
     precedence: readonly ["canonical", "legacy", "intent", "default"];
     /** Compatibility options observed on the invocation. */
@@ -103,8 +109,27 @@ export interface PmReadOutputReceipt {
     strings_compacted: boolean;
     /** Whether row collections were reduced while satisfying the cost ceiling. */
     rows_compacted: boolean;
+    /** Declared or nested collection paths reduced by budget degradation. */
+    compacted_row_paths?: string[];
     /** Whether the requested cost ceiling forced the useful result to be omitted. */
     result_omitted: boolean;
+    /** Estimated tokens in the useful result immediately before whole-result omission. */
+    omitted_result_estimated_tokens?: number;
+}
+/** Machine-readable explanation of budget-driven row degradation. */
+export interface PmReadOutputTruncationDisclosure {
+    /** Stable reason for dropping rows. */
+    reason: "output_budget_reached";
+    /** Layer that supplied the binding ceiling. */
+    budget_source: PmReadOutputDimensionSource | "session";
+    /** Binding estimated-token ceiling. */
+    budget_tokens: number;
+    /** Explicit dimensions whose unbounded request was overridden by the ceiling. */
+    overridden_dimensions: PmReadOutputDimension[];
+    /** Declared or nested collection paths reduced by budget degradation. */
+    compacted_row_paths: string[];
+    /** Executable recovery instruction for retrieving the complete result. */
+    restore_with: string;
 }
 /** Result returned when the requested cost ceiling cannot fit useful content. */
 export interface PmReadOutputBudgetExceeded {
@@ -124,6 +149,7 @@ export interface PmReadOutputBudgetExceeded {
 export type PmReadOutputResult<Result> = (Result & {
     read_output?: PmReadOutputReceipt;
     read_session?: PmReadOutputSessionReceipt;
+    output_budget_truncation?: PmReadOutputTruncationDisclosure;
 }) | (PmReadOutputBudgetExceeded & {
     read_session?: PmReadOutputSessionReceipt;
 });
@@ -139,6 +165,36 @@ export declare const PM_READ_OUTPUT_SURFACE_CONTRACTS: readonly PmReadOutputSurf
 export declare function resolveReadOutputSurface(command: string): PmReadOutputSurface | undefined;
 /** Reject malformed or mutation-scoped universal output controls before command execution. */
 export declare function validateReadOutputOptions(command: string, options: Record<string, unknown>): void;
+/**
+ * Map every canonical `--output-include` token that names a projection mode
+ * rather than a row field onto the command-local option that mode already owns.
+ *
+ * The include dimension folds two kinds of legacy alias into one canonical
+ * spelling: value-bearing selectors (`--fields`, `--section`) that name row
+ * fields, and mode flags (`--brief`, `--full`, `--summary`, ...) that select a
+ * whole declared projection. Only the first kind can be honoured by projecting
+ * an already-computed result, so mode tokens have to reach the command itself.
+ */
+export declare function readOutputIncludeModeOptions(command: string): ReadonlyMap<string, string>;
+/**
+ * Translate canonical projection-mode tokens into the command-local options
+ * they alias, so the spelling the migration hints recommend is behaviour
+ * identical to the legacy flag it replaces, and return the field selectors that
+ * remain for post-execution projection.
+ */
+export declare function applyReadOutputIncludeModes(command: string, includeValue: unknown, commandOptions: Record<string, unknown>): {
+    selectors: string[];
+    modes: string[];
+};
+/**
+ * Resolve canonical include modes against one combined options bag, rewriting
+ * the include value in place to the selectors that remain.
+ *
+ * Used by dispatch paths that carry command options and universal output
+ * controls in a single record, so an action honours a mode token exactly as the
+ * CLI does.
+ */
+export declare function normalizeReadOutputIncludeModeOptions(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. */