omp-conductor 0.18.0 → 0.18.1

package/src/host.ts

@@ -3,9 +3,11 @@
  * or the tracker. Pure so tests pin the thresholds without a real machine.
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { DEFAULT_CAPS } from "./types.ts";
+import { availableParallelism } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { DEFAULT_CAPS, type HostConstraints } from "./types.ts";
 
 /** 16 GiB — below this, two in-process omp sessions plus the orchestrator are
  *  a measured swap risk on a shared VPS (issue #51: 3–4GB peaks on 7.6GB). */
@@ -78,6 +80,86 @@ export function workerOvercommit(total: number, ram?: number | undefined): strin
     : undefined;
 }
 
+/**
+ * CPU cores this process can actually use — affinity- and quota-aware, which
+ * is the load a worker would really get on a shared host. `undefined` mirrors
+ * {@link hostRamBytes}: the renderer simply omits the count.
+ */
+export function hostCoreCount(): number | undefined {
+  try {
+    return availableParallelism();
+  } catch {
+    return undefined;
+  }
+}
+
+/** What {@link hostFacts} reads off the host; injectable for render tests. */
+export interface HostFacts {
+  cores?: number;
+  ramBytes?: number;
+}
+
+/**
+ * The host's numbers through the module's own readers — the same
+ * {@link hostRamBytes} the capacity decision and the wizard use, plus the
+ * core count — so the rendered brief, the worker-count recommendation and
+ * the status surfaces can never disagree about the box they run on. This is
+ * the default the brief renderer reaches for; tests inject facts instead.
+ */
+export function hostFacts(): HostFacts {
+  return { cores: hostCoreCount(), ramBytes: hostRamBytes() };
+}
+
+/**
+ * The usable-size phrase the brief folds into the host line (`4 cores,
+ * 3.2 GB`); empty when the host will not say either number.
+ */
+function hostSizePhrase(facts: HostFacts): string {
+  const parts: string[] = [];
+  if (facts.cores !== undefined) parts.push(`${facts.cores} cores`);
+  if (facts.ramBytes !== undefined) parts.push(formatRss(facts.ramBytes));
+  return parts.join(", ");
+}
+
+/**
+ * The worker-brief host-constraints paragraph (#721): the typed replacement
+ * for host facts hand-written into an untracked agent context file. Cores and
+ * RAM come from {@link hostFacts} (the module's own readers) and are folded
+ * into the operator's description; the PATH and per-repo convention lines are
+ * typed config. It never names a guarded command — the shared-host notice,
+ * derived from `SHARED_HOST_SCRIPTS`, stays the only list of refused suites.
+ *
+ * Empty when nothing renders — no section, and the brief is byte-for-byte
+ * today's for a fleet that never fills the config field. `facts` is a
+ * parameter so tests pin the rendering deterministically; the dispatch default
+ * is {@link hostFacts}. The return has no trailing newline and leads with one
+ * when non-empty, so the template can render it on the line below the
+ * shared-host notice without gluing the two paragraphs.
+ */
+export function hostConstraintsNotice(
+  host: HostConstraints | undefined,
+  repoSlug: string,
+  facts: HostFacts = hostFacts(),
+): string {
+  if (host === undefined) return "";
+
+  const lines: string[] = [];
+  const description = host.description?.trim();
+  if (description !== undefined && description !== "") {
+    const size = hostSizePhrase(facts);
+    lines.push(`**Host:** ${description}${size === "" ? "" : ` (${size})`}`);
+  }
+  const path = host.path?.trim();
+  if (path !== undefined && path !== "") {
+    lines.push(`**PATH:** non-interactive invocations (scripts and \`ssh host '<cmd>'\`) must export PATH="${path}".`);
+  }
+  const convention = host.conventions?.[repoSlug]?.trim();
+  if (convention !== undefined && convention !== "") {
+    lines.push(`**Convention (${repoSlug}):** ${convention}`);
+  }
+  return lines.length === 0 ? "" : `\n${lines.join("\n\n")}`;
+}
+
 /** Compact binary units for status lines (`3.2 GB`, `430 MB`). */
 export function formatRss(bytes: number): string {
   if (!Number.isFinite(bytes) || bytes < 0) return "?";
@@ -104,3 +186,486 @@ export function rssBytesFromHealthz(body: string | undefined): number | undefine
     return undefined;
   }
 }
+
+// ------------------------------------------------------- worker identity (#798) --
+
+/**
+ * The dedicated least-privilege account every worker session runs under.
+ *
+ * `setup host` creates it and grants it exactly the paths a worker session
+ * needs; the daemon resolves it before every worker launch and refuses to
+ * dispatch when it cannot be established. A worker under this uid is a kernel
+ * identity, not a stamp: it cannot write the daemon's state (every path it
+ * needs is either chowned to it at dispatch or granted read/search-only), and
+ * it cannot migrate itself into a daemon-owned cgroup (every cgroup.procs on
+ * the host is root-owned, and cgroupfs directory ownership is what v2 gates
+ * writes with). This is the closure the rejected cgroup-namespace boundary
+ * named as required: kuid 0 with CAP_SYS_ADMIN could re-enter the initial
+ * cgroup namespace and fabricate a top-level cgroup, and a different uid is
+ * what takes that capability away.
+ */
+export const WORKER_ACCOUNT = "omp-worker";
+
+/** The worker account's system home: its harness config, caches and state. */
+export const WORKER_HOME_DIR = "/var/lib/omp-worker";
+
+/**
+ * The util-linux launcher worker sessions are spawned through. Pinned to an
+ * absolute path, never PATH-resolved: a launcher found later in the search
+ * order is a launcher an operator's environment could shadow.
+ */
+export const WORKER_SETPRIV_PATH = "/usr/bin/setpriv";
+
+/**
+ * The harness package omp-conductor loads a session from. Held here, beside
+ * the identity that has to reach it, so `omp.ts` (which imports it) and the
+ * binding checks below can never name two different packages.
+ */
+export const OMP_HARNESS_PACKAGE = "@oh-my-pi/pi-coding-agent";
+
+/** Native addon package the harness imports at runtime. */
+export const OMP_NATIVES_PACKAGE = "@oh-my-pi/pi-natives";
+
+/**
+ * Where `setup host` binds the operator's install so a worker session can
+ * resolve it (#828).
+ *
+ * Bun's node_modules resolution needs **read** permission — not merely search
+ * — on the directory that holds a `node_modules`: it enumerates the directory
+ * to decide whether the child is there. The fleet account's home is granted to
+ * the worker search-only by design (#798), so a bare `@oh-my-pi/pi-coding-agent`
+ * import from `<fleet home>/node_modules/omp-conductor` did not find the
+ * operator's install at all and fell through to Bun's auto-install, which
+ * downloaded a *different* harness version into the worker's own cache whose
+ * native addon then failed to load — every dispatch on the host stopped before
+ * session start.
+ *
+ * The fix is a read-only bind of the operator's `node_modules` at a path whose
+ * every ancestor is world-readable. Worker children are launched from it, so
+ * the entry module, the peer import and every transitive import resolve inside
+ * one tree the worker can enumerate — and, because a bind shares inodes with
+ * its source, it is the operator's exact build rather than a copy that can
+ * drift.
+ *
+ * Deliberately **not** under {@link WORKER_HOME_DIR}: the worker owns its home
+ * between setups, and a symlink planted where a root-run mount point goes would
+ * redirect that mount to an arbitrary target (#816).
+ */
+export const WORKER_HARNESS_DIR = "/var/lib/omp-worker-harness";
+
+/** The bound `node_modules` itself. The leaf name is load-bearing: it is what
+ *  Node/Bun resolution looks for walking up from the entry module. */
+export const WORKER_HARNESS_NODE_MODULES = join(WORKER_HARNESS_DIR, "node_modules");
+
+/**
+ * The install root a module path sits in — its nearest ancestor named
+ * `node_modules` — or `undefined` when it has none, which is this package
+ * running from a source checkout rather than an install.
+ */
+export function packageNodeModulesRoot(modulePath: string): string | undefined {
+  const parts = resolve(modulePath)
+    .split("/")
+    .filter((part) => part !== "");
+  const idx = parts.lastIndexOf("node_modules");
+  return idx < 0 ? undefined : `/${parts.slice(0, idx + 1).join("/")}`;
+}
+
+/**
+ * `path` as a worker session sees it through the harness binding, or
+ * `undefined` when it is not inside `packageRoot` — a test seam pointing at a
+ * file elsewhere, or a source checkout with no install root at all.
+ *
+ * Production uses {@link WORKER_HARNESS_NODE_MODULES}; an explicit binding
+ * root lets the Linux regression build the same inode-sharing tree under its
+ * private temporary directory instead of touching the live host mount.
+ */
+export function workerHarnessPath(
+  path: string,
+  packageRoot: string | undefined,
+  bindingRoot: string = WORKER_HARNESS_NODE_MODULES,
+): string | undefined {
+  if (packageRoot === undefined) return undefined;
+  const absolute = resolve(path);
+  const prefix = `${packageRoot}/`;
+  if (!absolute.startsWith(prefix)) return undefined;
+  return join(bindingRoot, absolute.slice(prefix.length));
+}
+
+/** One path's filesystem identity. Identity rather than bytes, because that is
+ *  exactly what distinguishes a live bind of the operator's install (same
+ *  device and inode) from an empty mount point or a copy that has drifted. */
+function pathIdentity(path: string): string | undefined {
+  try {
+    const st = statSync(path);
+    return `${st.dev}:${st.ino}`;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read-only facts {@link harnessBindingProblem} decides on; injected by tests. */
+export interface HarnessBindingDeps {
+  /** This module's own directory — the install root is derived from it. */
+  moduleDir?: string;
+  /** `dev:ino` of one path, or `undefined` when it cannot be stat'ed. */
+  identity?: (path: string) => string | undefined;
+  /** Alternate binding root for the isolated Linux currentness regression. */
+  bindingRoot?: string;
+}
+
+/**
+ * Why a worker session could not load the operator's harness through the
+ * binding, or `undefined` when it can.
+ *
+ * Both halves of the launch are checked, by filesystem identity: this package's
+ * own directory (the child's entry module comes from it) and the harness
+ * package directory (its peer import resolves to it). A mount point that is
+ * empty, stale, or bound to some other tree fails on the identity comparison
+ * rather than being taken on faith — which is the whole point, since the
+ * symptom this replaces was a *successful* import of the wrong build.
+ */
+export function harnessBindingProblem(deps: HarnessBindingDeps = {}): string | undefined {
+  const moduleDir = deps.moduleDir ?? import.meta.dir;
+  const identity = deps.identity ?? pathIdentity;
+  const bindingRoot = deps.bindingRoot ?? WORKER_HARNESS_NODE_MODULES;
+  const packageRoot = packageNodeModulesRoot(moduleDir);
+  if (packageRoot === undefined) {
+    return (
+      `omp-conductor is running from ${moduleDir}, which is not inside a node_modules install root — ` +
+      "a worker session resolves its harness through a read-only bind of that root, so worker dispatch " +
+      "needs the installed package (install omp-conductor with its harness peer, then re-run `omp-conductor setup host`)"
+    );
+  }
+  for (const dir of [moduleDir, join(packageRoot, OMP_HARNESS_PACKAGE)]) {
+    const source = identity(dir);
+    if (source === undefined) {
+      return (
+        `${dir} is missing or unreadable — ${OMP_HARNESS_PACKAGE} must be installed alongside omp-conductor ` +
+        "for a worker session to load the same harness build the operator runs"
+      );
+    }
+    // Non-null by construction: `dir` is inside `packageRoot`.
+    const bound = workerHarnessPath(dir, packageRoot, bindingRoot) ?? dir;
+    if (identity(bound) !== source) {
+      return (
+        `${bound} does not resolve to ${dir} — the worker harness binding of ${packageRoot} at ` +
+        `${bindingRoot} is missing or stale, so a worker session would resolve a different ` +
+        "harness build (or none). Run `omp-conductor setup host` to establish it"
+      );
+    }
+  }
+  return undefined;
+}
+
+/** One resolved worker identity: the account exactly as the host knows it. */
+export interface WorkerIdentity {
+  account: string;
+  uid: number;
+  gid: number;
+  /** The account's passwd home. */
+  home: string;
+  /** Absolute path of the identity-transition launcher. */
+  setpriv: string;
+  /** The harness agent dir for this identity: `<home>/.omp/agent`. */
+  agentDir: string;
+}
+
+export type WorkerIdentityResolution =
+  | { ok: true; identity: WorkerIdentity }
+  | { ok: false; reason: string };
+
+export interface WorkerIdentityDeps {
+  /** The resolving process's own uid; injected so tests pin the verdict. */
+  daemonUid?: number;
+  /** Whether the transition launcher exists; injected so tests pin the verdict. */
+  setprivInstalled?: boolean;
+  /** The contents of /etc/passwd; injected so tests pin the verdict. */
+  passwd?: string;
+  /**
+   * Why the worker harness binding is unusable, or `undefined` when it is
+   * live. Injected so tests pin the verdict without a real mount; production
+   * reads the host through {@link harnessBindingProblem}.
+   */
+  harnessProblem?: () => string | undefined;
+}
+
+/** Is a process uid "unprivileged" for the worker identity's purposes — never
+ *  the daemon's uid, and never root: an account that keeps uid 0 is not a
+ *  boundary, it is a costume. */
+function usableWorkerUid(uid: number, daemonUid: number): string | undefined {
+  if (uid === 0) return "the worker account must not be uid 0 (root) — an identity transition to root is not a boundary";
+  if (uid === daemonUid) return `the worker account must not share the daemon's uid ${daemonUid}`;
+  return undefined;
+}
+
+/**
+ * Resolve the worker identity the daemon launches worker sessions under.
+ *
+ * This is the launch gate's input, resolved before every worker launch and at
+ * daemon startup for the banner. Every failure mode is a *reason*, never a
+ * throw: dispatch turns a missing account into a failed closed run (with this
+ * reason in the report and the escalation), so the operator hears exactly
+ * which host change is missing. A daemon that cannot transition — not running
+ * as root, or a host without setpriv — refuses to launch workers rather than
+ * running them unbound.
+ */
+export function resolveWorkerIdentity(deps: WorkerIdentityDeps = {}): WorkerIdentityResolution {
+  const daemonUid = deps.daemonUid ?? process.getuid?.() ?? 0;
+  if (daemonUid !== 0) {
+    return {
+      ok: false,
+      reason:
+        `the daemon runs as uid ${daemonUid}; only root can transition a child to another uid, ` +
+        "so worker sessions cannot be launched under the dedicated identity",
+    };
+  }
+  const setpriv = WORKER_SETPRIV_PATH;
+  const setprivInstalled = deps.setprivInstalled ?? existsSync(setpriv);
+  if (!setprivInstalled) {
+    return {
+      ok: false,
+      reason: `${setpriv} (util-linux setpriv) is not installed on this host — worker sessions cannot be launched under the dedicated identity`,
+    };
+  }
+  let passwd: string;
+  try {
+    passwd = deps.passwd ?? readFileSync("/etc/passwd", "utf8");
+  } catch {
+    return { ok: false, reason: `cannot read /etc/passwd while resolving the ${WORKER_ACCOUNT} identity` };
+  }
+  // `user:passwd:uid:gid:gecos:home:shell` — the whole line, never a prefix
+  // match, so a friendly lookalike account cannot satisfy the resolution.
+  const line = passwd.split("\n").find((entry) => entry.startsWith(`${WORKER_ACCOUNT}:`));
+  if (line === undefined) {
+    return {
+      ok: false,
+      reason:
+        `the ${WORKER_ACCOUNT} account does not exist on this host — run \`omp-conductor setup host\` ` +
+        "to create the dedicated worker identity",
+    };
+  }
+  const fields = line.split(":");
+  const uid = Number(fields[2]);
+  const gid = Number(fields[3]);
+  const home = fields[5] ?? "";
+  if (!Number.isInteger(uid) || uid < 0) {
+    return { ok: false, reason: `the ${WORKER_ACCOUNT} account has an unusable uid in /etc/passwd` };
+  }
+  if (!Number.isInteger(gid) || gid < 0) {
+    return { ok: false, reason: `the ${WORKER_ACCOUNT} account has an unusable gid in /etc/passwd` };
+  }
+  const problem = usableWorkerUid(uid, daemonUid);
+  if (problem !== undefined) return { ok: false, reason: problem };
+  if (home === "" || !home.startsWith("/")) {
+    return { ok: false, reason: `the ${WORKER_ACCOUNT} account has no absolute home in /etc/passwd` };
+  }
+  // Last, because it is the check the operator can only act on once the
+  // account is there: without a live bind of the operator's install, a worker
+  // child resolves its harness from Bun's auto-install cache instead — a
+  // different build whose native addon does not load (#828). Refusing here
+  // fails the launch closed with the fix, rather than letting every dispatch
+  // die inside a session it already paid to start.
+  const harnessProblem = deps.harnessProblem === undefined ? harnessBindingProblem() : deps.harnessProblem();
+  if (harnessProblem !== undefined) return { ok: false, reason: harnessProblem };
+  return {
+    ok: true,
+    identity: {
+      account: WORKER_ACCOUNT,
+      uid,
+      gid,
+      home,
+      setpriv,
+      agentDir: join(home, ".omp", "agent"),
+    },
+  };
+}
+
+/**
+ * The argv that launches a payload under the worker identity — the transition
+ * happens in the kernel at setpriv, BEFORE the first byte of any payload code
+ * runs, and setpriv does not exec the payload unless the transition succeeded
+ * (a failure exits non-zero with the reason on stderr, and the calling run
+ * settles failed with no live child). `--` protects a payload argv[0] that
+ * starts with `-`.
+ *
+ * A payload whose target uid/gid already equal this process's is returned
+ * unchanged: the identity is already in force, and spawning setpriv would
+ * only fail needlessly on a host without setuid privileges. That is also the
+ * only way the parity suite can drive the full spawn path as a non-root CI
+ * user.
+ */
+export function workerLaunchArgv(
+  payloadArgv: readonly string[],
+  identity: WorkerIdentity | undefined,
+  currentUid: number = process.getuid?.() ?? 0,
+  currentGid: number = process.getgid?.() ?? 0,
+): string[] {
+  if (identity === undefined) return [...payloadArgv];
+  if (identity.uid === currentUid && identity.gid === currentGid) return [...payloadArgv];
+  // `--init-groups` initialises the supplementary groups from the identity
+  // being dropped to. It deliberately takes NO account operand (util-linux
+  // 2.39; newer versions accept an optional one): appending the account after
+  // it would be parsed as the program to exec on 2.39 and the launch would
+  // die with "failed to execute <account>" before any identity was dropped.
+  return [
+    identity.setpriv,
+    "--reuid",
+    identity.account,
+    "--regid",
+    identity.account,
+    "--init-groups",
+    "--",
+    ...payloadArgv,
+  ];
+}
+
+/**
+ * The environment a worker session child runs with: the daemon's, with the
+ * worker's own HOME (a worker under /root's HOME would try to write the
+ * daemon's home), its own harness agent dir (so config discovery is
+ * deterministic whatever the parent's environment says), and its own
+ * conductor state root (the worker's `omp-conductor` CLI reads its own empty
+ * store instead of the daemon's — the daemon's DB is daemon state, not
+ * worker input).
+ */
+export function workerSessionEnv(
+  base: Record<string, string | undefined>,
+  identity: WorkerIdentity,
+): Record<string, string | undefined> {
+  return {
+    ...base,
+    HOME: identity.home,
+    PI_CODING_AGENT_DIR: identity.agentDir,
+    OMP_CONDUCTOR_HOME: join(identity.home, ".omp", "conductor"),
+  };
+}
+
+export interface WorkerHarnessImportOptions {
+  bun?: string;
+  moduleDir?: string;
+  bindingRoot?: string;
+  identity?: WorkerIdentity;
+  timeoutMs?: number;
+}
+
+/**
+ * Run the anchored harness loader through the worker's real HOME and setpriv
+ * transition. Setup uses this after the inode checks: a mount can be current
+ * while ambient Bun resolution still chooses its install cache (#828).
+ */
+export function workerHarnessImportProblem(
+  options: WorkerHarnessImportOptions = {},
+): string | undefined {
+  const bun = options.bun ?? process.execPath;
+  const moduleDir = options.moduleDir ?? import.meta.dir;
+  const bindingRoot = options.bindingRoot ?? WORKER_HARNESS_NODE_MODULES;
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  const packageRoot = packageNodeModulesRoot(moduleDir);
+  if (packageRoot === undefined) {
+    return `cannot probe the worker harness import because ${moduleDir} is not inside a node_modules install root`;
+  }
+  let identity = options.identity;
+  if (identity === undefined) {
+    const resolved = resolveWorkerIdentity({ harnessProblem: () => undefined });
+    if (!resolved.ok) return resolved.reason;
+    identity = resolved.identity;
+  }
+
+  let sourceHarness: string;
+  let sourceNative: string;
+  let expectedVersion: string;
+  try {
+    sourceHarness = Bun.resolveSync(OMP_HARNESS_PACKAGE, moduleDir);
+    sourceNative = Bun.resolveSync(OMP_NATIVES_PACKAGE, dirname(sourceHarness));
+    const parsed: unknown = JSON.parse(
+      readFileSync(join(packageRoot, OMP_HARNESS_PACKAGE, "package.json"), "utf8"),
+    );
+    if (parsed === null || typeof parsed !== "object") throw new Error("package metadata is not an object");
+    const version = Reflect.get(parsed, "version");
+    if (typeof version !== "string" || version === "") throw new Error("package version is absent");
+    expectedVersion = version;
+  } catch (cause) {
+    return `cannot resolve the operator's installed harness for the worker probe: ${cause instanceof Error ? cause.message : String(cause)}`;
+  }
+
+  const probe = workerHarnessPath(join(moduleDir, "harness-loader.ts"), packageRoot, bindingRoot);
+  const expectedHarness = workerHarnessPath(sourceHarness, packageRoot, bindingRoot);
+  const expectedNative = workerHarnessPath(sourceNative, packageRoot, bindingRoot);
+  if (probe === undefined || expectedHarness === undefined || expectedNative === undefined) {
+    return "cannot map the installed harness probe through the worker binding";
+  }
+  const argv = workerLaunchArgv([bun, "--no-install", probe], identity);
+  const command = argv[0];
+  if (command === undefined) return "cannot launch the worker harness probe: its argv is empty";
+  const ran = spawnSync(command, argv.slice(1), {
+    cwd: identity.home,
+    env: workerSessionEnv(process.env, identity),
+    encoding: "utf8",
+    timeout: timeoutMs,
+    killSignal: "SIGKILL",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const errorCode = ran.error === undefined ? undefined : Reflect.get(ran.error, "code");
+  if (errorCode === "ETIMEDOUT") {
+    return `the worker harness import probe timed out after ${timeoutMs} ms`;
+  }
+  if (ran.status !== 0) {
+    const detail =
+      `${ran.error?.message ?? ""}\n${ran.stderr ?? ""}${ran.stdout ?? ""}`.trim();
+    return (
+      "the worker identity cannot import the operator's harness and native addon through the binding" +
+      (detail === "" ? "" : `: ${detail}`)
+    );
+  }
+
+  let report: unknown;
+  try {
+    const line = (ran.stdout ?? "").trim().split("\n").at(-1);
+    report = JSON.parse(line ?? "");
+  } catch {
+    return "the worker harness import probe returned no readable attestation";
+  }
+  if (report === null || typeof report !== "object") {
+    return "the worker harness import probe returned no readable attestation";
+  }
+  const loadedPath = Reflect.get(report, "path");
+  const loadedVersion = Reflect.get(report, "version");
+  const nativePath = Reflect.get(report, "nativePath");
+  if (
+    loadedPath !== expectedHarness ||
+    loadedVersion !== expectedVersion ||
+    nativePath !== expectedNative
+  ) {
+    return (
+      `the worker harness import resolved ${String(loadedPath)} at version ${String(loadedVersion)} ` +
+      `with native addon ${String(nativePath)}, expected ${expectedHarness} at version ${expectedVersion} ` +
+      `with ${expectedNative}`
+    );
+  }
+  return undefined;
+}
+
+/**
+ * Why the current process does not satisfy the identity its launch spec
+ * required, or `undefined` when it does. The session child's first act, as
+ * early as there is a socket to report over: a child whose kernel identity is
+ * not the one it was launched for proves the boundary did not hold and must
+ * refuse to run worker code. The uid/gid getters default to this process's
+ * own, and are parameters so the check is testable without spawning.
+ */
+export function identityMismatch(
+  expected: { uid: number; gid: number } | undefined,
+  getuid: () => number = () => process.getuid?.() ?? 0,
+  getgid: () => number = () => process.getgid?.() ?? 0,
+): string | undefined {
+  if (expected === undefined) return undefined;
+  const uid = getuid();
+  const gid = getgid();
+  if (uid !== expected.uid || gid !== expected.gid) {
+    return (
+      `worker identity mismatch: running as uid ${uid} gid ${gid}, but this session was launched ` +
+      `for uid ${expected.uid} gid ${expected.gid} — the identity transition did not hold, refusing to start`
+    );
+  }
+  return undefined;
+}