omp-conductor 0.3.25 → 0.4.0

package/src/worktree.ts

@@ -1,16 +1,32 @@
 /**
  * Checkout provisioning for one run.
  *
- * Every issue gets its own working tree so two workers can never see each
- * other's half-finished edits. The trees are cut from a per-repo bare mirror
- * that is cloned once and refreshed, rather than a fresh full clone per issue:
- * a module repo's history is fetched one time and every later run pays only
- * for the delta.
+ * Every issue gets its own repository so two workers can never see each other's
+ * half-finished edits. Objects come from a per-repo bare mirror that is cloned
+ * once and refreshed, rather than a fresh full clone per issue: a module repo's
+ * history is fetched one time and every later run pays only for the delta.
+ *
+ * **A run gets its own repository, not a linked worktree of the mirror, and
+ * that is a security property rather than a preference (#125 1b).** A linked
+ * worktree shares the mirror's common dir — refs, objects, index locks — so it
+ * needs *write* access to it, which hands every run write access to every other
+ * run's refs. Here the objects arrive read-only through git's alternates
+ * mechanism and the run's refs, index and commits live in its own git dir. The
+ * documented residual is that a run can still *read* another run's objects out
+ * of the shared store: bounded, same source, no write path, no credential, and
+ * the price of not cloning the repo per run.
+ *
+ * Publishing is therefore the daemon's job, never the worker's — see
+ * `pushRunBranch` in `credentials.ts`. The run repo's `origin` deliberately
+ * names the real clone URL rather than the mirror, so a worker's
+ * `git push origin HEAD` attempts the network and fails on credentials instead
+ * of quietly succeeding into the shared object store.
  */
 
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
+import { credentialedEnv, scrubUserinfo } from "./credentials.ts";
 import type { RepoTarget } from "./types.ts";
 
 /**
@@ -19,15 +35,12 @@ import type { RepoTarget } from "./types.ts";
  */
 const TRACKING_REFSPEC = "+refs/heads/*:refs/remotes/origin/*";
 
-/** Matches the `user:token@` part of any URL, so it can be blanked out. */
-const URL_USERINFO = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^\s/@]+@/g;
-
 /**
  * The on-disk layout, in one place. Both are pure functions of config, so a
  * caller that has to clean up *before* provisioning — the dispatcher on a
  * retry, or reconciling orphaned trees at startup — can name a mirror or a
  * tree without a network hop, and cannot drift from what `ensureMirror` and
- * `addWorktree` will actually create.
+ * `addRunRepo` will actually create.
  */
 export function mirrorPathFor(repo: RepoTarget, mirrorRoot: string): string {
   return join(mirrorRoot, `${repo.name}.git`);
@@ -48,9 +61,12 @@ async function runGit(
     stdin: "ignore",
     stdout: "pipe",
     stderr: "pipe",
-    // An unattended dispatcher must fail loudly rather than block forever on a
-    // credential prompt nobody is there to answer.
-    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    // Every git call in this module runs on the *privileged* side — the daemon
+    // provisioning, salvaging or publishing — so it goes through the one named
+    // construction site of credential material (#125). It also carries
+    // GIT_TERMINAL_PROMPT=0, because an unattended dispatcher must fail loudly
+    // rather than block forever on a prompt nobody is there to answer.
+    env: credentialedEnv(),
   });
 
   const [stdout, stderr, code] = await Promise.all([
@@ -75,12 +91,7 @@ async function git(args: string[], cwd?: string): Promise<string> {
     const detail = stderr.trim() || stdout.trim() || "no output";
     // A clone URL can carry a token, and it lands in both our argv and git's
     // own error text; this string reaches logs and humans, so scrub it.
-    throw new Error(
-      `git ${args.join(" ")}${where} exited ${code}: ${detail}`.replace(
-        URL_USERINFO,
-        "$1***@",
-      ),
-    );
+    throw new Error(scrubUserinfo(`git ${args.join(" ")}${where} exited ${code}: ${detail}`));
   }
 
   return stdout.trim();
@@ -267,10 +278,24 @@ export async function ensureMirror(
 }
 
 /**
- * Provisions `<workspaceRoot>/<issue>` as a worktree of `repo` for `branch`,
- * and returns the path. On the first attempt the branch is cut from the
- * upstream tip of the default branch; on a retry the preserved branch is
- * reattached (see the comment on the add below).
+ * Provisions `<workspaceRoot>/<issue>` as a **repository of its own** for
+ * `repo`/`branch`, and returns the path. On the first attempt the branch is cut
+ * from the upstream tip of the default branch; on a retry the preserved branch
+ * is reattached out of the mirror (see the comment on the fetch below).
+ *
+ * The objects come from the shared mirror through `objects/info/alternates` —
+ * git's own read-only borrowing mechanism — so provisioning still costs one
+ * fetch of the delta rather than a full clone, exactly as the linked worktree
+ * it replaces did. What changed is who can write what: the run's refs, index
+ * and commits are its own, and nothing it does can reach a sibling run's refs
+ * or the mirror (#125 1b).
+ *
+ * `origin` is deliberately the real clone URL and not the mirror path. Pointing
+ * it at the mirror would make a worker's ordinary `git push origin HEAD`
+ * succeed *into the shared object store*, which is precisely the write access
+ * this replacement exists to remove; pointing it upstream makes that push
+ * attempt the network and fail on credentials it does not have, while the
+ * daemon publishes the branch for it (`pushRunBranch`).
  *
  * ponytail: reattachment is the only retry mode, so attempt 2 always inherits
  * attempt 1's tip — including a half-finished or broken state it might rather
@@ -279,7 +304,7 @@ export async function ensureMirror(
  * path: snapshot the branch to `refs/conductor/attempt/<issue>/<n>` before
  * resetting the run branch to `base`, and surface both refs in the escalation.
  */
-export async function addWorktree(
+export async function addRunRepo(
   repo: RepoTarget,
   mirrorRoot: string,
   workspaceRoot: string,
@@ -287,16 +312,19 @@ export async function addWorktree(
   branch: string,
 ): Promise<{ path: string; reattached: boolean }> {
   const mirrorPath = await ensureMirror(repo, mirrorRoot);
-  mkdirSync(workspaceRoot, { recursive: true });
+  // 0711: searchable, so a slot principal can reach its own checkout; not
+  // listable, so it cannot enumerate its siblings; not writable, so it cannot
+  // create or unlink one. Same reasoning as the socket parent directory.
+  mkdirSync(workspaceRoot, { recursive: true, mode: 0o711 });
 
-  const worktreePath = worktreePathFor(workspaceRoot, issue);
-  if (existsSync(worktreePath)) {
+  const runRepo = worktreePathFor(workspaceRoot, issue);
+  if (existsSync(runRepo)) {
     // Reusing a tree is how one worker silently inherits another attempt's
     // uncommitted edits and pushes them under this issue's name.
     throw new Error(
-      `worktree path already exists: ${worktreePath}. Refusing to reuse it — ` +
+      `worktree path already exists: ${runRepo}. Refusing to reuse it — ` +
         `it may hold a previous attempt's uncommitted work. Call ` +
-        `removeWorktree(${mirrorPath}, ${worktreePath}) first.`,
+        `removeWorktree(${mirrorPath}, ${runRepo}) first.`,
     );
   }
 
@@ -305,73 +333,98 @@ export async function addWorktree(
   // under normal-clone semantics is no longer refreshed at all), so branching
   // off it would silently start a run on a stale tip.
   const base = `refs/remotes/origin/${repo.defaultBranch}`;
-  await git(
-    [
-      "fetch",
-      "--no-tags",
-      "origin",
-      `+refs/heads/${repo.defaultBranch}:${base}`,
-    ],
-    mirrorPath,
-  );
-
-  // `--no-track` on the create path because the start point is a
-  // remote-tracking ref: without it git would set the run branch's upstream to
-  // the default branch, and the worker's `git push` would then argue with
-  // `push.default` instead of publishing the branch. The reattach path must
-  // *omit* the flag — git dies with "--[no-]track can only be used if a new
-  // branch is created" — and does not need it, since checking out an existing
-  // branch writes no tracking config at all.
-  //
-  // `-b` is only ever correct on the *first* attempt for an issue. Branch
-  // names are a deterministic function of the issue number, `removeWorktree`
-  // deliberately leaves the branch behind in the mirror, and `git worktree add
-  // -b <existing>` is a hard error — so without this probe a second attempt
-  // could never provision a tree and `maxAttemptsPerIssue` was fiction.
-  //
-  // The retry therefore *reattaches* the existing branch rather than doing
-  // either of the two easier things. A fresh `<branch>-attempt2` would break
-  // the fleet contract of one issue = one branch = one PR. A `branch -D` or a
-  // force-reset to the upstream tip would be irreversible: that branch can
-  // hold the only copy of work attempt 1 committed but never pushed. Attaching
-  // to it hands the new worker attempt 1's commits, so it can continue or
-  // recover them, and any destructive call stays a human's to make.
-  const branchExists = await gitSucceeds(
+  await git(["fetch", "--no-tags", "origin", `+refs/heads/${repo.defaultBranch}:${base}`], mirrorPath);
+
+  // Branch names are a deterministic function of the issue number and the
+  // mirror keeps the branch after a run ends, so its presence is what
+  // distinguishes a continuation from a first attempt. The retry *reattaches*
+  // rather than doing either of the two easier things: a fresh
+  // `<branch>-attempt2` would break the fleet contract of one issue = one
+  // branch = one PR, and a force-reset to upstream would be irreversible,
+  // because that branch can hold the only copy of work attempt 1 committed but
+  // never pushed. Attaching to it hands the new worker attempt 1's commits.
+  const reattached = await gitSucceeds(
     ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`],
     mirrorPath,
   );
-  const addArgs = branchExists
-    ? ["worktree", "add", worktreePath, branch]
-    : ["worktree", "add", "--no-track", "-b", branch, worktreePath, base];
+  const start = reattached ? `refs/heads/${branch}` : base;
 
   try {
-    await git(addArgs, mirrorPath);
-  } catch (err) {
-    // A hard crash can leave the branch registered to a worktree whose
-    // directory is long gone, and git then refuses the add as "already checked
-    // out". `prune` drops exactly that stale bookkeeping and never touches a
-    // commit, so run it and retry once. It is not conditioned on git's wording
-    // because that text is version- and locale-dependent; an add that is
-    // broken for any other reason simply fails the same way twice.
-    await git(["worktree", "prune"], mirrorPath);
-    try {
-      await git(addArgs, mirrorPath);
-    } catch (retryErr) {
-      const first = err instanceof Error ? err.message : String(err);
-      const second =
-        retryErr instanceof Error ? retryErr.message : String(retryErr);
-      throw new Error(
-        `failed to provision worktree ${worktreePath} for issue ${issue} on ` +
-          `branch ${branch} (${branchExists ? "reattaching an existing branch" : "creating a new branch"}), ` +
-          `both before and after \`git worktree prune\`: ${second} ` +
-          `(first attempt: ${first})`,
-      );
+    await git(["init", "--quiet", runRepo]);
+    // Before the first fetch, or git does not know the mirror's objects are
+    // reachable and the fetch below tries to copy the whole history.
+    const info = join(runRepo, ".git", "objects", "info");
+    mkdirSync(info, { recursive: true });
+    writeFileSync(join(info, "alternates"), `${join(mirrorPath, "objects")}\n`);
+
+    // HEAD is moved onto the run branch *after* the fetch, never before: git
+    // refuses to fetch into the branch HEAD is pointing at, even an unborn one,
+    // and the error ("refusing to fetch into branch … checked out at …") reads
+    // like a stale worktree registration rather than an ordering mistake. A
+    // fresh `git init` names its default branch, so the only way to collide is
+    // for the run branch to be called that — cheap to rule out, and silent
+    // breakage for exactly one issue number if it is not.
+    const initialHead = await git(["symbolic-ref", "--quiet", "HEAD"], runRepo);
+    if (initialHead === `refs/heads/${branch}`) {
+      await git(["symbolic-ref", "HEAD", "refs/heads/omp-conductor-bootstrap"], runRepo);
     }
+
+    // Fetched by path, from a remote that is never persisted: the run repo must
+    // not keep a handle on the mirror it could push back through. No leading
+    // `+` — the ref does not exist yet, so a fast-forward is trivially
+    // satisfied, and there is no forcing refspec anywhere on a run's own branch.
+    await git(["fetch", "--no-tags", mirrorPath, `${start}:refs/heads/${branch}`], runRepo);
+    // The upstream tracking refs, so the worker can read `origin/main` and diff
+    // against it. These are remote-tracking refs, which git force-updates by
+    // definition; the run branch above is the one that must never be forced.
+    await git(
+      ["fetch", "--no-tags", mirrorPath, "+refs/remotes/origin/*:refs/remotes/origin/*"],
+      runRepo,
+    );
+
+    // Added after the fetches so it cannot capture them: `origin` is upstream,
+    // and it exists so an ordinary `git push origin HEAD` fails on credentials
+    // rather than succeeding into the mirror. No upstream is configured for the
+    // run branch, for the reason the old `--no-track` existed: otherwise the
+    // worker's push argues with `push.default` instead of publishing.
+    await git(["remote", "add", "origin", repo.cloneUrl], runRepo);
+
+    await git(["symbolic-ref", "HEAD", `refs/heads/${branch}`], runRepo);
+    await git(["reset", "--hard"], runRepo);
+
+    // The mirror's `info/exclude` is no longer this repo's common dir, so the
+    // managed block has to be written here. Without it a worker's own scratch
+    // reaches its `git add -A`, and salvage inherits it (#44).
+    const exclude = join(runRepo, ".git", "info", "exclude");
+    mkdirSync(dirname(exclude), { recursive: true });
+    writeFileSync(exclude, mergeExclude(existsSync(exclude) ? readFileSync(exclude, "utf8") : ""));
+  } catch (err) {
+    // A half-provisioned repo would be seen as "present" by the next attempt
+    // and refused as possibly holding work, stranding the issue. It holds
+    // nothing yet — the branch's durable copy is in the mirror — so clear it.
+    rmSync(runRepo, { recursive: true, force: true });
+    throw new Error(
+      `failed to provision run repository ${runRepo} for issue ${issue} on branch ${branch} ` +
+        `(${reattached ? "reattaching an existing branch" : "creating a new branch"}): ` +
+        `${err instanceof Error ? err.message : String(err)}`,
+    );
   }
 
-  return { path: worktreePath, reattached: branchExists };
+  return { path: runRepo, reattached };
 }
 
+/**
+ * Publishes one run branch: run repo → mirror → GitHub, fast-forward only.
+ *
+ * Declared here as a function type rather than imported as a concrete
+ * implementation so this module stays free of the credential path: provisioning
+ * and salvage decide *what* to publish, `credentials.ts` is the only place that
+ * decides *how*, and the daemon is the only thing that holds both.
+ */
+export type RunPublisher = (
+  branch: string,
+) => Promise<{ ok: true; sha: string } | { ok: false; stderr: string }>;
+
 /**
  * What one salvage attempt did. A failure is a *value* rather than a throw
  * because the only caller is a run that is already ending badly: it has to log
@@ -468,10 +521,10 @@ function parseCachedNameStatus(raw: string): { files: string[]; newPaths: string
  * Commits a run's uncommitted work to the run's own branch and pushes it, so
  * that the tree the next attempt destroys is no longer the only copy.
  *
- * This closes a deliberate asymmetry. `addWorktree` preserves the run branch
+ * This closes a deliberate asymmetry. `addRunRepo` preserves the run branch
  * precisely because "that branch can hold the only copy of work attempt 1
  * committed but never pushed", while `removeWorktree` runs `worktree remove
- * --force` and `addWorktree` refuses to reuse a tree that "may hold a previous
+ * --force` and `addRunRepo` refuses to reuse a tree that "may hold a previous
  * attempt's uncommitted work" — committed work is kept by design, uncommitted
  * work was discarded by design.
  *
@@ -490,18 +543,28 @@ function parseCachedNameStatus(raw: string): { files: string[]; newPaths: string
  * Never throws. Every outcome, including its own failure, comes back as a value
  * for the caller to log and to put in front of a human.
  *
- * The push is best-effort and deliberately last, after the sha exists: a
+ * Publishing is best-effort and deliberately last, after the sha exists: a
  * refused push (diverged branch, no credentials, no network) still leaves the
- * commit in this host's mirror, which is strictly better than nothing. It is a
- * plain fast-forward push — never a force — and if the run already had a PR
- * open, that PR gains the WIP commit and re-runs its checks. That is the price
- * of work outliving its host.
+ * commit in the run's own repository, which the daemon can still read, and
+ * which is strictly better than nothing. It is a plain fast-forward push —
+ * never a force — and if the run already had a PR open, that PR gains the WIP
+ * commit and re-runs its checks. That is the price of work outliving its host.
+ *
+ * `publish` is a **required** parameter rather than an optional one with a
+ * no-op default, and that is the whole design. The salvage commit no longer
+ * pushes for itself: the run's repository holds no credential (#125), so the
+ * network hop is the daemon's, through `pushRunBranch`. A defaulted parameter
+ * is how a future call site silently stops publishing salvaged work and nobody
+ * finds out until the host that held it is gone — which is #121's failure with
+ * one extra step. Passing `undefined` is allowed, and is a visible decision at
+ * the call site.
  */
 export async function salvageWip(
   worktree: string,
   issue: number,
   attempt: number,
   ending: string,
+  publish: RunPublisher | undefined,
 ): Promise<SalvageOutcome> {
   try {
     // A tree that is not there cannot be holding work. Checked before spawning
@@ -572,18 +635,17 @@ export async function salvageWip(
       };
     }
 
-    const push = await runGit(["push", "origin", `HEAD:refs/heads/${branch}`], worktree);
-    if (push.code === 0) return { ...salvaged, pushed: true };
-
-    return {
-      ...salvaged,
-      pushed: false,
-      pushError: (
-        push.stderr.trim() ||
-        push.stdout.trim() ||
-        `git push exited ${push.code}`
-      ).replace(URL_USERINFO, "$1***@"),
-    };
+    if (publish === undefined) {
+      return {
+        ...salvaged,
+        pushed: false,
+        pushError:
+          "no publisher was supplied — the commit exists in the run's own repository and nowhere else",
+      };
+    }
+    const published = await publish(branch);
+    if (published.ok) return { ...salvaged, pushed: true };
+    return { ...salvaged, pushed: false, pushError: scrubUserinfo(published.stderr) };
   } catch (err) {
     return { kind: "failed", error: err instanceof Error ? err.message : String(err) };
   }
@@ -610,13 +672,22 @@ export async function removeWorktree(
   }
 
   if (existsSync(worktreePath)) {
+    // A run repo is a plain directory now, so removal is a plain removal — but
+    // the `worktree remove` is still attempted first, because a fleet upgrading
+    // into #125 has live trees that ARE linked worktrees of this mirror, and
+    // deleting one of those without deregistering it leaves the mirror
+    // believing the branch is still checked out. It refuses `worktree add` and,
+    // worse, refuses to delete the branch at cleanup. The failure is expected
+    // for a run repo and is ignored; what is not tolerated is a path that
+    // survives, since the next attempt for this issue would trip over it.
     try {
       await git(["worktree", "remove", "--force", worktreePath], mirrorPath);
-    } catch (err) {
-      // A path git does not recognise (hand-deleted, never registered) is fine
-      // for cleanup's purposes. A path that survives the attempt is not: the
-      // next run for this issue would trip over it.
-      if (existsSync(worktreePath)) throw err;
+    } catch {
+      // Not a registered worktree — the normal case from here on.
+    }
+    rmSync(worktreePath, { recursive: true, force: true });
+    if (existsSync(worktreePath)) {
+      throw new Error(`failed to remove run repository ${worktreePath}: the path still exists`);
     }
   }
 
@@ -664,6 +735,28 @@ export async function cleanupRetainedWorktree(
     await git(["fetch", "--prune", "origin"], mirrorPath);
 
     const ref = `refs/heads/${branch}`;
+
+    // **Ask the run's own repository first.** Its commits live in its own
+    // object store, not the mirror's, so a mirror-only check cannot even see
+    // them — it would answer "nothing unpushed" about a branch whose only copy
+    // is the directory this function is about to delete. That is the exact
+    // data loss #121 exists to prevent, reintroduced by the move to per-run
+    // repositories, so it is checked where the objects actually are.
+    if (existsSync(worktreePath)) {
+      await git(
+        ["fetch", "--no-tags", mirrorPath, "+refs/remotes/origin/*:refs/remotes/origin/*"],
+        worktreePath,
+      );
+      const runUnique = await git(["rev-list", ref, "--not", "--remotes"], worktreePath);
+      if (runUnique !== "") {
+        return {
+          kind: "retained",
+          reason: "unpushed",
+          detail: `${branch} has commits in the run repository that are absent from every remote ref`,
+        };
+      }
+    }
+
     if (await gitSucceeds(["show-ref", "--verify", "--quiet", ref], mirrorPath)) {
       const unique = await git(["rev-list", ref, "--not", "--remotes"], mirrorPath);
       if (unique !== "") {

package/systemd/omp-conductor.service.example

@@ -1,11 +1,13 @@
 # Example unit for a supervised omp-conductor daemon.
 #
-# Why MemoryMax exists: workers are *in-process* omp sessions inside this
-# service's MainPID (not separate processes). With the default two workers plus
-# the orchestrator session, journald on a reference 7.6 GB host recorded
-# Memory peaks of ~3.2–4.2 GB for this unit (issue #51). That is expected load,
-# not a leak — and on a shared VPS it is enough to thrash swap or OOM the
-# daemon mid-flight (orphan path).
+# Why MemoryMax exists: worker and orchestrator sessions are child processes of
+# this service (#125 moved them out of the daemon's own process so they can run
+# as a different OS principal). They stay in this unit's cgroup, so MemoryMax
+# still governs the fleet's total footprint — it is just no longer a ceiling on
+# one process. With the default two workers plus the orchestrator session,
+# journald on a reference 7.6 GB host recorded Memory peaks of ~3.2–4.2 GB for
+# this unit (issue #51). That is expected load, not a leak — and on a shared VPS
+# it is enough to thrash swap or OOM the daemon mid-flight (orphan path).
 #
 # Before enabling:
 #   1. Set User=/Group=/HOME=/PATH for the account that owns ~/.omp/conductor.
@@ -14,6 +16,66 @@
 #      consider MemoryMax=3G.
 #   4. Do not co-locate ClickHouse + other multi-GB services beside a 2-worker
 #      fleet on a ≤8 GB box.
+#   5. For credentials.isolation=per-run, do the one-time provisioning below.
+#      Without it the daemon runs unprotected (isolation=none) and says so in
+#      `omp-conductor status`.
+#
+# One-time provisioning for credentials.isolation=per-run (#125)
+# --------------------------------------------------------------
+# Model-executed code must not run as the account that holds the GitHub
+# credential. Accounts, groups, a shared root and the daemon's own home mode
+# are what make that true; environment scrubbing is only accident-prevention
+# and does not survive a determined session running as the same uid.
+#
+# Do NOT hand-copy the steps. `omp-conductor boundary-setup` prints the exact
+# idempotent commands, generated from the same constants the startup probe then
+# checks — a hand-maintained copy here would drift from what the daemon demands
+# and fail at first dispatch instead of at provisioning time. It needs no config
+# and must be run BEFORE `setup`, because setup writes worktree and mirror paths
+# into the shared root it creates:
+#
+#   omp-conductor boundary-setup --slots 2       # read what it will do
+#   omp-conductor boundary-setup --slots 2 | sudo bash
+#   sudo systemctl restart omp-conductor.service
+#
+# What it establishes, and why each part is load-bearing:
+#
+#   * conductor-agent-<n> per concurrent slot, plus conductor-agent-orch. The
+#     orchestrator's is distinct so it cannot reach a run checkout, and it is
+#     launched with no supplementary group at all.
+#   * conductor-daemon — the daemon account ONLY. Lets it fetch a run branch,
+#     salvage a killed run and reclaim the tree. A slot principal must NEVER be
+#     in it; that absence is what keeps sibling runs apart, and the probe suite
+#     asserts it from a live session.
+#   * conductor-runs — every slot. Read-only access to the shared mirror that
+#     run repos borrow objects from. A run being able to READ another run's
+#     objects there is the documented residual of sharing one object store.
+#   * /var/lib/omp-conductor, mode 0711 — worktrees, mirrors, per-run session
+#     transcripts and per-run boundary homes. OUTSIDE the state directory,
+#     because that stays 0700 (it holds conductor.db and the WAL SQLite keeps
+#     recreating, so a searchable parent would publish fleet history to every
+#     local account), and outside $HOME for the reason below.
+#   * $HOME at 0711 with credential leaves closed (.ssh, .config/gh 0700;
+#     .npmrc, .git-credentials 0600). Searchable because the runtime and the
+#     installed package live in it — a 0700 home kills every worker before it
+#     connects, and no shell-based probe notices — and closed at the leaves
+#     because that is where the boundary actually rests. The daemon re-checks
+#     this empirically at dispatch and refuses if a slot can read any
+#     credential path.
+#
+# The restart is REQUIRED, not tidiness: supplementary group membership is fixed
+# when a process starts, so without it the daemon's live credentials lack
+# conductor-daemon even though `getent` shows it, and it would chown every run
+# repo to a group it cannot itself use.
+#
+#   # util-linux, for the privilege-dropping launcher. Without it the probe
+#   # reports mechanism `none` — there is deliberately no hand-rolled
+#   # spawn({uid,gid}) fallback, because a child launched that way can hold
+#   # CAP_SETUID and setuid() straight back to a sibling run or to the daemon.
+#   sudo apt-get install -y util-linux
+#
+# Verify with `omp-conductor status`: the `boundary` row names the mechanism
+# that is actually live and lists what it does not close.
 #
 # Install:
 #   sudo install -m 0644 omp-conductor.service.example /etc/systemd/system/omp-conductor.service
@@ -34,8 +96,34 @@ User=fleet
 Group=fleet
 Environment=HOME=/home/fleet
 # systemd's default PATH has no user installs; include wherever `omp` /
-# `omp-conductor` and `gh` live on this host.
-Environment=PATH=/home/fleet/.local/bin:/usr/local/bin:/usr/bin:/bin
+# `omp-conductor`, `gh` and `setpriv` live on this host.
+Environment=PATH=/home/fleet/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin
+
+# These capabilities exist to be DROPPED INTO run children, never inherited by
+# them (#125). The daemon stays the unprivileged `fleet` account — a capability
+# grant on an existing account is a narrower blast radius than running as root
+# or shipping a setuid binary, both of which widen exactly what this exists to
+# narrow.
+#
+# Every run child is launched through `setpriv`, which sets the group list, then
+# the gid, then the uid, empties the permitted/effective/inheritable/ambient
+# capability sets, drops the bounding set, sets PR_SET_NO_NEW_PRIVS, and only
+# then execs. DO NOT "simplify" this into a raw spawn({uid,gid}): ambient
+# capabilities survive execve for ordinary binaries, so a child launched that
+# way holds CAP_SETUID itself and can setuid() back to another principal —
+# including a sibling run's. That voids the entire boundary while appearing to
+# work, which is the worst possible outcome for a security change.
+#
+# CAP_SETPCAP is present solely so the launcher can empty the child's capability
+# BOUNDING set (PR_CAPBSET_DROP requires it in the caller's own permitted set).
+# It is dropped along with everything else before the session child execs. A
+# host that refuses to grant it takes the documented fallback instead: the
+# launcher omits --bounding-set=-all, the child still ends with every other set
+# empty behind NoNewPrivs, and `status` reports the non-empty CapBnd as a named
+# residual rather than ignoring it.
+AmbientCapabilities=CAP_SETUID CAP_SETGID CAP_CHOWN CAP_FOWNER CAP_SETPCAP
+CapabilityBoundingSet=CAP_SETUID CAP_SETGID CAP_CHOWN CAP_FOWNER CAP_SETPCAP
+
 WorkingDirectory=/home/fleet
 
 # Foreground daemon so systemd tracks MainPID. `omp-conductor start` backgrounds;