@duckmind/dm-linux-x64 0.65.4 → 0.65.6

package/extensions/dm-lens/dist/clients/instance-reaper.js

@@ -0,0 +1,577 @@
+export const STALE_HEARTBEAT_MS = 6 * 60 * 60 * 1000;
+import { spawn as nodeSpawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeFileAtomicAsync } from "./atomic-write.js";
+import { sweepOwnStagingFiles } from "./atomic-write-staging.js";
+import { acquireQuarantinePidFileLock } from "./bounded-pid-file-lock.js";
+import { unrefChildAndPipes } from "./child-unref.js";
+import { incrementDegradationCount, recordDegradationOnce } from "./degradation-ledger.js";
+import { getGlobalDmLensDir } from "./file-utils.js";
+import { resolveBackstopStateDir } from "./instance-reaper-state.js";
+import { isInstanceRegistryEnabled, pruneDeadInstances as pruneDeadRegistryInstances, readInstanceRegistry } from "./instance-registry.js";
+import { logLatency } from "./latency-logger.js";
+import { queryProcessTable, windowsExe } from "./process-snapshot.js";
+const isWindows = process.platform === "win32";
+function isInstanceKillEligible(instance, isPidAlive) {
+  return !isPidAlive(instance.pid);
+}
+function isInstanceEntryStale(instance, now) {
+  const heartbeatMs = Date.parse(instance.heartbeatAt);
+  if (Number.isNaN(heartbeatMs))
+    return true;
+  return now - heartbeatMs > STALE_HEARTBEAT_MS;
+}
+function collectLiveMarkers(registry, isPidAlive) {
+  const liveMarkers = new Set;
+  for (const instance of registry) {
+    if (!isPidAlive(instance.pid))
+      continue;
+    for (const child of instance.lspChildren) {
+      if (child.marker)
+        liveMarkers.add(child.marker);
+    }
+  }
+  return liveMarkers;
+}
+function classifyDeadInstanceChildren(instance, isPidAlive, matchProcess, liveMarkers, out) {
+  for (const child of instance.lspChildren) {
+    const childAlive = isPidAlive(child.pid);
+    if (childAlive) {
+      const identityOk = matchProcess ? matchProcess(child.pid, {
+        command: child.command,
+        marker: child.marker
+      }) : true;
+      if (identityOk) {
+        out.childrenToKill.push({
+          pid: child.pid,
+          serverId: child.serverId,
+          command: child.command
+        });
+        continue;
+      }
+    }
+    if (child.marker && !liveMarkers.has(child.marker)) {
+      out.markerSearches.push({
+        marker: child.marker,
+        serverId: child.serverId
+      });
+    }
+  }
+}
+export function decideOrphanReaping(registry, isPidAlive, matchProcess, now = Date.now()) {
+  const deadInstances = [];
+  const staleInstances = [];
+  const childrenToKill = [];
+  const markerSearches = [];
+  const liveMarkers = collectLiveMarkers(registry, isPidAlive);
+  for (const instance of registry) {
+    if (isInstanceKillEligible(instance, isPidAlive)) {
+      deadInstances.push(instance);
+      classifyDeadInstanceChildren(instance, isPidAlive, matchProcess, liveMarkers, {
+        childrenToKill,
+        markerSearches
+      });
+    } else if (isInstanceEntryStale(instance, now)) {
+      staleInstances.push(instance);
+    }
+  }
+  return { deadInstances, staleInstances, childrenToKill, markerSearches };
+}
+export function realIsPidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0)
+    return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err?.code;
+    if (code === "ESRCH")
+      return false;
+    return true;
+  }
+}
+export const ATOMIC_STAGE_SWEEP_MAX_ENTRIES = 512;
+export async function sweepAtomicWriteStages(directories, options = {}) {
+  const requestedMax = options.maxEntries ?? ATOMIC_STAGE_SWEEP_MAX_ENTRIES;
+  const maxEntries = Number.isFinite(requestedMax) ? Math.max(1, Math.floor(requestedMax)) : ATOMIC_STAGE_SWEEP_MAX_ENTRIES;
+  const isPidAlive = options.isPidAlive ?? realIsPidAlive;
+  return sweepOwnStagingFiles(directories, { maxEntries, isPidAlive });
+}
+async function findPidsByMarkerWindows(marker) {
+  if (!isWindows || !marker)
+    return [];
+  const result = await queryProcessTable({
+    fields: ["pid"],
+    filter: { column: "CommandLine", op: "like", values: [marker] },
+    excludeSelfPid: true
+  }, {
+    timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS,
+    onTimeout: (child) => terminateScannerChild(child, {
+      kind: "orphan-backstop-scanner-escalated",
+      timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS
+    })
+  });
+  if (result.status !== "ok") {
+    recordDegradationOnce({
+      kind: "orphan-backstop-scan-failed",
+      subject: "marker-search",
+      reason: `marker command-line search ${result.status}`
+    });
+  }
+  return result.rows.map((row) => row.pid);
+}
+async function queryCommandLines(pids) {
+  const valid = [...new Set(pids.filter((p) => Number.isFinite(p) && p > 0))];
+  const map = new Map;
+  if (valid.length === 0)
+    return map;
+  const result = await queryProcessTable({
+    fields: ["pid", "command"],
+    filter: { column: "ProcessId", op: "eq", values: valid }
+  }, {
+    timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS,
+    onTimeout: (child) => terminateScannerChild(child, {
+      kind: "orphan-backstop-scanner-escalated",
+      timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS
+    })
+  });
+  const psReportedNoSuchPid = !isWindows && result.status === "exit-error";
+  if (result.status !== "ok" && !psReportedNoSuchPid) {
+    recordDegradationOnce({
+      kind: "orphan-backstop-scan-failed",
+      subject: "identity-query",
+      reason: `command-line identity query ${result.status}; reap suppressed this sweep`
+    });
+  }
+  for (const row of result.rows)
+    map.set(row.pid, row.command);
+  return map;
+}
+export function buildIdentityMatcher(cmdlines) {
+  return (pid, expected) => {
+    const cmdline = cmdlines.get(pid);
+    if (cmdline === undefined)
+      return false;
+    if (expected.marker && cmdline.includes(expected.marker))
+      return true;
+    const basename = path.basename(expected.command ?? "").toLowerCase();
+    if (!basename)
+      return false;
+    return cmdline.toLowerCase().includes(basename);
+  };
+}
+const KILL_VERIFY_ATTEMPTS = 5;
+const KILL_VERIFY_INTERVAL_MS = 100;
+function sleepUnref(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref();
+  });
+}
+async function killPidTree(pid, options = {}) {
+  if (!Number.isFinite(pid) || pid <= 0)
+    return "invalid";
+  if (isWindows) {
+    try {
+      const taskkill = windowsExe("taskkill.exe");
+      const killer = nodeSpawn(taskkill, ["/F", "/T", "/PID", String(pid)], {
+        shell: false,
+        windowsHide: true,
+        stdio: "ignore"
+      });
+      unrefChildAndPipes(killer);
+      await new Promise((resolve) => {
+        killer.once("close", () => resolve());
+        killer.once("error", () => resolve());
+      });
+    } catch {}
+  } else {
+    try {
+      process.kill(-pid, "SIGKILL");
+    } catch {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {}
+    }
+  }
+  return await verifyPidGone(pid, options);
+}
+async function verifyPidGone(pid, options = {}) {
+  const isPidAlive = options.isPidAlive ?? realIsPidAlive;
+  const attempts = Math.max(1, options.verifyAttempts ?? KILL_VERIFY_ATTEMPTS);
+  const intervalMs = Math.max(0, options.verifyIntervalMs ?? KILL_VERIFY_INTERVAL_MS);
+  for (let attempt = 0;attempt < attempts; attempt++) {
+    let alive;
+    try {
+      alive = isPidAlive(pid);
+    } catch {
+      alive = true;
+    }
+    if (!alive)
+      return "gone";
+    if (attempt < attempts - 1)
+      await sleepUnref(intervalMs);
+  }
+  return "alive";
+}
+const MANAGED_BINARIES = [
+  { name: "ast-grep", launcher: "native" },
+  { name: "opengrep-core", launcher: "native" },
+  { name: "opengrep", launcher: "native" },
+  { name: "marksman", launcher: "native" },
+  { name: "zizmor", launcher: "native" },
+  { name: "typos-lsp", launcher: "native" },
+  { name: "yaml-language-server", launcher: "node" },
+  { name: "typescript-language-server", launcher: "node" }
+];
+export const MANAGED_BINARY_NAMES = MANAGED_BINARIES.map((binary) => binary.name);
+export const MANAGED_IMAGE_NAMES = [
+  ...new Set(MANAGED_BINARIES.map((binary) => binary.launcher === "node" ? "node.exe" : `${binary.name}.exe`))
+];
+export function decideBackstopOrphanReaping(processes, registry, isPidAlive, options = {}) {
+  return partitionBackstopCandidates(processes, registry, isPidAlive, options).eligible;
+}
+export const BACKSTOP_SPAWN_GRACE_MS = 60000;
+export function partitionBackstopCandidates(processes, registry, isPidAlive, options = {}) {
+  const graceMs = Math.max(0, options.graceMs ?? BACKSTOP_SPAWN_GRACE_MS);
+  const trackedPids = new Set;
+  for (const instance of registry) {
+    for (const child of instance.lspChildren)
+      trackedPids.add(child.pid);
+  }
+  const partition = {
+    eligible: [],
+    tooFresh: [],
+    unknownAge: []
+  };
+  for (const proc of processes) {
+    if (trackedPids.has(proc.pid))
+      continue;
+    if (!Number.isFinite(proc.parentPid) || proc.parentPid <= 0)
+      continue;
+    if (proc.parentPid === proc.pid)
+      continue;
+    if (isPidAlive(proc.parentPid))
+      continue;
+    if (graceMs > 0) {
+      const ageMs = proc.ageMs;
+      if (typeof ageMs !== "number" || !Number.isFinite(ageMs)) {
+        partition.unknownAge.push(proc);
+        continue;
+      }
+      if (ageMs < graceMs) {
+        partition.tooFresh.push(proc);
+        continue;
+      }
+    }
+    partition.eligible.push(proc);
+  }
+  return partition;
+}
+async function enumerateManagedProcesses(options = {}) {
+  const scanTimeoutMs = options.timeoutMs ?? BACKSTOP_SCAN_TIMEOUT_MS;
+  const result = await queryProcessTable({
+    fields: ["pid", "ppid", "ageMs", "command"],
+    filter: { column: "Name", op: "eq", values: MANAGED_IMAGE_NAMES }
+  }, {
+    timeoutMs: scanTimeoutMs,
+    onTimeout: (child) => terminateScannerChild(child, {
+      verifyAttempts: options.verifyAttempts,
+      verifyIntervalMs: options.verifyIntervalMs,
+      kind: "orphan-backstop-scanner-escalated",
+      timeoutMs: scanTimeoutMs
+    })
+  });
+  return narrowToManagedBinaries(result.rows.map((row) => ({
+    pid: row.pid,
+    parentPid: row.ppid,
+    command: row.command,
+    ageMs: row.ageMs
+  })), result);
+}
+function narrowToManagedBinaries(processes, result) {
+  return {
+    processes: processes.filter((proc) => matchesManagedBinary(proc.command)),
+    status: result.status,
+    timeoutKill: result.timeoutKill
+  };
+}
+export async function terminateScannerChild(child, options) {
+  const pid = child.pid;
+  const outcome = typeof pid === "number" && pid > 0 ? await killPidTree(pid, {
+    verifyAttempts: options.verifyAttempts,
+    verifyIntervalMs: options.verifyIntervalMs
+  }) : "invalid";
+  incrementDegradationCount({
+    kind: options.kind,
+    subject: `${isWindows ? "win32-cim" : "posix-ps"}#${pid ?? "no-pid"}`,
+    reason: `scan exceeded its ${options.timeoutMs}ms timeout; tree kill reported ${outcome}`
+  });
+  return outcome;
+}
+export const BACKSTOP_SCAN_TIMEOUT_MS = 5000;
+function matchesManagedBinary(command) {
+  const lower = command.toLowerCase();
+  return MANAGED_BINARY_NAMES.some((name) => lower.includes(name.toLowerCase()));
+}
+export async function sweepUntrackedOrphans(options = {}) {
+  const startedAt = Date.now();
+  if (!isInstanceRegistryEnabled()) {
+    return logBackstopOutcome("disabled", startedAt, {}, options.onComplete);
+  }
+  const cooldownMs = Math.max(0, options.cooldownMs ?? BACKSTOP_COOLDOWN_MS);
+  let release = null;
+  try {
+    release = await acquireBackstopLock();
+    if (release === null) {
+      return logBackstopOutcome("concurrent", startedAt, {}, options.onComplete);
+    }
+    const throttled = await isWithinCooldown(Date.now(), cooldownMs, options);
+    if (throttled !== undefined) {
+      return logBackstopOutcome("cooldown", startedAt, {
+        sinceLastMs: throttled
+      }, options.onComplete);
+    }
+    await writeBackstopStamp(startedAt);
+    const [registry, scan] = await Promise.all([
+      readInstanceRegistry(),
+      enumerateManagedProcesses({
+        timeoutMs: options.scanTimeoutMs,
+        verifyAttempts: options.verifyAttempts,
+        verifyIntervalMs: options.verifyIntervalMs
+      })
+    ]);
+    if (scan.status !== "ok") {
+      recordDegradationOnce({
+        kind: "orphan-backstop-scan-failed",
+        subject: isWindows ? "win32-cim" : "posix-ps",
+        reason: `process enumeration ${scan.status}`
+      });
+      return logBackstopOutcome("error", startedAt, {
+        scanStatus: scan.status,
+        scannerKill: scan.timeoutKill,
+        scanned: scan.processes.length
+      }, options.onComplete);
+    }
+    const partition = partitionBackstopCandidates(scan.processes, registry, realIsPidAlive, { graceMs: options.graceMs });
+    for (const proc of partition.unknownAge) {
+      incrementDegradationCount({
+        kind: "orphan-backstop-age-unknown",
+        subject: describeManagedProcess(proc),
+        reason: "OS snapshot reported no usable process creation time"
+      });
+    }
+    const killed = [];
+    const unverified = [];
+    for (const proc of partition.eligible) {
+      const identity = describeManagedProcess(proc);
+      const outcome = await killPidTree(proc.pid, {
+        verifyAttempts: options.verifyAttempts,
+        verifyIntervalMs: options.verifyIntervalMs
+      });
+      if (outcome === "gone") {
+        killed.push(identity);
+        continue;
+      }
+      unverified.push(identity);
+      incrementDegradationCount({
+        kind: "orphan-backstop-kill-unverified",
+        subject: identity,
+        reason: `kill attempted, process still ${outcome === "alive" ? "alive" : "unresolvable"}`
+      });
+    }
+    const retryAt = scheduleGraceRetryIfNeeded(partition, options);
+    return logBackstopOutcome(classifyKillOutcome(killed.length, unverified.length), startedAt, {
+      scanStatus: scan.status,
+      scanned: scan.processes.length,
+      eligible: partition.eligible.length,
+      tooFresh: partition.tooFresh.length,
+      unknownAge: partition.unknownAge.length,
+      killed: killed.length,
+      killUnverified: unverified.length,
+      killedProcesses: killed.slice(0, BACKSTOP_IDENTITY_LOG_LIMIT),
+      unverifiedProcesses: unverified.slice(0, BACKSTOP_IDENTITY_LOG_LIMIT),
+      graceRetryInMs: retryAt
+    }, options.onComplete);
+  } catch (error) {
+    recordDegradationOnce({
+      kind: "orphan-backstop-scan-failed",
+      subject: "sweep",
+      reason: `sweep threw: ${error instanceof Error ? error.message : String(error)}`
+    });
+    return logBackstopOutcome("error", startedAt, { threw: true }, options.onComplete);
+  } finally {
+    if (release) {
+      await release().catch(() => {});
+    }
+  }
+}
+function classifyKillOutcome(killed, unverified) {
+  if (unverified === 0)
+    return killed > 0 ? "reaped" : "clean";
+  return killed > 0 ? "partial" : "unverified";
+}
+const BACKSTOP_COOLDOWN_MS = 30 * 60 * 1000;
+const BACKSTOP_START_DELAY_MS = 30000;
+const BACKSTOP_IDENTITY_LOG_LIMIT = 10;
+const BACKSTOP_GRACE_RETRY_MARGIN_MS = 30000;
+const BACKSTOP_LOCK_STALE_MS = 120000;
+export function scheduleUntrackedOrphanSweep(delayMs = BACKSTOP_START_DELAY_MS, options = {}) {
+  const timer = setTimeout(() => {
+    sweepUntrackedOrphans(options).catch(() => {});
+  }, Math.max(0, delayMs));
+  timer.unref();
+  return timer;
+}
+function scheduleGraceRetryIfNeeded(partition, options) {
+  if (options.allowGraceRetry === false)
+    return;
+  if (partition.tooFresh.length === 0)
+    return;
+  const graceMs = Math.max(0, options.graceMs ?? BACKSTOP_SPAWN_GRACE_MS);
+  const delayMs = Math.max(0, options.graceRetryDelayMs ?? graceMs + BACKSTOP_GRACE_RETRY_MARGIN_MS);
+  scheduleUntrackedOrphanSweep(delayMs, {
+    ...options,
+    force: true,
+    allowGraceRetry: false
+  });
+  options.onGraceRetryScheduled?.(delayMs);
+  return delayMs;
+}
+async function acquireBackstopLock() {
+  try {
+    return await acquireQuarantinePidFileLock(path.join(resolveBackstopStateDir(getGlobalDmLensDir()), "orphan-backstop.lock"), {
+      waitMs: 0,
+      retryMs: 50,
+      staleMs: BACKSTOP_LOCK_STALE_MS,
+      timeoutMessage: "orphan backstop sweep lock contended",
+      onContention: "skip-log",
+      logContention: () => {}
+    });
+  } catch {
+    return async () => {};
+  }
+}
+async function isWithinCooldown(now, cooldownMs, options) {
+  if (cooldownMs <= 0 || options.force)
+    return;
+  const lastSweepAt = await readBackstopStamp();
+  if (lastSweepAt === undefined)
+    return;
+  const sinceLastMs = now - lastSweepAt;
+  return sinceLastMs < cooldownMs ? sinceLastMs : undefined;
+}
+function describeManagedProcess(proc) {
+  const lower = proc.command.toLowerCase();
+  const matched = MANAGED_BINARY_NAMES.find((name) => lower.includes(name.toLowerCase()));
+  return `${matched ?? "unknown"}#${proc.pid}`;
+}
+function logBackstopOutcome(outcome, startedAt, metadata, onComplete) {
+  try {
+    logLatency({
+      type: "phase",
+      phase: "orphan_backstop_reaped",
+      filePath: "",
+      durationMs: Date.now() - startedAt,
+      metadata: { outcome, ...metadata }
+    });
+  } catch {}
+  try {
+    onComplete?.(outcome);
+  } catch {}
+  return outcome;
+}
+function backstopStampPath() {
+  return path.join(resolveBackstopStateDir(getGlobalDmLensDir()), "orphan-backstop.json");
+}
+async function readBackstopStamp() {
+  try {
+    const raw = await fs.promises.readFile(backstopStampPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    const value = parsed?.lastSweepAt;
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+  } catch {
+    return;
+  }
+}
+async function writeBackstopStamp(at) {
+  try {
+    await fs.promises.mkdir(resolveBackstopStateDir(getGlobalDmLensDir()), {
+      recursive: true
+    });
+    await writeFileAtomicAsync(backstopStampPath(), JSON.stringify({ lastSweepAt: at }));
+  } catch {}
+}
+export async function sweepOrphans() {
+  if (!isInstanceRegistryEnabled())
+    return;
+  const startedAt = Date.now();
+  try {
+    const registry = await readInstanceRegistry();
+    if (registry.length === 0)
+      return;
+    const candidatePids = registry.flatMap((instance) => instance.lspChildren.map((child) => child.pid));
+    const cmdlines = await queryCommandLines(candidatePids);
+    const matchProcess = buildIdentityMatcher(cmdlines);
+    const decision = decideOrphanReaping(registry, realIsPidAlive, matchProcess);
+    let killedCount = 0;
+    let unverifiedCount = 0;
+    const killedServerIds = [];
+    const killAndAccount = async (pid, serverId) => {
+      const outcome = await killPidTree(pid);
+      if (outcome === "gone") {
+        killedCount++;
+        killedServerIds.push(serverId);
+        return;
+      }
+      unverifiedCount++;
+      incrementDegradationCount({
+        kind: "orphan-reap-kill-unverified",
+        subject: `${serverId}#${pid}`,
+        reason: `kill attempted, process still ${outcome === "alive" ? "alive" : "unresolvable"}`
+      });
+    };
+    for (const child of decision.childrenToKill) {
+      await killAndAccount(child.pid, child.serverId);
+    }
+    for (const search of decision.markerSearches) {
+      try {
+        const pids = await findPidsByMarkerWindows(search.marker);
+        for (const pid of pids) {
+          await killAndAccount(pid, search.serverId);
+        }
+      } catch {}
+    }
+    if (decision.deadInstances.length > 0 || decision.staleInstances.length > 0) {
+      try {
+        const prunePids = new Set([
+          ...decision.deadInstances.map((i) => i.pid),
+          ...decision.staleInstances.map((i) => i.pid)
+        ]);
+        await pruneDeadInstances(prunePids);
+      } catch {}
+    }
+    try {
+      logLatency({
+        type: "phase",
+        phase: "orphan_lsp_reaped",
+        filePath: "",
+        durationMs: Date.now() - startedAt,
+        metadata: {
+          deadInstances: decision.deadInstances.length,
+          staleInstances: decision.staleInstances.length,
+          killed: killedCount,
+          killUnverified: unverifiedCount,
+          serverIds: killedServerIds,
+          markerSearches: decision.markerSearches.length
+        }
+      });
+    } catch {}
+  } catch {}
+}
+export async function pruneDeadInstances(deadPids) {
+  try {
+    await pruneDeadRegistryInstances(deadPids);
+  } catch {}
+}

package/extensions/dm-lens/dist/clients/instance-registry-lock.js

@@ -0,0 +1,131 @@
+import * as fs from "node:fs";
+import { randomInt } from "node:crypto";
+import * as path from "node:path";
+import { incrementDegradationCount } from "./degradation-ledger.js";
+const LOCK_STALE_MS = 5000;
+const LOCK_WAIT_MS = 500;
+const LOCK_MIN_BACKOFF_MS = 5;
+const LOCK_MAX_BACKOFF_MS = 25;
+function lockPath(target) {
+  return `${target}.lock`;
+}
+function ownerPid(lock) {
+  try {
+    const pid = Number(fs.readFileSync(lock, "utf8").trim().split(/\s+/)[0]);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+  } catch {
+    return;
+  }
+}
+function isPidAlive(pid) {
+  if (pid === undefined)
+    return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== "ESRCH";
+  }
+}
+function staleLock(lock) {
+  try {
+    const stat = fs.statSync(lock);
+    if (Date.now() - stat.mtimeMs > LOCK_STALE_MS)
+      return true;
+    const pid = ownerPid(lock);
+    return pid !== undefined && !isPidAlive(pid);
+  } catch {
+    return false;
+  }
+}
+function recordLockTimeout(target) {
+  incrementDegradationCount({
+    kind: "instance-registry-lock-timeout",
+    subject: path.resolve(target),
+    reason: `lock acquisition exhausted for ${path.basename(target)}`
+  });
+}
+function backoffMs() {
+  return randomInt(LOCK_MIN_BACKOFF_MS, LOCK_MAX_BACKOFF_MS + 1);
+}
+function backoff() {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, backoffMs());
+}
+function ownsLock(lock) {
+  return ownerPid(lock) === process.pid;
+}
+async function releaseLock(lock) {
+  if (ownsLock(lock))
+    await fs.promises.unlink(lock).catch(() => {});
+}
+function releaseLockSync(lock) {
+  if (!ownsLock(lock))
+    return;
+  try {
+    fs.unlinkSync(lock);
+  } catch {}
+}
+function takeOverStale(lock) {
+  if (!staleLock(lock))
+    return;
+  const displaced = `${lock}.stale-${process.pid}-${Date.now()}`;
+  try {
+    fs.renameSync(lock, displaced);
+    fs.unlinkSync(displaced);
+  } catch {}
+}
+function isLockContention(error) {
+  const code = error?.code;
+  return code === "EEXIST" || code === "EPERM" || code === "EBUSY";
+}
+export async function withInstanceRegistryLock(target, op) {
+  const lock = lockPath(target);
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  await fs.promises.mkdir(path.dirname(target), { recursive: true });
+  while (Date.now() <= deadline) {
+    try {
+      await fs.promises.writeFile(lock, `${process.pid} ${Date.now()}
+`, {
+        flag: "wx"
+      });
+    } catch (error) {
+      if (!isLockContention(error))
+        throw error;
+      takeOverStale(lock);
+      if (Date.now() <= deadline)
+        await new Promise((resolve) => setTimeout(resolve, backoffMs()));
+      continue;
+    }
+    try {
+      return await op();
+    } finally {
+      await releaseLock(lock);
+    }
+  }
+  recordLockTimeout(target);
+  return;
+}
+export function withInstanceRegistryLockSync(target, op) {
+  const lock = lockPath(target);
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  while (Date.now() <= deadline) {
+    try {
+      fs.writeFileSync(lock, `${process.pid} ${Date.now()}
+`, { flag: "wx" });
+      try {
+        return op();
+      } finally {
+        releaseLockSync(lock);
+      }
+    } catch (error) {
+      if (!isLockContention(error))
+        throw error;
+      takeOverStale(lock);
+      if (Date.now() <= deadline)
+        backoff();
+    }
+  }
+  recordLockTimeout(target);
+  return;
+}