fix(state): make lifecycle lock timeouts side-effect free

src/lib/state/mcp-lifecycle-lock-acquisition.ts

@@ -43,6 +43,8 @@ export interface McpLifecycleLockOptions {
   pollIntervalMs?: number;
   timeoutMs?: number;
   corruptLockGraceMs?: number;
+  /** Monotonic clock override used by deterministic deadline tests. */
+  monotonicNow?: () => number;
 }
 
 interface HeldLockLease {
@@ -72,10 +74,13 @@ function classifyObservedMcpLifecycleLock(
   sandboxName: string,
   corruptLockGraceMs: number,
   corruptTracker: CorruptGenerationTracker,
+  now: number,
 ): McpLifecycleLockDisposition {
-  if (!observation.owner || observation.owner.sandboxName !== sandboxName) {
+  if (
+    (!observation.owner || observation.owner.sandboxName !== sandboxName) &&
+    observation.reclaimable
+  ) {
     const generation = `${observation.dev}:${observation.ino}:${observation.mtimeMs}`;
-    const now = performance.now();
     if (corruptTracker.generation !== generation) {
       corruptTracker.generation = generation;
       corruptTracker.firstSeenAt = now;
@@ -85,36 +90,42 @@ function classifyObservedMcpLifecycleLock(
   }
   resetCorruptGenerationTracker(corruptTracker);
   // The wall-clock arguments are irrelevant for a structurally valid owner.
-  return classifyMcpLifecycleLock(
-    observation,
-    sandboxName,
-    observation.mtimeMs,
-    corruptLockGraceMs,
-  );
+  return observation.owner === null
+    ? "wait"
+    : classifyMcpLifecycleLock(observation, sandboxName, observation.mtimeMs, corruptLockGraceMs);
 }
 
 async function tryReapStaleLock(
   lockPath: string,
   sandboxName: string,
   corruptLockGraceMs: number,
   corruptTracker: CorruptGenerationTracker,
+  monotonicNow: () => number,
+  assertBeforeDeadline: () => void,
 ): Promise<boolean> {
   const reaperPath = `${lockPath}.reaper`;
   const reaperToken = crypto.randomUUID();
   const reaperOwner = createMcpLifecycleLockOwner(sandboxName, reaperToken);
+  assertBeforeDeadline();
   if (!(await writeMcpLifecycleLockCandidateAndLink(reaperPath, reaperOwner))) return false;
 
   try {
     const latest = await readMcpLifecycleLockObservation(lockPath);
     if (!latest) return true;
     if (
-      classifyObservedMcpLifecycleLock(latest, sandboxName, corruptLockGraceMs, corruptTracker) !==
-      "stale"
+      classifyObservedMcpLifecycleLock(
+        latest,
+        sandboxName,
+        corruptLockGraceMs,
+        corruptTracker,
+        monotonicNow(),
+      ) !== "stale"
     ) {
       return false;
     }
 
-    return reclaimStaleMcpLifecycleLockGeneration(lockPath, latest);
+    assertBeforeDeadline();
+    return await reclaimStaleMcpLifecycleLockGeneration(lockPath, latest, assertBeforeDeadline);
   } finally {
     await safelyReleaseMcpLifecycleLock(reaperPath, reaperToken);
   }
@@ -130,23 +141,27 @@ async function acquireMcpLifecycleLock(
     options.corruptLockGraceMs,
     DEFAULT_CORRUPT_LOCK_GRACE_MS,
   );
+  const monotonicNow = options.monotonicNow ?? (() => performance.now());
   const lockPath = getMcpLifecycleLockPath(sandboxName, options.stateDir);
   await fs.promises.mkdir(path.dirname(lockPath), {
     recursive: true,
     mode: 0o700,
   });
 
-  const startedAt = performance.now();
+  const deadline = monotonicNow() + timeoutMs;
   const corruptMainTracker: CorruptGenerationTracker = { generation: null, firstSeenAt: 0 };
   const corruptReaperTracker: CorruptGenerationTracker = { generation: null, firstSeenAt: 0 };
   let lastOwnerPid: number | null = null;
+  const assertBeforeDeadline = () => {
+    if (monotonicNow() < deadline) return;
+    const ownerSuffix = lastOwnerPid ? ` (owner pid ${lastOwnerPid})` : "";
+    throw new Error(
+      `Timed out waiting for the sandbox mutation lock for '${sandboxName}'${ownerSuffix}. Another lifecycle, policy, channel, shields, or snapshot operation is still running.`,
+    );
+  };
+
   for (;;) {
-    if (performance.now() - startedAt >= timeoutMs) {
-      const ownerSuffix = lastOwnerPid ? ` (owner pid ${lastOwnerPid})` : "";
-      throw new Error(
-        `Timed out waiting for the sandbox mutation lock for '${sandboxName}'${ownerSuffix}. Another lifecycle, policy, channel, shields, or snapshot operation is still running.`,
-      );
-    }
+    assertBeforeDeadline();
 
     const reaperPath = `${lockPath}.reaper`;
     const reaperObservation = await readMcpLifecycleLockObservation(reaperPath);
@@ -156,12 +171,18 @@ async function acquireMcpLifecycleLock(
         sandboxName,
         corruptLockGraceMs,
         corruptReaperTracker,
+        monotonicNow(),
       );
       if (reaperDisposition === "stale") {
         // The reaper has the same atomic, PID-identified owner format as the
         // main lock. A SIGKILL at any point in stale-lock cleanup is therefore
         // recoverable without age-expiring a legitimate long operation.
-        await reclaimStaleMcpLifecycleLockGeneration(reaperPath, reaperObservation);
+        assertBeforeDeadline();
+        await reclaimStaleMcpLifecycleLockGeneration(
+          reaperPath,
+          reaperObservation,
+          assertBeforeDeadline,
+        );
         continue;
       }
       await sleep(pollIntervalMs);
@@ -170,13 +191,22 @@ async function acquireMcpLifecycleLock(
     resetCorruptGenerationTracker(corruptReaperTracker);
 
     if (!(await mcpLifecycleLockPathExists(reaperPath))) {
+      assertBeforeDeadline();
       const token = crypto.randomUUID();
       const owner = createMcpLifecycleLockOwner(sandboxName, token);
       if (await writeMcpLifecycleLockCandidateAndLink(lockPath, owner)) {
         // A stale-lock reaper may have appeared between our pre-check and the
         // atomic link. Do not enter the critical section until that generation
         // gate has gone away.
-        if (!(await mcpLifecycleLockPathExists(reaperPath))) return { lockPath, token };
+        if (!(await mcpLifecycleLockPathExists(reaperPath))) {
+          try {
+            assertBeforeDeadline();
+          } catch (error) {
+            await safelyReleaseMcpLifecycleLock(lockPath, token);
+            throw error;
+          }
+          return { lockPath, token };
+        }
         await safelyReleaseMcpLifecycleLock(lockPath, token);
       }
     }
@@ -190,9 +220,20 @@ async function acquireMcpLifecycleLock(
           sandboxName,
           corruptLockGraceMs,
           corruptMainTracker,
+          monotonicNow(),
         ) === "stale"
       ) {
-        if (await tryReapStaleLock(lockPath, sandboxName, corruptLockGraceMs, corruptMainTracker)) {
+        assertBeforeDeadline();
+        if (
+          await tryReapStaleLock(
+            lockPath,
+            sandboxName,
+            corruptLockGraceMs,
+            corruptMainTracker,
+            monotonicNow,
+            assertBeforeDeadline,
+          )
+        ) {
           continue;
         }
       }

src/lib/state/mcp-lifecycle-lock-identity.test.ts

@@ -73,7 +73,7 @@ function owner(
 }
 
 function observation(lockOwner: McpLifecycleLockOwner | null, mtimeMs = 0): LockObservation {
-  return { owner: lockOwner, mtimeMs, dev: 10, ino: 20 };
+  return { owner: lockOwner, mtimeMs, dev: 10, ino: 20, reclaimable: true };
 }
 
 function probes(

src/lib/state/mcp-lifecycle-lock-identity.ts

@@ -30,6 +30,8 @@ export interface LockObservation {
   mtimeMs: number;
   dev: number;
   ino: number;
+  /** Directories cannot be restored with the no-overwrite hard-link protocol. */
+  reclaimable: boolean;
 }
 
 export type McpLifecycleLockDisposition = "active" | "stale" | "wait";
@@ -198,7 +200,9 @@ export function classifyMcpLifecycleLock(
 ): McpLifecycleLockDisposition {
   const { owner } = observation;
   if (!owner || owner.sandboxName !== sandboxName) {
-    return nowMs - observation.mtimeMs >= corruptLockGraceMs ? "stale" : "wait";
+    return observation.reclaimable && nowMs - observation.mtimeMs >= corruptLockGraceMs
+      ? "stale"
+      : "wait";
   }
   // The lock coordinates local CLI processes, not independent hosts or PID
   // namespaces. Never use this process's PID table to reap a foreign owner;

src/lib/state/mcp-lifecycle-lock-storage.ts

@@ -46,7 +46,13 @@ export async function readMcpLifecycleLockObservation(
     try {
       const stat = await fs.promises.lstat(lockPath);
       if (!stat.isFile() || stat.isSymbolicLink()) {
-        return { owner: null, mtimeMs: stat.mtimeMs, dev: stat.dev, ino: stat.ino };
+        return {
+          owner: null,
+          mtimeMs: stat.mtimeMs,
+          dev: stat.dev,
+          ino: stat.ino,
+          reclaimable: !stat.isDirectory(),
+        };
       }
     } catch (statError) {
       if (isErrnoException(statError) && statError.code === "ENOENT") return null;
@@ -58,7 +64,13 @@ export async function readMcpLifecycleLockObservation(
   try {
     const stat = await handle.stat();
     if (!stat.isFile()) {
-      return { owner: null, mtimeMs: stat.mtimeMs, dev: stat.dev, ino: stat.ino };
+      return {
+        owner: null,
+        mtimeMs: stat.mtimeMs,
+        dev: stat.dev,
+        ino: stat.ino,
+        reclaimable: !stat.isDirectory(),
+      };
     }
     try {
       const parsed: unknown = JSON.parse(await handle.readFile("utf8"));
@@ -67,9 +79,16 @@ export async function readMcpLifecycleLockObservation(
         mtimeMs: stat.mtimeMs,
         dev: stat.dev,
         ino: stat.ino,
+        reclaimable: true,
       };
     } catch {
-      return { owner: null, mtimeMs: stat.mtimeMs, dev: stat.dev, ino: stat.ino };
+      return {
+        owner: null,
+        mtimeMs: stat.mtimeMs,
+        dev: stat.dev,
+        ino: stat.ino,
+        reclaimable: true,
+      };
     }
   } finally {
     await handle.close();
@@ -97,9 +116,22 @@ export async function safelyReleaseMcpLifecycleLock(
   await reclaimStaleMcpLifecycleLockGeneration(lockPath, observation);
 }
 
+async function restoreClaimedMcpLifecycleLockGeneration(
+  targetPath: string,
+  quarantinePath: string,
+): Promise<void> {
+  try {
+    await fs.promises.link(quarantinePath, targetPath);
+    await fs.promises.rm(quarantinePath, { force: true });
+  } catch (error) {
+    if (!isErrnoException(error) || error.code !== "EEXIST") throw error;
+  }
+}
+
 export async function reclaimStaleMcpLifecycleLockGeneration(
   targetPath: string,
   expected: LockObservation,
+  assertAfterClaim?: () => void,
 ): Promise<boolean> {
   const quarantinePath = `${targetPath}.reclaim-${process.pid}-${crypto.randomUUID()}`;
   try {
@@ -122,6 +154,12 @@ export async function reclaimStaleMcpLifecycleLockGeneration(
         claimed.ino === expected.ino
       : claimed?.owner?.token === expectedToken;
   if (claimedExpectedGeneration) {
+    try {
+      assertAfterClaim?.();
+    } catch (error) {
+      await restoreClaimedMcpLifecycleLockGeneration(targetPath, quarantinePath);
+      throw error;
+    }
     await fs.promises.rm(quarantinePath, { force: true, recursive: true });
     return true;
   }
@@ -131,12 +169,7 @@ export async function reclaimStaleMcpLifecycleLockGeneration(
   // quarantine name. If another generation already occupies the canonical
   // path, preserve the displaced owner record for diagnosis rather than ever
   // deleting an owner we did not claim.
-  try {
-    await fs.promises.link(quarantinePath, targetPath);
-    await fs.promises.rm(quarantinePath, { force: true });
-  } catch (error) {
-    if (!isErrnoException(error) || error.code !== "EEXIST") throw error;
-  }
+  await restoreClaimedMcpLifecycleLockGeneration(targetPath, quarantinePath);
   return false;
 }
 

test/helpers/mcp-lifecycle-lock-properties.ts

@@ -42,7 +42,7 @@ function owner(
 }
 
 function observation(lockOwner: McpLifecycleLockOwner | null, mtimeMs = 0): LockObservation {
-  return { owner: lockOwner, mtimeMs, dev: 1, ino: 1 };
+  return { owner: lockOwner, mtimeMs, dev: 1, ino: 1, reclaimable: true };
 }
 
 function probes(