@unbrained/pm-cli 2026.8.14 → 2026.8.16

package/dist/core/history/replay.js

@@ -4,7 +4,7 @@
  * Implements append-only history and replay behavior for Replay.
  */
 
-!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]="a1283470-00c7-5e91-8676-e1c1a667537f")}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]="0c37a722-fda7-523e-991c-f8abfb7a1495")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { canonicalDocument } from "../item/item-format.js";
@@ -219,8 +219,35 @@ export function lenientApplyReplayPatch(current, patch) {
     };
     return { document, convertedReplaceToAdd, skippedOps };
 }
+/**
+ * Resolve the hash epoch a repair must retain.
+ *
+ * A valid stream is authoritative even when legacy entries omit the version
+ * field. For a broken stream, one consistent explicit epoch remains
+ * authoritative; fully implicit legacy streams stay on epoch 1. Only an
+ * irreconcilably mixed stream falls forward to the current epoch.
+ */
+export function resolveHistoryRepairItemHashVersion(entries) {
+    const verified = verifyHistoryChainWithVersion(entries);
+    if (verified.ok && verified.item_hash_version !== undefined) {
+        return verified.item_hash_version;
+    }
+    const explicitVersions = [
+        ...new Set(entries
+            .map((entry) => entry.item_hash_version)
+            .filter((version) => version !== undefined &&
+            SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(version))),
+    ];
+    if (explicitVersions.length === 1) {
+        return explicitVersions[0];
+    }
+    if (explicitVersions.length === 0) {
+        return 1;
+    }
+    return CURRENT_HISTORY_ITEM_HASH_VERSION;
+}
 /** Re-anchor a drifted history chain: replay every entry from empty, recompute the before/after hashes, and only rewrite a patch when the original op set no longer strictly applies (legacy drift). Clean entries keep their patch verbatim so the on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain. */
-export function reanchorHistoryEntries(entries) {
+export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistoryRepairItemHashVersion(entries)) {
     const unsupportedIndex = entries.findIndex((entry) => entry.item_hash_version !== undefined &&
         !SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(entry.item_hash_version));
     if (unsupportedIndex >= 0) {
@@ -233,9 +260,11 @@ export function reanchorHistoryEntries(entries) {
     let entriesPatchRepaired = 0;
     let convertedReplaceToAdd = 0;
     let skippedOps = 0;
+    const explicitItemHashVersion = itemHashVersion !== 1 ||
+        entries.some((entry) => entry.item_hash_version !== undefined);
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
-        const beforeHash = replayHash(replay, CURRENT_HISTORY_ITEM_HASH_VERSION);
+        const beforeHash = replayHash(replay, itemHashVersion);
         const strict = tryApplyReplayPatch(replay, entry.patch);
         let next;
         let outPatch;
@@ -257,18 +286,24 @@ export function reanchorHistoryEntries(entries) {
             skippedOps += entrySkipped;
             entriesPatchRepaired += 1;
         }
-        const afterHash = replayHash(next, CURRENT_HISTORY_ITEM_HASH_VERSION);
+        const afterHash = replayHash(next, itemHashVersion);
         const rehashed = beforeHash !== entry.before_hash || afterHash !== entry.after_hash;
         if (rehashed) {
             entriesRehashed += 1;
         }
-        rewritten.push({
+        const rewrittenEntry = {
             ...entry,
             patch: outPatch,
             before_hash: beforeHash,
             after_hash: afterHash,
-            item_hash_version: CURRENT_HISTORY_ITEM_HASH_VERSION,
-        });
+        };
+        if (explicitItemHashVersion) {
+            rewrittenEntry.item_hash_version = itemHashVersion;
+        }
+        else {
+            delete rewrittenEntry.item_hash_version;
+        }
+        rewritten.push(rewrittenEntry);
         details.push({
             index: index + 1,
             rehashed,
@@ -286,6 +321,8 @@ export function reanchorHistoryEntries(entries) {
         convertedReplaceToAdd,
         skippedOps,
         details,
+        itemHashVersion,
+        explicitItemHashVersion,
     };
 }
 /** Implements history entries to raw for the public runtime surface of this module. */
@@ -296,4 +333,4 @@ export function historyEntriesToRaw(entries) {
     return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
 }
 //# sourceMappingURL=replay.js.map
-//# debugId=a1283470-00c7-5e91-8676-e1c1a667537f
+//# debugId=0c37a722-fda7-523e-991c-f8abfb7a1495

package/dist/core/history/workspace-history.js

@@ -5,7 +5,7 @@
  * HistoryEntry format used by item mutations.
  */
 
-!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]="0f666995-78f8-5741-ae0c-0d792feea599")}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]="9027d972-ce29-5511-ba81-27e17d97446e")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
@@ -54,6 +54,28 @@ function workspaceDocuments(document) {
         ? document.metadata.documents
         : {};
 }
+/** Refuse a workspace mutation or replay whose append-only chain is invalid. */
+function throwWorkspaceHistoryVerificationFailure(errors) {
+    throw new PmCliError(`Workspace history verification failed: ${errors.join(", ")}`, EXIT_CODE.CONFLICT, {
+        code: "workspace_history_chain_invalid",
+        reason: "workspace_history_chain_verification_failed",
+        verification_errors: [...errors],
+        required: "Repair the _workspace history chain before reading, reconciling, restoring, or appending audited singleton state.",
+        why: "Continuing against an unverifiable append-only stream could hide or compound workspace state corruption.",
+        examples: [
+            "pm history _workspace --verify --json",
+            "pm validate --check-history-drift --fix-hints --json",
+        ],
+        nextSteps: [
+            "Inspect the exact verification_errors and preserve the corrupt stream as evidence.",
+            "Use the history-drift remediation returned by validate before retrying the refused operation.",
+        ],
+        recovery: {
+            recovery_mode: "compact",
+            next_best_command: "pm history _workspace --verify --json",
+        },
+    });
+}
 /** Resolve a governed singleton path and reject paths outside the tracker root. */
 function resolveGovernedDocumentPath(pmRoot, filePath) {
     const absolutePath = path.resolve(filePath);
@@ -76,7 +98,7 @@ export async function inspectWorkspaceHistoryState(pmRoot) {
     const entries = await readHistoryEntries(getWorkspaceHistoryPath(pmRoot), WORKSPACE_HISTORY_ID);
     const verification = verifyHistoryChain(entries);
     if (!verification.ok) {
-        throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+        throwWorkspaceHistoryVerificationFailure(verification.errors);
     }
     const documents = workspaceDocuments(entries.length === 0
         ? EMPTY_CANONICAL_DOCUMENT
@@ -123,7 +145,7 @@ async function appendWorkspaceHistoryChangeLocked(change) {
     const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
     const verification = verifyHistoryChain(entries);
     if (!verification.ok) {
-        throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+        throwWorkspaceHistoryVerificationFailure(verification.errors);
     }
     const idempotentEntry = change.idempotencyKey === undefined
         ? undefined
@@ -194,7 +216,7 @@ export async function appendWorkspaceAuditEvent(options) {
         const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
         const verification = verifyHistoryChain(entries);
         if (!verification.ok) {
-            throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+            throwWorkspaceHistoryVerificationFailure(verification.errors);
         }
         const beforeDocument = entries.length === 0
             ? EMPTY_CANONICAL_DOCUMENT
@@ -303,7 +325,7 @@ export async function reconcileWorkspaceJsonHistory(options) {
         const entries = await readHistoryEntries(historyPath, WORKSPACE_HISTORY_ID);
         const verification = verifyHistoryChain(entries);
         if (!verification.ok) {
-            throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
+            throwWorkspaceHistoryVerificationFailure(verification.errors);
         }
         const beforeDocument = replayWorkspaceEntries(entries);
         const priorDocuments = workspaceDocuments(beforeDocument);
@@ -349,15 +371,15 @@ export async function restoreWorkspaceJsonFromHistory(options) {
     try {
         const { documentPath, absolutePath } = resolveGovernedDocumentPath(options.pmRoot, options.filePath);
         const entries = await readHistoryEntries(getWorkspaceHistoryPath(options.pmRoot), WORKSPACE_HISTORY_ID);
+        const verification = verifyHistoryChain(entries);
+        if (!verification.ok) {
+            throwWorkspaceHistoryVerificationFailure(verification.errors);
+        }
         if (!Number.isInteger(options.targetVersion) ||
             options.targetVersion < 1 ||
             options.targetVersion > entries.length) {
             throw new TypeError(`Invalid workspace history target version: ${String(options.targetVersion)}`);
         }
-        const verification = verifyHistoryChain(entries);
-        if (!verification.ok) {
-            throw new TypeError(`Workspace history verification failed: ${verification.errors.join(", ")}`);
-        }
         const target = workspaceDocuments(replayWorkspaceEntries(entries, options.targetVersion))[documentPath];
         if (target === undefined) {
             throw new TypeError(`Workspace history version ${options.targetVersion} does not contain ${documentPath}`);
@@ -408,4 +430,4 @@ export async function restoreWorkspaceJsonFromHistory(options) {
     }
 }
 //# sourceMappingURL=workspace-history.js.map
-//# debugId=0f666995-78f8-5741-ae0c-0d792feea599
+//# debugId=9027d972-ce29-5511-ba81-27e17d97446e

package/dist/core/output/output.d.ts

@@ -24,6 +24,8 @@ export interface OutputOptions {
     outputFormat?: "toon" | "json";
     /** Caller-carried cross-call budget and served-item state. */
     outputSession?: string;
+    /** Opaque budget-compaction continuation cursor. */
+    outputCursor?: string;
     /** Include machine-readable row location and row-encoding metadata. */
     outputRowContract?: boolean;
     /** Fallback output format used when callers do not provide an override. */

package/dist/core/output/output.js

@@ -4,14 +4,14 @@
  * Formats compact human and machine output for Output.
  */
 
-!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]="88eb8f29-72a2-536f-8fc9-394ed3e0e0fb")}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]="202cbb3e-71fe-5701-a1f5-eb515bf56561")}catch(e){}}();
 import { getActiveCommandContext, runActiveCommandOverride, runActiveRendererOverride, runActiveServiceOverrideSync, setActiveCommandResult, } from "../extensions/index.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { isHostOutputSuppressed } from "./output-control.js";
 import { projectMutationResult } from "./mutation-projection.js";
 import { attachReadOutputContracts } from "../../sdk/context-intent-contracts.js";
 import { attachOutputTokenAccounting } from "../../sdk/output-token-accounting.js";
-import { resolveReadOutputEncoding } from "../../sdk/read-output-contracts.js";
+import { isReadOutputBudgetExceeded, resolveReadOutputEncoding, } from "../../sdk/read-output-contracts.js";
 import { encode as encodeToon } from "@toon-format/toon";
 const DECLARED_PROCESS_EXIT_CODES = new Set(Object.values(EXIT_CODE));
 const NATIVE_OUTPUT_MARKER = "__pm_native_output";
@@ -366,6 +366,7 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
             ["outputBudget", options.outputBudget],
             ["outputFormat", options.outputFormat],
             ["outputSession", options.outputSession],
+            ["outputCursor", options.outputCursor],
             ["outputRowContract", options.outputRowContract],
         ].filter((entry) => entry[1] !== undefined)),
     };
@@ -388,6 +389,9 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
         ? projectLinkedTestEvidence(outputResult, options.lean === true)
         : outputResult;
     const intentOutputResult = attachReadOutputContracts(command, resolvedCommandOptions, projectedOutputResult);
+    if (isReadOutputBudgetExceeded(intentOutputResult)) {
+        process.exitCode ||= EXIT_CODE.USAGE;
+    }
     const renderResolvedOutput = (value) => {
         if (format === "toon") {
             const markdownDefault = renderDefaultMarkdownResult(value);
@@ -464,4 +468,4 @@ export const outputTestOnly = {
     renderToonValue,
 };
 //# sourceMappingURL=output.js.map
-//# debugId=88eb8f29-72a2-536f-8fc9-394ed3e0e0fb
+//# debugId=202cbb3e-71fe-5701-a1f5-eb515bf56561

package/dist/core/shared/command-types.d.ts

@@ -29,6 +29,8 @@ export interface GlobalOptions {
     outputFormat?: "toon" | "json";
     /** Caller-carried cross-call budget and served-item state. */
     outputSession?: string;
+    /** Opaque budget-compaction continuation cursor. */
+    outputCursor?: string;
     /** Include the machine-readable row selector and TOON encoding contract. */
     outputRowContract?: boolean;
     /** Filesystem path used for path resolution. */

package/dist/core/shared/command-types.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]="044af354-3047-5fd4-ae65-458a259dedca")}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]="525dce5a-3824-5c45-aa61-bd8b132bd973")}catch(e){}}();
 export {};
 //# sourceMappingURL=command-types.js.map
-//# debugId=044af354-3047-5fd4-ae65-458a259dedca
+//# debugId=525dce5a-3824-5c45-aa61-bd8b132bd973

package/dist/core/shared/errors.d.ts

@@ -32,6 +32,8 @@ export interface PmCliErrorRecoveryPayload {
     candidate_commands_total?: number;
     /** Whether additional accepting command paths were omitted from this payload. */
     candidate_commands_truncated?: boolean;
+    /** Declared lexicon membership of an option rejected by the attempted path. */
+    option_scope?: "declared_on_path" | "declared_elsewhere" | "declared_nowhere";
     /** Value that configures or reports suggested retry for this contract. */
     suggested_retry?: string;
     /** Elapsed time in milliseconds for retry after. */
@@ -53,6 +55,16 @@ export interface PmCliErrorContext {
     reason?: string;
     /** Metadata field responsible for a validation failure, when known. */
     field?: string;
+    /** Assurance gate whose evaluation was refused, when known. */
+    gate_id?: string;
+    /** Assurance assertion whose evaluation was refused, when known. */
+    assertion_id?: string;
+    /** Assurance measurement whose source could not resolve, when known. */
+    measurement_id?: string;
+    /** Assurance measurement source kind involved in a refusal, when known. */
+    source_kind?: string;
+    /** Validate or health check selected by an assurance source, when known. */
+    check?: string;
     /** Serialization format involved in a parse failure. */
     format?: string;
     /** Item format version involved in a compatibility failure. */
@@ -75,6 +87,8 @@ export interface PmCliErrorContext {
     nextSteps?: string[];
     /** Exact selectors that could not be matched by a lossless removal. */
     unmatched?: string[];
+    /** Exact verifier findings that caused an integrity-sensitive operation to refuse. */
+    verification_errors?: string[];
     /** Local dependency targets that could not be resolved before mutation. */
     unresolved_targets?: string[];
     /** Available history bounds for a failed point-in-time read or restore target. */

package/dist/core/shared/errors.js

@@ -1,6 +1,6 @@
 /** Implements the exported pm cli error runtime abstraction for core/shared/errors.ts. */
 
-!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]="62fb0ba7-643f-5b33-870b-df875559610a")}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]="bf08255e-7ef4-5929-8431-2df83d98d0ba")}catch(e){}}();
 export class PmCliError extends Error {
     /** Value that configures or reports exit code for this contract. */
     exitCode;
@@ -18,4 +18,4 @@ export class PmCliError extends Error {
     }
 }
 //# sourceMappingURL=errors.js.map
-//# debugId=62fb0ba7-643f-5b33-870b-df875559610a
+//# debugId=bf08255e-7ef4-5929-8431-2df83d98d0ba

package/dist/core/store/item-store.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for Item Store.
  */
 
-!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]="f43e1170-e797-5a0c-b02e-d31e002ab275")}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]="d24d61bf-7db8-5f35-8dbc-5ef93ec8220b")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnReadHooks, runActiveBeforeMutationHooks, runActiveOnWriteHooks, runActiveServiceOverride, } from "../extensions/index.js";
@@ -69,6 +69,15 @@ function trackerRootNotDirectoryError(pmRoot) {
         ],
     });
 }
+function trackerRootUnreadableError(pmRoot) {
+    return new PmCliError(`Tracker root is not readable at ${pmRoot}.`, EXIT_CODE.GENERIC_FAILURE, {
+        code: "tracker_root_unreadable",
+        reason: "unreadable",
+        nextSteps: [
+            "Grant read and directory-search permission to the tracker root, then retry the SDK read.",
+        ],
+    });
+}
 async function assertMissingMetadataRootAncestors(pmRoot) {
     const filesystemRoot = path.parse(path.resolve(pmRoot)).root;
     let ancestor = path.dirname(path.resolve(pmRoot));
@@ -114,11 +123,28 @@ async function assertItemMetadataRoot(pmRoot) {
         if (isErrno(error, "ENOTDIR")) {
             throw trackerRootNotDirectoryError(pmRoot);
         }
+        if (isErrno(error, "EACCES") || isErrno(error, "EPERM")) {
+            throw trackerRootUnreadableError(pmRoot);
+        }
         throw error;
     }
     if (!stats.isDirectory()) {
         throw trackerRootNotDirectoryError(pmRoot);
     }
+    if (process.platform !== "win32" &&
+        ((stats.mode & 0o444) === 0 || (stats.mode & 0o111) === 0)) {
+        throw trackerRootUnreadableError(pmRoot);
+    }
+    try {
+        const directory = await fs.opendir(pmRoot);
+        await directory.close();
+    }
+    catch (error) {
+        if (isErrno(error, "EACCES") || isErrno(error, "EPERM")) {
+            throw trackerRootUnreadableError(pmRoot);
+        }
+        throw error;
+    }
 }
 /** Implements locate item for the public runtime surface of this module. */
 export async function locateItem(pmRoot, rawId, idPrefix = "pm-", preferredFormat, typeToFolder = TYPE_TO_FOLDER) {
@@ -684,4 +710,4 @@ export async function deleteItem(params) {
     }
 }
 //# sourceMappingURL=item-store.js.map
-//# debugId=f43e1170-e797-5a0c-b02e-d31e002ab275
+//# debugId=d24d61bf-7db8-5f35-8dbc-5ef93ec8220b

package/dist/mcp/tool-definitions.js

@@ -4,7 +4,7 @@
  * Defines the Tool Definitions module for pm CLI source.
  */
 
-!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]="cde81c26-97fa-5236-b807-e944ba4af321")}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]="d440a41a-ae54-55fd-b939-5404a1edcdd7")}catch(e){}}();
 import { GRAPH_SUBCOMMAND_VALUES, PM_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.js";
 import { buildPmActionToolInputSchema } from "../sdk/cli-contracts/tool-schema.js";
 import { RUNTIME_STATUS_ROLE_VALUES } from "../types.js";
@@ -20,9 +20,8 @@ const READ_OUTPUT_TOOL_PROPERTIES = {
         description: "Universal read row ceiling, or unbounded to disable the shared ceiling.",
     },
     outputBudget: {
-        type: "integer",
-        minimum: 1,
-        description: "Universal estimated-token ceiling for a read result.",
+        anyOf: [{ type: "integer", minimum: 1 }, { const: "unbounded" }],
+        description: "Universal estimated-token ceiling, or unbounded to return the complete read result.",
     },
     outputFormat: {
         type: "string",
@@ -32,6 +31,11 @@ const READ_OUTPUT_TOOL_PROPERTIES = {
     outputSession: {
         ...CANONICAL_OUTPUT_SESSION_TOOL_PROPERTY,
     },
+    outputCursor: {
+        type: "string",
+        minLength: 1,
+        description: "Opaque continuation cursor returned after budget compaction of a declared row collection.",
+    },
 };
 /** MCP transport parameters layered over every canonical action schema. */
 export const TOOL_SCHEMA_BASE = {
@@ -739,4 +743,4 @@ export function buildMcpToolContracts() {
     }).sort((left, right) => left.name.localeCompare(right.name));
 }
 //# sourceMappingURL=tool-definitions.js.map
-//# debugId=cde81c26-97fa-5236-b807-e944ba4af321
+//# debugId=d440a41a-ae54-55fd-b939-5404a1edcdd7

package/dist/sdk/agent/refusal-reachability.d.ts

@@ -36,5 +36,74 @@ export interface PmRefusalReachabilityReport {
     /** Stable, sorted conformance findings. */
     findings: PmRefusalReachabilityFinding[];
 }
+/** Recovery-reference kinds emitted by structured refusal envelopes. */
+export declare const PM_RECOVERY_REFERENCE_KINDS: readonly ["suggested_retry", "candidate_command", "example", "next_step", "migration_hint", "restore_with"];
+/** Recovery-reference kind emitted by a refusal. */
+export type PmRecoveryReferenceKind = (typeof PM_RECOVERY_REFERENCE_KINDS)[number];
+/** Behavioral promise attached to a recovery reference. */
+export type PmRecoveryReferenceSemantics = "recovery" | "replacement" | "behavior_preserving";
+/** One derived promise that another invocation or command path is reachable. */
+export interface PmRecoveryReferenceObligation {
+    /** Stable reference identifier derived from its emitting envelope. */
+    id: string;
+    /** Refusal probe that emitted the reference. */
+    probe_id: string;
+    /** Typed recovery vocabulary rather than prose inference. */
+    kind: PmRecoveryReferenceKind;
+    /** Whether the reference recovers, replaces, or preserves the original behavior. */
+    semantics: PmRecoveryReferenceSemantics;
+    /** Exact emitted command or recovery text. */
+    value: string;
+}
+/** Result of executing or resolving one derived recovery obligation. */
+export interface PmRecoveryReferenceObservation {
+    /** Stable obligation identifier. */
+    id: string;
+    /** Whether the promised recovery or command path was reachable. */
+    reachable: boolean;
+    /** How the promise was discharged. */
+    proof: "executed" | "declared_command_path" | "linked_execution";
+    /** Semantics actually demonstrated by the proof. */
+    semantics: PmRecoveryReferenceSemantics;
+}
+/** Coverage totals for one emitted recovery-reference kind. */
+export interface PmRecoveryReferenceKindCoverage {
+    /** Typed reference kind. */
+    kind: PmRecoveryReferenceKind;
+    /** Derived obligations of this kind. */
+    declared: number;
+    /** Obligations with one observation. */
+    observed: number;
+    /** Obligations proven reachable. */
+    passed: number;
+}
+/** One recovery-reference coverage failure. */
+export interface PmRecoveryReferenceFinding {
+    /** Stable finding kind for assurance and CI. */
+    kind: "duplicate_obligation" | "duplicate_observation" | "missing_observation" | "unreachable_reference" | "wrong_semantics" | "undeclared_observation";
+    /** Obligation or observation identifier. */
+    reference_id: string;
+    /** Human-readable mismatch summary. */
+    detail: string;
+}
+/** Complete cross-kind recovery-reference coverage receipt. */
+export interface PmRecoveryReferenceReport {
+    /** Whether every derived reference was uniquely proven reachable. */
+    ok: boolean;
+    /** Total references derived from real refusal envelopes. */
+    declared_reference_count: number;
+    /** Total reference observations supplied. */
+    observed_reference_count: number;
+    /** Reachable fraction across the declared obligation set. */
+    pass_fraction: number;
+    /** Stable coverage buckets, including zero-population kinds. */
+    coverage_by_kind: PmRecoveryReferenceKindCoverage[];
+    /** Stable, sorted conformance findings. */
+    findings: PmRecoveryReferenceFinding[];
+}
+/** Derive typed obligations from every recognized recovery field in an emitted envelope. */
+export declare function derivePmRecoveryReferenceObligations(probeId: string, envelope: unknown): PmRecoveryReferenceObligation[];
 /** Compare declared refusal states with real-entrypoint observations. */
 export declare function verifyPmRefusalReachability(catalog: readonly PmErrorCodeContract[], observations: readonly PmRefusalProbeObservation[]): PmRefusalReachabilityReport;
+/** Verify executable and declared-path proof for emitted recovery references. */
+export declare function verifyPmRecoveryReferences(obligations: readonly PmRecoveryReferenceObligation[], observations: readonly PmRecoveryReferenceObservation[]): PmRecoveryReferenceReport;