omp-conductor 0.3.24 → 0.4.0

package/src/credentials.ts

@@ -0,0 +1,2029 @@
+/**
+ * The credential boundary between the daemon and model-executed code (#125).
+ *
+ * The fact this file exists to fix: until it did, a worker session ran in the
+ * daemon's own process, as the daemon's own user, with the daemon's `$HOME` and
+ * `process.env`. The daemon authenticates by shelling out to the operator's
+ * logged-in `gh`, so a worker's `bash` reached the same credential by running
+ * the same binary. Scrubbing `GH_TOKEN` does not fix that and must never be
+ * described as if it did: same-uid code defeats an environment variable in one
+ * line (`GH_CONFIG_DIR=$HOME/.config/gh gh pr merge`), and the keychain,
+ * `~/.ssh` and `~/.git-credentials` need no environment at all.
+ *
+ * So this module has exactly two jobs, and they are not the same kind of thing:
+ *
+ * 1. **{@link credentialedEnv} — the one construction site of credential
+ *    material in the daemon.** Every privileged spawn (`gh`, the mirror's
+ *    clone/fetch, {@link pushRunBranch}, {@link openRunPr}) goes through it, so
+ *    "which processes can reach the credential" is a list one grep long.
+ * 2. **{@link probeHost} and {@link launcherArgv} — the OS principal.** This is
+ *    the layer that makes the claim true. {@link sessionEnv} sits beside it as
+ *    *convenience and accident-prevention only*; see its own comment.
+ *
+ * Nothing here may describe env scrubbing, or the degraded `group-mode`
+ * mechanism, as containing a determined bash escape. Only `uid-pool` on Linux
+ * and `sandbox-exec` on macOS make that claim, and `status` says which is live.
+ */
+
+import {
+  chmodSync,
+  chownSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+  type Stats,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import {
+  CONDUCTOR_GROUPS,
+  type CredentialIsolation,
+  type IsolationMechanism,
+  type ProjectConfig,
+  type RepoTarget,
+  type SessionRole,
+} from "./types.ts";
+
+/**
+ * Environment variables that carry, or lead to, a write credential. Removed
+ * from every session child.
+ *
+ * The first four are the set #125 names. `NPM_TOKEN`/`NODE_AUTH_TOKEN` are here
+ * because publish credentials are inside the same blast radius — `npm whoami`
+ * failing is one of the issue's acceptance probes — and `GH_HOST` because it
+ * redirects `gh` at an enterprise host whose credential may be configured
+ * separately from github.com's.
+ */
+export const CREDENTIAL_ENV_KEYS = [
+  "GH_TOKEN",
+  "GITHUB_TOKEN",
+  "GH_ENTERPRISE_TOKEN",
+  "GITHUB_ENTERPRISE_TOKEN",
+  "SSH_AUTH_SOCK",
+  "GH_HOST",
+  "NPM_TOKEN",
+  "NODE_AUTH_TOKEN",
+] as const;
+
+/**
+ * A binary that always fails, for `GIT_ASKPASS`/`SSH_ASKPASS` and git's own
+ * `core.askPass`.
+ *
+ * #125 names `/bin/false`, which is right on Linux and **does not exist on
+ * macOS** — there it is `/usr/bin/false`. The difference is not academic: a
+ * missing askpass makes git fail with `cannot exec '/bin/false'`, which happens
+ * to be the outcome we want but reads in a log like a broken conductor rather
+ * than a refused credential. Resolved once so the failure says what it means.
+ */
+const ALWAYS_FAILS = existsSync("/bin/false") ? "/bin/false" : "/usr/bin/false";
+
+/**
+ * The `.gitconfig` a session gets. No credential helper, and `askpass` wired to
+ * a binary that always fails, so an https push cannot silently pick up a helper
+ * the operator configured globally. Fenced and rewritten on every dispatch, the
+ * same way `info/exclude` is, so an older release's file heals itself.
+ */
+const SESSION_GITCONFIG = [
+  "# Written by omp-conductor for one session (#125). Rewritten on every dispatch.",
+  "# Deliberately empty of credential helpers: a session must not be able to",
+  "# reach a credential through git's own configuration. This is the",
+  "# accident-prevention layer — the OS principal is what makes it true.",
+  "[credential]",
+  "\thelper =",
+  "[core]",
+  `\taskPass = ${ALWAYS_FAILS}`,
+  // The run repository borrows its objects from a mirror the DAEMON owns, and
+  // git refuses to touch a repository owned by another uid ("detected dubious
+  // ownership") — which under `uid-pool` is every object read through
+  // alternates. Without this the checkout looks corrupt on the first command,
+  // and the operator is told to run a `git config --global` the session is
+  // deliberately unable to make stick. It is a trust statement about ownership,
+  // not a permission grant: the mirror stays 0750 and unwritable.
+  "[safe]",
+  "\tdirectory = *",
+  "",
+].join("\n");
+
+/**
+ * One process run, captured. Injected everywhere in this module so the probe,
+ * the launcher smoke test and the daemon-side push are all testable without a
+ * privileged host.
+ */
+export type Exec = (
+  argv: readonly string[],
+  opts?: { cwd?: string; env?: Record<string, string>; stdin?: string },
+) => Promise<{ code: number; stdout: string; stderr: string }>;
+
+/** The real one. Never inherits stdin: an unattended daemon must not block on a prompt. */
+export const spawnCaptured: Exec = async (argv, opts = {}) => {
+  const [command, ...rest] = argv;
+  if (command === undefined) return { code: 127, stdout: "", stderr: "empty argv" };
+  const proc = Bun.spawn([command, ...rest], {
+    ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+    ...(opts.env === undefined ? {} : { env: opts.env }),
+    stdin: new Blob([opts.stdin ?? ""]),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, stdout, stderr };
+};
+
+// --------------------------------------------------------------- credentials
+
+/**
+ * The daemon's own environment, credentials intact. **The only place this
+ * package constructs credential material.**
+ *
+ * There is nothing clever in the body, and that is deliberate: the value is
+ * that it is one named function, so "what can reach the operator's `gh`
+ * credential" is answered by its call sites rather than by auditing every
+ * `Bun.spawn` in the tree. A privileged spawn that does not come through here
+ * is a bug, whatever it happens to do.
+ *
+ * `GIT_TERMINAL_PROMPT=0` rides along because every caller is unattended: a
+ * credential prompt nobody can answer is a hang, not a failure.
+ */
+export function credentialedEnv(
+  extra: Readonly<Record<string, string>> = {},
+  base: Readonly<Record<string, string | undefined>> = process.env,
+): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(base)) {
+    if (value !== undefined) env[key] = value;
+  }
+  env["GIT_TERMINAL_PROMPT"] = "0";
+  return { ...env, ...extra };
+}
+
+/** Where one session's private config tree lives. All of it daemon-created. */
+export interface SessionEnvRoot {
+  /** `$HOME` for the child — the agent principal's config root, not the operator's. */
+  home: string;
+  /** `GH_CONFIG_DIR`: exists, is empty, and is not the operator's. */
+  ghConfigDir: string;
+  /** `GIT_CONFIG_GLOBAL`: conductor-owned, no credential helper. */
+  gitConfigGlobal: string;
+  /** `NPM_CONFIG_USERCONFIG`: an empty file, so `~/.npmrc` is not consulted. */
+  npmrc: string;
+  /** `TMPDIR`: inside the boundary, so a sandbox profile can grant it by name. */
+  tmp: string;
+}
+
+/**
+ * Materialise a session's private config tree under `root`.
+ *
+ * `$HOME` is redirected rather than merely scrubbed because the harness
+ * discovers its user-level configuration — including `mcp.json` — from
+ * `os.homedir()`, which reads `$HOME`. Leaving it pointed at the operator's
+ * home is what put a GitHub MCP server carrying its own PAT inside every
+ * session (#125 item 5). The redirect is what makes "the agent principal's
+ * config root" a real directory an operator can populate deliberately.
+ */
+export function prepareSessionEnvRoot(root: string): SessionEnvRoot {
+  const paths: SessionEnvRoot = {
+    home: join(root, "home"),
+    ghConfigDir: join(root, "gh"),
+    gitConfigGlobal: join(root, "gitconfig"),
+    npmrc: join(root, "npmrc"),
+    tmp: join(root, "tmp"),
+  };
+  // 0711 on the root, 0700 on the leaves: a slot principal reaches its own
+  // subtree by traversal and cannot list what else the daemon put here.
+  mkdirSync(root, { recursive: true, mode: 0o711 });
+  for (const dir of [paths.home, paths.ghConfigDir, paths.tmp]) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  writeFileSync(paths.gitConfigGlobal, SESSION_GITCONFIG, { mode: 0o644 });
+  if (!existsSync(paths.npmrc)) writeFileSync(paths.npmrc, "", { mode: 0o644 });
+  return paths;
+}
+
+/**
+ * The environment one session child runs with.
+ *
+ * **This layer is convenience and accident-prevention, not the boundary.** It
+ * stops a well-behaved tool from picking up a credential it was never meant to
+ * see, and it makes the common accidents — `git push` finding a helper, `gh`
+ * finding a config — fail immediately and legibly. It stops nothing that is
+ * trying. Model-executed code running as the same uid re-points every one of
+ * these variables in a single line, and needs none of them to read the
+ * keychain or `~/.ssh`. What makes the claim in #125 true is the OS principal
+ * selected by {@link probeHost} — and when that resolves to `none`, this
+ * function is all there is and `status` says the fleet is unprotected.
+ */
+export function sessionEnv(
+  paths: SessionEnvRoot,
+  opts: { readToken?: string } = {},
+  base: Readonly<Record<string, string | undefined>> = process.env,
+): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(base)) {
+    if (value !== undefined) env[key] = value;
+  }
+  for (const key of CREDENTIAL_ENV_KEYS) delete env[key];
+
+  env["HOME"] = paths.home;
+  env["GH_CONFIG_DIR"] = paths.ghConfigDir;
+  env["GIT_CONFIG_GLOBAL"] = paths.gitConfigGlobal;
+  // Without this a session inherits the *system* gitconfig's helpers, which on
+  // a developer host is where `osxkeychain` usually lives.
+  env["GIT_CONFIG_SYSTEM"] = "/dev/null";
+  env["GIT_CONFIG_NOSYSTEM"] = "1";
+  env["GIT_TERMINAL_PROMPT"] = "0";
+  env["GIT_ASKPASS"] = ALWAYS_FAILS;
+  env["SSH_ASKPASS"] = ALWAYS_FAILS;
+  env["NPM_CONFIG_USERCONFIG"] = paths.npmrc;
+  env["TMPDIR"] = paths.tmp;
+
+  // The one credential a session may be given, and only when an operator
+  // configured it. Read-scoped by construction on GitHub's side — this package
+  // cannot verify the scope, so the README says plainly that a write-scoped
+  // value here reopens the hole the rest of this file closes.
+  if (opts.readToken !== undefined && opts.readToken !== "") {
+    env["GH_TOKEN"] = opts.readToken;
+    env["GITHUB_TOKEN"] = opts.readToken;
+  }
+  return env;
+}
+
+// ------------------------------------------------------------- the principal
+
+/**
+ * One run slot's OS account. `gid`/`group` are the slot's *own* primary group,
+ * never a shared one: the shared group a slot gets back is
+ * {@link CONDUCTOR_GROUPS.runs}, and it is granted through the launcher's
+ * supplementary list rather than by making it anyone's primary.
+ */
+export interface SlotPrincipal {
+  /** Pool index, or `"orch"` for the orchestrator's own distinct account. */
+  slot: string;
+  user: string;
+  uid: number;
+  gid: number;
+  group: string;
+}
+
+/** Everything one session child needs to be launched behind the boundary. */
+export interface SessionBoundary {
+  mechanism: IsolationMechanism;
+  /** argv prefix that drops privilege. Empty for `group-mode` and `none`. */
+  launcher: string[];
+  /** Environment overrides for the child (see {@link sessionEnv}). */
+  env: Record<string, string>;
+  /** Present only when the mechanism gives this run a distinct uid. */
+  principal?: SlotPrincipal;
+}
+
+/**
+ * The privilege-dropping launcher, composed exactly once.
+ *
+ * **Never `spawn({ uid, gid })`.** Granting the daemon ambient
+ * `CAP_SETUID`/`CAP_SETGID` and calling a raw spawn looks identical from the
+ * outside and voids the entire boundary: ambient capabilities survive `execve`
+ * for ordinary binaries, so the child holds `CAP_SETUID` itself and can
+ * `setuid()` straight back — to the daemon, or to a sibling run. `setpriv` is
+ * preferred over a hand-rolled helper for the same reason one uses `sudo`
+ * instead of a setuid shell script: it is audited, and it does the five steps
+ * in the order that makes them stick (groups, gid, uid, empty every capability
+ * set, `PR_SET_NO_NEW_PRIVS`, then exec).
+ *
+ * Two flag traps, both of which fail *before* exec and so read like a broken
+ * conductor rather than a permissions problem:
+ *
+ * - `--clear-groups`, `--groups`, `--keep-groups` and `--init-groups` are
+ *   mutually exclusive. `--clear-groups --groups conductor-runs` exits non-zero
+ *   before running anything. `--groups` alone already *replaces* the inherited
+ *   list, which is the wanted behaviour, so it is used alone.
+ * - The one group granted back is the read-only mirror group. Omit it and the
+ *   child cannot read the shared mirror, so git alternates fail with a
+ *   permission error that reads like a corrupt object store.
+ *
+ * `--bounding-set=-all` performs `PR_CAPBSET_DROP`, which needs `CAP_SETPCAP`
+ * in the *caller's* permitted set. When the host did not grant it the flag is
+ * omitted rather than attempted: with every other set empty, an unprivileged
+ * uid and `NoNewPrivs: 1`, the child cannot acquire anything in the bounding
+ * set, so the leftover `CapBnd` is inert — and reported by `status` as a named
+ * residual instead of quietly ignored.
+ */
+export function setprivArgv(
+  principal: SlotPrincipal,
+  opts: { boundingSet: boolean; sharedGroup?: string | false },
+  command: readonly string[],
+): string[] {
+  // `false` means "no supplementary group at all", which is the orchestrator's
+  // case: it never reads the shared mirror, so granting it `conductor-runs`
+  // would hand it the one residual the design says it does not get. Expressed
+  // as `--clear-groups`, which is valid alone and is mutually exclusive with
+  // `--groups` — passing both aborts before exec.
+  const groups = opts.sharedGroup === false ? "--clear-groups" : `--groups=${opts.sharedGroup ?? CONDUCTOR_GROUPS.runs}`;
+  return [
+    "setpriv",
+    `--reuid=${principal.user}`,
+    `--regid=${principal.group}`,
+    groups,
+    "--inh-caps=-all",
+    "--ambient-caps=-all",
+    ...(opts.boundingSet ? ["--bounding-set=-all"] : []),
+    "--no-new-privs",
+    "--",
+    ...command,
+  ];
+}
+
+
+/**
+ * The exact, idempotent root commands that build the `uid-pool` topology.
+ *
+ * Shipped rather than documented, and generated rather than duplicated: the
+ * probe, the dispatch-time refusals and this script have to agree about account
+ * names, group names, modes and the shared root, and three prose copies of that
+ * would drift the first time one of them changed. `omp-conductor boundary-setup`
+ * prints it; CI runs the same output. Nothing here runs automatically — it
+ * creates system accounts, so it is the operator's call and their `sudo`.
+ *
+ * Printed rather than executed for the same reason `graph-setup` prints: an
+ * operator gets to read what will touch their box before it does.
+ */
+/**
+ * Credential paths inside the daemon's home, relative.
+ *
+ * One list, two consumers: the generated hardening chmods them, and
+ * `credentialDenyFiles()` builds the empirical recheck from the same names. A
+ * path hardened but not probed is a credential nobody verified was out of
+ * reach — which is exactly how `.gitconfig` (and its `url.*.insteadOf` inline
+ * tokens) was chmod-ed while dispatch still reported clean.
+ */
+export const CREDENTIAL_DIRS = [".ssh", ".config/gh", ".gnupg", ".aws"] as const;
+export const CREDENTIAL_FILES = [
+  ".npmrc",
+  ".git-credentials",
+  ".netrc",
+  ".gitconfig",
+  ".config/git/config",
+] as const;
+
+export function boundarySetupScript(opts: { slots: number; sharedRoot: string; daemonUser: string }): string {
+  const slots = Array.from({ length: opts.slots }, (_, i) => `${DEFAULT_ACCOUNT_PREFIX}${String(i)}`);
+  const accounts = [...slots, `${DEFAULT_ACCOUNT_PREFIX}orch`];
+  const q = (s: string): string => JSON.stringify(s);
+  return [
+    "#!/usr/bin/env bash",
+    "# Generated by `omp-conductor boundary-setup`. Idempotent; run as root.",
+    "set -euo pipefail",
+    "",
+    `DAEMON_USER=${q(opts.daemonUser)}`,
+    `SHARED_ROOT=${q(opts.sharedRoot)}`,
+    "",
+    "# Two groups: one the daemon alone holds (so it can fetch, salvage and",
+    "# reclaim every run repo), one every slot holds (read-only mirror access).",
+    `getent group ${CONDUCTOR_GROUPS.daemon} >/dev/null || groupadd --system ${CONDUCTOR_GROUPS.daemon}`,
+    `getent group ${CONDUCTOR_GROUPS.runs} >/dev/null || groupadd --system ${CONDUCTOR_GROUPS.runs}`,
+    "",
+    ...accounts.flatMap((user) => [
+      `id ${user} >/dev/null 2>&1 || useradd --system --no-create-home --shell /usr/sbin/nologin --user-group ${user}`,
+      `usermod -aG ${CONDUCTOR_GROUPS.runs} ${user}`,
+      `# A slot in the daemon group would reach every other run's repo.`,
+      `gpasswd -d ${user} ${CONDUCTOR_GROUPS.daemon} >/dev/null 2>&1 || true`,
+    ]),
+    "",
+    `usermod -aG ${CONDUCTOR_GROUPS.daemon} "$DAEMON_USER"`,
+    `usermod -aG ${CONDUCTOR_GROUPS.runs} "$DAEMON_USER"`,
+    "",
+    "# Searchable, unlistable, unwritable — a slot reaches its own tree and",
+    "# cannot enumerate its siblings.",
+    'mkdir -p "$SHARED_ROOT"',
+    `chown "$DAEMON_USER":${CONDUCTOR_GROUPS.daemon} "$SHARED_ROOT"`,
+    'chmod 0711 "$SHARED_ROOT"',
+    "",
+    "# The daemon's home must be BOTH searchable and closed: the runtime and the",
+    "# installed package live in it, so 0700 kills every worker before it starts,",
+    "# while the credential leaves are what the boundary actually rests on.",
+    'DAEMON_HOME="$(getent passwd "$DAEMON_USER" | cut -d: -f6)"',
+    'if [ -n "$DAEMON_HOME" ] && [ -d "$DAEMON_HOME" ]; then',
+    '  chmod 0711 "$DAEMON_HOME"',
+    `  for d in ${CREDENTIAL_DIRS.join(" ")}; do [ -d "$DAEMON_HOME/$d" ] && chmod 0700 "$DAEMON_HOME/$d"; done`,
+    `  for f in ${CREDENTIAL_FILES.join(" ")}; do [ -f "$DAEMON_HOME/$f" ] && chmod 0600 "$DAEMON_HOME/$f"; done`,
+    "fi",
+    "",
+    'echo "boundary provisioned. Supplementary groups apply to NEW processes:"',
+    'echo "  systemctl restart omp-conductor.service"',
+    "",
+  ].join("\n");
+}
+
+/**
+ * Ask the slot principal itself whether it can read any credential path, and
+ * refuse the boundary if it can.
+ *
+ * This is the difference between the claim and the wish. On macOS the
+ * `sandbox-exec` profile carries `denyReadRoots`/`denyReadFiles` and enforces
+ * them; on Linux `uid-pool` carries no such list — separation is DAC, and DAC
+ * is the *operator's* file modes, which nothing in this package chose. A home
+ * directory is commonly `0755`, `~/.npmrc` and `~/.gitconfig` commonly `0644`,
+ * and an inline token in either is then readable by every slot uid on the box.
+ * The boundary would report `uid-pool` and be wide open.
+ *
+ * So the check is empirical and runs as the principal: `test -r` through the
+ * real launcher, so ACLs, setgid and anything else the kernel honours all
+ * count. Anything readable is named and the mechanism refuses rather than
+ * resolving down quietly — a credential the model can read is the whole thing
+ * #125 exists to prevent.
+ */
+export async function credentialReadRefusal(
+  exec: Exec,
+  principal: SlotPrincipal,
+  opts: { boundingSet: boolean; sharedGroup?: string | false },
+  paths: readonly string[],
+): Promise<string | undefined> {
+  if (paths.length === 0) return undefined;
+  const q = (s: string): string => JSON.stringify(s);
+  // A directory leaks on **search**, not just read. With `$HOME` at 0711 a
+  // drifted `.ssh` at 0711 defeats `[ -r dir ]` and `ls` while
+  // `cat ~/.ssh/id_ed25519` still works, because reaching a known leaf needs
+  // only `+x` on the way down. So directories are tested for either bit, and
+  // the well-known leaves are additionally opened by exact path — which is what
+  // an attacker does, and what a listing-based check never notices.
+  const LEAVES: Record<string, readonly string[]> = {
+    ".ssh": ["id_rsa", "id_ed25519", "id_ecdsa", "id_dsa"],
+    "gh": ["hosts.yml"],
+    "git": ["config"],
+  };
+  const lines: string[] = [];
+  for (const p of paths) {
+    lines.push(`if [ -d ${q(p)} ]; then [ -r ${q(p)} ] || [ -x ${q(p)} ]; else [ -r ${q(p)} ]; fi && printf '%s\\n' ${q(p)}`);
+    const base = p.split("/").pop() ?? "";
+    for (const leaf of LEAVES[base] ?? []) {
+      const full = `${p}/${leaf}`;
+      lines.push(`[ -r ${q(full)} ] && printf '%s\\n' ${q(full)}`);
+    }
+  }
+  // `CHECKED` is the proof the launcher actually ran. Without it a `setpriv`
+  // the host rejects exits nonzero with empty stdout, which is indistinguishable
+  // from "nothing was readable" — the one wrong answer this function must never
+  // give. Absence is a refusal, not a pass.
+  const script = `${lines.join("; ")}; printf 'CHECKED\\n'`;
+  const out = await exec(setprivArgv(principal, opts, ["/bin/sh", "-c", script]));
+  const seen = out.stdout.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+  if (!seen.includes("CHECKED")) {
+    return (
+      `the credential readability check could not be run as ${principal.user} (launcher exited ` +
+      `${String(out.code)}: ${out.stderr.trim() || "no output"}). Refusing rather than assuming the ` +
+      `credentials are out of reach.`
+    );
+  }
+  const readable = seen.filter((l) => l !== "CHECKED");
+  if (readable.length === 0) return undefined;
+  return (
+    `${principal.user} can reach ${String(readable.length)} credential path(s) the boundary claims to ` +
+    `deny: ${readable.join(", ")}. On Linux the per-run principal separates by file permissions only, so a ` +
+    `world-readable file — or a merely *searchable* credential directory — defeats it entirely. Tighten ` +
+    `those paths (0600 files, 0700 credential directories) and restart.`
+  );
+}
+
+/**
+ * A macOS sandbox profile whose only writable paths are this run's own tree.
+ *
+ * Shaped as allow-default plus targeted denials rather than deny-default plus
+ * allowances, and that is not laziness: a deny-default profile has to enumerate
+ * every dyld cache, sysctl and mach service the harness and its toolchain
+ * touch, and the failure mode when it misses one is `SIGABRT` at exec with no
+ * diagnostic — measured on this host while developing #125. The write rule is
+ * still a whitelist (`deny file-write*` then allow the run's tree), which is
+ * the property the issue asks for; the read denials are what make the
+ * credential paths unreachable.
+ *
+ * Paths must be *resolved* — `/tmp` is a symlink to `/private/tmp` and a rule
+ * naming the symlink matches nothing, which silently produces a profile that
+ * denies the writes it meant to allow.
+ */
+export function sandboxProfile(input: {
+  writeRoots: readonly string[];
+  denyReadRoots: readonly string[];
+  denyReadFiles: readonly string[];
+}): string {
+  const subpaths = (values: readonly string[]): string =>
+    values.map((v) => `(subpath ${JSON.stringify(v)})`).join(" ");
+  const literals = (values: readonly string[]): string =>
+    values.map((v) => `(literal ${JSON.stringify(v)})`).join(" ");
+  return [
+    "(version 1)",
+    ";; omp-conductor per-run profile (#125). Regenerated per dispatch.",
+    "(allow default)",
+    ";; Writable: this run's checkout and its own scratch, and nothing else.",
+    "(deny file-write*)",
+    `(allow file-write* ${subpaths(input.writeRoots)} ` +
+      `(literal "/dev/null") (literal "/dev/stdout") (literal "/dev/stderr") ` +
+      `(literal "/dev/dtracehelper") (regex #"^/dev/tty"))`,
+    ";; The credential paths an environment variable cannot hide, plus the",
+    ";; sibling run checkouts — cross-run separation on macOS is the profile's",
+    ";; job, because sandbox-exec does not change the uid.",
+    ...(input.denyReadRoots.length === 0 && input.denyReadFiles.length === 0
+      ? []
+      : [
+          `(deny file-read* ${subpaths(input.denyReadRoots)}${
+            input.denyReadFiles.length === 0 ? "" : ` ${literals(input.denyReadFiles)}`
+          })`,
+        ]),
+    ";; Last, so it outranks the denials above: a run must still be able to read",
+    ";; its OWN checkout even when the workspace root that contains it is denied",
+    ";; wholesale. SBPL takes the last matching rule, so ordering is the grant.",
+    `(allow file-read* ${subpaths(input.writeRoots)})`,
+    ";; The login keychain, which is reached over mach and not through the filesystem.",
+    '(deny mach-lookup (global-name "com.apple.SecurityServer") ' +
+      '(global-name "com.apple.securityd") (global-name "com.apple.securityd.xpc"))',
+    "",
+  ].join("\n");
+}
+
+/** `sandbox-exec` prefix for an already-written profile. */
+export function sandboxExecArgv(profilePath: string, command: readonly string[]): string[] {
+  return ["sandbox-exec", "-f", profilePath, ...command];
+}
+
+// -------------------------------------------------------- capability probing
+
+/** The five capability sets and the one flag that makes an empty set stick. */
+export interface CapabilityState {
+  prm: string;
+  eff: string;
+  inh: string;
+  amb: string;
+  bnd: string;
+  noNewPrivs: number;
+  uid?: number;
+  gid?: number;
+}
+
+const CAP_FIELDS: Record<string, keyof CapabilityState> = {
+  CapPrm: "prm",
+  CapEff: "eff",
+  CapInh: "inh",
+  CapAmb: "amb",
+  CapBnd: "bnd",
+};
+
+/**
+ * Parse `/proc/<pid>/status`. Pure, so the acceptance assertions in #125 can be
+ * pinned against a captured fixture as well as run live inside a worker.
+ *
+ * Returns `undefined` on a kernel that reports no capability fields at all
+ * (and on macOS, where there is no procfs) — an absence the caller must handle
+ * as "cannot assert", never as "all clear".
+ */
+export function parseProcStatusCaps(text: string): CapabilityState | undefined {
+  const caps: Partial<CapabilityState> = { noNewPrivs: 0 };
+  let sawCap = false;
+  for (const line of text.split("\n")) {
+    const sep = line.indexOf(":");
+    if (sep === -1) continue;
+    const key = line.slice(0, sep);
+    const value = line.slice(sep + 1).trim();
+    const field = CAP_FIELDS[key];
+    if (field !== undefined) {
+      (caps as Record<string, unknown>)[field] = value;
+      sawCap = true;
+      continue;
+    }
+    if (key === "NoNewPrivs") caps.noNewPrivs = Number.parseInt(value, 10) || 0;
+    // "Uid:\treal\teffective\tsaved\tfs" — the effective id is the one that
+    // decides what this process may open, so it is the one asserted.
+    if (key === "Uid" || key === "Gid") {
+      const parts = value.split(/\s+/);
+      const effective = Number.parseInt(parts[1] ?? parts[0] ?? "", 10);
+      if (Number.isFinite(effective)) {
+        if (key === "Uid") caps.uid = effective;
+        else caps.gid = effective;
+      }
+    }
+  }
+  if (!sawCap) return undefined;
+  return {
+    prm: caps.prm ?? "",
+    eff: caps.eff ?? "",
+    inh: caps.inh ?? "",
+    amb: caps.amb ?? "",
+    bnd: caps.bnd ?? "",
+    noNewPrivs: caps.noNewPrivs ?? 0,
+    ...(caps.uid === undefined ? {} : { uid: caps.uid }),
+    ...(caps.gid === undefined ? {} : { gid: caps.gid }),
+  };
+}
+
+/** True for `0000000000000000` and any other all-zero spelling of an empty set. */
+function emptyCapSet(value: string): boolean {
+  return value !== "" && /^0+$/.test(value);
+}
+
+/** Does a capability mask contain a given bit? `CAP_SETPCAP` is 8, `CAP_SETUID` 7. */
+export function hasCapability(mask: string, bit: number): boolean {
+  if (mask === "") return false;
+  let value: bigint;
+  try {
+    value = BigInt(`0x${mask}`);
+  } catch {
+    return false;
+  }
+  return (value & (1n << BigInt(bit))) !== 0n;
+}
+
+export const CAP_SETGID = 6;
+export const CAP_SETUID = 7;
+export const CAP_SETPCAP = 8;
+export const CAP_CHOWN = 0;
+/**
+ * Needed because `applyRunOwnership` chowns a tree to the slot principal and
+ * only then chmods it — at which point the daemon is no longer the owner, and
+ * membership in `conductor-daemon` does not authorise `chmod`. Reordering does
+ * not help: `chown` clears the setgid bit, so the `g+s` that makes the group
+ * inheritable has to come after it. Without this capability the very first
+ * ownership handoff fails EPERM, and only a root CI run hides it.
+ */
+export const CAP_FOWNER = 3;
+
+/**
+ * Everything wrong with a session child's capability state, as a list of
+ * sentences. Empty means the child is as unprivileged as this host allows.
+ *
+ * `boundingSetDropped` is the probe's own answer, not a guess: when the host
+ * refused `CAP_SETPCAP` a non-empty `CapBnd` is the documented residual rather
+ * than a failure, and asserting it unconditionally would turn a correctly
+ * configured fallback host into a red build.
+ */
+export function capabilityViolations(
+  caps: CapabilityState,
+  opts: { boundingSetDropped: boolean },
+): string[] {
+  const wrong: string[] = [];
+  for (const [name, value] of [
+    ["CapPrm", caps.prm],
+    ["CapEff", caps.eff],
+    ["CapInh", caps.inh],
+    ["CapAmb", caps.amb],
+  ] as const) {
+    if (!emptyCapSet(value)) wrong.push(`${name} is ${value || "(absent)"}, expected all zero`);
+  }
+  if (opts.boundingSetDropped && !emptyCapSet(caps.bnd)) {
+    wrong.push(`CapBnd is ${caps.bnd || "(absent)"}, expected all zero on a host granting CAP_SETPCAP`);
+  }
+  if (caps.noNewPrivs !== 1) wrong.push(`NoNewPrivs is ${String(caps.noNewPrivs)}, expected 1`);
+  return wrong;
+}
+
+/** A POSIX identity as `id(1)` reports it. */
+export interface Identity {
+  uid: number;
+  user: string;
+  gid: number;
+  group: string;
+  groups: { id: number; name: string }[];
+}
+
+const ID_PART = /^(uid|gid)=(\d+)\(([^)]*)\)$/;
+
+/**
+ * Parse `id` output. Pure, because the identity assertion in #125 is
+ * "the *whole* identity, not just an absence" — a test that only checks
+ * `conductor-daemon` is missing also passes a launcher that forgot to replace
+ * the supplementary list at all, which is the bug it exists to catch.
+ */
+export function parseIdOutput(text: string): Identity | undefined {
+  const fields = text.trim().split(/\s+/);
+  let uid: number | undefined;
+  let user = "";
+  let gid: number | undefined;
+  let group = "";
+  const groups: { id: number; name: string }[] = [];
+  for (const field of fields) {
+    const simple = ID_PART.exec(field);
+    if (simple !== null) {
+      const value = Number.parseInt(simple[2] ?? "", 10);
+      if (simple[1] === "uid") {
+        uid = value;
+        user = simple[3] ?? "";
+      } else {
+        gid = value;
+        group = simple[3] ?? "";
+      }
+      continue;
+    }
+    if (!field.startsWith("groups=")) continue;
+    for (const entry of field.slice("groups=".length).split(",")) {
+      const m = /^(\d+)\(([^)]*)\)$/.exec(entry);
+      if (m === null) continue;
+      groups.push({ id: Number.parseInt(m[1] ?? "", 10), name: m[2] ?? "" });
+    }
+  }
+  if (uid === undefined || gid === undefined) return undefined;
+  return { uid, user, gid, group, groups };
+}
+
+/**
+ * Everything wrong with a launched child's identity. Pins all three facts the
+ * spec calls for: the uid is the slot principal, the gid is that slot's *own*
+ * primary group, and the supplementary list is exactly the shared runs group.
+ */
+export function identityViolations(
+  actual: Identity,
+  expected: { principal: SlotPrincipal; sharedGroup?: string },
+): string[] {
+  const shared = expected.sharedGroup ?? CONDUCTOR_GROUPS.runs;
+  const wrong: string[] = [];
+  if (actual.uid !== expected.principal.uid) {
+    wrong.push(`uid is ${String(actual.uid)}, expected ${String(expected.principal.uid)} (${expected.principal.user})`);
+  }
+  if (actual.gid !== expected.principal.gid) {
+    wrong.push(
+      `gid is ${String(actual.gid)}, expected ${String(expected.principal.gid)} (${expected.principal.group})`,
+    );
+  }
+  // The slot's own primary group reappears in `groups=` on every libc; the
+  // shared runs group is the only *additional* member allowed.
+  const extra = actual.groups
+    .map((g) => g.name)
+    .filter((name) => name !== shared && name !== expected.principal.group);
+  if (extra.length > 0) {
+    wrong.push(`supplementary groups include ${extra.join(", ")}, expected only ${shared}`);
+  }
+  if (!actual.groups.some((g) => g.name === shared)) {
+    wrong.push(`not a member of ${shared} — the child cannot read the shared mirror`);
+  }
+  if (actual.groups.some((g) => g.name === CONDUCTOR_GROUPS.daemon)) {
+    wrong.push(`is a member of ${CONDUCTOR_GROUPS.daemon} — that group is what keeps sibling runs out`);
+  }
+  return wrong;
+}
+
+// ---------------------------------------------------------------- host probe
+
+/** What this host can actually enforce, decided once at daemon startup. */
+export interface HostProbe {
+  mechanism: IsolationMechanism;
+  /**
+   * Why the stronger mechanisms were unavailable, in probe order. Read by the
+   * refusal message so an operator who asked for `per-run` on a host that
+   * cannot do it is told the missing piece rather than "isolation unavailable".
+   */
+  reasons: string[];
+  /** Real, named weaknesses of the mechanism that *was* selected. */
+  residuals: string[];
+  /** Whether the launcher may pass `--bounding-set=-all`. See {@link setprivArgv}. */
+  boundingSetDropped: boolean;
+  /** Worker slot principals, one per concurrent slot. Empty unless `uid-pool`. */
+  slots: SlotPrincipal[];
+  /** The orchestrator's own distinct account. Absent unless `uid-pool`. */
+  orchestrator?: SlotPrincipal;
+  /**
+   * The resolved `conductor-runs` gid, so the mirror can be handed the group
+   * every slot principal reads it through. Absent when the group is not
+   * defined, which is also why the mechanism is never `uid-pool` then.
+   */
+  runsGid?: number;
+  /**
+   * The resolved `conductor-daemon` gid. Carried rather than taken from the
+   * daemon's own `egid`, which is a different group entirely: the shipped unit
+   * runs `User=fleet`/`Group=fleet` with `conductor-daemon` only supplementary,
+   * so `egid` is `fleet` and handing that to {@link applyRunOwnership} would
+   * make every run repo `<slot>:fleet` — not the documented layout, readable by
+   * anyone else in `fleet`, and validated by a probe that checked a group the
+   * modes never used.
+   */
+  daemonGid?: number;
+}
+
+export interface ProbeOptions {
+  /** How many worker slots to provision principals for (`maxConcurrentWorkers`). */
+  slots: number;
+  platform?: NodeJS.Platform;
+  exec?: Exec;
+  /** `/proc/self/status` text for the daemon itself. Injected for tests. */
+  selfStatus?: () => string | undefined;
+  /** Prefix for slot account names. Pinned by the provisioning docs. */
+  accountPrefix?: string;
+  /**
+   * The daemon's own live credentials. Injected so the membership decision can
+   * be tested on a host that has neither conductor group; production reads the
+   * running process, which is the whole point (see {@link daemonGroupViolations}).
+   */
+  credentials?: () => DaemonCredentials;
+}
+
+/** This process's real group credentials, as the kernel sees them right now. */
+export function liveDaemonCredentials(): DaemonCredentials {
+  return {
+    egid: typeof process.getegid === "function" ? process.getegid() : -1,
+    groups: typeof process.getgroups === "function" ? process.getgroups() : [],
+  };
+}
+
+const DEFAULT_ACCOUNT_PREFIX = "conductor-agent-";
+
+function readSelfStatus(): string | undefined {
+  try {
+    return readFileSync("/proc/self/status", "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The daemon's own *live* credentials. Read from the running process, never
+ * from the passwd/group database — see {@link daemonGroupViolations}.
+ */
+export interface DaemonCredentials {
+  egid: number;
+  groups: readonly number[];
+}
+
+/** `getent group` output → gid, or `undefined` when the group is not defined. */
+export function parseGetentGid(output: string, group: string): number | undefined {
+  for (const line of output.split("\n")) {
+    const parts = line.split(":");
+    if (parts[0] !== group) continue;
+    const gid = Number.parseInt(parts[2] ?? "", 10);
+    if (Number.isFinite(gid)) return gid;
+  }
+  return undefined;
+}
+
+/**
+ * Why this daemon must not be reported as `uid-pool`, from its own credentials.
+ *
+ * **Existence is not membership, and this distinction can brick a fleet
+ * silently.** `getent group conductor-daemon` succeeds on a host where the
+ * daemon account is not in the group at all; the probe then reports `uid-pool`,
+ * the daemon chowns every run repo to `<slot>:conductor-daemon 2770`, and locks
+ * *itself* out of push, salvage and reclaim — after ownership handoff, which is
+ * the point of no return. The symptom is unexplained permission errors at the
+ * next settle, not a probe failure.
+ *
+ * It is not a hypothetical either: supplementary group membership is fixed when
+ * a process starts, so `usermod -aG conductor-daemon fleet` without a service
+ * restart leaves a live daemon whose credentials lack the group while every
+ * database check passes. That is the ordinary upgrade path.
+ *
+ * Pure, and takes the group list as data, so the decision is testable on a host
+ * that has neither group.
+ *
+ * Note what is *not* checked here: whether each slot principal is really in
+ * `conductor-runs`. That cannot be read from this process's credentials, and
+ * the database would be the same weak evidence this function exists to reject —
+ * so it is proven instead by the launcher smoke test, which reads the identity
+ * a real launched child actually ends up with.
+ */
+export function daemonGroupViolations(
+  creds: DaemonCredentials,
+  resolved: { daemonGid?: number; runsGid?: number },
+): string[] {
+  const wrong: string[] = [];
+  const member = (gid: number): boolean => creds.egid === gid || creds.groups.includes(gid);
+
+  if (resolved.daemonGid === undefined) {
+    wrong.push(`group ${CONDUCTOR_GROUPS.daemon} is not defined on this host`);
+  } else if (!member(resolved.daemonGid)) {
+    wrong.push(
+      `the daemon is not an effective member of ${CONDUCTOR_GROUPS.daemon} (gid ` +
+        `${String(resolved.daemonGid)}) — it would chown every run repo to a group it cannot use, and lock ` +
+        `itself out of push, salvage and reclaim. Supplementary groups are fixed at process start: run ` +
+        `\`usermod -aG ${CONDUCTOR_GROUPS.daemon} <daemon-account>\` and RESTART the service.`,
+    );
+  }
+  if (resolved.runsGid === undefined) {
+    wrong.push(`group ${CONDUCTOR_GROUPS.runs} is not defined on this host`);
+  }
+  return wrong;
+}
+
+/** Resolve one slot account to its numeric ids, or say why it could not be. */
+async function resolvePrincipal(
+  exec: Exec,
+  slot: string,
+  user: string,
+): Promise<{ principal: SlotPrincipal } | { missing: string }> {
+  const id = await exec(["id", user]);
+  if (id.code !== 0) return { missing: `account ${user} does not exist` };
+  const parsed = parseIdOutput(id.stdout);
+  if (parsed === undefined) return { missing: `could not read the identity of ${user}` };
+  return {
+    principal: { slot, user, uid: parsed.uid, gid: parsed.gid, group: parsed.group },
+  };
+}
+
+/**
+ * Decide the mechanism, then **prove it** before reporting it available.
+ *
+ * The smoke test is the part that is not optional. A mechanism whose launcher
+ * argv the host rejects — a `setpriv` too old for `--no-new-privs`, a slot
+ * account the daemon may not become, a mutually-exclusive group flag — looks
+ * exactly like an available mechanism at startup and then fails *every*
+ * dispatch at run time, which is the worst way to learn it. So the composed
+ * argv is run against `id` and the resulting identity is checked; anything
+ * short of the expected identity resolves the mechanism down rather than
+ * leaving a fleet that cannot dispatch.
+ */
+export async function probeHost(opts: ProbeOptions): Promise<HostProbe> {
+  const exec = opts.exec ?? spawnCaptured;
+  const platform = opts.platform ?? process.platform;
+  const prefix = opts.accountPrefix ?? DEFAULT_ACCOUNT_PREFIX;
+  const credentials = opts.credentials ?? liveDaemonCredentials;
+  const reasons: string[] = [];
+
+  if (platform === "darwin") return probeDarwin(exec, reasons);
+  if (platform !== "linux") {
+    reasons.push(`${platform} has no supported per-run isolation mechanism`);
+    return { mechanism: "none", reasons, residuals: [], boundingSetDropped: false, slots: [] };
+  }
+
+  const status = (opts.selfStatus ?? readSelfStatus)();
+  const caps = status === undefined ? undefined : parseProcStatusCaps(status);
+  const root = caps?.uid === 0;
+  const canSetuid = root || (caps !== undefined && hasCapability(caps.prm, CAP_SETUID) && hasCapability(caps.prm, CAP_SETGID));
+  // Ownership handoff needs both: CAP_CHOWN to give the tree away, CAP_FOWNER
+  // to keep chmod-ing it afterwards. Probed rather than assumed, because the
+  // failure lands at the first dispatch's point of no return.
+  const canOwn =
+    root || (caps !== undefined && hasCapability(caps.prm, CAP_CHOWN) && hasCapability(caps.prm, CAP_FOWNER));
+  const boundingSetDropped = root || (caps !== undefined && hasCapability(caps.prm, CAP_SETPCAP));
+
+  const setpriv = await exec(["setpriv", "--help"]);
+  const haveSetpriv = setpriv.code === 0;
+
+  if (!canOwn) {
+    reasons.push(
+      "the daemon holds neither CAP_CHOWN nor CAP_FOWNER in its permitted set — it could hand a run tree to " +
+        "its slot principal and then be unable to chmod it, failing at the point of no return. Add " +
+        "AmbientCapabilities=CAP_SETUID CAP_SETGID CAP_CHOWN CAP_FOWNER CAP_SETPCAP to the unit",
+    );
+  }
+  if (!canSetuid) {
+    reasons.push(
+      "the daemon holds neither CAP_SETUID nor CAP_SETGID in its permitted set — " +
+        "add AmbientCapabilities=CAP_SETUID CAP_SETGID CAP_CHOWN CAP_FOWNER CAP_SETPCAP to the unit",
+    );
+  }
+  if (!haveSetpriv) {
+    reasons.push(
+      "setpriv (util-linux) is not on PATH — a raw spawn({uid,gid}) is deliberately not a fallback, " +
+        "because a child launched that way can hold CAP_SETUID and setuid() back",
+    );
+  }
+
+  if (canSetuid && canOwn && haveSetpriv) {
+    const slots: SlotPrincipal[] = [];
+    let unresolved: string | undefined;
+    for (let i = 0; i < opts.slots; i += 1) {
+      const found = await resolvePrincipal(exec, String(i), `${prefix}${String(i)}`);
+      if ("missing" in found) {
+        unresolved = found.missing;
+        break;
+      }
+      slots.push(found.principal);
+    }
+    const orch = unresolved === undefined ? await resolvePrincipal(exec, "orch", `${prefix}orch`) : undefined;
+    if (orch !== undefined && "missing" in orch) unresolved = orch.missing;
+
+    if (unresolved !== undefined) {
+      reasons.push(`${unresolved} — provision the slot accounts as described in the README`);
+    } else if (orch !== undefined && "principal" in orch) {
+      const groups = await exec(["getent", "group", CONDUCTOR_GROUPS.daemon, CONDUCTOR_GROUPS.runs]);
+      // The database answers "does the group exist"; the running process
+      // answers "may this daemon use it". Only the second one is load-bearing.
+      const wrongGroups = daemonGroupViolations(credentials(), {
+        ...(parseGetentGid(groups.stdout, CONDUCTOR_GROUPS.daemon) === undefined
+          ? {}
+          : { daemonGid: parseGetentGid(groups.stdout, CONDUCTOR_GROUPS.daemon) }),
+        ...(parseGetentGid(groups.stdout, CONDUCTOR_GROUPS.runs) === undefined
+          ? {}
+          : { runsGid: parseGetentGid(groups.stdout, CONDUCTOR_GROUPS.runs) }),
+      });
+      if (wrongGroups.length > 0) {
+        // Without both groups the layout either locks the daemon out of the run
+        // repos it must fetch and reclaim, or lets the runs into each other's.
+        reasons.push(...wrongGroups);
+      } else {
+        const smoke = await smokeTestLauncher(exec, slots[0] ?? orch.principal, boundingSetDropped);
+        if (smoke === undefined) {
+          return {
+            mechanism: "uid-pool",
+            reasons,
+            residuals: boundingSetDropped
+              ? []
+              : [
+                  "CAP_SETPCAP was not granted, so the child's capability bounding set is not emptied. " +
+                    "It is inert — NoNewPrivs blocks both routes to acquiring anything in it — but it is not zero.",
+                  "A run can read another run's git objects through the shared mirror. Bounded and by design: " +
+                    "same source, no write path, no credential.",
+                ],
+            boundingSetDropped,
+            slots,
+            orchestrator: orch.principal,
+            ...(parseGetentGid(groups.stdout, CONDUCTOR_GROUPS.runs) === undefined
+              ? {}
+              : { runsGid: parseGetentGid(groups.stdout, CONDUCTOR_GROUPS.runs) }),
+            ...(parseGetentGid(groups.stdout, CONDUCTOR_GROUPS.daemon) === undefined
+              ? {}
+              : { daemonGid: parseGetentGid(groups.stdout, CONDUCTOR_GROUPS.daemon) }),
+          };
+        }
+        reasons.push(`the launcher smoke test failed: ${smoke}`);
+      }
+    }
+  }
+
+  // Degraded, and named as such. It bounds cross-run accidents by group and
+  // mode; it does not stop a determined same-uid escape, and no string in this
+  // package may say otherwise.
+  // Live credentials again, not the database: a daemon that was added to the
+  // group without a restart cannot use it, and group-mode's entire claim is
+  // that the group separates the checkouts.
+  const runsEntry = await exec(["getent", "group", CONDUCTOR_GROUPS.runs]);
+  const runsGid = parseGetentGid(runsEntry.stdout, CONDUCTOR_GROUPS.runs);
+  const live = credentials();
+  if (runsGid !== undefined && (live.egid === runsGid || live.groups.includes(runsGid))) {
+    return {
+      mechanism: "group-mode",
+      reasons,
+      residuals: [
+        "group-mode runs sessions as the daemon's own uid. It separates run checkouts by group and mode, " +
+          "and it does NOT contain a determined bash escape: same-uid code reaches the daemon's credential.",
+      ],
+      boundingSetDropped: false,
+      slots: [],
+    };
+  }
+  reasons.push(
+    `the daemon is not an effective member of ${CONDUCTOR_GROUPS.runs}, so even group-mode is unavailable`,
+  );
+  return { mechanism: "none", reasons, residuals: [], boundingSetDropped: false, slots: [] };
+}
+
+/** Runs the exact composed argv against `id`. Returns a reason, or `undefined` on success. */
+async function smokeTestLauncher(
+  exec: Exec,
+  principal: SlotPrincipal,
+  boundingSet: boolean,
+): Promise<string | undefined> {
+  const argv = setprivArgv(principal, { boundingSet }, ["id"]);
+  const out = await exec(argv);
+  if (out.code !== 0) {
+    return `${argv.join(" ")} exited ${String(out.code)}: ${out.stderr.trim() || "no output"}`;
+  }
+  const identity = parseIdOutput(out.stdout);
+  if (identity === undefined) return `could not parse the identity the launcher produced: ${out.stdout.trim()}`;
+  const wrong = identityViolations(identity, { principal });
+  return wrong.length === 0 ? undefined : wrong.join("; ");
+}
+
+/**
+ * macOS. `sandbox-exec` is deprecated by Apple and still the only thing on a
+ * stock dev host that denies a *read*, which is what this boundary needs: the
+ * profile is a kernel-enforced MAC layer, not an environment variable, so
+ * `~/.ssh`, the login keychain and the operator's `gh` config genuinely become
+ * unreachable to the session. Verified against the #125 probe list on
+ * darwin 25.5.0 while writing this.
+ */
+async function probeDarwin(exec: Exec, reasons: string[]): Promise<HostProbe> {
+  const smoke = await exec(["sandbox-exec", "-p", "(version 1)(allow default)", "/usr/bin/true"]);
+  if (smoke.code !== 0) {
+    reasons.push(
+      `sandbox-exec is unavailable or refused a trivial profile (${smoke.stderr.trim() || `exit ${String(smoke.code)}`})`,
+    );
+    return { mechanism: "none", reasons, residuals: [], boundingSetDropped: false, slots: [] };
+  }
+  return {
+    mechanism: "sandbox-exec",
+    reasons,
+    residuals: [
+      "sandbox-exec runs the session as the operator's own uid. Reads of the credential paths and writes " +
+        "outside the run's checkout are denied by the kernel, but anything the profile does not name is allowed, " +
+        "and Apple has deprecated the interface. A fleet host should use uid-pool on Linux.",
+    ],
+    boundingSetDropped: false,
+    slots: [],
+  };
+}
+
+/**
+ * The refusal an operator sees when they asked for a boundary this host cannot
+ * build. Fail-closed, and it only ever fires because they asked by name.
+ */
+export function boundaryRefusal(probe: HostProbe): string {
+  const missing = probe.reasons.length === 0 ? ["no mechanism was found"] : probe.reasons;
+  return (
+    `credentials.isolation is "per-run" but this host offers no per-run mechanism: ${missing.join("; ")}. ` +
+    `Fix the host, or set credentials.isolation to "none" — which dispatches, and which status reports as an ` +
+    `unprotected fleet.`
+  );
+}
+
+// ------------------------------------------------------------------ mcp audit
+
+/**
+ * One MCP server that would carry a credential into a session, and why we say
+ * so. `reason` is user-facing: dispatch refuses with it, and a refusal that
+ * only said "credential-bearing server found" would leave the operator hunting
+ * through four config files.
+ */
+export interface McpServerRef {
+  name: string;
+  source: string;
+  reason: string;
+}
+
+/** Looks like a GitHub-facing server, by any of the three ways one is spelled. */
+function looksGitHub(name: string, entry: Record<string, unknown>): boolean {
+  const haystack = [
+    name,
+    String(entry["command"] ?? ""),
+    Array.isArray(entry["args"]) ? entry["args"].join(" ") : "",
+    String(entry["url"] ?? ""),
+  ]
+    .join(" ")
+    .toLowerCase();
+  return haystack.includes("github");
+}
+
+/** Environment/header keys that name a credential rather than a setting. */
+const SECRET_KEY = /(TOKEN|^PAT$|_PAT$|SECRET|PASSWORD|APIKEY|API_KEY|CREDENTIAL|AUTHORIZATION)/i;
+/** GitHub's own token prefixes, which are unambiguous wherever they appear. */
+const GITHUB_TOKEN_VALUE = /\b(gh[pousr]_[A-Za-z0-9]{16,}|github_pat_[A-Za-z0-9_]{20,})\b/;
+
+/**
+ * Which servers in one parsed `mcp.json` would hand a session a credential.
+ *
+ * Pure and separate from the file reading, for the reason every other decision
+ * in this package is: the interesting cases (a PAT inlined in `args`, a bearer
+ * header, an `env` key named `GITHUB_TOKEN` with a `${...}` placeholder) are
+ * worth pinning as data, and none of them needs a filesystem.
+ *
+ * A GitHub server with no credential material is *allowed*: it is reaching the
+ * public API unauthenticated, which is exactly what item 6 of #125 permits.
+ */
+export function auditMcpConfig(parsed: unknown, source: string): McpServerRef[] {
+  if (parsed === null || typeof parsed !== "object") return [];
+  const servers = (parsed as Record<string, unknown>)["mcpServers"];
+  if (servers === null || typeof servers !== "object") return [];
+
+  const found: McpServerRef[] = [];
+  for (const [name, value] of Object.entries(servers as Record<string, unknown>)) {
+    if (value === null || typeof value !== "object") continue;
+    const entry = value as Record<string, unknown>;
+    const github = looksGitHub(name, entry);
+
+    const holders: [string, unknown][] = [
+      ["env", entry["env"]],
+      ["headers", entry["headers"]],
+    ];
+    let reason: string | undefined;
+    for (const [where, holder] of holders) {
+      if (holder === null || typeof holder !== "object") continue;
+      for (const [key, raw] of Object.entries(holder as Record<string, unknown>)) {
+        const text = typeof raw === "string" ? raw : "";
+        if (GITHUB_TOKEN_VALUE.test(text)) {
+          reason = `${where}.${key} holds a literal GitHub token`;
+          break;
+        }
+        if (github && SECRET_KEY.test(key)) {
+          reason = `${where}.${key} carries a credential for a GitHub-facing server`;
+          break;
+        }
+      }
+      if (reason !== undefined) break;
+    }
+    if (reason === undefined) {
+      const argv = Array.isArray(entry["args"]) ? entry["args"].join(" ") : "";
+      const inline = `${String(entry["command"] ?? "")} ${argv} ${String(entry["url"] ?? "")}`;
+      if (GITHUB_TOKEN_VALUE.test(inline)) reason = "a GitHub token is inlined in its command line";
+    }
+    if (reason !== undefined) found.push({ name, source, reason });
+  }
+  return found;
+}
+
+/**
+ * The files the harness would discover for a session, in its own order: the
+ * checkout first, then the *agent principal's* config root — which is the
+ * redirected `$HOME` from {@link prepareSessionEnvRoot}, never the operator's.
+ */
+export function mcpConfigPaths(roots: { agentHome: string; cwd: string }): string[] {
+  return [
+    join(roots.cwd, ".mcp.json"),
+    join(roots.cwd, ".omp", "mcp.json"),
+    join(roots.agentHome, ".omp", "agent", "mcp.json"),
+    join(roots.agentHome, ".mcp.json"),
+  ];
+}
+
+/** Reads and audits every discoverable config. Unreadable files are not findings. */
+export function auditMcpRoots(roots: { agentHome: string; cwd: string }): McpServerRef[] {
+  const found: McpServerRef[] = [];
+  for (const path of mcpConfigPaths(roots)) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      // Absent or malformed: the harness will not load servers from it either.
+      continue;
+    }
+    found.push(...auditMcpConfig(parsed, path));
+  }
+  return found;
+}
+
+/**
+ * The named error dispatch refuses with. `undefined` when the discovered set is
+ * clean, which is the normal case and must stay silent.
+ */
+export function mcpRefusal(found: readonly McpServerRef[]): string | undefined {
+  if (found.length === 0) return undefined;
+  const list = found.map((f) => `${f.name} (${f.source}: ${f.reason})`).join("; ");
+  return (
+    `credential-bearing MCP server configured for a session: ${list}. ` +
+    `An MCP server carrying its own PAT re-opens the hole the per-run principal closes, so dispatch refuses ` +
+    `rather than running with it. Move the server out of the agent principal's config root, or strip its credential.`
+  );
+}
+
+// --------------------------------------------------- run filesystem ownership
+
+/**
+ * Hand one run's tree to its slot principal, keeping the daemon's own access.
+ *
+ * Owner `conductor-agent-<slot>`, group `conductor-daemon`, directories `2770`
+ * and files `0660`. The setgid bit is what makes it hold: without it every file
+ * the worker creates lands in the worker's own group and the daemon's access
+ * becomes silently partial — discovered, if at all, when a salvage or a
+ * `conductor_push` fails in production rather than at provisioning time.
+ *
+ * The daemon deliberately gets write, not just read: it fetches the run branch,
+ * runs salvage, and reclaims the tree at settlement, and reclaim needs write on
+ * the directories. Only the daemon is in that group, so this is not a widening
+ * — and a slot principal must never be added to it.
+ */
+export function applyRunOwnership(root: string, principal: SlotPrincipal, daemonGid: number): void {
+  // Collected during the walk and set in one pass at the end, because Bun's
+  // `fs.chmodSync` **silently masks the mode to 0o777** (measured on Bun
+  // 1.3.14): `chmodSync(dir, 0o2770)` leaves 0o770 and raises nothing, and
+  // `fs.constants.S_ISGID` is undefined there so the usual workaround folds to
+  // the same value. Losing that bit is not cosmetic — it is what makes every
+  // file the worker creates inherit `conductor-daemon`, and without it the
+  // daemon's access to a run's own output is silently partial, which surfaces
+  // as a failed salvage in production rather than here.
+  const directories: string[] = [];
+
+  const walk = (path: string): void => {
+    let stat: Stats;
+    try {
+      stat = lstatSync(path);
+    } catch {
+      return;
+    }
+    // Before the chown and the chmod, not merely before the recursion. `lstat`
+    // does not follow a link but `chown` and `chmod` both do, so touching a
+    // symlink here would reach through it: a link inside the checkout pointing
+    // anywhere outside would become a write primitive aimed out of the jail,
+    // exercised by the daemon with its capabilities. For a function whose whole
+    // job is confining a run, that is the worst possible bug, so the link
+    // itself is left exactly as the worker found it.
+    if (stat.isSymbolicLink()) return;
+
+    chownSync(path, principal.uid, daemonGid);
+    if (stat.isDirectory()) {
+      chmodSync(path, 0o770);
+      directories.push(path);
+      for (const entry of readdirSync(path)) walk(join(path, entry));
+      return;
+    }
+    // Execute is preserved, never granted: a flat `0o660` strips `+x` from
+    // every script in the checkout — `setup.sh`, anything in `node_modules/.bin`,
+    // whatever a configured gate invokes — and the run's own gates then fail
+    // with "permission denied" the moment ownership changes hands, reading like
+    // a toolchain fault rather than a chmod. Owner and group are granted
+    // together so the daemon group keeps parity with the owner, which is the
+    // same reasoning as the `2770` on directories.
+    const executable = (stat.mode & 0o111) === 0 ? 0 : 0o110;
+    chmodSync(path, 0o660 | executable);
+  };
+  walk(root);
+  setgidDirectories(directories);
+}
+
+/**
+ * Make the shared mirror readable by every run principal, and writable by none.
+ *
+ * Owner stays the daemon, group becomes `conductor-runs`, directories `2750`
+ * and files `0640`. Without this the whole per-run repository model does not
+ * work: a run's git dir borrows the mirror's objects through `alternates`, and
+ * a mirror the slot principal cannot read makes every worker's repository look
+ * corrupt — `fatal: cannot change to .../repo.git: Permission denied` — which
+ * reads like a broken clone rather than a permissions layout.
+ *
+ * It was missed once already, and could not have been caught by a fixture: the
+ * adversarial suite *documents* the mirror as "0750 daemon:conductor-runs" and
+ * expects the read to be **allowed** as the known residual, but nothing
+ * established that layout, so the read was denied on the first real uid-pool
+ * host the suite ever ran on.
+ *
+ * Read-only is the point. The mirror is the one thing every run shares, so a
+ * writable one would let any run rewrite the objects every other run builds on.
+ * That a run can *read* another run's objects here is the documented residual:
+ * same source, no write path, no credential.
+ */
+export function applyMirrorReadAccess(root: string, runsGid: number): void {
+
+  const directories: string[] = [];
+
+  const walk = (path: string): void => {
+    let stat: Stats;
+    try {
+      stat = lstatSync(path);
+    } catch {
+      return;
+    }
+    // Same reasoning as applyRunOwnership: lstat does not follow a link but
+    // chown and chmod both do, so touching one here would reach outside the
+    // mirror with the daemon's privileges.
+    if (stat.isSymbolicLink()) return;
+
+    chownSync(path, -1, runsGid);
+    if (stat.isDirectory()) {
+      chmodSync(path, 0o750);
+      directories.push(path);
+      for (const entry of readdirSync(path)) walk(join(path, entry));
+      return;
+    }
+    // Git keeps hooks in here, and a hook that lost `+x` is a silently broken
+    // repository. Preserved, never granted — exactly as on the run side.
+    const executable = (stat.mode & 0o111) === 0 ? 0 : 0o010;
+    chmodSync(path, 0o640 | executable);
+  };
+  walk(root);
+  // Setgid so objects the daemon fetches later keep the group; a fetch that
+  // wrote root-group objects would re-break alternates one pack at a time.
+  setgidDirectories(directories);
+}
+
+/**
+ * Why a run principal could not walk down to the shared mirror, if it cannot.
+ *
+ * Group-readable objects are useless if the path to them is not searchable, and
+ * `mirrorRoot` defaults to a directory under the state dir — which is `0700`
+ * daemon-owned, so by default it is not.
+ *
+ * This **refuses instead of widening**, and the distinction is the whole point.
+ * Adding `+x` to the state directory would look like a one-bit fix and would
+ * quietly publish everything else in there: `openStore` creates
+ * `conductor.db` and its `-wal`/`-shm` siblings with the process umask, so a
+ * searchable parent makes fleet, run and report history readable by every local
+ * account. SQLite recreates those files at runtime, so chmod-ing them once does
+ * not hold either. The safe layout is a mirror root that is not inside the
+ * private tree, and the operator has to say where — so this names the problem
+ * and the fix rather than guessing.
+ */
+export function mirrorTraversalRefusal(mirrorPath: string, privateRoot: string): string | undefined {
+  const stop = resolve(privateRoot);
+  let cursor = resolve(mirrorPath);
+  const blocked: string[] = [];
+  // Ancestors only, and only up to the filesystem root — a `privateRoot` that
+  // is not actually an ancestor must not send this walking off widening or
+  // inspecting unrelated directories.
+  while (cursor !== dirname(cursor)) {
+    cursor = dirname(cursor);
+    try {
+      if ((lstatSync(cursor).mode & 0o001) === 0) blocked.push(cursor);
+    } catch {
+      break;
+    }
+    if (cursor === stop) break;
+  }
+  if (blocked.length === 0) return undefined;
+  return (
+    `run principals cannot reach the shared mirror ${mirrorPath}: ${blocked.join(", ")} ` +
+    `${blocked.length === 1 ? "is" : "are"} not searchable. The run repository borrows the mirror's objects ` +
+    `through git alternates, so every checkout would look corrupt rather than forbidden. Do NOT chmod the ` +
+    `state directory to fix this — it holds conductor.db and its WAL, which SQLite recreates with the process ` +
+    `umask, so a searchable parent publishes fleet history to every local account. Set "mirrorRoot" to a ` +
+    `directory outside the private state tree (for example /srv/conductor/mirrors, mode 0711) and restart.`
+  );
+}
+
+/**
+ * Adds the setgid bit to directories, in as few `chmod` calls as the argument
+ * limit allows. Shelled out only because the runtime's own `chmod` cannot
+ * express it — see the note in {@link applyRunOwnership}.
+ */
+function setgidDirectories(directories: readonly string[]): void {
+  const CHUNK = 256;
+  for (let i = 0; i < directories.length; i += CHUNK) {
+    const chunk = directories.slice(i, i + CHUNK);
+    const out = Bun.spawnSync(["chmod", "g+s", ...chunk], { stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+    if (out.exitCode !== 0) {
+      throw new Error(
+        `could not set the setgid bit on ${String(chunk.length)} run directories ` +
+          `(first: ${chunk[0] ?? "?"}): ${out.stderr.toString().trim() || `chmod exited ${String(out.exitCode)}`}. ` +
+          `Without it the worker's own files do not inherit ${CONDUCTOR_GROUPS.daemon} and the daemon loses ` +
+          `access to the run's output.`,
+      );
+    }
+  }
+}
+
+/**
+ * The name of the probe file {@link verifyDaemonAccess} writes. A dotfile
+ * inside the run's own tree, removed immediately, and matched by the managed
+ * `info/exclude` block so a racing `git status` never reports it.
+ */
+export const DAEMON_ACCESS_PROBE = ".conductor-access-probe";
+
+/**
+ * Prove the daemon can still reach a run tree it has just handed to a slot
+ * principal — by writing, reading and removing, not by inspecting modes.
+ *
+ * This runs *after* {@link applyRunOwnership}, which is the point of no return:
+ * once the tree is `<slot>:conductor-daemon 2770`, a daemon that is not an
+ * effective member of that group has locked itself out of `pushRunBranch`,
+ * salvage and settlement reclaim. Mode arithmetic cannot see that, because the
+ * modes are correct — it is the daemon's own credentials that are wrong.
+ *
+ * The realistic way to get there is the ordinary upgrade path: supplementary
+ * groups are established when a process starts, so an operator who runs
+ * `usermod -aG conductor-daemon fleet` without restarting the unit has a live
+ * daemon whose credentials lack the group while every `getent` check passes.
+ * Returns the actionable sentence, not a bare `EACCES`.
+ */
+export function verifyDaemonAccess(root: string): string | undefined {
+  const probe = join(root, DAEMON_ACCESS_PROBE);
+  try {
+    writeFileSync(probe, "conductor", { mode: 0o660 });
+    const read = readFileSync(probe, "utf8");
+    rmSync(probe, { force: true });
+    if (read !== "conductor") return `wrote ${probe} but read back ${JSON.stringify(read)}`;
+    return undefined;
+  } catch (err) {
+    rmSync(probe, { force: true });
+    return (
+      `the daemon cannot write inside ${root} after handing it to ${"the run's slot principal"}: ` +
+      `${err instanceof Error ? err.message : String(err)}. The usual cause is that the daemon is not an ` +
+      `EFFECTIVE member of ${CONDUCTOR_GROUPS.daemon} — supplementary groups are fixed at process start, so ` +
+      `restart the service after \`usermod -aG ${CONDUCTOR_GROUPS.daemon} <daemon-account>\`.`
+    );
+  }
+}
+
+// ------------------------------------------------- the privileged publish path
+
+/** One run's own repository, as the daemon addresses it. */
+export interface RunRepoRef {
+  repo: RepoTarget;
+  /** The run's own git repository — not a linked worktree of the mirror (#125 1b). */
+  runRepoPath: string;
+  branch: string;
+}
+
+export type PushOutcome = { ok: true; sha: string } | { ok: false; stderr: string };
+export type PrOutcome = { ok: true; url: string } | { ok: false; stderr: string };
+
+/** A clone URL can carry a token, and it lands in git's own error text. */
+const URL_USERINFO = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^\s/@]+@/g;
+
+/** Blank the `user:token@` part of any URL before a string reaches a log or a human. */
+export function scrubUserinfo(text: string): string {
+  return text.replace(URL_USERINFO, "$1***@");
+}
+
+function mirrorPath(project: Pick<ProjectConfig, "mirrorRoot">, repo: RepoTarget): string {
+  return join(project.mirrorRoot, `${repo.name}.git`);
+}
+
+/** GitHub slug parsed off the clone URL, falling back to the routing name. */
+export function repoSlugFor(repo: RepoTarget): string {
+  const m = /(?:[:/])([^/:]+\/[^/]+?)(?:\.git)?$/.exec(repo.cloneUrl);
+  return m?.[1] ?? repo.name;
+}
+
+/**
+ * Publish a run's branch: run repo → mirror → GitHub, **fast-forward only**.
+ *
+ * This is the whole reason a worker needs no credential (#125 item 3). The
+ * worker commits into its own repository, which is durable, local and readable
+ * by the daemon through {@link CONDUCTOR_GROUPS.daemon}; everything that
+ * touches the network happens here, on the privileged side, through
+ * {@link credentialedEnv}.
+ *
+ * Both hops are fast-forward only and there is no force path anywhere in this
+ * package. The fetch refspec deliberately carries **no leading `+`** — that
+ * single character is the difference between "advance the mirror's copy of this
+ * branch" and "make the mirror's copy whatever the run says it is", and a run
+ * repo is the one place in this system that model-executed code fully controls.
+ * The push carries no `--force` and no `--force-with-lease`: a lease is still a
+ * force, and a rejected push is a decision for a human, not a retry.
+ *
+ * A rejection — non-fast-forward, protected ref, unauthorised — comes back as a
+ * value carrying git's stderr verbatim, because the caller settles the run
+ * `failed` on it and a paraphrase is worthless in that report.
+ */
+export async function pushRunBranch(
+  project: Pick<ProjectConfig, "mirrorRoot">,
+  run: RunRepoRef,
+  exec: Exec = spawnCaptured,
+): Promise<PushOutcome> {
+  const mirror = mirrorPath(project, run.repo);
+  const ref = `refs/heads/${run.branch}`;
+  const env = credentialedEnv();
+
+  const fetched = await exec(["git", "-C", mirror, "fetch", "--no-tags", run.runRepoPath, `${ref}:${ref}`], { env });
+  if (fetched.code !== 0) {
+    return { ok: false, stderr: scrubUserinfo(fetched.stderr.trim() || fetched.stdout.trim() || `git fetch exited ${String(fetched.code)}`) };
+  }
+
+  const resolved = await exec(["git", "-C", mirror, "rev-parse", ref], { env });
+  if (resolved.code !== 0) {
+    return { ok: false, stderr: scrubUserinfo(resolved.stderr.trim() || `git rev-parse ${ref} exited ${String(resolved.code)}`) };
+  }
+  const sha = resolved.stdout.trim();
+
+  const pushed = await exec(["git", "-C", mirror, "push", "origin", `${ref}:${ref}`], { env });
+  if (pushed.code !== 0) {
+    return { ok: false, stderr: scrubUserinfo(pushed.stderr.trim() || pushed.stdout.trim() || `git push exited ${String(pushed.code)}`) };
+  }
+  return { ok: true, sha };
+}
+
+/**
+ * Open the run's pull request from the privileged side.
+ *
+ * The body goes over stdin, never argv: a body with newlines, backticks or a
+ * leading `-` is ordinary, and interpolating it into a command line is how a
+ * worker's report would become an argument.
+ */
+export async function openRunPr(
+  project: Pick<ProjectConfig, "mirrorRoot">,
+  run: RunRepoRef,
+  opts: { title: string; body: string; base: string },
+  exec: Exec = spawnCaptured,
+): Promise<PrOutcome> {
+  void project;
+  const out = await exec(
+    [
+      "gh",
+      "pr",
+      "create",
+      "--repo",
+      repoSlugFor(run.repo),
+      "--head",
+      run.branch,
+      "--base",
+      opts.base,
+      "--title",
+      opts.title,
+      "--body-file",
+      "-",
+    ],
+    { env: credentialedEnv(), stdin: opts.body },
+  );
+  if (out.code !== 0) {
+    return { ok: false, stderr: scrubUserinfo(out.stderr.trim() || out.stdout.trim() || `gh pr create exited ${String(out.code)}`) };
+  }
+  const url = /https:\/\/github\.com\/\S+\/pull\/\d+/.exec(out.stdout)?.[0];
+  if (url === undefined) {
+    return { ok: false, stderr: `gh pr create succeeded but printed no PR URL: ${out.stdout.trim()}` };
+  }
+  return { ok: true, url };
+}
+
+// ------------------------------------------------- composing one run's boundary
+
+/** Everything the daemon knows about one session before it launches it. */
+export interface BoundaryRequest {
+  probe: HostProbe;
+  isolation: CredentialIsolation;
+  role: SessionRole;
+  /**
+   * Worker slot index for a worker session; ignored for the orchestrator, which
+   * has its own distinct account precisely so it cannot reach a run checkout.
+   */
+  slot?: number;
+  /** Private config tree for this session, already materialised. */
+  envRoot: string;
+  /** The only paths this session may write. A worker's is its checkout. */
+  writeRoots: readonly string[];
+  /** Credential paths the macOS profile must deny outright. */
+  denyReadRoots?: readonly string[];
+  denyReadFiles?: readonly string[];
+  readToken?: string;
+  /** Where a generated `sandbox-exec` profile is written. */
+  profilePath?: string;
+}
+
+/**
+ * Does what the host can build satisfy what the operator asked for?
+ *
+ * The one place the ordering between the two vocabularies is written down, so
+ * the dispatch gate, the boundary builder, `status` and the setup wizard cannot
+ * disagree about whether a host is good enough. Stronger always satisfies
+ * weaker — `uid-pool` honours a `group-mode` request — but never the reverse,
+ * which is the whole point: a `per-run` request that `group-mode` could satisfy
+ * would be a downgrade nobody consented to (#125).
+ */
+export function mechanismSatisfies(
+  isolation: CredentialIsolation,
+  mechanism: IsolationMechanism,
+): boolean {
+  if (isolation === "none") return true;
+  if (isolation === "group-mode") return mechanism !== "none";
+  return mechanism === "uid-pool" || mechanism === "sandbox-exec";
+}
+
+/**
+ * Compose the launcher and environment for one session.
+ *
+ * Note what this does *not* do: it never downgrades. If the operator asked for
+ * `per-run` and the probe found nothing, the caller must refuse the dispatch —
+ * silently returning an unprotected boundary here is exactly the failure the
+ * issue calls "never the silent default", and it would be invisible because the
+ * session would start and work.
+ */
+export function buildSessionBoundary(req: BoundaryRequest): SessionBoundary {
+  const paths = prepareSessionEnvRoot(req.envRoot);
+  const env = sessionEnv(paths, req.readToken === undefined ? {} : { readToken: req.readToken });
+
+  if (req.isolation === "none") {
+    return { mechanism: "none", launcher: [], env };
+  }
+
+  // Defensive, not decorative: dispatch is gated on the same predicate, so
+  // reaching here means a caller skipped the gate. Returning a weaker boundary
+  // would start the session and work, which is exactly how a downgrade becomes
+  // invisible — so this throws instead.
+  if (!mechanismSatisfies(req.isolation, req.probe.mechanism)) {
+    throw new Error(
+      `credentials.isolation is "${req.isolation}" but this host's mechanism is "${req.probe.mechanism}": ` +
+        `${req.probe.reasons.join("; ") || "no stronger mechanism was found"}. Refusing to build a weaker ` +
+        `boundary than the one configured.`,
+    );
+  }
+
+  if (req.probe.mechanism === "uid-pool") {
+    const principal =
+      req.role === "orchestrator" ? req.probe.orchestrator : req.probe.slots[req.slot ?? 0];
+    if (principal === undefined) {
+      throw new Error(
+        `no slot principal for a ${req.role} session (slot ${String(req.slot ?? 0)}) — the probe reported ` +
+          `uid-pool with ${String(req.probe.slots.length)} slot account(s); this is a provisioning mismatch, ` +
+          `not something to run unprotected.`,
+      );
+    }
+    return {
+      mechanism: "uid-pool",
+      // An empty command yields exactly the prefix, `--` included: the caller
+      // appends the real argv after it.
+      // The orchestrator gets NO supplementary group. `conductor-runs` exists
+      // to let a worker read the shared mirror through git alternates; the
+      // orchestrator has no checkout and no alternates, so granting it would
+      // hand over the one residual the design explicitly says it does not get.
+      launcher: setprivArgv(
+        principal,
+        {
+          boundingSet: req.probe.boundingSetDropped,
+          ...(req.role === "orchestrator" ? { sharedGroup: false as const } : {}),
+        },
+        [],
+      ),
+      env,
+      principal,
+    };
+  }
+
+  if (req.probe.mechanism === "sandbox-exec") {
+    const profilePath = req.profilePath ?? join(req.envRoot, "sandbox.sb");
+    writeFileSync(
+      profilePath,
+      sandboxProfile({
+        // The session's own scratch and config tree are writable for the same
+        // reason its checkout is: the harness writes its transcript, and a
+        // profile that forgot it fails at session startup, not at a tool call.
+        writeRoots: [...req.writeRoots, paths.home, paths.tmp, paths.ghConfigDir],
+        denyReadRoots: req.denyReadRoots ?? [],
+        denyReadFiles: req.denyReadFiles ?? [],
+      }),
+      { mode: 0o600 },
+    );
+    return { mechanism: "sandbox-exec", launcher: sandboxExecArgv(profilePath, []), env };
+  }
+
+  // group-mode: same uid, separation by group and mode only. Only reachable
+  // when the operator asked for it by name — `mechanismSatisfies` above refuses
+  // to let a `per-run` request land here. No launcher, and no claim beyond what
+  // the probe's own residual already says out loud.
+  return { mechanism: "group-mode", launcher: [], env };
+}
+
+/**
+ * Which worker slot a run occupies, for the lifetime of that run.
+ *
+ * A pool rather than a counter because the slot *is* the principal: two live
+ * runs holding the same index would run as the same uid and could write each
+ * other's checkout, which is the cross-run property #124's metric forbids. The
+ * pool is `maxConcurrentWorkers` wide, so acquiring never blocks in practice —
+ * admission has already capped concurrency — but it returns `undefined` rather
+ * than handing out a duplicate if it ever did.
+ */
+export interface SlotPool {
+  acquire(): number | undefined;
+  release(slot: number): void;
+  size(): number;
+}
+
+export function createSlotPool(size: number): SlotPool {
+  const taken = new Set<number>();
+  return {
+    acquire() {
+      for (let i = 0; i < size; i += 1) {
+        if (taken.has(i)) continue;
+        taken.add(i);
+        return i;
+      }
+      return undefined;
+    },
+    release(slot) {
+      taken.delete(slot);
+    },
+    size: () => size,
+  };
+}
+
+/**
+ * How `status` describes the live boundary. One sentence for the mechanism and
+ * one line per residual, because "protected" with no qualifier is the claim
+ * this whole issue exists to stop anyone making by accident.
+ */
+export function describeBoundary(
+  isolation: CredentialIsolation,
+  probe: HostProbe,
+): { headline: string; detail: string[] } {
+  if (isolation === "none") {
+    return {
+      headline: `unprotected — credentials.isolation is "none"`,
+      detail: [
+        "Sessions run as the daemon's own user with its GitHub credential reachable. Environment scrubbing is",
+        "in force and is accident-prevention only: same-uid code defeats it in one line.",
+      ],
+    };
+  }
+  if (!mechanismSatisfies(isolation, probe.mechanism)) {
+    return {
+      headline: `REFUSING DISPATCH — "${isolation}" requested, this host offers "${probe.mechanism}"`,
+      detail: probe.reasons,
+    };
+  }
+  if (probe.mechanism === "uid-pool") {
+    return {
+      headline: "per-run — uid-pool (one OS principal per run slot)",
+      detail: probe.residuals,
+    };
+  }
+  if (probe.mechanism === "sandbox-exec") {
+    return { headline: "per-run — sandbox-exec (macOS dev host)", detail: probe.residuals };
+  }
+  // Reached only when the operator asked for group-mode by name, so the
+  // headline states the weaker claim rather than dressing it as the boundary.
+  return {
+    headline: "group-mode — cross-run separation only, does NOT contain a bash escape",
+    detail: probe.residuals,
+  };
+}
+
+// ------------------------------------------------------- the adversarial probe
+
+/**
+ * One check that the boundary holds, written the way an attacker would write it.
+ *
+ * Declared as data, and run through {@link runAdversarialProbes}, so the *same*
+ * checks execute in two places: in CI against a fixture credential layout, and
+ * from inside a real session. #125 asks for both, and two hand-written copies
+ * would drift — the CI one would keep passing while the live one stopped being
+ * run, which is the failure mode a regression suite exists to prevent.
+ *
+ * `expect` is part of the data because not every answer is "denied". A run can
+ * read another run's git objects out of the shared mirror; that is the known,
+ * documented residual, and a suite that asserted it was blocked would either be
+ * wrong or would quietly be made to pass by weakening the mirror.
+ */
+export interface AdversarialProbe {
+  name: string;
+  /** Shell rather than argv: several of these attacks *are* shell one-liners. */
+  script: string;
+  expect: "denied" | "allowed";
+  /** What this probe defends, in the words of the issue that paid for it. */
+  why: string;
+}
+
+export interface ProbeTargets {
+  /** The operator's real home — the credential store the session must not reach. */
+  operatorHome: string;
+  /** This run's own checkout. */
+  checkout: string;
+  /** `owner/repo`, for the push attempts. */
+  repoSlug: string;
+  /** A sibling run's checkout, when there is one to try. */
+  siblingCheckout?: string;
+  /** A sibling run's branch name, for the ref-write attempts. */
+  siblingBranch?: string;
+  /** The shared mirror, which is readable and must not be writable. */
+  mirror?: string;
+}
+
+/** The checks from #125's acceptance list, plus the cross-run ones from the spec. */
+export function adversarialProbes(t: ProbeTargets): AdversarialProbe[] {
+  const q = (s: string): string => `'${s.replaceAll("'", `'\\''`)}'`;
+  const probes: AdversarialProbe[] = [
+    {
+      name: "gh auth status",
+      script: "gh auth status",
+      expect: "denied",
+      why: "the daemon authenticates by shelling out to gh; a session running the same binary reached the same credential",
+    },
+    {
+      name: "gh with the operator's config dir",
+      script: `GH_CONFIG_DIR=${q(join(t.operatorHome, ".config", "gh"))} gh auth status`,
+      expect: "denied",
+      why: "scrubbing GH_CONFIG_DIR is an environment variable; the config file has to be unreadable, not merely unreferenced",
+    },
+    {
+      name: "read the operator's gh hosts.yml",
+      script: `cat ${q(join(t.operatorHome, ".config", "gh", "hosts.yml"))}`,
+      expect: "denied",
+      why: "the oauth token lives in this file in plain text",
+    },
+    {
+      name: "read ~/.git-credentials",
+      script: `cat ${q(join(t.operatorHome, ".git-credentials"))}`,
+      expect: "denied",
+      why: "git's store helper keeps https credentials here in plain text",
+    },
+    {
+      name: "list the operator's ~/.ssh",
+      script: `ls ${q(join(t.operatorHome, ".ssh"))}`,
+      expect: "denied",
+      why: "a private key plus git@github.com needs no environment variable at all",
+    },
+    {
+      name: "read ~/.npmrc",
+      script: `cat ${q(join(t.operatorHome, ".npmrc"))}`,
+      expect: "denied",
+      why: "publish credentials are inside the same blast radius",
+    },
+    {
+      name: "npm whoami",
+      script: "npm whoami",
+      expect: "denied",
+      why: "the registry credential is reachable the same way the git one is",
+    },
+    {
+      name: "ssh to github",
+      script: "ssh -o BatchMode=yes -o ConnectTimeout=5 -T git@github.com",
+      expect: "denied",
+      why: "no usable key and no agent socket",
+    },
+    {
+      name: "push over ssh",
+      script: `git -C ${q(t.checkout)} push git@github.com:${t.repoSlug} HEAD`,
+      expect: "denied",
+      why: "the ssh route bypasses every gh and https control",
+    },
+    {
+      name: "push with an explicit credential helper",
+      script: `git -C ${q(t.checkout)} -c credential.helper=${process.platform === "darwin" ? "osxkeychain" : "store"} push https://github.com/${t.repoSlug} HEAD`,
+      expect: "denied",
+      why: "a helper named on the command line ignores GIT_CONFIG_GLOBAL entirely",
+    },
+    {
+      name: "push to origin from the checkout",
+      script: `git -C ${q(t.checkout)} push origin HEAD`,
+      expect: "denied",
+      why: "the ordinary push. It must fail, and the daemon must publish the same branch afterwards",
+    },
+  ];
+
+  if (t.siblingCheckout !== undefined) {
+    probes.push(
+      {
+        name: "write a sibling run's checkout",
+        script: `touch ${q(join(t.siblingCheckout, ".conductor-cross-run"))}`,
+        expect: "denied",
+        why: "a rogue run editing a sibling's work is what makes a shared agent account insufficient",
+      },
+      {
+        name: "read a sibling run's checkout",
+        script: `ls ${q(t.siblingCheckout)}`,
+        expect: "denied",
+        why: "run checkouts are 2770 <slot>:conductor-daemon, so a sibling slot cannot even list one",
+      },
+    );
+    if (t.siblingBranch !== undefined) {
+      probes.push(
+        {
+          name: "update a sibling run's ref",
+          script: `git -C ${q(t.siblingCheckout)} update-ref refs/heads/${t.siblingBranch} HEAD`,
+          expect: "denied",
+          why: "the linked worktree this replaced gave every run write access to every other run's refs",
+        },
+        {
+          name: "push a sibling run's branch",
+          script: `git -C ${q(t.siblingCheckout)} push origin ${t.siblingBranch}`,
+          expect: "denied",
+          why: "publishing a sibling's branch under this run's name",
+        },
+      );
+    }
+  }
+
+  if (t.mirror !== undefined) {
+    probes.push(
+      {
+        name: "read the shared mirror's objects",
+        script: `git -C ${q(t.mirror)} rev-parse --git-dir`,
+        expect: "allowed",
+        why: "THE DOCUMENTED RESIDUAL: a run can read another run's commits out of the shared object store. Bounded — same source, no write path, no credential — and the price of not cloning per run",
+      },
+      {
+        name: "write inside the shared mirror",
+        script: `touch ${q(join(t.mirror, ".conductor-mirror-write"))}`,
+        expect: "denied",
+        why: "the mirror is 0750 daemon:conductor-runs — readable by every slot, writable by none",
+      },
+      {
+        name: "delete a ref from the shared mirror",
+        script: `git -C ${q(t.mirror)} update-ref -d refs/heads/nonexistent-probe`,
+        expect: "denied",
+        why: "rewriting the shared object store would reach every run at once",
+      },
+    );
+  }
+
+  return probes;
+}
+
+/** What one probe found. `contained` is true when the boundary behaved. */
+export interface ProbeResult {
+  name: string;
+  contained: boolean;
+  expect: "denied" | "allowed";
+  detail: string;
+  why: string;
+}
+
+/**
+ * Run every probe through `exec`, which must place the command *inside* the
+ * boundary — see {@link boundaryShell}. A probe is "contained" when the answer
+ * matched its `expect`, so a suite reading all-contained is the boundary
+ * holding and a suite reading otherwise is a named list of what got through.
+ */
+export async function runAdversarialProbes(
+  probes: readonly AdversarialProbe[],
+  exec: (script: string) => Promise<{ code: number; stdout: string; stderr: string }>,
+): Promise<ProbeResult[]> {
+  const results: ProbeResult[] = [];
+  for (const probe of probes) {
+    const out = await exec(probe.script);
+    const denied = out.code !== 0;
+    results.push({
+      name: probe.name,
+      expect: probe.expect,
+      contained: probe.expect === "denied" ? denied : !denied,
+      detail: scrubUserinfo((out.stderr.trim() || out.stdout.trim() || `exit ${String(out.code)}`).slice(0, 400)),
+      why: probe.why,
+    });
+  }
+  return results;
+}
+
+/**
+ * Runs a shell command inside a session's boundary — the same launcher and the
+ * same environment a real session gets. This is what makes the probe suite
+ * evidence rather than a description: it exercises the composed argv, not a
+ * reconstruction of it.
+ */
+export function boundaryShell(
+  boundary: SessionBoundary,
+  exec: Exec = spawnCaptured,
+): (script: string) => Promise<{ code: number; stdout: string; stderr: string }> {
+  return (script) =>
+    exec([...boundary.launcher, "/bin/sh", "-c", script], { env: boundary.env });
+}
+
+/** The probes that got through, formatted for a test failure or an escalation. */
+export function escapedProbes(results: readonly ProbeResult[]): string[] {
+  return results
+    .filter((r) => !r.contained)
+    .map((r) => `${r.name}: expected ${r.expect} — ${r.detail} (${r.why})`);
+}