@unbrained/pm-cli 2026.8.19 → 2026.8.20

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

@@ -0,0 +1,185 @@
+/**
+ * @module sdk/query/projection-contracts
+ *
+ * Declares dependency-light projection vocabularies for list, get, and search
+ * so contract-only SDK imports do not initialize query runtimes or storage.
+ */
+
+!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]="5bb71ec1-7eb1-558e-a965-acd779570c2e")}catch(e){}}();
+import { ITEM_METADATA_KEY_ORDER } from "../../core/shared/item-metadata-contract.js";
+/** Stable field order for the compact list projection. */
+export const DEFAULT_COMPACT_LIST_FIELDS = [
+    "id",
+    "title",
+    "status",
+    "type",
+    "priority",
+    "parent",
+    "updated_at",
+];
+/** Stable field order for the agent-optimized brief list projection. */
+export const BRIEF_LIST_FIELDS = ["id", "status", "type", "title"];
+/** Machine-readable default projection contract for every list command. */
+export const LIST_COMMAND_DEFAULT_PROJECTIONS = {
+    list: "brief",
+    "list-all": "full",
+    "list-draft": "full",
+    "list-open": "brief",
+    "list-in-progress": "brief",
+    "list-blocked": "brief",
+    "list-closed": "full",
+    "list-canceled": "full",
+};
+const TREE_METADATA_FIELDS = [
+    "tree_depth",
+    "tree_parent",
+    "tree_children",
+    "tree_title",
+];
+/** Return every accepted list projection selector for core and runtime metadata. */
+export function listListProjectionFields(runtimeMetadataKeys = []) {
+    return [
+        ...new Set([
+            ...ITEM_METADATA_KEY_ORDER,
+            "body",
+            ...TREE_METADATA_FIELDS,
+            ...runtimeMetadataKeys,
+        ]),
+    ]
+        .flatMap((field) => [field, `item.${field}`])
+        .sort();
+}
+/** Canonical get depth values. The CLI also accepts full as an alias for deep. */
+export const GET_DEPTH_VALUES = ["brief", "standard", "deep"];
+const GET_ROOT_PROJECTION_FIELDS = [
+    "body",
+    "linked",
+    "claim_state",
+    "children",
+    "schedule",
+];
+const GET_LINKED_PROJECTION_FIELDS = [
+    "linked.files",
+    "linked.tests",
+    "linked.docs",
+];
+const GET_CLAIM_STATE_PROJECTION_FIELDS = [
+    "claim_state.claimed",
+    "claim_state.assignee",
+    "claim_state.last_claim",
+    "claim_state.last_release",
+];
+const GET_SCHEDULE_PROJECTION_FIELDS = [
+    "schedule.deadline",
+    "schedule.start_at",
+    "schedule.end_at",
+    "schedule.location",
+    "schedule.reminders",
+    "schedule.events",
+];
+/** Return every accepted get projection selector for core and runtime metadata. */
+export function listGetProjectionFields(runtimeMetadataKeys = []) {
+    const itemFields = [
+        ...new Set([
+            ...ITEM_METADATA_KEY_ORDER,
+            ...runtimeMetadataKeys,
+            "notes_count",
+            "tests_count",
+            "collection_counts",
+        ]),
+    ];
+    return [
+        ...itemFields.flatMap((field) => [field, `item.${field}`]),
+        ...GET_ROOT_PROJECTION_FIELDS,
+        ...GET_LINKED_PROJECTION_FIELDS,
+        ...GET_CLAIM_STATE_PROJECTION_FIELDS,
+        ...GET_SCHEDULE_PROJECTION_FIELDS,
+    ].sort();
+}
+/** Stable field order for compact search results. */
+export const DEFAULT_COMPACT_SEARCH_FIELDS = [
+    "id",
+    "title",
+    "status",
+    "type",
+    "priority",
+    "updated_at",
+    "score",
+    "matched_fields",
+];
+/** Search-result fields that live beside the nested item projection. */
+export const SEARCH_HIT_FIELD_KEYS = [
+    "score",
+    "matched_fields",
+    "highlights",
+];
+/** Core item fields accepted by explicit search projections. */
+export const SEARCH_ITEM_FIELD_KEYS = [
+    "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",
+];
+/** Return every accepted search projection selector for core and runtime metadata. */
+export function listSearchProjectionFields(runtimeMetadataKeys = []) {
+    const runtimeKeys = [...new Set(runtimeMetadataKeys)];
+    return [
+        ...SEARCH_HIT_FIELD_KEYS,
+        ...SEARCH_ITEM_FIELD_KEYS,
+        ...SEARCH_ITEM_FIELD_KEYS.map((field) => `item.${field}`),
+        ...runtimeKeys,
+        ...runtimeKeys.map((field) => `item.${field}`),
+    ].sort();
+}
+//# sourceMappingURL=projection-contracts.js.map
+//# debugId=5bb71ec1-7eb1-558e-a965-acd779570c2e

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

@@ -1,6 +1,7 @@
 import type { RuntimeFieldRegistry } from "../../core/schema/runtime-schema.js";
 import type { SharedItemFilterOptions } from "./item-filter-options.js";
 import type { SearchMode } from "./search-rendering.js";
+export { DEFAULT_COMPACT_SEARCH_FIELDS, SEARCH_HIT_FIELD_KEYS, SEARCH_ITEM_FIELD_KEYS, listSearchProjectionFields, } from "./projection-contracts.js";
 /** Documents the search options payload exchanged by command, SDK, and package integrations. */
 export interface SearchOptions extends SharedItemFilterOptions {
     /** Value that configures or reports mode for this contract. */
@@ -60,7 +61,7 @@ export declare function normalizeSearchPhrase(value: string): string;
 /** Parse an optional deadline filter. */
 export declare function parseSearchDeadline(raw: string | undefined, fieldLabel: string): string | undefined;
 /** Resolve mutually exclusive compact, full, or explicit-field projection. */
-export declare function parseSearchProjection(options: SearchOptions): SearchProjectionConfig;
+export declare function parseSearchProjection(options: SearchOptions, query?: string): SearchProjectionConfig;
 /** Validate explicit projection fields against core and runtime metadata. */
 export declare function validateSearchProjectionFields(projection: SearchProjectionConfig, runtimeFieldRegistry: RuntimeFieldRegistry, query?: string): void;
 /** Parse a non-empty normalized query into lexical tokens. */

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

@@ -4,83 +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]="e737cdf9-734c-5010-864f-60e8052dd9c1")}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";
 import { renderPmCommand } from "../command-line.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 { 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)
@@ -155,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);
@@ -163,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] };
@@ -178,20 +114,14 @@ export function parseSearchProjection(options) {
 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 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 allowed = new Set(allowedValues);
     const unknown = projection.fields.filter((field) => {
         const normalized = field.trim();
-        return !allowedValues.has(normalized);
+        return !allowed.has(normalized);
     });
     if (unknown.length > 0) {
         const suggestedRetryArguments = [
@@ -201,6 +131,7 @@ export function validateSearchProjectionFields(projection, runtimeFieldRegistry,
             "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",
@@ -209,7 +140,7 @@ export function validateSearchProjectionFields(projection, runtimeFieldRegistry,
                 "Use item.<field> for explicit item metadata fields, or run pm search --help for projection examples.",
             ],
             recovery: {
-                allowed_values: [...allowedValues].sort(),
+                allowed_values: allowedValues,
                 suggested_retry: renderPmCommand(suggestedRetryArguments),
                 suggested_retry_args: suggestedRetryArguments,
             },
@@ -297,4 +228,4 @@ export function resolveSearchTuning(settings) {
     };
 }
 //# sourceMappingURL=search-contracts.js.map
-//# debugId=e737cdf9-734c-5010-864f-60e8052dd9c1
+//# 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]="0582c462-43fc-563c-b209-d6e3c39948f4")}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,
     };
 }
@@ -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=0582c462-43fc-563c-b209-d6e3c39948f4
+//# debugId=c650f22f-5fcd-5489-aa9b-da11c2d1db63

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. */

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]="95764dd9-1b0d-5732-9f10-b13b334ce27d")}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]="c770afea-3eb6-5476-ba07-8ec1c5d9c699")}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";
@@ -70,6 +70,7 @@ import { acknowledgeUnknownAuthorHistoryEventsFromTransport, } from "./author-at
 import { PROFILE_SUBCOMMANDS, runProfileApply, runProfileLint, runProfileList, runProfileShow, } from "./profile.js";
 import { runHistoryRedact, } from "./history-redact.js";
 import { runMcpHistoryCompactAction, runMcpHistoryRepairAction, } from "./history-mcp.js";
+import { runMcpCloseAction, runMcpReopenAction } from "./lifecycle/mcp-actions.js";
 import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, readRuntimeStringArray as readStringArray, resolveRuntimeLimit, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction, } from "./runtime-input.js";
 import { runDeps } from "./dependencies.js";
 import { runDocs } from "./docs.js";
@@ -119,6 +120,7 @@ export { runFocus, } from "./lifecycle/focus.js";
 export { runRestore, } from "./lifecycle/restore.js";
 export { DEFAULT_TERMINAL_TRANSITION_POLICY, applyTerminalOrderingPolicy, requireTerminalReason, resolveTerminalReason, } from "./lifecycle-policy.js";
 export { runUpdate } from "./lifecycle/update.js";
+export { runReopen } from "./lifecycle/reopen.js";
 export { NEXT_OUTPUT_VALUES, runNext, } from "./query/next.js";
 export { runSearch, } from "./query/search.js";
 export { runStats, } from "./stats.js";
@@ -536,6 +538,15 @@ export class PmClient {
             ...splitFullClientMutationOptions(options),
         });
     }
+    /** Reopen terminal work as a recurrence through the canonical update path. */
+    reopen(id, reason, options = {}) {
+        return this.runTyped("item-reopen", {
+            id,
+            reason,
+            fullChangedFields: true,
+            options,
+        });
+    }
     /** 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, reason, options = {}) {
         return this.runTyped("close", {
@@ -908,6 +919,10 @@ export function create(options = {}, clientOptions = {}) {
 export function update(id, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).update(id, options);
 }
+/** Reopen terminal work as a recurrence without constructing a reusable client. */
+export function reopen(id, reason, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).reopen(id, reason, options);
+}
 /** Close an item without constructing a reusable client. */
 export function close(id, reason, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).close(id, reason, options);
@@ -1392,18 +1407,6 @@ async function runMcpUpdateAction(ctx) {
         idOnly,
     });
 }
-async function runMcpCloseAction(ctx) {
-    const { changedFields, idOnly, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
-    const closeReason = readString(ctx.args, "reason") ??
-        readString(ctx.args, "text") ??
-        readString(runnerOptions, "reason") ??
-        readString(runnerOptions, "text");
-    return projectMutationResult(await runClose(requireMcpItemId(ctx, runnerOptions), closeReason, runnerOptions, ctx.global), {
-        changedFields,
-        compactEnvelope: changedFields === "compact" && !idOnly,
-        idOnly,
-    });
-}
 function runMcpCommentsAction(ctx) {
     const commentOptions = normalizeAnnotationTransportOptions(ctx.options);
     const isListing = commentOptions.add === undefined &&
@@ -1808,6 +1811,7 @@ const SDK_ACTION_HANDLERS = {
     copy: runMcpCopyAction,
     focus: (ctx) => runFocus(ctx.id, { clear: ctx.options.clear === true || ctx.args.clear === true }, ctx.global),
     update: runMcpUpdateAction,
+    "item-reopen": runMcpReopenAction,
     restore: runMcpRestoreAction,
     claim: (ctx) => ctx.options.next === true || ctx.args.next === true
         ? runClaimNext(ctx.force, ctx.global, { ...ctx.options, ...ctx.args }, { ...ctx.options, ...ctx.args })
@@ -1940,4 +1944,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=95764dd9-1b0d-5732-9f10-b13b334ce27d
+//# debugId=c770afea-3eb6-5476-ba07-8ec1c5d9c699

package/dist/sdk/similarity.d.ts

@@ -115,6 +115,19 @@ export interface SimilarityAdvisory {
     bypassed: boolean;
     /** Shared similarity query result. */
     result: SimilarItemsResult;
+    /** Executable next action selected from the strongest matching item's lifecycle state. */
+    recovery: SimilarityRecovery;
+}
+/** Executable duplicate-intake recovery selected from the strongest match. */
+export interface SimilarityRecovery {
+    /** Whether to continue existing active work or reopen terminal work as a recurrence. */
+    action: "reuse" | "reopen";
+    /** Strongest matching canonical item. */
+    item_id: string;
+    /** Shell-form recovery command. */
+    command: string;
+    /** Tokenized recovery command for direct execution. */
+    args: string[];
 }
 /** Render compact warning tokens shared by create and copy results. */
 export declare function similarityAdvisoryWarnings(advisory: SimilarityAdvisory | undefined): string[];