@agentswf/sandbox 0.0.0-stage → 0.1.0-beta.1

package/src/git.ts

@@ -0,0 +1,152 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { contains } from "./resolve";
+import type { ResolvedSandbox } from "./seam";
+
+/**
+ * What in a writable gitdir the host's git runs, or follows to config it would run: hooks and
+ * config; `commondir`, `gitdir` and `config.worktree`, which point it elsewhere; submodules'
+ * gitdirs; and `info/`. The rest (objects, refs, the index, `HEAD`) is what a commit writes.
+ */
+const GIT_PROTECTED = [
+  "hooks",
+  "config",
+  "config.worktree",
+  "commondir",
+  "gitdir",
+  "modules",
+  "info",
+] as const;
+
+/** A worktree's own state in its gitdir, which another worktree's commit leaves. */
+const WORKTREE_STATE = ["index", "HEAD"] as const;
+
+/**
+ * What the operator's tools run from a directory they work in, unasked: srt's own list, which it
+ * denies anywhere, and claude's project settings, whose hooks run on the host's next claude there.
+ */
+const HOST_RUN = [
+  ".gitconfig",
+  ".gitmodules",
+  ".bashrc",
+  ".bash_profile",
+  ".zshrc",
+  ".zprofile",
+  ".profile",
+  ".ripgreprc",
+  ".mcp.json",
+  ".vscode",
+  ".idea",
+  ".claude/commands",
+  ".claude/agents",
+  ".claude/settings.json",
+  ".claude/settings.local.json",
+] as const;
+
+/**
+ * Every path an agent must not write, whether it exists yet or not, so the host runs nothing an
+ * agent planted: each writable gitdir's protected parts, and those of every worktree kept inside
+ * it; the state of every worktree out of reach, the main one's included, which the operator
+ * commits from; the `.git` pointers of worktrees and submodules in writable paths, which
+ * rewritten would point the host's git at a gitdir an agent made; hooks `core.hooksPath` puts in a
+ * writable path; host-run config at the root of each writable path, worktree and clone; and what
+ * any of these, being a link, names in a writable path. Every provider holds the same list.
+ */
+export async function protectedPaths(spec: ResolvedSandbox<unknown>): Promise<string[]> {
+  const writable = spec.gitdirs.filter((gitdir) => gitdir.writable);
+  const inWrite = (path: string) => spec.write.some((root) => contains(root, path));
+  const gitdirs = new Set(writable.map(({ path }) => path));
+  // Whose worktree is in reach: the others' state is theirs to stage and check out.
+  const own = new Set(writable.filter((gitdir) => !gitdir.linked).map(({ path }) => path));
+  const others: string[] = [];
+  const pointers: string[] = [];
+  for (const { path } of writable) {
+    for (const name of await readdir(join(path, "worktrees")).catch(() => [])) {
+      const worktree = join(path, "worktrees", name);
+      gitdirs.add(worktree);
+      if (!own.has(worktree)) others.push(worktree);
+      // Git keeps where each worktree's pointer is.
+      const pointer = await readFile(join(worktree, "gitdir"), "utf8").catch(() => undefined);
+      if (pointer?.trim()) pointers.push(resolve(worktree, pointer.trim()));
+    }
+    pointers.push(...(await submodulePointers(join(path, "modules"))));
+  }
+  const guarded = pointers.filter(inWrite);
+  // Where the host's tools work: each writable path, and each worktree and clone inside one.
+  const roots = [
+    ...spec.write,
+    ...guarded.map(dirname),
+    ...writable
+      .filter(({ path }) => basename(path) === ".git" && inWrite(path))
+      .map(({ path }) => dirname(path)),
+  ];
+  // `core.hooksPath` puts hooks outside the gitdir, relative to a worktree's root, often in it.
+  const hooks: string[] = [];
+  for (const { path } of writable) {
+    for (const name of ["config", "config.worktree"]) {
+      const config = await readFile(join(path, name), "utf8").catch(() => "");
+      for (const [, value = ""] of config.matchAll(/^\s*hookspath\s*=\s*(.+?)\s*$/gim)) {
+        const named = value.replace(/^"(.*)"$/, "$1");
+        // Every worktree's root: a repository's config holds for each of them.
+        const worktrees = [
+          ...(basename(path) === ".git" ? [dirname(path)] : []),
+          ...guarded.map(dirname),
+        ];
+        hooks.push(
+          ...(isAbsolute(named) ? [named] : worktrees.map((root) => resolve(root, named))),
+        );
+      }
+    }
+  }
+  const listed = [
+    ...new Set([
+      ...[...gitdirs].flatMap((gitdir) => GIT_PROTECTED.map((name) => join(gitdir, name))),
+      ...[...writable.filter((gitdir) => gitdir.linked).map(({ path }) => path), ...others].flatMap(
+        (gitdir) => WORKTREE_STATE.map((name) => join(gitdir, name)),
+      ),
+      ...guarded,
+      ...hooks.filter(inWrite),
+      ...roots.flatMap((root) => HOST_RUN.map((name) => join(root, name))),
+    ]),
+  ];
+  // One that is, or is under, a link into a writable path is written through there: that path is
+  // guarded too, whether it exists yet or not.
+  const targets = await Promise.all(
+    listed.map(async (path) => {
+      const real = await realpathOf(path);
+      return real !== path && inWrite(real) ? [real] : [];
+    }),
+  );
+  return [...new Set([...listed, ...targets.flat()])];
+}
+
+/**
+ * The `.git` pointer of each submodule whose gitdir is under `modules`, nested ones included: a
+ * module's gitdir names its worktree in its config's `core.worktree`.
+ */
+async function submodulePointers(modules: string): Promise<string[]> {
+  const found: string[] = [];
+  const visit = async (directory: string): Promise<void> => {
+    const config = await readFile(join(directory, "config"), "utf8").catch(() => undefined);
+    if (config !== undefined) {
+      const worktree = /^\s*worktree\s*=\s*(.+?)\s*$/m.exec(config)?.[1];
+      if (worktree) found.push(join(resolve(directory, worktree), ".git"));
+      await visit(join(directory, "modules"));
+      return;
+    }
+    // A module's name may hold `/`: its gitdir is nested that deep.
+    for (const entry of await readdir(directory, { withFileTypes: true }).catch(() => [])) {
+      if (entry.isDirectory()) await visit(join(directory, entry.name));
+    }
+  };
+  if (await stat(modules).catch(() => undefined)) await visit(modules);
+  return found;
+}
+
+/** `path` with every link in it resolved, the part below the deepest one that exists kept as is. */
+async function realpathOf(path: string): Promise<string> {
+  const real = await realpath(path).catch(() => undefined);
+  if (real !== undefined) return real;
+  const parent = dirname(path);
+  return parent === path ? path : join(await realpathOf(parent), basename(path));
+}

package/src/groups.ts

@@ -0,0 +1,81 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+/** A shell script that records its pid in `$0`, then becomes the command in `$@`. */
+export const RECORD_LEADER = 'mkdir -p "$(dirname "$0")" && echo $$ > "$0" && exec "$@"';
+
+/**
+ * A shell script that kills, where the host's `process.kill` cannot reach, the group each pid file
+ * among its arguments names, or each one in a directory among them, and forgets it. A pid that is
+ * not a number above 1 is skipped: `kill -9 -1` would take every process of the uid.
+ */
+export const KILL_GROUPS = `for a in "$@"; do for f in "$a" "$a"/*; do [ -f "$f" ] || continue; p=$(cat "$f"); case "$p" in ''|*[!0-9]*|0|1) ;; *) kill -9 -"$p" 2>/dev/null;; esac; rm -f "$f"; done; done; true`;
+
+/**
+ * The process groups one agent's launches lead, each named by a pid file its leader writes, so a
+ * provider can end what an agent still runs at `release` and `close`: a turn left finishing, or
+ * one a caller never killed. `runProcess` makes each launch a group leader (`setsid`).
+ */
+export class LaunchedGroups {
+  constructor(private readonly directory: string) {}
+
+  /** A fresh pid file, in a directory that exists, for a leader that records itself: a pane's. */
+  async pidFile(): Promise<string> {
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    return join(this.directory, randomUUID());
+  }
+
+  /** `argv`, run by a shell that records its pid and then becomes it. */
+  wrap(argv: readonly string[]): { argv: string[]; pidFile: string } {
+    const pidFile = join(this.directory, randomUUID());
+    return {
+      argv: ["/bin/sh", "-c", RECORD_LEADER, pidFile, ...argv],
+      pidFile,
+    };
+  }
+
+  /**
+   * Kills the group whose leader wrote `pidFile`. A group id stays reserved while any member
+   * lives, and no process takes a live group's id, so the one risk is a leader whose group is
+   * gone and whose pid a new process has taken: a pane's file stays until release. A process
+   * holding the pid that started after the file was written is that one, and is left alone.
+   */
+  async kill(pidFile: string): Promise<void> {
+    const [text, written] = await Promise.all([
+      readFile(pidFile, "utf8").catch(() => ""),
+      stat(pidFile).then(
+        (found) => found.mtimeMs,
+        () => undefined,
+      ),
+    ]);
+    const pid = Number(text.trim());
+    const started = Number.isSafeInteger(pid) && pid > 1 ? startedAt(pid) : undefined;
+    // `ps` gives whole seconds. With the leader gone, what is left of its group is killed.
+    const reused = started !== undefined && written !== undefined && started > written + 1_000;
+    if (Number.isSafeInteger(pid) && pid > 1 && !reused) {
+      try {
+        process.kill(-pid, "SIGKILL");
+      } catch {
+        // Already gone.
+      }
+    }
+    await rm(pidFile, { force: true });
+  }
+
+  /** Kills every group still recorded, and forgets them. */
+  async killAll(): Promise<void> {
+    const files = await readdir(this.directory).catch(() => []);
+    await Promise.all(files.map((file) => this.kill(join(this.directory, file))));
+    await rm(this.directory, { recursive: true, force: true });
+  }
+}
+
+/** When the process `pid` started, in milliseconds, or undefined when there is none. */
+function startedAt(pid: number): number | undefined {
+  const listed = Bun.spawnSync(["ps", "-o", "lstart=", "-p", String(pid)], {
+    env: { PATH: "/bin:/usr/bin", LC_ALL: "C", TZ: "UTC" },
+  });
+  const started = Date.parse(`${listed.stdout.toString().trim()} UTC`);
+  return listed.exitCode === 0 && Number.isFinite(started) ? started : undefined;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { repositoryOf, resolveSandbox, withinReach } from "./resolve";
+export * from "./seam";
+export { shellQuote } from "./secrets";

package/src/once.ts

@@ -0,0 +1,16 @@
+/** `start`, run once and shared by every caller until it fails: the call after a failure tries again. */
+export function onceUnlessFailed<A extends unknown[], T>(
+  start: (...args: A) => Promise<T>,
+): (...args: A) => Promise<T> {
+  let running: Promise<T> | undefined;
+  return (...args) => {
+    if (!running) {
+      const attempt = start(...args);
+      running = attempt;
+      attempt.catch(() => {
+        if (running === attempt) running = undefined;
+      });
+    }
+    return running;
+  };
+}

package/src/pane.ts

@@ -0,0 +1,39 @@
+import { randomUUID } from "node:crypto";
+import type { PaneTerminal } from "./seam";
+import { shellQuote } from "./secrets";
+
+/**
+ * What a pane's login shell is typed, to become the agent's shell: a zsh run through `through`,
+ * with exactly `environment`, and nothing of the operator's shell; when it exits the pane closes
+ * (H6). Its pid is recorded in `pidFile` and, with job control off (`+m`), every job stays in the
+ * group it leads, so a release ends them all. Its secrets are sourced from `secretsFile`, which is
+ * then removed. zsh takes `PROMPT` from its environment, typed as `%%` and shown as `%`, so the
+ * screen shows `ready` only once zsh draws it.
+ */
+export function panePrelude(options: {
+  environment: Readonly<Record<string, string>>;
+  pidFile: string;
+  secretsFile: string;
+  through: readonly string[];
+}): Pick<PaneTerminal, "prelude" | "ready"> {
+  const nonce = randomUUID().replaceAll("-", "");
+  const environment = {
+    ...options.environment,
+    TERM: "xterm-256color",
+    PROMPT: `awf-%%-${nonce}%# `,
+  };
+  const pidFile = shellQuote(options.pidFile);
+  const secretsFile = shellQuote(options.secretsFile);
+  const confined = [
+    `mkdir -p "$(dirname ${pidFile})" && echo $$ > ${pidFile}`,
+    `set -a; . ${secretsFile}; set +a; rm -f ${secretsFile}`,
+    `exec ${[...options.through, "/bin/zsh", "-f", "+m"].map(shellQuote).join(" ")}`,
+  ].join("; ");
+  const assignments = Object.entries(environment)
+    .map(([name, value]) => `${name}=${shellQuote(value)}`)
+    .join(" ");
+  return {
+    prelude: `exec /usr/bin/env -i ${assignments} /bin/sh -c ${shellQuote(confined)}`,
+    ready: `awf-%-${nonce}% `,
+  };
+}

package/src/resolve.ts

@@ -0,0 +1,352 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { isRecord } from "@agentswf/contract";
+import { SANDBOX_ENVIRONMENTS, type SandboxEnvironmentKey } from "@agentswf/contract/workflow";
+import type { Gitdir, ResolvedSandbox, SandboxProviders } from "./seam";
+
+const REACH_KEYS = ["read", "write", "network", "sockets", "webSearch"] as const;
+
+export type SandboxResolution = {
+  /** The environment key the sandbox runs under: the one the spec named, else the default. */
+  provider: SandboxEnvironmentKey;
+  sandbox: ResolvedSandbox<unknown>;
+};
+
+export type ResolveOptions = {
+  key: string;
+  /** What a relative `cwd` resolves against, and the sandbox's `cwd` when the spec names none. */
+  cwd: string;
+  /** Every run's directory: no sandbox path may be or lie inside it, and one holding it hides it. */
+  runRoot: string;
+  /**
+   * What awf keeps per machine, `~/.awf`: every sandbox's homes, with their copied credentials, and
+   * the sessions runs drive. No sandbox path may lie inside it.
+   */
+  machineRoot: string;
+  providers: SandboxProviders;
+  /** An agent's private spec, which may not carry `key` or `cwd`. */
+  inline?: boolean;
+  /** The operator's home, for `~`. */
+  home?: string;
+  /** The operator's harness state, where its environment put it: no sandbox path may overlap it. */
+  harnessState: readonly string[];
+  /**
+   * Where the engine keeps every run's doors: `/tmp`, holding an `awf-*` directory per run. No
+   * sandbox path may contain it, or lie in one of those directories: an agent could rewrite
+   * another agent's launcher, which runs on the host.
+   */
+  controlRoot?: string;
+};
+
+/**
+ * Checks an author's spec the way the types would, since a workflow is untyped at run time, and
+ * resolves its paths once, at open: a sandbox holds what they named then, whatever moves later.
+ */
+export async function resolveSandbox(
+  spec: unknown,
+  options: ResolveOptions,
+): Promise<SandboxResolution> {
+  if (!isRecord(spec)) throw new Error("a sandbox spec must be an object");
+  const allowed = new Set<string>([
+    ...REACH_KEYS,
+    ...SANDBOX_ENVIRONMENTS,
+    ...(options.inline ? [] : ["key", "cwd"]),
+  ]);
+  for (const key of Object.keys(spec)) {
+    if (allowed.has(key)) continue;
+    throw new Error(
+      options.inline && (key === "key" || key === "cwd" || key === "provider")
+        ? `an agent's inline sandbox cannot name ${key}; open a sandbox and pass its ref to share one`
+        : `unknown sandbox field ${JSON.stringify(key)}`,
+    );
+  }
+  const named = SANDBOX_ENVIRONMENTS.filter((key) => spec[key] !== undefined);
+  if (named.length > 1) {
+    throw new Error(`a sandbox has one environment, not ${named.join(" and ")}`);
+  }
+  const provider = named[0] ?? options.providers.default;
+  if (provider === undefined) throw new Error("no sandbox provider is installed");
+  const installed = options.providers.installed[provider];
+  if (!installed) {
+    const why = options.providers.unavailable?.[provider];
+    throw new Error(
+      `the ${provider} sandbox provider is not ${why ? `usable: ${why}` : "installed"}`,
+    );
+  }
+  const environment = installed.environment(named[0] === undefined ? {} : spec[named[0]]);
+
+  const home = await realpath(options.home ?? homedir());
+  const runRoot = await realpath(options.runRoot);
+  const machine = await realpath(options.machineRoot).catch(() => options.machineRoot);
+  const controlRoot =
+    options.controlRoot === undefined
+      ? undefined
+      : await realpath(options.controlRoot).catch(() => options.controlRoot);
+  const harnessState = await Promise.all(
+    options.harnessState.map((path) => realpath(path).catch(() => path)),
+  );
+  const forbidden = (path: string, field: string) => {
+    if (contains(path, home)) throw new Error(`sandbox ${field} ${path} would expose ~`);
+    // A path within the run root would be another run's. One holding it is `hidden`.
+    if (contains(runRoot, path)) {
+      throw new Error(`sandbox ${field} ${path} would expose the run root`);
+    }
+    // Code the host runs and every past transcript (story 004, "A fresh harness home").
+    const state = harnessState.find((root) => contains(path, root) || contains(root, path));
+    if (state) throw new Error(`sandbox ${field} ${path} would expose harness state ${state}`);
+    const keys = KEY_DIRECTORIES.map((name) => join(home, name)).find(
+      (root) => contains(path, root) || contains(root, path),
+    );
+    if (keys) throw new Error(`sandbox ${field} ${path} would expose keys in ${keys}`);
+    if (contains(machine, path))
+      throw new Error(`sandbox ${field} ${path} would expose ${machine}`);
+    if (controlRoot && (contains(path, controlRoot) || insideDoors(controlRoot, path))) {
+      throw new Error(`sandbox ${field} ${path} would expose the engine's doors`);
+    }
+    return path;
+  };
+  const cwd = forbidden(
+    await resolvePath(spec.cwd === undefined ? "." : spec.cwd, options.cwd, home, "cwd"),
+    "cwd",
+  );
+  const paths = (field: "read" | "write" | "sockets") =>
+    Promise.all(
+      list(spec[field], field).map(async (path) =>
+        forbidden(await resolvePath(path, cwd, home, field), field),
+      ),
+    );
+  const write = unique(await paths("write"));
+  const read = unique(await paths("read")).filter((path) => !write.includes(path));
+  const sockets = unique(await paths("sockets"));
+  if (spec.webSearch !== undefined && typeof spec.webSearch !== "boolean") {
+    throw new Error("sandbox webSearch must be true or false");
+  }
+  const network = unique(
+    list(spec.network, "network").map((domain) => {
+      if (!isDomain(domain)) throw new Error(`not a sandbox domain: ${JSON.stringify(domain)}`);
+      return domain.toLowerCase();
+    }),
+  );
+  // The most specific path naming a directory decides whether it is writable.
+  const writableAt = (path: string) => writableIn({ read, write }, path);
+  /** Each gitdir, and whether a writable worktree reaches it as its own or as a linked one's. */
+  const gitdirs = new Map<string, { own: boolean; linked: boolean }>();
+  const add = (repository: Repository, path: string) => {
+    // Writable only when the whole worktree is: `write: ["out"]` must not let an agent move
+    // the repository's branches or stage what the operator commits next.
+    const writable = writableAt(repository.root);
+    repository.gitdirs.forEach((gitdir, index) => {
+      forbidden(gitdir, `gitdir of ${path}`);
+      const via = gitdirs.get(gitdir) ?? { own: false, linked: false };
+      // A linked worktree's common gitdir is its second.
+      if (writable && index === 1) via.linked = true;
+      else if (writable) via.own = true;
+      gitdirs.set(gitdir, via);
+    });
+  };
+  for (const path of [cwd, ...read, ...write]) {
+    const repository = await repositoryOf(path, home);
+    if (repository) add(repository, path);
+  }
+  // A clone inside a writable path is as writable as its hooks: its gitdir is guarded too. One
+  // whose gitdir lies outside is refused, never added: a pointer an earlier agent wrote would
+  // widen the reach to wherever it names. One whose gitdir is gone points nowhere to guard.
+  for (const root of write) {
+    for (const nested of await nestedRepositories(root)) {
+      const repository = await repositoryOf(nested, home).catch(() => undefined);
+      if (!repository) continue;
+      const outside = repository.gitdirs.find((gitdir) => !write.some((w) => contains(w, gitdir)));
+      if (outside) {
+        throw new Error(
+          `sandbox write ${root} holds ${nested}, whose gitdir ${outside} is outside it: write that too, or remove its .git`,
+        );
+      }
+      add(repository, nested);
+    }
+  }
+  // A project keeps its runs in `.awf/runs`: a sandbox holding the project is not refused, and
+  // every provider hides the run root inside it.
+  const holdsRunRoot = [cwd, ...read, ...write, ...gitdirs.keys()].some((path) =>
+    contains(path, runRoot),
+  );
+  return {
+    provider,
+    sandbox: {
+      key: options.key,
+      cwd,
+      read,
+      write,
+      network,
+      sockets,
+      webSearch: spec.webSearch === true,
+      hidden: holdsRunRoot ? [runRoot] : [],
+      gitdirs: [...gitdirs].map(([path, { own, linked }]): Gitdir => {
+        // A submodule's gitdir is in its superproject's `modules`, which is guarded whole: it is
+        // committed in under no provider, whether that superproject is in reach or not.
+        const module =
+          path.includes("/.git/modules/") ||
+          [...gitdirs.keys()].some((other) => contains(join(other, "modules"), path));
+        return {
+          path,
+          writable: (own || linked) && !module,
+          ...(linked && !own && !module ? { linked: true as const } : {}),
+        };
+      }),
+      environment,
+    },
+  };
+}
+
+/**
+ * Whether `path` is writable in this reach: the most specific of `read` and `write` holding it
+ * decides. The working directory is readable, but never more specific than a `write` holding it.
+ */
+export function writableIn(
+  reach: { read: readonly string[]; write: readonly string[] },
+  path: string,
+): boolean {
+  const deepest = [...reach.read, ...reach.write]
+    .filter((root) => contains(root, path))
+    .sort((a, b) => b.length - a.length)[0];
+  return deepest !== undefined && reach.write.includes(deepest);
+}
+
+/** Whether `path` lies in one of the engine's run directories under its control root. */
+function insideDoors(controlRoot: string, path: string): boolean {
+  if (path === controlRoot || !contains(controlRoot, path)) return false;
+  const [first = ""] = path.slice(controlRoot.length + 1).split("/");
+  return first.startsWith("awf-");
+}
+
+/** Whether `path` is `root` or lies under it. Both are absolute and resolved. */
+export function contains(root: string, path: string): boolean {
+  return path === root || path.startsWith(root.endsWith("/") ? root : `${root}/`);
+}
+
+/** Whether an agent at `path` sees it inside: under the sandbox's working directory or its reach. */
+export function withinReach(sandbox: ResolvedSandbox<unknown>, path: string): boolean {
+  return [sandbox.cwd, ...sandbox.read, ...sandbox.write].some((root) => contains(root, path));
+}
+
+/**
+ * `registry.npmjs.org`, or `*.npmjs.org` for its subdomains. The last label is not a number in any
+ * base a resolver reads (`10`, `0x7f000001`), so an address is not a name, and a wildcard needs a
+ * name under a top-level domain, not the domain itself. Anything with a scheme, port or path has
+ * characters no label has.
+ */
+export function isDomain(value: unknown): value is string {
+  if (typeof value !== "string" || value.length > 253) return false;
+  const wildcard = value.startsWith("*.");
+  const labels = (wildcard ? value.slice(2) : value).split(".");
+  return (
+    labels.every((label) => /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/i.test(label)) &&
+    !/^(\d+|0x[0-9a-f]*)$/i.test(labels.at(-1)!) &&
+    (!wildcard || labels.length >= 2)
+  );
+}
+
+/**
+ * Directories under `~` that hold keys, which no sandbox path may include or lie in, under any
+ * provider, nor a toolchain: OrbStack keeps its SSH key apart from its `bin/`.
+ */
+export const KEY_DIRECTORIES = [
+  ".ssh",
+  ".gnupg",
+  ".aws",
+  ".docker",
+  ".kube",
+  ".orbstack/ssh",
+] as const;
+
+/** Directories a writable path is scanned through for repositories, beyond which it is refused. */
+const SCAN_LIMIT = 100_000;
+
+/**
+ * The worktree roots below `root` that hold a `.git`, without entering a `.git`, `node_modules` or
+ * a link. Refuses a tree too large to scan, rather than leave a repository in it unguarded.
+ */
+async function nestedRepositories(root: string): Promise<string[]> {
+  const found: string[] = [];
+  const queue = [root];
+  for (let scanned = 0; queue.length > 0; scanned++) {
+    if (scanned === SCAN_LIMIT) {
+      throw new Error(
+        `sandbox write ${root} holds over ${SCAN_LIMIT} directories to check for repositories; name a narrower one`,
+      );
+    }
+    const directory = queue.pop()!;
+    for (const entry of await readdir(directory, { withFileTypes: true }).catch(() => [])) {
+      if (entry.name === ".git") {
+        if (directory !== root) found.push(directory);
+      } else if (entry.isDirectory() && entry.name !== "node_modules") {
+        queue.push(join(directory, entry.name));
+      }
+    }
+  }
+  return found;
+}
+
+type Repository = { root: string; gitdirs: string[] };
+
+/**
+ * The repository a path belongs to: its worktree's root, and the git directories git reads there,
+ * which may lie outside it: a `.git` directory, or a worktree's own gitdir and its common one.
+ * Read from the files git reads, without running git. The walk up stops below `home`, so a
+ * dotfiles repository at `~` is never the one a path belongs to.
+ */
+export async function repositoryOf(path: string, home: string): Promise<Repository | undefined> {
+  for (let at = path; !contains(at, home); at = dirname(at)) {
+    const dotGit = join(at, ".git");
+    const found = await stat(dotGit).catch(() => undefined);
+    if (found?.isDirectory()) return { root: at, gitdirs: [await realpath(dotGit)] };
+    if (found?.isFile()) {
+      const pointer = /^gitdir:\s*(.+)$/m.exec(await readFile(dotGit, "utf8"))?.[1]?.trim();
+      if (!pointer) throw new Error(`${dotGit} names no gitdir`);
+      const gitdir = await realpath(resolve(at, pointer)).catch(() => {
+        throw new Error(`${dotGit} names ${pointer}, which is gone: git worktree prune`);
+      });
+      const common = await readFile(join(gitdir, "commondir"), "utf8").catch(() => undefined);
+      return {
+        root: at,
+        gitdirs:
+          common === undefined
+            ? [gitdir]
+            : [gitdir, await realpath(resolve(gitdir, common.trim()))],
+      };
+    }
+    if (dirname(at) === at) break;
+  }
+  return undefined;
+}
+
+async function resolvePath(
+  path: unknown,
+  base: string,
+  home: string,
+  field: string,
+): Promise<string> {
+  if (typeof path !== "string" || path.trim() === "") {
+    throw new Error(`sandbox ${field} needs a non-empty path, not ${JSON.stringify(path)}`);
+  }
+  if (path.startsWith("~") && path !== "~" && !path.startsWith("~/")) {
+    throw new Error(`sandbox ${field} ${path}: only ~ and ~/ expand, to the operator's home`);
+  }
+  const expanded = path === "~" ? home : path.startsWith("~/") ? join(home, path.slice(2)) : path;
+  const absolute = isAbsolute(expanded) ? expanded : resolve(base, expanded);
+  try {
+    return await realpath(absolute);
+  } catch {
+    throw new Error(`sandbox ${field} ${path} does not exist`);
+  }
+}
+
+function list(value: unknown, field: string): unknown[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`sandbox ${field} must be a list`);
+  return value;
+}
+
+function unique<T>(values: readonly T[]): T[] {
+  return [...new Set(values)];
+}