@blogic-cz/agent-tools 0.14.62 → 0.15.2

package/src/shared/prerequisites/runtime.ts

@@ -1,137 +1,89 @@
-// Synchronous node:fs calls keep the cross-process lock/lease critical section atomic;
-// Bun does not provide equivalent synchronous directory primitives for this use case.
-import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
-import { Clock, Duration, Effect, Result } from "effect";
-import { ChildProcess } from "effect/unstable/process";
+import { Duration, Effect, Option, Result } from "effect";
 
-import type { AgentToolsConfig, ProfilePrerequisites } from "#config/types";
+import type { AgentToolsConfig, ProfilePrerequisites, VpnConfig } from "#config/types";
 import type {
   PrerequisiteCommandRunner,
   ResolvedVpnDriver,
   VpnCleanupPolicy,
-  VpnLease,
-  VpnLeaseHandle,
-  VpnLockOwner,
-  VpnStartState,
 } from "#shared/prerequisites/types";
 
-import { joinPath } from "#shared/path";
+import {
+  makeParentVpnCommand,
+  parseVpnStatus,
+  sanitizeVpnDriver,
+} from "#shared/prerequisites/driver-commands";
+import type { GuardianInitMessage, GuardianOutboundMessage } from "#shared/prerequisites/guardian";
 import { normalizeProfilePrerequisites } from "#shared/prerequisites/config";
 import { PrerequisiteRunError } from "#shared/prerequisites/errors";
+import type { SanitizedVpnDriver, VpnStore as VpnStoreType } from "#shared/prerequisites/store";
 import { missingVpnToolHint, resolveVpnDriverConfig } from "#shared/prerequisites/vpn";
 
-const readEnv = (name: string) => Bun.env[name];
+export const DEFAULT_VPN_IDLE_DISCONNECT_MS = 30_000;
+const DEFAULT_CONNECT_TIMEOUT_MS = 30_000;
+const DEFAULT_DISCONNECT_TIMEOUT_MS = 10_000;
+const COORDINATION_POLL_MS = 25;
+const GUARDIAN_HANDOFF_TIMEOUT_MS = 5_000;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 
-const DEFAULT_LEASE_TTL_MS = 10 * 60 * 1000;
-const LOCK_STALE_MS = 30_000;
-const LOCK_RETRY_MS = 25;
-const LOCK_TIMEOUT_BUFFER_MS = 5_000;
+type TimeoutScheduler = (callback: () => void, delayMs: number) => () => void;
 
-const getRuntimeRoot = () =>
-  readEnv("AGENT_TOOLS_RUNTIME_DIR") ??
-  joinPath(readEnv("TMPDIR") ?? readEnv("TEMP") ?? readEnv("TMP") ?? "/tmp", "agent-tools");
-
-const getDriverIdentity = (driver: ResolvedVpnDriver) => {
-  if (driver.type === "macos-scutil") {
-    return { type: driver.type, platform: driver.platform, serviceName: driver.serviceName };
-  }
-
-  if (driver.type === "linux-nmcli") {
-    return { type: driver.type, platform: driver.platform, connectionName: driver.connectionName };
-  }
-
-  return { type: driver.type, platform: driver.platform, entryName: driver.entryName };
-};
-
-const getDriverLeaseKey = (driver: ResolvedVpnDriver) =>
-  Bun.hash(JSON.stringify(getDriverIdentity(driver))).toString(16);
-
-const makeLeaseHandle = (
-  driver: ResolvedVpnDriver,
-  ttlMs: number,
-  lockTimeoutMs: number,
-): VpnLeaseHandle => {
-  const key = getDriverLeaseKey(driver);
-  const directory = joinPath(getRuntimeRoot(), "vpn-prerequisites", key);
-  return {
-    directory,
-    leasePath: joinPath(directory, `lease-${process.pid}.json`),
-    statePath: joinPath(directory, "started.json"),
-    lockPath: joinPath(directory, "lock"),
-    ttlMs,
-    lockTimeoutMs,
+export const scheduleLongTimeout = (
+  callback: () => void,
+  timeoutMs: number,
+  now: () => number = Date.now,
+  schedule: TimeoutScheduler = (scheduled, delayMs) => {
+    const handle = setTimeout(scheduled, delayMs);
+    return () => clearTimeout(handle);
+  },
+) => {
+  const deadline = now() + timeoutMs;
+  let cancelled = false;
+  let cancelActive: (() => void) | undefined;
+  const scheduleNext = () => {
+    if (cancelled) return;
+    const remainingMs = deadline - now();
+    if (remainingMs <= 0) {
+      cancelled = true;
+      callback();
+      return;
+    }
+    cancelActive = schedule(scheduleNext, Math.min(remainingMs, MAX_TIMER_DELAY_MS));
+  };
+  scheduleNext();
+  return () => {
+    cancelled = true;
+    cancelActive?.();
   };
 };
 
-const getErrorMessage = (error: unknown) =>
-  error instanceof Error ? error.message : String(error);
+const noop = () => undefined;
+const readEnv = (name: string) => process.env[name];
+const errorMessage = (error: unknown) => (error instanceof Error ? error.message : String(error));
 
-const hasErrorCode = (error: unknown, code: string) =>
-  typeof error === "object" && error !== null && "code" in error && error.code === code;
+export const vpnStartFailureMessage = (key: string, stderr: string, redactStderr: boolean) => {
+  const generic = `Failed to start VPN prerequisite "${key}".`;
+  return redactStderr ? generic : stderr.trim() || generic;
+};
 
-const fsError = (message: string, error: unknown) =>
+export const missingVpnSecretError = (key: string) =>
   new PrerequisiteRunError({
-    message: `${message}: ${getErrorMessage(error)}`,
-    hint: "Retry the command. If this repeats, remove stale files under the agent-tools runtime directory.",
+    message: `VPN prerequisite "${key}" requires configured credentials.`,
+    hint: "Set the configured VPN secret before retrying, or remove secretEnvVar from the VPN config.",
   });
 
-const syncFs = <A>(message: string, operation: () => A) =>
-  Effect.try({
-    try: operation,
-    catch: (error) => fsError(message, error),
+const coordinationError = (key: string, error: unknown) =>
+  new PrerequisiteRunError({
+    message: `Failed to coordinate VPN prerequisite "${key}": ${errorMessage(error)}`,
+    hint:
+      error instanceof Error && "hint" in error && typeof error.hint === "string"
+        ? error.hint
+        : "Retry after all agent-tools processes using this VPN have quiesced.",
   });
 
-const readJsonFile = (path: string): unknown | undefined => {
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-    return parsed;
-  } catch (error) {
-    void error;
-    return undefined;
-  }
-};
-
-type JsonObject = { readonly [key: string]: unknown };
-
-const isJsonObject = (value: unknown): value is JsonObject =>
-  typeof value === "object" && value !== null;
-
-const isFiniteNumber = (value: unknown): value is number =>
-  typeof value === "number" && Number.isFinite(value);
-
-const isVpnLease = (value: unknown): value is VpnLease =>
-  isJsonObject(value) &&
-  isFiniteNumber(value.pid) &&
-  isFiniteNumber(value.createdAt) &&
-  isFiniteNumber(value.updatedAt);
-
-const isVpnStartState = (value: unknown): value is VpnStartState =>
-  isJsonObject(value) && isFiniteNumber(value.pid) && isFiniteNumber(value.startedAt);
-
-const isVpnLockOwner = (value: unknown): value is VpnLockOwner =>
-  isJsonObject(value) && isFiniteNumber(value.pid) && isFiniteNumber(value.createdAt);
-
-const readVpnLease = (path: string) => {
-  const parsed = readJsonFile(path);
-  return isVpnLease(parsed) ? parsed : undefined;
-};
-
-const readVpnStartState = (path: string) => {
-  const parsed = readJsonFile(path);
-  return isVpnStartState(parsed) ? parsed : undefined;
-};
-
-const readVpnLockOwner = (path: string) => {
-  const parsed = readJsonFile(path);
-  return isVpnLockOwner(parsed) ? parsed : undefined;
-};
-
 const isPidLive = (pid: number) => {
-  if (!Number.isInteger(pid) || pid <= 0) {
-    return false;
-  }
-
+  if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
     process.kill(pid, 0);
     return true;
@@ -140,331 +92,648 @@ const isPidLive = (pid: number) => {
   }
 };
 
-const isLeaseLive = (lease: VpnLease | undefined, now: number, ttlMs: number) => {
-  if (!lease) {
-    return false;
-  }
-
-  if (isPidLive(lease.pid)) {
-    return true;
-  }
-
-  return now - lease.updatedAt <= ttlMs;
+const runStatus = <E>(driver: ResolvedVpnDriver, runCommand: PrerequisiteCommandRunner<E>) => {
+  const command = makeParentVpnCommand(driver, "status");
+  return runCommand(command.command, command.label).pipe(
+    Effect.result,
+    Effect.map((result) =>
+      Result.isSuccess(result)
+        ? parseVpnStatus(sanitizeVpnDriver(driver), result.success)
+        : undefined,
+    ),
+  );
 };
 
-const pruneStaleLeases = (handle: VpnLeaseHandle, now: number) =>
-  syncFs("Failed to prune VPN prerequisite lease files", () => {
-    for (const entry of readdirSync(handle.directory, { withFileTypes: true })) {
-      if (!entry.isFile() || !entry.name.startsWith("lease-") || !entry.name.endsWith(".json")) {
-        continue;
-      }
-
-      const leasePath = joinPath(handle.directory, entry.name);
-      const lease = readVpnLease(leasePath);
-      if (!isLeaseLive(lease, now, handle.ttlMs)) {
-        rmSync(leasePath, { force: true });
-      }
-    }
+const runStatusBefore = <E>(
+  driver: ResolvedVpnDriver,
+  deadline: number,
+  runCommand: PrerequisiteCommandRunner<E>,
+) =>
+  Effect.suspend(() => {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) return Effect.succeed(undefined);
+    return runStatus(driver, runCommand).pipe(
+      Effect.timeoutOption(Duration.millis(remainingMs)),
+      Effect.map(Option.getOrUndefined),
+    );
   });
 
-const hasOtherLiveLeases = (handle: VpnLeaseHandle, now: number) =>
+const waitForConnected = <E>(
+  driver: ResolvedVpnDriver,
+  deadline: number,
+  runCommand: PrerequisiteCommandRunner<E>,
+) =>
   Effect.gen(function* () {
-    yield* pruneStaleLeases(handle, now);
-
-    return yield* syncFs("Failed to inspect VPN prerequisite lease files", () => {
-      for (const entry of readdirSync(handle.directory, { withFileTypes: true })) {
-        if (!entry.isFile() || !entry.name.startsWith("lease-") || !entry.name.endsWith(".json")) {
-          continue;
-        }
-
-        const leasePath = joinPath(handle.directory, entry.name);
-        if (leasePath === handle.leasePath) {
-          continue;
-        }
-
-        const lease = readVpnLease(leasePath);
-        if (isLeaseLive(lease, now, handle.ttlMs)) {
-          return true;
-        }
-      }
-
-      return false;
-    });
-  });
-
-const writeLease = (handle: VpnLeaseHandle, now: number) =>
-  syncFs("Failed to write VPN prerequisite lease", () => {
-    mkdirSync(handle.directory, { recursive: true });
-    const existingLease = readVpnLease(handle.leasePath);
-    const lease: VpnLease = {
-      pid: process.pid,
-      createdAt: existingLease?.createdAt ?? now,
-      updatedAt: now,
-    };
-    writeFileSync(handle.leasePath, JSON.stringify(lease));
+    let last: boolean | undefined;
+    while (true) {
+      last = yield* runStatusBefore(driver, deadline, runCommand);
+      if (last === true) return true as const;
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) return last;
+      yield* Effect.sleep(Duration.millis(Math.min(250, remainingMs)));
+    }
   });
 
-const writeStartState = (handle: VpnLeaseHandle, now: number) =>
-  syncFs("Failed to write VPN prerequisite start state", () => {
-    const state: VpnStartState = { pid: process.pid, startedAt: now };
-    writeFileSync(handle.statePath, JSON.stringify(state));
-  });
+type GuardianHandle = {
+  readonly leaseId: string;
+  readonly stableGuardianId: () => Promise<string>;
+  readonly release: () => Promise<void>;
+};
 
-const readStartState = (handle: VpnLeaseHandle) =>
-  syncFs("Failed to read VPN prerequisite start state", () => readVpnStartState(handle.statePath));
+type GuardianSpawner = typeof Bun.spawn;
 
-const removeOwnLease = (handle: VpnLeaseHandle) =>
-  syncFs("Failed to remove VPN prerequisite lease", () => {
-    rmSync(handle.leasePath, { force: true });
-  });
+const safeGuardianEnvironment = (excludedName?: string) =>
+  Object.fromEntries(
+    ["PATH", "HOME", "TMPDIR", "TEMP", "TMP", "SYSTEMROOT", "WINDIR"].flatMap((name) => {
+      const value = process.env[name];
+      return value === undefined || name === excludedName ? [] : [[name, value]];
+    }),
+  );
 
-const removeStartState = (handle: VpnLeaseHandle) =>
-  syncFs("Failed to remove VPN prerequisite start state", () => {
-    rmSync(handle.statePath, { force: true });
-  });
+const guardianInit = (
+  driver: SanitizedVpnDriver,
+  runtimeRoot: string,
+  config: VpnConfig,
+  cleanup: VpnCleanupPolicy,
+  leaseId: string,
+  guardianId: string,
+): GuardianInitMessage => {
+  return {
+    type: "INIT",
+    driver,
+    runtimeRoot,
+    leaseId,
+    guardianId,
+    ownerPid: process.pid,
+    cleanup,
+    idleDisconnectMs: config.idleDisconnectMs ?? DEFAULT_VPN_IDLE_DISCONNECT_MS,
+    disconnectTimeoutMs: config.disconnectTimeoutMs ?? DEFAULT_DISCONNECT_TIMEOUT_MS,
+  };
+};
 
-const getLockDirectoryAgeMs = (handle: VpnLeaseHandle, now: number) =>
-  syncFs("Failed to inspect VPN prerequisite lease lock", () => {
-    let stats: ReturnType<typeof statSync>;
+const spawnDetachedGuardian = async (
+  driver: ResolvedVpnDriver,
+  config: VpnConfig,
+  cleanup: VpnCleanupPolicy,
+  spawn: GuardianSpawner = Bun.spawn,
+): Promise<GuardianHandle> => {
+  type Generation = {
+    readonly guardianId: string;
+    readonly child: ReturnType<typeof Bun.spawn>;
+  };
+  type Phase = "starting" | "ready" | "replacing" | "releasing" | "released" | "failed";
+
+  const { getVpnStoreLocation, VpnStore } = await import("#shared/prerequisites/store");
+  const sanitizedDriver = sanitizeVpnDriver(driver);
+  const runtimeRoot = getVpnStoreLocation(sanitizedDriver).root;
+  const leaseId = crypto.randomUUID();
+  let phase: Phase = "starting";
+  let active: Generation | undefined;
+  let candidate: Generation | undefined;
+  let replacements = 0;
+  let replacementFailure: Error | undefined;
+  let replacementInFlight: Promise<void> | undefined;
+  let failedCleanup: Promise<void> | undefined;
+  let releaseResolve: (() => void) | undefined;
+  let releaseReject: ((error: Error) => void) | undefined;
+  let releaseInFlight: Promise<void> | undefined;
+
+  const cleanupLease = () => {
+    let store: VpnStoreType | undefined;
     try {
-      stats = statSync(handle.lockPath);
-    } catch (error) {
-      if (hasErrorCode(error, "ENOENT")) {
-        return undefined;
+      store = VpnStore.open(sanitizedDriver, { root: runtimeRoot });
+      store.abandonLease(leaseId, Date.now());
+    } catch {
+      noop();
+    } finally {
+      try {
+        store?.close();
+      } catch {
+        noop();
       }
+    }
+  };
+  const cleanupFailedLease = () => (failedCleanup ??= Promise.resolve().then(cleanupLease));
+  const failReplacement = (error: unknown) => {
+    replacementFailure = error instanceof Error ? error : new Error(errorMessage(error));
+    phase = "failed";
+    releaseReject?.(replacementFailure);
+  };
 
+  const spawnGeneration = async (): Promise<Generation> => {
+    const guardianId = crypto.randomUUID();
+    let readyResolve!: () => void;
+    let readyReject!: (error: Error) => void;
+    const ready = new Promise<void>((resolve, reject) => {
+      readyResolve = resolve;
+      readyReject = reject;
+    });
+    const entry = fileURLToPath(new URL("./guardian-entry.ts", import.meta.url));
+    const child = spawn([process.execPath, entry], {
+      detached: true,
+      env: safeGuardianEnvironment(
+        driver.type === "macos-scutil" ? driver.secretEnvVar : undefined,
+      ),
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+      ipc(message: GuardianOutboundMessage) {
+        if (
+          message.type === "READY" &&
+          message.leaseId === leaseId &&
+          message.guardianId === guardianId
+        ) {
+          readyResolve();
+        } else if (message.type === "RELEASED" && message.leaseId === leaseId) {
+          releaseResolve?.();
+        } else if (message.type === "ERROR") {
+          const error = new Error(message.message);
+          readyReject(error);
+          releaseReject?.(error);
+        }
+      },
+    });
+    const generation = { guardianId, child };
+    candidate = generation;
+    child.send(guardianInit(sanitizedDriver, runtimeRoot, config, cleanup, leaseId, guardianId));
+    const timeout = setTimeout(
+      () => readyReject(new Error("Timed out waiting for VPN lease guardian readiness.")),
+      GUARDIAN_HANDOFF_TIMEOUT_MS,
+    );
+    try {
+      await Promise.race([
+        ready,
+        child.exited.then((code) => {
+          throw new Error(`VPN lease guardian exited before readiness (${code}).`);
+        }),
+      ]);
+    } catch (error) {
+      if (candidate === generation) candidate = undefined;
+      child.kill();
+      await child.exited.catch(noop);
       throw error;
+    } finally {
+      clearTimeout(timeout);
     }
+    child.unref();
+    active = generation;
+    candidate = undefined;
+    return generation;
+  };
 
-    return now - stats.mtimeMs;
-  });
+  const observe = (generation: Generation) => {
+    void generation.child.exited.then(
+      (code) => {
+        if (active !== generation) return;
+        active = undefined;
+        if (phase !== "ready") return;
+        if (replacements >= 1) {
+          failReplacement(new Error(`VPN lease guardian exited (${code}).`));
+          return;
+        }
+        replacements += 1;
+        phase = "replacing";
+        replacementInFlight = spawnGeneration()
+          .then((replacement) => {
+            if (phase === "releasing") {
+              replacement.child.send({ type: "RELEASE", leaseId });
+            } else if (phase === "replacing") {
+              phase = "ready";
+              observe(replacement);
+            }
+            return undefined;
+          })
+          .catch((error) => {
+            failReplacement(error);
+            throw replacementFailure;
+          });
+        void replacementInFlight.catch(noop);
+        return undefined;
+      },
+      (error) => {
+        if (active === generation) active = undefined;
+        failReplacement(error);
+        return undefined;
+      },
+    );
+  };
 
-const isLockOwnerStale = (
-  owner: VpnLockOwner | undefined,
-  lockAgeMs: number,
-  timeoutMs: number,
-) => {
-  const staleThresholdMs = Math.max(LOCK_STALE_MS, timeoutMs);
-  if (!owner) {
-    return lockAgeMs > staleThresholdMs;
+  let generation: Generation;
+  try {
+    generation = await spawnGeneration();
+  } catch (error) {
+    await cleanupLease();
+    replacements += 1;
+    try {
+      generation = await spawnGeneration();
+    } catch (replacementError) {
+      await cleanupLease();
+      throw replacementError instanceof Error
+        ? replacementError
+        : new Error(errorMessage(replacementError), { cause: error });
+    }
   }
+  phase = "ready";
+  observe(generation);
+
+  const stableGuardianId = async () => {
+    if (phase === "replacing") await replacementInFlight;
+    if (phase === "failed") {
+      await cleanupFailedLease();
+      throw replacementFailure ?? new Error("VPN lease guardian replacement failed.");
+    }
+    const current = active;
+    if (phase !== "ready" || !current) {
+      throw replacementFailure ?? new Error("VPN lease guardian is unavailable.");
+    }
+    if (current.child.exitCode !== null) {
+      await Promise.resolve();
+      return stableGuardianId();
+    }
+    return current.guardianId;
+  };
 
-  return !isPidLive(owner.pid) && lockAgeMs > staleThresholdMs;
-};
-
-const acquireFileLock = (handle: VpnLeaseHandle) =>
-  Effect.gen(function* () {
-    yield* syncFs("Failed to create VPN prerequisite lease directory", () => {
-      mkdirSync(handle.directory, { recursive: true });
-    });
-    const start = yield* Clock.currentTimeMillis;
-
-    while (true) {
-      const now = yield* Clock.currentTimeMillis;
-      let lockError: unknown;
+  const release = (): Promise<void> => {
+    if (phase === "released") return Promise.resolve();
+    if (releaseInFlight) return releaseInFlight;
+    if (phase === "failed") {
+      return cleanupFailedLease().then(() => {
+        throw replacementFailure ?? new Error("VPN lease guardian replacement failed.");
+      });
+    }
+    if (phase === "replacing" && !candidate) {
+      return (replacementInFlight ?? Promise.resolve()).then(release, async (error: unknown) => {
+        await cleanupFailedLease();
+        throw error;
+      });
+    }
+    phase = "releasing";
+    const target = candidate ?? active;
+    if (!target) return Promise.reject(new Error("VPN lease guardian is unavailable."));
+    const releaseTimeoutMs =
+      config.idleDisconnectMs === 0
+        ? (config.disconnectTimeoutMs ?? DEFAULT_DISCONNECT_TIMEOUT_MS) +
+          GUARDIAN_HANDOFF_TIMEOUT_MS
+        : GUARDIAN_HANDOFF_TIMEOUT_MS;
+    releaseInFlight = new Promise<void>((resolve, reject) => {
+      let settled = false;
+      let cancelTimeout: () => void = noop;
+      const settleResolve = () => {
+        if (settled) return;
+        settled = true;
+        cancelTimeout();
+        releaseResolve = undefined;
+        releaseReject = undefined;
+        resolve();
+      };
+      const settleReject = (error: Error) => {
+        if (settled) return;
+        settled = true;
+        cancelTimeout();
+        releaseResolve = undefined;
+        releaseReject = undefined;
+        reject(error);
+      };
+      cancelTimeout = scheduleLongTimeout(
+        () => settleReject(new Error("Timed out waiting for VPN lease guardian release.")),
+        releaseTimeoutMs,
+      );
+      releaseResolve = settleResolve;
+      releaseReject = settleReject;
       try {
-        mkdirSync(handle.lockPath);
-        writeFileSync(
-          joinPath(handle.lockPath, "owner.json"),
-          `{"pid":${process.pid},"createdAt":${Number(now)}}`,
+        target.child.send({ type: "RELEASE", leaseId });
+        void target.child.exited.then(
+          (code) => {
+            if (phase === "releasing") {
+              settleReject(new Error(`VPN lease guardian exited during release (${code}).`));
+            }
+            return undefined;
+          },
+          (error) => {
+            settleReject(error instanceof Error ? error : new Error(errorMessage(error)));
+          },
         );
-        return;
       } catch (error) {
-        lockError = error;
-      }
-
-      if (!hasErrorCode(lockError, "EEXIST")) {
-        return yield* fsError("Failed to acquire VPN prerequisite lease lock", lockError);
+        settleReject(error instanceof Error ? error : new Error(errorMessage(error)));
       }
+    }).then(() => {
+      phase = "released";
+      target.child.disconnect();
+      return undefined;
+    });
+    return releaseInFlight;
+  };
 
-      const lockOwner = readVpnLockOwner(joinPath(handle.lockPath, "owner.json"));
-      const lockAgeMs = yield* getLockDirectoryAgeMs(handle, Number(now));
-      if (lockAgeMs === undefined) {
-        continue;
-      }
-
-      if (isLockOwnerStale(lockOwner, lockAgeMs, handle.lockTimeoutMs)) {
-        yield* syncFs("Failed to remove stale VPN prerequisite lease lock", () => {
-          rmSync(handle.lockPath, { recursive: true, force: true });
-        });
-        continue;
-      }
-
-      if (Number(now) - Number(start) > handle.lockTimeoutMs) {
-        return yield* new PrerequisiteRunError({
-          message: "Timed out while waiting for VPN prerequisite lease lock.",
-          hint: "Retry the command. If this repeats, remove stale files under the agent-tools runtime directory.",
-        });
-      }
-
-      yield* Effect.sleep(Duration.millis(LOCK_RETRY_MS));
-    }
-  });
-
-const releaseFileLock = (handle: VpnLeaseHandle) =>
-  syncFs("Failed to release VPN prerequisite lease lock", () => {
-    rmSync(handle.lockPath, { recursive: true, force: true });
-  }).pipe(Effect.ignore);
-
-const withVpnLeaseLock = <A, E>(
-  handle: VpnLeaseHandle,
-  effect: Effect.Effect<A, E, never>,
-): Effect.Effect<A, E | PrerequisiteRunError, never> =>
-  Effect.acquireRelease(acquireFileLock(handle), () => releaseFileLock(handle)).pipe(
-    Effect.flatMap(() => effect),
-    Effect.scoped,
-  );
-
-type HeldVpnLease = {
-  readonly handle: VpnLeaseHandle;
-  readonly driver: ResolvedVpnDriver;
-  readonly cleanup: VpnCleanupPolicy;
-  readonly cooldownMs: number;
+  return { leaseId, stableGuardianId, release };
 };
 
-const cleanupHeldLeases = <CommandError>(
-  heldLeases: readonly HeldVpnLease[],
-  runCommand: PrerequisiteCommandRunner<CommandError>,
-) =>
-  Effect.gen(function* () {
-    for (const held of heldLeases.toReversed()) {
-      if (held.cooldownMs > 0) {
-        yield* Effect.sleep(Duration.millis(held.cooldownMs));
-      }
-
-      yield* withVpnLeaseLock(
-        held.handle,
-        Effect.gen(function* () {
-          const now = yield* Clock.currentTimeMillis;
-          yield* removeOwnLease(held.handle);
-          if (held.cleanup === "leave-running") {
-            // Treat the agent-started VPN as intentionally adopted so later default runs do not stop it.
-            yield* removeStartState(held.handle);
-            return;
-          }
-
-          const state = yield* readStartState(held.handle);
-          const hasOtherLeases = yield* hasOtherLiveLeases(held.handle, Number(now));
-          const shouldStop = state !== undefined && !hasOtherLeases;
-
-          if (!shouldStop) {
-            return;
-          }
-
-          const stopCommand = makeVpnCommand(held.driver, "stop");
-          yield* runCommand(stopCommand.command, stopCommand.label).pipe(Effect.ignore);
-          yield* removeStartState(held.handle);
-        }),
-      ).pipe(Effect.ignore);
-    }
-  });
-
-const makeVpnCommand = (driver: ResolvedVpnDriver, action: "status" | "start" | "stop") => {
-  if (driver.type === "macos-scutil") {
-    const secret = driver.secretEnvVar ? readEnv(driver.secretEnvVar) : undefined;
-    const secretArgs = action === "start" && secret ? ["--secret", secret] : [];
-    const redactedSecretArgs = secretArgs.length > 0 ? ["--secret", "<redacted>"] : [];
-    const args =
-      action === "status"
-        ? ["--nc", "status", driver.serviceName]
-        : action === "start"
-          ? ["--nc", "start", driver.serviceName, ...secretArgs]
-          : ["--nc", "stop", driver.serviceName];
-    const labelArgs =
-      action === "start" ? ["--nc", "start", driver.serviceName, ...redactedSecretArgs] : args;
-
-    return {
-      command: ChildProcess.make("scutil", args, { stdout: "pipe", stderr: "pipe" }),
-      label: ["scutil", ...labelArgs].join(" "),
-    };
-  }
-
-  if (driver.type === "linux-nmcli") {
-    const args =
-      action === "status"
-        ? ["-t", "-f", "NAME", "connection", "show", "--active"]
-        : action === "start"
-          ? ["connection", "up", driver.connectionName]
-          : ["connection", "down", driver.connectionName];
-
-    return {
-      command: ChildProcess.make("nmcli", args, { stdout: "pipe", stderr: "pipe" }),
-      label: ["nmcli", ...args].join(" "),
-    };
-  }
-
-  const args =
-    action === "stop"
-      ? [driver.entryName, "/disconnect"]
-      : action === "start"
-        ? [driver.entryName]
-        : [];
+const makeInlineGuardian = async <E>(
+  driver: ResolvedVpnDriver,
+  config: VpnConfig,
+  cleanup: VpnCleanupPolicy,
+  runCommand: PrerequisiteCommandRunner<E>,
+): Promise<GuardianHandle> => {
+  const [{ runGuardian }, { getVpnStoreLocation }] = await Promise.all([
+    import("#shared/prerequisites/guardian"),
+    import("#shared/prerequisites/store"),
+  ]);
+  const leaseId = crypto.randomUUID();
+  const guardianId = crypto.randomUUID();
+  const sanitizedDriver = sanitizeVpnDriver(driver);
+  const init = guardianInit(
+    sanitizedDriver,
+    getVpnStoreLocation(sanitizedDriver).root,
+    config,
+    cleanup,
+    leaseId,
+    guardianId,
+  );
+  const guardian = await runGuardian(
+    init,
+    () => undefined,
+    (action) => {
+      const command = makeParentVpnCommand(driver, action);
+      return Effect.runPromise(runCommand(command.command, command.label));
+    },
+  );
   return {
-    command: ChildProcess.make("rasdial", args, { stdout: "pipe", stderr: "pipe" }),
-    label: ["rasdial", ...args].join(" "),
+    leaseId,
+    stableGuardianId: () => Promise.resolve(guardianId),
+    release: guardian.release,
   };
 };
 
-const isVpnConnectedOutput = (driver: ResolvedVpnDriver, stdout: string) => {
-  if (driver.type === "macos-scutil") {
-    return stdout.includes("Connected");
-  }
-
-  if (driver.type === "linux-nmcli") {
-    return stdout
-      .trim()
-      .split("\n")
-      .some((line) => line.trim() === driver.connectionName);
-  }
-
-  return stdout.includes(driver.entryName);
-};
-
-const isVpnConnected = <E>(driver: ResolvedVpnDriver, runCommand: PrerequisiteCommandRunner<E>) => {
-  const statusCommand = makeVpnCommand(driver, "status");
-  return runCommand(statusCommand.command, statusCommand.label).pipe(
-    Effect.result,
-    Effect.map((result) => {
-      if (Result.isFailure(result)) {
-        return false;
-      }
-
-      return result.success.exitCode === 0 && isVpnConnectedOutput(driver, result.success.stdout);
-    }),
+const startGuardian = <E>(
+  driver: ResolvedVpnDriver,
+  config: VpnConfig,
+  cleanup: VpnCleanupPolicy,
+  runCommand: PrerequisiteCommandRunner<E>,
+  runGuardianInProcess: boolean,
+  spawn?: GuardianSpawner,
+) =>
+  runGuardianInProcess
+    ? makeInlineGuardian(driver, config, cleanup, runCommand)
+    : spawnDetachedGuardian(driver, config, cleanup, spawn);
+
+type ReleasableGuardian = { readonly release: () => Promise<void> };
+type HeldVpnLease = { readonly guardian: GuardianHandle };
+
+const safelyReleaseGuardian = (guardian: ReleasableGuardian) =>
+  Effect.promise(() =>
+    Promise.resolve()
+      .then(() => guardian.release())
+      .catch(noop),
   );
-};
 
-const waitForVpn = <E>(
+export const releaseHeldLeases = (leases: readonly { readonly guardian: ReleasableGuardian }[]) =>
+  leases
+    .toReversed()
+    .reduce(
+      (released, held) => released.pipe(Effect.andThen(safelyReleaseGuardian(held.guardian))),
+      Effect.void,
+    );
+
+export const closeVpnStoreAfter = <A, E>(
+  key: string,
+  guardian: ReleasableGuardian,
+  close: () => void,
+  body: Effect.Effect<A, E, never>,
+): Effect.Effect<A, E | PrerequisiteRunError, never> =>
+  Effect.matchCauseEffect(body, {
+    onFailure: (cause) =>
+      Effect.exit(Effect.sync(close)).pipe(Effect.andThen(Effect.failCause(cause))),
+    onSuccess: (value) =>
+      Effect.try({
+        try: close,
+        catch: (error) => coordinationError(key, error),
+      }).pipe(
+        Effect.catch((error) =>
+          safelyReleaseGuardian(guardian).pipe(Effect.andThen(Effect.fail(error))),
+        ),
+        Effect.map(() => value),
+      ),
+  });
+
+const acquireVpn = <E>(
+  key: string,
   driver: ResolvedVpnDriver,
-  timeoutMs: number,
+  config: VpnConfig,
+  cleanup: VpnCleanupPolicy,
   runCommand: PrerequisiteCommandRunner<E>,
+  runGuardianInProcess: boolean,
+  spawn?: GuardianSpawner,
 ) =>
   Effect.gen(function* () {
-    const startTime = yield* Clock.currentTimeMillis;
-    const deadline = Number(startTime) + timeoutMs;
-    let result: boolean | undefined;
-
-    yield* Effect.whileLoop({
-      while: () => result === undefined,
-      body: () =>
-        Effect.gen(function* () {
-          if (yield* isVpnConnected(driver, runCommand)) {
-            result = true;
-            return;
+    const guardian = yield* Effect.tryPromise({
+      try: () => startGuardian(driver, config, cleanup, runCommand, runGuardianInProcess, spawn),
+      catch: (error) => coordinationError(key, error),
+    });
+    const releaseGuardian = safelyReleaseGuardian(guardian);
+    const fail = (error: PrerequisiteRunError) =>
+      releaseGuardian.pipe(Effect.andThen(Effect.fail(error)));
+    const store = yield* Effect.tryPromise({
+      try: async () => {
+        const { VpnStore } = await import("#shared/prerequisites/store");
+        return VpnStore.open(sanitizeVpnDriver(driver));
+      },
+      catch: (error) => coordinationError(key, error),
+    }).pipe(Effect.catch(fail));
+    const connectTimeoutMs = config.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    const idleDisconnectMs = config.idleDisconnectMs ?? DEFAULT_VPN_IDLE_DISCONNECT_MS;
+    const connectDeadline = Date.now() + connectTimeoutMs;
+    const stoppingCoordinationDeadline =
+      connectDeadline + (config.disconnectTimeoutMs ?? DEFAULT_DISCONNECT_TIMEOUT_MS);
+    const activateGuardianLease = Effect.tryPromise({
+      try: async () => {
+        const guardianId = await guardian.stableGuardianId();
+        return store.activateLease(guardian.leaseId, guardianId, Date.now());
+      },
+      catch: (error) => coordinationError(key, error),
+    }).pipe(Effect.catch(fail));
+
+    const acquisition = Effect.gen(function* () {
+      try {
+        store.deleteDeadLeases(isPidLive, idleDisconnectMs, Date.now());
+        while (true) {
+          const snapshot = store.snapshot();
+          if (snapshot.lifecycle === "UNKNOWN") {
+            return yield* fail(
+              new PrerequisiteRunError({
+                message: `VPN prerequisite "${key}" has unknown ownership: ${snapshot.evidence ?? "no evidence"}`,
+                hint: "Quiesce all agent-tools processes and remove its VPN runtime state before retrying.",
+              }),
+            );
+          }
+          if (snapshot.lifecycle === "ACTIVE" || snapshot.lifecycle === "IDLE") {
+            if (yield* activateGuardianLease) return guardian;
+            const remainingMs = connectDeadline - Date.now();
+            if (remainingMs <= 0) {
+              return yield* fail(coordinationError(key, "Guardian lease reservation was lost."));
+            }
+            yield* Effect.sleep(Duration.millis(Math.min(COORDINATION_POLL_MS, remainingMs)));
+            continue;
+          }
+          if (snapshot.lifecycle === "EXTERNAL") {
+            const guard = store.claimExternalCheck(
+              crypto.randomUUID(),
+              crypto.randomUUID(),
+              process.pid,
+              Date.now(),
+            );
+            if (!guard) continue;
+            const claimed = store.snapshot();
+            const connected = yield* runStatusBefore(driver, connectDeadline, runCommand);
+            if (connected === undefined) {
+              store.reconcileOperation(claimed, undefined, Date.now());
+              return yield* fail(
+                new PrerequisiteRunError({
+                  message: `Could not confirm external VPN prerequisite "${key}" status.`,
+                  hint: missingVpnToolHint(driver),
+                }),
+              );
+            }
+            if (!store.commitCheck(guard, connected, Date.now())) continue;
+            if (!connected) continue;
+            if (yield* activateGuardianLease) return guardian;
+            continue;
+          }
+          if (
+            snapshot.lifecycle === "CHECKING" ||
+            snapshot.lifecycle === "STARTING" ||
+            snapshot.lifecycle === "STOPPING"
+          ) {
+            const operationDeadline =
+              snapshot.lifecycle === "STOPPING" ? stoppingCoordinationDeadline : connectDeadline;
+            const remainingMs = operationDeadline - Date.now();
+            if (remainingMs <= 0) {
+              store.reconcileOperation(snapshot, undefined, Date.now());
+              return yield* fail(
+                coordinationError(key, `Timed out waiting for ${snapshot.lifecycle}.`),
+              );
+            }
+            if (snapshot.operationPid !== null && !isPidLive(snapshot.operationPid)) {
+              if (snapshot.lifecycle !== "CHECKING") {
+                store.reconcileOperation(snapshot, undefined, Date.now());
+                continue;
+              }
+              const connected = yield* runStatusBefore(driver, connectDeadline, runCommand);
+              store.reconcileOperation(snapshot, connected, Date.now());
+              continue;
+            }
+            const sleepRemainingMs = operationDeadline - Date.now();
+            if (sleepRemainingMs <= 0) continue;
+            yield* Effect.sleep(Duration.millis(Math.min(COORDINATION_POLL_MS, sleepRemainingMs)));
+            continue;
           }
 
-          const now = yield* Clock.currentTimeMillis;
-          if (Number(now) >= deadline) {
-            result = false;
-            return;
+          const checkGuard = store.claimCheck(
+            crypto.randomUUID(),
+            crypto.randomUUID(),
+            process.pid,
+            Date.now(),
+          );
+          if (!checkGuard) continue;
+          const claimedCheck = store.snapshot();
+          const connected = yield* runStatusBefore(driver, connectDeadline, runCommand);
+          if (connected === undefined) {
+            store.reconcileOperation(claimedCheck, undefined, Date.now());
+            return yield* fail(
+              new PrerequisiteRunError({
+                message: `Could not determine VPN prerequisite "${key}" status.`,
+                hint: missingVpnToolHint(driver),
+              }),
+            );
+          }
+          if (!store.commitCheck(checkGuard, connected, Date.now())) continue;
+          if (connected) {
+            if (yield* activateGuardianLease) return guardian;
+            continue;
           }
 
-          yield* Effect.sleep(Duration.millis(500));
-        }),
-      step: () => undefined,
+          if (
+            driver.type === "macos-scutil" &&
+            driver.secretEnvVar &&
+            !readEnv(driver.secretEnvVar)
+          ) {
+            return yield* fail(missingVpnSecretError(key));
+          }
+          const startGuard = store.claimStart(
+            crypto.randomUUID(),
+            crypto.randomUUID(),
+            process.pid,
+            Date.now(),
+          );
+          if (!startGuard) continue;
+          const startSecret =
+            driver.type === "macos-scutil" && driver.secretEnvVar
+              ? readEnv(driver.secretEnvVar)
+              : undefined;
+          const startCommand = makeParentVpnCommand(driver, "start", startSecret);
+          const startRemainingMs = connectDeadline - Date.now();
+          const startResult =
+            startRemainingMs <= 0
+              ? Option.none()
+              : yield* runCommand(startCommand.command, startCommand.label).pipe(
+                  Effect.result,
+                  Effect.timeoutOption(Duration.millis(startRemainingMs)),
+                );
+          if (Option.isNone(startResult) || Result.isFailure(startResult.value)) {
+            const message = `VPN prerequisite "${key}" start timed out or failed after dispatch.`;
+            store.commitStart(startGuard, "unknown", crypto.randomUUID(), message, Date.now());
+            return yield* fail(
+              new PrerequisiteRunError({
+                message,
+                hint: missingVpnToolHint(driver),
+              }),
+            );
+          }
+          if (startResult.value.success.exitCode !== 0) {
+            const message = vpnStartFailureMessage(
+              key,
+              startResult.value.success.stderr,
+              startSecret !== undefined,
+            );
+            store.commitStart(startGuard, "down", crypto.randomUUID(), message, Date.now());
+            return yield* fail(
+              new PrerequisiteRunError({
+                message,
+                hint: missingVpnToolHint(driver),
+              }),
+            );
+          }
+          const ready = yield* waitForConnected(driver, connectDeadline, runCommand);
+          if (ready !== true) {
+            store.commitStart(
+              startGuard,
+              "unknown",
+              crypto.randomUUID(),
+              ready === false
+                ? "VPN start completed but was not confirmed connected before the deadline."
+                : "VPN start confirmation failed, timed out, or was unparseable.",
+              Date.now(),
+            );
+            return yield* fail(
+              new PrerequisiteRunError({
+                message: `VPN prerequisite "${key}" did not connect within timeout.`,
+                hint: missingVpnToolHint(driver),
+              }),
+            );
+          }
+          store.commitStart(
+            startGuard,
+            "managed",
+            crypto.randomUUID(),
+            "VPN start confirmed connected.",
+            Date.now(),
+          );
+        }
+      } catch (error) {
+        return yield* fail(
+          error instanceof PrerequisiteRunError ? error : coordinationError(key, error),
+        );
+      }
     });
-
-    return result === true;
+    return yield* closeVpnStoreAfter(key, guardian, () => store.close(), acquisition);
   });
 
 export const runWithProfilePrerequisites = <A, E, CommandError>(
@@ -472,30 +741,27 @@ export const runWithProfilePrerequisites = <A, E, CommandError>(
   profile: ProfilePrerequisites,
   runCommand: PrerequisiteCommandRunner<CommandError>,
   effect: Effect.Effect<A, E, never>,
-  options?: { tryWithoutPrerequisites?: boolean },
+  options?: {
+    tryWithoutPrerequisites?: boolean;
+    runGuardianInProcess?: boolean;
+    guardianSpawn?: GuardianSpawner;
+  },
 ): Effect.Effect<A, E | PrerequisiteRunError, never> => {
-  const prerequisites = normalizeProfilePrerequisites(profile);
-  const vpnPrerequisites = prerequisites.filter((prerequisite) => prerequisite.type === "vpn");
-
-  if (vpnPrerequisites.length === 0) {
-    return effect;
-  }
+  const vpnPrerequisites = normalizeProfilePrerequisites(profile).filter(
+    (prerequisite) => prerequisite.type === "vpn",
+  );
+  if (vpnPrerequisites.length === 0) return effect;
 
   return Effect.gen(function* () {
-    const shouldTryDirect = options?.tryWithoutPrerequisites === true;
-
     const tryDirect = () => effect.pipe(Effect.result);
-
-    if (shouldTryDirect) {
-      const directResult = yield* tryDirect();
-      if (Result.isSuccess(directResult)) {
-        return directResult.success;
-      }
+    if (options?.tryWithoutPrerequisites) {
+      const direct = yield* tryDirect();
+      if (Result.isSuccess(direct)) return direct.success;
     }
 
     const prerequisiteResult = yield* Effect.gen(function* () {
-      const heldLeases: HeldVpnLease[] = [];
-      const acquirePrerequisites = Effect.gen(function* () {
+      const held: HeldVpnLease[] = [];
+      const acquired = yield* Effect.gen(function* () {
         for (const prerequisite of vpnPrerequisites) {
           const vpnConfig = config.vpns?.[prerequisite.key];
           if (!vpnConfig) {
@@ -504,138 +770,44 @@ export const runWithProfilePrerequisites = <A, E, CommandError>(
               hint: `Add vpns.${prerequisite.key} to agent-tools.json5 or remove the prerequisite.`,
             });
           }
-
-          const driverResolution = resolveVpnDriverConfig(vpnConfig);
-          if (!driverResolution.success) {
+          const resolution = resolveVpnDriverConfig(vpnConfig);
+          if (!resolution.success) {
             return yield* new PrerequisiteRunError({
-              message: driverResolution.error,
-              hint: driverResolution.hint,
+              message: resolution.error,
+              hint: resolution.hint,
             });
           }
-
-          const driver = driverResolution.driver;
-          const cleanup: VpnCleanupPolicy =
-            prerequisite.cleanup ?? vpnConfig.defaultCleanup ?? "stop-if-started";
-          const connectTimeoutMs = vpnConfig.connectTimeoutMs ?? 30000;
-          const handle = makeLeaseHandle(
-            driver,
-            vpnConfig.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS,
-            connectTimeoutMs + LOCK_TIMEOUT_BUFFER_MS,
+          const cleanup = prerequisite.cleanup ?? vpnConfig.defaultCleanup ?? "stop-if-started";
+          const guardian = yield* acquireVpn(
+            prerequisite.key,
+            resolution.driver,
+            vpnConfig,
+            cleanup,
+            runCommand,
+            options?.runGuardianInProcess === true,
+            options?.guardianSpawn,
           );
-
-          const acquisitionResult = yield* withVpnLeaseLock(
-            handle,
-            Effect.gen(function* () {
-              const result = yield* Effect.gen(function* () {
-                const now = yield* Clock.currentTimeMillis;
-                yield* writeLease(handle, Number(now));
-                yield* pruneStaleLeases(handle, Number(now));
-
-                const wasConnected = yield* isVpnConnected(driver, runCommand);
-                if (wasConnected) {
-                  return;
-                }
-
-                if (
-                  driver.type === "macos-scutil" &&
-                  driver.secretEnvVar &&
-                  !readEnv(driver.secretEnvVar)
-                ) {
-                  return yield* new PrerequisiteRunError({
-                    message: `VPN secret environment variable "${driver.secretEnvVar}" is not set.`,
-                    hint: `Set ${driver.secretEnvVar} before running this tool or remove secretEnvVar from the VPN config.`,
-                  });
-                }
-
-                const startCommand = makeVpnCommand(driver, "start");
-                const startResult = yield* runCommand(
-                  startCommand.command,
-                  startCommand.label,
-                ).pipe(
-                  Effect.mapError(
-                    () =>
-                      new PrerequisiteRunError({
-                        message: `Failed to start VPN prerequisite "${prerequisite.key}".`,
-                        hint: missingVpnToolHint(driver),
-                      }),
-                  ),
-                );
-
-                if (startResult.exitCode !== 0) {
-                  const stderr = startResult.stderr.trim();
-                  return yield* new PrerequisiteRunError({
-                    message:
-                      stderr !== ""
-                        ? stderr
-                        : `Failed to start VPN prerequisite "${prerequisite.key}".`,
-                    hint: missingVpnToolHint(driver),
-                  });
-                }
-
-                const ready = yield* waitForVpn(driver, connectTimeoutMs, runCommand);
-                if (!ready) {
-                  return yield* new PrerequisiteRunError({
-                    message: `VPN prerequisite "${prerequisite.key}" did not connect within timeout.`,
-                    hint: missingVpnToolHint(driver),
-                  });
-                }
-
-                if (cleanup === "stop-if-started") {
-                  const connectedAt = yield* Clock.currentTimeMillis;
-                  yield* writeStartState(handle, Number(connectedAt));
-                }
-              }).pipe(Effect.result);
-
-              if (Result.isFailure(result)) {
-                yield* removeOwnLease(handle).pipe(Effect.ignore);
-              }
-
-              return result;
-            }),
-          ).pipe(
-            Effect.mapError((error) =>
-              error instanceof PrerequisiteRunError
-                ? error
-                : new PrerequisiteRunError({
-                    message: `Failed to coordinate VPN prerequisite "${prerequisite.key}".`,
-                    hint: missingVpnToolHint(driver),
-                  }),
-            ),
-          );
-
-          if (Result.isFailure(acquisitionResult)) {
-            return yield* Effect.fail(acquisitionResult.failure);
-          }
-
-          heldLeases.push({ handle, driver, cleanup, cooldownMs: vpnConfig.cooldownMs ?? 0 });
+          held.push({ guardian });
         }
-      });
-
-      const acquireResult = yield* acquirePrerequisites.pipe(Effect.result);
-      const cleanup = cleanupHeldLeases(heldLeases, runCommand);
+      }).pipe(Effect.result);
 
-      if (Result.isFailure(acquireResult)) {
-        yield* cleanup.pipe(Effect.ignore);
-        return yield* Effect.fail(acquireResult.failure);
+      if (Result.isFailure(acquired)) {
+        yield* releaseHeldLeases(held);
+        return yield* Effect.fail(acquired.failure);
       }
-
-      return yield* effect.pipe(Effect.ensuring(cleanup));
+      return yield* effect.pipe(Effect.ensuring(releaseHeldLeases(held)));
     }).pipe(Effect.result);
 
-    if (Result.isSuccess(prerequisiteResult)) {
-      return prerequisiteResult.success;
-    }
-
-    if (shouldTryDirect && prerequisiteResult.failure instanceof PrerequisiteRunError) {
-      const directRetryResult = yield* tryDirect();
-      if (Result.isSuccess(directRetryResult)) {
-        return directRetryResult.success;
-      }
-      if (!(directRetryResult.failure instanceof PrerequisiteRunError)) {
-        return yield* Effect.fail(directRetryResult.failure);
-      }
+    if (Result.isSuccess(prerequisiteResult)) return prerequisiteResult.success;
+    if (
+      options?.tryWithoutPrerequisites &&
+      prerequisiteResult.failure instanceof PrerequisiteRunError
+    ) {
+      const retry = yield* tryDirect();
+      if (Result.isSuccess(retry)) return retry.success;
+      if (!(retry.failure instanceof PrerequisiteRunError))
+        return yield* Effect.fail(retry.failure);
     }
-
     return yield* Effect.fail(prerequisiteResult.failure);
   });
 };