avenic 1.0.0

package/vendor/core-src/runtime/config.mjs

@@ -0,0 +1,227 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { getAgent } from "./agents.mjs";
+import { ensureRuntimeGitignore, removeRuntimeGitignore } from "./gitignore.mjs";
+
+const AUTH_MODES = new Set(["global", "project"]);
+const SESSIONS_MODES = new Set(["global", "project"]);
+
+async function readJsonIfExists(file, fallback) {
+  if (!existsSync(file)) {
+    return fallback;
+  }
+  return JSON.parse((await readFile(file, "utf8")).replace(/^\uFEFF/, ""));
+}
+
+async function writeJsonIfChanged(file, value) {
+  const content = `${JSON.stringify(value, null, 2)}\n`;
+  if (existsSync(file) && (await readFile(file, "utf8")) === content) {
+    return false;
+  }
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, content, "utf8");
+  return true;
+}
+
+export function validateAuthMode(authMode) {
+  if (!AUTH_MODES.has(authMode)) {
+    throw new Error(`Authentication must be global or project: ${authMode}`);
+  }
+  return authMode;
+}
+
+export function validateSessionsMode(sessionsMode) {
+  if (!SESSIONS_MODES.has(sessionsMode)) {
+    throw new Error(`Sessions must be global or project: ${sessionsMode}`);
+  }
+  return sessionsMode;
+}
+
+export function runtimePaths(projectRoot) {
+  const agentsRoot = path.join(projectRoot, ".agents");
+  const localRoot = path.join(agentsRoot, "local");
+  return {
+    localRoot,
+    runtimeFile: path.join(agentsRoot, "runtime.json"),
+    localRuntimeFile: path.join(localRoot, "runtime.local.json"),
+    sessionsRoot: path.join(agentsRoot, "sessions"),
+  };
+}
+
+export async function loadRuntime(projectRoot) {
+  const paths = runtimePaths(projectRoot);
+  const runtime = await readJsonIfExists(paths.runtimeFile, { schemaVersion: 1, agents: {} });
+  const local = await readJsonIfExists(paths.localRuntimeFile, { schemaVersion: 1, agents: {} });
+  return { paths, runtime, local };
+}
+
+export async function initializeAgent(projectRoot, agentId, authMode, sessionsMode) {
+  getAgent(agentId);
+  if (authMode) {
+    validateAuthMode(authMode);
+  }
+  if (sessionsMode) {
+    validateSessionsMode(sessionsMode);
+  }
+  const state = await loadRuntime(projectRoot);
+  state.runtime.schemaVersion ??= 1;
+  state.runtime.agents ??= {};
+  const previous = state.runtime.agents[agentId] ?? {};
+  const effectiveAuthMode = authMode ?? previous.auth ?? "global";
+  const effectiveSessionsMode = sessionsMode ?? previous.sessions ?? "project";
+  state.runtime.agents[agentId] = {
+    ...previous,
+    enabled: true,
+    auth: effectiveAuthMode,
+    sessions: effectiveSessionsMode,
+  };
+  const sessionDirectory = path.join(state.paths.sessionsRoot, agentId);
+  const localDirectory = path.join(state.paths.localRoot, agentId);
+  const missingStructure = [sessionDirectory];
+  if (effectiveAuthMode === "project") {
+    missingStructure.push(localDirectory);
+  }
+  const structureRepaired = missingStructure.some((directory) => !existsSync(directory));
+  for (const directory of missingStructure) {
+    await mkdir(directory, { recursive: true });
+  }
+  const configChanged = await writeJsonIfChanged(state.paths.runtimeFile, state.runtime);
+  const gitignoreChanged = await ensureRuntimeGitignore(projectRoot);
+  return {
+    ...state,
+    authMode: effectiveAuthMode,
+    sessionsMode: effectiveSessionsMode,
+    configChanged,
+    gitignoreChanged,
+    structureRepaired,
+  };
+}
+
+// Environment overrides that scope an agent's credentials and configuration to
+// the project (stored under .agents/local/, which is always gitignored).
+export function projectAuthEnvironment(agentId, projectRoot) {
+  getAgent(agentId);
+  const localRoot = runtimePaths(projectRoot).localRoot;
+  switch (agentId) {
+    case "claude":
+      return { CLAUDE_CONFIG_DIR: path.join(localRoot, "claude") };
+    case "codex":
+      return { CODEX_HOME: path.join(localRoot, "codex") };
+    case "opencode":
+      return { XDG_CONFIG_HOME: path.join(localRoot, "opencode") };
+    default:
+      throw new Error(`Unknown Agent: ${agentId}`);
+  }
+}
+
+export async function deinitializeAgent(projectRoot, agentId, options = {}) {
+  const agent = getAgent(agentId);
+  const state = await loadRuntime(projectRoot);
+  if (!state.runtime.agents?.[agentId]) {
+    const sessionDirectory = path.join(state.paths.sessionsRoot, agentId);
+    const localDirectory = path.join(state.paths.localRoot, agentId);
+    const purged = Boolean(options.purge && (existsSync(sessionDirectory) || existsSync(localDirectory)));
+    if (options.purge) {
+      await rm(sessionDirectory, { recursive: true, force: true });
+      await rm(localDirectory, { recursive: true, force: true });
+      if (Object.keys(state.runtime.agents ?? {}).length === 0) {
+        await removeRuntimeGitignore(projectRoot, { sessions: true });
+      }
+    }
+    return {
+      agent,
+      changed: purged,
+      purged,
+      remaining: Object.keys(state.runtime.agents ?? {}).length,
+    };
+  }
+
+  delete state.runtime.agents[agentId];
+  if (Object.keys(state.runtime.agents).length === 0) {
+    await rm(state.paths.runtimeFile, { force: true });
+  } else {
+    await writeJsonIfChanged(state.paths.runtimeFile, state.runtime);
+  }
+
+  if (state.local.agents?.[agentId]) {
+    delete state.local.agents[agentId];
+    if (Object.keys(state.local.agents).length === 0) {
+      await rm(state.paths.localRuntimeFile, { force: true });
+    } else {
+      await writeJsonIfChanged(state.paths.localRuntimeFile, state.local);
+    }
+  }
+  if (options.purge) {
+    await rm(path.join(state.paths.localRoot, agentId), { recursive: true, force: true });
+    await rm(path.join(state.paths.sessionsRoot, agentId), { recursive: true, force: true });
+  }
+  const remaining = Object.keys(state.runtime.agents).length;
+  if (remaining === 0) {
+    if (options.purge) {
+      await rm(state.paths.localRoot, { recursive: true, force: true });
+      await rm(path.join(projectRoot, ".agents", "tmp"), { recursive: true, force: true });
+    }
+    await removeRuntimeGitignore(projectRoot, { sessions: Boolean(options.purge) });
+  }
+  return {
+    agent,
+    changed: true,
+    purged: Boolean(options.purge),
+    remaining,
+  };
+}
+
+export async function setLocalAuth(projectRoot, agentId, authMode) {
+  const agent = getAgent(agentId);
+  validateAuthMode(authMode);
+  const state = await loadRuntime(projectRoot);
+  if (!state.runtime.agents?.[agentId]?.enabled) {
+    throw new Error(`${agent.displayName} is not initialized`);
+  }
+  state.local.schemaVersion ??= 1;
+  state.local.agents ??= {};
+  state.local.agents[agentId] = {
+    ...(state.local.agents[agentId] ?? {}),
+    auth: authMode,
+  };
+  await mkdir(state.paths.localRoot, { recursive: true });
+  if (authMode === "project") {
+    await mkdir(path.join(state.paths.localRoot, agentId), { recursive: true });
+  }
+  await writeJsonIfChanged(state.paths.localRuntimeFile, state.local);
+  await ensureRuntimeGitignore(projectRoot);
+  return effectiveAgentConfig(state, agentId);
+}
+
+export async function clearLocalAuth(projectRoot, agentId) {
+  const agent = getAgent(agentId);
+  const state = await loadRuntime(projectRoot);
+  if (!state.runtime.agents?.[agentId]?.enabled) {
+    throw new Error(`${agent.displayName} is not initialized`);
+  }
+  if (!state.local.agents?.[agentId]) {
+    return effectiveAgentConfig(state, agentId);
+  }
+  delete state.local.agents[agentId];
+  if (Object.keys(state.local.agents).length === 0) {
+    await rm(state.paths.localRuntimeFile, { force: true });
+  } else {
+    await writeJsonIfChanged(state.paths.localRuntimeFile, state.local);
+  }
+  return effectiveAgentConfig(state, agentId);
+}
+
+export function effectiveAgentConfig(state, agentId) {
+  const configured = state.runtime.agents?.[agentId];
+  const override = state.local.agents?.[agentId];
+  if (!configured) {
+    return null;
+  }
+  return {
+    ...configured,
+    ...override,
+    configuredAuth: configured.auth ?? "global",
+    localAuth: override?.auth ?? null,
+  };
+}

package/vendor/core-src/runtime/gitignore.mjs

@@ -0,0 +1,69 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const REQUIRED_RULES = [
+  ".claude/skills/",
+  ".agents/skills/",
+  ".agents/local/",
+  ".agents/tmp/",
+  ".agents/direct/",
+  ".agents/licenses/",
+];
+const SESSIONS_RULE = ".agents/sessions/";
+
+async function readGitignore(projectRoot) {
+  const file = path.join(projectRoot, ".gitignore");
+  return {
+    content: existsSync(file) ? await readFile(file, "utf8") : "",
+    file,
+  };
+}
+
+async function addRules(projectRoot, rules) {
+  const { content, file } = await readGitignore(projectRoot);
+  const lines = new Set(content.split(/\r?\n/).map((line) => line.trim()));
+  const missing = rules.filter((rule) => !lines.has(rule));
+  if (missing.length === 0) return false;
+  const prefix = content.length === 0 ? "" : content.endsWith("\n") ? "\n" : "\n\n";
+  await writeFile(file, `${content}${prefix}# Agent Runtime\n${missing.join("\n")}\n`, "utf8");
+  return true;
+}
+
+export async function ensureRuntimeGitignore(projectRoot) {
+  return addRules(projectRoot, REQUIRED_RULES);
+}
+
+export async function sessionsGitIgnored(projectRoot) {
+  const { content } = await readGitignore(projectRoot);
+  return content.split(/\r?\n/).some((line) => line.trim() === SESSIONS_RULE);
+}
+
+export async function setSessionsGitIgnored(projectRoot, ignored) {
+  if (ignored) return addRules(projectRoot, [SESSIONS_RULE]);
+  const { content, file } = await readGitignore(projectRoot);
+  const lines = content.split(/\r?\n/);
+  const filtered = lines.filter((line) => line.trim() !== SESSIONS_RULE);
+  if (filtered.length === lines.length) return false;
+  await writeFile(file, filtered.join("\n"), "utf8");
+  return true;
+}
+
+export async function removeRuntimeGitignore(projectRoot, options = {}) {
+  const { content, file } = await readGitignore(projectRoot);
+  if (!content) return false;
+  const removable = new Set([".agents/local/", ".agents/tmp/"]);
+  if (options.sessions) removable.add(SESSIONS_RULE);
+  let lines = content.split(/\r?\n/).filter((line) => !removable.has(line.trim()));
+  const managedRules = new Set([...REQUIRED_RULES, SESSIONS_RULE]);
+  if (!lines.some((line) => managedRules.has(line.trim()))) {
+    lines = lines.filter((line) => line.trim() !== "# Agent Runtime");
+  }
+  while (lines.length > 0 && lines.at(-1) === "") lines.pop();
+  const updated = lines.length > 0 ? `${lines.join("\n")}\n` : "";
+  if (updated === content) return false;
+  await writeFile(file, updated, "utf8");
+  return true;
+}
+
+export { REQUIRED_RULES, SESSIONS_RULE };

package/vendor/core-src/runtime/process.mjs

@@ -0,0 +1,41 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+function resolveOnPath(executable, environment) {
+  if (path.isAbsolute(executable) || executable.includes(path.sep)) {
+    return existsSync(executable) ? executable : null;
+  }
+  const extensions = process.platform === "win32" ? [".exe", ".com", ".ps1", ".cmd", ".bat", ""] : [""];
+  for (const directory of (environment.PATH ?? "").split(path.delimiter)) {
+    if (!directory) continue;
+    for (const extension of extensions) {
+      const candidate = path.join(directory.replace(/^"|"$/g, ""), `${executable}${extension}`);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+function invocation(executable, argumentsList, environment) {
+  const resolved = resolveOnPath(executable, environment) ?? executable;
+  if (process.platform === "win32" && resolved.toLowerCase().endsWith(".ps1")) {
+    const powershell = path.join(environment.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    return {
+      command: powershell,
+      argumentsList: ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", resolved, ...argumentsList],
+    };
+  }
+  return { command: resolved, argumentsList };
+}
+
+export function spawnExecutableSync(executable, argumentsList, options = {}) {
+  const environment = options.env ?? process.env;
+  const { spawn, ...spawnOptions } = options;
+  if (spawn) {
+    return spawn(executable, argumentsList, { ...spawnOptions, env: environment });
+  }
+  const resolved = invocation(executable, argumentsList, environment);
+  return spawnSync(resolved.command, resolved.argumentsList, { ...spawnOptions, env: environment });
+}

package/vendor/core-src/runtime/project-root.mjs

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { LEGACY_PROJECT_CONFIG_FILE, PROJECT_CONFIG_FILE } from "../skills/paths.mjs";
+
+function findMarker(startDirectory, relativeMarker) {
+  let current = path.resolve(startDirectory);
+  while (true) {
+    if (existsSync(path.join(current, relativeMarker))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+function findGitRoot(startDirectory) {
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: startDirectory,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (result.status !== 0) {
+    return null;
+  }
+  const root = result.stdout.trim();
+  return root ? path.resolve(root) : null;
+}
+
+export function locateProjectRoot(startDirectory = process.cwd()) {
+  const start = path.resolve(startDirectory);
+  return (
+    findGitRoot(start) ??
+    findMarker(start, path.join(".agents", "runtime.json")) ??
+    findMarker(start, PROJECT_CONFIG_FILE) ??
+    findMarker(start, LEGACY_PROJECT_CONFIG_FILE) ??
+    start
+  );
+}

package/vendor/core-src/runtime/sessions.mjs

@@ -0,0 +1,312 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import {
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+export const PROJECT_ROOT_TOKEN = "${PROJECT_ROOT}";
+
+export function samePath(left, right) {
+  if (!left || !right) {
+    return false;
+  }
+  const normalize = (value) => {
+    const resolved = path.resolve(value);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+  };
+  return normalize(left) === normalize(right);
+}
+
+export function transformJsonLines(content, transform) {
+  const trailingNewline = content.endsWith("\n");
+  const lines = content.split(/\r?\n/);
+  if (trailingNewline) {
+    lines.pop();
+  }
+  const transformed = lines.map((line) => {
+    if (!line.trim()) {
+      return line;
+    }
+    try {
+      return JSON.stringify(transform(JSON.parse(line)));
+    } catch {
+      return line;
+    }
+  });
+  return `${transformed.join("\n")}${trailingNewline ? "\n" : ""}`;
+}
+
+export async function listFiles(root) {
+  if (!existsSync(root)) {
+    return [];
+  }
+  const files = [];
+  async function walk(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await walk(absolute);
+      } else if (entry.isFile()) {
+        files.push(path.relative(root, absolute));
+      }
+    }
+  }
+  await walk(root);
+  return files.sort();
+}
+
+export async function replaceDirectory(destination, build) {
+  const parent = path.dirname(destination);
+  const suffix = `${process.pid}-${Date.now()}`;
+  const temporary = `${destination}.tmp-${suffix}`;
+  const backup = `${destination}.bak-${suffix}`;
+  await mkdir(parent, { recursive: true });
+  await rm(temporary, { recursive: true, force: true });
+  await mkdir(temporary, { recursive: true });
+  try {
+    await build(temporary);
+    if (existsSync(destination)) {
+      await renameWithRetry(destination, backup);
+    }
+    await renameWithRetry(temporary, destination);
+    await rm(backup, { recursive: true, force: true });
+  } catch (error) {
+    await rm(temporary, { recursive: true, force: true });
+    if (existsSync(backup) && !existsSync(destination)) {
+      await renameWithRetry(backup, destination);
+    }
+    throw error;
+  }
+}
+
+async function renameWithRetry(source, destination) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      await rename(source, destination);
+      return;
+    } catch (error) {
+      if (attempt >= 4 || !["EACCES", "EBUSY", "EPERM"].includes(error.code)) throw error;
+      await delay(40 * (attempt + 1));
+    }
+  }
+}
+
+export async function snapshotFiles(sourceRoot, relativeFiles, destination, transform) {
+  await replaceDirectory(destination, async (temporary) => {
+    for (const relative of relativeFiles) {
+      const source = path.join(sourceRoot, relative);
+      const target = path.join(temporary, relative);
+      await mkdir(path.dirname(target), { recursive: true });
+      const content = await readFile(source);
+      await writeFile(target, transform ? await transform(content, relative) : content);
+    }
+  });
+}
+
+function isPrefix(prefix, content) {
+  return prefix.length <= content.length && content.subarray(0, prefix.length).equals(prefix);
+}
+
+export async function mergeFiles(sourceRoot, relativeFiles, destinationRoot, transform, options = {}) {
+  let added = 0;
+  let conflicts = 0;
+  let updated = 0;
+  let unchanged = 0;
+  for (const relative of relativeFiles) {
+    const source = path.join(sourceRoot, relative);
+    const destination = path.join(destinationRoot, relative);
+    const sourceContent = Buffer.from(transform ? await transform(await readFile(source), relative) : await readFile(source));
+    if (!existsSync(destination)) {
+      await mkdir(path.dirname(destination), { recursive: true });
+      await writeFile(destination, sourceContent);
+      added += 1;
+      continue;
+    }
+    const destinationContent = await readFile(destination);
+    if (sourceContent.equals(destinationContent) || isPrefix(sourceContent, destinationContent)) {
+      unchanged += 1;
+      continue;
+    }
+    if (relative.endsWith(".jsonl") && isPrefix(destinationContent, sourceContent)) {
+      await writeFile(destination, sourceContent);
+      updated += 1;
+      continue;
+    }
+    if (options.onConflict === "keep-destination") {
+      conflicts += 1;
+      continue;
+    }
+    if (options.onConflict === "keep-source") {
+      // The portable (project) copy wins; the destination gets the source
+      // content and the caller reports the conflict.
+      await writeFile(destination, sourceContent);
+      conflicts += 1;
+      continue;
+    }
+    throw new Error(`Session conflict: ${relative}. Keep one version, then retry.`);
+  }
+  return { added, conflicts, updated, unchanged };
+}
+
+export async function readFirstJsonLine(file) {
+  const content = await readFile(file, "utf8");
+  const line = content.split(/\r?\n/, 1)[0];
+  return JSON.parse(line.replace(/^\uFEFF/, ""));
+}
+
+export function hashContent(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function copyPath(source, destination) {
+  const stats = await stat(source);
+  if (stats.isDirectory()) {
+    await mkdir(destination, { recursive: true });
+    for (const entry of await readdir(source, { withFileTypes: true })) {
+      await copyPath(path.join(source, entry.name), path.join(destination, entry.name));
+    }
+  } else {
+    await mkdir(path.dirname(destination), { recursive: true });
+    await writeFile(destination, await readFile(source));
+  }
+}
+
+// Copy a file or directory into destination, which must not exist; when the
+// source is absent the destination is removed instead, so a path that did not
+// exist at snapshot time disappears again on revert.
+export async function snapshotInto(source, destination) {
+  if (!existsSync(source)) {
+    await rm(destination, { recursive: true, force: true });
+    return;
+  }
+  await rm(destination, { recursive: true, force: true });
+  await copyPath(source, destination);
+}
+
+// Restore the pre-launch state saved by snapshotInto: the source path returns
+// to its snapshot content, or disappears entirely when the snapshot is absent.
+export async function revertFrom(snapshot, source) {
+  await rm(source, { recursive: true, force: true });
+  if (existsSync(snapshot)) {
+    await copyPath(snapshot, source);
+  }
+}
+
+export function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM"; // exists but owned by another user
+  }
+}
+
+// Shared state for concurrent avenic launches of one agent in one project.
+export function sessionLeasePath(agentId, projectRoot) {
+  const key = createHash("sha256").update(`${path.resolve(projectRoot)}\n${agentId}`).digest("hex").slice(0, 16);
+  return path.join(os.tmpdir(), `avenic-launch-${key}`);
+}
+
+// Serialize the short bookkeeping sections of acquire/release. The lock file
+// is created exclusively, holds the owner pid, and is stolen when that
+// process is gone (crashed or killed).
+async function withLaunchLock(stateDir, run) {
+  await mkdir(stateDir, { recursive: true });
+  const lockFile = path.join(stateDir, ".lock");
+  const deadline = Date.now() + 60000;
+  for (;;) {
+    try {
+      await writeFile(lockFile, `${process.pid}\n`, { encoding: "utf8", flag: "wx" });
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+      let owner = null;
+      try {
+        owner = Number.parseInt((await readFile(lockFile, "utf8")).trim(), 10);
+      } catch {}
+      if (!(Number.isInteger(owner) && processAlive(owner))) {
+        await rm(lockFile, { force: true });
+        continue;
+      }
+      if (Date.now() > deadline) {
+        throw new Error("Timed out waiting for another avenic launch in this project");
+      }
+      await delay(100);
+    }
+  }
+  try {
+    return await run();
+  } finally {
+    await rm(lockFile, { force: true });
+  }
+}
+
+async function aliveLeasePids(stateDir) {
+  let names = [];
+  try {
+    names = await readdir(path.join(stateDir, "pids"));
+  } catch {}
+  return names
+    .map((name) => Number.parseInt(name.split("-", 1)[0], 10))
+    .filter((pid) => Number.isInteger(pid) && processAlive(pid));
+}
+
+let leaseMemberSequence = 0;
+
+// Join a launch group for one project+agent. Any number of launches can be
+// active at once; the first one snapshots the agent's native storage (or, when
+// a previous group died without finishing, salvages it via onFirst(true)
+// first) and the last one to exit reverts it via onLast, so sessions created
+// by avenic launches live only in the project. The returned function
+// leaves the group.
+// Leave a launch group as the given member. Runs onLast when the group has
+// no live launches left, then removes the group state. Used by the launch
+// flow and by the watchdog that finishes an interrupted launch.
+export async function releaseSessionLease(agentId, projectRoot, member, callbacks = {}) {
+  const stateDir = sessionLeasePath(agentId, projectRoot);
+  await withLaunchLock(stateDir, async () => {
+    await rm(path.join(stateDir, "pids", member), { force: true });
+    if ((await aliveLeasePids(stateDir)).length > 0) {
+      return;
+    }
+    try {
+      await callbacks.onLast?.();
+    } finally {
+      await rm(stateDir, { recursive: true, force: true });
+    }
+  });
+}
+
+export async function acquireSessionLease(agentId, projectRoot, callbacks = {}) {
+  const stateDir = sessionLeasePath(agentId, projectRoot);
+  const snapshotMarker = path.join(stateDir, "snapshot.ok");
+  // One member file per launch: two launches of the same process (tests) must
+  // count separately, while the pid records whether the owner is still alive.
+  const member = `${process.pid}-${Date.now()}-${leaseMemberSequence++}`;
+  await withLaunchLock(stateDir, async () => {
+    if ((await aliveLeasePids(stateDir)).length === 0) {
+      // First launch of the group, or every previous launch died: the marker
+      // records that a completed snapshot exists to recover from.
+      await callbacks.onFirst?.(existsSync(snapshotMarker));
+      await writeFile(snapshotMarker, "", { encoding: "utf8" });
+    }
+    await mkdir(path.join(stateDir, "pids"), { recursive: true });
+    await writeFile(path.join(stateDir, "pids", member), "", { encoding: "utf8" });
+  });
+  return {
+    member,
+    stateDir,
+    release: () => releaseSessionLease(agentId, projectRoot, member, callbacks),
+  };
+}