wendkeep 0.62.0 → 0.63.0

package/packages/vault/src/vault-path-safety.mjs

@@ -12,6 +12,12 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 
 export const VAULT_LOCK_BUSY = Symbol('wendkeep:vault-lock-busy');
 export const VAULT_LOCK_OWNER_FILE = '.owner.json';
+const VAULT_PATH_FAILURE = Symbol('wendkeep:vault-path-failure');
+const VAULT_PATH_CREATED = Symbol('wendkeep:vault-path-created');
+const VAULT_LOCK_RETRY_DEADLINE = Symbol('wendkeep:vault-lock-retry-deadline');
+const VAULT_LOCK_TOPOLOGY_RETRIES = 3;
+const VAULT_LOCK_TOPOLOGY_RETRY_MS = 10;
+const VAULT_LOCK_RELEASE_RETRY_WINDOW_MS = 50;
 
 function pathKey(value) {
   const normalized = resolve(value).replaceAll('\\', '/').replace(/^\\\\\?\//, '');
@@ -106,6 +112,10 @@ export function assertVaultPathSafe(vaultBase, targetPath, {
     } catch (cause) {
       const error = unsafe(`${label} possui componente dangling ou irresolvível: ${logicalCursor}`, code);
       error.cause = cause;
+      error[VAULT_PATH_FAILURE] = {
+        kind: 'component-realpath',
+        component: logicalCursor,
+      };
       throw error;
     }
     const expectedPhysical = join(physicalRoot, ...segments.slice(0, index + 1));
@@ -118,8 +128,23 @@ export function assertVaultPathSafe(vaultBase, targetPath, {
     }
   }
 
-  if (!exists && !allowMissing) throw unsafe(`${label} inexistente: ${target}`, code);
-  if (exists && mustNotExist) throw unsafe(`${label} preexistente: ${target}`, code);
+  if (!exists && !allowMissing) {
+    const error = unsafe(`${label} inexistente: ${target}`, code);
+    error[VAULT_PATH_FAILURE] = {
+      kind: 'component-missing',
+      component: target,
+      causeCode: 'ENOENT',
+    };
+    throw error;
+  }
+  if (exists && mustNotExist) {
+    const error = unsafe(`${label} preexistente: ${target}`, code);
+    error[VAULT_PATH_FAILURE] = {
+      kind: 'target-preexisting',
+      component: target,
+    };
+    throw error;
+  }
   if (exists) {
     if (targetStat?.isFile() && targetStat.nlink > 1) {
       throw unsafe(`${label} preexistente possui hardlink (nlink=${targetStat.nlink}): ${target}`, code);
@@ -160,16 +185,25 @@ export function mkdirVaultPath(vaultBase, targetPath, {
   let checked = assertVaultPathSafe(vaultBase, targetPath, {
     expectedType: 'directory', label, code,
   });
-  if (exclusive || !checked.exists) {
-    // Deliberately adjacent to mkdir: this is the last userspace check before mutation.
-    checked = assertVaultPathSafe(vaultBase, targetPath, {
-      expectedType: 'directory', label, code,
-    });
-    mkdirSync(checked.target, { recursive: exclusive ? false : recursive });
+  let created = false;
+  try {
+    if (exclusive || !checked.exists) {
+      // Deliberately adjacent to mkdir: this is the last userspace check before mutation.
+      checked = assertVaultPathSafe(vaultBase, targetPath, {
+        expectedType: 'directory', label, code,
+      });
+      mkdirSync(checked.target, { recursive: exclusive ? false : recursive });
+      created = true;
+    }
+    return assertVaultPathSafe(vaultBase, targetPath, {
+      allowMissing: false, expectedType: 'directory', label, code,
+    }).target;
+  } catch (error) {
+    // Callers may safely clean only a directory whose mkdir syscall actually succeeded.
+    // In particular, EEXIST must never authorize cleanup of a pre-existing path.
+    if (created) error[VAULT_PATH_CREATED] = checked.target;
+    throw error;
   }
-  return assertVaultPathSafe(vaultBase, targetPath, {
-    allowMissing: false, expectedType: 'directory', label, code,
-  }).target;
 }
 
 export function writeVaultFileSync(vaultBase, targetPath, content, encoding = 'utf8', {
@@ -301,25 +335,69 @@ function waitBriefly(ms) {
   Atomics.wait(signal, 0, 0, ms);
 }
 
-// A lock may legitimately disappear between lstat and realpath while another owner
-// releases/replaces that exact canonical directory. Retry only when the original
-// failure is the resulting ENOENT and a fresh walk still resolves to either the
-// canonical directory or a missing suffix. Junctions/reparse points and every other
-// unsafe topology keep failing closed.
-function retryableLockTopologyRace(vaultBase, lock, error, code) {
-  if (error?.cause?.code !== 'ENOENT'
-    || (error?.code !== code && error?.code !== 'VAULT_PATH_UNSAFE')) return false;
-  for (let attempt = 0; attempt < 3; attempt += 1) {
+// A public lock may legitimately disappear while another owner releases it. Only ENOENT
+// observed by an operation explicitly scoped to that canonical lock receives bounded
+// backoff; private .pending paths and every unsafe topology fail closed.
+function retryablePublicLockError(lock, error, code, { allowRaw = true } = {}) {
+  const failure = error?.[VAULT_PATH_FAILURE];
+  if (!failure) return allowRaw && error?.code === 'ENOENT' && !error?.cause;
+  const causeCode = error?.cause?.code || failure.causeCode;
+  return causeCode === 'ENOENT'
+    && (error?.code === code || error?.code === 'VAULT_PATH_UNSAFE')
+    && ['component-realpath', 'component-missing'].includes(failure.kind)
+    && containedBy(resolve(lock), resolve(failure.component));
+}
+
+function vaultLockRenameCollision(error, pending, lock) {
+  const acceptedCodes = process.platform === 'win32'
+    ? ['EEXIST', 'ENOTEMPTY', 'EPERM']
+    : ['EEXIST', 'ENOTEMPTY'];
+  return acceptedCodes.includes(error?.code)
+    && error?.syscall === 'rename'
+    && typeof error?.path === 'string'
+    && typeof error?.dest === 'string'
+    && pathKey(error.path) === pathKey(pending)
+    && pathKey(error.dest) === pathKey(lock);
+}
+
+function preexistingPublicLockError(lock, error, code) {
+  const failure = error?.[VAULT_PATH_FAILURE];
+  return failure?.kind === 'target-preexisting'
+    && (error?.code === code || error?.code === 'VAULT_PATH_UNSAFE')
+    && typeof failure.component === 'string'
+    && pathKey(failure.component) === pathKey(lock);
+}
+
+function vaultLockRetryDeadlineError() {
+  const error = new Error('deadline de retry do lock do Vault esgotado');
+  error[VAULT_LOCK_RETRY_DEADLINE] = true;
+  return error;
+}
+
+function withPublicLockRetry(lock, code, retryState, operation, initialError = null) {
+  let error = initialError;
+  while (true) {
+    if (error) {
+      if (!retryablePublicLockError(lock, error, code)
+        || retryState.remaining <= 0) throw error;
+      const remainingMs = retryState.deadline - Date.now();
+      if (remainingMs <= 0) throw vaultLockRetryDeadlineError();
+      retryState.remaining -= 1;
+      waitBriefly(Math.min(VAULT_LOCK_TOPOLOGY_RETRY_MS, remainingMs));
+      if (Date.now() >= retryState.deadline) throw vaultLockRetryDeadlineError();
+    }
     try {
-      assertVaultPathSafe(vaultBase, lock, {
-        expectedType: 'directory', label: 'lock de escrita do Vault', code,
-      });
-      return true;
-    } catch (recheckError) {
-      if (recheckError?.cause?.code !== 'ENOENT') return false;
+      return operation();
+    } catch (nextError) {
+      error = nextError;
     }
   }
-  return false;
+}
+
+function inspectVaultLock(vaultBase, lock, code, retryState, initialError = null) {
+  return withPublicLockRetry(lock, code, retryState, () => assertVaultPathSafe(vaultBase, lock, {
+    expectedType: 'directory', label: 'lock de escrita do Vault', code,
+  }), initialError);
 }
 
 function processIsAlive(pid) {
@@ -333,23 +411,44 @@ function processIsAlive(pid) {
   }
 }
 
-function vaultLockOwner(vaultBase, lock, code) {
-  const path = join(lock, VAULT_LOCK_OWNER_FILE);
-  const checked = assertVaultPathSafe(vaultBase, path, {
-    expectedType: 'file', label: 'owner do lock de escrita do Vault', code,
-  });
-  if (!checked.exists) return { owner: null, path: checked.target, raw: '' };
-  const raw = readFileSync(checked.target, 'utf8');
-  try {
-    const owner = JSON.parse(raw);
-    const valid = owner?.v === 1
-      && Number.isSafeInteger(owner.pid) && owner.pid > 0
-      && typeof owner.token === 'string' && owner.token.length > 0
-      && typeof owner.created_at === 'string' && owner.created_at.length > 0;
-    return { owner: valid ? owner : null, path: checked.target, raw };
-  } catch {
-    return { owner: null, path: checked.target, raw };
-  }
+function vaultLockOwner(vaultBase, lock, code, retryState = null) {
+  const inspect = () => {
+    const checkedLock = assertVaultPathSafe(vaultBase, lock, {
+      expectedType: 'directory', label: 'lock de escrita do Vault', code,
+    });
+    const path = join(lock, VAULT_LOCK_OWNER_FILE);
+    if (!checkedLock.exists) {
+      return {
+        lockExists: false, ownerExists: false, owner: null, path, raw: '',
+      };
+    }
+    const checked = assertVaultPathSafe(vaultBase, path, {
+      expectedType: 'file', label: 'owner do lock de escrita do Vault', code,
+    });
+    if (!checked.exists) {
+      return {
+        lockExists: true, ownerExists: false, owner: null, path: checked.target, raw: '',
+      };
+    }
+    const raw = readFileSync(checked.target, 'utf8');
+    try {
+      const owner = JSON.parse(raw);
+      const valid = owner?.v === 1
+        && Number.isSafeInteger(owner.pid) && owner.pid > 0
+        && typeof owner.token === 'string' && owner.token.length > 0
+        && typeof owner.created_at === 'string' && owner.created_at.length > 0;
+      return {
+        lockExists: true, ownerExists: true, owner: valid ? owner : null, path: checked.target, raw,
+      };
+    } catch {
+      return {
+        lockExists: true, ownerExists: true, owner: null, path: checked.target, raw,
+      };
+    }
+  };
+  return retryState
+    ? withPublicLockRetry(lock, code, retryState, inspect)
+    : inspect();
 }
 
 function vaultLockLease(lock, token) {
@@ -383,91 +482,138 @@ function removePreparedVaultLock(vaultBase, lock, token, code) {
   });
 }
 
-function releaseOwnedVaultLock(vaultBase, lock, { pid, token, code }) {
-  const observed = vaultLockOwner(vaultBase, lock, code).owner;
+function releaseOwnedVaultLock(vaultBase, lock, {
+  pid, token, code, retryState,
+}) {
+  const observedState = vaultLockOwner(vaultBase, lock, code, retryState);
+  if (!observedState.lockExists) return true;
+  const observed = observedState.owner;
   if (observed?.pid !== pid || observed?.token !== token) return false;
   // The token-specific lease is the filesystem CAS. An old finally/reaper can only
   // remove the directory after successfully unlinking the lease it originally saw;
   // a replacement lock never contains that unguessable path.
-  const leaseRemoved = unlinkVaultFile(vaultBase, vaultLockLease(lock, token), {
-    label: 'lease do lock de escrita do Vault', code,
-  });
+  const leaseRemoved = withPublicLockRetry(lock, code, retryState, () => unlinkVaultFile(
+    vaultBase, vaultLockLease(lock, token), {
+      label: 'lease do lock de escrita do Vault', code,
+    },
+  ));
   if (!leaseRemoved) return false;
-  const current = vaultLockOwner(vaultBase, lock, code).owner;
+  const currentState = vaultLockOwner(vaultBase, lock, code, retryState);
+  if (!currentState.lockExists) return true;
+  const current = currentState.owner;
   if (current?.pid !== pid || current?.token !== token) return false;
   const ownerPath = join(lock, VAULT_LOCK_OWNER_FILE);
-  if (!unlinkVaultFile(vaultBase, ownerPath, {
-    label: 'owner do lock de escrita do Vault', code,
-  })) return false;
-  return removeVaultLockDirectory(vaultBase, lock, {
-    missingOk: false, label: 'lock de escrita do Vault', code,
-  });
+  if (!withPublicLockRetry(lock, code, retryState, () => unlinkVaultFile(
+    vaultBase, ownerPath, {
+      label: 'owner do lock de escrita do Vault', code,
+    },
+  ))) return false;
+  return withPublicLockRetry(lock, code, retryState, () => removeVaultLockDirectory(
+    vaultBase, lock, {
+      missingOk: false, label: 'lock de escrita do Vault', code,
+    },
+  ));
 }
 
-function reapDeadVaultLock(vaultBase, lock, staleMs, code) {
-  const checked = assertVaultPathSafe(vaultBase, lock, {
-    expectedType: 'directory', label: 'lock de escrita do Vault', code,
+function reapDeadVaultLock(vaultBase, lock, staleMs, code, retryState) {
+  const initial = withPublicLockRetry(lock, code, retryState, () => {
+    const checked = assertVaultPathSafe(vaultBase, lock, {
+      expectedType: 'directory', label: 'lock de escrita do Vault', code,
+    });
+    if (!checked.exists) return null;
+    return { checked, before: statSync(checked.target) };
   });
-  if (!checked.exists) return true;
-  let before;
-  try {
-    before = statSync(checked.target);
-  } catch (error) {
-    if (error?.code === 'ENOENT') return true;
-    throw error;
-  }
+  if (!initial) return true;
+  const { checked, before } = initial;
   if (Date.now() - before.mtimeMs <= staleMs) return false;
-  const observed = vaultLockOwner(vaultBase, checked.target, code);
+  const observed = vaultLockOwner(vaultBase, checked.target, code, retryState);
+  if (!observed.lockExists) return true;
   if (observed.owner) {
     if (processIsAlive(observed.owner.pid)) return false;
-    const lease = assertVaultPathSafe(vaultBase, vaultLockLease(checked.target, observed.owner.token), {
-      expectedType: 'file', label: 'lease do lock de escrita do Vault', code,
+    const lease = withPublicLockRetry(lock, code, retryState, () => {
+      const current = assertVaultPathSafe(vaultBase, lock, {
+        expectedType: 'directory', label: 'lock de escrita do Vault', code,
+      });
+      if (!current.exists) return null;
+      return assertVaultPathSafe(vaultBase, vaultLockLease(current.target, observed.owner.token), {
+        expectedType: 'file', label: 'lease do lock de escrita do Vault', code,
+      });
     });
+    if (!lease) return true;
     if (lease.exists) {
       return releaseOwnedVaultLock(vaultBase, checked.target, {
-        pid: observed.owner.pid, token: observed.owner.token, code,
+        pid: observed.owner.pid, token: observed.owner.token, code, retryState,
       });
     }
     // Compatibility with owner-aware locks from 0.58.x, which predate token leases.
     // A dead PID plus byte-identical owner and directory identity is sufficient here;
     // a live legacy owner was returned above and is never reaped by age.
-    const entries = readdirSync(checked.target);
+    const legacy = withPublicLockRetry(lock, code, retryState, () => {
+      const current = assertVaultPathSafe(vaultBase, lock, {
+        expectedType: 'directory', label: 'lock legado de escrita do Vault', code,
+      });
+      if (!current.exists) return null;
+      return {
+        entries: readdirSync(current.target),
+        currentStat: statSync(current.target),
+        currentOwner: vaultLockOwner(vaultBase, current.target, code),
+      };
+    });
+    if (!legacy) return true;
+    const { entries, currentStat, currentOwner } = legacy;
     if (entries.some((name) => name !== VAULT_LOCK_OWNER_FILE)) return false;
-    const currentStat = statSync(checked.target);
-    const currentOwner = vaultLockOwner(vaultBase, checked.target, code);
     if (currentStat.birthtimeMs !== before.birthtimeMs
       || currentStat.mtimeMs !== before.mtimeMs
       || currentOwner.raw !== observed.raw) return false;
-    if (!unlinkVaultFile(vaultBase, currentOwner.path, {
-      label: 'owner legado morto do lock de escrita do Vault', code,
-    })) return false;
-    return removeVaultLockDirectory(vaultBase, checked.target, {
-      missingOk: false, label: 'lock legado de escrita do Vault', code,
-    });
+    if (!withPublicLockRetry(lock, code, retryState, () => unlinkVaultFile(
+      vaultBase, currentOwner.path, {
+        label: 'owner legado morto do lock de escrita do Vault', code,
+      },
+    ))) return false;
+    return withPublicLockRetry(lock, code, retryState, () => removeVaultLockDirectory(
+      vaultBase, checked.target, {
+        missingOk: false, label: 'lock legado de escrita do Vault', code,
+      },
+    ));
   }
 
   // Locks are published by atomic directory rename only after owner + lease exist.
   // Thus an old empty/partial directory is legacy or crash residue, never an in-flight
   // live acquisition. Unknown children remain fail-closed.
-  const entries = readdirSync(checked.target);
-  for (const name of entries) {
-    assertVaultPathSafe(vaultBase, join(checked.target, name), {
-      allowMissing: false, expectedType: 'file', label: `resíduo do lock do Vault ${name}`, code,
+  const partial = withPublicLockRetry(lock, code, retryState, () => {
+    const current = assertVaultPathSafe(vaultBase, lock, {
+      expectedType: 'directory', label: 'lock de escrita do Vault', code,
     });
-  }
+    if (!current.exists) return null;
+    const entries = readdirSync(current.target);
+    for (const name of entries) {
+      assertVaultPathSafe(vaultBase, join(current.target, name), {
+        allowMissing: false, expectedType: 'file', label: `resíduo do lock do Vault ${name}`, code,
+      });
+    }
+    return {
+      entries,
+      currentStat: statSync(current.target),
+      currentOwner: vaultLockOwner(vaultBase, current.target, code),
+    };
+  });
+  if (!partial) return true;
+  const { entries, currentStat, currentOwner } = partial;
   if (entries.some((name) => name !== VAULT_LOCK_OWNER_FILE)) return false;
-  const currentStat = statSync(checked.target);
-  const currentOwner = vaultLockOwner(vaultBase, checked.target, code);
   if (currentStat.birthtimeMs !== before.birthtimeMs
     || currentStat.mtimeMs !== before.mtimeMs
     || currentOwner.raw !== observed.raw) return false;
   if (entries.includes(VAULT_LOCK_OWNER_FILE)
-    && !unlinkVaultFile(vaultBase, currentOwner.path, {
-      label: 'owner parcial do lock de escrita do Vault', code,
-    })) return false;
-  return removeVaultLockDirectory(vaultBase, checked.target, {
-    missingOk: false, label: 'lock de escrita do Vault', code,
-  });
+    && !withPublicLockRetry(lock, code, retryState, () => unlinkVaultFile(
+      vaultBase, currentOwner.path, {
+        label: 'owner parcial do lock de escrita do Vault', code,
+      },
+    ))) return false;
+  return withPublicLockRetry(lock, code, retryState, () => removeVaultLockDirectory(
+    vaultBase, checked.target, {
+      missingOk: false, label: 'lock de escrita do Vault', code,
+    },
+  ));
 }
 
 export function withVaultPathLock(vaultBase, path, fn, {
@@ -478,80 +624,103 @@ export function withVaultPathLock(vaultBase, path, fn, {
   const lock = `${path}.lock`;
   const deadline = Date.now() + timeoutMs;
   const token = randomUUID();
-  while (true) {
-    let current;
-    try {
-      current = assertVaultPathSafe(vaultBase, lock, {
-        expectedType: 'directory', label: 'lock de escrita do Vault', code,
-      });
-    } catch (error) {
-      if (retryableLockTopologyRace(vaultBase, lock, error, code)) continue;
-      throw error;
-    }
-    if (current.exists) {
-      let reaped = false;
-      try { reaped = reapDeadVaultLock(vaultBase, lock, staleMs, code); }
-      catch (error) {
-        if (retryableLockTopologyRace(vaultBase, lock, error, code)) continue;
-        if (error?.code === code || error?.code === 'VAULT_PATH_UNSAFE') throw error;
+  const retryState = { deadline, remaining: VAULT_LOCK_TOPOLOGY_RETRIES };
+  let firstAttempt = true;
+  try {
+    while (true) {
+      if (!firstAttempt && Date.now() >= deadline) return VAULT_LOCK_BUSY;
+      firstAttempt = false;
+      const current = inspectVaultLock(vaultBase, lock, code, retryState);
+      if (current.exists) {
+        const reaped = reapDeadVaultLock(vaultBase, lock, staleMs, code, retryState);
+        if (reaped) continue;
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) return VAULT_LOCK_BUSY;
+        waitBriefly(Math.min(10, remainingMs));
+        continue;
       }
-      if (reaped) continue;
-      if (Date.now() >= deadline) return VAULT_LOCK_BUSY;
-      waitBriefly(10);
-      continue;
-    }
 
-    const pending = `${lock}.${process.pid}.${token}.pending`;
-    let pendingCreated = false;
-    try {
-      mkdirVaultPath(vaultBase, pending, {
-        recursive: false, exclusive: true, label: 'lock de escrita do Vault', code,
-      });
-      pendingCreated = true;
-      writeVaultFileAtomic(vaultBase, join(pending, VAULT_LOCK_OWNER_FILE), `${JSON.stringify({
-        v: 1,
-        pid: process.pid,
-        token,
-        created_at: new Date().toISOString(),
-      })}\n`, 'utf8', { label: 'owner do lock de escrita do Vault', code });
-      writeVaultFileAtomic(vaultBase, vaultLockLease(pending, token), `${token}\n`, 'utf8', {
-        label: 'lease do lock de escrita do Vault', code,
-      });
-      const raced = assertVaultPathSafe(vaultBase, lock, {
-        expectedType: 'directory', label: 'lock de escrita do Vault', code,
-      });
-      if (raced.exists) {
-        removePreparedVaultLock(vaultBase, pending, token, code);
-      } else {
+      const pending = `${lock}.${process.pid}.${token}.pending`;
+      let pendingCreated = false;
+      try {
         try {
-          renameVaultPath(vaultBase, pending, lock, {
-            sourceType: 'directory', label: 'publicação do lock de escrita do Vault', code,
+          mkdirVaultPath(vaultBase, pending, {
+            recursive: false, exclusive: true, label: 'lock de escrita do Vault', code,
           });
-          break;
+          pendingCreated = true;
         } catch (error) {
-          const raced = assertVaultPathSafe(vaultBase, lock, {
-            expectedType: 'directory', label: 'lock de escrita do Vault', code,
-          });
-          if (!raced.exists) throw error;
+          pendingCreated = typeof error?.[VAULT_PATH_CREATED] === 'string'
+            && pathKey(error[VAULT_PATH_CREATED]) === pathKey(pending);
+          throw error;
+        }
+        writeVaultFileAtomic(vaultBase, join(pending, VAULT_LOCK_OWNER_FILE), `${JSON.stringify({
+          v: 1,
+          pid: process.pid,
+          token,
+          created_at: new Date().toISOString(),
+        })}\n`, 'utf8', { label: 'owner do lock de escrita do Vault', code });
+        writeVaultFileAtomic(vaultBase, vaultLockLease(pending, token), `${token}\n`, 'utf8', {
+          label: 'lease do lock de escrita do Vault', code,
+        });
+        const raced = inspectVaultLock(vaultBase, lock, code, retryState);
+        if (raced.exists) {
           removePreparedVaultLock(vaultBase, pending, token, code);
+        } else {
+          try {
+            renameVaultPath(vaultBase, pending, lock, {
+              sourceType: 'directory', label: 'publicação do lock de escrita do Vault', code,
+            });
+            break;
+          } catch (error) {
+            const retryableRenameRace = retryablePublicLockError(lock, error, code, {
+              allowRaw: false,
+            });
+            const nativeRenameCollision = vaultLockRenameCollision(error, pending, lock);
+            const preflightRenameCollision = preexistingPublicLockError(lock, error, code);
+            if (!retryableRenameRace && !nativeRenameCollision && !preflightRenameCollision) {
+              throw error;
+            }
+            const racedAfterRename = inspectVaultLock(
+              vaultBase, lock, code, retryState, retryableRenameRace ? error : null,
+            );
+            if (!racedAfterRename.exists) {
+              // EPERM is ambiguous on Windows; without an extant destination it remains fatal.
+              if (error?.code === 'EPERM') throw error;
+              removePreparedVaultLock(vaultBase, pending, token, code);
+              continue;
+            }
+            removePreparedVaultLock(vaultBase, pending, token, code);
+          }
         }
+      } catch (error) {
+        if (pendingCreated) {
+          try { removePreparedVaultLock(vaultBase, pending, token, code); }
+          catch { /* residue private remains recoverable; never clean through an alias */ }
+        }
+        throw error;
       }
-    } catch (error) {
-      if (pendingCreated) {
-        try { removePreparedVaultLock(vaultBase, pending, token, code); }
-        catch { /* residue private remains recoverable; never clean through an alias */ }
-      }
-      throw error;
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) return VAULT_LOCK_BUSY;
+      waitBriefly(Math.min(10, remainingMs));
     }
-    if (Date.now() >= deadline) return VAULT_LOCK_BUSY;
-    waitBriefly(10);
+  } catch (error) {
+    if (error?.[VAULT_LOCK_RETRY_DEADLINE]) return VAULT_LOCK_BUSY;
+    throw error;
   }
 
   try {
     return fn();
   } finally {
     try {
-      releaseOwnedVaultLock(vaultBase, lock, { pid: process.pid, token, code });
+      releaseOwnedVaultLock(vaultBase, lock, {
+        pid: process.pid,
+        token,
+        code,
+        retryState: {
+          deadline: Date.now() + VAULT_LOCK_RELEASE_RETRY_WINDOW_MS,
+          remaining: VAULT_LOCK_TOPOLOGY_RETRIES,
+        },
+      });
     }
     catch { /* a failed safe release leaves the lock in place; never remove through an alias */ }
   }