@blogic-cz/agent-tools 0.14.15 → 0.14.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.14.15",
+  "version": "0.14.20",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",

package/src/session-tool/codex.ts

@@ -0,0 +1,237 @@
+import { Glob } from "bun";
+import { Effect } from "effect";
+
+import type { MessageSummary } from "./types";
+
+import { SessionReadError, SessionStorageNotFoundError, type SessionError } from "./errors";
+
+export type CodexContentBlock =
+  | { type: "input_text"; text: string }
+  | { type: "output_text"; text: string }
+  | { type: string; text?: string };
+
+export type CodexRecord =
+  | {
+      type: "session_meta";
+      timestamp: string;
+      payload: { id: string; cwd?: string; timestamp?: string };
+    }
+  | {
+      type: "event_msg";
+      timestamp: string;
+      payload: { type: "thread_name_updated"; thread_name: string };
+    }
+  | {
+      type: "response_item";
+      timestamp: string;
+      payload: {
+        type: "message";
+        role: "user" | "assistant" | "developer" | string;
+        content: ReadonlyArray<CodexContentBlock>;
+      };
+    };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+export const parseCodexLine = (line: string): CodexRecord | null => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+
+  if (
+    !isRecord(parsed) ||
+    typeof parsed.type !== "string" ||
+    typeof parsed.timestamp !== "string"
+  ) {
+    return null;
+  }
+
+  const payload = parsed.payload;
+  if (!isRecord(payload)) {
+    return null;
+  }
+
+  if (parsed.type === "session_meta" && typeof payload.id === "string") {
+    return {
+      type: "session_meta",
+      timestamp: parsed.timestamp,
+      payload: {
+        id: payload.id,
+        cwd: typeof payload.cwd === "string" ? payload.cwd : undefined,
+        timestamp: typeof payload.timestamp === "string" ? payload.timestamp : undefined,
+      },
+    };
+  }
+
+  if (
+    parsed.type === "event_msg" &&
+    payload.type === "thread_name_updated" &&
+    typeof payload.thread_name === "string"
+  ) {
+    return {
+      type: "event_msg",
+      timestamp: parsed.timestamp,
+      payload: { type: "thread_name_updated", thread_name: payload.thread_name },
+    };
+  }
+
+  if (
+    parsed.type === "response_item" &&
+    payload.type === "message" &&
+    typeof payload.role === "string" &&
+    Array.isArray(payload.content)
+  ) {
+    return {
+      type: "response_item",
+      timestamp: parsed.timestamp,
+      payload: {
+        type: "message",
+        role: payload.role,
+        content: (payload.content as unknown[]).filter(
+          (item): item is CodexContentBlock =>
+            isRecord(item) && typeof (item as Record<string, unknown>).type === "string",
+        ),
+      },
+    };
+  }
+
+  return null;
+};
+
+export const extractCodexText = (content: ReadonlyArray<CodexContentBlock>): string =>
+  content
+    .filter(
+      (block): block is CodexContentBlock & { text: string } =>
+        (block.type === "input_text" || block.type === "output_text") &&
+        typeof block.text === "string",
+    )
+    .map((block) => block.text)
+    .join("\n");
+
+export const extractCodexTitle = (records: ReadonlyArray<CodexRecord>): string => {
+  const named = records.find((record) => record.type === "event_msg");
+  if (named !== undefined && named.type === "event_msg") {
+    return named.payload.thread_name;
+  }
+
+  const firstUser = records.find(
+    (record) => record.type === "response_item" && record.payload.role === "user",
+  );
+  if (firstUser !== undefined && firstUser.type === "response_item") {
+    return extractCodexText(firstUser.payload.content).slice(0, 100);
+  }
+
+  return "Untitled session";
+};
+
+const getSessionIdFromFile = (filePath: string): string => {
+  const fileName = filePath.split("/").pop() ?? "";
+  const match =
+    /rollout-.*?-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/u.exec(
+      fileName,
+    );
+  return match?.[1] ?? fileName.replace(/\.jsonl$/u, "");
+};
+
+export const getCodexSessionId = getSessionIdFromFile;
+
+const walkSessionFiles = (basePath: string): Promise<string[]> => {
+  const glob = new Glob("*/*/*/rollout-*.jsonl");
+  return Array.fromAsync(glob.scan({ cwd: basePath, absolute: true }));
+};
+
+const readSessionMeta = async (
+  sessionFile: string,
+): Promise<{ id: string; cwd?: string } | null> => {
+  try {
+    const text = await Bun.file(sessionFile).text();
+    const firstLine = text.split("\n")[0] ?? "";
+    const record = parseCodexLine(firstLine);
+    if (record !== null && record.type === "session_meta") {
+      return { id: record.payload.id, cwd: record.payload.cwd };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};
+
+export const getCodexSessions = (
+  basePath: string,
+  projectDir: string | null,
+): Effect.Effect<string[], SessionError> =>
+  Effect.tryPromise({
+    try: async () => {
+      const allFiles = await walkSessionFiles(basePath);
+      if (projectDir === null) {
+        return allFiles;
+      }
+
+      const metas = await Promise.all(allFiles.map((file) => readSessionMeta(file)));
+      return allFiles.filter((_, i) => metas[i] !== null && metas[i]?.cwd === projectDir);
+    },
+    catch: (error) =>
+      new SessionStorageNotFoundError({
+        message: error instanceof Error ? error.message : "Codex storage directory not found",
+        path: basePath,
+      }),
+  });
+
+export const readCodexMessages = (
+  sessionFiles: string[],
+): Effect.Effect<MessageSummary[], SessionError> =>
+  Effect.tryPromise({
+    try: async () => {
+      const summaries: MessageSummary[] = [];
+
+      for (const sessionFile of sessionFiles) {
+        let fileContent: string;
+        try {
+          // eslint-disable-next-line eslint/no-await-in-loop -- sequential file read keeps memory bounded
+          fileContent = await Bun.file(sessionFile).text();
+        } catch {
+          continue;
+        }
+
+        const records = fileContent
+          .split(/\r?\n/u)
+          .map((line) => line.trim())
+          .filter((line) => line.length > 0)
+          .map(parseCodexLine)
+          .filter((record): record is CodexRecord => record !== null);
+
+        const title = extractCodexTitle(records);
+        const sessionID = getSessionIdFromFile(sessionFile);
+
+        for (const record of records) {
+          if (record.type !== "response_item") continue;
+          if (record.payload.role !== "user" && record.payload.role !== "assistant") continue;
+
+          const body = extractCodexText(record.payload.content);
+          if (body.length === 0) continue;
+
+          const createdTimestamp = new Date(record.timestamp).getTime();
+          summaries.push({
+            sessionID,
+            id: `${sessionID}:${record.timestamp}`,
+            title,
+            body,
+            created: Number.isFinite(createdTimestamp) ? createdTimestamp : 0,
+            role: record.payload.role,
+            source: "codex",
+          });
+        }
+      }
+
+      return summaries.toSorted((left, right) => right.created - left.created);
+    },
+    catch: (error) =>
+      new SessionReadError({
+        message: error instanceof Error ? error.message : "Failed to read Codex sessions",
+        source: "codex",
+      }),
+  });

package/src/session-tool/config.ts

@@ -44,6 +44,7 @@ export class ResolvedPaths extends Context.Service<
     readonly messagesPath: string;
     readonly sessionsPath: string;
     readonly claudeCodePath: string | null;
+    readonly codexPath: string | null;
   }
 >()("@agent-tools/ResolvedPaths") {}
 
@@ -54,6 +55,8 @@ export const ResolvedPathsLayer = Layer.effect(
     const sessionsPath = yield* resolveSessionsPath;
     const claudeCodeBasePath = join(homedir(), ".claude/projects");
     const claudeCodePath = existsSync(claudeCodeBasePath) ? claudeCodeBasePath : null;
-    return { messagesPath, sessionsPath, claudeCodePath };
+    const codexBasePath = join(homedir(), ".codex/sessions");
+    const codexPath = existsSync(codexBasePath) ? codexBasePath : null;
+    return { messagesPath, sessionsPath, claudeCodePath, codexPath };
   }),
 );

package/src/session-tool/index.ts

@@ -22,7 +22,7 @@ import { formatDate, SessionService, SessionServiceLayer, truncate } from "./ser
 const AppLayer = SessionServiceLayer.pipe(Layer.provideMerge(ResolvedPathsLayer));
 
 const sourceOption = Flag.string("source").pipe(
-  Flag.withDescription("Filter by source: all, opencode, claude-code"),
+  Flag.withDescription("Filter by source: all, opencode, claude-code, codex"),
   Flag.withDefault("all"),
 );
 

package/src/session-tool/service.ts

@@ -1,9 +1,10 @@
 import { Context, Effect, Layer } from "effect";
 import { readdir } from "node:fs/promises";
 
-import type { MessageSummary, SessionInfo } from "./types";
+import type { MessageSummary, SessionInfo, SessionSource } from "./types";
 
 import { getClaudeCodeSessions, readClaudeCodeMessages } from "./claude-code";
+import { getCodexSessions, getCodexSessionId, readCodexMessages } from "./codex";
 import { ResolvedPaths } from "./config";
 import { SessionReadError, SessionStorageNotFoundError, type SessionError } from "./errors";
 
@@ -38,7 +39,11 @@ export const truncate = (value: string, maxLen: number): string => {
 
 type FileEntry = { filePath: string; content: string };
 
-type SourceFilter = "both" | "opencode" | "claude-code";
+type SourceFilter = ReadonlySet<SessionSource>;
+
+const ALL_SOURCES: SourceFilter = new Set<SessionSource>(["opencode", "claude-code", "codex"]);
+const UUID_SOURCES: SourceFilter = new Set<SessionSource>(["claude-code", "codex"]);
+const OPENCODE_ONLY: SourceFilter = new Set<SessionSource>(["opencode"]);
 
 const UUID_SESSION_ID_REGEX =
   /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/u;
@@ -50,23 +55,23 @@ const getSessionIdFromClaudeFile = (filePath: string): string => {
 
 const detectSourceFilter = (filterSessions: Set<string> | null): SourceFilter => {
   if (filterSessions === null || filterSessions.size !== 1) {
-    return "both";
+    return ALL_SOURCES;
   }
 
   const sessionId = filterSessions.values().next().value;
   if (typeof sessionId !== "string") {
-    return "both";
+    return ALL_SOURCES;
   }
 
   if (sessionId.startsWith("ses_")) {
-    return "opencode";
+    return OPENCODE_ONLY;
   }
 
   if (UUID_SESSION_ID_REGEX.test(sessionId)) {
-    return "claude-code";
+    return UUID_SOURCES;
   }
 
-  return "both";
+  return ALL_SOURCES;
 };
 
 /**
@@ -196,10 +201,26 @@ export class SessionService extends Context.Service<
                   ),
                 );
 
+          const codexSessions =
+            paths.codexPath === null
+              ? new Set<string>()
+              : yield* getCodexSessions(paths.codexPath, projectDir).pipe(
+                  Effect.map(
+                    (files) =>
+                      new Set<string>(files.map((filePath) => getCodexSessionId(filePath))),
+                  ),
+                  Effect.catchTag("SessionStorageNotFoundError", () =>
+                    Effect.succeed(new Set<string>()),
+                  ),
+                );
+
           const matchingSessions = new Set<string>(opencodeSessions);
           for (const sessionId of claudeSessions) {
             matchingSessions.add(sessionId);
           }
+          for (const sessionId of codexSessions) {
+            matchingSessions.add(sessionId);
+          }
 
           return matchingSessions;
         }),
@@ -209,65 +230,64 @@ export class SessionService extends Context.Service<
         ) {
           const sourceFilter = detectSourceFilter(filterSessions);
 
-          const opencodeSummaries =
-            sourceFilter === "claude-code"
-              ? []
-              : yield* Effect.gen(function* () {
-                  const sessionDirs = yield* Effect.tryPromise({
-                    try: async () => {
-                      const dirs = await readdir(paths.messagesPath);
-                      return dirs
-                        .filter((name) => name.startsWith("ses_"))
-                        .filter((name) => filterSessions === null || filterSessions.has(name));
-                    },
-                    catch: () =>
-                      new SessionStorageNotFoundError({
-                        message: "Message storage directory not found",
-                        path: paths.messagesPath,
-                      }),
-                  });
-
-                  const summaries: MessageSummary[] = [];
-
-                  for (const sessionId of sessionDirs) {
-                    const sessionPath = `${paths.messagesPath}/${sessionId}`;
-                    const files = yield* readJsonFilesFlat(sessionPath);
-
-                    for (const { filePath, content } of files) {
-                      const parsed = parseJson<{
-                        id?: string;
-                        role?: string;
-                        sessionID?: string;
-                        summary?: {
-                          body?: string;
-                          title?: string;
-                        };
-                        time?: {
-                          created?: number;
-                        };
-                      }>(content);
-
-                      if (parsed === null || parsed.summary?.title === undefined) {
-                        continue;
-                      }
-
-                      summaries.push({
-                        sessionID: parsed.sessionID ?? sessionId,
-                        id: parsed.id ?? filePath.split("/").pop()?.replace(".json", "") ?? "",
-                        title: parsed.summary.title,
-                        body: parsed.summary.body ?? "",
-                        created: parsed.time?.created ?? 0,
-                        role: parsed.role ?? "unknown",
-                        source: "opencode",
-                      });
+          const opencodeSummaries = !sourceFilter.has("opencode")
+            ? []
+            : yield* Effect.gen(function* () {
+                const sessionDirs = yield* Effect.tryPromise({
+                  try: async () => {
+                    const dirs = await readdir(paths.messagesPath);
+                    return dirs
+                      .filter((name) => name.startsWith("ses_"))
+                      .filter((name) => filterSessions === null || filterSessions.has(name));
+                  },
+                  catch: () =>
+                    new SessionStorageNotFoundError({
+                      message: "Message storage directory not found",
+                      path: paths.messagesPath,
+                    }),
+                });
+
+                const summaries: MessageSummary[] = [];
+
+                for (const sessionId of sessionDirs) {
+                  const sessionPath = `${paths.messagesPath}/${sessionId}`;
+                  const files = yield* readJsonFilesFlat(sessionPath);
+
+                  for (const { filePath, content } of files) {
+                    const parsed = parseJson<{
+                      id?: string;
+                      role?: string;
+                      sessionID?: string;
+                      summary?: {
+                        body?: string;
+                        title?: string;
+                      };
+                      time?: {
+                        created?: number;
+                      };
+                    }>(content);
+
+                    if (parsed === null || parsed.summary?.title === undefined) {
+                      continue;
                     }
+
+                    summaries.push({
+                      sessionID: parsed.sessionID ?? sessionId,
+                      id: parsed.id ?? filePath.split("/").pop()?.replace(".json", "") ?? "",
+                      title: parsed.summary.title,
+                      body: parsed.summary.body ?? "",
+                      created: parsed.time?.created ?? 0,
+                      role: parsed.role ?? "unknown",
+                      source: "opencode",
+                    });
                   }
+                }
 
-                  return summaries;
-                }).pipe(Effect.catchTag("SessionStorageNotFoundError", () => Effect.succeed([])));
+                return summaries;
+              }).pipe(Effect.catchTag("SessionStorageNotFoundError", () => Effect.succeed([])));
 
           const claudeSummaries =
-            sourceFilter === "opencode" || paths.claudeCodePath === null
+            !sourceFilter.has("claude-code") || paths.claudeCodePath === null
               ? []
               : yield* getClaudeCodeSessions(paths.claudeCodePath, null).pipe(
                   Effect.map((sessionFiles) =>
@@ -281,7 +301,25 @@ export class SessionService extends Context.Service<
                   Effect.catchTag("SessionStorageNotFoundError", () => Effect.succeed([])),
                 );
 
-          const summaries = [...opencodeSummaries, ...claudeSummaries];
+          const codexSummaries =
+            !sourceFilter.has("codex") || paths.codexPath === null
+              ? []
+              : yield* getCodexSessions(paths.codexPath, null).pipe(
+                  Effect.map((sessionFiles) =>
+                    filterSessions === null
+                      ? sessionFiles
+                      : sessionFiles.filter((sessionFile) =>
+                          filterSessions.has(getCodexSessionId(sessionFile)),
+                        ),
+                  ),
+                  Effect.flatMap(readCodexMessages),
+                  Effect.catchTags({
+                    SessionStorageNotFoundError: () => Effect.succeed([]),
+                    SessionReadError: () => Effect.succeed([]),
+                  }),
+                );
+
+          const summaries = [...opencodeSummaries, ...claudeSummaries, ...codexSummaries];
 
           return (
             summaries as MessageSummary[] & {

package/src/session-tool/types.ts

@@ -1,3 +1,5 @@
+import { Schema } from "effect";
+
 import type { OutputFormat } from "#shared";
 
 export type { OutputFormat };
@@ -8,7 +10,8 @@ export type SessionInfo = {
   projectID: string;
 };
 
-export type SessionSource = "opencode" | "claude-code";
+export const SessionSourceLiterals = Schema.Literals(["opencode", "claude-code", "codex"]);
+export type SessionSource = Schema.Schema.Type<typeof SessionSourceLiterals>;
 
 export type MessageSummary = {
   sessionID: string;

package/src/shared/path.ts

@@ -0,0 +1,15 @@
+const trimSlashes = (segment: string) => segment.replace(/^\/+|\/+$/g, "");
+
+export const joinPath = (first: string, ...rest: readonly string[]) => {
+  const isAbsolute = first.startsWith("/");
+  const joined = [first, ...rest]
+    .map(trimSlashes)
+    .filter((segment) => segment !== "")
+    .join("/");
+
+  if (!isAbsolute) {
+    return joined;
+  }
+
+  return joined === "" ? "/" : `/${joined}`;
+};

package/src/shared/prerequisites/runtime.ts

@@ -1,15 +1,364 @@
+// 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 { Clock, Duration, Effect, Result } from "effect";
 import { ChildProcess } from "effect/unstable/process";
 
 import type { AgentToolsConfig, ProfilePrerequisites } from "#config/types";
-import type { PrerequisiteCommandRunner, ResolvedVpnDriver } from "#shared/prerequisites/types";
-
+import type {
+  PrerequisiteCommandRunner,
+  ResolvedVpnDriver,
+  VpnCleanupPolicy,
+  VpnLease,
+  VpnLeaseHandle,
+  VpnLockOwner,
+  VpnStartState,
+} from "#shared/prerequisites/types";
+
+import { joinPath } from "#shared/path";
 import { normalizeProfilePrerequisites } from "#shared/prerequisites/config";
 import { PrerequisiteRunError } from "#shared/prerequisites/errors";
 import { missingVpnToolHint, resolveVpnDriverConfig } from "#shared/prerequisites/vpn";
 
 const readEnv = (name: string) => Bun.env[name];
 
+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;
+
+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,
+  };
+};
+
+const getErrorMessage = (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;
+
+const fsError = (message: string, error: unknown) =>
+  new PrerequisiteRunError({
+    message: `${message}: ${getErrorMessage(error)}`,
+    hint: "Retry the command. If this repeats, remove stale files under the agent-tools runtime directory.",
+  });
+
+const syncFs = <A>(message: string, operation: () => A) =>
+  Effect.try({
+    try: operation,
+    catch: (error) => fsError(message, error),
+  });
+
+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;
+  }
+
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error instanceof Error && "code" in error && error.code === "EPERM";
+  }
+};
+
+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 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 hasOtherLiveLeases = (handle: VpnLeaseHandle, now: number) =>
+  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));
+  });
+
+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));
+  });
+
+const readStartState = (handle: VpnLeaseHandle) =>
+  syncFs("Failed to read VPN prerequisite start state", () => readVpnStartState(handle.statePath));
+
+const removeOwnLease = (handle: VpnLeaseHandle) =>
+  syncFs("Failed to remove VPN prerequisite lease", () => {
+    rmSync(handle.leasePath, { force: true });
+  });
+
+const removeStartState = (handle: VpnLeaseHandle) =>
+  syncFs("Failed to remove VPN prerequisite start state", () => {
+    rmSync(handle.statePath, { force: true });
+  });
+
+const getLockDirectoryAgeMs = (handle: VpnLeaseHandle, now: number) =>
+  syncFs("Failed to inspect VPN prerequisite lease lock", () => {
+    let stats: ReturnType<typeof statSync>;
+    try {
+      stats = statSync(handle.lockPath);
+    } catch (error) {
+      if (hasErrorCode(error, "ENOENT")) {
+        return undefined;
+      }
+
+      throw error;
+    }
+
+    return now - stats.mtimeMs;
+  });
+
+const isLockOwnerStale = (
+  owner: VpnLockOwner | undefined,
+  lockAgeMs: number,
+  timeoutMs: number,
+) => {
+  const staleThresholdMs = Math.max(LOCK_STALE_MS, timeoutMs);
+  if (!owner) {
+    return lockAgeMs > staleThresholdMs;
+  }
+
+  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;
+      try {
+        mkdirSync(handle.lockPath);
+        writeFileSync(
+          joinPath(handle.lockPath, "owner.json"),
+          `{"pid":${process.pid},"createdAt":${Number(now)}}`,
+        );
+        return;
+      } catch (error) {
+        lockError = error;
+      }
+
+      if (!hasErrorCode(lockError, "EEXIST")) {
+        return yield* fsError("Failed to acquire VPN prerequisite lease lock", lockError);
+      }
+
+      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;
+};
+
+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;
@@ -145,87 +494,131 @@ export const runWithProfilePrerequisites = <A, E, CommandError>(
     }
 
     const prerequisiteResult = yield* Effect.gen(function* () {
-      const startedDrivers: Array<{ driver: ResolvedVpnDriver; cooldownMs: number }> = [];
-
-      for (const prerequisite of vpnPrerequisites) {
-        const vpnConfig = config.vpns?.[prerequisite.key];
-        if (!vpnConfig) {
-          return yield* new PrerequisiteRunError({
-            message: `VPN prerequisite "${prerequisite.key}" is not defined.`,
-            hint: `Add vpns.${prerequisite.key} to agent-tools.json5 or remove the prerequisite.`,
-          });
-        }
-
-        const driverResolution = resolveVpnDriverConfig(vpnConfig);
-        if (!driverResolution.success) {
-          return yield* new PrerequisiteRunError({
-            message: driverResolution.error,
-            hint: driverResolution.hint,
-          });
-        }
-
-        const driver = driverResolution.driver;
-        const wasConnected = yield* isVpnConnected(driver, runCommand);
-        if (wasConnected) {
-          continue;
-        }
+      const heldLeases: HeldVpnLease[] = [];
+      const acquirePrerequisites = Effect.gen(function* () {
+        for (const prerequisite of vpnPrerequisites) {
+          const vpnConfig = config.vpns?.[prerequisite.key];
+          if (!vpnConfig) {
+            return yield* new PrerequisiteRunError({
+              message: `VPN prerequisite "${prerequisite.key}" is not defined.`,
+              hint: `Add vpns.${prerequisite.key} to agent-tools.json5 or remove the prerequisite.`,
+            });
+          }
 
-        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 driverResolution = resolveVpnDriverConfig(vpnConfig);
+          if (!driverResolution.success) {
+            return yield* new PrerequisiteRunError({
+              message: driverResolution.error,
+              hint: driverResolution.hint,
+            });
+          }
 
-        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),
-              }),
-          ),
-        );
+          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 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);
+          }
 
-        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),
-          });
+          heldLeases.push({ handle, driver, cleanup, cooldownMs: vpnConfig.cooldownMs ?? 0 });
         }
+      });
 
-        const ready = yield* waitForVpn(driver, vpnConfig.connectTimeoutMs ?? 30000, runCommand);
-        if (!ready) {
-          return yield* new PrerequisiteRunError({
-            message: `VPN prerequisite "${prerequisite.key}" did not connect within timeout.`,
-            hint: missingVpnToolHint(driver),
-          });
-        }
+      const acquireResult = yield* acquirePrerequisites.pipe(Effect.result);
+      const cleanup = cleanupHeldLeases(heldLeases, runCommand);
 
-        const cleanup = prerequisite.cleanup ?? vpnConfig.defaultCleanup ?? "stop-if-started";
-        if (cleanup === "stop-if-started") {
-          startedDrivers.push({ driver, cooldownMs: vpnConfig.cooldownMs ?? 0 });
-        }
+      if (Result.isFailure(acquireResult)) {
+        yield* cleanup.pipe(Effect.ignore);
+        return yield* Effect.fail(acquireResult.failure);
       }
 
-      const cleanup = Effect.gen(function* () {
-        for (const started of startedDrivers.toReversed()) {
-          if (started.cooldownMs > 0) {
-            yield* Effect.sleep(Duration.millis(started.cooldownMs));
-          }
-
-          const stopCommand = makeVpnCommand(started.driver, "stop");
-          yield* runCommand(stopCommand.command, stopCommand.label).pipe(Effect.ignore);
-        }
-      });
-
       return yield* effect.pipe(Effect.ensuring(cleanup));
     }).pipe(Effect.result);
 

package/src/shared/prerequisites/types.ts

@@ -1,4 +1,4 @@
-import type { Effect } from "effect";
+import { Schema, type Effect } from "effect";
 import type { ChildProcess } from "effect/unstable/process";
 
 import type {
@@ -23,6 +23,9 @@ export type VpnDriverResolution =
   | { success: true; driver: ResolvedVpnDriver }
   | { success: false; error: string; hint: string };
 
+export const VpnCleanupPolicy = Schema.Literals(["leave-running", "stop-if-started"]);
+export type VpnCleanupPolicy = Schema.Schema.Type<typeof VpnCleanupPolicy>;
+
 export type PrerequisiteCommandResult = {
   readonly stdout: string;
   readonly stderr: string;
@@ -33,3 +36,28 @@ export type PrerequisiteCommandRunner<E> = (
   command: ChildProcess.Command,
   label: string,
 ) => Effect.Effect<PrerequisiteCommandResult, E, never>;
+
+export type VpnLease = {
+  readonly pid: number;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+};
+
+export type VpnStartState = {
+  readonly pid: number;
+  readonly startedAt: number;
+};
+
+export type VpnLockOwner = {
+  readonly pid: number;
+  readonly createdAt: number;
+};
+
+export type VpnLeaseHandle = {
+  readonly directory: string;
+  readonly leasePath: string;
+  readonly statePath: string;
+  readonly lockPath: string;
+  readonly ttlMs: number;
+  readonly lockTimeoutMs: number;
+};