omp-conductor 0.5.3 → 0.5.6

package/README.md

@@ -2028,7 +2028,7 @@ dispatcher. The brief is explicit about the boundary:
 | Add or update tests for behaviour it introduced. | Suppress a warning, delete an assertion, or special-case an input to make a check pass. |
 | Run the repo's configured cheap gates, each from its listed `cwd`, over the whole tree. | Run docker or image builds, production builds, browser/e2e suites, or the full test suite on the shared host — CI owns the heavy gates. |
 | Review its whole diff, then commit and publish once with `conductor_push`. One corrective push if CI is red. | Force-push, `git add -f`, or add AI/co-author attribution. There is no force path to reach: `conductor_push` publishes that run's branch fast-forward only and takes no other ref. Red twice means stop and report, not push a third time. |
-| Open a PR with `conductor_pr_create`, and poll CI to a verdict with `conductor_pr_status`. | Run `gh pr merge` — or reach `conductor_pr_merge`, which refuses a worker session mechanically. **A worker is never authorised to merge**, whoever else holds the authority, so PRs land one at a time with a freshness re-check; two workers merging concurrently is how agent PRs clobber each other. Who *may* merge is the [`authority`](#configuration) answer, and it is never the worker. The verb refusal is mechanical; reaching for `gh` instead is a prohibition, and one that shows up as a merge absent from the [ledger](#the-ledger). |
+| Open a PR with `conductor_pr_create`, and poll CI to a verdict with `conductor_pr_status`. | Run `gh pr merge` — or reach `conductor_pr_merge`, which refuses a worker session mechanically. **A worker is never authorised to merge**, whoever else holds the authority, so PRs land one at a time with a freshness re-check; two workers merging concurrently is how agent PRs clobber each other. Who *may* merge is the [`authority`](#configuration) answer, and it is never the worker. The verb refusal is mechanical, and so is the channel: each one is bound to the pid the daemon spawned, so reaching for the orchestrator's socket is refused rather than honoured (see [The transport](#the-transport)). Shelling out to `gh` remains a prohibition, not an impossibility — a session shares the daemon's credentials. |
 | Escalate: ambiguity, a cross-repo contract, a needed credential, a product or data-migration decision, a blocking existing test, CI red twice, or most of the wall-clock budget burned. | Cut a release, push a tag, publish to npm, edit a deployment pin, deploy, or touch infrastructure or secrets. `conductor_release` and `conductor_label` refuse a worker whatever `releasePolicy` says, because the check compares the caller against the configured holder rather than ruling one value out. The in-session tripwire still blocks recognised release/deploy tool calls early and audits the attempt, but it is [defence in depth](#the-mediated-verbs-126), not the gate. |
 
 The worker ends with a seven-line evidence report (issue, PR, observed head SHA,
@@ -2149,10 +2149,31 @@ every release shape under the most permissive config there is.
 ### The transport
 
 Identity is never an argument. `project`, `run`, `issue` and the caller's role
-come from **which socket the call arrived on** plus the verified peer uid, and a
-request carrying any of those field names is refused outright, named. So a worker
-on run X cannot *ask* to merge run Y's PR: on its own channel that request is
-unexpressible, and a merge is refused for a worker session on any channel.
+come from **which socket the call arrived on**, and a request carrying any of
+those field names is refused outright, named. So a worker on run X cannot *ask*
+to merge run Y's PR — on its own channel that request is unexpressible.
+
+**Each channel is bound to one process, because the modes cannot tell sessions
+apart.** Every session runs as the daemon's own uid, so it matches the *owner*
+class here: it can list this directory and connect to any socket in it, including
+the orchestrator's. Authorisation and the ledger both read the role from the
+channel, so a worker doing that would have been authorised as the orchestrator
+(under `authority.merge: "orchestrator"`) *and recorded as* the orchestrator. No
+file mode closes that — the owner bits belong to the uid the session already has.
+
+So the daemon binds each channel to the **pid it spawned for that session**, and
+refuses a connection from anything else without answering it, logged the way an
+impersonation is. Until a channel is bound it refuses everything, because the
+socket necessarily exists before the child that connects to it. The kernel
+supplies the pid: `SO_PEERCRED` on Linux, `LOCAL_PEERPID` on macOS. A host where
+neither can be asked — no loadable libc, or the call refused — refuses every
+connection on a bound channel and says so at startup, rather than falling back to
+the uid, which under one shared uid is no check at all.
+
+The residual is narrow, real, and worth stating: one uid can `ptrace` and signal
+its siblings, so a determined session can still interfere with the process that
+*is* bound. That is a far higher bar than connecting to a socket, and closing it
+needs separate OS principals.
 
 ```
 <state dir>/verbs/                 daemon-owned, mode 0711
@@ -2298,9 +2319,12 @@ Known and deliberate in this version:
 - **Workers stop at green PRs.** They are never authorised to merge, release or
   deploy: those actions default to a human, and while setup may grant either to
   the orchestrator, `authority` never grants them to a worker or the dispatch
-  daemon. The verbs refuse a worker mechanically. A session that shells out
-  instead is violating its brief rather than defeating a gate — sessions inherit
-  the daemon's credentials — and the missing ledger entry is the evidence.
+  daemon. The verbs refuse a worker mechanically, and a worker reaching for
+  another session's channel is refused too — each channel is bound to the pid the
+  daemon spawned for it. What remains a prohibition rather than a gate is shelling
+  out to `gh` directly: sessions inherit the daemon's credentials. That shows up as
+  a mutation with no matching ledger entry, which is a mismatch an operator can
+  find.
 - **The worker gate is partial, and the orchestrator has none.** A worker's
   structured `write` / `edit` / `read` / `grep` / `glob` calls are gated to its
   worktree by an inline harness extension; `bash` is not, so a shell one-liner

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.5.3",
+  "version": "0.5.6",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/src/daemon.ts

@@ -976,6 +976,14 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
         // a child process of the daemon reaches it directly.
         socketPath: join(sessionDir, "ipc.sock"),
         verbSocketPath: verbListener.path,
+        // Names this run's channel the instant the child exists. Until this
+        // fires the channel refuses every connection, because a session that
+        // reached it first would be one nobody had identified — and every
+        // session shares this daemon's uid, so the socket alone cannot tell
+        // them apart (#163).
+        onSpawn: (pid) => {
+          verbListener?.bindPid(pid);
+        },
         onChildLog: (line) => {
           log(`#${issue} ${line}`);
         },
@@ -3045,10 +3053,14 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
       const orchCwd = join(orchTreeRoot, "orchestrator");
       mkdirSync(orchCwd, { recursive: true });
       // A third socket, distinct from every run's, in the same daemon-owned
-      // 0711 parent. This is what makes "merge authority is the orchestrator's"
-      // a property of the channel: the daemon knows which session is speaking
-      // because of where the connection arrived, and no payload can move a
-      // worker's call onto this one (#126).
+      // 0711 parent. It makes the orchestrator's authority a property of the
+      // channel rather than of a payload: no argument list can move a worker's
+      // call onto this one (#126).
+      //
+      // It does NOT authenticate the session. Sessions share this daemon's uid,
+      // so one could list this directory and connect here, and the ledger would
+      // record the orchestrator's role because that is the channel's. See
+      // conductor#163 for the pid binding that would close it.
       orchestratorVerbs = await listenVerbChannel(
         verbDeps({ project, store, tracker, verbActions }),
         {
@@ -3065,6 +3077,12 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
         releaseGrants,
         socketPath: join(orchCwd, "ipc.sock"),
         verbSocketPath: orchestratorVerbs.path,
+        // The orchestrator's channel is the one that matters most: it is the
+        // session authorised to merge, so an unbound channel here is a worker's
+        // route to that authority (#163).
+        onSpawn: (pid) => {
+          orchestratorVerbs?.bindPid(pid);
+        },
         onChildLog: (line) => {
           log(`orchestrator ${line}`);
         },

package/src/omp.ts

@@ -361,6 +361,13 @@ const START_TIMEOUT_MS = 180_000;
 /** Bounded tail of the child's stderr, so a crash is legible without unbounded buffering. */
 const STDERR_TAIL = 8_000;
 
+/**
+ * How long a dying child's pipes get to finish before its failure is reported
+ * without them. Generous because it only ever delays an already-failed startup,
+ * and the streams normally reach EOF the instant the process does.
+ */
+const DRAIN_GRACE_MS = 2_000;
+
 /** How long a disposed child gets to exit before it is signalled. */
 const DISPOSE_GRACE_MS = 5_000;
 
@@ -388,6 +395,14 @@ export interface CreateSessionOptions {
    * session plumbing an attack surface for verbs.
    */
   verbSocketPath?: string;
+  /**
+   * The child's pid, the instant it exists.
+   *
+   * Called synchronously after `Bun.spawn` and before the child could have
+   * connected to anything, because that ordering is the point: the daemon binds
+   * its verb channel to this pid, and a channel accepts nothing until it is bound.
+   */
+  onSpawn?: (pid: number) => void;
   /** Child stderr, line by line. Defaults to the process's own stderr. */
   onChildLog?: (line: string) => void;
   startupTimeoutMs?: number;
@@ -483,6 +498,10 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
     stderr: "pipe",
   });
 
+  // Synchronously, before a single await: the child cannot have connected yet, so
+  // the caller's channel is bound before it can be reached.
+  if (child.pid !== undefined) opts.onSpawn?.(child.pid);
+
   let stderrTail = "";
   const drain = async (stream: ReadableStream<Uint8Array> | undefined, prefix: string): Promise<void> => {
     if (stream === undefined) return;
@@ -499,8 +518,35 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
       }
     }
   };
-  void drain(child.stdout, "session: ");
-  void drain(child.stderr, "session: ");
+  // Kept, not discarded: the child's own stderr is the whole value of the startup
+  // failure path, and it is a *race* against `child.exited` rather than a
+  // guarantee. A child that dies before connecting resolves `exited` as soon as
+  // the process is gone, which can be before these loops have read what it
+  // printed on the way out — and then the operator gets "exited 1" instead of the
+  // reason, which is precisely the diagnosis this path exists to give. Observed
+  // failing on ubuntu and passing on darwin, which is what a race looks like.
+  const drained = Promise.all([drain(child.stdout, "session: "), drain(child.stderr, "session: ")]);
+  drained.catch(() => undefined);
+
+  /**
+   * The child's output, once the pipes have actually finished — the whole point of
+   * every failure path below.
+   *
+   * Bounded rather than awaited outright: a grandchild that inherited stderr keeps
+   * the pipe open after the child is gone, and a failure nobody reports is worse
+   * than one reported without its tail. Both exit routes go through here so they
+   * cannot drift apart again; the pre-connect one did, which is how a release run
+   * caught this.
+   */
+  const settledTail = async (): Promise<string> => {
+    await Promise.race([
+      drained,
+      new Promise<void>((resolve) => {
+        setTimeout(resolve, DRAIN_GRACE_MS).unref?.();
+      }),
+    ]);
+    return stderrTail.trim();
+  };
 
   const cleanup = (): void => {
     server.close();
@@ -532,7 +578,7 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
     pending.clear();
   };
 
-  void child.exited.then((code) => {
+  void child.exited.then(async (code) => {
     onExit();
     cleanup();
     // A child that exits during teardown exited because we asked it to. Only an
@@ -540,6 +586,8 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
     // to reach whoever is awaiting a prompt, or the dispatcher waits forever
     // for a turn from a process that is gone.
     if (disposing) return;
+    // The tail first, so the message carries the child's own words.
+    await settledTail();
     fail(`omp-conductor session child exited ${String(code)} before the session ended`);
   });
 
@@ -565,7 +613,11 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
   } catch (err) {
     child.kill("SIGKILL");
     cleanup();
-    const tail = stderrTail.trim();
+    // Killed first, so the pipes are already closing, and only then read. This is
+    // the route a child that dies before connecting takes — a missing peer
+    // dependency, say — and reading `stderrTail` synchronously here raced the
+    // drain loops and reported a bare exit code instead of the reason.
+    const tail = await settledTail();
     throw new Error(
       `${err instanceof Error ? err.message : String(err)}${tail === "" ? "" : `\nchild output:\n${tail}`}`,
     );

package/src/orchestrator.ts

@@ -47,6 +47,7 @@ export type CreateSessionFn = (opts: {
   role: SessionRole;
   releaseGrants?: ResolvedGrants;
   onReleaseBlocked?: (shape: ReleaseShape) => void;
+  onSpawn?: (pid: number) => void;
   socketPath?: string;
   verbSocketPath?: string;
   onChildLog?: (line: string) => void;
@@ -84,6 +85,8 @@ export interface OrchestratorOpts {
   model?: string;
   releaseGrants?: ResolvedGrants;
   onReleaseBlocked?: (shape: ReleaseShape) => void;
+  /** The child's pid, the instant it exists. See {@link VerbListener.bindPid}. */
+  onSpawn?: (pid: number) => void;
   /** Control socket for the session child, beside its own working directory. */
   socketPath?: string;
   /**
@@ -180,6 +183,7 @@ export async function startOrchestrator(o: OrchestratorOpts): Promise<Orchestrat
     role: "orchestrator",
     ...(o.releaseGrants === undefined ? {} : { releaseGrants: o.releaseGrants }),
     ...(o.onReleaseBlocked === undefined ? {} : { onReleaseBlocked: o.onReleaseBlocked }),
+    ...(o.onSpawn === undefined ? {} : { onSpawn: o.onSpawn }),
     ...(o.socketPath === undefined ? {} : { socketPath: o.socketPath }),
     ...(o.verbSocketPath === undefined ? {} : { verbSocketPath: o.verbSocketPath }),
     ...(o.onChildLog === undefined ? {} : { onChildLog: o.onChildLog }),

package/src/verbs/server.ts

@@ -10,10 +10,24 @@
  * Four rules shape the order of the checks, and each is here because prose
  * alone did not hold it on `main`:
  *
- *  - **Identity is the channel's.** `project`, `run`, `issue` and role come from
- *    {@link VerbChannel} — which socket the call arrived on, plus the verified
- *    peer uid. A worker's channel names exactly one run, so "merge run Y's PR"
- *    is not a request this daemon can be sent from run X. It is unexpressible.
+ *  - **Identity is the channel's, and the channel is bound to one process.**
+ *    `project`, `run`, `issue` and role come from {@link VerbChannel} — which
+ *    socket the call arrived on. No payload can name them, so a *request* to act
+ *    as another run is unexpressible.
+ *
+ *    That alone was never authentication: every session runs as the daemon's own
+ *    uid, so any of them could list the socket directory and connect to another
+ *    channel — including the orchestrator's, which holds merge under
+ *    `authority.merge: "orchestrator"` — and the ledger would have recorded the
+ *    channel's role, attributing it to the orchestrator. A file mode cannot fix
+ *    that, because the owner bits belong to the uid the session already has.
+ *
+ *    So each channel is **bound to the pid the daemon spawned for it**, and a
+ *    connection from any other process is refused unanswered and logged. Until it
+ *    is bound it refuses everything, because the socket necessarily exists before
+ *    the child does. The residual is narrow and real: one uid can still `ptrace`
+ *    or signal its siblings, so a determined session can interfere with the
+ *    process that *is* bound — a much higher bar than connecting to a socket.
  *  - **Compared against the configured holder, never against one forbidden
  *    value.** `authority` has exactly two holders, so `!== "human"` would let a
  *    worker release. Merge and release both ask "is the caller the holder".
@@ -53,6 +67,7 @@ import {
   unlinkStaleSocket,
   validateSocketPath,
   type PeerReader,
+  type PeerVerdict,
   type SocketOwnership,
 } from "./socket.ts";
 
@@ -915,6 +930,17 @@ async function prStatusVerb(
 export interface VerbListener {
   path: string;
   ownership: SocketOwnership;
+  /**
+   * Name the process this channel belongs to.
+   *
+   * Called with the child's pid the moment the daemon has spawned it, and the
+   * channel refuses every connection until it is: the socket has to exist before
+   * the child can connect to it, so there is a window between `listen` and the
+   * spawn, and a session that connected in that window would be one nobody had
+   * identified. `Bun.spawn` returns the pid synchronously, so the window closes
+   * before the child has finished booting.
+   */
+  bindPid(pid: number): void;
   close(): Promise<void>;
 }
 
@@ -964,8 +990,13 @@ export async function listenVerbChannel(
   // here and a race in a world-writable directory.
   unlinkStaleSocket(channel.path);
 
+  // Unbound until the daemon names the child. Read through a closure rather than
+  // captured by value so the connection handler sees the binding that exists when
+  // a connection arrives, not the one that existed when the server was created.
+  let boundPid: number | undefined;
+
   const server: Server = createServer((socket) => {
-    handleConnection(deps, channel, socket, opts.peerReader);
+    handleConnection(deps, channel, socket, opts.peerReader, () => boundPid);
   });
   server.on("error", (err) => {
     deps.log(`verb socket ${channel.path} errored: ${err.message}`);
@@ -985,6 +1016,9 @@ export async function listenVerbChannel(
   return {
     path: channel.path,
     ownership,
+    bindPid: (pid) => {
+      boundPid = pid;
+    },
     close: async () => {
       await new Promise<void>((resolve) => {
         server.close(() => {
@@ -1001,10 +1035,29 @@ function handleConnection(
   channel: VerbChannel,
   socket: Socket,
   peerReader: PeerReader | undefined,
+  boundPid: () => number | undefined,
 ): void {
   const fd = socketFd(socket);
   const peer = fd === undefined || peerReader === undefined ? undefined : peerReader(fd);
-  const verdict = peerVerdict({ uid: process.getuid?.() ?? 0 }, peer);
+  const expectedPid = boundPid();
+  // Refused until the daemon has named the process this channel belongs to.
+  //
+  // The socket must exist before the child can connect to it, so there is a real
+  // window between `listen` and the spawn — and any session already running shares
+  // this daemon's uid, so one of them could reach a freshly bound orchestrator
+  // channel in that window and be authorised as the orchestrator. Nothing about
+  // the socket distinguishes them; only the pid does (#163).
+  const verdict: PeerVerdict =
+    expectedPid === undefined
+      ? {
+          ok: false,
+          peerUid: peer?.uid ?? -1,
+          expectedUid: process.getuid?.() ?? 0,
+          detail:
+            "this channel has not been bound to a process yet, so the caller cannot be identified — " +
+            "every session on this host shares the daemon's uid",
+        }
+      : peerVerdict({ uid: process.getuid?.() ?? 0, pid: expectedPid }, peer);
   if (!verdict.ok) {
     // Not a client error, and deliberately not answered: a caller who is not
     // who the socket was allocated to gets no reply to calibrate against.

package/src/verbs/socket.ts

@@ -236,6 +236,18 @@ export function secureBoundSocket(
 export interface PeerCredentials {
   uid: number;
   gid: number;
+  /**
+   * The connecting process, as the kernel reports it.
+   *
+   * The uid alone stopped meaning anything the moment sessions began sharing the
+   * daemon's account: every session satisfies it. The pid is what distinguishes
+   * them, because the daemon spawned each one and knows which is which.
+   *
+   * `undefined` only when the platform call failed. It is not optional in the
+   * sense of "nice to have" — {@link peerVerdict} refuses a channel whose pid it
+   * expected and could not read.
+   */
+  pid?: number;
 }
 
 /**
@@ -243,9 +255,9 @@ export interface PeerCredentials {
  * `undefined` where the platform (or this runtime's socket object) does not
  * expose them.
  *
- * `getpeereid` on darwin, `SO_PEERCRED` on Linux — both asked of the kernel,
- * which is the point: the answer cannot be forged by the peer, unlike anything
- * the peer could put in a payload.
+ * `SO_PEERCRED` on Linux, `getpeereid` plus `LOCAL_PEERPID` on darwin — all asked
+ * of the kernel, which is the point: the answer cannot be forged by the peer,
+ * unlike anything the peer could put in a payload.
  */
 export type PeerReader = (fd: number) => PeerCredentials | undefined;
 
@@ -258,6 +270,10 @@ interface LibcSymbols {
 const SOL_SOCKET_LINUX = 1;
 const SO_PEERCRED_LINUX = 17;
 
+/** `SOL_LOCAL` / `LOCAL_PEERPID` from darwin's `sys/un.h`. Also ABI constants. */
+const SOL_LOCAL_DARWIN = 0;
+const LOCAL_PEERPID_DARWIN = 0x002;
+
 /**
  * The peer reader for this host, or `undefined` when there is none.
  *
@@ -271,7 +287,14 @@ const SO_PEERCRED_LINUX = 17;
 export function peerCredentialReader(): PeerReader | undefined {
   const declarations: Record<string, { args: FFIType[]; returns: FFIType }> =
     process.platform === "darwin"
-      ? { getpeereid: { args: [FFIType.i32, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 } }
+      ? {
+          getpeereid: { args: [FFIType.i32, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+          // For LOCAL_PEERPID: `getpeereid` answers uid and gid, and nothing else.
+          getsockopt: {
+            args: [FFIType.i32, FFIType.i32, FFIType.i32, FFIType.ptr, FFIType.ptr],
+            returns: FFIType.i32,
+          },
+        }
       : {
           getsockopt: {
             args: [FFIType.i32, FFIType.i32, FFIType.i32, FFIType.ptr, FFIType.ptr],
@@ -302,12 +325,21 @@ export function peerCredentialReader(): PeerReader | undefined {
 
   if (process.platform === "darwin") {
     const getpeereid = symbols.getpeereid;
+    const getsockoptDarwin = symbols.getsockopt;
     if (getpeereid === undefined) return undefined;
     return (fd) => {
       const uid = new Uint32Array(1);
       const gid = new Uint32Array(1);
       if (getpeereid(fd, ptr(uid), ptr(gid)) !== 0) return undefined;
-      return { uid: uid[0] ?? -1, gid: gid[0] ?? -1 };
+      let pid: number | undefined;
+      if (getsockoptDarwin !== undefined) {
+        const out = new Uint32Array(1);
+        const len = new Uint32Array([out.byteLength]);
+        if (getsockoptDarwin(fd, SOL_LOCAL_DARWIN, LOCAL_PEERPID_DARWIN, ptr(out), ptr(len)) === 0) {
+          pid = out[0];
+        }
+      }
+      return { uid: uid[0] ?? -1, gid: gid[0] ?? -1, ...(pid === undefined ? {} : { pid }) };
     };
   }
 
@@ -320,7 +352,8 @@ export function peerCredentialReader(): PeerReader | undefined {
     if (getsockopt(fd, SOL_SOCKET_LINUX, SO_PEERCRED_LINUX, ptr(cred), ptr(len)) !== 0) {
       return undefined;
     }
-    return { uid: cred[1] ?? -1, gid: cred[2] ?? -1 };
+    // struct ucred's first field is the pid, and it has been read all along.
+    return { uid: cred[1] ?? -1, gid: cred[2] ?? -1, ...(cred[0] === undefined ? {} : { pid: cred[0] }) };
   };
 }
 
@@ -339,22 +372,37 @@ export function socketFd(socket: unknown): number | undefined {
 }
 
 export type PeerVerdict =
+  | { ok: true; basis: "peer-pid"; uid: number; pid: number }
   | { ok: true; basis: "peer-uid"; uid: number }
   | { ok: true; basis: "socket-ownership"; why: string }
   | { ok: false; detail: string; peerUid: number; expectedUid: number };
 
 /**
- * Compare the kernel-reported peer against the uid the daemon allocated.
+ * Compare the kernel-reported peer against the session the daemon launched.
  *
- * The two `ok` bases are not the same guarantee and are deliberately not
- * collapsed. `peer-uid` means the kernel vouched for the caller. `socket-
- * ownership` means nobody could vouch and the whole guarantee is the `0600`
- * socket under an unlistable, daemon-owned, non-writable parent — which is
- * real, but it does not distinguish two runs sharing one uid. A caller that
- * printed "verified" for both would be claiming something it never checked.
+ * The three `ok` bases are different guarantees and are deliberately not
+ * collapsed:
+ *
+ * - `peer-pid` — the kernel says this connection comes from the exact process the
+ *   daemon spawned for this channel. This is the only basis that distinguishes one
+ *   session from another, because they all share the daemon's uid.
+ * - `peer-uid` — the uid matched but no pid was expected for this channel. True of
+ *   a channel nothing was bound to, which in production is a bug and in a test is
+ *   the case under test.
+ * - `socket-ownership` — nobody could vouch at all, and the whole guarantee is the
+ *   `0600` socket under an unlistable, daemon-owned parent. Real against other
+ *   accounts, and no help between sessions.
+ *
+ * A caller that printed "verified" for all three would be claiming something it
+ * never checked, which is exactly how the channel came to be described as
+ * authentication when it was only ever context.
+ *
+ * **Fail closed on doubt.** If a pid was expected and the kernel would not answer,
+ * that is a refusal: on a host where the check normally works, "could not ask"
+ * arriving on the one connection that matters is not a reason to allow it.
  */
 export function peerVerdict(
-  expected: { uid: number } | undefined,
+  expected: { uid: number; pid?: number } | undefined,
   peer: PeerCredentials | undefined,
 ): PeerVerdict {
   if (expected === undefined) {
@@ -365,10 +413,29 @@ export function peerVerdict(
     };
   }
   if (peer === undefined) {
+    // A channel bound to a process and no way to identify the caller is the one
+    // combination that must never pass. Under one uid the mode says nothing about
+    // *which* session is connecting, so allowing here would hand any session the
+    // authority of whichever channel it reached — on exactly the hosts where the
+    // check silently could not run. This ordering was the bug: the previous
+    // release returned `socket-ownership` here before ever looking at the
+    // expected pid, so a host whose libc would not load failed OPEN while the
+    // startup banner claimed it refused everything.
+    if (expected.pid !== undefined) {
+      return {
+        ok: false,
+        peerUid: -1,
+        expectedUid: expected.uid,
+        detail:
+          `this channel belongs to pid ${expected.pid} and this host reports no peer credentials at all, ` +
+          `so the caller cannot be identified — every session here shares one uid, and the socket mode ` +
+          `cannot tell them apart`,
+      };
+    }
     return {
       ok: true,
       basis: "socket-ownership",
-      why: "this host exposes no peer-credential call, so the 0600 socket under the daemon-owned 0711 parent is all that keeps other local accounts out",
+      why: "this host exposes no peer-credential call and no pid was expected, so the 0600 socket under the daemon-owned 0711 parent is all that keeps other local accounts out",
     };
   }
   if (peer.uid !== expected.uid) {
@@ -379,6 +446,29 @@ export function peerVerdict(
       detail: `uid ${peer.uid} connected to a socket allocated to uid ${expected.uid}`,
     };
   }
+  if (expected.pid !== undefined) {
+    if (peer.pid === undefined) {
+      return {
+        ok: false,
+        peerUid: peer.uid,
+        expectedUid: expected.uid,
+        detail:
+          `this channel belongs to pid ${expected.pid} and the kernel would not report the caller's pid, ` +
+          `so the session could not be identified — every session shares this uid`,
+      };
+    }
+    if (peer.pid !== expected.pid) {
+      return {
+        ok: false,
+        peerUid: peer.uid,
+        expectedUid: expected.uid,
+        detail:
+          `pid ${peer.pid} connected to a channel belonging to pid ${expected.pid} — same uid, ` +
+          `different session, so this is another session assuming this one's authority`,
+      };
+    }
+    return { ok: true, basis: "peer-pid", uid: peer.uid, pid: peer.pid };
+  }
   return { ok: true, basis: "peer-uid", uid: peer.uid };
 }
 
@@ -386,10 +476,10 @@ export function peerVerdict(
 export function transportBanner(dir: string, peerReader: PeerReader | undefined): string {
   const peers =
     peerReader === undefined
-      ? `no peer-credential call on ${process.platform}`
+      ? `no peer-credential call on ${process.platform} — every bound channel REFUSES every connection`
       : process.platform === "darwin"
-        ? "peer uid asserted with getpeereid"
-        : "peer uid asserted with SO_PEERCRED";
+        ? "caller pid+uid asserted with getpeereid and LOCAL_PEERPID; each channel bound to the session the daemon launched"
+        : "caller pid+uid asserted with SO_PEERCRED; each channel bound to the session the daemon launched";
   return (
     `verb sockets in ${dir} (mode ${VERB_DIR_MODE.toString(8)}); ` +
     `each socket 0600 under the daemon's own uid; ${peers}`

package/src/worker.ts

@@ -53,6 +53,8 @@ export interface WorkerOpts {
   releaseGrants?: ResolvedGrants;
   /** Durable audit sink for rejected release/deploy calls. */
   onReleaseBlocked?: (shape: ReleaseShape) => void;
+  /** The child's pid, the instant it exists. See {@link VerbListener.bindPid}. */
+  onSpawn?: (pid: number) => void;
   /** Control socket for that child, beside the run's own session directory. */
   socketPath?: string;
   /**
@@ -195,6 +197,7 @@ export async function runWorker(
     role: "worker",
     ...(o.releaseGrants === undefined ? {} : { releaseGrants: o.releaseGrants }),
     ...(o.onReleaseBlocked === undefined ? {} : { onReleaseBlocked: o.onReleaseBlocked }),
+    ...(o.onSpawn === undefined ? {} : { onSpawn: o.onSpawn }),
     ...(o.socketPath === undefined ? {} : { socketPath: o.socketPath }),
     ...(o.verbSocketPath === undefined ? {} : { verbSocketPath: o.verbSocketPath }),
     ...(o.onChildLog === undefined ? {} : { onChildLog: o.onChildLog }),