omp-conductor 0.3.25 → 0.4.0

package/src/verbs/server.ts

@@ -0,0 +1,1098 @@
+/**
+ * The privileged half of the mutation verbs (#126): every check, in the daemon.
+ *
+ * The child-side tool handler forwards arguments and renders an answer. It
+ * holds no credential, evaluates no policy and writes no ledger entry, because
+ * under #125 it runs inside the untrusted per-run process — anything it decided
+ * would be decided by code the model can rewrite. Everything below runs on the
+ * other side of the socket.
+ *
+ * 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.
+ *  - **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".
+ *  - **Stop always wins.** Pause state, the config and the run's own row are
+ *    re-read *inside* the verb, after the model decided to call it. A green
+ *    check a second ago is not a green check now.
+ *  - **Fail closed.** An unreadable config, an unknown run, a head nobody can
+ *    resolve: refuse with a named reason. Never allow on doubt.
+ */
+
+import { randomUUID } from "node:crypto";
+import { createServer, type Server, type Socket } from "node:net";
+
+import { resolvePolicy, resolveReleaseGrants } from "../config.ts";
+import { releaseRefusal } from "../release-policy.ts";
+import { LIVE_STATES } from "../store.ts";
+import type {
+  OpenCloser,
+  PrState,
+  PrVerification,
+  ProjectConfig,
+  ReleaseRequirement,
+  ReleaseShape,
+  RepoTarget,
+  RunRecord,
+  Store,
+  Tracker,
+  VerbLedgerEntry,
+  VerbName,
+  VerbRefusal,
+} from "../types.ts";
+import { parseVerbRequest, roleRefusal, VERB_SPECS, type VerbReply } from "./protocol.ts";
+import {
+  peerVerdict,
+  secureBoundSocket,
+  socketFd,
+  unlinkStaleSocket,
+  traversalProblem,
+  validateSocketPath,
+  type PeerReader,
+  type SocketOwnership,
+} from "./socket.ts";
+
+/**
+ * The OS principal a run was allocated (#125).
+ *
+ * Imported as a type from the credential boundary rather than redeclared, so
+ * there is one definition of "which uid is this run": a second copy is a second
+ * place identity is decided, which is the bug both issues exist to remove.
+ */
+import type { SlotPrincipal } from "../credentials.ts";
+
+/**
+ * How long a merge lock may be held before another daemon may break it.
+ *
+ * Generous, because the window it covers is a real `gh pr merge` against a
+ * repository with branch protection. Breaking it is safe rather than merely
+ * tolerable: the second merge re-reads the live head before acting, so a stolen
+ * lock cannot turn into a merge of something nobody looked at.
+ */
+export const MERGE_LOCK_STALE_MS = 10 * 60_000;
+
+/** A hostile local client must not be able to make the daemon buffer forever. */
+const MAX_REQUEST_BYTES = 64 * 1024;
+
+/** A connection that opens and says nothing is a connection that is holding a slot. */
+const REQUEST_TIMEOUT_MS = 30_000;
+
+/**
+ * Who is on the other end of one socket, decided by the daemon at dispatch.
+ *
+ * A discriminated union rather than a bag of optionals, because the two kinds
+ * differ in exactly the way the verbs care about: a run channel names one run
+ * and can name no other, and the orchestrator's names a project and no run at
+ * all. Nothing in a payload can move a call from one to the other.
+ */
+export type VerbChannel =
+  | {
+      kind: "run";
+      /** Absolute socket path. Also this channel's identity in the log. */
+      path: string;
+      project: string;
+      role: "worker";
+      runId: string;
+      issue: number;
+      /** The routed checkout, for the privileged push/PR half. */
+      repo: RepoTarget;
+      /** The run's own repository on disk (#125's per-run clone). */
+      runRepoPath: string;
+      branch: string;
+      principal?: SlotPrincipal;
+    }
+  | {
+      kind: "orchestrator";
+      path: string;
+      project: string;
+      role: "orchestrator";
+      principal?: SlotPrincipal;
+    };
+
+export type ActionOutcome = { ok: true; sha?: string; detail?: string } | { ok: false; stderr: string };
+
+/** What one release asks the privileged half to do, after policy said yes. */
+export interface ReleaseExecution {
+  shape: ReleaseShape;
+  repo: RepoTarget;
+  tag?: string;
+  artefact?: string;
+  environment?: string;
+}
+
+/**
+ * The privileged half, as an interface so every check above it is testable
+ * without a repository, a credential or a network.
+ *
+ * `releasableShapes` is declared by the implementation rather than assumed by
+ * the server: this daemon holds a GitHub credential, not an npm token and not a
+ * deploy key, and a release shape it cannot actually cut must be refused by
+ * name rather than attempted and reported as a command failure.
+ */
+export interface VerbActions {
+  releasableShapes: readonly ReleaseShape[];
+  push(run: { repo: RepoTarget; runRepoPath: string; branch: string }): Promise<ActionOutcome>;
+  createPr(
+    run: { repo: RepoTarget; runRepoPath: string; branch: string },
+    opts: { title: string; body: string; base: string },
+  ): Promise<{ ok: true; url: string } | { ok: false; stderr: string }>;
+  updatePrBranch(prUrl: string): Promise<ActionOutcome>;
+  mergePr(prUrl: string, headSha: string): Promise<ActionOutcome>;
+  setLabel(issue: number, label: string, action: "add" | "remove"): Promise<ActionOutcome>;
+  release(execution: ReleaseExecution): Promise<ActionOutcome>;
+}
+
+export interface VerbDeps {
+  /**
+   * The project config, **re-read per call**. A thunk rather than a value
+   * because "unreadable config refuses the call" is only true if the call is
+   * the thing that reads it: a config resolved once at boot cannot become
+   * unreadable, and cannot pick up an operator's edit either.
+   */
+  project: () => ProjectConfig;
+  store: Store;
+  tracker: Tracker;
+  actions: VerbActions;
+  /**
+   * Why the fleet is stopped right now, or `undefined`. Called inside the verb,
+   * after the model decided to call it. `hold` and `halt` both set the pause
+   * sentinel alongside disarming ticks, so one read covers both.
+   */
+  fleetStop: () => string | undefined;
+  log: (message: string) => void;
+  now: () => number;
+}
+
+/**
+ * The labels a session may change on this project's issues.
+ *
+ * Two lists, not one filter, because the interesting refusal is the second:
+ * `agent:in-progress` is a *real* label of this project that a session still
+ * may not touch, since the loop's orphan detection is only trustworthy while
+ * every lifecycle label on the tracker was written by the conductor (#26).
+ * Telling a caller "not in the vocabulary" about a label it can plainly see on
+ * the issue teaches it to try harder; telling it "that transition is the
+ * daemon's" tells it to stop.
+ */
+export interface LabelVocabulary {
+  grantable: string[];
+  lifecycle: string[];
+}
+
+export function labelVocabulary(p: ProjectConfig): LabelVocabulary {
+  return {
+    grantable: [
+      p.queueLabel,
+      ...Object.keys(p.routing.repos).map((name) => `${p.routing.labelPrefix}${name}`),
+    ],
+    lifecycle: [p.stateLabels.inProgress, p.stateLabels.blocked, p.stateLabels.failed],
+  };
+}
+
+/** `owner/repo` and the number, from a fully-qualified issue URL. */
+const ISSUE_URL = /^https?:\/\/[^\s/]+\/([^\s/]+\/[^\s/]+)\/issues\/(\d+)\/?$/;
+
+/**
+ * Parse an issue reference the caller fully qualified.
+ *
+ * Fully qualified for the reason `PR_URL` in the GitHub adapter is: `gh` also
+ * accepts a bare number and resolves it against whatever repository the current
+ * directory belongs to, so an unqualified reference is not refused — it is
+ * answered, confidently, about some other repository's issue.
+ */
+export function issueRefFrom(url: string): { repo: string; issue: number } | undefined {
+  const match = ISSUE_URL.exec(url);
+  if (match === null) return undefined;
+  const issue = Number.parseInt(match[2] ?? "", 10);
+  return Number.isSafeInteger(issue) && issue > 0 ? { repo: match[1] ?? "", issue } : undefined;
+}
+
+/**
+ * Whether a `verifyPr` refusal is the exact-head mismatch rather than a check
+ * verdict.
+ *
+ * Matched on the adapter's own wording (`prVerificationFrom`, `tracker/
+ * github.ts`), which already names both SHAs — reusing it is what #126 asks
+ * for, and re-deriving the comparison here would be a second implementation of
+ * the one rule that must not drift. Pinned by a test against that function's
+ * real output, so a reworded reason fails a test rather than silently
+ * downgrading a stale head into "checks not green".
+ */
+export function isHeadMismatch(reason: string): boolean {
+  return reason.startsWith("PR head changed");
+}
+
+/**
+ * Which declared release requirements are not satisfied.
+ *
+ * Pure, and fail-closed on anything it cannot settle: a requirement the daemon
+ * cannot prove is a requirement that has not been met. `epic-children-closed`
+ * is the honest example — nothing in a release request names an epic, so the
+ * daemon cannot check it and says so rather than waving it through.
+ */
+export interface ReleaseFacts {
+  /** Runs still occupying an issue: live workers and unmerged green PRs. */
+  unsettledRuns: number;
+  /** Of those, the ones with a pull request still open. */
+  openPrs: number;
+  /** Queue depth, or `undefined` when the tracker could not be read. */
+  queueDepth: number | undefined;
+}
+
+export function releaseRequirementRefusal(
+  requires: readonly ReleaseRequirement[],
+  facts: ReleaseFacts,
+): string | undefined {
+  for (const requirement of requires) {
+    if (requirement === "runs-settled" && facts.unsettledRuns > 0) {
+      return `policy.release.requires includes runs-settled and ${facts.unsettledRuns} run(s) have not settled`;
+    }
+    if (requirement === "no-open-prs" && facts.openPrs > 0) {
+      return `policy.release.requires includes no-open-prs and ${facts.openPrs} pull request(s) are still open`;
+    }
+    if (requirement === "queue-drained") {
+      if (facts.queueDepth === undefined) {
+        return "policy.release.requires includes queue-drained and the tracker could not be read; refusing rather than assuming the queue is empty";
+      }
+      if (facts.queueDepth > 0) {
+        return `policy.release.requires includes queue-drained and ${facts.queueDepth} issue(s) are still queued`;
+      }
+    }
+    if (requirement === "epic-children-closed") {
+      return "policy.release.requires includes epic-children-closed, which nothing in a release request names an epic for. The daemon cannot settle it, so it refuses: take the requirement off this project's policy, or cut this release by hand.";
+    }
+  }
+  return undefined;
+}
+
+/** Everything one decided call writes down, whichever way it went. */
+interface Verdict {
+  reply: VerbReply;
+  entry?: VerbLedgerEntry;
+}
+
+function record(
+  deps: VerbDeps,
+  channel: VerbChannel,
+  verb: VerbName,
+  args: Record<string, unknown>,
+  outcome:
+    | { decision: "allowed"; detail: string; sha?: string }
+    | { decision: "refused"; refusal: VerbRefusal; detail: string },
+  issue?: number,
+): Verdict {
+  // Reads are not ledgered. The ledger is the record of what a session *did* and
+  // tried to do; a status poll every thirty seconds would bury the refusals it
+  // exists to surface under its own noise.
+  if (!VERB_SPECS[verb].mutating) {
+    return {
+      reply: {
+        ok: outcome.decision === "allowed",
+        verb,
+        ...(outcome.decision === "refused" ? { refusal: outcome.refusal } : {}),
+        text: outcome.detail,
+      },
+    };
+  }
+  const entry = deps.store.appendVerbLedger({
+    project: channel.project,
+    ...(channel.kind === "run" ? { runId: channel.runId } : {}),
+    ...(issue === undefined ? {} : { issue }),
+    verb,
+    role: channel.role,
+    args,
+    decision: outcome.decision,
+    ...(outcome.decision === "refused" ? { refusal: outcome.refusal } : {}),
+    detail: outcome.detail,
+    ...(outcome.decision === "allowed" && outcome.sha !== undefined ? { sha: outcome.sha } : {}),
+  });
+  return {
+    entry,
+    reply: {
+      ok: outcome.decision === "allowed",
+      verb,
+      ...(outcome.decision === "refused" ? { refusal: outcome.refusal } : {}),
+      text: outcome.detail,
+      ...(outcome.decision === "allowed" && outcome.sha !== undefined ? { sha: outcome.sha } : {}),
+    },
+  };
+}
+
+/**
+ * Decide and execute one verb call. Never throws: a thrown error inside a check
+ * would close the connection with no ledger entry, which is exactly the shape
+ * an attacker would like an unhandled case to have.
+ */
+export async function handleVerbCall(
+  deps: VerbDeps,
+  channel: VerbChannel,
+  raw: unknown,
+): Promise<VerbReply> {
+  try {
+    return (await decide(deps, channel, raw)).reply;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    deps.log(`verb call on ${channel.path} failed unexpectedly: ${detail}`);
+    return { ok: false, refusal: "config-unreadable", text: `refused: the daemon errored (${detail}).` };
+  }
+}
+
+async function decide(deps: VerbDeps, channel: VerbChannel, raw: unknown): Promise<Verdict> {
+  const parsed = parseVerbRequest(raw);
+  if (!parsed.ok) {
+    // A payload whose verb never resolved cannot be filed under a verb. It is
+    // still answered — the caller learns exactly what it sent wrong — but the
+    // ledger stays a record of calls to real verbs rather than of noise.
+    if (parsed.verb === undefined) {
+      return { reply: { ok: false, refusal: parsed.refusal, text: parsed.detail } };
+    }
+    return record(deps, channel, parsed.verb, {}, { decision: "refused", refusal: parsed.refusal, detail: parsed.detail });
+  }
+
+  const { verb, args } = parsed.request;
+  const spec = VERB_SPECS[verb];
+  const issue = channel.kind === "run" ? channel.issue : undefined;
+  const refuse = (refusal: VerbRefusal, detail: string, at = issue): Verdict =>
+    record(deps, channel, verb, args, { decision: "refused", refusal, detail }, at);
+  const allow = (detail: string, sha?: string, at = issue): Verdict =>
+    record(deps, channel, verb, args, { decision: "allowed", detail, ...(sha === undefined ? {} : { sha }) }, at);
+
+  // 1. Closed by default. Before anything else reads config or touches the
+  //    network: a caller of the wrong kind learns nothing about this project.
+  const wrongRole = roleRefusal(spec, channel.role);
+  if (wrongRole !== undefined) return refuse("role-not-allowed", `refused: ${wrongRole}`);
+
+  // 2. Fail closed on config. Read now, per call, so an operator's edit and an
+  //    unreadable file both take effect on the next verb rather than the next
+  //    daemon restart.
+  let project: ProjectConfig;
+  try {
+    project = deps.project();
+  } catch (err) {
+    const why = err instanceof Error ? err.message : String(err);
+    return refuse("config-unreadable", `refused: this project's config could not be read (${why}).`);
+  }
+  if (project.name !== channel.project) {
+    return refuse(
+      "config-unreadable",
+      `refused: this socket belongs to project ${channel.project}, and the config now resolves ${project.name}.`,
+    );
+  }
+
+  // 3. Stop always wins, and is re-read here rather than remembered. Reads are
+  //    exempt: a run finishing its report during a `hold` still has to be able
+  //    to say what it saw, and refusing that would only make it guess.
+  const stopped = spec.mutating ? deps.fleetStop() : undefined;
+  if (stopped !== undefined) {
+    return refuse("fleet-paused", `refused: ${stopped}. Mutating verbs are refused while the fleet is stopped.`);
+  }
+
+  // 4. The run's own row, re-read. A worker whose run was killed, orphaned or
+  //    settled between its last turn and this call is no longer holding
+  //    anything, and a push from it would land work nothing is tracking.
+  let run: RunRecord | undefined;
+  if (channel.kind === "run") {
+    run = deps.store.getRun(channel.runId);
+    if (run === undefined) {
+      return refuse("run-not-live", `refused: run ${channel.runId} is no longer in the store.`);
+    }
+    if (!LIVE_STATES.some((state) => state === run?.state)) {
+      return refuse("run-not-live", `refused: this run is ${run.state}, not live. Its mutations are over.`);
+    }
+  }
+
+  switch (verb) {
+    case "conductor_push":
+      return pushVerb(deps, channel, args, refuse, allow);
+    case "conductor_pr_create":
+      return prCreateVerb(deps, project, channel, args, refuse, allow);
+    case "conductor_pr_update_branch":
+      return prUpdateBranchVerb(deps, project, channel, args, refuse, allow);
+    case "conductor_pr_merge":
+      return prMergeVerb(deps, project, channel, args, refuse, allow);
+    case "conductor_label":
+      return labelVerb(deps, project, channel, args, refuse, allow);
+    case "conductor_release":
+      return releaseVerb(deps, project, channel, args, refuse, allow);
+    case "conductor_pr_status":
+      return prStatusVerb(deps, project, channel, args, refuse, allow);
+  }
+}
+
+type Refuse = (refusal: VerbRefusal, detail: string, issue?: number) => Verdict;
+type Allow = (detail: string, sha?: string, issue?: number) => Verdict;
+
+/** A run channel, or the refusal for a verb that needs one. Narrows the union. */
+function runChannel(
+  channel: VerbChannel,
+  refuse: Refuse,
+): { ok: true; channel: Extract<VerbChannel, { kind: "run" }> } | { ok: false; verdict: Verdict } {
+  if (channel.kind === "run") return { ok: true, channel };
+  return {
+    ok: false,
+    verdict: refuse("role-not-allowed", "refused: this verb acts on a run, and this socket belongs to no run."),
+  };
+}
+
+async function pushVerb(
+  deps: VerbDeps,
+  channel: VerbChannel,
+  args: Record<string, unknown>,
+  refuse: Refuse,
+  allow: Allow,
+): Promise<Verdict> {
+  const scoped = runChannel(channel, refuse);
+  if (!scoped.ok) return scoped.verdict;
+  const run = scoped.channel;
+
+  // The only ref this verb has. `ref` is an assertion the caller may make about
+  // it, never a selector: a mismatch is refused rather than redirected, and
+  // there is no `force` argument to reject because none is declared.
+  const expected = `refs/heads/${run.branch}`;
+  const ref = args["ref"];
+  if (typeof ref === "string" && ref !== expected) {
+    return refuse(
+      "ref-not-run-branch",
+      `refused: this run pushes ${expected} and nothing else. You named "${ref}". ` +
+        "There is no force path and no way to name another ref: the daemon derives the ref from the run.",
+    );
+  }
+
+  const outcome = await deps.actions.push({
+    repo: run.repo,
+    runRepoPath: run.runRepoPath,
+    branch: run.branch,
+  });
+  if (!outcome.ok) {
+    return refuse(
+      "action-failed",
+      `refused: the push was rejected. git said:\n${outcome.stderr}\n\n` +
+        "This push is fast-forward only. A non-fast-forward rejection means the remote branch moved — " +
+        "fetch and rebase in your own checkout, then push again.",
+    );
+  }
+  return allow(`pushed ${expected}${outcome.sha === undefined ? "" : ` at ${outcome.sha}`}.`, outcome.sha);
+}
+
+async function prCreateVerb(
+  deps: VerbDeps,
+  project: ProjectConfig,
+  channel: VerbChannel,
+  args: Record<string, unknown>,
+  refuse: Refuse,
+  allow: Allow,
+): Promise<Verdict> {
+  const scoped = runChannel(channel, refuse);
+  if (!scoped.ok) return scoped.verdict;
+  const run = scoped.channel;
+  const base = run.repo.defaultBranch;
+
+  const claimedBase = args["base"];
+  if (typeof claimedBase === "string" && claimedBase !== base) {
+    return refuse(
+      "base-not-default-branch",
+      `refused: ${run.repo.name} targets ${base}, and you named "${claimedBase}". ` +
+        "The base is the repo's configured defaultBranch, not an argument.",
+    );
+  }
+  const claimedHead = args["head"];
+  if (typeof claimedHead === "string" && claimedHead !== run.branch) {
+    return refuse(
+      "ref-not-run-branch",
+      `refused: this run's head is ${run.branch}, and you named "${claimedHead}".`,
+    );
+  }
+
+  // #25's guard, asked of the tracker rather than the store: the store only
+  // knows work this database recorded, and a restored or relocated state
+  // directory presents finished work as an untouched queue item.
+  const existing = deps.store.getRun(run.runId)?.prUrl;
+  if (existing !== undefined) {
+    return refuse("open-pr-exists", `refused: this run already opened ${existing}.`);
+  }
+  let closer: OpenCloser | undefined;
+  try {
+    closer = await deps.tracker.openCloserFor(run.issue);
+  } catch (err) {
+    const why = err instanceof Error ? err.message : String(err);
+    return refuse(
+      "open-pr-lookup-error",
+      `refused: the tracker could not say whether #${run.issue} already has an open pull request (${why}). ` +
+        "Refusing rather than opening a second one.",
+    );
+  }
+  if (closer !== undefined) {
+    return refuse("open-pr-exists", `refused: ${closer.url} is already open and already closes #${run.issue}.`);
+  }
+
+  const title = args["title"];
+  const body = args["body"];
+  const outcome = await deps.actions.createPr(
+    { repo: run.repo, runRepoPath: run.runRepoPath, branch: run.branch },
+    { title: typeof title === "string" ? title : "", body: typeof body === "string" ? body : "", base },
+  );
+  if (!outcome.ok) {
+    return refuse("action-failed", `refused: gh could not open the pull request:\n${outcome.stderr}`);
+  }
+  // Recorded now rather than at settlement: the merge verb resolves a run from
+  // its PR URL, and a PR the store never learned about is one the orchestrator
+  // cannot act on through any verb.
+  deps.store.updateRun(run.runId, { prUrl: outcome.url });
+  return allow(`opened ${outcome.url} (${run.branch} → ${base}).`);
+}
+
+/**
+ * The run one pull request belongs to, within this project.
+ *
+ * How far back to look is the recent-history cutoff `status` already uses: a
+ * pull request older than that is not one an orchestrator is mid-flight on.
+ */
+const PR_LOOKUP_WINDOW_MS = 30 * 24 * 60 * 60_000;
+
+function runForPr(deps: VerbDeps, project: string, prUrl: string): RunRecord | undefined {
+  return deps.store
+    .recentRuns(project, deps.now() - PR_LOOKUP_WINDOW_MS)
+    .find((candidate) => candidate.prUrl === prUrl);
+}
+
+async function prUpdateBranchVerb(
+  deps: VerbDeps,
+  project: ProjectConfig,
+  channel: VerbChannel,
+  args: Record<string, unknown>,
+  refuse: Refuse,
+  allow: Allow,
+): Promise<Verdict> {
+  const prUrl = String(args["prUrl"]);
+
+  let target: RunRecord | undefined;
+  if (channel.kind === "run") {
+    const own = deps.store.getRun(channel.runId);
+    if (own?.prUrl === undefined) {
+      return refuse("pr-missing", "refused: this run has no pull request yet.");
+    }
+    if (own.prUrl !== prUrl) {
+      return refuse(
+        "pr-not-this-run",
+        `refused: this socket belongs to the run for #${channel.issue}, whose pull request is ${own.prUrl}. ` +
+          "A worker can only act on its own run's PR — the daemon resolves the run from the socket, not from what you sent.",
+      );
+    }
+    target = own;
+  } else {
+    target = runForPr(deps, project.name, prUrl);
+    if (target === undefined) {
+      return refuse("pr-not-this-run", `refused: ${prUrl} is not a pull request any run in ${project.name} opened.`);
+    }
+  }
+
+  let state: PrState | undefined;
+  try {
+    state = await deps.tracker.prState(prUrl);
+  } catch (err) {
+    state = undefined;
+    deps.log(`verb pr_update_branch could not read ${prUrl}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (state !== "open") {
+    return refuse(
+      "pr-not-open",
+      state === undefined
+        ? `refused: the tracker could not say whether ${prUrl} is open. Refusing rather than acting on an unknown state.`
+        : `refused: ${prUrl} is ${state}, not open.`,
+      target.issue,
+    );
+  }
+
+  const outcome = await deps.actions.updatePrBranch(prUrl);
+  if (!outcome.ok) {
+    return refuse("action-failed", `refused: gh could not update the branch:\n${outcome.stderr}`, target.issue);
+  }
+  return allow(`updated ${prUrl} with its base branch. Re-check its checks before merging.`, outcome.sha, target.issue);
+}
+
+async function prMergeVerb(
+  deps: VerbDeps,
+  project: ProjectConfig,
+  channel: VerbChannel,
+  args: Record<string, unknown>,
+  refuse: Refuse,
+  allow: Allow,
+): Promise<Verdict> {
+  // The grant says *who*. Compared against the caller rather than tested for a
+  // single forbidden value: `authority` has two holders, so `!== "human"` would
+  // have let a worker through, and `"human"` has to refuse the orchestrator too.
+  const holder = project.authority.merge;
+  if (holder !== channel.role) {
+    return refuse(
+      "authority-holder",
+      `refused: merge authority is the ${holder}'s for ${project.name}, and this is a ${channel.role} session. ` +
+        (holder === "human"
+          ? "No session merges under this config. Report the PR as ready and stop."
+          : "Ask the operator which session is meant to hold it."),
+    );
+  }
+
+  const prUrl = String(args["prUrl"]);
+  const headSha = String(args["headSha"]);
+  const target = runForPr(deps, project.name, prUrl);
+  if (target === undefined) {
+    return refuse("pr-not-this-run", `refused: ${prUrl} is not a pull request any run in ${project.name} opened.`);
+  }
+
+  // Taken before any network call, so two concurrent callers contend here
+  // rather than both spending a `gh` round trip and racing at the merge.
+  const holderId = randomUUID();
+  const lock = deps.store.acquireMergeLock(project.name, holderId, prUrl, deps.now(), MERGE_LOCK_STALE_MS);
+  if (lock === undefined) {
+    const live = deps.store.mergeLock(project.name);
+    return refuse(
+      "merge-in-flight",
+      `refused: a merge is already in flight for ${project.name}` +
+        (live === undefined ? "" : ` (${live.prUrl})`) +
+        ". PRs land one at a time, each re-checked against its base: two agent merges at once is how they clobber each other.",
+      target.issue,
+    );
+  }
+
+  try {
+    // Exact-head, re-read at mutation time. Any push since the caller observed
+    // green invalidates that observation, and `verifyPr` is the one place that
+    // comparison is implemented.
+    let verification: PrVerification | undefined;
+    try {
+      verification = await deps.tracker.verifyPr(prUrl, headSha);
+    } catch (err) {
+      const why = err instanceof Error ? err.message : String(err);
+      return refuse("head-unresolvable", `refused: the live head of ${prUrl} could not be read (${why}).`, target.issue);
+    }
+    if (verification === undefined) {
+      return refuse(
+        "head-unresolvable",
+        `refused: the live head of ${prUrl} could not be resolved. Refusing rather than merging what you last saw.`,
+        target.issue,
+      );
+    }
+    if (verification.status !== "green") {
+      const stale = verification.status === "failed" && isHeadMismatch(verification.reason);
+      return refuse(
+        stale ? "head-stale" : "checks-not-green",
+        stale
+          ? `refused: ${verification.reason}. You asked to merge ${headSha}; that is not what is on the branch now. ` +
+            "Re-read the head, re-check the checks at it, and call again."
+          : `refused: ${prUrl} is not mergeable at ${headSha} — ${verification.reason}.`,
+        target.issue,
+      );
+    }
+
+    const outcome = await deps.actions.mergePr(prUrl, headSha);
+    if (!outcome.ok) {
+      return refuse("action-failed", `refused: gh could not merge:\n${outcome.stderr}`, target.issue);
+    }
+    return allow(
+      `merged ${prUrl} at ${headSha} (${verification.reason}).`,
+      outcome.sha ?? headSha,
+      target.issue,
+    );
+  } finally {
+    deps.store.releaseMergeLock(project.name, holderId);
+  }
+}
+
+async function labelVerb(
+  deps: VerbDeps,
+  project: ProjectConfig,
+  channel: VerbChannel,
+  args: Record<string, unknown>,
+  refuse: Refuse,
+  allow: Allow,
+): Promise<Verdict> {
+  const ref = issueRefFrom(String(args["issueUrl"]));
+  if (ref === undefined) {
+    return refuse(
+      "malformed-argument",
+      `refused: "${String(args["issueUrl"])}" is not a full issue URL. A bare number resolves against whatever ` +
+        "repository the daemon happens to be in, which is how a label lands on the wrong project's issue.",
+    );
+  }
+  if (ref.repo !== project.tracker.repo) {
+    return refuse(
+      "malformed-argument",
+      `refused: ${ref.repo} is not this project's tracker (${project.tracker.repo}).`,
+    );
+  }
+
+  const label = String(args["label"]);
+  const vocabulary = labelVocabulary(project);
+  if (vocabulary.lifecycle.includes(label)) {
+    return refuse(
+      "label-is-lifecycle",
+      `refused: ${label} is a lifecycle label. Those transitions stay the daemon's — orphan detection is only ` +
+        "trustworthy while every state label on the tracker was written by the conductor. Use omp-conductor unblock.",
+      ref.issue,
+    );
+  }
+  if (!vocabulary.grantable.includes(label)) {
+    return refuse(
+      "label-not-in-vocabulary",
+      `refused: ${label} is not in ${project.name}'s own vocabulary. It declares ${vocabulary.grantable.join(", ")}.`,
+      ref.issue,
+    );
+  }
+
+  const action = args["action"] === "remove" ? "remove" : "add";
+  const outcome = await deps.actions.setLabel(ref.issue, label, action);
+  if (!outcome.ok) {
+    return refuse("action-failed", `refused: the tracker rejected the label change:\n${outcome.stderr}`, ref.issue);
+  }
+  return allow(`${action === "add" ? "added" : "removed"} ${label} on #${ref.issue}.`, undefined, ref.issue);
+}
+
+async function releaseVerb(
+  deps: VerbDeps,
+  project: ProjectConfig,
+  channel: VerbChannel,
+  args: Record<string, unknown>,
+  refuse: Refuse,
+  allow: Allow,
+): Promise<Verdict> {
+  // Same rule as merge, written twice on purpose. A worker never reaches here
+  // — the role gate refused it — and an orchestrator still has to *be* the
+  // configured holder.
+  const holder = project.authority.release;
+  if (holder !== channel.role) {
+    return refuse(
+      "authority-holder",
+      `refused: release authority is the ${holder}'s for ${project.name}, and this is a ${channel.role} session.` +
+        (holder === "human" ? " No session releases under this config." : ""),
+    );
+  }
+
+  const shape = args["shape"] as ReleaseShape;
+  const grants = resolveReleaseGrants(project);
+  const granted = releaseRefusal(grants, channel.role, shape);
+  if (granted !== undefined) {
+    return refuse("release-not-granted", `refused: ${granted.reason}`);
+  }
+
+  const repoName = String(args["repo"]);
+  const repo: RepoTarget | undefined = project.routing.repos[repoName];
+  if (repo === undefined) {
+    return refuse(
+      "malformed-argument",
+      `refused: ${project.name} routes no repository called "${repoName}". It has ${Object.keys(project.routing.repos).join(", ")}.`,
+    );
+  }
+
+  const policy = resolvePolicy(project);
+  const artefact = args["artefact"];
+  const environment = args["environment"];
+  if (shape === "package-publish") {
+    if (typeof artefact !== "string" || !policy.release.artefacts.includes(artefact)) {
+      return refuse(
+        "release-target-not-declared",
+        `refused: ${project.name} declares ${policy.release.artefacts.length === 0 ? "no artefacts" : `artefacts ${policy.release.artefacts.join(", ")}`}, ` +
+          `and you named ${JSON.stringify(artefact)}. An undeclared artefact is one nobody authorised publishing.`,
+      );
+    }
+  }
+  if (shape === "deploy") {
+    if (typeof environment !== "string" || !policy.release.environments.includes(environment)) {
+      return refuse(
+        "release-target-not-declared",
+        `refused: ${project.name} declares ${policy.release.environments.length === 0 ? "no environments" : `environments ${policy.release.environments.join(", ")}`}, ` +
+          `and you named ${JSON.stringify(environment)}. An undeclared environment is one nobody authorised deploying to.`,
+      );
+    }
+  }
+
+  const active = deps.store.activeRuns(project.name);
+  const wantsQueue = policy.release.requires.includes("queue-drained");
+  let queueDepth: number | undefined;
+  if (wantsQueue) {
+    try {
+      queueDepth = (await deps.tracker.listReady()).length;
+    } catch {
+      queueDepth = undefined;
+    }
+  }
+  const unmet = releaseRequirementRefusal(policy.release.requires, {
+    unsettledRuns: active.length,
+    openPrs: active.filter((r) => r.prUrl !== undefined).length,
+    queueDepth,
+  });
+  if (unmet !== undefined) return refuse("release-not-granted", `refused: ${unmet}`);
+
+  if (!deps.actions.releasableShapes.includes(shape)) {
+    return refuse(
+      "release-shape-not-executable",
+      `refused: this daemon cannot cut a ${shape}. It holds a GitHub credential and nothing else — no npm token, ` +
+        "no deploy key — and #125 exists to keep it that way. It can do " +
+        `${deps.actions.releasableShapes.join(", ")}. Escalate this one to your operator.`,
+    );
+  }
+
+  const tag = args["tag"];
+  const outcome = await deps.actions.release({
+    shape,
+    repo,
+    ...(typeof tag === "string" ? { tag } : {}),
+    ...(typeof artefact === "string" ? { artefact } : {}),
+    ...(typeof environment === "string" ? { environment } : {}),
+  });
+  if (!outcome.ok) {
+    return refuse("action-failed", `refused: the release command failed:\n${outcome.stderr}`);
+  }
+  return allow(
+    `cut ${shape} for ${repo.name}${outcome.detail === undefined ? "" : ` — ${outcome.detail}`}.`,
+    outcome.sha,
+  );
+}
+
+
+/**
+ * The one read verb, and the reason a credential-less worker can still report
+ * honestly (#125 took `gh pr view` away from it).
+ *
+ * Reuses `Tracker.verifyPr`, so the answer is literally the merge gate's own
+ * verdict rather than a second opinion assembled here — including the
+ * moved-head case, whose reason already names both shas. A worker that quotes
+ * this has read a fact; a worker that says "should be green" has not.
+ */
+async function prStatusVerb(
+  deps: VerbDeps,
+  project: ProjectConfig,
+  channel: VerbChannel,
+  args: Record<string, unknown>,
+  refuse: Refuse,
+  allow: Allow,
+): Promise<Verdict> {
+  const asked = args["prUrl"];
+  let prUrl: string;
+  let issue: number | undefined;
+
+  if (channel.kind === "run") {
+    // A worker reads its own run's PR and no other. Omitting `prUrl` is the
+    // normal path; naming one is an assertion, checked, never a selector.
+    const own = deps.store.getRun(channel.runId);
+    if (own?.prUrl === undefined) {
+      return refuse("pr-missing", "refused: this run has no pull request yet. Open one with conductor_pr_create.");
+    }
+    if (typeof asked === "string" && asked !== own.prUrl) {
+      return refuse(
+        "pr-not-this-run",
+        `refused: this socket belongs to the run for #${channel.issue}, whose pull request is ${own.prUrl}. ` +
+          "A worker reads only its own run's PR — the daemon resolves the run from the socket.",
+      );
+    }
+    prUrl = own.prUrl;
+    issue = channel.issue;
+  } else {
+    if (typeof asked !== "string") {
+      return refuse("malformed-argument", "refused: conductor_pr_status needs prUrl when it has no run to infer one from.");
+    }
+    const target = runForPr(deps, project.name, asked);
+    if (target === undefined) {
+      return refuse("pr-not-this-run", `refused: ${asked} is not a pull request any run in ${project.name} opened.`);
+    }
+    prUrl = asked;
+    issue = target.issue;
+  }
+
+  const headSha = String(args["headSha"]);
+  let verification: PrVerification | undefined;
+  try {
+    verification = await deps.tracker.verifyPr(prUrl, headSha);
+  } catch (err) {
+    verification = undefined;
+    deps.log(`verb pr_status could not read ${prUrl}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (verification === undefined) {
+    return refuse(
+      "head-unresolvable",
+      `refused: ${prUrl} could not be read. That is not "green" and not "red" — wait and ask again, ` +
+        "and report blocked rather than guessing if it stays unreadable.",
+      issue,
+    );
+  }
+  return allow(`${prUrl} at ${headSha}: ${verification.status} — ${verification.reason}`, undefined, issue);
+}
+
+// ------------------------------------------------------------------ the listener
+
+export interface VerbListener {
+  path: string;
+  ownership: SocketOwnership;
+  close(): Promise<void>;
+}
+
+/**
+ * Refusing to bind is refusing to dispatch. Thrown rather than returned so no
+ * caller can accidentally continue past it into a run with no boundary.
+ */
+export class VerbSocketRefusal extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "VerbSocketRefusal";
+  }
+}
+
+export interface ListenOptions {
+  peerReader?: PeerReader;
+  daemonUid?: number;
+  /** Injected in tests; the real one chowns, which needs privilege. */
+  secure?: typeof secureBoundSocket;
+  /**
+   * Injected in tests for the same reason `secure` is: the traversal rule is
+   * about the *deployment's* directory chain, and a test that needs a bound
+   * socket in a developer's `0750` home is not the case it is asserting. The
+   * rule itself is pinned directly in `socket.test.ts`.
+   */
+  traversal?: typeof traversalProblem;
+}
+
+/**
+ * Bind one channel's socket, after proving nobody else could have tampered with
+ * where it is going.
+ *
+ * The validation is not defensive tidiness: a socket under a directory a third
+ * party can write is a socket a third party can unlink and re-bind, and the
+ * daemon would then be handing a run's verbs to whoever won that race. A failed
+ * check refuses dispatch rather than degrading, because the degraded mode here
+ * is "no boundary at all, silently".
+ */
+export async function listenVerbChannel(
+  deps: VerbDeps,
+  channel: VerbChannel,
+  opts: ListenOptions = {},
+): Promise<VerbListener> {
+  const daemonUid = opts.daemonUid ?? process.getuid?.() ?? 0;
+  const problem = validateSocketPath(channel.path, daemonUid);
+  if (problem !== undefined) {
+    throw new VerbSocketRefusal(
+      `dispatch refused: ${problem.message}. The verb socket layout requires every component to be ` +
+        "owned by the daemon (or root), free of symlinks, and unwritable by anyone else.",
+    );
+  }
+  // Traversal, proven rather than assumed, and only when it can actually fail:
+  // a run with its own principal reaches this socket by searching every
+  // component, and the daemon's state directory is 0700. Refusing here names
+  // the directory and the fix; letting it bind would produce an EACCES inside
+  // a worker turn, about a path nobody was thinking about.
+  if (channel.principal !== undefined) {
+    const blocked = (opts.traversal ?? traversalProblem)(channel.path);
+    if (blocked !== undefined) {
+      throw new VerbSocketRefusal(
+        `dispatch refused: ${blocked.message}. This run has its own OS principal, so it must be able to ` +
+          "traverse to its socket; binding one it cannot reach would take its verbs away silently.",
+      );
+    }
+  }
+  // Only the daemon ever unlinks these, and it has just proven the parent is
+  // not writable by anyone else — which is what makes unlink-then-bind safe
+  // here and a race in a world-writable directory.
+  unlinkStaleSocket(channel.path);
+
+  const server: Server = createServer((socket) => {
+    handleConnection(deps, channel, socket, opts.peerReader);
+  });
+  server.on("error", (err) => {
+    deps.log(`verb socket ${channel.path} errored: ${err.message}`);
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(channel.path, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+
+  const secure = opts.secure ?? secureBoundSocket;
+  const ownership = secure(channel.path, channel.principal);
+
+  return {
+    path: channel.path,
+    ownership,
+    close: async () => {
+      await new Promise<void>((resolve) => {
+        server.close(() => {
+          resolve();
+        });
+      });
+      unlinkStaleSocket(channel.path);
+    },
+  };
+}
+
+function handleConnection(
+  deps: VerbDeps,
+  channel: VerbChannel,
+  socket: Socket,
+  peerReader: PeerReader | undefined,
+): void {
+  const fd = socketFd(socket);
+  const peer = fd === undefined || peerReader === undefined ? undefined : peerReader(fd);
+  const verdict = peerVerdict(channel.principal, 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.
+    deps.log(
+      `IMPERSONATION on ${channel.path}: ${verdict.detail}. Connection closed without a reply. ` +
+        `This socket belongs to ${channel.kind === "run" ? `run ${channel.runId} (#${channel.issue})` : "the orchestrator"} in ${channel.project}.`,
+    );
+    // `end`, not `destroy`: the caller gets no reply either way, but a clean
+    // close means it learns *now* instead of sitting out its whole timeout. An
+    // impersonation attempt that also hangs the honest client behind it is a
+    // denial of service the refusal handed out for free.
+    socket.end();
+    return;
+  }
+
+  socket.setTimeout(REQUEST_TIMEOUT_MS, () => {
+    socket.destroy();
+  });
+
+  let buffer = "";
+  let answered = false;
+  const answer = async (raw: unknown): Promise<void> => {
+    if (answered) return;
+    answered = true;
+    const reply = await handleVerbCall(deps, channel, raw);
+    socket.end(`${JSON.stringify(reply)}\n`);
+  };
+
+  socket.on("data", (chunk) => {
+    if (answered) return;
+    buffer += chunk.toString("utf8");
+    if (buffer.length > MAX_REQUEST_BYTES) {
+      answered = true;
+      socket.end(
+        `${JSON.stringify({ ok: false, refusal: "malformed-argument", text: `refused: a verb request may not exceed ${MAX_REQUEST_BYTES} bytes.` })}\n`,
+      );
+      return;
+    }
+    const newline = buffer.indexOf("\n");
+    if (newline < 0) return;
+    void answer(parseJson(buffer.slice(0, newline)));
+  });
+  socket.on("end", () => {
+    if (!answered && buffer.trim().length > 0) void answer(parseJson(buffer));
+  });
+  socket.on("error", () => {
+    socket.destroy();
+  });
+}
+
+/** A body that is not JSON is `undefined`, which the parser refuses by name. */
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}