pi-lens 4.1.2 → 4.1.4

package/dist/clients/installer/managed-tool-refresh.js

@@ -259,6 +259,8 @@ async function installedRefreshCandidates() {
         candidates.push({
             toolId: tool.toolId,
             strategy: tool.strategy,
+            checkArgs: tool.checkArgs,
+            verificationTimeoutMs: tool.verificationTimeoutMs ?? 10_000,
             ...(tool.packageName !== undefined && { packageName: tool.packageName }),
             ...(tool.binaryName !== undefined && { binaryName: tool.binaryName }),
         });
@@ -513,7 +515,7 @@ async function performNpmRefresh(candidate, packageName, now) {
     // drops npm entries that do not.
     const binaryName = candidate.binaryName;
     const binPath = resolveManagedNpmBinPath(binaryName);
-    const verified = await verifyToolBinary(binPath);
+    const verified = await verifyToolBinary(binPath, undefined, undefined, candidate.verificationTimeoutMs, candidate.checkArgs);
     if (!verified) {
         recordDegradationOnce({
             kind: "managed-tool-refresh",

package/dist/clients/instance-reaper.js

@@ -67,11 +67,12 @@ 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 { spawnCollectStdoutResult, unrefChildAndPipes, } from "./child-unref.js";
+import { unrefChildAndPipes, } from "./child-unref.js";
 import { incrementDegradationCount, recordDegradationOnce, } from "./degradation-ledger.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
-import { isInstanceRegistryEnabled, readInstanceRegistry, } from "./instance-registry.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";
 /**
  * KILL eligibility: pid-confirmed-dead ONLY. Heartbeat staleness must never
@@ -249,31 +250,14 @@ export async function sweepAtomicWriteStages(directories, options = {}) {
     const isPidAlive = options.isPidAlive ?? realIsPidAlive;
     return sweepOwnStagingFiles(directories, { maxEntries, isPidAlive });
 }
-function windowsExe(name) {
-    return path.join(process.env.SystemRoot ?? String.raw `C:\Windows`, "System32", name);
-}
-/** Resolve an absolute path to `ps` (S4036: never spawn via bare PATH lookup).
- *  Prefers `/bin/ps` (present on virtually every POSIX system), falls back to
- *  `/usr/bin/ps`, and defaults back to `/bin/ps` if neither probe succeeds
- *  (spawn will then fail closed rather than silently resolving via PATH). */
-function posixPsPath() {
-    if (fs.existsSync("/bin/ps"))
-        return "/bin/ps";
-    if (fs.existsSync("/usr/bin/ps"))
-        return "/usr/bin/ps";
-    return "/bin/ps";
-}
-/** Escape a value for embedding in a WQL LIKE clause: WQL uses `'` as the
- *  string delimiter (doubled to escape) and `%`/`_` as wildcards — the marker
- *  is an opaque path string, so escape all three before interpolating. */
-function escapeWqlLikeValue(value) {
-    return value.replaceAll("'", "''").replaceAll(/[%_]/g, (ch) => `[${ch}]`);
-}
-/** Escape a value for a WQL EQUALITY comparison: only the string delimiter
- *  needs escaping — `%`/`_` are literal outside `LIKE`. */
-function escapeWqlStringValue(value) {
-    return value.replaceAll("'", "''");
-}
+/**
+ * Interpreter resolution, WQL escaping and the platform listing itself all
+ * live in the ONE process-table seam (#2443): `scripts/lib/process-scan.mjs`,
+ * reached from clients/ through `clients/process-snapshot.ts`. This file used
+ * to carry its own copy of each, which is how the three queries below drifted
+ * apart from the two in `clients/resource-sampler.ts` and the two in
+ * `scripts/`. `windowsExe` is re-exported by the seam and imported above.
+ */
 /** Search running processes whose command line contains `marker` (Windows,
  *  via CIM/WQL). Returns matching pids. Best-effort: any failure ⇒ [], but a
  *  failure is RECORDED (#1857 class sweep) — "the search found no orphan" and
@@ -282,14 +266,26 @@ function escapeWqlStringValue(value) {
 async function findPidsByMarkerWindows(marker) {
     if (!isWindows || !marker)
         return [];
-    const escaped = escapeWqlLikeValue(marker);
-    // $PID exclusion: the query's own powershell.exe command line embeds the
-    // marker string, so it would match itself.
-    const psScript = `Get-CimInstance Win32_Process -Filter "CommandLine LIKE '%${escaped}%'" ` +
-        `| Where-Object { $_.ProcessId -ne $PID } ` +
-        `| Select-Object -ExpandProperty ProcessId`;
-    const powershell = windowsExe("WindowsPowerShell\\v1.0\\powershell.exe");
-    const result = await spawnCollectStdoutResult(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] }, { timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS });
+    const result = await queryProcessTable({
+        fields: ["pid"],
+        filter: { column: "CommandLine", op: "like", values: [marker] },
+        // The query's own powershell.exe command line embeds the marker, so
+        // without this exclusion the search matches itself.
+        excludeSelfPid: true,
+    }, {
+        timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS,
+        // #2527 review F2: omitting `onTimeout` falls through to
+        // child-unref.ts's default — one bare, unverified `child.kill()`, no
+        // tree kill, no identity-carrying record — inside the orphan backstop
+        // path, the exact abandonment `terminateScannerChild`'s own doc
+        // comment says it exists to prevent. This query shares the backstop's
+        // scanner identity and budget (same producer as
+        // `enumerateManagedProcesses`), so it gets the same kind.
+        onTimeout: (child) => terminateScannerChild(child, {
+            kind: "orphan-backstop-scanner-escalated",
+            timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS,
+        }),
+    });
     if (result.status !== "ok") {
         recordDegradationOnce({
             kind: "orphan-backstop-scan-failed",
@@ -297,10 +293,7 @@ async function findPidsByMarkerWindows(marker) {
             reason: `marker command-line search ${result.status}`,
         });
     }
-    return result.stdout
-        .split(/\r?\n/)
-        .map((line) => Number(line.trim()))
-        .filter((n) => Number.isFinite(n) && n > 0);
+    return result.rows.map((row) => row.pid);
 }
 /** Fetch command lines for a set of pids in one query (Windows: CIM; POSIX:
  *  `ps`). Returns a pid → command-line map; pids that can't be resolved are
@@ -317,59 +310,35 @@ async function queryCommandLines(pids) {
     const map = new Map();
     if (valid.length === 0)
         return map;
-    const noteFailure = (status) => {
-        if (status === "ok")
-            return;
+    const result = await queryProcessTable({
+        fields: ["pid", "command"],
+        filter: { column: "ProcessId", op: "eq", values: valid },
+    }, {
+        timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS,
+        // #2527 review F2: same rationale as findPidsByMarkerWindows above —
+        // route through the reaper's own tree-kill-and-verify machinery with
+        // the backstop's kind rather than falling through to the unverified
+        // default kill with no ledger record.
+        onTimeout: (child) => terminateScannerChild(child, {
+            kind: "orphan-backstop-scanner-escalated",
+            timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS,
+        }),
+    });
+    // POSIX `ps -p` exits nonzero when NONE of the requested pids exist, which
+    // is a legitimate clean result for this caller, so that one status is not
+    // recorded on that platform. The shared collector calls it an exit failure;
+    // this caller's command contract makes it the expected empty table. Windows
+    // CIM has no such convention, so an exit failure there is a real failure.
+    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 ${status}; reap suppressed this sweep`,
+            reason: `command-line identity query ${result.status}; reap suppressed this sweep`,
         });
-    };
-    if (isWindows) {
-        const filter = valid.map((p) => `ProcessId=${p}`).join(" OR ");
-        const psScript = `Get-CimInstance Win32_Process -Filter "${filter}" ` +
-            `| ForEach-Object { "$($_.ProcessId)\t$($_.CommandLine)" }`;
-        const powershell = windowsExe("WindowsPowerShell\\v1.0\\powershell.exe");
-        const result = await spawnCollectStdoutResult(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] }, { timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS });
-        noteFailure(result.status);
-        for (const line of result.stdout.split(/\r?\n/)) {
-            const tab = line.indexOf("\t");
-            if (tab <= 0)
-                continue;
-            const pid = Number(line.slice(0, tab).trim());
-            if (Number.isFinite(pid) && pid > 0)
-                map.set(pid, line.slice(tab + 1));
-        }
-        return map;
-    }
-    const result = await spawnCollectStdoutResult(posixPsPath(), ["-p", valid.join(","), "-o", "pid=,args="], { shell: false, stdio: ["ignore", "pipe", "ignore"] }, { timeoutMs: BACKSTOP_SCAN_TIMEOUT_MS });
-    // `ps -p` exits nonzero when NONE of the pids exist, which is a legitimate
-    // clean result here, so only spawn/timeout failures are recorded. The
-    // shared collector calls that an exit failure, but this caller's command
-    // contract makes that status the expected empty-table result.
-    if (result.status !== "exit-error")
-        noteFailure(result.status);
-    for (const line of result.stdout.split(/\r?\n/)) {
-        // Linear parse (S8786/S6594: avoid regex backtracking on
-        // attacker-lengthenable ps output) — trim leading whitespace,
-        // then split on the first whitespace run: "  1234 args here".
-        const trimmed = line.trimStart();
-        if (!trimmed)
-            continue;
-        let i = 0;
-        while (i < trimmed.length && trimmed[i] >= "0" && trimmed[i] <= "9")
-            i++;
-        if (i === 0)
-            continue;
-        const pidStr = trimmed.slice(0, i);
-        let j = i;
-        while (j < trimmed.length && (trimmed[j] === " " || trimmed[j] === "\t"))
-            j++;
-        const pid = Number(pidStr);
-        if (Number.isFinite(pid) && pid > 0)
-            map.set(pid, trimmed.slice(j));
     }
+    for (const row of result.rows)
+        map.set(row.pid, row.command);
     return map;
 }
 /**
@@ -605,104 +574,42 @@ export function partitionBackstopCandidates(processes, registry, isPidAlive, opt
 }
 /** Enumerate live OS processes whose command line contains one of
  *  `MANAGED_BINARY_NAMES` (#658), independent of the instance registry.
- *  Windows: one batched CIM/WQL query (mirrors `findPidsByMarkerWindows`'s
- *  query pattern). POSIX: `ps -eo pid=,ppid=,args=`, filtered in JS. Returns
- *  `{pid, parentPid, command}` rows. Best-effort: any failure ⇒ []. */
+ *  One projected process-table query through the shared seam, narrowed to
+ *  managed binaries in JS; returns `{pid, parentPid, command, ageMs}` rows.
+ *  Best-effort: any failure ⇒ [], with the scan status carried alongside so
+ *  an empty table is never mistaken for a scan that did not run. */
 async function enumerateManagedProcesses(options = {}) {
-    const timeoutMs = options.timeoutMs ?? BACKSTOP_SCAN_TIMEOUT_MS;
-    const collect = {
-        timeoutMs,
-        onTimeout: (child) => terminateScannerChild(child, options),
-    };
-    if (isWindows) {
-        // #1857: `Name = '…'` equality replaces eight leading-wildcard
-        // `CommandLine LIKE '%…%'` clauses, and the query now also projects
-        // `CreationDate` so the spawn-grace guard has an age to work with. The
-        // image-name set is DERIVED from MANAGED_BINARIES (MANAGED_IMAGE_NAMES),
-        // so adding a managed binary cannot leave a stale parallel list behind.
-        const clauses = MANAGED_IMAGE_NAMES.map((name) => `Name = '${escapeWqlStringValue(name)}'`).join(" OR ");
-        // The age column is computed IN PowerShell as a millisecond delta, not
-        // exported as `CreationDate.Ticks`. `Ticks` is the LOCAL-time
-        // representation, so subtracting the Unix epoch in JS produced an age
-        // wrong by the machine's UTC offset — measured on a UTC+3 host as
-        // -8358s for a process started 40 minutes earlier. A delta computed on
-        // one side of the boundary has no timezone to get wrong. The explicit
-        // `[datetime]` test matters: `(Get-Date) - $null` yields a two-thousand
-        // year TimeSpan, which would read as "ancient" and defeat the grace
-        // guard exactly where the data is missing.
-        const psScript = `Get-CimInstance -Query "SELECT ProcessId,ParentProcessId,CreationDate,CommandLine FROM Win32_Process WHERE ${clauses}" ` +
-            `| ForEach-Object { $age = if ($_.CreationDate -is [datetime]) { [int64]((Get-Date) - $_.CreationDate).TotalMilliseconds } else { '' }; ` +
-            `"$($_.ProcessId)\t$($_.ParentProcessId)\t$age\t$($_.CommandLine)" }`;
-        const powershell = windowsExe("WindowsPowerShell\\v1.0\\powershell.exe");
-        const result = await spawnCollectStdoutResult(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] }, collect);
-        const processes = [];
-        for (const line of result.stdout.split(/\r?\n/)) {
-            const firstTab = line.indexOf("\t");
-            if (firstTab <= 0)
-                continue;
-            const secondTab = line.indexOf("\t", firstTab + 1);
-            if (secondTab <= 0)
-                continue;
-            const thirdTab = line.indexOf("\t", secondTab + 1);
-            if (thirdTab <= 0)
-                continue;
-            const pid = Number(line.slice(0, firstTab).trim());
-            const parentPid = Number(line.slice(firstTab + 1, secondTab).trim());
-            const ageMs = parseNonNegativeMs(line.slice(secondTab + 1, thirdTab));
-            const command = line.slice(thirdTab + 1);
-            if (!Number.isFinite(pid) || pid <= 0)
-                continue;
-            processes.push({ pid, parentPid, command, ageMs });
-        }
-        return narrowToManagedBinaries(processes, result);
-    }
-    // POSIX: enumerate everything, filter in JS by managed-name substring —
-    // there is no single-query WQL-style server-side filter available.
-    // `etime` is the POSIX-standard elapsed-time column (Linux and macOS both
-    // support it; `etimes` is Linux-only), and supplies the spawn-grace age.
-    const result = await spawnCollectStdoutResult(posixPsPath(), [...POSIX_PS_ARGS], { shell: false, stdio: ["ignore", "pipe", "ignore"] }, collect);
-    const processes = [];
-    for (const line of result.stdout.split(/\r?\n/)) {
-        // Linear parse (S8786/S6594): "  pid ppid etime args here".
-        const trimmed = line.trimStart();
-        if (!trimmed)
-            continue;
-        let i = 0;
-        while (i < trimmed.length && trimmed[i] >= "0" && trimmed[i] <= "9")
-            i++;
-        if (i === 0)
-            continue;
-        const pid = Number(trimmed.slice(0, i));
-        let rest = trimmed.slice(i);
-        let k = 0;
-        while (k < rest.length && (rest[k] === " " || rest[k] === "\t"))
-            k++;
-        rest = rest.slice(k);
-        let j = 0;
-        while (j < rest.length && rest[j] >= "0" && rest[j] <= "9")
-            j++;
-        if (j === 0)
-            continue;
-        const parentPid = Number(rest.slice(0, j));
-        rest = rest.slice(j);
-        let m = 0;
-        while (m < rest.length && (rest[m] === " " || rest[m] === "\t"))
-            m++;
-        rest = rest.slice(m);
-        // etime token: a non-whitespace run of digits, ':' and '-'.
-        let e = 0;
-        while (e < rest.length && rest[e] !== " " && rest[e] !== "\t")
-            e++;
-        const ageMs = ageMsFromPosixEtime(rest.slice(0, e));
-        let n = e;
-        while (n < rest.length && (rest[n] === " " || rest[n] === "\t"))
-            n++;
-        const args = rest.slice(n);
-        if (!Number.isFinite(pid) || pid <= 0)
-            continue;
-        processes.push({ pid, parentPid, command: args, ageMs });
-    }
-    return narrowToManagedBinaries(processes, result);
+    // #1857: `Name = '…'` equality replaces eight leading-wildcard
+    // `CommandLine LIKE '%…%'` clauses, and the projection carries an age so
+    // the spawn-grace guard has something to reason from. The image-name set is
+    // DERIVED from MANAGED_BINARIES (MANAGED_IMAGE_NAMES), so adding a managed
+    // binary cannot leave a stale parallel list behind.
+    //
+    // POSIX `ps` cannot express that filter — the seam reports it as
+    // `serverSideFiltered: false` and hands back the whole table — which is why
+    // `narrowToManagedBinaries` runs on BOTH platforms rather than only on the
+    // POSIX branch. Windows over-collects for its own reason anyway
+    // (`node.exe` is a superset image name covering every node process on the
+    // machine).
+    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);
 }
 /**
  * The ONE place a raw OS-process snapshot is narrowed to managed binaries.
@@ -730,6 +637,18 @@ function narrowToManagedBinaries(processes, result) {
  * exists to fix, so the scanner now gets exactly what an orphan gets:
  * `taskkill /F /T` or a POSIX group kill, then a verified liveness poll. The
  * escalation is recorded with the scanner's identity, never swallowed.
+ *
+ * The kill attempt itself is real regardless of what happens next: this
+ * handler is invoked the instant the caller's timer elapses, which can race
+ * a query child that is genuinely about to close successfully (its own
+ * "close" event may still win the overall settle — see
+ * `child-unref.ts#spawnCollectStdoutResult`, which resolves on whichever of
+ * "close" or the timeout handler's own settle lands first). This function has
+ * no way to observe that outcome — it runs strictly BEFORE the caller's
+ * promise resolves — so it always records the escalation it actually
+ * attempted; callers whose escalation kind can fire on that race classify it
+ * as informational rather than a warning (see
+ * `degradation-ledger.ts`'s `resource-sampler-scanner-escalated` doc comment).
  */
 export async function terminateScannerChild(child, options) {
     const pid = child.pid;
@@ -740,9 +659,9 @@ export async function terminateScannerChild(child, options) {
         })
         : "invalid";
     incrementDegradationCount({
-        kind: "orphan-backstop-scanner-escalated",
+        kind: options.kind,
         subject: `${isWindows ? "win32-cim" : "posix-ps"}#${pid ?? "no-pid"}`,
-        reason: `scan exceeded its timeout; tree kill reported ${outcome}`,
+        reason: `scan exceeded its ${options.timeoutMs}ms timeout; tree kill reported ${outcome}`,
     });
     return outcome;
 }
@@ -755,51 +674,6 @@ function matchesManagedBinary(command) {
     const lower = command.toLowerCase();
     return MANAGED_BINARY_NAMES.some((name) => lower.includes(name.toLowerCase()));
 }
-/**
- * Parse the Windows age column: a non-negative integer millisecond count, or
- * anything else. A negative or malformed value is `undefined`, not zero and
- * not a clamp — a nonsensical age means the age is UNKNOWN, and the grace
- * guard must spare an unknown-age process rather than reason from a number it
- * cannot trust. That rule is what surfaced the local-time tick bug during the
- * host probe instead of silently sparing everything.
- */
-function parseNonNegativeMs(raw) {
-    const token = raw.trim();
-    if (!/^\d+$/.test(token))
-        return undefined;
-    const value = Number(token);
-    return Number.isFinite(value) ? value : undefined;
-}
-/**
- * POSIX enumeration columns. Exported so a real-`ps` test can assert this
- * exact argument vector is accepted by the host's `ps` — a rejected column
- * would make the whole backstop silently return zero rows, and this is the
- * one part of the fix that cannot be checked from a Windows dev machine.
- */
-export const POSIX_PS_ARGS = [
-    "-eo",
-    "pid=,ppid=,etime=,args=",
-];
-/** Parse `ps -o etime` output: `[[dd-]hh:]mm:ss`. Returns undefined for any
- *  shape the column did not produce (a `ps` without the column emits the
- *  command line where the token was expected). */
-export function ageMsFromPosixEtime(raw) {
-    const token = raw.trim();
-    if (!/^(?:\d+-)?(?:\d+:)?\d+:\d+$/.test(token))
-        return undefined;
-    let days = 0;
-    let rest = token;
-    const dash = rest.indexOf("-");
-    if (dash >= 0) {
-        days = Number(rest.slice(0, dash));
-        rest = rest.slice(dash + 1);
-    }
-    const parts = rest.split(":").map(Number);
-    if (parts.some((part) => !Number.isFinite(part)))
-        return undefined;
-    const [hours, minutes, seconds] = parts.length === 3 ? parts : [0, parts[0], parts[1]];
-    return ((days * 24 + hours) * 60 * 60 + minutes * 60 + seconds) * 1000;
-}
 /**
  * Fire-and-forget REGISTRY-INDEPENDENT backstop sweep (#658): finds
  * pi-lens-managed LSP/scanner processes the registry-driven `sweepOrphans`
@@ -1226,8 +1100,8 @@ export async function sweepOrphans() {
 /** Drop dead-parent AND stale-heartbeat (#525, record-cleanup-only)
  *  instances from the registry. Re-reads immediately before
  *  writing (rather than reusing the earlier `readInstanceRegistry()` snapshot)
- *  to narrow — not eliminate — the last-writer-wins race already accepted for
- *  slice 1's read-modify-write model.
+ *  under the instance-registry lock so the reaper cannot lose a registration
+ *  or heartbeat while pruning.
  *
  *  Exported for the #1217 concurrency regression test; `sweepOrphans` is the
  *  only production caller.
@@ -1244,17 +1118,8 @@ export async function sweepOrphans() {
  *  rename, which the hand-rolled copy did not, and puts this writer back on
  *  the same scheme as the other writer of this same file. */
 export async function pruneDeadInstances(deadPids) {
-    const target = path.join(getGlobalPiLensDir(), "instances.json");
     try {
-        const raw = await fs.promises.readFile(target, "utf-8");
-        const parsed = JSON.parse(raw);
-        if (!parsed || !Array.isArray(parsed.instances))
-            return;
-        const remaining = parsed.instances.filter((entry) => !deadPids.has(entry.pid));
-        if (remaining.length === parsed.instances.length)
-            return;
-        await fs.promises.mkdir(getGlobalPiLensDir(), { recursive: true });
-        await writeFileAtomicAsync(target, JSON.stringify({ instances: remaining }));
+        await pruneDeadRegistryInstances(deadPids);
     }
     catch {
         // best-effort

package/dist/clients/instance-registry-lock.js

@@ -0,0 +1,145 @@
+/** Cross-process mutual exclusion for the machine-global instance registry. */
+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 = 5_000;
+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 undefined;
+    }
+}
+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) {
+    // Residual TOCTOU: ownership and unlink are separate syscalls, so a stale
+    // takeover can still replace the lock between them.
+    if (ownsLock(lock))
+        await fs.promises.unlink(lock).catch(() => { });
+}
+function releaseLockSync(lock) {
+    if (!ownsLock(lock))
+        return;
+    try {
+        fs.unlinkSync(lock);
+    }
+    catch {
+        // A stale takeover may have displaced the lock after ownership was read.
+    }
+}
+function takeOverStale(lock) {
+    if (!staleLock(lock))
+        return;
+    const displaced = `${lock}.stale-${process.pid}-${Date.now()}`;
+    try {
+        fs.renameSync(lock, displaced);
+        fs.unlinkSync(displaced);
+    }
+    catch {
+        // Another owner may have released or taken over it first.
+    }
+}
+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()}\n`, {
+                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 undefined;
+}
+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()}\n`, { 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 undefined;
+}