@unbrained/pm-cli 2026.8.18 → 2026.8.19

package/dist/sdk/query/search-contracts.js

@@ -4,11 +4,12 @@
  * Owns search input parsing, output projection contracts, and tuning defaults.
  */
 
-!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]="47576eb5-4ddf-5e04-9e1d-c961da39b754")}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]="e737cdf9-734c-5010-864f-60e8052dd9c1")}catch(e){}}();
 import { coerceNumberInRange } from "../../core/shared/primitives.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { resolveIsoOrRelative } from "../../core/shared/time.js";
+import { renderPmCommand } from "../command-line.js";
 const DEFAULT_COMPACT_SEARCH_FIELDS = [
     "id",
     "title",
@@ -174,23 +175,31 @@ export function parseSearchProjection(options) {
     return { mode: "full", fields: [] };
 }
 /** Validate explicit projection fields against core and runtime metadata. */
-export function validateSearchProjectionFields(projection, runtimeFieldRegistry) {
+export function validateSearchProjectionFields(projection, runtimeFieldRegistry, query = "<query>") {
     if (projection.mode !== "fields")
         return;
     const runtimeKeys = new Set(runtimeFieldRegistry.definitions.flatMap((field) => [
         field.key,
         field.metadata_key,
     ]));
+    const allowedValues = new Set([
+        ...SEARCH_HIT_FIELD_KEYS,
+        ...SEARCH_ITEM_FIELD_KEYS,
+        ...[...SEARCH_ITEM_FIELD_KEYS].map((field) => `item.${field}`),
+        ...runtimeKeys,
+        ...[...runtimeKeys].map((field) => `item.${field}`),
+    ]);
     const unknown = projection.fields.filter((field) => {
         const normalized = field.trim();
-        const itemKey = normalized.startsWith("item.")
-            ? normalized.slice("item.".length)
-            : normalized;
-        return (!SEARCH_HIT_FIELD_KEYS.has(normalized) &&
-            !SEARCH_ITEM_FIELD_KEYS.has(itemKey) &&
-            !runtimeKeys.has(itemKey));
+        return !allowedValues.has(normalized);
     });
     if (unknown.length > 0) {
+        const suggestedRetryArguments = [
+            "search",
+            query,
+            "--fields",
+            "id,title,status,score",
+        ];
         throw new PmCliError(`Unknown search --fields value(s): ${unknown.join(", ")}`, EXIT_CODE.USAGE, {
             examples: [
                 "pm search <query> --fields id,title,status,score",
@@ -199,6 +208,11 @@ export function validateSearchProjectionFields(projection, runtimeFieldRegistry)
             nextSteps: [
                 "Use item.<field> for explicit item metadata fields, or run pm search --help for projection examples.",
             ],
+            recovery: {
+                allowed_values: [...allowedValues].sort(),
+                suggested_retry: renderPmCommand(suggestedRetryArguments),
+                suggested_retry_args: suggestedRetryArguments,
+            },
         });
     }
 }
@@ -283,4 +297,4 @@ export function resolveSearchTuning(settings) {
     };
 }
 //# sourceMappingURL=search-contracts.js.map
-//# debugId=47576eb5-4ddf-5e04-9e1d-c961da39b754
+//# debugId=e737cdf9-734c-5010-864f-60e8052dd9c1

package/dist/sdk/query/search.js

@@ -4,7 +4,7 @@
  * Implements the pm search 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]="1750b332-dd40-5497-b410-26c8c7436329")}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]="0582c462-43fc-563c-b209-d6e3c39948f4")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
@@ -1552,7 +1552,7 @@ async function resolveSearchRuntimeContext(prepared, global) {
     const settings = resolveSettingsWithSemanticRuntimeDefaults(storedSettings).settings;
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
-    validateSearchProjectionFields(prepared.projection, runtimeFieldRegistry);
+    validateSearchProjectionFields(prepared.projection, runtimeFieldRegistry, prepared.query);
     const runtimeFieldFilters = collectRuntimeFilterValues(prepared.options, runtimeFieldRegistry, "search");
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const providerResolution = resolveEmbeddingProviders(settings);
@@ -1961,4 +1961,4 @@ export async function runSearch(rawQuery, rawOptions, global) {
     return withSearchWorkspaceMemory(buildSearchResultForHits(response, projectedItems, total, page.limited.length, effectiveProjection, page.pageExtras), workspaceMemoryResult);
 }
 //# sourceMappingURL=search.js.map
-//# debugId=1750b332-dd40-5497-b410-26c8c7436329
+//# debugId=0582c462-43fc-563c-b209-d6e3c39948f4

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

@@ -1,5 +1,5 @@
 import type { PmReadOutputCursorEnvelope, PmReadOutputSurface } from "../read-output-contracts.js";
-/** Fingerprint stable row identities without including volatile observation fields. */
+/** Fingerprint the complete canonical row snapshot so changed evidence fails closed. */
 export declare function readOutputCollectionFingerprint(path: string, value: unknown[] | Record<string, unknown>): string;
 /** Encode one stable declared-row continuation for CLI, SDK, and MCP callers. */
 export declare function encodeReadOutputContinuationCursor(cursor: Omit<PmReadOutputCursorEnvelope, "version">): string;

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

@@ -6,38 +6,21 @@
  * resolution and budget policy.
  */
 
-!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]="8e523bbc-5745-514e-a1d8-a6ad6ece001a")}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]="1c73c31e-6246-5730-8c8a-d3ba7c9ec112")}catch(e){}}();
 import { createHash } from "node:crypto";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
+import { stableStringify } from "../../core/shared/serialization.js";
 import { resolveReadOutputSurface } from "../read-output-contracts.js";
-import { readOutputRowCollections, sliceReadOutputRowCollection, } from "../read-output-rows.js";
+import { readOutputContinuationRowCollections, sliceReadOutputRowCollection, } from "../read-output-rows.js";
 const MAX_READ_OUTPUT_CURSOR_LENGTH = 4096;
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-/** Fingerprint stable row identities without including volatile observation fields. */
+/** Fingerprint the complete canonical row snapshot so changed evidence fails closed. */
 export function readOutputCollectionFingerprint(path, value) {
-    const identities = Array.isArray(value)
-        ? value.map((row, index) => {
-            if (!isRecord(row))
-                return `index:${String(index)}`;
-            for (const key of [
-                "id",
-                "assertion_id",
-                "measurement_id",
-                "event_id",
-            ]) {
-                const candidate = row[key];
-                if (typeof candidate === "string" && candidate.length > 0) {
-                    return `${key}:${candidate}`;
-                }
-            }
-            return `index:${String(index)}`;
-        })
-        : Object.keys(value);
     return createHash("sha256")
-        .update(JSON.stringify({ path, identities }))
+        .update(stableStringify({ path, value }))
         .digest("base64url")
         .slice(0, 16);
 }
@@ -113,7 +96,7 @@ export function applyReadOutputContinuation(result, command, cursor) {
     if (cursor.command !== command) {
         throw new PmCliError(`The read-output cursor belongs to ${cursor.command}, not ${command}.`, EXIT_CODE.USAGE, { code: "read_output_cursor_command_mismatch" });
     }
-    const collection = readOutputRowCollections(result).find((entry) => entry.path === cursor.path);
+    const collection = readOutputContinuationRowCollections(result).find((entry) => entry.path === cursor.path);
     const totalRows = collection
         ? Array.isArray(collection.value)
             ? collection.value.length
@@ -129,4 +112,4 @@ export function applyReadOutputContinuation(result, command, cursor) {
     return sliceReadOutputRowCollection(result, cursor.path, cursor.offset);
 }
 //# sourceMappingURL=continuation.js.map
-//# debugId=8e523bbc-5745-514e-a1d8-a6ad6ece001a
+//# debugId=1c73c31e-6246-5730-8c8a-d3ba7c9ec112

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

@@ -5,12 +5,12 @@
  * 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]="db1d54b0-ff27-51f5-a179-14556ced24eb")}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]="b3c001df-9891-5cf7-990b-8d9da7b51801")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { compactReadOutputToBudget, estimateReadOutputTokens, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
 import { resolvePmCommandOutputBudget } from "./cli-contracts/agent-output-contracts.js";
-import { boundReadOutputRows, countReadOutputRows, mapReadOutputRows, readOutputRowCollections, readOutputRowPaths, } from "./read-output-rows.js";
+import { boundReadOutputRows, countReadOutputRows, mapReadOutputRows, readOutputBudgetCollections, readOutputContinuationRowCollections, readOutputRowPaths, } from "./read-output-rows.js";
 import { applyReadOutputContinuation, decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, prioritizeAssuranceAssertions, readOutputCollectionFingerprint, } from "./read-output/continuation.js";
 export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, } from "./read-output/continuation.js";
 import { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
@@ -763,6 +763,54 @@ export function stabilizeReadOutputReceiptEstimates(result, options) {
     }
     return attachReadOutputSessionContracts(result, session, receipt);
 }
+/** Declare independently resumable validate diagnostic arrays on rich results. */
+function attachValidateDiagnosticRowContract(command, result) {
+    if (command !== "validate")
+        return result;
+    const projection = isRecord(result.projection)
+        ? result.projection
+        : undefined;
+    const declaredFieldGroups = Array.isArray(projection?.declared_field_groups)
+        ? projection.declared_field_groups
+        : [];
+    if (!declaredFieldGroups.some((group) => isRecord(group) && group.name === "diagnostic_rows")) {
+        return result;
+    }
+    const diagnosticCollectionPaths = [
+        ...new Set(readOutputBudgetCollections(result)
+            .map(({ path }) => path)
+            .filter((path) => /^checks\.\d+\.details\./u.test(path))),
+    ];
+    const diagnosticRowKeys = diagnosticCollectionPaths.filter((path) => !diagnosticCollectionPaths.some((candidate) => candidate !== path && path.startsWith(`${candidate}.`)));
+    if (diagnosticRowKeys.length === 0)
+        return result;
+    const existingContract = isRecord(result.row_contract)
+        ? result.row_contract
+        : {};
+    const existingRowKeys = Array.isArray(existingContract.row_keys)
+        ? existingContract.row_keys.filter((entry) => typeof entry === "string")
+        : [];
+    const existingContinuationRowKeys = Array.isArray(existingContract.continuation_row_keys)
+        ? existingContract.continuation_row_keys.filter((entry) => typeof entry === "string")
+        : [];
+    const rowKeys = existingRowKeys.length > 0 ? existingRowKeys : diagnosticRowKeys;
+    const continuationRowKeys = [...new Set(diagnosticRowKeys)];
+    return JSON.stringify(rowKeys) === JSON.stringify(existingRowKeys) &&
+        JSON.stringify(continuationRowKeys) ===
+            JSON.stringify(existingContinuationRowKeys)
+        ? result
+        : {
+            ...result,
+            row_contract: {
+                ...existingContract,
+                row_keys: rowKeys,
+                continuation_row_keys: continuationRowKeys,
+                jq_selector: typeof existingContract.jq_selector === "string"
+                    ? existingContract.jq_selector
+                    : ".checks[].details",
+            },
+        };
+}
 /** Apply field, amount, and repeat projections to every declared row path. */
 function projectReadOutputRows(result, resolved, session, cursor) {
     let projected = { ...result };
@@ -871,7 +919,7 @@ function attachReadOutputTruncationDisclosure(projected, resolved, receipt, bind
     if (!receipt.rows_compacted)
         return;
     const overridden = resolved.amount?.value === "unbounded" ? ["amount"] : [];
-    const afterByPath = new Map(readOutputRowCollections(projected).map((collection) => [
+    const afterByPath = new Map(readOutputContinuationRowCollections(projected).map((collection) => [
         collection.path,
         Array.isArray(collection.value)
             ? collection.value.length
@@ -974,7 +1022,7 @@ function rebaseBudgetCompactedCursor(projected, originalItemCount, cursorSource,
     return true;
 }
 function captureReadOutputContinuationState(projected, cursor, options) {
-    const collectionsBeforeBudget = new Map(readOutputRowCollections(projected).map((collection) => {
+    const collectionsBeforeBudget = new Map(readOutputContinuationRowCollections(projected).map((collection) => {
         const rows = Array.isArray(collection.value)
             ? collection.value.length
             : Object.keys(collection.value).length;
@@ -1032,8 +1080,9 @@ export function applyReadOutputDimensions(command, options, result) {
         canReturnReadOutputUnchanged(resolved, requested, session, result)) {
         return result;
     }
+    const continuationReadyResult = attachValidateDiagnosticRowContract(resolved.command, result);
     const bindingBudget = resolveBindingReadOutputBudget(resolved, session);
-    let projected = projectReadOutputRows(result, resolved, session, cursor);
+    let projected = projectReadOutputRows(continuationReadyResult, resolved, session, cursor);
     const continuationState = captureReadOutputContinuationState(projected, cursor, options);
     const receipt = {
         contract_version: 1,
@@ -1085,4 +1134,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=db1d54b0-ff27-51f5-a179-14556ced24eb
+//# debugId=b3c001df-9891-5cf7-990b-8d9da7b51801

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

@@ -15,8 +15,12 @@ export interface PmReadOutputRowCollection {
 export declare function sliceReadOutputRowCollection(result: Record<string, unknown>, rowPath: string, offset: number): Record<string, unknown>;
 /** Resolve declared row paths, falling back to top-level array properties. */
 export declare function readOutputRowPaths(result: Record<string, unknown>): string[];
+/** Resolve collections that may be resumed independently from primary result rows. */
+export declare function readOutputContinuationRowPaths(result: Record<string, unknown>): string[];
 /** Resolve every declared row path that currently contains iterable rows. */
 export declare function readOutputRowCollections(result: Record<string, unknown>): PmReadOutputRowCollection[];
+/** Resolve every declared continuation path that currently contains iterable rows. */
+export declare function readOutputContinuationRowCollections(result: Record<string, unknown>): PmReadOutputRowCollection[];
 /**
  * Discover every collection the token-budget degradation ladder may reduce.
  *

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

@@ -5,7 +5,7 @@
  * 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]="0c69ff43-7bbc-5128-9533-bbf15365126b")}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]="810d42b5-98f4-57a7-bdd9-2dfa1b2b1c03")}catch(e){}}();
 const BUDGET_METADATA_ROOT_KEYS = new Set([
     "applied_bound",
     "completeness",
@@ -29,31 +29,43 @@ function isRecord(value) {
 function valueAtPath(result, rowPath) {
     let value = result;
     for (const segment of rowPath.split(".")) {
-        if (!isRecord(value))
-            return undefined;
-        value = value[segment];
+        if (Array.isArray(value)) {
+            if (!/^\d+$/u.test(segment))
+                return undefined;
+            value = value[Number(segment)];
+        }
+        else {
+            if (!isRecord(value))
+                return undefined;
+            value = value[segment];
+        }
     }
     return value;
 }
 /** Clone the owners along one row path and replace only its terminal value. */
 function replaceValueAtPath(result, rowPath, replacement) {
     const segments = rowPath.split(".");
-    const root = { ...result };
-    let source = result;
-    let target = root;
-    for (const segment of segments.slice(0, -1)) {
-        const sourceChild = source[segment];
-        const targetChild = { ...sourceChild };
-        target[segment] = targetChild;
-        source = sourceChild;
-        target = targetChild;
-    }
-    target[segments.at(-1)] = replacement;
-    return root;
+    const replace = (value, offset) => {
+        if (offset === segments.length)
+            return replacement;
+        const segment = segments[offset];
+        if (Array.isArray(value)) {
+            const index = Number(segment);
+            const cloned = [...value];
+            cloned[index] = replace(value[index], offset + 1);
+            return cloned;
+        }
+        const record = value;
+        return {
+            ...record,
+            [segment]: replace(record[segment], offset + 1),
+        };
+    };
+    return replace(result, 0);
 }
 /** Replace one declared row collection with a suffix beginning at an offset. */
 export function sliceReadOutputRowCollection(result, rowPath, offset) {
-    const collection = readOutputRowCollections(result).find((entry) => entry.path === rowPath);
+    const collection = readOutputContinuationRowCollections(result).find((entry) => entry.path === rowPath);
     if (!collection)
         return result;
     const replacement = Array.isArray(collection.value)
@@ -71,6 +83,14 @@ export function readOutputRowPaths(result) {
         .filter(([, value]) => Array.isArray(value))
         .map(([key]) => key);
 }
+/** Resolve collections that may be resumed independently from primary result rows. */
+export function readOutputContinuationRowPaths(result) {
+    const contract = result.row_contract;
+    if (isRecord(contract) && Array.isArray(contract.continuation_row_keys)) {
+        return contract.continuation_row_keys.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+    }
+    return readOutputRowPaths(result);
+}
 /** Resolve every declared row path that currently contains iterable rows. */
 export function readOutputRowCollections(result) {
     return readOutputRowPaths(result).flatMap((rowPath) => {
@@ -80,6 +100,15 @@ export function readOutputRowCollections(result) {
             : [];
     });
 }
+/** Resolve every declared continuation path that currently contains iterable rows. */
+export function readOutputContinuationRowCollections(result) {
+    return readOutputContinuationRowPaths(result).flatMap((rowPath) => {
+        const value = valueAtPath(result, rowPath);
+        return Array.isArray(value) || isRecord(value)
+            ? [{ path: rowPath, value }]
+            : [];
+    });
+}
 /**
  * Discover every collection the token-budget degradation ladder may reduce.
  *
@@ -155,4 +184,4 @@ export function boundReadOutputRows(result, amount) {
     return { result: projected, truncated };
 }
 //# sourceMappingURL=read-output-rows.js.map
-//# debugId=0c69ff43-7bbc-5128-9533-bbf15365126b
+//# debugId=810d42b5-98f4-57a7-bdd9-2dfa1b2b1c03

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]="48d9b905-70a1-52c3-9b9c-33624661e6eb")}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]="95764dd9-1b0d-5732-9f10-b13b334ce27d")}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";
@@ -1349,13 +1349,14 @@ async function runMcpListAction(ctx) {
     return withQuerySummary((await runList(readString(ctx.args, "status") ?? readString(listOptions, "status"), listOptions, ctx.global)), listOptions);
 }
 async function runMcpSearchAction(ctx) {
-    const searchOptions = applyContextIntentProjection("search", ctx.options);
+    const query = readRequiredString(ctx.args, "query");
+    const searchOptions = applyContextIntentProjection("search", ctx.options, [query]);
     if (searchOptions.compact === undefined &&
         searchOptions.full === undefined &&
         searchOptions.fields === undefined) {
         searchOptions.compact = true;
     }
-    return withQuerySummary((await runSearch(readRequiredString(ctx.args, "query"), searchOptions, ctx.global)), searchOptions);
+    return withQuerySummary((await runSearch(query, searchOptions, ctx.global)), searchOptions);
 }
 async function runMcpCreateAction(ctx) {
     const { changedFields, idOnly, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
@@ -1783,7 +1784,10 @@ const SDK_ACTION_HANDLERS = {
     event: runRuntimeSchedulingAction,
     remind: runRuntimeSchedulingAction,
     list: runMcpListAction,
-    get: (ctx) => runGet(requireMcpItemId(ctx), ctx.global, applyContextIntentProjection("get", ctx.options)),
+    get: (ctx) => {
+        const id = requireMcpItemId(ctx);
+        return runGet(id, ctx.global, applyContextIntentProjection("get", ctx.options, [id]));
+    },
     search: runMcpSearchAction,
     duplicates: (ctx) => {
         const status = typeof ctx.options.status === "string"
@@ -1936,4 +1940,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=48d9b905-70a1-52c3-9b9c-33624661e6eb
+//# debugId=95764dd9-1b0d-5732-9f10-b13b334ce27d

package/dist/sdk/workspace-snapshot.d.ts

@@ -1,5 +1,7 @@
 /** Current content-addressed workspace snapshot manifest schema identifier. */
 export declare const SNAPSHOT_SCHEMA = "https://schema.unbrained.dev/pm/workspace-snapshot/v1";
+/** Workspace snapshot action tokens accepted by the SDK and CLI dispatcher. */
+export declare const WORKSPACE_SNAPSHOT_ACTIONS: readonly ["create", "list", "inspect", "restore", "delete"];
 /** Filesystem operations required by atomic snapshot publish and restore swaps. */
 export interface WorkspaceSnapshotAtomicOperations {
     /** Rename one filesystem entry atomically. */

package/dist/sdk/workspace-snapshot.js

@@ -5,7 +5,7 @@
  * state while excluding clone-local caches, locks, and recovery journals.
  */
 
-!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]="36aacc71-c5f5-56f1-85f4-28b2be5b02e2")}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]="2580e043-8675-5070-b57e-30cae333228c")}catch(e){}}();
 import crypto from "node:crypto";
 import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
 import path from "node:path";
@@ -18,6 +18,14 @@ import { PmCliError } from "../core/shared/errors.js";
 import { withHostEnvironmentBoundary } from "./environment/host-environment-errors.js";
 /** Current content-addressed workspace snapshot manifest schema identifier. */
 export const SNAPSHOT_SCHEMA = "https://schema.unbrained.dev/pm/workspace-snapshot/v1";
+/** Workspace snapshot action tokens accepted by the SDK and CLI dispatcher. */
+export const WORKSPACE_SNAPSHOT_ACTIONS = [
+    "create",
+    "list",
+    "inspect",
+    "restore",
+    "delete",
+];
 const SNAPSHOT_RUNTIME_PATH = path.join("runtime", "workspace-snapshots");
 const EXCLUDED_ROOT_NAMES = new Set([
     "checkpoints",
@@ -603,4 +611,4 @@ export async function deleteWorkspaceSnapshot(pmRoot, target) {
     return { deleted: "object", target };
 }
 //# sourceMappingURL=workspace-snapshot.js.map
-//# debugId=36aacc71-c5f5-56f1-85f4-28b2be5b02e2
+//# debugId=2580e043-8675-5070-b57e-30cae333228c

package/docs/COMMANDS.md

@@ -2,7 +2,7 @@
 
 This is a task-oriented command guide. For exact flags, use runtime help because extensions and settings can change the active surface:
 
-Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-qd3woa](../.agents/pm/issues/pm-qd3woa.toon), [pm-ypuc39](../.agents/pm/issues/pm-ypuc39.toon), [pm-tz2ikr](../.agents/pm/issues/pm-tz2ikr.toon), the schema-migration recovery contract [pm-s79kel](../.agents/pm/issues/pm-s79kel.toon), the lossless mutation contracts [pm-x3dq0l](../.agents/pm/issues/pm-x3dq0l.toon), [pm-lppm6y](../.agents/pm/issues/pm-lppm6y.toon), and [pm-embm6t](../.agents/pm/issues/pm-embm6t.toon), and the SDK-first agent grammar tranche [pm-p316vn](../.agents/pm/issues/pm-p316vn.toon), [pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon), [pm-mkinft](../.agents/pm/issues/pm-mkinft.toon), [pm-ulqu](../.agents/pm/issues/pm-ulqu.toon), [pm-qmjx](../.agents/pm/issues/pm-qmjx.toon), [pm-4bzq](../.agents/pm/features/pm-4bzq.toon), [pm-x2vx](../.agents/pm/issues/pm-x2vx.toon), and [pm-g543](../.agents/pm/issues/pm-g543.toon).
+Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-qd3woa](../.agents/pm/issues/pm-qd3woa.toon), [pm-ypuc39](../.agents/pm/issues/pm-ypuc39.toon), [pm-tz2ikr](../.agents/pm/issues/pm-tz2ikr.toon), the schema-migration recovery contract [pm-s79kel](../.agents/pm/issues/pm-s79kel.toon), the lossless mutation contracts [pm-x3dq0l](../.agents/pm/issues/pm-x3dq0l.toon), [pm-lppm6y](../.agents/pm/issues/pm-lppm6y.toon), and [pm-embm6t](../.agents/pm/issues/pm-embm6t.toon), positional action discovery [pm-2tan](../.agents/pm/issues/pm-2tan.toon), and the SDK-first agent grammar tranche [pm-p316vn](../.agents/pm/issues/pm-p316vn.toon), [pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon), [pm-mkinft](../.agents/pm/issues/pm-mkinft.toon), [pm-ulqu](../.agents/pm/issues/pm-ulqu.toon), [pm-qmjx](../.agents/pm/issues/pm-qmjx.toon), [pm-4bzq](../.agents/pm/features/pm-4bzq.toon), [pm-x2vx](../.agents/pm/issues/pm-x2vx.toon), and [pm-g543](../.agents/pm/issues/pm-g543.toon).
 
 Workspace-integrity contracts are tracked by [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), and [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon).
 
@@ -1120,6 +1120,13 @@ Profiles are extensible: a package can ship its own archetype with `api.register
 
 Plan creation shares the normal create contract. Governance fields such as `--status`, `--deadline`, `--estimate`, `--acceptance-criteria`, `--assignee`, review/risk fields, comments, notes, learnings, reminders, events, and linked resources are accepted directly and pass through the same strict/progressive schema validation as `pm create`.
 
+Every positional plan action is also a discoverable virtual command path. Use
+`pm plan create --help --json` or `pm help plan create --json` for its exact
+arguments and effective flags, and use `pm contracts --command "plan create"
+--flags-only --json` for the matching machine contract. Root `pm plan --help
+--json` publishes the same action inventory under `subcommands`; omitting the
+required action fails as `missing_required_argument` before mutation dispatch.
+
 ```bash
 pm plan create --title "Refactor lock retry" --scope "Improve retry semantics" --harness claude-code --parent pm-epic1 --related pm-rel1,pm-rel2 --claim
 pm plan create --title "Fix flaky retry test" --step "Read lock.ts" --step "Write the fix" --step "Run the tests"
@@ -1190,9 +1197,14 @@ 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. `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.
+window. `command_summaries` contains one row per registered command path,
+including aliases and namespace children, with a meaningful intent plus
+`default_max_estimated_tokens`. The low-token summary intentionally does not
+repeat the 32 virtual positional Plan, Assurance, and workspace-snapshot action rows;
+`grammar_contracts.positional_action_count` and `positional_action_parents`
+retain their complete discoverability and route callers to root help. A
+command-scoped contract for an exact action restores its typed positional
+signature, exact flags, provenance, and 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

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -15,7 +15,8 @@ selectors are tracked by
 [pm-x710qm](../.agents/pm/issues/pm-x710qm.toon). Default contract suppression
 and canonical TOON tables are tracked by
 [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon) and
-[pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon).
+[pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon). Nested evidence continuation
+is tracked by [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon).
 
 ## Agent Quick Context
 
@@ -73,6 +74,7 @@ or not the current page has rows:
     "command": "list",
     "row_kind": "collection",
     "row_keys": ["items"],
+    "continuation_row_keys": ["items"],
     "fields": "supported",
     "jq_selector": ".row_contract.row_keys[] as $key | getpath($key | split(\".\")) | if type == \"array\" then .[] else if type == \"object\" then to_entries[] else empty end end",
     "toon_encoding": "tabular_when_uniform"
@@ -89,6 +91,12 @@ nested dependency graph and relationship-context rows addressable as
 `graph.nodes`, `graph.edges`, `context.nodes`, and `context.edges` without
 duplicating them at the envelope root. Array collections produce their
 elements; object maps produce jq `to_entries` rows.
+`continuation_row_keys` is optional and defaults to `row_keys`. A command uses
+it only when independently resumable nested evidence differs from its primary
+amount-bounded rows. Validate, for example, keeps `checks` and `warnings` as
+primary rows while a rich result can name
+`checks.0.details.missing_resolution_rows` as a continuation row. This prevents
+an inner diagnostic array from disabling `--output-limit` on the outer checks.
 `toon_encoding: "tabular_when_uniform"` declares that an array of flat objects
 with one shared key set renders as a length-marked TOON table; mixed, nested,
 or heterogeneous arrays retain the expanded representation. Quoted,
@@ -107,7 +115,8 @@ publish a row contract.
 SDK and package authors can import `PM_READ_ROW_CONTRACTS`,
 `PM_READ_ROW_JQ_SELECTOR`, and `resolveReadRowContract` from
 `@unbrained/pm-cli/sdk`. Existing package declarations are preserved only
-when `command`, `row_kind`, `row_keys`, `fields`, the conditional
+when `command`, `row_kind`, `row_keys`, optional unique non-empty
+`continuation_row_keys`, `fields`, the conditional
 `jq_selector`, and any supplied `toon_encoding` form a structurally valid row contract; malformed declarations
 are replaced by the canonical built-in contract when one applies.
 

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -15,10 +15,13 @@ Every built-in read surface uses four output dimensions: what to include, how mu
 
 The contract covers `list`, `context`, `search`, `get`, `next`, `health`, `deps`, `graph`, `history`, `activity`, `validate`, `events`, `contracts`, `comments`, `notes`, `files`, `docs`, `stats`, and `aggregate`, including list aliases and `ctx`.
 
-Row shaping follows each envelope's `row_contract.row_keys`, including
-dot-delimited nested arrays and object maps such as `graph.nodes`. Include,
-amount, repeat suppression, and cost compaction therefore operate on the same
-machine-declared rows; they do not rely on command-specific top-level keys.
+Primary row shaping follows each envelope's `row_contract.row_keys`, including
+dot-delimited arrays and object maps such as `graph.nodes`. Include, amount, and
+repeat suppression therefore remain bound to the rows the command says it
+returns. A result may additionally declare `continuation_row_keys` when a
+nested evidence collection must resume independently without redefining the
+primary rows that `--output-limit` bounds. Cost compaction may inspect both
+primary and nested collections; it does not rely on command-specific keys.
 The runtime uses that declaration internally on every read but omits the
 repeated metadata from results by default. Request
 `--output-row-contract` / `outputRowContract: true` when a consumer needs the
@@ -153,8 +156,9 @@ producer cursor, a universal output cursor, and a terminal page;
 `next_cursor` mirrors the first universal entry for ordinary one-path
 consumers. Replay the same query and budget
 with `--output-cursor <cursor>` / `outputCursor`. The cursor validates the
-command, declared row path, total, and stable row identities before slicing, so
-a mismatched or stale replay fails closed instead of skipping evidence. A
+command, declared continuation path, total, and canonical content fingerprint
+before slicing, so same-cardinality content changes and other stale replays
+fail closed instead of skipping evidence. A
 bounded recovery therefore does not require replacing a 600-token request with
 an unbounded multi-megabyte response;
 `recovery_budget_multiplier: 1` declares that each next page retains the same

package/docs/SDK.md

@@ -50,6 +50,10 @@ first-class recurrence relationships are tracked by
 Fail-closed whole-corpus reads and package-catalog output controls are tracked by
 [pm-y4aaol](../.agents/pm/issues/pm-y4aaol.toon) and
 [pm-2firut](../.agents/pm/issues/pm-2firut.toon).
+Positional command signatures, action-scoped discovery, and MCP/CLI option
+parity are tracked by [pm-ya7x55](../.agents/pm/tasks/pm-ya7x55.toon),
+[pm-2tan](../.agents/pm/issues/pm-2tan.toon), and
+[pm-y0htkd](../.agents/pm/issues/pm-y0htkd.toon).
 
 Use it for extension authoring, package authoring, command/action contract discovery, and deterministic app or CI automation. Do not import private `src/core/...` modules from external integrations or packages.
 
@@ -340,6 +344,8 @@ Command/action contract exports:
 - Execution and diagnostics contracts: `TestCommandOptions` / `TestResult` / `TestRunResult`, `TestAllCommandOptions` / `TestAllResult`, `StartBackgroundRunCommandOptions` / `StartBackgroundRunResult`, `TestRuns*CommandOptions`, `EvalOptions` / `EvalResult`, `TelemetryCommandOptions` / `TelemetrySubcommand`, and `StatsCommandOptions` / `StatsResult`.
 - Linked-test authoring primitives: `parseLinkedTestJsonEntries`, the `parseLinkedTest*` field parsers, `LINKED_TEST_PM_CONTEXT_MODE_VALUES`, `LINKED_TEST_PROTECTED_ENV_KEYS`, `classifyLinkedTestFailure`, `countFailureCategories`, and `summarizeContextPreflight` let custom hosts validate, execute, classify, and report linked tests without duplicating CLI policy.
 - Agent command primitives: `normalizeItemAddressInvocation` and `supportsItemIdAlias` project one item-id grammar across CLI adapters; `renderMissingOptionRetry`, `resolveMissingOptionPlaceholder`, and `resolveRecoveryCommandName` preserve attempted argv, derive enum/boolean/scalar recovery arity from flag contracts, and identify the actual command without mistaking a global option value for one; `createUnknownSubcommandError` provides one typed positional refusal with complete allowed values and deterministic nearest retry; `rankCommandPaths` and `scoreCommandPathMatch` provide deterministic synonym/edit-distance/substring ranking; `resolveCreateExplicitEmptyFlag` and `supportsCreateExplicitEmpty` model a considered-but-empty strict repeatable input without inventing metadata or graph edges.
+- Positional grammar primitives: `PM_COMMAND_POSITIONAL_CONTRACTS` declares every core and known-package command signature as ordered, typed slots; `PM_POSITIONAL_ACTION_CONTRACTS` promotes positional plan and assurance actions into discoverable virtual command paths with action-scoped flags, examples, and intent. `resolvePmCommandPositionalContract`, `resolvePmPositionalActionContract`, and `verifyPmCommandPositionalContracts` let custom hosts resolve or fail-closed compare the same signatures emitted by runtime contracts. The grammar receipt ratchets distinct semantic shapes through `positional_shape_budget` so a new arity cannot silently expand agent context.
+- MCP/CLI option parity primitive: `verifyToolOptionCliParity` compares one `ToolOptionFlagContract` table with its executable `CliFlagContract` table. It fails when the transport-selected canonical flag is absent or when a parameter such as `linkedFile` cannot be invoked using its kebab-case CLI spelling (`--linked-file`) canonically or through a registered alias. Core create/update parity is part of the required command-grammar gate.
 - Refusal reachability primitives: generated `PmErrorCodeContract.owned_states` declarations bind stable codes to concrete states, probe ids, entrypoints, and exit classes; `verifyPmRefusalReachability` compares those declarations with real CLI, SDK, MCP, or package observations and fails closed for missing, duplicate, wrong-entrypoint, mismatched, or undeclared probes.
 - Typed plan workflow primitives on `PmClient`: `plan`, `planCreate`, `planShow`, `planAddStep`, `planUpdateStep`, `planCompleteStep`, `planBlockStep`, `planReorderStep`, `planRemoveStep`, `planLink`, `planUnlink`, `planDecision`, `planDiscovery`, `planValidation`, `planResume`, `planApprove`, and `planMaterialize`
 - Plan contracts: `PlanSubcommand`, `PlanCommandOptions`, `PlanCommandResult`, `PlanResultPlan`, `PlanStepSummary`, `PlanShowDepth`, and `PlanTemplateName`