@unbrained/pm-cli 2026.8.19 → 2026.8.21

package/dist/sdk/lifecycle/update-many.js

@@ -4,8 +4,9 @@
  * Implements the pm update many 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]="e797d654-df89-554b-876b-cb2faa350bd0")}catch(e){}}();
-import { pathExists, createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, toItemRecord, applyAcceptanceCriteriaMutations, applyTagRemovals, mergeAdditiveTags, parseOptionalNonNegativeInteger, parseTags, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, resolveItemTypeRegistry, resolveTypeName, collectRuntimeUpdateFieldValues, buildInvalidTypeError, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, toErrorMessage, stableValueEquals, nowIso, resolveIsoOrRelative, getActiveExtensionRegistrations, 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]="7a157c2e-e9e6-5bce-b124-0a7d34e3c7dc")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, toItemRecord, applyAcceptanceCriteriaMutations, applyTagRemovals, mergeAdditiveTags, parseOptionalNonNegativeInteger, parseTags, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, resolveItemTypeRegistry, resolveTypeName, collectRuntimeUpdateFieldValues, buildInvalidTypeError, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, toErrorMessage, stableValueEquals, nowIso, resolveIsoOrRelative, getActiveExtensionRegistrations, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { assertDependencyTargetsResolvable } from "../dependency-flag-validation.js";
 import { parseStatusFilterCsv } from "../../core/item/status-filter.js";
 import { hasListFilters } from "../query/list-filter-shared.js";
@@ -588,9 +589,7 @@ const buildUnmatchedIdFields = (plan) => plan.unmatchedIds === undefined
 /** Loads tracker settings and runtime registries for update-many execution. */
 const loadUpdateManyRuntimeContext = async (global) => {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     return {
         pmRoot,
@@ -853,4 +852,4 @@ export const _testOnlyUpdateManyCommand = {
     toComparablePreviewValue,
 };
 //# sourceMappingURL=update-many.js.map
-//# debugId=e797d654-df89-554b-876b-cb2faa350bd0
+//# debugId=7a157c2e-e9e6-5bce-b124-0a7d34e3c7dc

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

@@ -1,8 +1,3 @@
-/**
- * @module sdk/lifecycle/update
- *
- * Implements the pm update command surface and its agent-facing runtime behavior.
- */
 import { resolveItemTypeRegistry, type RuntimeFieldRegistry, type RuntimeStatusRegistry, type NormalizedTypeWorkflow, type GlobalOptions, PmCliError, getActiveExtensionRegistrations, readSettings } from "../runtime-primitives.js";
 import type { Dependency, GovernanceWorkflowEnforcement, ItemDocument } from "../../types/index.js";
 import { DEPENDENCY_KIND_VALUES } from "../../types/index.js";
@@ -67,6 +62,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 +163,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,10 @@
  * 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]="d024d9cf-81f8-5690-b8f4-03620e3e9bf8")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { 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, 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";
@@ -439,9 +441,9 @@ function parseDependencyRemovals(raw, prefix) {
         if (!trimmed) {
             throw new PmCliError("--dep-remove requires id or key/value selectors", EXIT_CODE.USAGE);
         }
-        if (trimmed.includes("=") ||
-            /^(?:[-*+]\s+)?(?:id|kind|type|source_kind)\s*[:=]/i.test(trimmed) ||
-            trimmed.startsWith("```")) {
+        const isStructured = looksLikeStructuredDependencyEntry(trimmed);
+        assertValidBareDependencyFlagValue(trimmed, isStructured, "--dep-remove");
+        if (isStructured) {
             const kv = parseCsvKv(trimmed, "--dep-remove");
             assertNoUnknownCsvKeys(kv, "--dep-remove", DEP_REMOVE_KEYS);
             const idRaw = kv.id?.trim();
@@ -1081,9 +1083,7 @@ async function buildNoopUpdateResult(params) {
     };
 }
 async function assertUpdateTrackerInitialized(pmRoot) {
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
 }
 function assertMatchingOrderRank(options) {
     if (options.order !== undefined &&
@@ -1214,8 +1214,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 +1254,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");
@@ -1312,6 +1312,44 @@ function applyTypeOptionMutation(document, context, activeTypeName, changedField
     }
     document.metadata.type_options = validation.normalized;
 }
+/** Collapse duplicate rows only for identities explicitly touched by this mutation. */
+function normalizeTouchedDependencyIdentities(current, additions) {
+    const touchedKeys = new Set(additions.map((entry) => dependencyKey(entry)));
+    const retainedTouchedKeys = new Set();
+    return current.filter((entry) => {
+        const key = dependencyKey(entry);
+        if (!touchedKeys.has(key)) {
+            return true;
+        }
+        if (retainedTouchedKeys.has(key)) {
+            return false;
+        }
+        retainedTouchedKeys.add(key);
+        return true;
+    });
+}
+/** Refuse lossless removals unless every selector resolves against stored edges. */
+function assertDependencyRemovalSelectorsMatch(current, selectors, itemId) {
+    const unmatchedSelectors = selectors.filter((selector) => !current.some((entry) => matchesDependencySelector(entry, selector)));
+    if (unmatchedSelectors.length === 0) {
+        return;
+    }
+    throw new PmCliError(`Dependency removal did not match ${unmatchedSelectors.length === 1 ? "a stored edge" : "stored edges"}.`, EXIT_CODE.NOT_FOUND, {
+        code: "dependency_remove_no_match",
+        reason: "selector_not_found",
+        unmatched_selectors: unmatchedSelectors,
+        available_dependencies: current.map((entry) => ({
+            id: entry.id,
+            kind: entry.kind,
+            source_kind: entry.source_kind,
+        })),
+        why: "Failing on a zero-match selector prevents a mistyped dependency removal from being reported as successful.",
+        nextSteps: [
+            `Inspect the current item with: pm get ${itemId} --full`,
+            "Retry --dep-remove with the exact id, kind, and optional source_kind shown in dependencies.",
+        ],
+    });
+}
 function applyDependencyMutations(document, context, changedFields) {
     if (context.options.dep === undefined &&
         context.options.depRemove === undefined &&
@@ -1322,6 +1360,7 @@ function applyDependencyMutations(document, context, changedFields) {
         ? []
         : [...(document.metadata.dependencies ?? [])];
     if (context.dependencyUpdates.additions.length > 0) {
+        nextDependencies = normalizeTouchedDependencyIdentities(nextDependencies, context.dependencyUpdates.additions);
         const seen = new Set(nextDependencies.map((entry) => dependencyKey(entry)));
         for (const addition of context.dependencyUpdates.additions) {
             const key = dependencyKey(addition);
@@ -1332,6 +1371,7 @@ function applyDependencyMutations(document, context, changedFields) {
         }
     }
     if (context.dependencyRemovals.length > 0) {
+        assertDependencyRemovalSelectorsMatch(nextDependencies, context.dependencyRemovals, document.metadata.id);
         nextDependencies = nextDependencies.filter((entry) => !context.dependencyRemovals.some((selector) => matchesDependencySelector(entry, selector)));
     }
     if (nextDependencies.length === 0) {
@@ -1700,7 +1740,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 +1860,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 +1929,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 +2021,4 @@ export const _testOnlyUpdateCommand = {
     resolveRuntimeUnsetDefinition: (token, registry) => resolveRuntimeUnsetFieldDefinition(token, "update", registry),
 };
 //# sourceMappingURL=update.js.map
-//# debugId=a421c150-13a9-5334-85a4-5b3199a5d2c7
+//# debugId=d024d9cf-81f8-5690-b8f4-03620e3e9bf8

package/dist/sdk/linked-artifacts.js

@@ -4,11 +4,12 @@
  * Implements the pm linked artifacts 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]="72f57c4d-65c5-57f1-a16a-f6c970aca680")}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]="1832e2b3-0ece-523d-8f38-598303d3f590")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import fg from "fast-glob";
-import { isFileAbsentError, pathExists } from "../core/fs/fs-utils.js";
+import { isFileAbsentError } from "../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, parseCsvKv, } from "../core/item/parse.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
@@ -18,7 +19,7 @@ import { PmCliError } from "../core/shared/errors.js";
 import { splitCommaList } from "../core/shared/split-comma-list.js";
 import { stableValueEquals } from "../core/shared/serialization.js";
 import { locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
-import { getSettingsPath, resolvePmRoot, resolveWorkspaceRoot, } from "../core/store/paths.js";
+import { resolvePmRoot, resolveWorkspaceRoot, } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { SCOPE_VALUES } from "../types/index.js";
 import { resolveAuthor } from "../core/shared/author.js";
@@ -450,9 +451,7 @@ export async function runLinkedArtifacts(id, options, global, config) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
     const workspaceRoot = resolveWorkspaceRoot(pmRoot);
     const invocationRoot = process.cwd();
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const resolvedAdds = await stdinResolver.resolveList(options.add, "--add");
@@ -539,4 +538,4 @@ export function renameArtifactsResultKey(result, key) {
     return out;
 }
 //# sourceMappingURL=linked-artifacts.js.map
-//# debugId=72f57c4d-65c5-57f1-a16a-f6c970aca680
+//# debugId=1832e2b3-0ece-523d-8f38-598303d3f590

package/dist/sdk/merge/install.js

@@ -8,7 +8,8 @@
  * mutations refresh the fenced block automatically once it is installed.
  */
 
-!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]="5e1810a5-04b8-5929-8eee-7a63f1684860")}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]="dea4137f-adbd-5dca-bfc7-b56c99c7aa79")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { isFileMissingError } from "../../core/fs/fs-utils.js";
 import { readFile, realpath, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
@@ -22,7 +23,7 @@ import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { resolveAuthor } from "../../core/shared/author.js";
 import { nowIso } from "../../core/shared/time.js";
-import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings, resolveGovernanceKnobs, } from "../../core/store/settings.js";
 import { isPathOutsideRoot } from "../workspace.js";
 import { resolveSourceContextWritePolicy } from "../environment/source-context.js";
@@ -453,9 +454,7 @@ export async function runMergeInstall(options, global) {
         environment: process.env,
     });
     const pmRoot = context.pm_root;
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const workspaceRoot = await resolveGitWorkspaceRoot(context.workspace_start);
     return installMergeFence({
         pmRoot,
@@ -561,4 +560,4 @@ export async function installMergeFence(options) {
     };
 }
 //# sourceMappingURL=install.js.map
-//# debugId=5e1810a5-04b8-5929-8eee-7a63f1684860
+//# debugId=dea4137f-adbd-5dca-bfc7-b56c99c7aa79

package/dist/sdk/mutation-events.js

@@ -5,15 +5,15 @@
  * history store without requiring a daemon or shell subprocess.
  */
 
-!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]="e8cd5790-eacf-5ef7-bc0a-11ea3fe17d2d")}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]="01043e67-99d4-5b68-a1b2-33f35f5cef5f")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { createHash } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 import { queryHistoryEventIndex, queryHistoryEventStreams, rebuildHistoryEventIndex, } from "../core/history/event-index.js";
-import { pathExists } from "../core/fs/fs-utils.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { stableStringify } from "../core/shared/serialization.js";
-import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { parseHistoryProvenanceFilters, projectHistoryProvenance, resolveHistoryProvenanceDimensions, summarizeHistoryProvenance, } from "./history-provenance.js";
 const MUTATION_EVENT_CURSOR_VERSION = 1;
@@ -150,9 +150,7 @@ function resolveMutationEventCursorMode(value) {
 /** Read one bounded page of mutation events from the persistent projection. */
 export async function listMutationEvents(options = {}) {
     const pmRoot = resolvePmRoot(options.cwd ?? process.cwd(), options.pmRoot);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const requestedLimit = parseMutationEventLimit(options.limit);
     const cursorMode = resolveMutationEventCursorMode(options.cursorMode);
     if (options.full === true && options.provenance === true) {
@@ -292,4 +290,4 @@ export const _testOnlyMutationEvents = {
     resolveMutationEventStart,
 };
 //# sourceMappingURL=mutation-events.js.map
-//# debugId=e8cd5790-eacf-5ef7-bc0a-11ea3fe17d2d
+//# debugId=01043e67-99d4-5b68-a1b2-33f35f5cef5f

package/dist/sdk/package-import-adapters.js

@@ -13,19 +13,20 @@
  * helper bodies while keeping each package's explicit field mapping in the package.
  */
 
-!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]="c2567f6a-cd1c-56b5-a93d-41e92ed574bf")}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]="863df651-49e0-552f-a7f0-92c3cc9a12a2")}catch(e){}}();
 import { appendHistoryEntry, createHistoryEntry, } from "../core/history/history.js";
 import { acquireLock } from "../core/lock/lock.js";
 import { parseTags } from "../core/item/parse.js";
 import { normalizeStatusInput } from "../core/item/status.js";
 import { serializeItemDocument } from "../core/item/item-format.js";
-import { getHistoryPath, getSettingsPath } from "../core/store/paths.js";
-import { pathExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
+import { getHistoryPath } from "../core/store/paths.js";
+import { removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
 import { runActiveOnWriteHooks } from "../core/extensions/index.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { resolveAuthor } from "../core/shared/author.js";
 import { nowIso } from "../core/shared/time.js";
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 /** Returns the trimmed string when `value` is a non-empty string, else undefined. */
 export function toNonEmptyImportString(value) {
     if (typeof value !== "string") {
@@ -367,10 +368,7 @@ function toImportLinkedTestAssertions(entry) {
 }
 /** Throws a NOT_FOUND PmCliError when the tracker has not been initialized. */
 export async function ensureTrackerInitialized(pmRoot) {
-    const exists = await pathExists(getSettingsPath(pmRoot));
-    if (!exists) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
 }
 /** Returns an empty item document used as the `before` state on import. */
 export function emptyImportedDocument() {
@@ -442,4 +440,4 @@ export async function commitImportedItem(params) {
     }
 }
 //# sourceMappingURL=package-import-adapters.js.map
-//# debugId=c2567f6a-cd1c-56b5-a93d-41e92ed574bf
+//# debugId=863df651-49e0-552f-a7f0-92c3cc9a12a2

package/dist/sdk/profile.js

@@ -10,16 +10,17 @@
  * and human formatting around it.
  */
 
-!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]="a1e34cfb-3d4e-5b79-8585-3162e71e574c")}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]="f65b4f1f-5501-5829-a04b-d4fbcfb59f5c")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import path from "node:path";
-import { pathExists, readFileIfExists, } from "../core/fs/fs-utils.js";
+import { readFileIfExists, } from "../core/fs/fs-utils.js";
 import { writeWorkspaceJsonWithHistory } from "../core/history/workspace-history.js";
 import { acquireLock } from "../core/lock/lock.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { resolveAuthor } from "../core/shared/author.js";
 import { nowIso } from "../core/shared/time.js";
-import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings, resolveGovernanceKnobs, writeSettings, } from "../core/store/settings.js";
 import { DEFAULT_RUNTIME_SCHEMA_FILE_PATHS, filePathForSchemaSection, normalizeRuntimeSchemaSettings, } from "../core/schema/runtime-schema.js";
 import { normalizeAddTypeInput, serializeItemTypesFile, } from "../core/schema/item-types-file.js";
@@ -198,9 +199,7 @@ function buildApplyResult(profile, plan, applied, dryRun, warnings) {
     };
 }
 async function assertProfileTrackerInitialized(pmRoot) {
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
 }
 function resolveProfileForCommand(name) {
     try {
@@ -453,4 +452,4 @@ export function formatProfileApplyHuman(result) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=profile.js.map
-//# debugId=a1e34cfb-3d4e-5b79-8585-3162e71e574c
+//# debugId=f65b4f1f-5501-5829-a04b-d4fbcfb59f5c

package/dist/sdk/query/activity.js

@@ -4,11 +4,12 @@
  * Implements the pm activity 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]="49304d18-d722-5413-8e4d-4f2c3df4a1ca")}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]="7005305a-5fd4-56b8-a0a0-5612e8bf48cc")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { isFileMissingError } from "../../core/fs/fs-utils.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { getActiveExtensionRegistrations, runActiveOnReadHooks, pathExists, enforceHistoryStreamPolicyForItems, resolveItemTypeRegistry, EXIT_CODE, PmCliError, compareTimestampStrings, nowIso, resolveIsoOrRelative, listAllItemMetadataLight, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
+import { getActiveExtensionRegistrations, runActiveOnReadHooks, enforceHistoryStreamPolicyForItems, resolveItemTypeRegistry, EXIT_CODE, PmCliError, compareTimestampStrings, nowIso, resolveIsoOrRelative, listAllItemMetadataLight, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 import { readHistoryEntries } from "../history-read.js";
 import { parseLimit } from "./parsers.js";
 import { resolveModePairedOutputOmissionReceipt, } from "../output-projection.js";
@@ -168,9 +169,7 @@ function resolveActivityFilters(options, projectionMode) {
 }
 async function resolveActivityRuntimeContext(global) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     return {
         pmRoot,
         settings: await readSettings(pmRoot),
@@ -400,4 +399,4 @@ export async function runActivity(options, global) {
     };
 }
 //# sourceMappingURL=activity.js.map
-//# debugId=49304d18-d722-5413-8e4d-4f2c3df4a1ca
+//# debugId=7005305a-5fd4-56b8-a0a0-5612e8bf48cc

package/dist/sdk/query/calendar.js

@@ -4,9 +4,10 @@
  * Implements the pm calendar 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]="f1677c6e-872e-5c42-ae3d-f73f4ec73616")}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]="47de55f1-589f-5743-bcb8-3b7a6302dfbb")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { encode as encodeToon } from "@toon-format/toon";
-import { pathExists, getActiveExtensionRegistrations, resolveItemTypeRegistry, normalizeStatusInput, collectRuntimeFilterValues, matchesRuntimeFilters, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, levenshteinDistanceWithinLimit, compareTimestampStrings, nowIso, resolveIsoOrRelative, listAllItemMetadataLight, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
+import { getActiveExtensionRegistrations, resolveItemTypeRegistry, normalizeStatusInput, collectRuntimeFilterValues, matchesRuntimeFilters, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, levenshteinDistanceWithinLimit, compareTimestampStrings, nowIso, resolveIsoOrRelative, listAllItemMetadataLight, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 import { parseIntegerLimit, parsePriority, parseType, } from "./parsers.js";
 import { weekdayOrderIndex, } from "../../types/index.js";
 const CALENDAR_VIEW_VALUES = ["agenda", "day", "week", "month"];
@@ -928,9 +929,7 @@ function buildCalendarRangeResult(options, rangeBounds) {
 /** Implements run calendar for the public runtime surface of this module. */
 export async function runCalendar(options, global) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const inputs = resolveCalendarExecutionInputs(options);
     const settings = await readSettings(pmRoot);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
@@ -963,4 +962,4 @@ export async function runCalendar(options, global) {
     };
 }
 //# sourceMappingURL=calendar.js.map
-//# debugId=f1677c6e-872e-5c42-ae3d-f73f4ec73616
+//# debugId=47de55f1-589f-5743-bcb8-3b7a6302dfbb

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

@@ -1,12 +1,8 @@
-/**
- * @module sdk/query/get
- *
- * Implements the SDK-owned item query shared by every surface.
- */
 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 +88,3 @@ export declare function runGet(id: string, global: GlobalOptions, options?: GetO
 export declare const _testOnlyGetCommand: {
     shouldAutoIncludeGetChildren: typeof shouldAutoIncludeGetChildren;
 };
-export {};