totemlayer 0.1.59 → 0.1.66

package/bin/process-isolation.mjs

@@ -0,0 +1,258 @@
+import { access, copyFile, cp, mkdir, realpath, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname, isAbsolute, join, delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isolationError } from "./inference-broker.mjs";
+
+const entry = fileURLToPath(new URL("./isolated-agent-entry.mjs", import.meta.url));
+const darwinSupervisor = fileURLToPath(new URL("./native/darwin-lifetime", import.meta.url));
+const safePath = (path) => isAbsolute(path) && !/[\x00-\x1f]/u.test(path);
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveAgentExecutable(command, environment = process.env) {
+  const candidates = isAbsolute(command)
+    ? [command]
+    : (environment.PATH ?? "/usr/local/bin:/usr/bin:/bin")
+        .split(delimiter)
+        .filter(isAbsolute)
+        .map((root) => join(root, command));
+  for (const path of candidates) {
+    try {
+      await access(path, constants.X_OK);
+      const resolved = await realpath(path);
+      if ((await stat(resolved)).isFile()) return resolved;
+    } catch {
+      /* Next installation. */
+    }
+  }
+  throw isolationError(
+    "AGENT_NOT_INSTALLED",
+    "The selected agent executable is not installed on this host.",
+  );
+}
+
+/** A sandbox backend is a host capability, never a brand-specific allow/deny decision. */
+export async function isolationBackend(platform = process.platform) {
+  if (platform === "darwin" && (await exists("/usr/bin/sandbox-exec"))) return "seatbelt";
+  if (platform === "linux" && (await exists("/usr/bin/bwrap"))) return "bubblewrap";
+  throw isolationError(
+    "ISOLATION_UNAVAILABLE",
+    "This host needs an OS isolation backend (macOS sandbox-exec or Linux bubblewrap) before automatic agent execution. No uncontained fallback is used.",
+  );
+}
+
+export function seatbeltProfile({ root, readPaths, codeRoots = [], port }) {
+  if (
+    ![root, ...readPaths, ...codeRoots].every(safePath) ||
+    (port !== null && (!Number.isInteger(port) || port < 1 || port > 65535))
+  )
+    throw isolationError("ISOLATION_CONFIG_INVALID", "Invalid sandbox paths or broker port.");
+  const quote = JSON.stringify;
+  const systemInfo = [
+    "hw.memsize",
+    "hw.pagesize",
+    "hw.pagesize_compat",
+    "hw.ncpu",
+    "hw.activecpu",
+    "hw.logicalcpu",
+    "hw.logicalcpu_max",
+    "hw.physicalcpu",
+    "hw.physicalcpu_max",
+    "hw.cpufamily",
+    "hw.cputype",
+    "hw.cpusubtype",
+    "hw.machine",
+    "hw.cachelinesize",
+    "kern.hostname",
+    "kern.version",
+    "kern.osrelease",
+    "kern.osversion",
+    "kern.ostype",
+    "kern.maxfilesperproc",
+    "kern.argmax",
+    "sysctl.proc_cputype",
+  ];
+  const metadata = new Set();
+  // Let a CLI distinguish absent system policy from an inaccessible policy.
+  // Existing policy contents stay denied unless explicitly provisioned.
+  for (const path of [
+    "/etc",
+    "/private/etc",
+    "/private/etc/codex",
+    "/private/etc/codex/requirements.toml",
+    "/private/etc/codex/managed_config.toml",
+  ])
+    metadata.add(path);
+  for (const path of [
+    root,
+    ...readPaths,
+    ...codeRoots,
+    "/System/Library",
+    "/usr/lib",
+    "/usr/share",
+    "/Library/Apple",
+    "/dev/null",
+    "/usr/bin/env",
+  ]) {
+    for (let parent = dirname(path); parent !== "/"; parent = dirname(parent)) metadata.add(parent);
+  }
+  return (
+    `(version 1)\n(deny default)\n` +
+    `(allow process-fork process-exec)\n` +
+    // Account lookup only; preferences, Keychain and owner files remain denied.
+    `(allow mach-lookup (global-name "com.apple.system.opendirectoryd.libinfo"))\n` +
+    `(allow sysctl-read ${systemInfo.map((name) => `(sysctl-name ${quote(name)})`).join(" ")} (sysctl-name-prefix "hw.optional."))\n` +
+    `(allow file-read-metadata ${[...metadata].map((path) => `(literal ${quote(path)})`).join(" ")})\n` +
+    `(allow signal (target self))\n` +
+    `(allow file-read* (literal "/") (subpath "/System/Library") (subpath "/usr/lib") (subpath "/usr/share") (subpath "/Library/Apple") (literal "/dev/null") (literal "/dev/urandom") (literal "/dev/random") (literal "/usr/bin/env") (subpath ${quote(root)}) ${readPaths.map((path) => `(literal ${quote(path)})`).join(" ")} ${codeRoots.map((path) => `(subpath ${quote(path)})`).join(" ")})\n` +
+    `(allow file-write* (subpath ${quote(root)}) (literal "/dev/null"))\n` +
+    (port ? `(allow network-outbound (remote tcp "localhost:${port}"))\n` : "")
+  );
+}
+
+/** Only executable code is readable. Owner home, auth files, sockets and repositories are absent. */
+export async function isolatedInvocation({
+  command,
+  args,
+  root,
+  env,
+  broker,
+  environment = process.env,
+  platform = process.platform,
+  codePaths = [],
+}) {
+  const backend = await isolationBackend(platform);
+  root = await realpath(root);
+  let executable = await resolveAgentExecutable(command, environment);
+  let node = await realpath(process.execPath);
+  args = await Promise.all(
+    args.map((arg) => (typeof arg === "string" && isAbsolute(arg) ? realpath(arg) : arg)),
+  );
+  let readPaths = [
+    ...new Set(
+      await Promise.all(
+        [
+          executable,
+          node,
+          ...codePaths,
+          ...args.filter((arg) => typeof arg === "string" && isAbsolute(arg)),
+        ].map((path) => realpath(path)),
+      ),
+    ),
+  ];
+  for (const path of readPaths) {
+    if (!safePath(path) || !(await stat(path)).isFile())
+      throw isolationError("ISOLATION_CONFIG_INVALID", "Agent code inputs must be explicit files.");
+  }
+  // Installed package code is a trusted executable dependency, never a user home
+  // or project directory. Standalone scripts expose only their exact code files.
+  const packageMatch = executable.match(/^(.*\/node_modules\/(?:@[^/]+\/)?[^/]+)\//u);
+  let codeRoots = packageMatch ? [packageMatch[1]] : [];
+  if (backend === "seatbelt") {
+    // launchd does not inherit the caller's access to TCC-protected folders.
+    // Stage only the code already approved above, preserving its relative layout.
+    const protectedCode =
+      /^\/(?:System\/Volumes\/Data\/)?Users\/[^/]+\/(?:Documents|Desktop|Downloads|Library\/(?:Mobile Documents|CloudStorage))(?:\/|$)/u;
+    const staged = new Map();
+    const destination = (path) => join(root, "code", path.slice(1));
+    for (const path of codeRoots.filter((path) => protectedCode.test(path))) {
+      await mkdir(dirname(destination(path)), { recursive: true });
+      // Do not dereference package symlinks into unapproved owner files.
+      await cp(path, destination(path), {
+        recursive: true,
+        dereference: false,
+        verbatimSymlinks: true,
+      });
+      staged.set(path, destination(path));
+    }
+    for (const path of readPaths.filter((path) => protectedCode.test(path))) {
+      const target = destination(path);
+      if (!codeRoots.some((parent) => path.startsWith(`${parent}/`) && staged.has(parent))) {
+        await mkdir(dirname(target), { recursive: true });
+        await copyFile(path, target);
+      }
+      staged.set(path, target);
+    }
+    executable = staged.get(executable) ?? executable;
+    node = staged.get(node) ?? node;
+    args = args.map((arg) => staged.get(arg) ?? arg);
+    readPaths = readPaths.map((path) => staged.get(path) ?? path);
+    codeRoots = codeRoots.map((path) => staged.get(path) ?? path);
+  }
+  const childEnv = {
+    PATH: `${dirname(node)}:/usr/local/bin:/usr/bin:/bin`,
+    HOME: root,
+    CFFIXED_USER_HOME: root,
+    TMPDIR: root,
+    TMP: root,
+    TEMP: root,
+    XDG_CONFIG_HOME: join(root, "config"),
+    XDG_DATA_HOME: join(root, "data"),
+    XDG_CACHE_HOME: join(root, "cache"),
+    LANG: "en_US.UTF-8",
+    ...env,
+  };
+  if (backend === "seatbelt") {
+    try {
+      await access(darwinSupervisor, constants.X_OK);
+    } catch {
+      throw isolationError(
+        "ISOLATION_UNAVAILABLE",
+        "The macOS process lifetime supervisor is missing. Reinstall the CLI before running native agents.",
+      );
+    }
+    return {
+      command: darwinSupervisor,
+      args: [
+        "--status-fd=3",
+        "--",
+        "/usr/bin/sandbox-exec",
+        "-p",
+        seatbeltProfile({ root, readPaths, codeRoots, port: broker?.port ?? null }),
+        executable,
+        ...args,
+      ],
+      env: childEnv,
+      cwd: root,
+      inheritSystemEnvironment: false,
+      managedLifecycle: "darwin-coalition",
+    };
+  }
+  const bargs = [
+    "--die-with-parent",
+    "--new-session",
+    "--unshare-all",
+    "--proc",
+    "/proc",
+    "--dev",
+    "/dev",
+  ];
+  for (const path of ["/usr/bin", "/usr/lib", "/bin", "/lib", "/lib64", "/etc/ssl/certs"])
+    if (await exists(path)) bargs.push("--ro-bind", path, path);
+  for (const path of readPaths) bargs.push("--ro-bind", path, path);
+  for (const path of codeRoots) bargs.push("--ro-bind", path, path);
+  bargs.push("--bind", root, root, "--chdir", root);
+  if (broker) {
+    bargs.push("--ro-bind", entry, entry, node, entry);
+    childEnv.AGENT_SESSION_CONFIG = JSON.stringify({
+      command: executable,
+      args,
+      cwd: root,
+      socketPath: broker.socketPath,
+    });
+  } else bargs.push(executable, ...args);
+  return {
+    command: "/usr/bin/bwrap",
+    args: bargs,
+    env: childEnv,
+    cwd: root,
+    inheritSystemEnvironment: false,
+  };
+}

package/bin/runtime-archive.mjs

@@ -0,0 +1,131 @@
+import { gzipSync, gunzipSync } from "node:zlib";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
+export const MAX_RUNTIME_BYTES = 256 * 1024 * 1024;
+const MAX_FILES = 12000;
+const invalid = () => new Error("Invalid runtime update archive.");
+function archivePath(value) {
+  if (
+    typeof value !== "string" ||
+    Buffer.byteLength(value) > 255 ||
+    !value.startsWith("node_modules/") ||
+    /[\\:\u0000-\u001f\u007f]/.test(value) ||
+    value.split("/").some((part) => !part || part === "." || part === "..")
+  )
+    throw invalid();
+  return value;
+}
+function octal(buffer, start, length, value) {
+  const text = value.toString(8);
+  if (text.length >= length) throw invalid();
+  buffer.write(text.padStart(length - 1, "0") + "\0", start, length, "ascii");
+}
+function checksum(header) {
+  let sum = 0;
+  for (let index = 0; index < 512; index++) sum += index >= 148 && index < 156 ? 32 : header[index];
+  return sum;
+}
+export async function buildRuntimeArchive(root) {
+  const chunks = [];
+  let count = 0,
+    total = 0;
+  async function walk(relative) {
+    const names = (await readdir(join(root, relative))).sort();
+    for (const name of names) {
+      const path = archivePath(relative + "/" + name);
+      const info = await lstat(join(root, path));
+      if (info.isSymbolicLink()) throw invalid();
+      if (info.isDirectory()) {
+        await walk(path);
+        continue;
+      }
+      if (!info.isFile() || ++count > MAX_FILES || (total += info.size) > MAX_RUNTIME_BYTES)
+        throw invalid();
+      const data = await readFile(join(root, path));
+      const header = Buffer.alloc(512);
+      const split = path.lastIndexOf("/");
+      const short = Buffer.byteLength(path) <= 100 ? path : path.slice(split + 1);
+      const prefix = short === path ? "" : path.slice(0, split);
+      if (Buffer.byteLength(short) > 100 || Buffer.byteLength(prefix) > 155) throw invalid();
+      header.write(short, 0, 100, "utf8");
+      octal(header, 100, 8, info.mode & 0o111 ? 0o700 : 0o600);
+      octal(header, 108, 8, 0);
+      octal(header, 116, 8, 0);
+      octal(header, 124, 12, data.length);
+      octal(header, 136, 12, 0);
+      header.write("0", 156);
+      header.write("ustar\0", 257);
+      header.write("00", 263);
+      header.write(prefix, 345, 155, "utf8");
+      octal(header, 148, 8, checksum(header));
+      chunks.push(header, data, Buffer.alloc((512 - (data.length % 512)) % 512));
+    }
+  }
+  await walk("node_modules");
+  chunks.push(Buffer.alloc(1024));
+  const tar = Buffer.concat(chunks);
+  if (tar.length > MAX_RUNTIME_BYTES) throw invalid();
+  const archive = gzipSync(tar, { level: 9 });
+  if (archive.length > MAX_ARCHIVE_BYTES) throw invalid();
+  return archive;
+}
+export async function extractRuntimeArchive(archive, destination) {
+  if (archive.length > MAX_ARCHIVE_BYTES) throw invalid();
+  const data = gunzipSync(archive, { maxOutputLength: MAX_RUNTIME_BYTES });
+  const seen = new Set();
+  let offset = 0,
+    ended = false;
+  const text = (buffer, start, size) =>
+    buffer
+      .subarray(start, start + size)
+      .toString("utf8")
+      .replace(/\0.*$/s, "");
+  const number = (buffer, start, size) => {
+    const value = text(buffer, start, size).trim();
+    if (!/^[0-7]+$/.test(value)) throw invalid();
+    const result = Number.parseInt(value, 8);
+    if (!Number.isSafeInteger(result) || result < 0) throw invalid();
+    return result;
+  };
+  while (offset + 512 <= data.length) {
+    const header = data.subarray(offset, offset + 512);
+    if (header.every((value) => value === 0)) {
+      ended = true;
+      break;
+    }
+    if (
+      text(header, 257, 6) !== "ustar" ||
+      ![0, 48].includes(header[156]) ||
+      text(header, 157, 100) ||
+      number(header, 148, 8) !== checksum(header)
+    )
+      throw invalid();
+    const prefix = text(header, 345, 155);
+    const path = archivePath((prefix ? prefix + "/" : "") + text(header, 0, 100));
+    const size = number(header, 124, 12);
+    const mode = number(header, 100, 8);
+    if (seen.has(path) || seen.size >= MAX_FILES || offset + 512 + size > data.length)
+      throw invalid();
+    seen.add(path);
+    const target = join(destination, path);
+    // Every parent is created inside a new, private staging directory.
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    const handle = await open(
+      target,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0),
+      mode & 0o111 ? 0o700 : 0o600,
+    );
+    try {
+      await handle.writeFile(data.subarray(offset + 512, offset + 512 + size));
+    } finally {
+      await handle.close();
+    }
+    offset += 512 + Math.ceil(size / 512) * 512;
+  }
+  if (!ended || seen.size === 0 || data.subarray(offset).some((value) => value !== 0))
+    throw invalid();
+  return seen.size;
+}

package/bin/runtime-installation.mjs

@@ -60,15 +60,50 @@ export async function privateWrite(path, value) {
 export async function ensureInstalledRuntime(env = process.env) {
   const root = runtimeRoot(env);
   await privateDirectory(root);
+  await privateDirectory(join(root, "runtime"));
+  const { withRuntimeUpdateLock } = await import("./runtime-update.mjs");
+  return withRuntimeUpdateLock(root, () => installRuntimeUnlocked(env), { waitMs: 20000 });
+}
+async function installRuntimeUnlocked(env) {
+  const root = runtimeRoot(env);
+  const { compareRuntimeVersions } = await import("./runtime-update.mjs");
+  let previousRecord = {};
   let previousVersion;
   try {
-    previousVersion = (await privateRead(join(root, "runtime", "current.json"))).version;
+    previousRecord = await privateRead(join(root, "runtime", "current.json"));
+    previousVersion = previousRecord.version;
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
   }
   const metadata = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
   if (!/^\d+\.\d+\.\d+$/.test(metadata.version)) throw new Error("Invalid runtime version.");
   const runtime = join(root, "runtime");
+  // A pinned bootstrap is still useful after an update; it must never downgrade the managed copy.
+  if (previousVersion && compareRuntimeVersions(previousVersion, metadata.version) > 0) {
+    const installed = JSON.parse(
+      await readFile(
+        join(
+          root,
+          "runtime-packages",
+          previousVersion,
+          "node_modules",
+          "totemlayer",
+          "package.json",
+        ),
+        "utf8",
+      ),
+    );
+    if (installed.name !== "totemlayer" || installed.version !== previousVersion)
+      throw new Error("Invalid managed runtime installation.");
+    return {
+      root,
+      cli: join(runtime, "totem.mjs"),
+      supervisor: join(runtime, "supervisor.mjs"),
+      directory: runtime,
+      version: previousVersion,
+      upgraded: false,
+    };
+  }
   const modules = join(root, "runtime-packages", metadata.version, "node_modules");
   const destination = join(modules, "totemlayer");
   await privateDirectory(runtime);
@@ -118,6 +153,11 @@ export async function ensureInstalledRuntime(env = process.env) {
       }
       if (!selected) throw new Error("Install Totem's runtime dependencies before starting it.");
       const dependencyManifest = JSON.parse(await readFile(join(selected, "package.json"), "utf8"));
+      if (
+        dependency.from === packageRoot &&
+        dependencyManifest.version !== metadata.dependencies[dependency.name]
+      )
+        throw new Error("Runtime dependency does not match the pinned release version.");
       if (copied.has(dependency.name)) {
         if (copied.get(dependency.name) !== dependencyManifest.version)
           throw new Error("Conflicting runtime dependency versions.");
@@ -169,7 +209,7 @@ if (process.env.TOTEM_RUNTIME_ENV_LOADED === entry) {
     catch (error) { if (error.code !== 'ENOENT') throw error; }
   }
   // Node reads proxy opt-in and extra CA configuration at process startup.
-  let stopping = false, child;
+  let stopping = false, child, failures = 0;
   const controller = new AbortController();
   const handlers = ['SIGTERM', 'SIGINT'].map((signal) => [signal, () => {
     stopping = true; controller.abort(); child?.kill(signal);
@@ -185,7 +225,22 @@ if (process.env.TOTEM_RUNTIME_ENV_LOADED === entry) {
       child.once('error', () => resolve(1));
       child.once('exit', (code) => resolve(code ?? 1));
     });
-    ${target === "automatic-runtime.mjs" ? `if (code === 0) break;\n    if (!stopping) await delay(Date.now() - started < 30000 ? 30000 : 1000, undefined, { signal: controller.signal }).catch(() => {});` : "process.exitCode = code;"}
+    ${
+      target === "automatic-runtime.mjs"
+        ? `if (code === 0) break;
+    if (!stopping && code !== 75 && Date.now() - started < 30000) failures++;
+    else failures = 0;
+    if (!stopping && failures >= 3) {
+      try {
+        const latest = JSON.parse(await readFile(file, 'utf8'));
+        const { rollbackRuntimeUpdate } = await import(pathToFileURL(join(root, '..', 'runtime-packages', version, 'node_modules', 'totemlayer', 'bin', 'runtime-update.mjs')));
+        await rollbackRuntimeUpdate(latest.version, { ...environment, TOTEM_CONFIG_DIR: join(root, '..') });
+      } catch {}
+      failures = 0;
+    }
+    if (!stopping) await delay(code === 75 ? 100 : Date.now() - started < 30000 ? 30000 : 1000, undefined, { signal: controller.signal }).catch(() => {});`
+        : "process.exitCode = code;"
+    }
   } while (${target === "automatic-runtime.mjs" ? "!stopping" : "false"});
   for (const [signal, handler] of handlers) process.removeListener(signal, handler);
 }
@@ -205,7 +260,11 @@ if (process.env.TOTEM_RUNTIME_ENV_LOADED === entry) {
       await handle.close();
     }
   }
-  await privateWrite(join(runtime, "current.json"), { version: metadata.version });
+  if (previousVersion !== metadata.version)
+    await privateWrite(join(runtime, "current.json"), {
+      version: metadata.version,
+      ...(previousVersion ? { previousVersion } : {}),
+    });
   return {
     root,
     cli,

package/bin/runtime-lock.mjs

@@ -0,0 +1,118 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { lstat, rename, readdir, unlink, rmdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { powershellInvocation } from "./platform-client.mjs";
+import { privateDirectory, privateRead, privateWrite } from "./runtime-installation.mjs";
+
+const execute = promisify(execFile);
+export async function processIdentity(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 1) return null;
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    if (error.code === "ESRCH") return null;
+    throw error;
+  }
+  // PID reuse across reboot must not make an abandoned lock permanent. A failed
+  // process inspection is uncertainty, never evidence that another owner died.
+  const invocation =
+    process.platform === "win32"
+      ? powershellInvocation(
+          `$p=Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}';if(!$p){exit 1};$p|Select-Object ProcessId,CreationDate,CommandLine|ConvertTo-Json -Compress`,
+          process.env,
+        )
+      : { command: "ps", args: ["-p", String(pid), "-o", "lstart=", "-o", "args="] };
+  const result = await execute(invocation.command, invocation.args, {
+    encoding: "utf8",
+    timeout: 3000,
+    maxBuffer: 8192,
+  });
+  if (!result.stdout.trim()) throw new Error("Cannot verify the supervisor process identity.");
+  return result.stdout.trim();
+}
+export async function readSupervisorOwner(lock) {
+  const info = await lstat(lock);
+  if (
+    !info.isDirectory() ||
+    info.isSymbolicLink() ||
+    (process.getuid && info.uid !== process.getuid()) ||
+    (process.platform !== "win32" && (info.mode & 0o777) !== 0o700)
+  )
+    throw new Error("Unsafe supervisor lock.");
+  const names = await readdir(lock);
+  if (!names.length) return null;
+  if (names.length !== 1 || !/^(?:owner|owner-[a-f0-9-]{36})\.json$/.test(names[0]))
+    throw new Error("The supervisor lock contains unrecognized state.");
+  const owner = await privateRead(join(lock, names[0]));
+  if (
+    !Number.isSafeInteger(owner?.pid) ||
+    owner.pid <= 1 ||
+    (names[0] !== "owner.json" &&
+      (names[0] !== `owner-${owner.token}.json` ||
+        typeof owner.identity !== "string" ||
+        !owner.identity))
+  )
+    throw new Error("Invalid supervisor owner.");
+  return { file: names[0], owner };
+}
+export async function acquireSupervisorLock(directory, options = {}) {
+  const lock = join(directory, "supervisor.lock");
+  const stage = join(directory, `supervisor-start-${randomUUID()}`);
+  const token = randomUUID();
+  const ownerFile = `owner-${token}.json`;
+  const identity = options.processIdentity ?? processIdentity;
+  await privateDirectory(directory);
+  const owner = { pid: process.pid, token, identity: await identity(process.pid) };
+  if (!owner.identity) throw new Error("Cannot verify this supervisor process.");
+  await privateDirectory(stage);
+  await privateWrite(join(stage, ownerFile), owner);
+  const removeObserved = async (file) => {
+    if (file)
+      await unlink(join(lock, file)).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    // Never recursively delete or rename the shared lock path. A replacement
+    // contains its own unique owner file and makes rmdir fail with ENOTEMPTY.
+    await rmdir(lock).catch((error) => {
+      if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code)) throw error;
+    });
+  };
+  try {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const snapshot = await lstat(lock).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+        return null;
+      });
+      if (snapshot) {
+        const current = await readSupervisorOwner(lock).catch((error) => {
+          if (error.code !== "ENOENT") throw error;
+          return undefined;
+        });
+        if (current === undefined) continue;
+        if (!current) {
+          if (Date.now() - snapshot.mtimeMs < (options.emptyLockGraceMs ?? 30000))
+            throw new Error("Another supervisor is starting. Wait before retrying.");
+        } else {
+          const actual = await identity(current.owner.pid);
+          if (actual && (!current.owner.identity || current.owner.identity === actual))
+            throw Object.assign(new Error("The Totem supervisor is already running."), {
+              code: "SUPERVISOR_ALREADY_RUNNING",
+            });
+        }
+        await removeObserved(current?.file);
+      }
+      try {
+        // Publish owner and lock together. New installations never expose an empty lock.
+        await rename(stage, lock);
+        return () => removeObserved(ownerFile);
+      } catch (error) {
+        if (!["EEXIST", "ENOTEMPTY", "ENOENT"].includes(error.code)) throw error;
+      }
+    }
+    throw new Error("Another supervisor is starting. Wait before retrying.");
+  } finally {
+    await rm(stage, { recursive: true, force: true });
+  }
+}