@unbrained/pm-cli 2026.8.20 → 2026.8.22

package/dist/sdk/lifecycle/hierarchy-mutation-lock.d.ts

@@ -0,0 +1,15 @@
+/** Inputs for the internal workspace-wide hierarchy mutation lock. */
+export interface HierarchyMutationLockOptions {
+    /** Tracker root whose hierarchy is being changed. */
+    pmRoot: string;
+    /** Principal recorded as the lock owner. */
+    author: string;
+    /** Tracker-configured stale-lock lifetime. */
+    ttlSeconds: number;
+    /** Tracker-configured bounded lock wait. */
+    waitMs: number;
+    /** Whether this mutation can add hierarchy evidence. */
+    required: boolean;
+}
+/** Acquire the shared hierarchy writer lock, or return a no-op release. */
+export declare function acquireHierarchyMutationLock(options: HierarchyMutationLockOptions): Promise<() => Promise<void>>;

package/dist/sdk/lifecycle/hierarchy-mutation-lock.js

@@ -0,0 +1,25 @@
+/**
+ * @module sdk/lifecycle/hierarchy-mutation-lock
+ *
+ * Serializes hierarchy-affecting create and update transactions so each
+ * before/after integrity decision is made from a fresh workspace snapshot.
+ */
+
+!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]="39a36d42-29b1-5f0f-a8b2-f3bfc0ef78c2")}catch(e){}}();
+import { acquireLock } from "../../core/lock/lock.js";
+const HIERARCHY_MUTATION_LOCK_ID = "hierarchy-integrity";
+/** Acquire the shared hierarchy writer lock, or return a no-op release. */
+export async function acquireHierarchyMutationLock(options) {
+    const release = options.required
+        ? await acquireLock(options.pmRoot, HIERARCHY_MUTATION_LOCK_ID, options.ttlSeconds, options.author, false, false, options.waitMs)
+        : async () => { };
+    let released = false;
+    return async () => {
+        if (released)
+            return;
+        released = true;
+        await release();
+    };
+}
+//# sourceMappingURL=hierarchy-mutation-lock.js.map
+//# debugId=39a36d42-29b1-5f0f-a8b2-f3bfc0ef78c2

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

@@ -1,8 +1,3 @@
-/**
- * @module sdk/lifecycle/plan
- *
- * Implements the pm plan command surface and its agent-facing runtime behavior.
- */
 import { type GlobalOptions } from "../runtime-primitives.js";
 import type { DependencyKind, ItemMetadata, PlanDecision, PlanDiscovery, PlanHarness, PlanMode, PlanStep, PlanStepStatus, PlanValidationCheck } from "../../types/index.js";
 import type { MutationMetadataCommandOptions, SharedLinkedResourceOptions } from "./mutation-command-options.js";

package/dist/sdk/lifecycle/plan.js

@@ -4,8 +4,9 @@
  * Implements the pm plan 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]="3d5ea029-26ef-51bc-bacc-b1d4d807a024")}catch(e){}}();
-import { pathExists, getActiveExtensionRegistrations, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, resolveTypeName, EXIT_CODE, PmCliError, splitCommaList, nowIso, locateItem, mutateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, isTerminalPlanMode, } 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]="49fd5730-99c2-5a93-a80e-83c806a124bf")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { getActiveExtensionRegistrations, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, resolveTypeName, EXIT_CODE, PmCliError, splitCommaList, nowIso, locateItem, mutateItem, readLocatedItem, resolvePmRoot, readSettings, resolveAuthor, isTerminalPlanMode, } from "../runtime-primitives.js";
 import { PLAN_HARNESS_VALUES, PLAN_MODE_VALUES, PLAN_STEP_LINK_KIND_VALUES, PLAN_STEP_STATUS_VALUES, } from "../../types/index.js";
 import { runCreate, } from "./create.js";
 import { createUnknownSubcommandError } from "../agent/subcommand-recovery.js";
@@ -547,9 +548,7 @@ function ensurePlanItem(item) {
 }
 async function loadContext(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, settings };
 }
@@ -1587,4 +1586,4 @@ export const _testOnlyPlanCommand = {
     changedPlanMetadataFields,
 };
 //# sourceMappingURL=plan.js.map
-//# debugId=3d5ea029-26ef-51bc-bacc-b1d4d807a024
+//# debugId=49fd5730-99c2-5a93-a80e-83c806a124bf

package/dist/sdk/lifecycle/restore.js

@@ -4,10 +4,11 @@
  * Implements the SDK-owned restore lifecycle operation shared by every surface.
  */
 
-!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]="353be665-9f67-5d0e-99c9-6bbb7e927e0b")}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]="db5f3a6d-9ae5-5f9b-bedf-766b2b79324c")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import jsonPatch from "fast-json-patch";
 import fs from "node:fs/promises";
-import { pathExists, readFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, enforceHistoryStreamPolicyForItem, normalizeItemId, normalizeRawItemId, canonicalDocument, serializeItemDocument, resolveItemTypeRegistry, acquireLock, EXIT_CODE, PmCliError, nowIso, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnWriteHooks, runActiveBeforeMutationHooks, locateItem, createMutationGuardSdk, readLocatedItem, getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+import { pathExists, readFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, enforceHistoryStreamPolicyForItem, normalizeItemId, normalizeRawItemId, canonicalDocument, serializeItemDocument, resolveItemTypeRegistry, acquireLock, EXIT_CODE, PmCliError, nowIso, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnWriteHooks, runActiveBeforeMutationHooks, locateItem, createMutationGuardSdk, readLocatedItem, getHistoryPath, getItemPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { applyHistoryPatch, ensureMaterializedHistoryTarget as ensureMaterializedRestoreTarget, extractPatchFailureContext, readHistoryEntries, replayHistoryToTarget as replayToTarget, resolveHistoryTarget, } from "../history-read.js";
 import { acquireItemMetadataDerivedIndexLock, refreshItemMetadataDerivedIndex, } from "../item-metadata-index.js";
 /** Resolve restore targets with the command's established wording and at-or-before timestamp semantics. */
@@ -163,9 +164,7 @@ async function runRestoreWriteHooks(params) {
 /** Implements run restore for the public runtime surface of this module. */
 export async function runRestore(id, target, 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 settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const subject = await resolveRestoreSubject(pmRoot, id, settings, typeRegistry.type_to_folder);
@@ -317,4 +316,4 @@ export const _testOnlyRestoreCommand = {
     resolveRestoreSubject,
 };
 //# sourceMappingURL=restore.js.map
-//# debugId=353be665-9f67-5d0e-99c9-6bbb7e927e0b
+//# debugId=db5f3a6d-9ae5-5f9b-bedf-766b2b79324c

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

@@ -1,8 +1,3 @@
-/**
- * @module cli/commands/update-many
- *
- * Implements the pm update many command surface and its agent-facing runtime behavior.
- */
 import { type RuntimeFieldRegistry, type RuntimeStatusRegistry, type GlobalOptions } from "../runtime-primitives.js";
 import type { ItemStatus, PmSettings } from "../../types/index.js";
 import { hasListFilters } from "../query/list-filter-shared.js";

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";
@@ -126,6 +121,8 @@ interface DependencyRemovalSelector {
     id: string;
     kind?: (typeof DEPENDENCY_KIND_VALUES)[number];
     source_kind?: string;
+    author?: string;
+    created_at?: string;
 }
 /** Parse dependency additions into their canonical storage representation. */
 export declare function parseDependencyAdditions(raw: string[] | undefined, prefix: string, nowIso: string, fallbackAuthor: string): ParsedDependencyUpdates;

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]="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";
+!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]="7c1729f8-4a67-5746-a1bf-351f862ceb66")}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";
@@ -16,6 +17,9 @@ import { assertDependencyEdgesAllowed, assertDependencyTargetsResolvable, assert
 import { normalizeDependencySeedId, normalizeDependencySourceKind, } from "../dependency-provenance.js";
 import { resolveCanonicalRelationshipKind } from "../relationships.js";
 import { collectNewOrderingCycleWarnings } from "../graph/mutation-advisory.js";
+import { assertHierarchyMutationAllowed } from "../graph/hierarchy-integrity.js";
+import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
+import { acquireHierarchyMutationLock } from "./hierarchy-mutation-lock.js";
 import { DEPENDENCY_KIND_VALUES, ISSUE_SEVERITY_VALUES, RISK_VALUES, } from "../../types/index.js";
 import { parseDocs, parseFiles, parseLogSeed, parseTests, requireStringOption, } from "./create.js";
 import { COMMON_UNSET_FIELD_DEFINITIONS_AFTER_CLOSE_REASON_BEFORE_AUTHOR, COMMON_UNSET_FIELD_DEFINITIONS_AFTER_AUTHOR, COMMON_UNSET_FIELD_DEFINITIONS_BEFORE_CLOSE_REASON, parseCommandUnsetTargets, resolveRuntimeUnsetFieldDefinition, } from "./shared-unset-fields.js";
@@ -354,6 +358,9 @@ function parseDependencyCreatedAt(value, currentIso) {
     if (!value || value.trim() === "" || value.trim().toLowerCase() === "now") {
         return currentIso;
     }
+    return normalizeDependencyTimestamp(value);
+}
+function normalizeDependencyTimestamp(value) {
     const parsed = Date.parse(value);
     if (!Number.isFinite(parsed)) {
         throw new PmCliError(`Invalid dependency created_at timestamp "${value}"`, EXIT_CODE.USAGE);
@@ -376,7 +383,14 @@ const DEP_ADDITION_KEYS = [
     "source_kind",
 ];
 /** Allowed CSV/markdown keys for the `--dep-remove` selector (GH-258). */
-const DEP_REMOVE_KEYS = ["id", "kind", "type", "source_kind"];
+const DEP_REMOVE_KEYS = [
+    "id",
+    "kind",
+    "type",
+    "author",
+    "created_at",
+    "source_kind",
+];
 function looksLikeStructuredDependencyEntry(raw) {
     if (raw.startsWith("```") || raw.includes("\n")) {
         return true;
@@ -440,9 +454,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();
@@ -454,12 +468,18 @@ function parseDependencyRemovals(raw, prefix) {
             }
             const kindRaw = normalizeDependencyKindInput(parseOptionalDependencyString(kv.kind ?? kv.type));
             const sourceKind = normalizeDependencySourceKind(parseOptionalDependencyString(kv.source_kind));
+            const author = parseOptionalDependencyString(kv.author);
+            const createdAt = parseOptionalDependencyString(kv.created_at);
             return {
                 id: normalizeDependencySeedId(idRaw, prefix, sourceKind),
                 kind: kindRaw
                     ? ensureEnum(kindRaw, DEPENDENCY_KIND_VALUES, "dependency kind")
                     : undefined,
                 source_kind: sourceKind,
+                author,
+                created_at: createdAt
+                    ? normalizeDependencyTimestamp(createdAt)
+                    : undefined,
             };
         }
         if (trimmed.toLowerCase() === "undefined") {
@@ -472,7 +492,24 @@ function parseDependencyRemovals(raw, prefix) {
 }
 function dependencyKey(value) {
     const sourceKind = value.source_kind?.trim().toLowerCase() ?? "";
-    return `${value.id.trim().toLowerCase()}::${value.kind}::${sourceKind}`;
+    return [value.id.trim().toLowerCase(), value.kind, sourceKind].join("\u0000");
+}
+/** Return the complete normalized identity of one stored dependency row. */
+function storedDependencyIdentityKey(value) {
+    const sourceKind = value.source_kind?.trim().toLowerCase() ?? "";
+    const author = value.author?.trim().toLowerCase() ?? "";
+    const rawCreatedAt = value.created_at?.trim() ?? "";
+    const parsedCreatedAt = Date.parse(rawCreatedAt);
+    const createdAt = Number.isFinite(parsedCreatedAt)
+        ? new Date(parsedCreatedAt).toISOString()
+        : rawCreatedAt;
+    return [
+        value.id.trim().toLowerCase(),
+        value.kind,
+        sourceKind,
+        author,
+        createdAt,
+    ].join("\u0000");
 }
 // pm-kyd6: `--blocked-by` writes the `blocked_by` scalar, but the dependency
 // graph (`pm deps`) is built only from the `dependencies` array. Mirror the
@@ -567,6 +604,17 @@ function matchesDependencySelector(value, selector) {
             selector.source_kind.trim().toLowerCase()) {
         return false;
     }
+    if (selector.author !== undefined &&
+        value.author?.trim().toLowerCase() !== selector.author.trim().toLowerCase()) {
+        return false;
+    }
+    if (selector.created_at !== undefined &&
+        (value.created_at === undefined ||
+            !Number.isFinite(Date.parse(value.created_at)) ||
+            new Date(Date.parse(value.created_at)).toISOString() !==
+                selector.created_at)) {
+        return false;
+    }
     return true;
 }
 function ensurePriority(raw) {
@@ -1081,10 +1129,21 @@ async function buildNoopUpdateResult(params) {
         warnings: ["noop_no_update_fields"],
     };
 }
+async function loadUpdateRelationshipGraph(params) {
+    if (!params.fieldFlags.dep &&
+        !params.fieldFlags.blockedBy &&
+        !params.fieldFlags.parent &&
+        !params.clearedMetadataKeys.has("parent"))
+        return undefined;
+    return listAllItemMetadataLight(params.pmRoot, params.settings.item_format, params.typeToFolder, undefined, params.settings.schema);
+}
+function assertUpdateHierarchyIntegrity(params) {
+    if (!params.before)
+        return;
+    assertHierarchyMutationAllowed(params.before, params.before.map((item) => item.id === params.document.metadata.id ? params.document.metadata : item), params.document.metadata.id, (status) => isTerminalStatus(status, params.statusRegistry), resolveWorkspaceRelationshipKindRegistry());
+}
 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 &&
@@ -1313,6 +1372,46 @@ 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 retainedStoredIdentities = new Set();
+    return current.filter((entry) => {
+        if (!touchedKeys.has(dependencyKey(entry))) {
+            return true;
+        }
+        const storedIdentity = storedDependencyIdentityKey(entry);
+        if (retainedStoredIdentities.has(storedIdentity)) {
+            return false;
+        }
+        retainedStoredIdentities.add(storedIdentity);
+        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,
+            author: entry.author,
+            created_at: entry.created_at,
+        })),
+        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 plus any kind, source_kind, author, or created_at selectors needed to identify one stored row.",
+        ],
+    });
+}
 function applyDependencyMutations(document, context, changedFields) {
     if (context.options.dep === undefined &&
         context.options.depRemove === undefined &&
@@ -1323,6 +1422,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);
@@ -1333,6 +1433,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) {
@@ -1818,82 +1919,108 @@ async function runUpdateWithContext(id, options, global, execution = {}) {
         return routedClose;
     }
     assertMatchingOrderRank(options);
-    let graphBeforeUpdate = fieldFlags.dep || fieldFlags.depRemove || fieldFlags.blockedBy
-        ? await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema)
-        : undefined;
-    let lifecycleTransition;
-    let recurrenceHistoryContext;
-    const result = await mutateItemWithHistoryContextResolver({
+    const relationshipRegistry = resolveWorkspaceRelationshipKindRegistry();
+    const hierarchyMutationRequired = (fieldFlags.parent && !clearItemMetadataKeys.has("parent")) ||
+        dependencyUpdates.additions.some((dependency) => relationshipRegistry.resolve(dependency.kind)?.hierarchy);
+    const releaseHierarchyMutationLock = await acquireHierarchyMutationLock({
         pmRoot,
-        settings,
-        typeToFolder: typeRegistry.type_to_folder,
-        id,
-        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);
-            return mutateUpdateDocument(document, {
-                options,
-                settings,
-                typeRegistry,
-                statusRegistry,
-                runtimeFieldRegistry,
-                extensionRegistrations,
-                extensionFieldNames,
-                clearItemMetadataKeys,
-                dependencyUpdates,
-                dependencyRemovals,
-                commentUpdates,
-                noteUpdates,
-                learningUpdates,
-                fileUpdates,
-                testUpdates,
-                docUpdates,
-                resolvedParentValue: parentReference.resolvedParentValue,
-                resolvedBlockedByDependencyId,
-                runtimeFieldUpdates,
-                nowValue,
-                nowIso,
-                author,
-                pmRoot,
-            });
-        },
+        ttlSeconds: settings.locks.ttl_seconds,
+        waitMs: settings.locks.wait_ms,
+        required: hierarchyMutationRequired,
     });
-    const orderingCycleWarnings = graphBeforeUpdate
-        ? collectNewOrderingCycleWarnings(graphBeforeUpdate, graphBeforeUpdate.map((item) => item.id === result.item.id ? result.item : item), result.item.id)
-        : [];
-    return {
-        item: toItemRecord(result.item),
-        changed_fields: result.changedFields,
-        warnings: [
-            ...workflowTransitionWarnings,
-            ...parentReferenceWarnings,
-            ...dependencyTargetWarnings,
-            ...orderingCycleWarnings,
-            ...result.warnings,
-        ],
-        ...(lifecycleTransition === undefined
-            ? {}
-            : { lifecycle_transition: lifecycleTransition }),
-    };
+    try {
+        let graphBeforeUpdate = await loadUpdateRelationshipGraph({
+            fieldFlags,
+            clearedMetadataKeys: clearItemMetadataKeys,
+            pmRoot,
+            settings,
+            typeToFolder: typeRegistry.type_to_folder,
+        });
+        let lifecycleTransition;
+        let recurrenceHistoryContext;
+        const result = await mutateItemWithHistoryContextResolver({
+            pmRoot,
+            settings,
+            typeToFolder: typeRegistry.type_to_folder,
+            id,
+            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);
+                const mutation = mutateUpdateDocument(document, {
+                    options,
+                    settings,
+                    typeRegistry,
+                    statusRegistry,
+                    runtimeFieldRegistry,
+                    extensionRegistrations,
+                    extensionFieldNames,
+                    clearItemMetadataKeys,
+                    dependencyUpdates,
+                    dependencyRemovals,
+                    commentUpdates,
+                    noteUpdates,
+                    learningUpdates,
+                    fileUpdates,
+                    testUpdates,
+                    docUpdates,
+                    resolvedParentValue: parentReference.resolvedParentValue,
+                    resolvedBlockedByDependencyId,
+                    runtimeFieldUpdates,
+                    nowValue,
+                    nowIso,
+                    author,
+                    pmRoot,
+                });
+                assertUpdateHierarchyIntegrity({
+                    before: graphBeforeUpdate,
+                    document,
+                    statusRegistry,
+                });
+                return mutation;
+            },
+        });
+        await releaseHierarchyMutationLock();
+        const orderingCycleWarnings = graphBeforeUpdate
+            ? collectNewOrderingCycleWarnings(graphBeforeUpdate, graphBeforeUpdate.map((item) => item.id === result.item.id ? result.item : item), result.item.id)
+            : [];
+        return {
+            item: toItemRecord(result.item),
+            changed_fields: result.changedFields,
+            warnings: [
+                ...workflowTransitionWarnings,
+                ...parentReferenceWarnings,
+                ...dependencyTargetWarnings,
+                ...orderingCycleWarnings,
+                ...result.warnings,
+            ],
+            ...(lifecycleTransition === undefined
+                ? {}
+                : { lifecycle_transition: lifecycleTransition }),
+        };
+    }
+    finally {
+        await releaseHierarchyMutationLock();
+    }
 }
 /** Resolve the immutable operation name for ordinary, bypass, and recurrence updates. */
 function resolveUpdateHistoryOperation(options, execution) {
@@ -1982,4 +2109,4 @@ export const _testOnlyUpdateCommand = {
     resolveRuntimeUnsetDefinition: (token, registry) => resolveRuntimeUnsetFieldDefinition(token, "update", registry),
 };
 //# sourceMappingURL=update.js.map
-//# debugId=3ab4f16d-ce37-546e-a2f6-0495fd1967c7
+//# debugId=7c1729f8-4a67-5746-a1bf-351f862ceb66

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