@unbrained/pm-cli 2026.8.13 → 2026.8.14

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

@@ -5,10 +5,11 @@
  * 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]="0ab0c72c-cac0-5670-93d1-7a446f8a2301")}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]="c78ba845-78ae-5b16-b486-c279f834d601")}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";
+import { compactReadOutputToBudget, estimateReadOutputTokens, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
+import { resolvePmCommandOutputBudget } from "./cli-contracts/agent-output-contracts.js";
 import { boundReadOutputRows, countReadOutputRows, mapReadOutputRows, readOutputRowPaths, } from "./read-output-rows.js";
 import { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 /** Stable output dimensions shared by every read surface. */
@@ -40,6 +41,8 @@ export const PM_READ_OUTPUT_SURFACES = [
     "stats",
     "aggregate",
     "package-manage",
+    "comments-audit",
+    "assurance",
 ];
 const READ_OUTPUT_PRECEDENCE = [
     "canonical",
@@ -91,7 +94,7 @@ const LEGACY_FLAGS_BY_COMMAND = {
         encoding: ["--format"],
     },
     health: {
-        include: ["--brief", "--check-only", "--full", "--summary", "--verbose"],
+        include: ["--brief", "--check-only", "--full", "--summary"],
     },
     deps: {
         include: ["--collapse", "--full", "--summary"],
@@ -113,7 +116,7 @@ const LEGACY_FLAGS_BY_COMMAND = {
         amount: ["--limit", "--unbounded"],
         encoding: ["--stream"],
     },
-    validate: { include: ["--counts", "--full", "--verbose"] },
+    validate: { include: ["--counts", "--full"] },
     events: {
         include: ["--full"],
         amount: ["--limit"],
@@ -129,17 +132,26 @@ const LEGACY_FLAGS_BY_COMMAND = {
     stats: {},
     aggregate: {},
     "package-manage": {},
+    "comments-audit": {},
+    assurance: {},
 };
-const VALUE_BEARING_INCLUDE_ALIASES = new Set(["--fields", "--section"]);
+const VALUE_BEARING_INCLUDE_ALIASES = new Set([
+    "--collapse",
+    "--fields",
+    "--section",
+]);
 const BEHAVIOR_PRESERVING_MIGRATION_HINTS = Object.freeze({
     "--after": "--after retains cursor-position semantics; use --output-limit <n> separately to bound returned rows.",
     "--check-only": "--check-only retains health side-effect semantics; --output-include does not suppress vector refresh.",
+    "--collapse": "--collapse retains dependency grouping semantics; --output-include does not replace it.",
     "--depth": "--depth retains traversal or detail-depth semantics; --output-limit does not replace it.",
     "--follow": "--follow retains event-tail semantics; --output-format does not enable following.",
     "--max-depth": "--max-depth retains graph traversal-depth semantics; --output-limit does not replace it.",
     "--max-paths": "--max-paths retains graph path-search semantics; use --output-limit separately to bound returned rows.",
+    "--no-truncate": "--no-truncate is a compatibility alias; prefer --output-limit unbounded.",
     "--offset": "--offset retains positional pagination semantics; use --output-limit separately to bound returned rows.",
     "--stream": "--stream retains command streaming semantics; --output-format selects only static result encoding.",
+    "--unbounded": "--unbounded is a compatibility alias; prefer --output-limit unbounded.",
 });
 function flagSelector(flag) {
     return flag.slice(2).replaceAll("-", "_");
@@ -170,6 +182,9 @@ function buildSurfaceContract(command) {
             inapplicable_reason: null,
             legacy_aliases: Object.freeze((legacy[dimension] ?? []).map((flag) => Object.freeze({
                 flag,
+                semantics: BEHAVIOR_PRESERVING_MIGRATION_HINTS[flag] === undefined
+                    ? "replacement"
+                    : "behavior_preserving",
                 migration_hint: migrationHint(flag, dimension),
                 visibility: "hidden_alias",
             }))),
@@ -242,8 +257,8 @@ const READ_OUTPUT_VALUE_VALIDATORS = [
     },
     {
         keys: ["outputBudget", "output_budget"],
-        valid: (value) => positiveInteger(value) !== undefined,
-        message: "--output-budget must be a positive integer.",
+        valid: (value) => value === "unbounded" || positiveInteger(value) !== undefined,
+        message: "--output-budget must be a positive integer or unbounded.",
     },
     {
         keys: ["outputFormat", "output_format"],
@@ -279,6 +294,68 @@ export function validateReadOutputOptions(command, options) {
         }
     }
 }
+/**
+ * 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 function readOutputIncludeModeOptions(command) {
+    const surface = resolveReadOutputSurface(command);
+    if (!surface)
+        return new Map();
+    return new Map((LEGACY_FLAGS_BY_COMMAND[surface].include ?? [])
+        .filter((flag) => !VALUE_BEARING_INCLUDE_ALIASES.has(flag) &&
+        BEHAVIOR_PRESERVING_MIGRATION_HINTS[flag] === undefined)
+        .map((flag) => [flagSelector(flag), optionKey(flag)]));
+}
+/**
+ * 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 function applyReadOutputIncludeModes(command, includeValue, commandOptions) {
+    const requested = stringList(includeValue) ?? [];
+    const modeOptions = readOutputIncludeModeOptions(command);
+    const selectors = [];
+    const modes = [];
+    for (const token of requested) {
+        const option = modeOptions.get(token);
+        if (option === undefined) {
+            selectors.push(token);
+            continue;
+        }
+        commandOptions[option] = true;
+        modes.push(token);
+    }
+    return { selectors, modes };
+}
+/**
+ * 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 function normalizeReadOutputIncludeModeOptions(command, options) {
+    const include = options.outputInclude ?? options.output_include;
+    if (include === undefined)
+        return;
+    const { selectors, modes } = applyReadOutputIncludeModes(command, include, options);
+    if (modes.length === 0)
+        return;
+    const residual = selectors.length > 0 ? selectors.join(",") : undefined;
+    options.outputInclude = residual;
+    if (Object.hasOwn(options, "output_include")) {
+        options.output_include = residual;
+    }
+}
 function optionKey(flag) {
     return flag
         .slice(2)
@@ -353,6 +430,9 @@ function resolveAmountValue(canonical, legacy) {
         : { source: "legacy", value: legacyLimit };
 }
 function resolveCostValue(canonical, legacy) {
+    if (canonical === "unbounded") {
+        return { source: "canonical", value: "unbounded" };
+    }
     const canonicalBudget = positiveInteger(canonical);
     if (canonicalBudget !== undefined) {
         return { source: "canonical", value: canonicalBudget };
@@ -404,12 +484,23 @@ export function resolveReadOutputDimensions(command, options) {
         const alias = contract.dimensions[dimension].legacy_aliases.find((entry) => entry.flag === resolved.flag);
         return [alias.migration_hint];
     });
+    const encoding = resolveEncodingValue(options.outputFormat ?? options.output_format, legacyByDimension.encoding);
+    const explicitCost = resolveCostValue(options.outputBudget ?? options.output_budget, legacyByDimension.cost);
+    const budget = resolvePmCommandOutputBudget(command, {
+        generateFallback: true,
+    });
+    const resolvedOutputFormat = encoding?.value === "json" || options.resolvedOutputFormat === "json"
+        ? "json"
+        : "toon";
     return {
         command: normalizedCommand,
         include: resolveIncludeValue(options.outputInclude ?? options.output_include, legacyByDimension.include),
         amount: resolveAmountValue(options.outputLimit ?? options.output_limit, legacyByDimension.amount),
-        cost: resolveCostValue(options.outputBudget ?? options.output_budget, legacyByDimension.cost),
-        encoding: resolveEncodingValue(options.outputFormat ?? options.output_format, legacyByDimension.encoding),
+        cost: explicitCost ?? {
+            source: "default",
+            value: budget.default_max_estimated_tokens_by_format[resolvedOutputFormat],
+        },
+        encoding,
         legacy_aliases_used: legacyAliasesUsed,
         migration_hints: migrationHints,
         precedence: READ_OUTPUT_PRECEDENCE,
@@ -525,6 +616,34 @@ function applyGetIncludeProjection(result, selectors) {
     };
     return projected;
 }
+/** Count row objects that still carry at least one field. */
+function countPopulatedRows(result) {
+    let populated = 0;
+    mapReadOutputRows({ ...result }, (entry) => {
+        if (isRecord(entry) && Object.keys(entry).length > 0)
+            populated += 1;
+        return entry;
+    });
+    return populated;
+}
+/**
+ * Refuse an include projection that strips every field from every row.
+ *
+ * Selectors that match no field are not a narrower answer, they are no answer:
+ * without this the surface returns the requested row count as empty objects and
+ * exits 0, so a mistyped or mode-shaped selector is indistinguishable from a
+ * workspace that genuinely holds nothing.
+ */
+function rejectEmptyIncludeProjection(command, original, shaped, selectors) {
+    if (countPopulatedRows(original) === 0 || countPopulatedRows(shaped) > 0) {
+        return;
+    }
+    const modes = [...readOutputIncludeModeOptions(command).keys()];
+    const domain = modes.length > 0
+        ? ` Declared ${command} projection modes: ${modes.join(", ")}.`
+        : ` The ${command} surface declares no projection modes; name row fields instead.`;
+    throw new PmCliError(`Unknown --output-include selector(s) for ${command}: ${selectors.join(", ")}. No selector matched any returned row field.${domain}`, EXIT_CODE.USAGE);
+}
 function applyIncludeProjection(command, result, selectors) {
     if (command === "get") {
         return applyGetIncludeProjection(result, selectors);
@@ -537,11 +656,10 @@ function applyIncludeProjection(command, result, selectors) {
         !rows.some((rowPath) => selector.startsWith(`${rowPath}.`)));
     if (rows.length > 0 && (!selectedRoot || qualifiedRowSelectors.length > 0)) {
         const projected = { ...result };
-        return mapReadOutputRows(projected, (entry) => isRecord(entry)
-            ? projectRecordFields(entry, qualifiedRowSelectors.length > 0
-                ? qualifiedRowSelectors
-                : selectors)
-            : entry);
+        const rowSelectors = qualifiedRowSelectors.length > 0 ? qualifiedRowSelectors : selectors;
+        const shaped = mapReadOutputRows(projected, (entry) => isRecord(entry) ? projectRecordFields(entry, rowSelectors) : entry);
+        rejectEmptyIncludeProjection(command, result, shaped, rowSelectors);
+        return shaped;
     }
     return Object.fromEntries(Object.entries(result).filter(([key]) => selectors.some((selector) => selector.split(".")[0] === key) ||
         ENVELOPE_KEYS.has(key)));
@@ -565,7 +683,8 @@ function applyAmountBound(result, amount) {
     return bounded;
 }
 function requestedDimensions(resolved) {
-    return PM_READ_OUTPUT_DIMENSIONS.filter((dimension) => resolved[dimension] !== undefined);
+    return PM_READ_OUTPUT_DIMENSIONS.filter((dimension) => resolved[dimension] !== undefined &&
+        resolved[dimension]?.source !== "default");
 }
 /** Stabilize the per-call and cross-call receipts in one complete envelope. */
 function attachReadOutputSessionContracts(result, state, receipt) {
@@ -611,19 +730,34 @@ function projectReadOutputRows(result, resolved, session) {
 /** Resolve the smallest binding per-call or remaining cross-call ceiling. */
 function resolveBindingReadOutputBudget(resolved, session) {
     const budgets = [
-        ...(resolved.cost?.source === "canonical" ? [resolved.cost.value] : []),
+        ...(resolved.cost !== undefined &&
+            resolved.cost.value !== "unbounded" &&
+            (resolved.cost.source === "canonical" || resolved.cost.source === "default")
+            ? [{ source: resolved.cost.source, tokens: resolved.cost.value }]
+            : []),
         ...(session === undefined
             ? []
-            : [readOutputSessionRemainingTokens(session)]),
+            : [
+                {
+                    source: "session",
+                    tokens: readOutputSessionRemainingTokens(session),
+                },
+            ]),
     ];
-    return budgets.length === 0 ? undefined : Math.min(...budgets);
+    return budgets.sort((left, right) => left.tokens - right.tokens)[0];
 }
 /** Build the smallest truthful omission envelope or reject an exhausted session. */
-function omitReadOutputForBudget(resolved, requested, session, budget) {
+function omitReadOutputForBudget(resolved, requested, session, bindingBudget, omittedResultEstimatedTokens) {
     const minimalReceipt = {
         contract_version: 1,
         command: resolved.command,
         requested_dimensions: requested,
+        ...(bindingBudget.source === "default"
+            ? {
+                budget_source: bindingBudget.source,
+                budget_tokens: bindingBudget.tokens,
+            }
+            : {}),
         precedence: resolved.precedence,
         legacy_aliases_used: [],
         migration_hints: [],
@@ -632,6 +766,9 @@ function omitReadOutputForBudget(resolved, requested, session, budget) {
         strings_compacted: false,
         rows_compacted: false,
         result_omitted: true,
+        ...(session === undefined
+            ? { omitted_result_estimated_tokens: omittedResultEstimatedTokens }
+            : {}),
     };
     const omitted = {
         output_budget_exceeded: {
@@ -647,11 +784,48 @@ function omitReadOutputForBudget(resolved, requested, session, budget) {
     if (session === undefined) {
         updateReadOutputReceiptEstimate(boundedOmission, minimalReceipt);
     }
-    if (session !== undefined && minimalReceipt.estimated_tokens > budget) {
+    if (session !== undefined &&
+        minimalReceipt.estimated_tokens > bindingBudget.tokens) {
         throw new PmCliError("The remaining output-session budget cannot fit its mandatory receipts; start a new session with a larger token_budget.", EXIT_CODE.USAGE);
     }
     return boundedOmission;
 }
+/** Decide whether shaping would add no value to an already-bounded result. */
+function canReturnReadOutputUnchanged(resolved, requested, session, result) {
+    if (session !== undefined)
+        return false;
+    const canonicalRequestedCount = requested.filter((dimension) => resolved[dimension]?.source === "canonical").length;
+    if (resolved.cost?.value === "unbounded") {
+        return canonicalRequestedCount === 1;
+    }
+    if (resolved.cost?.source === "legacy" && canonicalRequestedCount === 0) {
+        return true;
+    }
+    return (canonicalRequestedCount === 0 &&
+        (resolved.cost === undefined ||
+            estimateReadOutputTokens(result) <= resolved.cost.value));
+}
+/**
+ * Disclose a budget-driven row drop in the envelope that carries it.
+ *
+ * `has_more` and `truncated` say that rows were withheld but not why, by what,
+ * or how to get them: the row-compaction path emits no continuation cursor, so
+ * without this an explicitly requested unbounded read is silently downgraded and
+ * the only working recovery is never named.
+ */
+function attachReadOutputTruncationDisclosure(projected, resolved, receipt, bindingBudget) {
+    if (!receipt.rows_compacted)
+        return;
+    const overridden = resolved.amount?.value === "unbounded" ? ["amount"] : [];
+    projected.output_budget_truncation = {
+        reason: "output_budget_reached",
+        budget_source: bindingBudget.source,
+        budget_tokens: bindingBudget.tokens,
+        overridden_dimensions: overridden,
+        compacted_row_paths: receipt.compacted_row_paths,
+        restore_with: "Re-run with --output-budget unbounded for the complete result.",
+    };
+}
 /** Apply universal field, row, and token bounds and attach an exact receipt. */
 export function applyReadOutputDimensions(command, options, result) {
     const resolved = resolveReadOutputDimensions(command, options);
@@ -659,15 +833,21 @@ export function applyReadOutputDimensions(command, options, result) {
         return result;
     const session = parseReadOutputSession(options.outputSession ?? options.output_session);
     const requested = requestedDimensions(resolved);
-    const canonicalRequested = requested.filter((dimension) => resolved[dimension]?.source === "canonical");
-    if (canonicalRequested.length === 0 && session === undefined) {
+    if (canReturnReadOutputUnchanged(resolved, requested, session, result)) {
         return result;
     }
+    const bindingBudget = resolveBindingReadOutputBudget(resolved, session);
     let projected = projectReadOutputRows(result, resolved, session);
     const receipt = {
         contract_version: 1,
         command: resolved.command,
         requested_dimensions: requested,
+        ...(bindingBudget?.source === "default"
+            ? {
+                budget_source: bindingBudget.source,
+                budget_tokens: bindingBudget.tokens,
+            }
+            : {}),
         precedence: resolved.precedence,
         legacy_aliases_used: resolved.legacy_aliases_used,
         migration_hints: resolved.migration_hints,
@@ -683,15 +863,17 @@ export function applyReadOutputDimensions(command, options, result) {
             ? projected
             : attachReadOutputSessionContracts(projected, session, receipt);
     updateReadOutputReceiptEstimate(projected, receipt);
-    const budget = resolveBindingReadOutputBudget(resolved, session);
-    if (budget !== undefined && receipt.estimated_tokens > budget) {
-        projected = compactReadOutputToBudget(projected, receipt, budget);
+    if (bindingBudget !== undefined &&
+        receipt.estimated_tokens > bindingBudget.tokens) {
+        projected = compactReadOutputToBudget(projected, receipt, bindingBudget.tokens);
+        attachReadOutputTruncationDisclosure(projected, resolved, receipt, bindingBudget);
         if (session !== undefined) {
             projected = attachReadOutputSessionContracts(projected, session, receipt);
         }
     }
-    if (budget !== undefined && receipt.estimated_tokens > budget) {
-        return omitReadOutputForBudget(resolved, requested, session, budget);
+    if (bindingBudget !== undefined &&
+        receipt.estimated_tokens > bindingBudget.tokens) {
+        return omitReadOutputForBudget(resolved, requested, session, bindingBudget, receipt.estimated_tokens);
     }
     return projected;
 }
@@ -710,4 +892,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=0ab0c72c-cac0-5670-93d1-7a446f8a2301
+//# debugId=c78ba845-78ae-5b16-b486-c279f834d601

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

@@ -15,6 +15,17 @@ export interface PmReadOutputRowCollection {
 export declare function readOutputRowPaths(result: Record<string, unknown>): string[];
 /** Resolve every declared row path that currently contains iterable rows. */
 export declare function readOutputRowCollections(result: Record<string, unknown>): PmReadOutputRowCollection[];
+/**
+ * Discover every collection the token-budget degradation ladder may reduce.
+ *
+ * Ordinary field and amount projections stay bound to declared row paths (or
+ * top-level array fallbacks), because a nested tag list is not an independent
+ * result row. Budget degradation has a different obligation: it must exhaust
+ * nested content collections before omitting the whole useful result. This
+ * census therefore adds nested arrays while excluding receipt/envelope metadata
+ * whose mutation would make the disclosure itself incomplete.
+ */
+export declare function readOutputBudgetCollections(result: Record<string, unknown>): PmReadOutputRowCollection[];
 /** Count array entries and object-map values across declared row collections. */
 export declare function countReadOutputRows(result: Record<string, unknown>): number;
 /**

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

@@ -5,7 +5,20 @@
  * envelopes, including dot-delimited nested paths used by graph projections.
  */
 
-!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]="ae6fbd4a-6c4e-5639-93ac-f107a336e95b")}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]="03e25a43-f05c-5bc6-a42a-140914e522d5")}catch(e){}}();
+const BUDGET_METADATA_ROOT_KEYS = new Set([
+    "applied_bound",
+    "completeness",
+    "continuation_contract",
+    "filters",
+    "omission_receipt",
+    "output_budget_truncation",
+    "projection",
+    "read_output",
+    "read_session",
+    "row_contract",
+    "sorting",
+]);
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -54,6 +67,38 @@ export function readOutputRowCollections(result) {
             : [];
     });
 }
+/**
+ * Discover every collection the token-budget degradation ladder may reduce.
+ *
+ * Ordinary field and amount projections stay bound to declared row paths (or
+ * top-level array fallbacks), because a nested tag list is not an independent
+ * result row. Budget degradation has a different obligation: it must exhaust
+ * nested content collections before omitting the whole useful result. This
+ * census therefore adds nested arrays while excluding receipt/envelope metadata
+ * whose mutation would make the disclosure itself incomplete.
+ */
+export function readOutputBudgetCollections(result) {
+    const collections = readOutputRowCollections(result);
+    const declaredPaths = new Set(collections.map((collection) => collection.path));
+    const visit = (value, path) => {
+        if (Array.isArray(value)) {
+            if (!declaredPaths.has(path)) {
+                collections.push({ path, value });
+            }
+            value.forEach((entry, index) => visit(entry, `${path}.${index}`));
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        for (const [key, entry] of Object.entries(value)) {
+            if (path.length === 0 && BUDGET_METADATA_ROOT_KEYS.has(key))
+                continue;
+            visit(entry, path.length === 0 ? key : `${path}.${key}`);
+        }
+    };
+    visit(result, "");
+    return collections;
+}
 /** Count array entries and object-map values across declared row collections. */
 export function countReadOutputRows(result) {
     return readOutputRowCollections(result).reduce((total, collection) => total +
@@ -97,4 +142,4 @@ export function boundReadOutputRows(result, amount) {
     return { result: projected, truncated };
 }
 //# sourceMappingURL=read-output-rows.js.map
-//# debugId=ae6fbd4a-6c4e-5639-93ac-f107a336e95b
+//# debugId=03e25a43-f05c-5bc6-a42a-140914e522d5

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

@@ -18,7 +18,7 @@ export { type HistoryDiffValueEntry, computeHistoryDiff, patchPathToChangedField
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
 export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, type HistoryItemHashVersion, } from "../core/history/history.js";
 export { 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 { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceHistoryStateAgreement, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonReconciliationOptions, type WorkspaceJsonRestoreOptions, type WorkspaceJsonRestoreResult, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
 export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 export { resolveBodyFileContent } from "../core/io/body-file.js";
 export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/item/id.js";

package/dist/sdk/runtime-primitives.js

@@ -7,7 +7,7 @@
  * prefer the typed operations exported by the main SDK barrel.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="78779372-1987-54d0-9ae4-775b52641a26")}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]="a678b9f8-ba36-5127-877f-96bb4acc38c5")}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";
@@ -20,7 +20,7 @@ export { computeHistoryDiff, patchPathToChangedField, } from "../core/history/hi
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
 export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, } from "../core/history/history.js";
 export { readHistoryEntries } from "../core/history/read.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 { 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";
@@ -81,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=78779372-1987-54d0-9ae4-775b52641a26
+//# debugId=a678b9f8-ba36-5127-877f-96bb4acc38c5

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]="7c27b516-1714-5f2b-8304-98e8372280be")}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]="a387cd7a-cb16-5082-80e1-9632ebd02480")}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";
@@ -31,7 +31,7 @@ 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";
+import { normalizeReadOutputIncludeModeOptions, validateReadOutputOptions, } from "./read-output-contracts.js";
 export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";
 import { normalizeActivityProjectionOptions, runActivity, } from "./query/activity.js";
 import { runAssuranceDispatch } from "./governance/assurance-action.js";
@@ -1870,6 +1870,7 @@ export function analyzeSdkActionCoverage(actions = PM_TOOL_ACTIONS) {
 async function dispatchAction(action, args, global, activeExtensions) {
     const options = optionsWithAuthor(args, action);
     validateReadOutputOptions(action, options);
+    normalizeReadOutputIncludeModeOptions(action, options);
     const ctx = {
         action,
         args,
@@ -1883,6 +1884,7 @@ async function dispatchAction(action, args, global, activeExtensions) {
     const result = handler
         ? await handler(ctx)
         : await dispatchActiveExtensionAction(action, args, options, global, activeExtensions);
+    options.resolvedOutputFormat = "json";
     return attachReadOutputContracts(action, options, result);
 }
 const actionRunnerTestHooks = {
@@ -1930,4 +1932,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=7c27b516-1714-5f2b-8304-98e8372280be
+//# debugId=a387cd7a-cb16-5082-80e1-9632ebd02480

package/docs/ASSURANCE.md

@@ -1,6 +1,6 @@
 # Project Assurance Primitives
 
-Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon), [pm-uhv1m5](../.agents/pm/features/pm-uhv1m5.toon), [pm-m7bb7r](../.agents/pm/features/pm-m7bb7r.toon), [pm-py7qv2](../.agents/pm/issues/pm-py7qv2.toon), [pm-33mjrw](../.agents/pm/issues/pm-33mjrw.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon)
+Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon), [pm-uhv1m5](../.agents/pm/features/pm-uhv1m5.toon), [pm-m7bb7r](../.agents/pm/features/pm-m7bb7r.toon), [pm-py7qv2](../.agents/pm/issues/pm-py7qv2.toon), [pm-33mjrw](../.agents/pm/issues/pm-33mjrw.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon)
 
 ## Agent Quick Context
 
@@ -12,6 +12,15 @@ Assurance turns project policy into three reusable SDK-owned declarations:
 
 Declarations live in `.agents/pm/assurance.json`. Every registry mutation and non-dry gate verdict is appended through the verified workspace history stream; never edit either file directly.
 
+`pm history _workspace --verify`, `pm validate`, and `pm health` verify both
+the hash chain and replay-to-disk agreement for every governed singleton. A
+valid chain paired with a different, missing, or unreadable singleton is still
+drift. SDK hosts can inspect that state with `inspectWorkspaceHistoryState`,
+adopt a reviewed out-of-band value only through
+`reconcileWorkspaceJsonHistory` with a terminal authorizing Decision, or
+replace it from a verified version with `restoreWorkspaceJsonFromHistory`.
+Both recovery paths append forward; neither rewrites the existing stream.
+
 ## Why Assurance Exists
 
 Project management is context management. A useful quality gate therefore needs more than a shell exit code: it must preserve what was measured, which population was judged, why a bound exists, who owns it, what changed the result, how expensive the evaluation was, and which immutable tree received the verdict.

package/docs/COMMANDS.md

@@ -21,7 +21,29 @@ pm contracts --command <command> --flags-only --json
 
 Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon),
 [pm-7nqo6b](../.agents/pm/issues/pm-7nqo6b.toon), and
-[pm-j1r8gl](../.agents/pm/issues/pm-j1r8gl.toon).
+[pm-j1r8gl](../.agents/pm/issues/pm-j1r8gl.toon). Universal command intent and
+default output-budget enforcement are tracked by
+[pm-5t33or](../.agents/pm/features/pm-5t33or.toon),
+[pm-s2h0mq](../.agents/pm/issues/pm-s2h0mq.toon),
+[pm-pmrae8](../.agents/pm/issues/pm-pmrae8.toon), and
+[pm-7i97c3](../.agents/pm/issues/pm-7i97c3.toon).
+
+### Universal read-output ceiling
+
+Every SDK-backed read has a format-aware default token ceiling discovered from
+`pm contracts`. Results already within that ceiling are returned unchanged, so
+the default adds no receipt overhead to ordinary reads. An oversized result is
+degraded deterministically through string compaction, row compaction, and a
+truthful omission envelope; automatic degradation adds `read_output` with
+`budget_source: default`, `budget_tokens`, the final estimate, and the applied
+compaction flags.
+
+Use `--output-budget <tokens>` to request a tighter per-call ceiling. Use
+`--output-budget unbounded` only when the caller deliberately accepts the full
+cost. This cost opt-out is distinct from command-local row controls such as
+`activity --unbounded`, which disable a row limit but do not disable the shared
+token ceiling. `--output-format json` and global `--json` select the declared
+JSON ceiling; TOON uses the smaller default agent ceiling.
 
 ## Command Families
 
@@ -1161,7 +1183,14 @@ Extension policy tokens are explicitly scoped by
 Project-governance setters use the separate `governance_contracts` value
 domains; in particular, workflow enforcement is `off|warn|strict`, not the
 extension policy token `enforce`.
-Use `pm contracts --summary --json` first when bootstrapping in a tight context window; it emits one command and terse intent per row before the agent requests heavier command-specific flags or schemas.
+Use `pm contracts --summary --json` first when bootstrapping in a tight context
+window. `command_summaries` contains exactly one row per advertised command
+path—including aliases and namespace children—with a meaningful intent plus
+`default_max_estimated_tokens` and the format-specific TOON/JSON ceilings.
+Package commands contribute their intent through command registration (falling
+back to the registered description), so agents never need a generic
+`Inspect flags.` placeholder. Request heavier command-specific flags or schemas
+only after selecting the exact path.
 
 ## Completion