@unbrained/pm-cli 2026.7.4 → 2026.7.5

package/dist/core/history/history-rewrite.js

@@ -4,7 +4,7 @@
  * Implements append-only history and replay behavior for History Rewrite.
  */
 
-!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]="f03392a5-662f-5a2d-97c6-7a51a575dd39")}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]="b9f14848-6edc-507a-a543-7bf01d91db50")}catch(e){}}();
 import fs from "node:fs/promises";
 import { readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
 import { acquireLock } from "../lock/lock.js";
@@ -88,7 +88,7 @@ export async function executeHistoryRewrite(params) {
             force: params.force,
             settings: params.settings,
         })];
-    const releaseLock = await acquireLock(params.pmRoot, params.subject.id, params.settings.locks.ttl_seconds, params.author, Boolean(params.force), params.settings.governance.force_required_for_stale_lock);
+    const releaseLock = await acquireLock(params.pmRoot, params.subject.id, params.settings.locks.ttl_seconds, params.author, Boolean(params.force), params.settings.governance.force_required_for_stale_lock, params.settings.locks.wait_ms);
     try {
         const verified = await verifyHistoryRewriteNoDrift({
             pmRoot: params.pmRoot,
@@ -110,4 +110,4 @@ export async function executeHistoryRewrite(params) {
     }
 }
 //# sourceMappingURL=history-rewrite.js.map
-//# debugId=f03392a5-662f-5a2d-97c6-7a51a575dd39
+//# debugId=b9f14848-6edc-507a-a543-7bf01d91db50

package/dist/core/history/history-rewrite.js.map

@@ -1 +1 @@
-{"version":3,"file":"history-rewrite.js","sources":["core/history/history-rewrite.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/history/history-rewrite\n *\n * Implements append-only history and replay behavior for History Rewrite.\n */\nimport fs from \"node:fs/promises\";\nimport { readFileIfExists, writeFileAtomic } from \"../fs/fs-utils.js\";\nimport type { ItemTypeRegistry } from \"../item/type-registry.js\";\nimport { acquireLock } from \"../lock/lock.js\";\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\nimport { locateItem, readLocatedItem } from \"../store/item-store.js\";\nimport { resolveGovernanceKnobs } from \"../store/settings.js\";\nimport type { ItemDocument, PmSettings } from \"../../types/index.js\";\n\ntype LoadedItem = Awaited<ReturnType<typeof readLocatedItem>>;\ntype HistoryRawWriter = (filePath: string, content: string) => Promise<void>;\n\n/**\n * Documents the history rewrite subject payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryRewriteSubject {\n  id: string;\n  historyPath: string;\n}\n\n/**\n * Documents the history rewrite ownership params payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryRewriteOwnershipParams {\n  itemDocument: ItemDocument | null;\n  subjectId: string;\n  author: string;\n  force: boolean | undefined;\n  settings: PmSettings;\n}\n\n/**\n * Apply ownership_enforcement governance to a history-rewriting operation.\n * Returns the warning(s) the caller should append (empty when no conflict or strict-throws).\n * Throws PmCliError(CONFLICT) in strict mode when the assignee conflicts and --force is not set.\n */\nexport function checkHistoryRewriteOwnership(params: HistoryRewriteOwnershipParams): string[] {\n  if (!params.itemDocument) return [];\n  const assigned = params.itemDocument.metadata?.assignee?.trim();\n  if (!assigned || assigned === params.author || params.force) return [];\n\n  const governance = resolveGovernanceKnobs(params.settings);\n  if (governance.ownership_enforcement === \"strict\") {\n    throw new PmCliError(\n      `Item ${params.subjectId} is assigned to ${assigned}. Use --force to override.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  if (governance.ownership_enforcement === \"warn\") {\n    return [`ownership_warning:assignee_conflict:${params.subjectId}:${assigned}`];\n  }\n  return [];\n}\n\n/**\n * Documents the verify history rewrite drift params payload exchanged by command, SDK, and package integrations.\n */\nexport interface VerifyHistoryRewriteDriftParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in the conflict message (e.g. \"history-redact\"). */\n  operation: string;\n}\n\n/**\n * Documents the verified history rewrite state payload exchanged by command, SDK, and package integrations.\n */\nexport interface VerifiedHistoryRewriteState {\n  historyRawUnderLock: string | null;\n  locatedUnderLock: Awaited<ReturnType<typeof locateItem>>;\n  loadedItemUnderLock: LoadedItem | null;\n}\n\n/**\n * Re-read the history stream and the located item document under the acquired lock and\n * compare both with the pre-lock raw snapshots. Throws PmCliError(CONFLICT) if either\n * diverged while waiting for the lock so the caller surfaces an actionable retry.\n */\nexport async function verifyHistoryRewriteNoDrift(\n  params: VerifyHistoryRewriteDriftParams,\n): Promise<VerifiedHistoryRewriteState> {\n  const historyRawUnderLock = await readFileIfExists(params.subject.historyPath);\n  if (historyRawUnderLock !== params.historyRawBeforeLock) {\n    throw new PmCliError(\n      `History for ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  const locatedUnderLock = await locateItem(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.id_prefix,\n    params.settings.item_format,\n    params.typeRegistry.type_to_folder,\n  );\n  const loadedItemUnderLock = locatedUnderLock\n    ? await readLocatedItem(locatedUnderLock, { schema: params.settings.schema })\n    : null;\n  if ((loadedItemUnderLock?.raw ?? null) !== (params.currentItemRawBeforeLock ?? null)) {\n    throw new PmCliError(\n      `Item ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  return { historyRawUnderLock, locatedUnderLock, loadedItemUnderLock };\n}\n\n/**\n * Documents the execute history rewrite params payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExecuteHistoryRewriteParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in conflict guidance (e.g. \"history-redact\"). */\n  operation: string;\n  author: string;\n  force: boolean | undefined;\n  itemDocument: ItemDocument | null;\n  applyRewrite: (verified: VerifiedHistoryRewriteState) => Promise<void>;\n  applyPostRewrite?: (verified: VerifiedHistoryRewriteState) => Promise<string[]>;\n}\n\n/**\n * Writes the rewritten history stream and restores the under-lock snapshot on failure.\n */\nexport async function writeHistoryRawWithRollback(params: {\n  historyPath: string;\n  nextHistoryRaw: string;\n  historyRawUnderLock: string | null;\n  writeHistoryRaw?: HistoryRawWriter;\n}): Promise<void> {\n  const writeHistoryRaw = params.writeHistoryRaw ?? writeFileAtomic;\n  try {\n    await writeHistoryRaw(params.historyPath, params.nextHistoryRaw);\n  } catch (error) {\n    try {\n      if (params.historyRawUnderLock === null) {\n        await fs.rm(params.historyPath, { force: true });\n      } else {\n        await writeHistoryRaw(params.historyPath, params.historyRawUnderLock);\n      }\n    } catch (rollbackError) {\n      throw new AggregateError(\n        [error, rollbackError],\n        `History rewrite failed and rollback also failed: ${String(error)}`,\n      );\n    }\n    throw error;\n  }\n}\n\n/**\n * Shared lock/verify/ownership orchestration for history-rewrite commands.\n * Callers provide the operation-specific write/rollback logic and optional\n * post-write hook execution while this helper enforces the common governance +\n * lock sequencing contract.\n */\nexport async function executeHistoryRewrite(params: ExecuteHistoryRewriteParams): Promise<string[]> {\n  const warnings = [...checkHistoryRewriteOwnership({\n    itemDocument: params.itemDocument,\n    subjectId: params.subject.id,\n    author: params.author,\n    force: params.force,\n    settings: params.settings,\n  })];\n  const releaseLock = await acquireLock(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.locks.ttl_seconds,\n    params.author,\n    Boolean(params.force),\n    params.settings.governance.force_required_for_stale_lock,\n  );\n  try {\n    const verified = await verifyHistoryRewriteNoDrift({\n      pmRoot: params.pmRoot,\n      subject: params.subject,\n      settings: params.settings,\n      typeRegistry: params.typeRegistry,\n      historyRawBeforeLock: params.historyRawBeforeLock,\n      currentItemRawBeforeLock: params.currentItemRawBeforeLock,\n      operation: params.operation,\n    });\n    await params.applyRewrite(verified);\n    if (params.applyPostRewrite) {\n      warnings.push(...(await params.applyPostRewrite(verified)));\n    }\n    return warnings;\n  } finally {\n    await releaseLock();\n  }\n}\n"],"names":[],"mappings":"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","debugId":"f03392a5-662f-5a2d-97c6-7a51a575dd39"}
+{"version":3,"file":"history-rewrite.js","sources":["core/history/history-rewrite.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/history/history-rewrite\n *\n * Implements append-only history and replay behavior for History Rewrite.\n */\nimport fs from \"node:fs/promises\";\nimport { readFileIfExists, writeFileAtomic } from \"../fs/fs-utils.js\";\nimport type { ItemTypeRegistry } from \"../item/type-registry.js\";\nimport { acquireLock } from \"../lock/lock.js\";\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\nimport { locateItem, readLocatedItem } from \"../store/item-store.js\";\nimport { resolveGovernanceKnobs } from \"../store/settings.js\";\nimport type { ItemDocument, PmSettings } from \"../../types/index.js\";\n\ntype LoadedItem = Awaited<ReturnType<typeof readLocatedItem>>;\ntype HistoryRawWriter = (filePath: string, content: string) => Promise<void>;\n\n/**\n * Documents the history rewrite subject payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryRewriteSubject {\n  id: string;\n  historyPath: string;\n}\n\n/**\n * Documents the history rewrite ownership params payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryRewriteOwnershipParams {\n  itemDocument: ItemDocument | null;\n  subjectId: string;\n  author: string;\n  force: boolean | undefined;\n  settings: PmSettings;\n}\n\n/**\n * Apply ownership_enforcement governance to a history-rewriting operation.\n * Returns the warning(s) the caller should append (empty when no conflict or strict-throws).\n * Throws PmCliError(CONFLICT) in strict mode when the assignee conflicts and --force is not set.\n */\nexport function checkHistoryRewriteOwnership(params: HistoryRewriteOwnershipParams): string[] {\n  if (!params.itemDocument) return [];\n  const assigned = params.itemDocument.metadata?.assignee?.trim();\n  if (!assigned || assigned === params.author || params.force) return [];\n\n  const governance = resolveGovernanceKnobs(params.settings);\n  if (governance.ownership_enforcement === \"strict\") {\n    throw new PmCliError(\n      `Item ${params.subjectId} is assigned to ${assigned}. Use --force to override.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  if (governance.ownership_enforcement === \"warn\") {\n    return [`ownership_warning:assignee_conflict:${params.subjectId}:${assigned}`];\n  }\n  return [];\n}\n\n/**\n * Documents the verify history rewrite drift params payload exchanged by command, SDK, and package integrations.\n */\nexport interface VerifyHistoryRewriteDriftParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in the conflict message (e.g. \"history-redact\"). */\n  operation: string;\n}\n\n/**\n * Documents the verified history rewrite state payload exchanged by command, SDK, and package integrations.\n */\nexport interface VerifiedHistoryRewriteState {\n  historyRawUnderLock: string | null;\n  locatedUnderLock: Awaited<ReturnType<typeof locateItem>>;\n  loadedItemUnderLock: LoadedItem | null;\n}\n\n/**\n * Re-read the history stream and the located item document under the acquired lock and\n * compare both with the pre-lock raw snapshots. Throws PmCliError(CONFLICT) if either\n * diverged while waiting for the lock so the caller surfaces an actionable retry.\n */\nexport async function verifyHistoryRewriteNoDrift(\n  params: VerifyHistoryRewriteDriftParams,\n): Promise<VerifiedHistoryRewriteState> {\n  const historyRawUnderLock = await readFileIfExists(params.subject.historyPath);\n  if (historyRawUnderLock !== params.historyRawBeforeLock) {\n    throw new PmCliError(\n      `History for ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  const locatedUnderLock = await locateItem(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.id_prefix,\n    params.settings.item_format,\n    params.typeRegistry.type_to_folder,\n  );\n  const loadedItemUnderLock = locatedUnderLock\n    ? await readLocatedItem(locatedUnderLock, { schema: params.settings.schema })\n    : null;\n  if ((loadedItemUnderLock?.raw ?? null) !== (params.currentItemRawBeforeLock ?? null)) {\n    throw new PmCliError(\n      `Item ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  return { historyRawUnderLock, locatedUnderLock, loadedItemUnderLock };\n}\n\n/**\n * Documents the execute history rewrite params payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExecuteHistoryRewriteParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in conflict guidance (e.g. \"history-redact\"). */\n  operation: string;\n  author: string;\n  force: boolean | undefined;\n  itemDocument: ItemDocument | null;\n  applyRewrite: (verified: VerifiedHistoryRewriteState) => Promise<void>;\n  applyPostRewrite?: (verified: VerifiedHistoryRewriteState) => Promise<string[]>;\n}\n\n/**\n * Writes the rewritten history stream and restores the under-lock snapshot on failure.\n */\nexport async function writeHistoryRawWithRollback(params: {\n  historyPath: string;\n  nextHistoryRaw: string;\n  historyRawUnderLock: string | null;\n  writeHistoryRaw?: HistoryRawWriter;\n}): Promise<void> {\n  const writeHistoryRaw = params.writeHistoryRaw ?? writeFileAtomic;\n  try {\n    await writeHistoryRaw(params.historyPath, params.nextHistoryRaw);\n  } catch (error) {\n    try {\n      if (params.historyRawUnderLock === null) {\n        await fs.rm(params.historyPath, { force: true });\n      } else {\n        await writeHistoryRaw(params.historyPath, params.historyRawUnderLock);\n      }\n    } catch (rollbackError) {\n      throw new AggregateError(\n        [error, rollbackError],\n        `History rewrite failed and rollback also failed: ${String(error)}`,\n      );\n    }\n    throw error;\n  }\n}\n\n/**\n * Shared lock/verify/ownership orchestration for history-rewrite commands.\n * Callers provide the operation-specific write/rollback logic and optional\n * post-write hook execution while this helper enforces the common governance +\n * lock sequencing contract.\n */\nexport async function executeHistoryRewrite(params: ExecuteHistoryRewriteParams): Promise<string[]> {\n  const warnings = [...checkHistoryRewriteOwnership({\n    itemDocument: params.itemDocument,\n    subjectId: params.subject.id,\n    author: params.author,\n    force: params.force,\n    settings: params.settings,\n  })];\n  const releaseLock = await acquireLock(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.locks.ttl_seconds,\n    params.author,\n    Boolean(params.force),\n    params.settings.governance.force_required_for_stale_lock,\n    params.settings.locks.wait_ms,\n  );\n  try {\n    const verified = await verifyHistoryRewriteNoDrift({\n      pmRoot: params.pmRoot,\n      subject: params.subject,\n      settings: params.settings,\n      typeRegistry: params.typeRegistry,\n      historyRawBeforeLock: params.historyRawBeforeLock,\n      currentItemRawBeforeLock: params.currentItemRawBeforeLock,\n      operation: params.operation,\n    });\n    await params.applyRewrite(verified);\n    if (params.applyPostRewrite) {\n      warnings.push(...(await params.applyPostRewrite(verified)));\n    }\n    return warnings;\n  } finally {\n    await releaseLock();\n  }\n}\n"],"names":[],"mappings":"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","debugId":"b9f14848-6edc-507a-a543-7bf01d91db50"}

package/dist/core/item/parent-reference-policy.d.ts

@@ -11,10 +11,18 @@ export declare function normalizeParentReferencePolicy(value: string | undefined
 /**
  * Implements normalize parent reference value for the public runtime surface of this module.
  */
-export declare function normalizeParentReferenceValue(rawValue: string): string;
+export declare function normalizeParentReferenceValue(rawValue: unknown): string;
+/**
+ * Detects parent-style placeholder tokens that should never become stored ids.
+ */
+export declare function isPlaceholderReferenceToken(value: string): boolean;
 /**
  * Implements validate missing parent reference for the public runtime surface of this module.
  */
 export declare function validateMissingParentReference(parentId: string, policy: ParentReferencePolicy): {
     warnings: string[];
 };
+/**
+ * Rejects the one-node hierarchy cycle where an item points at itself.
+ */
+export declare function assertParentReferenceIsNotSelf(itemId: string, parentId: string, prefix: string): void;

package/dist/core/item/parent-reference-policy.js

@@ -1,7 +1,9 @@
 
-!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]="14feaca7-1c1f-59a0-a258-e2d33a848526")}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]="a8ef1b95-7cd2-572b-b1c3-9c782616bdf3")}catch(e){}}();
+import { normalizeItemId } from "./id.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
+const PLACEHOLDER_REFERENCE_TOKENS = new Set(["none", "null", "undefined"]);
 /**
  * Implements normalize parent reference policy for the public runtime surface of this module.
  */
@@ -19,16 +21,24 @@ export function normalizeParentReferencePolicy(value) {
  * Implements normalize parent reference value for the public runtime surface of this module.
  */
 export function normalizeParentReferenceValue(rawValue) {
+    if (typeof rawValue !== "string") {
+        throw new PmCliError("--parent must be a string. Use --unset parent to clear this field.", EXIT_CODE.USAGE);
+    }
     const value = rawValue.trim();
     if (value.length === 0) {
         throw new PmCliError("--parent must not be empty. Use --parent none to unset.", EXIT_CODE.USAGE);
     }
-    const normalized = value.toLowerCase();
-    if (normalized === "none" || normalized === "null" || normalized === "undefined") {
+    if (isPlaceholderReferenceToken(value)) {
         throw new PmCliError(`--parent must not use placeholder token "${value}". Use --unset parent to clear this field.`, EXIT_CODE.USAGE);
     }
     return value;
 }
+/**
+ * Detects parent-style placeholder tokens that should never become stored ids.
+ */
+export function isPlaceholderReferenceToken(value) {
+    return PLACEHOLDER_REFERENCE_TOKENS.has(value.trim().toLowerCase());
+}
 /**
  * Implements validate missing parent reference for the public runtime surface of this module.
  */
@@ -40,5 +50,19 @@ export function validateMissingParentReference(parentId, policy) {
         warnings: [`validation_warning:parent_reference_missing:${parentId}`],
     };
 }
+/**
+ * Rejects the one-node hierarchy cycle where an item points at itself.
+ */
+export function assertParentReferenceIsNotSelf(itemId, parentId, prefix) {
+    const normalizedItemId = normalizeItemId(itemId, prefix);
+    const normalizedParentId = normalizeItemId(parentId, prefix);
+    if (normalizedItemId !== normalizedParentId) {
+        return;
+    }
+    const normalizationDetail = parentId !== normalizedParentId || itemId !== normalizedItemId
+        ? ` (normalized from parent "${parentId}" and item "${itemId}")`
+        : "";
+    throw new PmCliError(`Parent item "${normalizedParentId}" cannot be the same as item "${normalizedItemId}"${normalizationDetail}. Use --unset parent to clear this field.`, EXIT_CODE.USAGE);
+}
 //# sourceMappingURL=parent-reference-policy.js.map
-//# debugId=14feaca7-1c1f-59a0-a258-e2d33a848526
+//# debugId=a8ef1b95-7cd2-572b-b1c3-9c782616bdf3

package/dist/core/item/parent-reference-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"parent-reference-policy.js","sources":["core/item/parent-reference-policy.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/item/parent-reference-policy\n *\n * Defines item parsing, formatting, and lifecycle helpers for Parent Reference Policy.\n */\nimport type { ParentReferencePolicy } from \"../../types/index.js\";\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\n\n/**\n * Implements normalize parent reference policy for the public runtime surface of this module.\n */\nexport function normalizeParentReferencePolicy(value: string | undefined): ParentReferencePolicy {\n  const normalized = value?.trim().toLowerCase().replaceAll(\"-\", \"_\");\n  if (normalized === \"warn\" || normalized === \"strict_error\") {\n    return normalized;\n  }\n  if (normalized === \"strict\") {\n    return \"strict_error\";\n  }\n  throw new PmCliError(\n    \"Config set parent-reference-policy requires --policy with one of: warn, strict_error (alias: strict)\",\n    EXIT_CODE.USAGE,\n  );\n}\n\n/**\n * Implements normalize parent reference value for the public runtime surface of this module.\n */\nexport function normalizeParentReferenceValue(rawValue: string): string {\n  const value = rawValue.trim();\n  if (value.length === 0) {\n    throw new PmCliError(\"--parent must not be empty. Use --parent none to unset.\", EXIT_CODE.USAGE);\n  }\n  const normalized = value.toLowerCase();\n  if (normalized === \"none\" || normalized === \"null\" || normalized === \"undefined\") {\n    throw new PmCliError(\n      `--parent must not use placeholder token \"${value}\". Use --unset parent to clear this field.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return value;\n}\n\n/**\n * Implements validate missing parent reference for the public runtime surface of this module.\n */\nexport function validateMissingParentReference(\n  parentId: string,\n  policy: ParentReferencePolicy,\n): { warnings: string[] } {\n  if (policy === \"strict_error\") {\n    throw new PmCliError(\n      `Parent item \"${parentId}\" was not found. Create it first or use --parent none.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return {\n    warnings: [`validation_warning:parent_reference_missing:${parentId}`],\n  };\n}\n"],"names":[],"mappings":";;AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAAC,KAAyB;IACtE,MAAM,UAAU,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACpE,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,cAAc,EAAE,CAAC;QAC3D,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,MAAM,IAAI,UAAU,CAClB,sGAAsG,EACtG,SAAS,CAAC,KAAK,CAChB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAAC,QAAgB;IAC5D,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,UAAU,CAAC,yDAAyD,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IACnG,CAAC;IACD,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;QACjF,MAAM,IAAI,UAAU,CAClB,4CAA4C,KAAK,4CAA4C,EAC7F,SAAS,CAAC,KAAK,CAChB,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,QAAgB,EAChB,MAA6B;IAE7B,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;QAC9B,MAAM,IAAI,UAAU,CAClB,gBAAgB,QAAQ,wDAAwD,EAChF,SAAS,CAAC,KAAK,CAChB,CAAC;IACJ,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,CAAC,+CAA+C,QAAQ,EAAE,CAAC;KACtE,CAAC;AACJ,CAAC","debugId":"14feaca7-1c1f-59a0-a258-e2d33a848526"}
+{"version":3,"file":"parent-reference-policy.js","sources":["core/item/parent-reference-policy.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/item/parent-reference-policy\n *\n * Defines item parsing, formatting, and lifecycle helpers for Parent Reference Policy.\n */\nimport type { ParentReferencePolicy } from \"../../types/index.js\";\nimport { normalizeItemId } from \"./id.js\";\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\n\nconst PLACEHOLDER_REFERENCE_TOKENS = new Set([\"none\", \"null\", \"undefined\"]);\n\n/**\n * Implements normalize parent reference policy for the public runtime surface of this module.\n */\nexport function normalizeParentReferencePolicy(value: string | undefined): ParentReferencePolicy {\n  const normalized = value?.trim().toLowerCase().replaceAll(\"-\", \"_\");\n  if (normalized === \"warn\" || normalized === \"strict_error\") {\n    return normalized;\n  }\n  if (normalized === \"strict\") {\n    return \"strict_error\";\n  }\n  throw new PmCliError(\n    \"Config set parent-reference-policy requires --policy with one of: warn, strict_error (alias: strict)\",\n    EXIT_CODE.USAGE,\n  );\n}\n\n/**\n * Implements normalize parent reference value for the public runtime surface of this module.\n */\nexport function normalizeParentReferenceValue(rawValue: unknown): string {\n  if (typeof rawValue !== \"string\") {\n    throw new PmCliError(\"--parent must be a string. Use --unset parent to clear this field.\", EXIT_CODE.USAGE);\n  }\n  const value = rawValue.trim();\n  if (value.length === 0) {\n    throw new PmCliError(\"--parent must not be empty. Use --parent none to unset.\", EXIT_CODE.USAGE);\n  }\n  if (isPlaceholderReferenceToken(value)) {\n    throw new PmCliError(\n      `--parent must not use placeholder token \"${value}\". Use --unset parent to clear this field.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return value;\n}\n\n/**\n * Detects parent-style placeholder tokens that should never become stored ids.\n */\nexport function isPlaceholderReferenceToken(value: string): boolean {\n  return PLACEHOLDER_REFERENCE_TOKENS.has(value.trim().toLowerCase());\n}\n\n/**\n * Implements validate missing parent reference for the public runtime surface of this module.\n */\nexport function validateMissingParentReference(\n  parentId: string,\n  policy: ParentReferencePolicy,\n): { warnings: string[] } {\n  if (policy === \"strict_error\") {\n    throw new PmCliError(\n      `Parent item \"${parentId}\" was not found. Create it first or use --parent none.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return {\n    warnings: [`validation_warning:parent_reference_missing:${parentId}`],\n  };\n}\n\n/**\n * Rejects the one-node hierarchy cycle where an item points at itself.\n */\nexport function assertParentReferenceIsNotSelf(itemId: string, parentId: string, prefix: string): void {\n  const normalizedItemId = normalizeItemId(itemId, prefix);\n  const normalizedParentId = normalizeItemId(parentId, prefix);\n  if (normalizedItemId !== normalizedParentId) {\n    return;\n  }\n  const normalizationDetail =\n    parentId !== normalizedParentId || itemId !== normalizedItemId\n      ? ` (normalized from parent \"${parentId}\" and item \"${itemId}\")`\n      : \"\";\n  throw new PmCliError(\n    `Parent item \"${normalizedParentId}\" cannot be the same as item \"${normalizedItemId}\"${normalizationDetail}. Use --unset parent to clear this field.`,\n    EXIT_CODE.USAGE,\n  );\n}\n"],"names":[],"mappings":";;AAMA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,MAAM,4BAA4B,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;AAE5E;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAAC,KAAyB;IACtE,MAAM,UAAU,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACpE,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,cAAc,EAAE,CAAC;QAC3D,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,MAAM,IAAI,UAAU,CAClB,sGAAsG,EACtG,SAAS,CAAC,KAAK,CAChB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAAC,QAAiB;IAC7D,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,UAAU,CAAC,oEAAoE,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9G,CAAC;IACD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,UAAU,CAAC,yDAAyD,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IACnG,CAAC;IACD,IAAI,2BAA2B,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,UAAU,CAClB,4CAA4C,KAAK,4CAA4C,EAC7F,SAAS,CAAC,KAAK,CAChB,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAAa;IACvD,OAAO,4BAA4B,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,QAAgB,EAChB,MAA6B;IAE7B,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;QAC9B,MAAM,IAAI,UAAU,CAClB,gBAAgB,QAAQ,wDAAwD,EAChF,SAAS,CAAC,KAAK,CAChB,CAAC;IACJ,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,CAAC,+CAA+C,QAAQ,EAAE,CAAC;KACtE,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAAC,MAAc,EAAE,QAAgB,EAAE,MAAc;IAC7F,MAAM,gBAAgB,GAAG,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzD,MAAM,kBAAkB,GAAG,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC7D,IAAI,gBAAgB,KAAK,kBAAkB,EAAE,CAAC;QAC5C,OAAO;IACT,CAAC;IACD,MAAM,mBAAmB,GACvB,QAAQ,KAAK,kBAAkB,IAAI,MAAM,KAAK,gBAAgB;QAC5D,CAAC,CAAC,6BAA6B,QAAQ,eAAe,MAAM,IAAI;QAChE,CAAC,CAAC,EAAE,CAAC;IACT,MAAM,IAAI,UAAU,CAClB,gBAAgB,kBAAkB,iCAAiC,gBAAgB,IAAI,mBAAmB,2CAA2C,EACrJ,SAAS,CAAC,KAAK,CAChB,CAAC;AACJ,CAAC","debugId":"a8ef1b95-7cd2-572b-b1c3-9c782616bdf3"}

package/dist/core/lock/lock.d.ts

@@ -9,12 +9,36 @@ interface LockReadResult {
     info: LockInfo | null;
     warnings: string[];
 }
+interface StaleLockRemovalResult {
+    lockInfo: LockReadResult;
+    shouldRetryCreate: boolean;
+    staleRemovalCounted: boolean;
+}
 declare function parseLockInfo(raw: string): LockReadResult;
 declare function readLockInfo(lockPath: string): Promise<LockReadResult>;
 declare function isErrno(error: unknown, code: string): boolean;
 declare function buildLockPayload(id: string, owner: string, ttlSeconds: number): LockInfo;
 declare function isStaleLock(info: LockInfo | null, ttlSeconds: number): boolean;
 declare function lockOwnerSuffix(info: LockInfo | null): string;
+/**
+ * Resolves the effective bounded wait budget for a contended lock: the
+ * PM_LOCK_WAIT_MS environment override wins when it parses as a non-negative
+ * integer, then the caller-provided budget (settings `locks.wait_ms`), then 0
+ * (fail-fast, the pre-wait behavior).
+ */
+declare function resolveLockWaitMs(waitMs: number | undefined): number;
+declare function acquireStaleCleanupGate(lockPath: string, _id: string): Promise<(() => Promise<void>) | null>;
+declare function removeConfirmedStaleLock(params: {
+    lockPath: string;
+    id: string;
+    ttlSeconds: number;
+    force: boolean;
+    forceRequiredForStaleLock: boolean;
+    staleRemovals: number;
+    waitBudgetMs: number;
+    startedAtMs: number;
+    fallbackLockInfo: LockReadResult;
+}): Promise<StaleLockRemovalResult>;
 export declare const _testOnly: {
     parseLockInfo: typeof parseLockInfo;
     readLockInfo: typeof readLockInfo;
@@ -22,9 +46,12 @@ export declare const _testOnly: {
     buildLockPayload: typeof buildLockPayload;
     isStaleLock: typeof isStaleLock;
     lockOwnerSuffix: typeof lockOwnerSuffix;
+    resolveLockWaitMs: typeof resolveLockWaitMs;
+    acquireStaleCleanupGate: typeof acquireStaleCleanupGate;
+    removeConfirmedStaleLock: typeof removeConfirmedStaleLock;
 };
 /**
  * Implements acquire lock for the public runtime surface of this module.
  */
-export declare function acquireLock(pmRoot: string, id: string, ttlSeconds: number, owner: string, force?: boolean, forceRequiredForStaleLock?: boolean): Promise<() => Promise<void>>;
+export declare function acquireLock(pmRoot: string, id: string, ttlSeconds: number, owner: string, force?: boolean, forceRequiredForStaleLock?: boolean, waitMs?: number): Promise<() => Promise<void>>;
 export {};

package/dist/core/lock/lock.js

@@ -4,9 +4,10 @@
  * Coordinates tracker lock ownership and cleanup for Lock.
  */
 
-!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]="1efcdef7-4101-5f91-8c05-8d79c6effe9d")}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]="54aefb1b-1723-52fc-bd7f-a29840fe26dc")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { runActiveOnReadHooks, runActiveOnWriteHooks, runActiveServiceOverride } from "../extensions/index.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
@@ -115,9 +116,11 @@ async function unlinkLockWithHook(lockPath, op) {
     try {
         await fs.unlink(lockPath);
         await emitLockWriteHook(lockPath, op);
+        return true;
     }
     catch {
         // Lock cleanup is best-effort.
+        return false;
     }
 }
 function isStaleLock(info, ttlSeconds) {
@@ -128,16 +131,222 @@ function isStaleLock(info, ttlSeconds) {
 function lockOwnerSuffix(info) {
     return info?.owner ? ` (owner ${info.owner})` : "";
 }
-async function handleExistingLock(lockPath, id, ttlSeconds, force, forceRequiredForStaleLock) {
-    const lockInfo = await readLockInfo(lockPath);
-    if (!isStaleLock(lockInfo.info, ttlSeconds)) {
-        throw new PmCliError(`Item ${id} is locked${lockOwnerSuffix(lockInfo.info)}`, EXIT_CODE.CONFLICT);
+const LOCK_WAIT_INITIAL_DELAY_MS = 25;
+const LOCK_WAIT_MAX_DELAY_MS = 200;
+const LOCK_CONFLICT_RETRY_HINT_MS = 250;
+const MAX_STALE_LOCK_REMOVALS = 3;
+const STALE_CLEANUP_GATE_SUFFIX = ".stale-cleanup";
+const STALE_CLEANUP_GATE_OWNER_FILE = "owner.json";
+const STALE_CLEANUP_GATE_STALE_MS = 10_000;
+// Bounds PID-reuse false positives: a live recycled PID can delay cleanup, but not indefinitely.
+const STALE_CLEANUP_GATE_MAX_ACTIVE_MS = 5 * 60_000;
+function parseNonNegativeIntegerWaitMs(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (!/^\d+$/.test(trimmed)) {
+            return undefined;
+        }
+        const parsed = Number(trimmed);
+        return Number.isSafeInteger(parsed) ? parsed : undefined;
+    }
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+        return Math.trunc(value);
+    }
+    return undefined;
+}
+/**
+ * Resolves the effective bounded wait budget for a contended lock: the
+ * PM_LOCK_WAIT_MS environment override wins when it parses as a non-negative
+ * integer, then the caller-provided budget (settings `locks.wait_ms`), then 0
+ * (fail-fast, the pre-wait behavior).
+ */
+function resolveLockWaitMs(waitMs) {
+    const envRaw = process.env.PM_LOCK_WAIT_MS;
+    const envParsed = parseNonNegativeIntegerWaitMs(envRaw);
+    if (envParsed !== undefined) {
+        return envParsed;
+    }
+    const callerParsed = parseNonNegativeIntegerWaitMs(waitMs);
+    if (callerParsed !== undefined) {
+        return callerParsed;
+    }
+    return 0;
+}
+function sleepWithJitter(baseDelayMs) {
+    const jitteredMs = Math.max(1, Math.round(baseDelayMs * (0.5 + Math.random())));
+    return new Promise((resolve) => setTimeout(resolve, jitteredMs));
+}
+function buildLockConflictError(id, info, waitedMs) {
+    const waitedSuffix = waitedMs > 0 ? ` after waiting ${waitedMs}ms` : "";
+    return new PmCliError(`Item ${id} is locked${lockOwnerSuffix(info)}${waitedSuffix}`, EXIT_CODE.CONFLICT, {
+        code: "lock_conflict",
+        recovery: {
+            retry_after_ms: LOCK_CONFLICT_RETRY_HINT_MS,
+        },
+    });
+}
+function resolveLockOverrideRelease(result) {
+    if (typeof result === "function") {
+        return result;
+    }
+    if (typeof result === "object" && result !== null && "release" in result) {
+        const release = result.release;
+        return typeof release === "function" ? release : null;
     }
-    if (!force && forceRequiredForStaleLock) {
+    return null;
+}
+function throwIfStaleLockNeedsForce(id, lockInfo, force, forceRequired) {
+    if (!force && forceRequired) {
         const warningSuffix = lockInfo.warnings.length > 0 ? ` (${lockInfo.warnings.join(",")})` : "";
         throw new PmCliError(`Item ${id} lock is stale${warningSuffix}; rerun with --force when supported for this command`, EXIT_CODE.CONFLICT);
     }
-    await unlinkLockWithHook(lockPath, "lock:stale_remove");
+}
+function parseStaleCleanupGateOwner(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const candidate = parsed;
+    const pid = candidate.pid;
+    const token = candidate.token;
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0 || typeof token !== "string" || token.length === 0) {
+        return null;
+    }
+    return { pid, token };
+}
+async function readStaleCleanupGateOwner(gatePath) {
+    try {
+        return parseStaleCleanupGateOwner(await fs.readFile(path.join(gatePath, STALE_CLEANUP_GATE_OWNER_FILE), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (isErrno(error, "ESRCH")) {
+            return false;
+        }
+        return true;
+    }
+}
+async function removeStaleCleanupGateDirectory(gatePath) {
+    try {
+        await fs.rm(gatePath, { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function releaseStaleCleanupGate(gatePath, token) {
+    const owner = await readStaleCleanupGateOwner(gatePath);
+    if (owner === null || owner.token !== token) {
+        return;
+    }
+    await removeStaleCleanupGateDirectory(gatePath);
+}
+async function tryCreateStaleCleanupGate(gatePath) {
+    try {
+        await fs.mkdir(gatePath);
+    }
+    catch (error) {
+        if (isErrno(error, "EEXIST")) {
+            return null;
+        }
+        return null;
+    }
+    const owner = { pid: process.pid, token: randomUUID() };
+    try {
+        await fs.writeFile(path.join(gatePath, STALE_CLEANUP_GATE_OWNER_FILE), `${JSON.stringify(owner)}\n`, "utf8");
+    }
+    catch {
+        await removeStaleCleanupGateDirectory(gatePath);
+        return null;
+    }
+    return owner;
+}
+async function removeExpiredStaleCleanupGate(gatePath) {
+    let gateAgeMs;
+    try {
+        const stats = await fs.stat(gatePath);
+        gateAgeMs = Date.now() - stats.mtimeMs;
+        if (gateAgeMs <= STALE_CLEANUP_GATE_STALE_MS) {
+            return false;
+        }
+    }
+    catch (error) {
+        return isErrno(error, "ENOENT");
+    }
+    const owner = await readStaleCleanupGateOwner(gatePath);
+    if (owner !== null && isProcessAlive(owner.pid) && gateAgeMs <= STALE_CLEANUP_GATE_MAX_ACTIVE_MS) {
+        return false;
+    }
+    return removeStaleCleanupGateDirectory(gatePath);
+}
+async function acquireStaleCleanupGate(lockPath, _id) {
+    const gatePath = `${lockPath}${STALE_CLEANUP_GATE_SUFFIX}`;
+    const owner = await tryCreateStaleCleanupGate(gatePath);
+    if (owner !== null) {
+        return async () => releaseStaleCleanupGate(gatePath, owner.token);
+    }
+    if (!(await removeExpiredStaleCleanupGate(gatePath))) {
+        return null;
+    }
+    const recoveredOwner = await tryCreateStaleCleanupGate(gatePath);
+    if (recoveredOwner === null) {
+        return null;
+    }
+    return async () => releaseStaleCleanupGate(gatePath, recoveredOwner.token);
+}
+async function removeConfirmedStaleLock(params) {
+    const releaseCleanupGate = await acquireStaleCleanupGate(params.lockPath, params.id);
+    if (releaseCleanupGate === null) {
+        return {
+            lockInfo: params.fallbackLockInfo,
+            shouldRetryCreate: false,
+            staleRemovalCounted: false,
+        };
+    }
+    try {
+        const currentLockInfo = await readLockInfo(params.lockPath);
+        if (currentLockInfo.info === null && currentLockInfo.warnings.length === 0) {
+            return {
+                lockInfo: currentLockInfo,
+                shouldRetryCreate: true,
+                staleRemovalCounted: false,
+            };
+        }
+        if (!isStaleLock(currentLockInfo.info, params.ttlSeconds)) {
+            return {
+                lockInfo: currentLockInfo,
+                shouldRetryCreate: false,
+                staleRemovalCounted: false,
+            };
+        }
+        throwIfStaleLockNeedsForce(params.id, currentLockInfo, params.force, params.forceRequiredForStaleLock);
+        if (params.staleRemovals >= MAX_STALE_LOCK_REMOVALS) {
+            throw buildLockConflictError(params.id, currentLockInfo.info, Date.now() - params.startedAtMs);
+        }
+        return {
+            lockInfo: currentLockInfo,
+            shouldRetryCreate: await unlinkLockWithHook(params.lockPath, "lock:stale_remove"),
+            staleRemovalCounted: true,
+        };
+    }
+    finally {
+        await releaseCleanupGate();
+    }
 }
 export const _testOnly = {
     parseLockInfo,
@@ -146,11 +355,14 @@ export const _testOnly = {
     buildLockPayload,
     isStaleLock,
     lockOwnerSuffix,
+    resolveLockWaitMs,
+    acquireStaleCleanupGate,
+    removeConfirmedStaleLock,
 };
 /**
  * Implements acquire lock for the public runtime surface of this module.
  */
-export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false, forceRequiredForStaleLock = true) {
+export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false, forceRequiredForStaleLock = true, waitMs) {
     const lockOverride = await runActiveServiceOverride("lock_acquire", {
         pm_root: pmRoot,
         id,
@@ -160,14 +372,7 @@ export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false,
         force_required_for_stale_lock: forceRequiredForStaleLock,
     });
     if (lockOverride.handled) {
-        const releaseFromFunction = typeof lockOverride.result === "function" ? lockOverride.result : null;
-        const releaseFromObject = typeof lockOverride.result === "object" &&
-            lockOverride.result !== null &&
-            "release" in lockOverride.result &&
-            typeof lockOverride.result.release === "function"
-            ? lockOverride.result.release
-            : null;
-        const release = releaseFromFunction ?? releaseFromObject;
+        const release = resolveLockOverrideRelease(lockOverride.result);
         if (release) {
             return async () => {
                 await Promise.resolve(release());
@@ -180,7 +385,11 @@ export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false,
         }
     }
     const lockPath = getLockPath(pmRoot, id);
-    for (let attempt = 0; attempt < 3; attempt += 1) {
+    const waitBudgetMs = resolveLockWaitMs(waitMs);
+    const startedAtMs = Date.now();
+    let staleRemovals = 0;
+    let backoffMs = LOCK_WAIT_INITIAL_DELAY_MS;
+    for (;;) {
         try {
             await createLockFile(lockPath, id, owner, ttlSeconds);
             return async () => {
@@ -196,10 +405,35 @@ export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false,
             if (!isErrno(error, "EEXIST")) {
                 throw new PmCliError(`Failed to acquire lock for ${id}: ${toErrorMessage(error)}`, EXIT_CODE.GENERIC_FAILURE);
             }
-            await handleExistingLock(lockPath, id, ttlSeconds, force, forceRequiredForStaleLock);
+            let lockInfo = await readLockInfo(lockPath);
+            if (isStaleLock(lockInfo.info, ttlSeconds)) {
+                const staleRemoval = await removeConfirmedStaleLock({
+                    lockPath,
+                    id,
+                    ttlSeconds,
+                    force,
+                    forceRequiredForStaleLock,
+                    staleRemovals,
+                    waitBudgetMs,
+                    startedAtMs,
+                    fallbackLockInfo: lockInfo,
+                });
+                lockInfo = staleRemoval.lockInfo;
+                if (staleRemoval.staleRemovalCounted) {
+                    staleRemovals += 1;
+                }
+                if (staleRemoval.shouldRetryCreate) {
+                    continue;
+                }
+            }
+            const elapsedMs = Date.now() - startedAtMs;
+            if (waitBudgetMs === 0 || elapsedMs >= waitBudgetMs) {
+                throw buildLockConflictError(id, lockInfo.info, waitBudgetMs === 0 ? 0 : elapsedMs);
+            }
+            await sleepWithJitter(Math.min(backoffMs, waitBudgetMs - elapsedMs));
+            backoffMs = Math.min(backoffMs * 2, LOCK_WAIT_MAX_DELAY_MS);
         }
     }
-    throw new PmCliError(`Failed to acquire lock for ${id}`, EXIT_CODE.CONFLICT);
 }
 //# sourceMappingURL=lock.js.map
-//# debugId=1efcdef7-4101-5f91-8c05-8d79c6effe9d
+//# debugId=54aefb1b-1723-52fc-bd7f-a29840fe26dc