@unbrained/pm-cli 2026.8.18 → 2026.8.20

package/dist/sdk/init-agent-guidance.js

@@ -4,7 +4,7 @@
  * Implements the pm init agent guidance 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]="b7c97e30-02c8-547c-b3db-c6c59e662b54")}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]="e404796d-439b-5f4c-9330-5b12ff41d7b2")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import readline from "node:readline/promises";
@@ -91,14 +91,14 @@ function findGuidanceBlockRange(content) {
 function hasGuidanceMarker(content) {
     return findGuidanceBlockRange(content) !== null;
 }
-function buildAgentGuidanceBlock(lineEnding) {
+function buildAgentGuidanceBlock(lineEnding, projectTestCommand = "<your project test command>") {
     const lines = [
         AGENT_GUIDANCE_START_MARKER,
         "## pm Workflow (Agent Quickstart)",
         "",
         '- Orient before mutate: `pm context --limit 10`, `pm search "<keywords>" --limit 10`, `pm list --status open --limit 20`.',
         "- Claim and execute: `pm claim <id>` then `pm update <id> --status in_progress`.",
-        '- Link evidence while coding: `pm files <id> --add ...`, `pm docs <id> --add ...`, `pm test <id> --add command="node scripts/run-tests.mjs test -- ..."`.',
+        `- Link evidence while coding: \`pm files <id> --add ...\`, \`pm docs <id> --add ...\`, \`pm test <id> --add command="${projectTestCommand}"\`.`,
         '- Verify and close: `pm test <id> --run --progress`, `pm close <id> "<evidence>" --validate-close warn`, `pm release <id>`.',
         "- Author identity is automatic for supported agent harnesses; use `--author` only for an explicit override.",
         "",
@@ -107,9 +107,9 @@ function buildAgentGuidanceBlock(lineEnding) {
     ];
     return lines.join(lineEnding);
 }
-function upsertAgentGuidanceBlock(existingContent) {
+function upsertAgentGuidanceBlock(existingContent, projectTestCommand = "<your project test command>") {
     const lineEnding = detectLineEnding(existingContent);
-    const nextBlock = buildAgentGuidanceBlock(lineEnding);
+    const nextBlock = buildAgentGuidanceBlock(lineEnding, projectTestCommand);
     const existingRange = findGuidanceBlockRange(existingContent);
     if (existingRange) {
         const trailingContent = existingContent.slice(existingRange.end_index);
@@ -135,6 +135,65 @@ function upsertAgentGuidanceBlock(existingContent) {
         changed: nextContent !== existingContent,
     };
 }
+/** Resolve an executable linked-test command from a target repository's own files. */
+export async function resolveProjectTestCommand(projectRoot) {
+    if (await pathExists(path.join(projectRoot, "scripts", "run-tests.mjs"))) {
+        return "node scripts/run-tests.mjs test";
+    }
+    let packageDocument;
+    try {
+        packageDocument = JSON.parse(await fs.readFile(path.join(projectRoot, "package.json"), "utf8"));
+    }
+    catch {
+        return "<your project test command>";
+    }
+    const manifest = normalizeProjectPackageManifest(packageDocument);
+    if (manifest === undefined) {
+        return "<your project test command>";
+    }
+    const packageManager = manifest.packageManager?.split("@")[0];
+    if (packageManager === "pnpm") {
+        return "pnpm test";
+    }
+    if (packageManager === "bun") {
+        return "bun run test";
+    }
+    if (packageManager === "yarn") {
+        return "yarn test";
+    }
+    if (packageManager === "npm")
+        return "npm test";
+    if (await pathExists(path.join(projectRoot, "pnpm-lock.yaml"))) {
+        return "pnpm test";
+    }
+    if ((await pathExists(path.join(projectRoot, "bun.lock"))) ||
+        (await pathExists(path.join(projectRoot, "bun.lockb")))) {
+        return "bun run test";
+    }
+    if (await pathExists(path.join(projectRoot, "yarn.lock")))
+        return "yarn test";
+    return "npm test";
+}
+/** Validate the minimal package manifest shape needed for executable test guidance. */
+function normalizeProjectPackageManifest(value) {
+    if (typeof value !== "object" || value === null || !("scripts" in value)) {
+        return undefined;
+    }
+    const scripts = value.scripts;
+    if (typeof scripts !== "object" ||
+        scripts === null ||
+        !("test" in scripts) ||
+        typeof scripts.test !== "string" ||
+        scripts.test.trim().length === 0) {
+        return undefined;
+    }
+    return {
+        scripts: { test: scripts.test },
+        ...("packageManager" in value && typeof value.packageManager === "string"
+            ? { packageManager: value.packageManager }
+            : {}),
+    };
+}
 function resolveProjectRoot(pmRoot, cwd) {
     const parent = path.dirname(pmRoot);
     if (path.basename(pmRoot) === "pm" && path.basename(parent) === ".agents") {
@@ -240,10 +299,10 @@ function applyAgentGuidanceState(settings, currentState) {
     }
     return { changed, state: currentState };
 }
-async function writeGuidanceFile(filePath) {
+async function writeGuidanceFile(filePath, projectRoot = path.dirname(filePath)) {
     const exists = await pathExists(filePath);
     const currentContent = exists ? await fs.readFile(filePath, "utf8") : "";
-    const nextContent = upsertAgentGuidanceBlock(currentContent);
+    const nextContent = upsertAgentGuidanceBlock(currentContent, await resolveProjectTestCommand(projectRoot));
     if (!nextContent.changed) {
         return { changed: false, warnings: [] };
     }
@@ -292,7 +351,7 @@ async function addAgentGuidanceBlockIfMissing(flow, context) {
     if (context.presentBefore) {
         return;
     }
-    const writeResult = await writeGuidanceFile(context.targetPath);
+    const writeResult = await writeGuidanceFile(context.targetPath, context.projectRoot);
     flow.warnings.push(...writeResult.warnings);
     if (writeResult.changed) {
         flow.applied = true;
@@ -413,6 +472,7 @@ export async function runInitAgentGuidance(options) {
         targetRelativePath,
         checkedFiles,
         presentBefore,
+        projectRoot,
     });
     const stateUpdate = applyAgentGuidanceState(options.settings, flow.state);
     scans = await refreshGuidanceScansAfterApply(flow.applied, scans, projectRoot);
@@ -434,4 +494,4 @@ export async function runInitAgentGuidance(options) {
     };
 }
 //# sourceMappingURL=init-agent-guidance.js.map
-//# debugId=b7c97e30-02c8-547c-b3db-c6c59e662b54
+//# debugId=e404796d-439b-5f4c-9330-5b12ff41d7b2

package/dist/sdk/lifecycle/mcp-actions.d.ts

@@ -0,0 +1,18 @@
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+/** Minimal generic dispatch context consumed by lifecycle mutation adapters. */
+export interface LifecycleMutationActionContext {
+    /** Flat MCP/action arguments. */
+    args: Record<string, unknown>;
+    /** Normalized command option bag. */
+    options: Record<string, unknown>;
+    /** Item id resolved from flat arguments, when present. */
+    id: string | undefined;
+    /** Normalized transport-level force override. */
+    force?: boolean;
+    /** Presentation-neutral global command options. */
+    global: GlobalOptions;
+}
+/** Dispatch close through the shared MCP mutation compaction contract. */
+export declare function runMcpCloseAction(context: LifecycleMutationActionContext): Promise<unknown>;
+/** Dispatch recurrence through the shared MCP mutation compaction contract. */
+export declare function runMcpReopenAction(context: LifecycleMutationActionContext): Promise<unknown>;

package/dist/sdk/lifecycle/mcp-actions.js

@@ -0,0 +1,52 @@
+/**
+ * @module sdk/runtime-mutation-actions
+ *
+ * Keeps lifecycle-specific MCP mutation adapters outside the generic runtime
+ * dispatcher while preserving the shared token-efficient result projection.
+ */
+
+!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]="55869854-565d-52d2-8dca-b66aade074bb")}catch(e){}}();
+import { projectMutationResult } from "../../core/output/mutation-projection.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { runClose } from "./close.js";
+import { runReopen } from "./reopen.js";
+import { readRuntimeString, withMutationCompaction } from "../runtime-input.js";
+function requireLifecycleItemId(context, options) {
+    const id = context.id ?? readRuntimeString(options, "id");
+    if (!id) {
+        throw new PmCliError("Missing required argument: id", 64);
+    }
+    return id;
+}
+function readLifecycleReason(context, options) {
+    return (readRuntimeString(context.args, "reason") ??
+        readRuntimeString(context.args, "text") ??
+        readRuntimeString(options, "reason") ??
+        readRuntimeString(options, "text"));
+}
+/** Dispatch close through the shared MCP mutation compaction contract. */
+export async function runMcpCloseAction(context) {
+    const { changedFields, idOnly, runnerOptions } = withMutationCompaction(context.args, context.options);
+    return projectMutationResult(await runClose(requireLifecycleItemId(context, runnerOptions), readLifecycleReason(context, runnerOptions), {
+        ...runnerOptions,
+        force: context.force === true || runnerOptions.force === true,
+    }, context.global), {
+        changedFields,
+        compactEnvelope: changedFields === "compact" && !idOnly,
+        idOnly,
+    });
+}
+/** Dispatch recurrence through the shared MCP mutation compaction contract. */
+export async function runMcpReopenAction(context) {
+    const { changedFields, idOnly, runnerOptions } = withMutationCompaction(context.args, context.options);
+    return projectMutationResult(await runReopen(requireLifecycleItemId(context, runnerOptions), readLifecycleReason(context, runnerOptions) ?? "", {
+        ...runnerOptions,
+        force: context.force === true || runnerOptions.force === true,
+    }, context.global), {
+        changedFields,
+        compactEnvelope: changedFields === "compact" && !idOnly,
+        idOnly,
+    });
+}
+//# sourceMappingURL=mcp-actions.js.map
+//# debugId=55869854-565d-52d2-8dca-b66aade074bb

package/dist/sdk/lifecycle/reopen.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @module sdk/lifecycle/reopen
+ *
+ * Reopens terminal work as a recurrence while preserving immutable closure
+ * evidence and delegating every state change to the canonical update pipeline.
+ */
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { type PreviousTerminalEvidence } from "./update.js";
+export type { PreviousTerminalEvidence } from "./update.js";
+/** Options accepted by the SDK and `pm item reopen` recurrence primitive. */
+export interface ReopenCommandOptions {
+    /** Active target status; only the workspace open or in-progress status is allowed. */
+    status?: string;
+    /** Explicit mutation author override. */
+    author?: string;
+    /** Optional human-readable history message in addition to structured recurrence context. */
+    message?: string;
+    /** Override an ownership or stale-lock conflict. */
+    force?: boolean;
+}
+/** Structured recurrence receipt returned by every presentation surface. */
+export interface RecurrenceReceipt {
+    /** Required reason that the terminal work became active again. */
+    reason: string;
+    /** Terminal status observed while holding the item lock. */
+    from_status: string;
+    /** Active status written through the update pipeline. */
+    to_status: string;
+    /** Prior terminal evidence retained in immutable history. */
+    previous_terminal: PreviousTerminalEvidence;
+}
+/** Result returned after a terminal item is reopened. */
+export interface ReopenResult {
+    /** Reopened item metadata. */
+    item: Record<string, unknown>;
+    /** Fields changed by the canonical update pipeline. */
+    changed_fields: string[];
+    /** Non-fatal mutation and extension warnings. */
+    warnings: string[];
+    /** Immutable recurrence transition receipt. */
+    recurrence: RecurrenceReceipt;
+}
+/** Reopen terminal work through the canonical update mutation and history path. */
+export declare function runReopen(id: string, reason: string, options: ReopenCommandOptions, global: GlobalOptions): Promise<ReopenResult>;

package/dist/sdk/lifecycle/reopen.js

@@ -0,0 +1,69 @@
+
+!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]="08dcee99-5572-5133-b76a-6a50e4e292e7")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { normalizeStatusInput } from "../../core/item/status.js";
+import { resolveRuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
+import { resolvePmRoot } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+import { resolveStartTaskInProgressStatus } from "../start-task-status.js";
+import { runReopenUpdate, } from "./update.js";
+/** Reopen terminal work through the canonical update mutation and history path. */
+export async function runReopen(id, reason, options, global) {
+    const normalizedReason = reason.trim();
+    if (normalizedReason.length === 0) {
+        throw new PmCliError("pm item reopen requires a non-empty recurrence reason.", EXIT_CODE.USAGE, {
+            code: "reopen_reason_required",
+            required: "Describe why the terminal work became active again.",
+            recovery: {
+                suggested_retry: `pm item reopen ${id} "<recurrence reason>"`,
+                suggested_retry_args: ["item", "reopen", id, "<recurrence reason>"],
+            },
+        });
+    }
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    const statusRegistry = resolveRuntimeStatusRegistry((await readSettings(pmRoot)).schema);
+    const openStatus = statusRegistry.open_status;
+    const inProgressStatus = resolveStartTaskInProgressStatus(statusRegistry);
+    const requestedStatus = options.status ?? openStatus;
+    const targetStatus = normalizeStatusInput(requestedStatus, statusRegistry) ?? requestedStatus;
+    if (targetStatus !== openStatus && targetStatus !== inProgressStatus) {
+        throw new PmCliError(`Reopen target status must be ${openStatus} or ${inProgressStatus}; received ${requestedStatus}.`, EXIT_CODE.USAGE, {
+            code: "reopen_target_status_invalid",
+            required: "Choose the workspace open or in-progress lifecycle status.",
+            recovery: {
+                allowed_values: [...new Set([openStatus, inProgressStatus])],
+                suggested_retry: `pm item reopen ${id} "${normalizedReason}" --status ${openStatus}`,
+                suggested_retry_args: [
+                    "item",
+                    "reopen",
+                    id,
+                    normalizedReason,
+                    "--status",
+                    openStatus,
+                ],
+            },
+        });
+    }
+    const update = await runReopenUpdate(id, {
+        status: targetStatus,
+        unset: [
+            "close-reason",
+            "resolution",
+            "expected-result",
+            "actual-result",
+            "fixed-version",
+        ],
+        author: options.author,
+        message: options.message,
+        force: options.force,
+    }, global, normalizedReason);
+    return {
+        item: update.item,
+        changed_fields: update.changed_fields,
+        warnings: update.warnings,
+        recurrence: update.lifecycle_transition,
+    };
+}
+//# sourceMappingURL=reopen.js.map
+//# debugId=08dcee99-5572-5133-b76a-6a50e4e292e7

package/dist/sdk/lifecycle/update.d.ts

@@ -67,6 +67,35 @@ export interface UpdateResult {
     /** Value that configures or reports warnings for this contract. */
     warnings: string[];
 }
+/** Terminal evidence captured atomically before a recurrence transition. */
+export interface PreviousTerminalEvidence {
+    /** Prior close reason, when recorded. */
+    close_reason?: string;
+    /** Prior structured resolution, when recorded. */
+    resolution?: string;
+    /** Prior expected result, when recorded. */
+    expected_result?: string;
+    /** Prior actual result, when recorded. */
+    actual_result?: string;
+    /** Prior fixed version, when recorded. */
+    fixed_version?: string;
+}
+/** Internal update-path receipt consumed by the public recurrence primitive. */
+export interface ReopenUpdateReceipt {
+    /** Recurrence reason stored in immutable history context. */
+    reason: string;
+    /** Terminal status observed while holding the item lock. */
+    from_status: string;
+    /** Active status written by the update path. */
+    to_status: string;
+    /** Terminal evidence removed from active metadata but retained in history. */
+    previous_terminal: PreviousTerminalEvidence;
+}
+/** Update result carrying the recurrence receipt produced by the locked transition. */
+export interface ReopenUpdateResult extends UpdateResult {
+    /** Lifecycle-specific receipt populated by the recurrence primitive. */
+    lifecycle_transition: ReopenUpdateReceipt;
+}
 declare function normalizeLegacyNoneUpdateOptions(options: UpdateCommandOptions): UpdateCommandOptions;
 declare function parseUpdateUnsetTargets(raw: string[] | undefined, runtimeFieldRegistry?: RuntimeFieldRegistry, extensionFieldNames?: readonly string[]): {
     metadataKeys: Set<string>;
@@ -139,6 +168,8 @@ type UpdateStatusMutationContext = Pick<UpdateMutationContext, "options" | "stat
 declare function applyStatusAndCloseReasonMutations(document: ItemDocument, context: UpdateStatusMutationContext, previousStatusNormalized: string, changedFields: string[]): void;
 /** Implements run update for the public runtime surface of this module. */
 export declare function runUpdate(id: string, options: UpdateCommandOptions, global: GlobalOptions): Promise<UpdateResult>;
+/** Execute a recurrence transition through the exact atomic update pipeline. */
+export declare function runReopenUpdate(id: string, options: UpdateCommandOptions, global: GlobalOptions, recurrenceReason: string): Promise<ReopenUpdateResult>;
 /** Public contract for test only update command, shared by SDK and presentation-layer consumers. */
 export declare const _testOnlyUpdateCommand: {
     applyStatusAndCloseReasonMutations: typeof applyStatusAndCloseReasonMutations;

package/dist/sdk/lifecycle/update.js

@@ -4,8 +4,9 @@
  * Implements the pm update 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]="a421c150-13a9-5334-85a4-5b3199a5d2c7")}catch(e){}}();
-import { pathExists, COMMON_MUTATION_COMMAND_OPTION_KEYS, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, normalizeItemId, toItemRecord, buildInvalidTypeError, assertParentReferenceIsNotSelf, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, isTerminalStatus, collectRuntimeUpdateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, describeAllowedTransitions, evaluateTransition, resolveTypeWorkflows, EXIT_CODE, PmCliError, stableValueEquals, resolveIsoOrRelative, getActiveExtensionRegistrations, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, buildItemNotFoundError, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+!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]="3ab4f16d-ce37-546e-a2f6-0495fd1967c7")}catch(e){}}();
+import { pathExists, COMMON_MUTATION_COMMAND_OPTION_KEYS, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, normalizeItemId, toItemRecord, buildInvalidTypeError, assertParentReferenceIsNotSelf, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, isTerminalStatus, collectRuntimeUpdateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, describeAllowedTransitions, evaluateTransition, resolveTypeWorkflows, EXIT_CODE, PmCliError, stableValueEquals, resolveIsoOrRelative, getActiveExtensionRegistrations, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+import { mutateItemWithHistoryContextResolver } from "../../core/store/item-store.js";
 import { runClose } from "./close.js";
 import { normalizeRiskInput, normalizeSeverityInput, parseConfidenceInput, parseRegressionInput, } from "./metadata-normalizers.js";
 import { applyLegacyNoneCollectionNormalizers, createLegacyNoneCollectionNormalizers, assertNoLegacyNoneToken, assertNoLegacyNoneTokens, isLegacyNoneToken, } from "./legacy-none-tokens.js";
@@ -1214,8 +1215,8 @@ function applyStatusMutation(document, context, statusInput, previousStatusNorma
         changedFields.push("closed_at", "completed_at");
         return;
     }
-    if (status !== context.statusRegistry.close_status &&
-        previousStatusNormalized === context.statusRegistry.close_status &&
+    if (!isTerminalStatus(status, context.statusRegistry) &&
+        isTerminalStatus(previousStatusNormalized, context.statusRegistry) &&
         document.metadata.closed_at !== undefined) {
         delete document.metadata.closed_at;
         changedFields.push("closed_at");
@@ -1254,8 +1255,8 @@ function applyCloseReasonMutations(document, context, previousStatusNormalized,
         return;
     }
     if (context.options.status !== undefined &&
-        previousStatusNormalized === context.statusRegistry.close_status &&
-        document.metadata.status !== context.statusRegistry.canceled_status &&
+        isTerminalStatus(previousStatusNormalized, context.statusRegistry) &&
+        !isTerminalStatus(document.metadata.status, context.statusRegistry) &&
         document.metadata.close_reason !== undefined) {
         delete document.metadata.close_reason;
         changedFields.push("close_reason");
@@ -1700,7 +1701,7 @@ function mutateUpdateDocument(document, context) {
     return { changedFields: actualChangedFields, warnings };
 }
 /** Implements run update for the public runtime surface of this module. */
-export async function runUpdate(id, options, global) {
+async function runUpdateWithContext(id, options, global, execution = {}) {
     options = await resolveStdinUpdateOptions(options);
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
     await assertUpdateTrackerInitialized(pmRoot);
@@ -1820,23 +1821,32 @@ export async function runUpdate(id, options, global) {
     let graphBeforeUpdate = fieldFlags.dep || fieldFlags.depRemove || fieldFlags.blockedBy
         ? await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema)
         : undefined;
-    const result = await mutateItem({
+    let lifecycleTransition;
+    let recurrenceHistoryContext;
+    const result = await mutateItemWithHistoryContextResolver({
         pmRoot,
         settings,
         typeToFolder: typeRegistry.type_to_folder,
         id,
-        op: options.ownershipMetadataBypass === true ||
-            options.ownershipDependencyBypass === true
-            ? "update_ownership_bypass"
-            : "update",
+        op: resolveUpdateHistoryOperation(options, execution),
         author,
         message: options.message,
+        resolveHistoryContext: () => recurrenceHistoryContext,
         force: options.force,
         bypassAssigneeConflict: options.ownershipMetadataBypass === true ||
             options.ownershipDependencyBypass === true,
         extensionFieldNames,
         skipNoop: true,
         mutate(document) {
+            lifecycleTransition = prepareRecurrenceTransition({
+                document,
+                recurrenceReason: execution.recurrenceReason,
+                requestedStatus: options.status,
+                statusRegistry,
+            });
+            recurrenceHistoryContext = lifecycleTransition
+                ? { recurrence: lifecycleTransition }
+                : undefined;
             graphBeforeUpdate = graphBeforeUpdate?.map((item) => item.id === document.metadata.id
                 ? structuredClone(document.metadata)
                 : item);
@@ -1880,8 +1890,80 @@ export async function runUpdate(id, options, global) {
             ...orderingCycleWarnings,
             ...result.warnings,
         ],
+        ...(lifecycleTransition === undefined
+            ? {}
+            : { lifecycle_transition: lifecycleTransition }),
     };
 }
+/** Resolve the immutable operation name for ordinary, bypass, and recurrence updates. */
+function resolveUpdateHistoryOperation(options, execution) {
+    if (options.ownershipMetadataBypass === true ||
+        options.ownershipDependencyBypass === true) {
+        return "update_ownership_bypass";
+    }
+    return execution.recurrenceReason === undefined ? "update" : "reopen";
+}
+/** Validate and capture a terminal-to-active recurrence while the item lock is held. */
+function prepareRecurrenceTransition(params) {
+    if (params.recurrenceReason === undefined) {
+        return undefined;
+    }
+    const fromStatus = normalizeStatusInput(params.document.metadata.status, params.statusRegistry) ?? params.document.metadata.status;
+    if (!isTerminalStatus(fromStatus, params.statusRegistry)) {
+        throw new PmCliError(`Item ${params.document.metadata.id} is already active with status ${fromStatus}; recurrence transitions require a terminal item.`, EXIT_CODE.CONFLICT, {
+            code: "item_already_active",
+            reason: "recurrence_requires_terminal_item",
+            required: "Use item reopen only for a terminal item whose work has recurred.",
+            why: "Appending a recurrence event to active work would corrupt lifecycle history.",
+            recovery: {
+                suggested_retry: `pm get ${params.document.metadata.id} --full`,
+                suggested_retry_args: ["get", params.document.metadata.id, "--full"],
+            },
+            nextSteps: [
+                `Inspect the active item with: pm get ${params.document.metadata.id} --full`,
+                `Continue the existing work with: pm update ${params.document.metadata.id} ...`,
+            ],
+        });
+    }
+    const requestedStatus = params.requestedStatus ?? params.statusRegistry.open_status;
+    const toStatus = normalizeStatusInput(requestedStatus, params.statusRegistry) ??
+        requestedStatus;
+    const metadata = toItemRecord(params.document.metadata);
+    const previousTerminal = Object.fromEntries([
+        "close_reason",
+        "resolution",
+        "expected_result",
+        "actual_result",
+        "fixed_version",
+    ].flatMap((key) => {
+        const value = metadata[key];
+        return typeof value === "string" ? [[key, value]] : [];
+    }));
+    return {
+        reason: params.recurrenceReason,
+        from_status: fromStatus,
+        to_status: toStatus,
+        previous_terminal: previousTerminal,
+    };
+}
+/** Implements run update for the public runtime surface of this module. */
+export async function runUpdate(id, options, global) {
+    return runUpdateWithContext(id, options, global);
+}
+/** Execute a recurrence transition through the exact atomic update pipeline. */
+export async function runReopenUpdate(id, options, global, recurrenceReason) {
+    const result = await runUpdateWithContext(id, options, global, {
+        recurrenceReason,
+    });
+    if (result.lifecycle_transition === undefined) {
+        throw new PmCliError(`Item ${id} did not produce the required recurrence receipt.`, EXIT_CODE.GENERIC_FAILURE, {
+            code: "reopen_receipt_missing",
+            reason: "recurrence_transition_not_recorded",
+            required: "A successful reopen must return the terminal-to-active lifecycle transition recorded in immutable history.",
+        });
+    }
+    return { ...result, lifecycle_transition: result.lifecycle_transition };
+}
 /* c8 ignore stop */
 /** Public contract for test only update command, shared by SDK and presentation-layer consumers. */
 export const _testOnlyUpdateCommand = {
@@ -1900,4 +1982,4 @@ export const _testOnlyUpdateCommand = {
     resolveRuntimeUnsetDefinition: (token, registry) => resolveRuntimeUnsetFieldDefinition(token, "update", registry),
 };
 //# sourceMappingURL=update.js.map
-//# debugId=a421c150-13a9-5334-85a4-5b3199a5d2c7
+//# debugId=3ab4f16d-ce37-546e-a2f6-0495fd1967c7

package/dist/sdk/output-projection.d.ts

@@ -33,6 +33,8 @@ export interface ReadRowContract {
     row_kind: "collection" | "none";
     /** Dot-delimited paths to array or object-map collections containing iterable result rows. */
     row_keys: string[];
+    /** Optional nested collections that are independently resumable without redefining primary result rows. */
+    continuation_row_keys?: string[];
     /** Whether the command accepts an explicit row-field projection. */
     fields: "supported" | "unsupported";
     /** Universal jq expression that iterates every declared collection path. */

package/dist/sdk/output-projection.js

@@ -4,7 +4,7 @@
  * Declares machine-readable field-group omissions for bounded command results.
  */
 
-!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]="d059aa19-3822-5ff4-b4be-e2be8f537d1e")}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]="8ffd2cd5-8b7e-5ae1-a0c6-aab488edb73c")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 const MATERIAL_FIELD_GROUPS_BY_RESULT = new WeakMap();
@@ -161,15 +161,21 @@ const READ_ROW_TOON_ENCODINGS = new Set([
 ]);
 const READ_ROW_KINDS = new Set(["collection", "none"]);
 const READ_ROW_FIELD_MODES = new Set(["supported", "unsupported"]);
+function isUniqueNonEmptyStringArray(value, allowEmpty) {
+    return (Array.isArray(value) &&
+        (allowEmpty || value.length > 0) &&
+        value.every((entry) => typeof entry === "string" && entry.length > 0) &&
+        new Set(value).size === value.length);
+}
 /** Return whether an unknown value is a structurally valid row declaration. */
 export function isReadRowContract(value) {
     return (isRecord(value) &&
         typeof value.command === "string" &&
         value.command.trim().length > 0 &&
         READ_ROW_KINDS.has(value.row_kind) &&
-        Array.isArray(value.row_keys) &&
-        value.row_keys.every((key) => typeof key === "string" && key.length > 0) &&
-        new Set(value.row_keys).size === value.row_keys.length &&
+        isUniqueNonEmptyStringArray(value.row_keys, true) &&
+        (value.continuation_row_keys === undefined ||
+            isUniqueNonEmptyStringArray(value.continuation_row_keys, false)) &&
         READ_ROW_FIELD_MODES.has(value.fields) &&
         READ_ROW_TOON_ENCODINGS.has(value.toon_encoding) &&
         (value.row_kind === "collection"
@@ -414,4 +420,4 @@ export function attachOutputOmissionReceipt(command, result) {
         : { ...disclosedResult, omission_receipt: receipt };
 }
 //# sourceMappingURL=output-projection.js.map
-//# debugId=d059aa19-3822-5ff4-b4be-e2be8f537d1e
+//# debugId=8ffd2cd5-8b7e-5ae1-a0c6-aab488edb73c

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

@@ -7,6 +7,7 @@ import { type GlobalOptions } from "../runtime-primitives.js";
 import { type ChildRollupContext } from "../item-children.js";
 import { type ItemScheduleContext } from "../item-schedule.js";
 import type { ItemMetadata, LinkedDoc, LinkedFile, LinkedTest } from "../../types/index.js";
+export { GET_DEPTH_VALUES, listGetProjectionFields, } from "./projection-contracts.js";
 interface ClaimHistoryContext {
     ts: string;
     author: string;
@@ -92,4 +93,3 @@ export declare function runGet(id: string, global: GlobalOptions, options?: GetO
 export declare const _testOnlyGetCommand: {
     shouldAutoIncludeGetChildren: typeof shouldAutoIncludeGetChildren;
 };
-export {};