@unbrained/pm-cli 2026.8.18 → 2026.8.20

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

@@ -4,82 +4,13 @@
  * 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]="d20ab01b-a8ae-5fe8-988a-d05fe87951f6")}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";
-const DEFAULT_COMPACT_SEARCH_FIELDS = [
-    "id",
-    "title",
-    "status",
-    "type",
-    "priority",
-    "updated_at",
-    "score",
-    "matched_fields",
-];
-const SEARCH_HIT_FIELD_KEYS = new Set([
-    "score",
-    "matched_fields",
-    "highlights",
-]);
-const SEARCH_ITEM_FIELD_KEYS = new Set([
-    "id",
-    "title",
-    "description",
-    "type",
-    "status",
-    "priority",
-    "tags",
-    "created_at",
-    "updated_at",
-    "deadline",
-    "assignee",
-    "author",
-    "estimated_minutes",
-    "acceptance_criteria",
-    "dependencies",
-    "comments",
-    "notes",
-    "learnings",
-    "reminders",
-    "events",
-    "files",
-    "tests",
-    "docs",
-    "close_reason",
-    "parent",
-    "reviewer",
-    "risk",
-    "confidence",
-    "sprint",
-    "release",
-    "blocked_by",
-    "blocked_reason",
-    "reporter",
-    "severity",
-    "environment",
-    "repro_steps",
-    "resolution",
-    "expected_result",
-    "actual_result",
-    "affected_version",
-    "fixed_version",
-    "component",
-    "regression",
-    "customer_impact",
-    "definition_of_ready",
-    "order",
-    "rank",
-    "goal",
-    "objective",
-    "value",
-    "impact",
-    "outcome",
-    "why_now",
-    "plan",
-]);
+import { renderPmCommand } from "../command-line.js";
+import { EXIT_CODE, PmCliError } from "../runtime-primitives.js";
+import { DEFAULT_COMPACT_SEARCH_FIELDS, listSearchProjectionFields, } from "./projection-contracts.js";
+export { DEFAULT_COMPACT_SEARCH_FIELDS, SEARCH_HIT_FIELD_KEYS, SEARCH_ITEM_FIELD_KEYS, listSearchProjectionFields, } from "./projection-contracts.js";
 /** Parse the configured search execution mode. */
 export function parseSearchMode(raw) {
     if (raw === undefined)
@@ -154,7 +85,7 @@ function parseFieldSelectors(raw) {
     return [...new Set(selectors)];
 }
 /** Resolve mutually exclusive compact, full, or explicit-field projection. */
-export function parseSearchProjection(options) {
+export function parseSearchProjection(options, query = "<query>") {
     const compactRequested = options.compact === true;
     const fullRequested = options.full === true;
     const fieldSelectors = parseFieldSelectors(options.fields);
@@ -162,7 +93,13 @@ export function parseSearchProjection(options) {
         Number(fullRequested) +
         Number(fieldSelectors !== undefined);
     if (enabledModes > 1) {
-        throw new PmCliError("Search projection options are mutually exclusive. Use one of --compact, --full, or --fields.", EXIT_CODE.USAGE);
+        throw new PmCliError("Search projection options are mutually exclusive. Use one of --compact, --full, or --fields.", EXIT_CODE.USAGE, {
+            code: "projection_options_mutually_exclusive",
+            recovery: {
+                suggested_retry: renderPmCommand(["search", query, "--full"]),
+                suggested_retry_args: ["search", query, "--full"],
+            },
+        });
     }
     if (compactRequested) {
         return { mode: "compact", fields: [...DEFAULT_COMPACT_SEARCH_FIELDS] };
@@ -174,24 +111,27 @@ 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) => [
+    const allowedValues = listSearchProjectionFields(runtimeFieldRegistry.definitions.flatMap((field) => [
         field.key,
         field.metadata_key,
     ]));
+    const allowed = new Set(allowedValues);
     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 !allowed.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, {
+            code: "unknown_field_projection",
             examples: [
                 "pm search <query> --fields id,title,status,score",
                 "pm search <query> --fields id,title,item.description,matched_fields",
@@ -199,6 +139,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,
+                suggested_retry: renderPmCommand(suggestedRetryArguments),
+                suggested_retry_args: suggestedRetryArguments,
+            },
         });
     }
 }
@@ -283,4 +228,4 @@ export function resolveSearchTuning(settings) {
     };
 }
 //# sourceMappingURL=search-contracts.js.map
-//# debugId=47576eb5-4ddf-5e04-9e1d-c961da39b754
+//# debugId=d20ab01b-a8ae-5fe8-988a-d05fe87951f6

package/dist/sdk/query/search.d.ts

@@ -183,8 +183,23 @@ export declare function collectErrorCauseCodes(error: unknown): string;
  */
 export declare function classifyImplicitSemanticFallbackReason(error: unknown): ImplicitSemanticFallbackReason;
 declare function buildExplicitSemanticFallbackWarning(requestedMode: SearchMode, error: unknown): string;
+interface VectorIndexRecoveryRegistrations {
+    commands?: readonly {
+        command: string;
+    }[];
+}
+interface VectorIndexRecovery {
+    command: string;
+    args: string[];
+    follow_up_command?: string;
+    follow_up_args?: string[];
+}
+/** Resolve an executable reindex path from the active extension capability surface. */
+export declare function resolveVectorIndexRecovery(registrations: VectorIndexRecoveryRegistrations | null): VectorIndexRecovery;
 /** Compare the vectorization-status ledger against the filtered corpus and, when the vector index is behind, emit a one-line stderr warning plus a structured `vector_index_stale:N` entry in the JSON warnings array. Best-effort: ledger read failures fall through silently — the existing semantic/hybrid fallback paths cover backend errors. */
 declare function maybeEmitVectorIndexStaleWarning(pmRoot: string, filteredDocuments: ItemDocument[], warnings: string[]): Promise<void>;
+/** Format token-efficient vector-index staleness and executable recovery warnings. */
+export declare function formatVectorIndexRecoveryWarnings(staleCount: number, recovery: VectorIndexRecovery): string[];
 /** Public contract for test only search command, shared by SDK and presentation-layer consumers. */
 export declare const _testOnlySearchCommand: {
     applyFilters: typeof applyFilters;

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]="c650f22f-5fcd-5489-aa9b-da11c2d1db63")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
@@ -128,6 +128,21 @@ function buildExplicitSemanticFallbackWarning(requestedMode, error) {
     const reason = classifyImplicitSemanticFallbackReason(error);
     return `search_${requestedMode}_fallback:${reason}:using_keyword_mode`;
 }
+/** Resolve an executable reindex path from the active extension capability surface. */
+export function resolveVectorIndexRecovery(registrations) {
+    const hasReindex = registrations?.commands?.some((registration) => registration.command.trim() === "reindex") === true;
+    return hasReindex
+        ? {
+            command: "pm reindex --mode hybrid",
+            args: ["reindex", "--mode", "hybrid"],
+        }
+        : {
+            command: "pm install search-advanced --project",
+            args: ["install", "search-advanced", "--project"],
+            follow_up_command: "pm reindex --mode hybrid",
+            follow_up_args: ["reindex", "--mode", "hybrid"],
+        };
+}
 /** Compare the vectorization-status ledger against the filtered corpus and, when the vector index is behind, emit a one-line stderr warning plus a structured `vector_index_stale:N` entry in the JSON warnings array. Best-effort: ledger read failures fall through silently — the existing semantic/hybrid fallback paths cover backend errors. */
 async function maybeEmitVectorIndexStaleWarning(pmRoot, filteredDocuments, warnings) {
     try {
@@ -142,15 +157,26 @@ async function maybeEmitVectorIndexStaleWarning(pmRoot, filteredDocuments, warni
         if (staleIds.length === 0) {
             return;
         }
-        warnings.push(`vector_index_stale:${staleIds.length}`);
+        const recovery = resolveVectorIndexRecovery(getActiveExtensionRegistrations());
+        warnings.push(...formatVectorIndexRecoveryWarnings(staleIds.length, recovery));
         /* c8 ignore start -- singular/plural warning text branches are cosmetic and validated in integration UX tests */
-        process.stderr.write(`[pm] warning: ${staleIds.length} item${staleIds.length === 1 ? " is" : "s are"} new or modified since the last reindex and ${staleIds.length === 1 ? "is" : "are"} NOT in the semantic index yet — they will be missing from semantic/hybrid results until you run 'pm reindex --mode hybrid'. (Write-time embedding is governed by search.mutation_refresh_policy; staleness means the embed was skipped, failed, or the backend was unreachable.)\n`);
+        process.stderr.write(`[pm] warning: ${staleIds.length} item${staleIds.length === 1 ? " is" : "s are"} new or modified since the last reindex and ${staleIds.length === 1 ? "is" : "are"} NOT in the semantic index yet — run '${recovery.command}'${recovery.follow_up_command ? `, then '${recovery.follow_up_command}'` : ""}. (Write-time embedding is governed by search.mutation_refresh_policy; staleness means the embed was skipped, failed, or the backend was unreachable.)\n`);
         /* c8 ignore stop */
     }
     catch {
         // Best-effort: missing/unreadable ledger is not a query-blocking concern.
     }
 }
+/** Format token-efficient vector-index staleness and executable recovery warnings. */
+export function formatVectorIndexRecoveryWarnings(staleCount, recovery) {
+    return [
+        `vector_index_stale:${staleCount}`,
+        `vector_index_recovery:${recovery.args.join(" ")}`,
+        ...(recovery.follow_up_args
+            ? [`vector_index_recovery_follow_up:${recovery.follow_up_args.join(" ")}`]
+            : []),
+    ];
+}
 /** Public contract for test only search command, shared by SDK and presentation-layer consumers. */
 export const _testOnlySearchCommand = {
     applyFilters,
@@ -1539,7 +1565,7 @@ function prepareSearchInput(rawQuery, rawOptions) {
         tokens: parseSearchTokens(query),
         normalizedQuery: normalizeSearchPhrase(query),
         limit: parseLimit(options.limit),
-        projection: parseSearchProjection(options),
+        projection: parseSearchProjection(options, rawQuery),
         modeWasExplicit: typeof options.mode === "string" && options.mode.trim().length > 0,
     };
 }
@@ -1552,7 +1578,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 +1987,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=c650f22f-5fcd-5489-aa9b-da11c2d1db63

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-primitives.d.ts

@@ -72,7 +72,7 @@ export { splitCommaList } from "../core/shared/split-comma-list.js";
 export { compareTimestampStrings, nowIso, resolveIsoOrRelative, } from "../core/shared/time.js";
 export { migrateItemFilesToFormat } from "../core/store/item-format-migration.js";
 export { type CachedDocumentCandidate, listAllDocumentCandidatesCached, } from "../core/store/item-metadata-cache.js";
-export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
+export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, mutateItemWithHistoryContext, readLocatedItem, } from "../core/store/item-store.js";
 export { isTerminalPlanMode, shouldCompletePlanOnClose, } from "../core/item/plan-lifecycle.js";
 export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 export { persistSelectedItemFormat, readSettings, readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";

package/dist/sdk/runtime-primitives.js

@@ -7,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]="a678b9f8-ba36-5127-877f-96bb4acc38c5")}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]="1bcfba24-e761-571c-96e6-36bbc12d2814")}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";
@@ -73,7 +73,7 @@ export { splitCommaList } from "../core/shared/split-comma-list.js";
 export { compareTimestampStrings, nowIso, resolveIsoOrRelative, } from "../core/shared/time.js";
 export { migrateItemFilesToFormat } from "../core/store/item-format-migration.js";
 export { listAllDocumentCandidatesCached, } from "../core/store/item-metadata-cache.js";
-export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
+export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, mutateItemWithHistoryContext, readLocatedItem, } from "../core/store/item-store.js";
 export { isTerminalPlanMode, shouldCompletePlanOnClose, } from "../core/item/plan-lifecycle.js";
 export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 export { persistSelectedItemFormat, readSettings, readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";
@@ -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=a678b9f8-ba36-5127-877f-96bb4acc38c5
+//# debugId=1bcfba24-e761-571c-96e6-36bbc12d2814

package/dist/sdk/runtime.d.ts

@@ -23,6 +23,7 @@ import { type AggregateOptions, type AggregateResult } from "./query/aggregate.j
 import { type UpgradeCommandOptions, type UpgradeResult } from "./governance/upgrade.js";
 import { type CreateResult } from "./lifecycle/create.js";
 import { type UpdateResult } from "./lifecycle/update.js";
+import type { ReopenCommandOptions, ReopenResult } from "./lifecycle/reopen.js";
 import { type PlanCommandOptions, type PlanCommandResult, type PlanSubcommand } from "./lifecycle/plan.js";
 import { type ContextOptions, type ContextResult } from "./query/context.js";
 import { type NextOptions, type NextResult } from "./query/next.js";
@@ -93,6 +94,7 @@ export { runFocus, type FocusOptions, type FocusResult, } from "./lifecycle/focu
 export { runRestore, type RestoreCommandOptions, type RestoreResult, } from "./lifecycle/restore.js";
 export { DEFAULT_TERMINAL_TRANSITION_POLICY, applyTerminalOrderingPolicy, requireTerminalReason, resolveTerminalReason, type CloseOperationOptions, type CloseOperationResult, type TerminalOrderingMutation, type TerminalReasonInput, type TerminalReasonResolution, type TerminalReasonSource, type TerminalTransitionPolicy, } from "./lifecycle-policy.js";
 export { runUpdate, type UpdateCommandOptions } from "./lifecycle/update.js";
+export { runReopen, type PreviousTerminalEvidence, type RecurrenceReceipt, type ReopenCommandOptions, type ReopenResult } from "./lifecycle/reopen.js";
 export { NEXT_OUTPUT_VALUES, runNext, type NextActionableItem, type NextBlockerRef, type NextOptions, type NextOutputFormat, type NextRecommendation, type NextResult, } from "./query/next.js";
 export { runSearch, type SearchCompactResult, type SearchHit, type SearchHitHighlight, type SearchMatchMode, type SearchOptions, type SearchResult, type SearchResultItem, type SearchVerboseResult, } from "./query/search.js";
 export { runStats, type StatsCommandOptions, type StatsResult, } from "./stats.js";
@@ -293,6 +295,8 @@ export declare class PmClient {
     create(options?: PmCreateActionOptions): Promise<CreateResult>;
     /** Update an item using the same mutation path as `pm update`. Options are contract-typed (pm-x29o): unknown keys and non-scalar values fail `tsc`; runtime-schema custom fields go through the repeatable `field` option, and {@link PmClient.run} stays the wide escape hatch. */
     update(id: string, options?: PmUpdateActionOptions): Promise<UpdateResult>;
+    /** Reopen terminal work as a recurrence through the canonical update path. */
+    reopen(id: string, reason: string, options?: ReopenCommandOptions): Promise<ReopenResult>;
     /** Close an item using the same mutation path as `pm close`. Options are contract-typed (pm-x29o); the close reason is the positional parameter, so the option bag omits `reason`/`text`. */
     close(id: string, reason: string, options?: PmClientCloseActionOptions): Promise<CloseResult>;
     /** Claim an item using the same mutation path as `pm claim`. */
@@ -469,6 +473,8 @@ export declare function historyCompactBulk(options: HistoryCompactBulkCommandOpt
 export declare function create(options?: PmCreateActionOptions, clientOptions?: PmClientOptions): Promise<CreateResult>;
 /** Update an item without constructing a reusable client. */
 export declare function update(id: string, options?: PmUpdateActionOptions, clientOptions?: PmClientOptions): Promise<UpdateResult>;
+/** Reopen terminal work as a recurrence without constructing a reusable client. */
+export declare function reopen(id: string, reason: string, options?: ReopenCommandOptions, clientOptions?: PmClientOptions): Promise<ReopenResult>;
 /** Close an item without constructing a reusable client. */
 export declare function close(id: string, reason: string, options?: PmClientCloseActionOptions, clientOptions?: PmClientOptions): Promise<CloseResult>;
 /** Claim an item without constructing a reusable client. */