omp-conductor 0.17.1 → 0.18.1

package/src/verbs/server.ts

@@ -41,12 +41,21 @@
 import { randomUUID } from "node:crypto";
 import { createServer, type Server, type Socket } from "node:net";
 
-import { resolvePolicy, resolveReleaseGrants } from "../config.ts";
+import { resolvePolicy, resolveReleaseGrants, resolveReview } from "../config.ts";
+// The mediated release is the drain's closing gesture (#791): a successful
+// release ends this project's bounded release window, so the privileged half
+// clears the record through the same operator surface the CLI uses.
+import { cancelDrain } from "../fleet.ts";
+import { effectiveLane, laneEcho, writeLaneSectionHeading } from "../admission.ts";
 import { chainEntriesFromDiff, chainViolations } from "../chain-check.ts";
 import { repoSlugFor, type readBaseChain as readBaseChainType } from "../gitops.ts";
 import { releaseRefusal } from "../release-policy.ts";
+import { PR_LOOKUP_WINDOW_MS, REVISABLE_RUN_STATES, prReviewReadiness } from "../decisions.ts";
 import { LIVE_STATES } from "../store.ts";
 import type {
+  FileLane,
+  IssueComment,
+  IssueState,
   OpenCloser,
   PrState,
   PrVerification,
@@ -56,13 +65,14 @@ import type {
   RepoTarget,
   ReviewReason,
   RunRecord,
+  RunState,
   Store,
   Tracker,
   VerbLedgerEntry,
   VerbName,
   VerbRefusal,
 } from "../types.ts";
-import { prUrlParts } from "../tracker/github.ts";
+import { prUrlParts, GhPrMissingError } from "../tracker/github.ts";
 import { parseVerbRequest, roleRefusal, VERB_SPECS, type VerbReply } from "./protocol.ts";
 import {
   peerVerdict,
@@ -222,11 +232,18 @@ export interface VerbDeps {
  * 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.
+ * daemon's" tells it to stop. The operator's park label is a third kind and a
+ * harder line than either: it is not "not in the vocabulary" (setup creates it,
+ * so that refusal would evaporate the day the vocabulary grows) and not the
+ * daemon's either — it is the operator's, and naming that owner is the point
+ * (#507). An orchestrator that could set or clear a park could hide work it
+ * does not want to groom.
  */
 export interface LabelVocabulary {
   grantable: string[];
   lifecycle: string[];
+  /** Labels only the operator may change: the park gesture. */
+  operator: string[];
 }
 
 export function labelVocabulary(p: ProjectConfig): LabelVocabulary {
@@ -236,6 +253,7 @@ export function labelVocabulary(p: ProjectConfig): LabelVocabulary {
       ...Object.keys(p.routing.repos).map((name) => `${p.routing.labelPrefix}${name}`),
     ],
     lifecycle: [p.stateLabels.inProgress, p.stateLabels.blocked, p.stateLabels.failed],
+    operator: [p.stateLabels.backlog],
   };
 }
 
@@ -306,6 +324,12 @@ export interface ReleaseFacts {
   blockingRuns?: { repo: string; issue: number }[];
   /** Queue depth, or `undefined` when the tracker could not be read. */
   queueDepth: number | undefined;
+  /**
+   * The project this release targets, so a runs-settled refusal can name that
+   * project's own bounded drain command as the remedy (#791). Absent when the
+   * caller cannot name one; the remedy then omits --project.
+   */
+  project?: string;
   /** Current live-head workflow verdict for the released routed repository. */
   baseCheck?: RunRecord["baseCheck"];
   /** Evidence attached to a current red verdict. */
@@ -340,10 +364,20 @@ export function releaseRequirementRefusal(
         facts.blockingRuns === undefined || facts.blockingRuns.length === 0
           ? ""
           : ` — blocking: ${facts.blockingRuns.map((r) => `${r.repo} #${r.issue}`).join(", ")}`;
+      // The bounded drain is the release-window remedy (#484): it pauses only
+      // claiming while the settle pass keeps running, and expires on an
+      // absolute deadline. It is the one command that reaches this gate
+      // honestly — not hold, which stops every pass, and no queue-label
+      // churn, which writes tracker state (#791).
+      const drain =
+        ". Settle the fleet with a bounded drain: " +
+        `omp-conductor drain start${facts.project === undefined ? "" : ` --project ${facts.project}`} --until <deadline>` +
+        " — claiming pauses while settlement runs, and admission resumes at the deadline on its own.";
       return (
         `policy.release.requires includes ${requirement} and ${facts.unsettledRuns} run(s) have not settled` +
         (parts.length === 0 ? "" : ` — ${parts.join("; ")}`) +
-        blocking
+        blocking +
+        drain
       );
     }
     if (requirement === "no-open-prs" && facts.openPrs > 0) {
@@ -519,6 +553,7 @@ async function decide(deps: VerbDeps, channel: VerbChannel, raw: unknown): Promi
       verb === "conductor_pr_update_branch" ||
       verb === "conductor_pr_update" ||
       verb === "conductor_pr_review" ||
+      verb === "conductor_pr_recover" ||
       verb === "conductor_label");
   const stopped =
     spec.mutating && verb !== "conductor_release" && verb !== "conductor_install" && !orchestratorCompletion
@@ -532,7 +567,7 @@ async function decide(deps: VerbDeps, channel: VerbChannel, raw: unknown): Promi
         "fleet-paused",
         `refused: ${stopped}. The pause refuses new claims and work-starting mutations. ` +
           "Completion verbs for runs admitted before the pause (conductor_pr_merge, conductor_pr_update_branch, " +
-          "conductor_pr_update, conductor_label), conductor_release and conductor_install remain available.",
+          "conductor_pr_update, conductor_pr_recover, conductor_label), conductor_release and conductor_install remain available.",
       );
     }
   }
@@ -556,6 +591,8 @@ async function decide(deps: VerbDeps, channel: VerbChannel, raw: unknown): Promi
       return installVerb(deps, project, channel, args, refuse, allow);
     case "conductor_pr_review":
       return prReviewVerb(deps, project, channel, args, refuse, allow);
+    case "conductor_pr_recover":
+      return prRecoverVerb(deps, project, channel, args, refuse, allow);
     case "conductor_pr_status":
       return prStatusVerb(deps, project, channel, args, refuse, allow);
   }
@@ -700,9 +737,9 @@ async function prCreateVerb(
  *
  * 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.
+ * The bound itself is shared with the review watch (`PR_LOOKUP_WINDOW_MS` in
+ * `decisions.ts`), so verb and condition resolve ownership identically.
  */
-export const PR_LOOKUP_WINDOW_MS = 30 * 24 * 60 * 60_000;
-
 function runForPr(deps: VerbDeps, project: string, prUrl: string): RunRecord | undefined {
   // Every attempt that recorded this PR, newest first — not `recentRuns`'
   // newest-attempt-per-issue view. The row a PR belongs to is the newest
@@ -1071,6 +1108,18 @@ async function labelVerb(
 
   const label = String(args["label"]);
   const vocabulary = labelVocabulary(project);
+  if (vocabulary.operator.includes(label)) {
+    // Harder than the lifecycle refusal: add and remove alike, and never
+    // learned away by growing the vocabulary. The park is the operator's
+    // gesture — an orchestrator that can park work can hide work it does not
+    // want to groom (#507).
+    return refuse(
+      "label-is-operator-owned",
+      `refused: ${label} is the operator's park label and only the operator may set or clear it. ` +
+        "No session — orchestrator or worker — may add or remove it; use the tracker directly.",
+      ref.issue,
+    );
+  }
   if (vocabulary.lifecycle.includes(label)) {
     return refuse(
       "label-is-lifecycle",
@@ -1088,6 +1137,36 @@ async function labelVerb(
   }
 
   const action = args["action"] === "remove" ? "remove" : "add";
+  const outcome = `${action === "add" ? "added" : "removed"} ${label} on #${ref.issue}.`;
+  // Adding the queue label is the promotion: the author is asserting the file
+  // lane right now, so the verb echoes the one admission will enforce — the
+  // parsed file list, or the explicit fail-open note (#724). A clearly
+  // delimited write-lane section that parsed nothing REFUSES the promotion
+  // instead of failing open (#825): the echo must never claim fail-open for a
+  // heading that plainly tried to declare one, and failing open beside
+  // overlapping work is the exact gap the interlock exists to close. Best
+  // effort still holds for reads: an unreadable issue or thread can never
+  // block the promotion itself (the label is the point), so a failed read
+  // falls back to the plain message.
+  let echo: string | undefined;
+  let malformed: string | undefined;
+  if (action === "add" && label === project.queueLabel) {
+    const lane = await laneForEcho(deps, ref.issue);
+    if (lane !== undefined) {
+      malformed = lane.malformed;
+      echo = laneEcho(lane.lane);
+    }
+  }
+  if (malformed !== undefined) {
+    return refuse(
+      "file-lane-unparseable",
+      `refused: ${label} was not added — #${ref.issue} declares a write-lane section (${malformed}) but no ` +
+        "path-like files parsed under it, so admission would fail open beside overlapping work. " +
+        'Name the files as backticked bullets directly under the heading (e.g. "- `omp/src/a.ts` — what ' +
+        'changes"), or remove the heading, then add the queue label again.',
+      ref.issue,
+    );
+  }
   // The queue label is the fleet's lock, so it must not ride the GraphQL
   // surface a provider outage just broke: `gh issue edit` is a GraphQL
   // mutation in gh 2.86, and #642 comment 4 measured a label withdrawal
@@ -1104,7 +1183,44 @@ async function labelVerb(
     const why = err instanceof Error ? err.message : String(err);
     return refuse("action-failed", `refused: the tracker rejected the label change:\n${why}`, ref.issue);
   }
-  return allow(`${action === "add" ? "added" : "removed"} ${label} on #${ref.issue}.`, undefined, ref.issue);
+
+  return allow(
+    echo === undefined ? outcome : `${outcome} File lane: ${echo}.`,
+    undefined,
+    ref.issue,
+  );
+}
+
+/**
+ * The effective file lane admission will enforce for one issue, as the
+ * one-line echo (#724), plus the malformed write-lane section marker (#825):
+ * the body plus the whole comment thread, the same inputs `effectiveLane`
+ * reads at admission. `undefined` when either read fails or the tracker cannot
+ * produce the issue — the promotion is never blocked by its own feedback.
+ */
+async function laneForEcho(deps: VerbDeps, issue: number): Promise<
+  | { lane: FileLane | undefined; malformed: string | undefined }
+  | undefined
+> {
+  let body: string;
+  let comments: IssueComment[];
+  try {
+    const row = await deps.tracker.getIssue(issue);
+    if (row === undefined) return undefined;
+    body = row.body;
+    comments = await deps.tracker.listComments(issue);
+  } catch {
+    return undefined;
+  }
+  const lane = effectiveLane(body, comments);
+  if (lane !== undefined) return { lane, malformed: undefined };
+  // No declaration parsed anywhere. If a clearly delimited write-lane section
+  // exists anyway, the section tried to declare and failed — the echo must
+  // refuse, never claim fail-open.
+  const heading =
+    writeLaneSectionHeading(body) ??
+    comments.map((c) => writeLaneSectionHeading(c.body)).find((h) => h !== undefined);
+  return { lane: undefined, malformed: heading };
 }
 
 async function releaseVerb(
@@ -1261,6 +1377,7 @@ async function releaseVerb(
     ...(unconfirmedMerges === undefined ? {} : { unconfirmedMerges }),
     ...(blockingRuns === undefined ? {} : { blockingRuns }),
     queueDepth,
+    project: project.name,
     ...(health === undefined ? {} : { baseCheck: health.verdict }),
     ...(health?.verdict === "red" && health.detail !== undefined
       ? { redBase: health.detail }
@@ -1288,6 +1405,15 @@ async function releaseVerb(
   if (!outcome.ok) {
     return refuse("action-failed", `refused: the release command failed:\n${outcome.stderr}`);
   }
+  // The bounded drain is a release window: it stays latched until the release
+  // work it fences has actually completed, then clears so admission resumes
+  // without a second operator action (#791). Every refusal and failed action
+  // above returned without touching it. The release-window boundary is the
+  // *terminal* act: a version-bump preparation — whether opened, already
+  // prepared, or merged — explicitly leaves git-tag pending (review #1 on
+  // #823), so clearing there would admit a run that makes that follow-up
+  // git-tag fail runs-settled and forces a second drain. Only the final
+  // cut/publish/deploy allow below clears the drain.
   if (shape === "version-bump-pr") {
     if (outcome.review === undefined) {
       return allow(
@@ -1359,6 +1485,7 @@ async function releaseVerb(
       deps.store.releaseMergeLock(project.name, holderId);
     }
   }
+  cancelDrain(project.name);
   return allow(
     `cut ${shape} for ${repo.name}${outcome.detail === undefined ? "" : ` — ${outcome.detail}`}.`,
     outcome.sha,
@@ -1576,12 +1703,41 @@ async function prUpdateVerb(
  * session directory — so a revision round never creates a new attempt and
  * never touches the failed-attempt or continuation budgets.
  *
- * The duplicate in-flight guard has two halves: while a revision is queued
- * but not yet dispatched, the pending `review_revisions` row refuses the
- * second request atomically inside `claimReviewRevision`; once dispatched,
- * the run row itself is `running` (claimed from `pushed-green` by the
- * dispatch pass), which this verb refuses by name.
+ * A second orchestrator axis finishing against the same fixed head before the
+ * first revision dispatches folds its finding into the pending revision
+ * (#786) rather than being refused: one round, one row, one worker attempt,
+ * and the resumed session reads both findings. The fold is only for the same
+ * reviewed head; a pending revision at a different head is a review of a
+ * moved PR and is refused, as is anything once the revision has dispatched.
+ *
+ * The duplicate in-flight guard therefore has two halves: while a revision is
+ * queued but not yet dispatched, the pending `review_revisions` row folds a
+ * same-head finding into itself atomically inside `enqueueReviewRevision` and
+ * refuses a different head; once dispatched, the run row itself is `running`
+ * (claimed from a revisable terminal state by the dispatch pass), which this
+ * verb refuses by name — an already-running worker's prompt is never silently
+ * changed.
+ */
+
+/**
+ * The run states a review revision may start from (#795).
+ *
+ * A revision round resumes the exact run whose row owns the PR, so the
+ * revisable states are exactly the terminal runs that pushed one: a settled
+ * `pushed-green` row, or a `failed` / `killed` row — a run that capped or
+ * failed *after* pushing a green PR. The PR is the durable artefact, the
+ * exact-head green verification in the verb is the gate on "green at the
+ * reviewed SHA", and a terminal row proves no worker is in flight, so the
+ * findings are returned without the close-PR → unblock → continuation dance.
+ *
+ * Closed on purpose: a live row (`running` / `claimed`) is already doing its
+ * own work, a `pushed-pending` PR is not green yet, and a `blocked` /
+ * `orphaned` / `stopped` / `merged` row is not work returned for revision.
+ * The set itself is the shared `REVISABLE_RUN_STATES` in `decisions.ts` —
+ * the one definition the review verb and the `pr-review-ready` watch gate on,
+ * so the two can never drift (#844).
  */
+
 async function prReviewVerb(
   deps: VerbDeps,
   project: ProjectConfig,
@@ -1595,18 +1751,21 @@ async function prReviewVerb(
   const findings = String(args["findings"]);
   const reason = String(args["reason"]) as ReviewReason;
 
-  // The run whose pushed-green row owns the PR — same resolution as merge: the
-  // newest attempt that recorded this PR within the recent-history window. A
-  // PR no run of this project opened (or one outside the routed repos) cannot
-  // be returned to a worker this project can resume.
-  const target = runForPr(deps, project.name, prUrl);
-  if (target === undefined) {
+  // The shared review-readiness gate (#844): the newest project-owned run
+  // that recorded the PR, in a revisable state — the same predicate the
+  // `pr-review-ready` watch reads, so the verb and the condition resolve
+  // ownership and revisability identically. A PR no run of this project
+  // opened (or one outside the routed repos) cannot be returned to a worker
+  // this project can resume.
+  const readiness = prReviewReadiness(deps.store, project.name, prUrl, deps.now());
+  if (readiness.kind === "no-owner") {
     return refuse(
       "pr-not-this-run",
       `refused: ${prUrl} is not a pull request any run in ${project.name} opened. ` +
         "A review revision acts on a run-owned PR only.",
     );
   }
+  const target = readiness.run;
   if (!prInProjectRouting(project, prUrl)) {
     return refuse(
       "pr-not-this-run",
@@ -1625,18 +1784,22 @@ async function prReviewVerb(
     );
   }
 
-  // The revisable state is a settled green run. Any other state is a worker in
-  // flight (the original run or an earlier revision) or a run whose PR no
-  // longer waits on revision — the detail names the state field that produced
-  // the refusal.
-  if (target.state !== "pushed-green") {
+  // The revisable state is a run that pushed a green PR and is not live: a
+  // settled `pushed-green` row, or a `failed` / `killed` row — a run that
+  // capped or failed after the push (#795). The exact-head verification below
+  // still re-reads the PR and insists it is green at the reviewed SHA, so
+  // admitting a capped row here never reviews a PR that stopped being green.
+  // Any other state is a worker in flight (the original run or an earlier
+  // revision) or a run whose PR no longer waits on revision — the detail names
+  // the state field that produced the refusal.
+  if (readiness.kind !== "ready") {
     const live = target.state === "running" || target.state === "claimed";
     return refuse(
       "review-in-flight",
-      `refused: run ${target.id} is ${target.state}, not pushed-green — ${
+      `refused: run ${target.id} is ${target.state}, not a settled green run — ${
         live
           ? `a worker (the original run or an earlier revision) is still live on ${prUrl}; wait for it to settle before returning it.`
-          : `a review revision starts from a settled green run, and this one is ${target.state}.`
+          : `a review revision starts from a run that pushed a green PR, and this one is ${target.state}.`
       }`,
       issue,
     );
@@ -1678,11 +1841,53 @@ async function prReviewVerb(
     );
   }
 
-  // Durable, and refused atomically against a concurrent duplicate: the row is
-  // persisted before any wake, and a second request for the same run bumps
-  // into the pending row rather than racing it.
+  // The hard bound (#678): the round ceiling is the dispatcher's, not the
+  // orchestrator's to re-read from prose. A PR may be returned at most
+  // `maxRounds` times per lifecycle; at the ceiling this refuses, and the
+  // refusal states the two non-actions that replace a further round — leave
+  // the PR open, record the unresolved findings and escalate once. The same
+  // count `latestReviewRound` drives the renderer's `review-revision N`, so
+  // the bound and the visible round can never disagree.
+  //
+  // A finding that folds into an already-pending revision opens no round, so
+  // the ceiling never binds an append — only a genuine new round counts. The
+  // store is the single authority on the fold; this read exists only to
+  // decide whether the ceiling gates this call.
+  const review = resolveReview(project);
+  const pendingForRun = deps.store.pendingReviewForRun(project.name, target.id);
+  if (pendingForRun === undefined && deps.store.latestReviewRound(project.name, target.id) >= review.maxRounds) {
+    return refuse(
+      "review-round-ceiling",
+      `refused: ${prUrl} has already been through ${review.maxRounds} review round(s) ` +
+        `(project "${project.name}" is ${review.strictness} strictness, ceiling ${review.maxRounds}). ` +
+        "Leave the PR open, record the unresolved findings, and escalate once — a further revision round is not available.",
+      issue,
+    );
+  }
+
+  // The run row is re-read synchronously, immediately before the durable
+  // enqueue and with no await in between: the daemon's dispatch pass
+  // (`pushed-green` → `running`) cannot land inside a single synchronous
+  // block, so a revision that dispatched while the live-head verification
+  // above was in flight is refused here rather than racing the worker that
+  // now owns the PR — an already-running worker's prompt is never silently
+  // changed.
+  const fresh = deps.store.getRun(target.id);
+  if (fresh === undefined || REVISABLE_RUN_STATES[fresh.state] !== true) {
+    return refuse(
+      "review-in-flight",
+      `refused: run ${target.id} is no longer revisable on ${prUrl} (now ${fresh?.state ?? "gone"}) — ` +
+        "the pending revision has dispatched to a worker. " +
+        "Wait for it to settle, then return the finding as its own later review round.",
+      issue,
+    );
+  }
+
+  // Durable, and decided atomically against a concurrent same-head request:
+  // the same transaction that records a new round also folds a same-head
+  // finding into the one already pending, and the merge never overwrites.
   const round = deps.store.latestReviewRound(project.name, target.id) + 1;
-  const recorded = deps.store.createReviewRevision({
+  const enqueued = deps.store.enqueueReviewRevision({
     project: project.name,
     runId: target.id,
     issue,
@@ -1691,20 +1896,531 @@ async function prReviewVerb(
     findings,
     round,
     reason,
-    ...(target.sessionFile === undefined ? {} : { sessionFile: target.sessionFile }),
+    ...(fresh.sessionFile === undefined ? {} : { sessionFile: fresh.sessionFile }),
     requestedAt: deps.now(),
   });
-  if (recorded === undefined) {
+  if (enqueued.kind === "refused") {
     return refuse(
       "review-in-flight",
-      `refused: a review revision is already pending for ${prUrl} (run ${target.id}); exactly one revision is in flight per PR.`,
+      `refused: a review revision is already pending for ${prUrl} (run ${target.id}) at a different head — ` +
+        "amend nothing, because that round reviewed a moved PR. Wait for it to dispatch and settle, then return the finding as its own later review round.",
+      issue,
+    );
+  }
+  const revision = enqueued.record;
+  return allow(
+    enqueued.kind === "created"
+      ? `recorded review round ${revision.round} for ${prUrl} at ${headSha}; the daemon will resume run ${target.id}'s session` +
+          `${fresh.sessionFile === undefined ? "" : ` (${fresh.sessionFile})`} on its next dispatch pass.`
+      : `appended a finding to the pending review round ${revision.round} for ${prUrl} at ${headSha}; ` +
+          "the daemon will resume run " +
+          `${target.id}'s session${fresh.sessionFile === undefined ? "" : ` (${fresh.sessionFile})`} on its next dispatch pass ` +
+          "and the resumed worker reads both findings.",
+    undefined,
+    issue,
+  );
+}
+
+/**
+ * The run states a missing-PR recovery may act on (#806).
+ *
+ * Recovery exists for a run whose worker finished and recorded an exact head
+ * but whose PR never materialised — exactly the states the settlement sweep
+ * owns: `pushed-pending` (the #777/#809 ghosts) and `pushed-green`. Those
+ * rows sit in the store's active set, so the sweep verifies the recovered
+ * PR's checks on its next tick (`pushed-pending` → `pushed-green`) and
+ * review/merge settlement resumes normally. A terminal row outside this set —
+ * failed/killed/stopped/orphaned/blocked — has its own prescribed
+ * reconciliation (continuation or review revision, operator stop, restart
+ * reconciliation, unblock), and receiving a PR would strand it: nothing would
+ * ever verify, review or merge it.
+ *
+ * Closed on purpose, like {@link REVISABLE_RUN_STATES}: recovery may never
+ * widen into a state the daemon's own sweep does not revisit.
+ */
+const RECOVERABLE_RUN_STATES: Record<string, true> = {
+  "pushed-pending": true,
+  "pushed-green": true,
+};
+
+/** A complete commit SHA, as current workers record it. */
+const FULL_HEAD_SHA = /^[0-9a-f]{40}$/i;
+
+/**
+ * A legacy abbreviated commit SHA (#836): the `git rev-parse --short` output
+ * an older worker generation recorded instead of the full SHA. Git defaults
+ * to 7 hex characters and lengthens the abbreviation when 7 is ambiguous, so
+ * a legacy record is always at least 7 hex; 4–6 hex are git-legal
+ * abbreviations but cannot be legacy records, and at that length the prefix
+ * evidence is too weak for an identity recovery to rest on. Anything shorter
+ * than git's own abbreviation minimum (4) is not a usable object id at all —
+ * ambiguous, and it fails closed.
+ */
+const ABBREVIATED_HEAD_SHA = /^[0-9a-f]{7,39}$/i;
+
+/**
+ * Open (or adopt) the missing pull request for a settled run whose branch was
+ * preserved (#806).
+ *
+ * A worker that pushed and recorded an exact head can still leave the run
+ * spent: the PR it claimed never existed (a guessed URL — #779), or the run
+ * settled before a PR was ever opened. Nothing else in the verb surface can
+ * act then — the mediated PR verbs resolve the PR from a URL some run
+ * recorded (`conductor_pr_review` refuses "not a PR any run opened"), the
+ * worker-only create verb is gone with the worker, and the package-floor
+ * fallback is a fresh clone and re-push, which republishes code. This is the
+ * strictly smaller act: publish the pull request the run's work already
+ * earned, at the exact head the daemon recorded.
+ *
+ * Every identity the worker's own `conductor_pr_create` read off its live
+ * channel is re-proven here in its absence:
+ *  - the run is terminal — no worker is live on it (`claimed`/`running`
+ *    refuse, and a merged row is resolved, not recoverable);
+ *  - the routed repository is still routed, and the branch comes from the run
+ *    row, never from an argument — `branch`/`base`/`headSha` are assertions
+ *    exactly as on the worker verb, and a disagreement is a refusal, never a
+ *    redirect;
+ *  - the remote branch still exists at the recorded identity: a 40-hex head
+ *    must equal the live branch head exactly, and a legacy abbreviated head
+ *    (7–39 hex, #836) may only canonicalize against the fixed routed branch —
+ *    the live branch head must begin with it, and that canonical object is
+ *    the identity compared everywhere after, never an argument;
+ *  - the issue still wants the work: a closed issue, a merged row or a merged
+ *    recorded PR is "resolved" and refuses; a recorded PR a human closed
+ *    without merging refuses as `pr-not-open`;
+ *  - no PR already represents that head: an open closer on the run's branch
+ *    at the recorded head is adopted (idempotent — the row gains the URL it
+ *    never recorded, so review/merge verbs can act on it), an open closer at
+ *    a different head or on another branch refuses, and a recorded PR that is
+ *    still open is that same recovery's answer.
+ *
+ * The PR describes itself from durable state only — no title/body arguments,
+ * because nothing here may publish a headline a session did not already
+ * settle. A definitively missing recorded PR (a corroborated 404 — the #779
+ * guess) is replaced by the new one; an unreadable recorded PR, unreadable
+ * branch head or unreadable closer list fails closed and stays retryable.
+ */
+async function prRecoverVerb(
+  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 recovered PR 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}).`,
+    );
+  }
+
+  // The run is the newest attempt for the issue — the row that occupies the
+  // issue's slot, and exactly the row `unblock`/`worker stop` name by issue
+  // number. Recovery never re-implements dispatch's per-issue choice.
+  const target = deps.store.latestRun(project.name, ref.issue);
+  if (target === undefined) {
+    return refuse(
+      "recovery-no-run",
+      `refused: ${project.name} has no recorded attempt for #${ref.issue}, so there is no run branch to recover a ` +
+        "pull request for. Check the issue's status before trying again.",
+    );
+  }
+  const issue = target.issue;
+
+  if (LIVE_STATES.some((state) => state === target.state)) {
+    return refuse(
+      "recovery-run-live",
+      `refused: run ${target.id} for #${issue} is ${target.state} — a worker is still live on it. ` +
+        "Recovery opens the missing PR only for a settled run; wait for it to settle (or stop the worker) first.",
+      issue,
+    );
+  }
+  if (target.state === "merged") {
+    return refuse(
+      "recovery-issue-resolved",
+      `refused: run ${target.id} for #${issue} already merged — the work landed and there is no missing PR to recover.`,
+      issue,
+    );
+  }
+  if (RECOVERABLE_RUN_STATES[target.state] !== true) {
+    const guidance =
+      target.state === "failed" || target.state === "killed"
+        ? "A failed or killed run's branch continues through `omp-conductor unblock` (continuation), or through a review revision once it owns a PR."
+        : target.state === "stopped"
+          ? "The operator ended this run; recovery does not reopen stopped work."
+          : target.state === "orphaned"
+            ? "Restart reconciliation owns orphaned runs."
+            : "Answer the run's question and unblock the issue.";
+    return refuse(
+      "recovery-unsettled-state",
+      `refused: run ${target.id} for #${issue} is ${target.state}, a state the settlement sweep does not own — a ` +
+        `recovered PR would never be verified, reviewed or merged. ${guidance}`,
+      issue,
+    );
+  }
+
+  const paused = orchestratorPauseRefusal(deps, channel, target, refuse);
+  if (paused !== undefined) return paused;
+
+  const routed = Object.values(project.routing.repos).find((repo) => repo.name === target.repo);
+  if (routed === undefined) {
+    return refuse(
+      "recovery-repo-unrouted",
+      `refused: run ${target.id} was routed to repository ${target.repo}, which ${project.name} no longer routes ` +
+        `(${Object.values(project.routing.repos).map(repoSlugFor).join(", ") || "none"}). ` +
+        "A recovery PR cannot be created for a repository the daemon has no entry for; re-route the repo first.",
+      issue,
+    );
+  }
+
+  // The recorded head the preserved branch must still carry. Absent, the
+  // recovery cannot prove it would publish this run's work rather than
+  // whatever the branch tip happens to be — fail closed on the missing
+  // record. Legacy rows recorded git's default abbreviation (`rev-parse
+  // --short`, 7+ hex) instead of the full SHA; those stay eligible and are
+  // canonicalized against the fixed routed branch below (#836).
+  const recordedHead = target.headSha;
+  if (recordedHead === undefined) {
+    return refuse(
+      "recovery-unrecorded-head",
+      `refused: run ${target.id} for #${issue} records no head to verify its branch against. ` +
+        "Recovery publishes only the head the run itself recorded.",
+      issue,
+    );
+  }
+  const isFullHead = FULL_HEAD_SHA.test(recordedHead);
+  const isAbbreviatedHead = !isFullHead && ABBREVIATED_HEAD_SHA.test(recordedHead);
+  if (!isFullHead && !isAbbreviatedHead) {
+    return refuse(
+      "recovery-unrecorded-head",
+      `refused: run ${target.id} for #${issue} records ${JSON.stringify(recordedHead)}, which is neither a full ` +
+        "40-hex SHA nor an unambiguous legacy abbreviation of one (7–39 hex). Recovery publishes only the head " +
+        "the run itself recorded.",
+      issue,
+    );
+  }
+
+  // Assertions, never selectors — the mirror of `conductor_pr_create`'s
+  // head/base claims. A disagreement means the caller is pointing somewhere
+  // the run row does not own; the daemon derives everything from the row.
+  const claimedBranch = args["branch"];
+  if (typeof claimedBranch === "string" && claimedBranch !== target.branch) {
+    return refuse(
+      "ref-not-run-branch",
+      `refused: run ${target.id}'s recorded branch is ${target.branch}, and you named "${claimedBranch}". ` +
+        "Recovery derives the head branch from the run; it cannot be pointed at another branch.",
+      issue,
+    );
+  }
+  const claimedBase = args["base"];
+  if (typeof claimedBase === "string" && claimedBase !== routed.defaultBranch) {
+    return refuse(
+      "base-not-default-branch",
+      `refused: ${routed.name} targets ${routed.defaultBranch}, and you named "${claimedBase}". ` +
+        "The base is the configured defaultBranch, not an argument.",
+      issue,
+    );
+  }
+  const claimedHead = args["headSha"];
+  if (typeof claimedHead === "string" && claimedHead.toLowerCase() !== recordedHead.toLowerCase()) {
+    return refuse(
+      "recovery-head-mismatch",
+      `refused: run ${target.id} recorded head ${recordedHead}, and you asserted "${claimedHead}". ` +
+        "The exact recorded head is the daemon's, not a selector.",
+      issue,
+    );
+  }
+
+  // Closed issues are resolved issues: a merge closed it, or a human closed it
+  // without merging. Either way it does not want a recovered PR — and an
+  // unreadable state is not a green light: "could not tell" must never open a
+  // PR beside (or for) an issue that may already be closed, so it fails
+  // closed and stays retryable like every sibling read in this verb.
+  let issueState: IssueState | undefined;
+  try {
+    issueState = await deps.tracker.issueState(issue);
+  } catch (err) {
+    issueState = undefined;
+    deps.log(`conductor_pr_recover could not read #${issue} state: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (issueState === undefined) {
+    return refuse(
+      "issue-state-unreadable",
+      `refused: the tracker could not say whether #${issue} is open. An unreadable state is not a green light — ` +
+        "retry before recovering, so a recovered PR is never opened beside (or for) a closed issue.",
+      issue,
+    );
+  }
+  if (issueState === "closed") {
+    return refuse(
+      "recovery-issue-resolved",
+      `refused: #${issue} is closed. The work already merged or a human declined it; recovery does not reopen either.`,
+      issue,
+    );
+  }
+
+  // The branch/head verification: the routed repository's branch, read live,
+  // must still sit at the exact head this run recorded. This is the proof the
+  // PR to be created publishes verified work and not something that replaced
+  // it. An unreadable branch stays retryable — that is "could not tell", never
+  // a green light.
+  const identity = repoSlugFor(routed);
+  let liveBranchHead: string | undefined;
+  try {
+    liveBranchHead = await deps.tracker.branchHead(identity, target.branch);
+  } catch (err) {
+    liveBranchHead = undefined;
+    deps.log(
+      `conductor_pr_recover could not read ${identity}/${target.branch} head: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (liveBranchHead === undefined) {
+    return refuse(
+      "head-unresolvable",
+      `refused: the live head of ${identity}/${target.branch} could not be read. That is a transient or unknown ` +
+        "state, not a green light — retry before recovering, and check the branch still exists.",
+      issue,
+    );
+  }
+
+  // The canonical object, decided from the fixed routed branch only (#836). A
+  // full 40-hex record keeps its exact-identity behavior: the branch must
+  // still sit at that object. A legacy abbreviated record can never be used
+  // as an identity on its own — the live branch head must literally begin
+  // with the abbreviation, and that full head becomes the identity every
+  // later check compares against (PR adoption, no-duplicate proof, the PR's
+  // own description). Nothing resolves the abbreviation anywhere else, and
+  // never from caller input: `headSha` remains an assertion of the recorded
+  // value, so no argument can appoint a different object.
+  const canonicalHead: string = isFullHead ? recordedHead : liveBranchHead;
+  if (isAbbreviatedHead) {
+    if (!FULL_HEAD_SHA.test(liveBranchHead)) {
+      return refuse(
+        "head-unresolvable",
+        `refused: the live head of ${identity}/${target.branch} is ${liveBranchHead}, not a full commit SHA, so the ` +
+          `recorded abbreviation ${recordedHead} cannot be canonicalized against it. That is an unknown state, not a ` +
+          "green light — retry before recovering.",
+        issue,
+      );
+    }
+    if (!liveBranchHead.toLowerCase().startsWith(recordedHead.toLowerCase())) {
+      return refuse(
+        "recovery-head-mismatch",
+        `refused: ${identity}/${target.branch} now points at ${liveBranchHead}, which does not begin with the ` +
+          `recorded run head ${recordedHead}. A legacy abbreviated head canonicalizes only against a branch that ` +
+          "still carries it; the branch was replaced, force-updated or continued elsewhere — a PR created now would " +
+          "publish work the daemon did not verify at that head. Do not force; reconcile what the branch should be first.",
+        issue,
+      );
+    }
+  } else if (liveBranchHead.toLowerCase() !== recordedHead.toLowerCase()) {
+    return refuse(
+      "recovery-head-mismatch",
+      `refused: ${identity}/${target.branch} now points at ${liveBranchHead}, not the recorded run head ${recordedHead}. ` +
+        "The branch was replaced, force-updated or continued elsewhere — a PR created now would publish work the daemon " +
+        "did not verify at that head. Do not force; reconcile what the branch should be first.",
+      issue,
+    );
+  }
+
+  // The no-duplicate-proof: any OPEN PR that already closes the issue. The
+  // run's own branch at the recorded head is the run's PR (whoever opened it —
+  // the operator's manual recovery is PR #805 for run #777) and is adopted,
+  // idempotently; the same branch at a different head, or another branch with
+  // the issue, each refuse rather than duplicate.
+  let closers: OpenCloser[];
+  try {
+    closers = await deps.tracker.openClosersFor(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 #${issue} already has an open pull request (${why}). ` +
+        "Refusing rather than opening a second one.",
+      issue,
+    );
+  }
+  const sameBranch = closers.find(
+    (closer) => closer.headRefName !== "" && closer.headRefName === target.branch && closer.repo === identity,
+  );
+  if (sameBranch !== undefined) {
+    let live: string | undefined;
+    try {
+      live = await deps.tracker.prHead(sameBranch.url);
+    } catch (err) {
+      live = undefined;
+      deps.log(
+        `conductor_pr_recover could not read ${sameBranch.url} head: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    if (live === undefined) {
+      return refuse(
+        "head-unresolvable",
+        `refused: ${sameBranch.url} is open on ${target.branch}, but its head could not be read. ` +
+          "Retry before deciding whether to adopt it or treat it as a conflict.",
+        issue,
+      );
+    }
+    if (live.toLowerCase() === canonicalHead.toLowerCase()) {
+      const already = deps.store.getRun(target.id)?.prUrl === sameBranch.url;
+      if (!already) deps.store.updateRun(target.id, { prUrl: sameBranch.url });
+      return allow(
+        `recovered ${sameBranch.url} — an open pull request already exists at run head ${canonicalHead} ` +
+          `(${target.branch}); ${
+            already
+              ? "it is already this run's recorded PR"
+              : `recorded it on run ${target.id} so review and merge verbs can act on it`
+          }.`,
+        undefined,
+        issue,
+      );
+    }
+    return refuse(
+      "recovery-head-mismatch",
+      `refused: ${sameBranch.url} is open on ${target.branch} but at ${live}, not the recorded run head ${canonicalHead}. ` +
+        "That open PR superseded the run's recorded head; a second PR would duplicate it.",
+      issue,
+    );
+  }
+  if (closers.length > 0) {
+    const other = closers[0]!;
+    return refuse(
+      "open-pr-exists",
+      `refused: ${other.url} is already open and already closes #${issue} (head ${other.headRefName || "unknown"} in ${
+        other.repo || "unknown"
+      }). Recovery opens a PR only for the run's own preserved branch, and this issue already has open work.`,
       issue,
     );
   }
 
+  if (target.prUrl !== undefined) {
+    // The run believes it has a PR. Before creating one, the recorded URL is
+    // decided: still open → it is the recovery's answer (idempotent); merged →
+    // the work landed; closed → a human declined it; definitively missing →
+    // the #779 guess, replaced by a real PR below.
+    let recorded: PrState | "missing" | undefined;
+    try {
+      recorded = await deps.tracker.prState(target.prUrl);
+    } catch (err) {
+      recorded = err instanceof GhPrMissingError ? "missing" : undefined;
+      if (recorded !== "missing") {
+        deps.log(
+          `conductor_pr_recover could not read recorded PR ${target.prUrl}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+    if (recorded === "open") {
+      // An open recorded PR is the recovery's answer only when it actually
+      // represents the recorded head — otherwise it is some other PR the row
+      // once believed in, and answering "already open, nothing to create"
+      // would leave the run's own head unpublished.
+      let recordedLive: string | undefined;
+      try {
+        recordedLive = await deps.tracker.prHead(target.prUrl);
+      } catch (err) {
+        recordedLive = undefined;
+        deps.log(
+          `conductor_pr_recover could not read ${target.prUrl} head: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+      if (recordedLive === undefined) {
+        return refuse(
+          "head-unresolvable",
+          `refused: ${target.prUrl} is open, but its head could not be read. ` +
+            "Retry before deciding whether it is this run's PR or another one.",
+          issue,
+        );
+      }
+      if (recordedLive.toLowerCase() === canonicalHead.toLowerCase()) {
+        return allow(
+          `recovered ${target.prUrl} — this run's recorded pull request is already open at the recorded head; nothing to create.`,
+          undefined,
+          issue,
+        );
+      }
+      return refuse(
+        "recovery-head-mismatch",
+        `refused: the run records ${target.prUrl}, which is open at ${recordedLive}, not the recorded run head ${canonicalHead}. ` +
+          "That PR is not this run's head; recovery cannot claim it. Match the PR to the head by hand, or close it and recover afresh.",
+        issue,
+      );
+    }
+    if (recorded === "merged") {
+      return refuse(
+        "recovery-issue-resolved",
+        `refused: the run's recorded PR ${target.prUrl} already merged — the work landed; there is no missing PR to recover.`,
+        issue,
+      );
+    }
+    if (recorded === "closed") {
+      return refuse(
+        "pr-not-open",
+        `refused: the run's recorded PR ${target.prUrl} was closed without merging. ` +
+          "Recovery does not resurrect a PR a human declined; reopen it by hand if that was a mistake.",
+        issue,
+      );
+    }
+    if (recorded === undefined) {
+      return refuse(
+        "head-unresolvable",
+        `refused: the run records PR ${target.prUrl}, but its state could not be read. ` +
+          "Retry rather than creating a second PR next to one that may exist.",
+        issue,
+      );
+    }
+    // `missing`: the recorded URL provably never existed (a #779 guess). Fall
+    // through and replace it with a real PR at the verified head.
+  }
+
+  // The PR's own voice comes from durable state only: the issue title and the
+  // run's settlement report. The closing keyword must name the TRACKER
+  // repository — the issue lives there, not in the routed code repo, and
+  // `openClosersFor` asks the tracker's GraphQL `closedByPullRequestsReferences`
+  // whether an OPEN PR already closes it. A keyword aimed at the code repo
+  // would close an unrelated same-numbered issue there, leave the tracker
+  // issue open, and hide this PR from the duplicate guard on the next call.
+  let issueTitle: string | undefined;
+  try {
+    issueTitle = (await deps.tracker.getIssue(issue))?.title;
+  } catch (err) {
+    issueTitle = undefined;
+    deps.log(`conductor_pr_recover could not read #${issue} title: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const body = [
+    `Closes ${project.tracker.repo}#${issue}`,
+    "",
+    `Recovered pull request for run ${target.id} (attempt ${target.attempt}).`,
+    `The run ended ${target.state} with no pull request; this PR opens its preserved branch ${target.branch} at the ` +
+      `exact recorded head ${canonicalHead} through the orchestrator's conductor_pr_recover verb.`,
+    ...(target.report === undefined ? [] : ["", "Worker report:", "", target.report]),
+  ].join("\n");
+  // The worktree of a settled run is long removed; `openRunPr` resolves
+  // everything from the remote identities (repo slug, branch, base) and never
+  // opens the path — it is carried only to satisfy the shared action surface.
+  const outcome = await deps.actions.createPr(
+    { repo: routed, runRepoPath: target.worktree, branch: target.branch },
+    {
+      title: issueTitle ?? `recover ${target.branch} (${project.tracker.repo} #${issue})`,
+      body,
+      base: routed.defaultBranch,
+    },
+  );
+  if (!outcome.ok) {
+    return refuse("action-failed", `refused: gh could not open the recovered pull request:\n${outcome.stderr}`, issue);
+  }
+  deps.store.updateRun(target.id, { prUrl: outcome.url });
   return allow(
-    `recorded review round ${round} for ${prUrl} at ${headSha}; the daemon will resume run ${target.id}'s session` +
-      `${target.sessionFile === undefined ? "" : ` (${target.sessionFile})`} on its next dispatch pass.`,
+    `opened ${outcome.url} for ${target.branch} at ${canonicalHead} (${identity} → ${routed.defaultBranch}), ` +
+      "recorded on the run so review/merge settlement resumes.",
     undefined,
     issue,
   );
@@ -1743,6 +2459,14 @@ export class VerbSocketRefusal extends Error {
 export interface ListenOptions {
   peerReader?: PeerReader;
   daemonUid?: number;
+  /**
+   * The identity the channel is secured to — the worker account for a worker
+   * run channel (#798). When set, the bound socket is chowned to that uid/gid
+   * (the worker child, and only it, must be able to connect) and the peer
+   * verdict expects that uid on the wire. Absent, the channel stays
+   * daemon-owned and daemon-uid as today (orchestrator, tests).
+   */
+  channelOwner?: { uid: number; gid: number };
   /** Injected in tests; the real one chowns, which needs privilege. */
   secure?: typeof secureBoundSocket;
 }
@@ -1780,8 +2504,10 @@ export async function listenVerbChannel(
   // a connection arrives, not the one that existed when the server was created.
   let boundPid: number | undefined;
 
+  const expectedUid = opts.channelOwner?.uid ?? process.getuid?.() ?? 0;
+
   const server: Server = createServer((socket) => {
-    handleConnection(deps, channel, socket, opts.peerReader, () => boundPid);
+    handleConnection(deps, channel, socket, opts.peerReader, () => boundPid, expectedUid);
   });
   server.on("error", (err) => {
     deps.log(`verb socket ${channel.path} errored: ${err.message}`);
@@ -1795,7 +2521,10 @@ export async function listenVerbChannel(
     });
   });
 
-  const secure = opts.secure ?? secureBoundSocket;
+  // A worker-run channel belongs to the worker: the socket is chowned to it so
+  // the session child can connect, and the ownership line in the startup banner
+  // says so rather than guessing.
+  const secure = opts.secure ?? ((path: string) => secureBoundSocket(path, { owner: opts.channelOwner }));
   const ownership = secure(channel.path);
 
   return {
@@ -1821,6 +2550,7 @@ function handleConnection(
   socket: Socket,
   peerReader: PeerReader | undefined,
   boundPid: () => number | undefined,
+  expectedUid: number,
 ): void {
   const fd = socketFd(socket);
   const peer = fd === undefined || peerReader === undefined ? undefined : peerReader(fd);
@@ -1837,12 +2567,12 @@ function handleConnection(
       ? {
           ok: false,
           peerUid: peer?.uid ?? -1,
-          expectedUid: process.getuid?.() ?? 0,
+          expectedUid,
           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",
+            "this socket is 0600 and its owner is the only uid that can reach it",
         }
-      : peerVerdict({ uid: process.getuid?.() ?? 0, pid: expectedPid }, peer);
+      : peerVerdict({ uid: expectedUid, 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.