@ngockhoale/ukit 2.3.9 → 2.3.11

package/CHANGELOG.md

@@ -2,6 +2,93 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.11 - 2026-09-11
+
+Freeze-sweep wave 11 (post-2.3.10): the two deferred liveness candidates fixed via TDD, plus
+a self-refresh downgrade trap repaired during verification. All template/live mirrors are
+byte-synced.
+
+**P1 — SessionStart hook could hang the session forever.** `handoff-resume.sh`'s "advisory,
+always exit 0" rested on `|| true`, which never fires when the embedded node process wedges
+(hung runtime import, unresolved lock wait, stalled file read) — session start stalls mid-run
+with no visible reason. A 3s wall-clock watchdog (`UKIT_HOOK_DEADLINE_MS`, env-tunable) now
+exits 0 unconditionally, and the RUN.md read is async so sync I/O cannot block the timer.
+
+**P1 — router state writes could tear; route-audit merge lost entries.** All five
+`skill-router-state.json` / `route-audit.json` writes were direct `writeFileSync`: a torn or
+empty state parses as `{}` downstream and completion-gate.sh then releases a premature Stop
+with no message. Writes now go through tmp+rename (`writeJsonFileAtomic`), and the audit
+append runs under the standard PID + owner-token lock (5s bounded, fail-open). 16 concurrent
+router runs previously kept only 13/16 audit entries; now 16/16.
+
+**Incident — post-release self-refresh downgraded live hooks.** Running `ukit install` from a
+global CLI older than the published release rewrote six live hook mirrors with pre-release
+content, resurrecting just-fixed lock-theft bugs in the development workspace. Recovered by
+upgrading the global CLI and re-installing; the deferred guard candidate is a stale-CLI
+warning in `ukit install`.
+
+## 2.3.10 - 2026-09-11
+
+Freeze-sweep waves 7-10 (post-2.3.9): twelve verified mid-run-freeze defects fixed, each locked
+by a regression reproducing the failure first. All affected template/live mirrors are byte-synced.
+
+**P1 — continuation budget reset on every route re-key.** The router re-keys `requestKey` per
+tool call (the target file is part of the key), but the Stop-gate continuation budget was keyed
+on `requestKey` — the count reset to 0 on every re-key, the cap was unreachable, and omp looped
+forever (no `stop_hook_active` valve). Budget identity is now the logical prompt hash
+(`promptKey`) everywhere, and omp gained `stop_hook_active` parity via `noteStopProgress`.
+
+**P1 — parallel execution receipts crashed and raced.** Same-process concurrent receipt writers
+shared one temp path and crashed with ENOENT mid-hook; unlocked read-modify-write also dropped
+receipts, and a missing/foreign route state could rebuild a session ledger from blank, erasing
+banked evidence. Temp paths are unique, the whole receipt write runs under `withFileLock`, and
+a missing route no longer blanks the ledger.
+
+**P1 — ledger lock waits exceeded the hook child budget.** `withFileLock` waited up to 5s but
+the hook chain kills children at 4s, so a contended lock got the recording hook killed and omp's
+fail-closed Edit|Write chain then blocked the edit. Ledger lock waits now cap at 2.5s and fail
+open — a lost receipt beats a killed hook.
+
+**P1 — vibecode had no exit when verification kept failing identically.** Two adjacent identical
+failed verifications (no edit between) now mint a visible `verification-loop` blocker; vibecode
+additionally escapes after the same command fails 4× across edits.
+
+**P1 — clean map-impact Stop loop.** A completed analysis-only `map-impact` route still demanded
+write + verification evidence. A narrow visible release valve permits a completed impact read
+with no mutation attempt and no failed verification; incomplete analysis and partial edits stay
+gated.
+
+**P1 — omp hook child timeouts falsely blocked edits.** A 4s-killed `protect-files` gate was
+treated as its fail-closed verdict, freezing all edits on a slow machine. Timeouts now fail open
+as infrastructure failures with a visible warning; `block-dangerous.sh` stays fail-closed. An
+unknown mutation-shaped omp tool now normalizes to `Edit` and runs the normal safety chain
+instead of emitting an impossible "add host mapping" block.
+
+**P1 — hard-cap grace slots crossed session boundaries.** Global grace slots let one session
+spend or reset another session's landing allowance, stranding it mid-edit. Slots and advisory
+state are now session-keyed.
+
+**P2 — transcript fallback rescanned up to 4MB per mutation.** A persisted, session-bound
+2-second boundary-probe cache coalesces mutation bursts to one scan; `skill-router.sh` also
+skips its redundant prompt-only Node spawn on tool payloads.
+
+**P1 — lock stale-reclaim could steal a live owner.** The shared runtime lock used mtime-only
+reclaim: a slow-but-alive holder was deleted after 10s, then deleted its successor's lock in
+`finally` — lost receipts re-triggered completion debt. All lock implementations (runtime
+mirror, verification guard, auto-allow, auto-prune, compact-pressure reset) now stamp
+PID + random owner tokens, reclaim only provably-dead owners, and release only their own token.
+
+**P3 — stale verification-guard enforcement env var froze runs.** An inherited
+`UKIT_VERIFICATION_GUARD_ENFORCE=1` turned an advisory test-order recommendation into an
+exit-2 block. The guard is now exclusively advisory; real safety gates keep enforcement.
+
+Also in wave 7: piped/redirected verification (`yarn test 2>&1 | tail -6`) counts as targeted,
+and delivery-only requests ("push this to git") route `informational` with no fabricated
+mutation debt in all three routing copies.
+
+Full suite: 81 files, 1,439 tests green (plus wave 9-10 focused regressions). No npm tag
+policy change; artifact unpacked ceiling raised once to 5,785,000 with dated rationale.
+
 ## 2.3.9 - 2026-09-10
 
 Freeze-sweep wave 5: fixes for completion-gate loops, worker-agent dead ends, and malformed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.9",
+  "version": "2.3.11",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/core/fileOps.js

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
@@ -142,17 +143,46 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM: the process exists but belongs to another user — still alive.
+    return error?.code === 'EPERM';
+  }
+}
+
+async function readLockOwner(lockPath) {
+  try {
+    const raw = JSON.parse(await fs.readFile(path.join(lockPath, 'owner'), 'utf8'));
+    const pid = Number(raw?.pid);
+    return Number.isInteger(pid) && pid > 0
+      ? { pid, token: typeof raw?.token === 'string' ? raw.token : null }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+// Same-pid holders are parallel async flows whose liveness a pid probe cannot prove.
+const inProcessLockHolders = new Map();
+
 /**
  * Serialize read-modify-write mutations of a shared state file — across processes
  * (hook invocations run as separate node processes) and across concurrent async
  * flows in one process (parallel subagents). The lock is a directory created next
  * to the target file: `mkdir` is atomic, so exactly one caller can create it.
- * A crashed holder is reclaimed once the directory's mtime exceeds staleMs.
+ * Ownership is recorded in an `owner` file inside the lock dir: stale reclaim first
+ * proves the recorded holder is gone (dead pid, or no in-process holder for our own
+ * pid — no owner file keeps legacy mtime-only recovery). Release only removes a dir
+ * this acquisition still owns, so a reclaimed-then-reacquired lock is never deleted
+ * out from under its successor.
  * Liveness wins over strictness: if the lock cannot be acquired within maxWaitMs
  * the callback runs anyway (the pre-lock behaviour) — these state files are
  * advisory caches, and losing an update beats freezing a hook mid-flight.
- * Holders must keep their critical section far below staleMs; nothing refreshes
- * the lock mtime, so a section that somehow runs longer can have its lock stolen.
+ * Protocol-compatible with the runtime token-utils.mjs lock (same `<file>.lock`
+ * path and owner-file format), so CLI and hook processes serialize against each other.
  * @param {string} filePath - state file the mutation targets (lock lives beside it)
  * @param {() => Promise<*>} fn - critical section; its result is returned
  * @returns {Promise<*>} whatever fn resolves with
@@ -160,24 +190,44 @@ function sleep(ms) {
 export async function withFileLock(filePath, fn, { staleMs = LOCK_STALE_MS, maxWaitMs = LOCK_MAX_WAIT_MS } = {}) {
   const lockPath = `${filePath}.lock`;
   const startedAt = Date.now();
+  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
   let locked = false;
+  let ownerStamped = false;
 
   while (!locked) {
     try {
       await ensureDir(path.dirname(lockPath));
       await fs.mkdir(lockPath); // atomic acquire — EEXIST means another holder exists
       locked = true;
+      inProcessLockHolders.set(lockPath, ownerToken);
+      try {
+        await fs.writeFile(
+          path.join(lockPath, 'owner'),
+          `${JSON.stringify({ pid: process.pid, token: ownerToken, ts: Date.now() })}\n`,
+          'utf8',
+        );
+        ownerStamped = true;
+      } catch {
+        ownerStamped = false; // unverifiable release skips removal; stale reclaim cleans up
+      }
       break;
     } catch (error) {
       if (error?.code !== 'EEXIST') throw error;
     }
 
-    // Someone holds the lock. Reclaim it when it looks abandoned; otherwise back off.
+    // Someone holds the lock. Reclaim it only when the holder is provably gone.
     try {
       const stat = await fs.stat(lockPath);
       if (Date.now() - stat.mtimeMs > staleMs) {
-        await fs.rm(lockPath, { recursive: true, force: true });
-        continue; // the slot is free now — retry immediately
+        const owner = await readLockOwner(lockPath);
+        const liveInProcess = inProcessLockHolders.has(lockPath);
+        const reclaimable = !owner || owner.pid === process.pid
+          ? !liveInProcess
+          : !isPidAlive(owner.pid);
+        if (reclaimable) {
+          await fs.rm(lockPath, { recursive: true, force: true });
+          continue; // the slot is free now — retry immediately
+        }
       }
     } catch {
       continue; // lock vanished between mkdir and stat — retry immediately
@@ -192,7 +242,11 @@ export async function withFileLock(filePath, fn, { staleMs = LOCK_STALE_MS, maxW
   } finally {
     if (locked) {
       try {
-        await fs.rm(lockPath, { recursive: true, force: true });
+        const current = ownerStamped ? await readLockOwner(lockPath) : null;
+        if (current && current.token === ownerToken) {
+          await fs.rm(lockPath, { recursive: true, force: true });
+        }
+        if (inProcessLockHolders.get(lockPath) === ownerToken) inProcessLockHolders.delete(lockPath);
       } catch {
         // best-effort release; a stale lock is reclaimed by the next waiter
       }

package/src/index/taskRouting.js

@@ -78,6 +78,7 @@ export async function deriveTaskRoute({
     intentMode,
     executionScores,
     executionCandidates,
+    signalText: buildRouteSignalText(normalizedPrompt, normalizedCommand),
   });
   const preservedPrompt = normalizedPrompt || String(lastExplicitUserPromptText || '').trim();
   const degradedWarnings = [];
@@ -412,8 +413,10 @@ function deriveExecutionMode({
   intentMode = null,
   executionScores = {},
   executionCandidates = null,
+  signalText = '',
 } = {}) {
   const raw = `${promptText ?? ''}\n${commandText ?? ''}`.toLowerCase();
+  const signalRaw = `${raw}\n${String(signalText || '').toLowerCase()}`;
   const scores = executionScores;
   const candidates = executionCandidates ?? buildExecutionModeCandidates({
     promptText,
@@ -423,14 +426,44 @@ function deriveExecutionMode({
     executionScores,
   });
   const explicitReviewLead = /\b(review this|audit this|review\b.*\brelease readiness|verify\b.*\brelease readiness)\b/.test(raw);
+  const releaseVerificationContinuation = /\b(?:pending\s+diff[- ]review|self-install|verify\s+(?:consistency|release)|release\s+(?:verification|readiness))\b/.test(raw)
+    && /\b(?:release|tag|publish|push|report)\b/.test(raw);
   const strongImpactLead = scores.sharedRisk
     && (scores.impactSignal || /\b(check all affected|map all affected|across all affected)\b/.test(raw));
   const boundedLocalBuildCandidate = scores.buildSignal && scores.boundedEditSignal && scores.explicitTarget && !scores.sharedRisk;
+  // A bare delivery command ("push this to git", "đẩy bộ này lên git") performs no
+  // repository mutation the ledger could ever receipt. With no edit/review/debug/
+  // build signal present, routing it to an investigation lane fabricates write debt
+  // and the completion gate then demands an edit that cannot exist. Delivery-only
+  // requests carry no completion contract instead.
+  const deliveryWordSignal = /\bgit\s+push\b/.test(signalRaw)
+    || /\bpush\b[^\n]{0,60}\b(?:git|github|gitlab|remote|origin|repo)\b/.test(signalRaw)
+    || /\b(?:git|github|gitlab|remote|origin|repo)\b[^\n]{0,60}\bpush\b/.test(signalRaw)
+    || /\bday\b(?:\s+\S+){0,3}?\s+len\b/.test(signalRaw);
+  const deliveryOnlySignal = deliveryWordSignal
+    && scores.editCertainty === 0
+    && !scores.implementSignal
+    && !scores.reviewSignal
+    && !scores.debugSignal
+    && !scores.failureSignal
+    && !scores.impactSignal
+    && !scores.buildSignal
+    && !scores.directTransformSignal
+    && !scores.smallFixSignal
+    && !scores.sharedRisk
+    && !targetFile;
 
-  if ((intentMode === 'review-specific' || explicitReviewLead) && !scores.implementSignal) {
+  if (
+    releaseVerificationContinuation
+    || ((intentMode === 'review-specific' || explicitReviewLead) && !scores.implementSignal)
+  ) {
     return 'review-release';
   }
 
+  if (deliveryOnlySignal) {
+    return 'informational';
+  }
+
   if (strongImpactLead || (scores.blastRadius >= 3 && (scores.ambiguity >= 2 || scores.investigationNeed >= 2))) {
     return 'map-impact';
   }
@@ -530,7 +563,7 @@ function buildExecutionModeCandidates({
     ),
     'map-impact': (
       (scores.sharedRisk ? 7 : 0)
-      + (scores.impactSignal ? 5 : 0)
+      + (scores.impactSignal ? 5 : -5)
       + (scores.ambiguity * 2)
       + scores.investigationNeed
     ),

package/templates/.claude/hooks/auto-allow-bash.sh

@@ -78,6 +78,7 @@ MAX_RULES="${CLAUDE_AUTO_ALLOW_MAX_RULES:-150}"
 # Liveness over strictness: if the lock cannot be acquired within maxWaitMs the mutation
 # runs anyway (pre-lock behaviour) — this hook must never hang a PreToolUse chain.
 node -e '
+const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
 
@@ -115,24 +116,57 @@ function appendAudit(event, payload) {
   fs.appendFileSync(auditPath, JSON.stringify({ ts: nowUtc, event, ...payload }) + "\n");
 }
 
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+function readLockOwner(lockPath) {
+  const owner = readJson(path.join(lockPath, "owner"), null);
+  return owner && Number.isInteger(owner.pid) && typeof owner.token === "string"
+    ? owner
+    : null;
+}
+
 async function withLock(lockPath, fn) {
   const staleMs = 10000;
   const maxWaitMs = 5000;
   const startedAt = Date.now();
+  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
   let held = false;
   while (!held) {
     try {
       fs.mkdirSync(lockPath);
+      try {
+        fs.writeFileSync(path.join(lockPath, "owner"), JSON.stringify({
+          pid: process.pid,
+          token: ownerToken,
+          ts: Date.now(),
+        }));
+      } catch (error) {
+        try {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+        throw error;
+      }
       held = true;
     } catch (error) {
       if (!error || error.code !== "EEXIST") return fn();
       try {
         const stat = fs.statSync(lockPath);
         if (Date.now() - stat.mtimeMs > staleMs) {
-          try {
-            fs.rmSync(lockPath, { recursive: true, force: true });
-            continue;
-          } catch {}
+          const owner = readLockOwner(lockPath);
+          if (!owner || !isPidAlive(owner.pid)) {
+            try {
+              fs.rmSync(lockPath, { recursive: true, force: true });
+              continue;
+            } catch {}
+          }
         }
       } catch {}
       if (Date.now() - startedAt > maxWaitMs) break;
@@ -143,9 +177,12 @@ async function withLock(lockPath, fn) {
     return await fn();
   } finally {
     if (held) {
-      try {
-        fs.rmdirSync(lockPath);
-      } catch {}
+      const owner = readLockOwner(lockPath);
+      if (owner?.token === ownerToken) {
+        try {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+      }
     }
   }
 }

package/templates/.claude/hooks/auto-prune-bash.sh

@@ -14,6 +14,7 @@ fi
 NOW_UTC=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
 node -e '
+const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
 
@@ -55,25 +56,58 @@ function appendAudit(event, payload) {
 // writes because Claude Code re-reads settings.local.json — a torn write would drop the
 // ENTIRE allow list and every command would prompt again. Fail-open after 5s: a hook
 // must never hang the chain.
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+function readLockOwner(lockPath) {
+  const owner = readJson(path.join(lockPath, "owner"), null);
+  return owner && Number.isInteger(owner.pid) && typeof owner.token === "string"
+    ? owner
+    : null;
+}
+
 async function withLock(lockPath, fn) {
   const staleMs = 10000;
   const maxWaitMs = 5000;
   const startedAt = Date.now();
+  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
   let held = false;
   while (!held) {
     try {
       fs.mkdirSync(path.dirname(lockPath), { recursive: true });
       fs.mkdirSync(lockPath);
+      try {
+        fs.writeFileSync(path.join(lockPath, "owner"), JSON.stringify({
+          pid: process.pid,
+          token: ownerToken,
+          ts: Date.now(),
+        }));
+      } catch (error) {
+        try {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+        throw error;
+      }
       held = true;
     } catch (error) {
       if (!error || error.code !== "EEXIST") return fn();
       try {
         const stat = fs.statSync(lockPath);
         if (Date.now() - stat.mtimeMs > staleMs) {
-          try {
-            fs.rmSync(lockPath, { recursive: true, force: true });
-            continue;
-          } catch {}
+          const owner = readLockOwner(lockPath);
+          if (!owner || !isPidAlive(owner.pid)) {
+            try {
+              fs.rmSync(lockPath, { recursive: true, force: true });
+              continue;
+            } catch {}
+          }
         }
       } catch {}
       if (Date.now() - startedAt > maxWaitMs) break;
@@ -84,9 +118,12 @@ async function withLock(lockPath, fn) {
     return await fn();
   } finally {
     if (held) {
-      try {
-        fs.rmdirSync(lockPath);
-      } catch {}
+      const owner = readLockOwner(lockPath);
+      if (owner?.token === ownerToken) {
+        try {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+      }
     }
   }
 }

package/templates/.claude/hooks/context-hardcap-gate.sh

@@ -128,7 +128,9 @@ function readRunCursor() {
   let state = mod.buildCompactPressureState(rawState, sessionConfig);
   try {
     const synced = await mod.syncCompactPressureStateWithTranscript(state, sessionConfig, payload.transcript_path);
-    if (synced.reset) {
+    if (synced.reset || synced.probed) {
+      // Persist a clean probe too: hook processes are ephemeral, so otherwise every
+      // mutation would reopen and parse the same 4MB transcript tail.
       state = await mod.writeCompactPressureState(projectRoot, synced.state, sessionConfig);
     }
   } catch {
@@ -141,13 +143,24 @@ function readRunCursor() {
   // both write 4, silently multiplying the budget), so each spent call is claimed with an
   // exclusive-create sentinel file (openSync 'wx'): the sentinels present ARE the number
   // of grace calls spent, and one claim can never be counted twice.
-  const gracePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hardcap-grace.json');
-  const graceDir = path.dirname(gracePath);
-  const slotPath = (n) => path.join(graceDir, `hardcap-grace.json.${n}`);
+  // Grace is a landing allowance for THIS session's over-cap episode. The old global
+  // `hardcap-grace.json.N` slot pool let session A consume session B's allowance (and A
+  // clearing it refilled B's spent pool), so parallel sessions could be hard-blocked mid-
+  // landing for no reason. Keep the fallback `default` for hosts that omit session_id: in
+  // that legacy shape sibling workers still deliberately share one bounded allowance.
+  const rawGraceSessionId = typeof payload.session_id === 'string' && payload.session_id.trim()
+    ? payload.session_id.trim()
+    : 'default';
+  const graceSessionKey = rawGraceSessionId.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'default';
+  const graceDir = path.join(projectRoot, '.ukit', 'storage', 'cache');
+  const graceBaseName = `hardcap-grace.${graceSessionKey}.json`;
+  const gracePath = path.join(graceDir, graceBaseName);
+  const slotPath = (n) => path.join(graceDir, `${graceBaseName}.${n}`);
+  const slotPattern = new RegExp(`^${graceBaseName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.(\\d+)$`);
   const readSlots = () => {
     try {
       return fs.readdirSync(graceDir)
-        .map((name) => /^hardcap-grace\.json\.(\d+)$/.exec(name))
+        .map((name) => slotPattern.exec(name))
         .filter(Boolean)
         .map((m) => Number(m[1]))
         .sort((a, b) => a - b);

package/templates/.claude/hooks/handoff-resume.sh

@@ -27,6 +27,14 @@ const fs = require('fs');
 const path = require('path');
 const { pathToFileURL } = require('url');
 
+// Wall-clock watchdog. This hook is ADVISORY ONLY, so any hang — a wedged runtime
+// import, a lock wait that never resolves, a stalled filesystem read — must end in a
+// clean exit 0 instead of stalling session start mid-run with no visible reason.
+// Every read below is async on purpose: sync I/O would block the loop and this timer
+// could never fire. Keep it that way.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+
 const payload = (() => {
   try {
     const parsed = JSON.parse(process.env.INPUT || '');
@@ -68,7 +76,8 @@ async function emitOrdinaryResume() {
 (async () => {
   let text;
   try {
-    text = fs.readFileSync(runPath, 'utf8');
+    // Async on purpose — a sync read on a stalled mount would block the watchdog timer.
+    text = await fs.promises.readFile(runPath, 'utf8');
   } catch {
     // No handoff cursor: an ordinary routed-task intent may still be resumable.
     await emitOrdinaryResume();

package/templates/.claude/hooks/reset-compact-pressure.sh

@@ -26,26 +26,63 @@ fi
 
 # The lock directory lives beside the state file; its parent exists because the file does.
 node -e '
+const crypto = require("crypto");
 const fs = require("fs");
+const path = require("path");
+
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+function readLockOwner(lockPath) {
+  try {
+    const owner = JSON.parse(fs.readFileSync(path.join(lockPath, "owner"), "utf8"));
+    return Number.isInteger(owner?.pid) && typeof owner.token === "string" ? owner : null;
+  } catch {
+    return null;
+  }
+}
 
 async function withLock(lockPath, fn) {
   const staleMs = 10000;
   const maxWaitMs = 5000;
   const startedAt = Date.now();
+  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
   let held = false;
   while (!held) {
     try {
       fs.mkdirSync(lockPath);
+      try {
+        fs.writeFileSync(path.join(lockPath, "owner"), JSON.stringify({
+          pid: process.pid,
+          token: ownerToken,
+          ts: Date.now(),
+        }));
+      } catch (error) {
+        try {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+        throw error;
+      }
       held = true;
     } catch (error) {
       if (!error || error.code !== "EEXIST") return fn();
       try {
         const stat = fs.statSync(lockPath);
         if (Date.now() - stat.mtimeMs > staleMs) {
-          try {
-            fs.rmSync(lockPath, { recursive: true, force: true });
-            continue;
-          } catch {}
+          const owner = readLockOwner(lockPath);
+          if (!owner || !isPidAlive(owner.pid)) {
+            try {
+              fs.rmSync(lockPath, { recursive: true, force: true });
+              continue;
+            } catch {}
+          }
         }
       } catch {}
       if (Date.now() - startedAt > maxWaitMs) break;
@@ -56,9 +93,12 @@ async function withLock(lockPath, fn) {
     return await fn();
   } finally {
     if (held) {
-      try {
-        fs.rmdirSync(lockPath);
-      } catch {}
+      const owner = readLockOwner(lockPath);
+      if (owner?.token === ownerToken) {
+        try {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+      }
     }
   }
 }