omp-conductor 0.18.2 → 0.19.1

package/src/verbs/server.ts

@@ -40,15 +40,23 @@
 
 import { randomUUID } from "node:crypto";
 import { createServer, type Server, type Socket } from "node:net";
+import { join } from "node:path";
 
 import { resolvePolicy, resolveReleaseGrants, resolveReview } from "../config.ts";
+import { wakeDispatch } from "../wake.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 {
+  repoSlugFor,
+  type LaneFile,
+  type LaneSource,
+  type RunLaneProbe,
+  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";
@@ -146,6 +154,16 @@ export interface ReleaseExecution {
   shape: ReleaseShape;
   repo: RepoTarget;
   tag?: string;
+  /**
+   * The exact commit a tag shape must point at (#695). Absent means "whatever
+   * the released repo's default branch is at cut time", which is the behaviour
+   * that stranded a tag every time the release window needed a merge: cutting
+   * required a quiet window, reaching that window required merging the open PR,
+   * and merging moved the branch past the tag that had just been cut. A pinned
+   * commit removes the dependence on *when* the tag is cut; the privileged half
+   * still refuses one that is not reachable from that branch.
+   */
+  sha?: string;
   artefact?: string;
   environment?: string;
 }
@@ -178,6 +196,14 @@ export interface VerbActions {
     fields: { title?: string; body?: string },
   ): Promise<{ ok: true } | { ok: false; stderr: string }>;
   mergePr(prUrl: string, headSha: string): Promise<ActionOutcome>;
+  /**
+   * Close one pull request, having first posted `comment` on it (#876).
+   *
+   * Both halves in one action because the ordering is the contract: a close that
+   * lands while its explanation fails leaves a PR nobody can account for, so the
+   * comment goes first and a failed comment means no close.
+   */
+  closePr(prUrl: string, comment: string): Promise<ActionOutcome>;
   release(execution: ReleaseExecution): Promise<ActionOutcome>;
   /**
    * Request the fleet upgrade itself to `version`: refuse when npm does not
@@ -221,6 +247,17 @@ export interface VerbDeps {
    * whether the merge would fork the chain, it never changes it (#227).
    */
   chain: { readBaseChain: typeof readBaseChainType };
+  /**
+   * Read-only access to one run's actual file lane (#925), kept off
+   * {@link VerbDeps.actions} for the same reason {@link VerbDeps.chain} is:
+   * `conductor_pr_recover` consults what a branch carries, it never changes it.
+   *
+   * Required rather than optional on purpose. This seam decides a fail-CLOSED
+   * refusal, so "the field was not wired" must be a compile error rather than a
+   * silently skipped check — an unwired guard that reports success is worse
+   * than no guard, because nothing anywhere says the lane went unproven.
+   */
+  lane: { probeRunLane: RunLaneProbe };
 }
 
 /**
@@ -553,6 +590,12 @@ async function decide(deps: VerbDeps, channel: VerbChannel, raw: unknown): Promi
       verb === "conductor_pr_update_branch" ||
       verb === "conductor_pr_update" ||
       verb === "conductor_pr_review" ||
+      // A clearance disposes of evidence against a PR a pre-pause run already
+      // pushed (#913). It starts no work, and a pause that refused it would
+      // simply relocate the deadlock it exists to break: `conductor_pr_merge`
+      // stays available under a pause, so the one thing that unblocks it must
+      // too.
+      verb === "conductor_pr_review_clear" ||
       verb === "conductor_pr_recover" ||
       verb === "conductor_label");
   const stopped =
@@ -567,7 +610,8 @@ 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_pr_recover, conductor_label), conductor_release and conductor_install remain available.",
+          "conductor_pr_update, conductor_pr_review, conductor_pr_review_clear, conductor_pr_recover, " +
+          "conductor_label), conductor_release and conductor_install remain available.",
       );
     }
   }
@@ -591,6 +635,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_review_clear":
+      return prReviewClearVerb(deps, project, channel, args, refuse, allow);
     case "conductor_pr_recover":
       return prRecoverVerb(deps, project, channel, args, refuse, allow);
     case "conductor_pr_status":
@@ -970,6 +1016,96 @@ async function prMergeVerb(
     }
   }
 
+  // Exact-head review gate (#888): green checks say nothing about the durable
+  // review lifecycle, and #886 merged through exactly that blind spot — CI
+  // green at the live head while a review revision had settled `failed` on
+  // that same head hours earlier. Consulted here, before the lock and every
+  // `gh` call, from the same local rows the review verb writes: any round not
+  // yet settled (queued, or dispatched and crashed mid-review) and any round
+  // settled `failed` at exactly the requested head refuses the merge, unless a
+  // `conductor_pr_review_clear` recorded at or after that round's own last
+  // activity has dispositioned it (#913). A finding tied only to an older head
+  // never appears here — clearance follows the exact head, so a corrected push
+  // is never poisoned.
+  // A head an adjudication decided against never merges (#876), whatever else
+  // is green. The disposition normally closes the PR, so this rarely fires —
+  // but "rarely" is not "never": a close that failed, or a race between the
+  // disposition pass and this call, must not leave a rejected diff mergeable.
+  // Read from the same durable row status renders, so the refusal and the board
+  // cannot disagree.
+  const decided = deps.store.reviewAdjudicationForHead(project.name, prUrl, headSha);
+  if (decided !== undefined && decided.settledAt !== undefined && decided.state !== "cleared") {
+    return refuse(
+      "merge-blocked-by-review",
+      `refused: the review-ceiling adjudication for ${prUrl} at ${headSha.slice(0, 12)} settled ` +
+        `${decided.state}, not cleared${decided.evidence === undefined ? "" : ` — ${decided.evidence}`}. ` +
+        "There is no further review round and no second adjudicator: this head does not merge. " +
+        "Push a corrected head, which is adjudicated on its own merits.",
+      issue,
+    );
+  }
+
+  // The exact-head review-evidence gate (#888), whose reasoning the block above
+  // this one continues from: any round not yet settled (queued, or dispatched
+  // and crashed mid-review) and any round settled `failed` at exactly the
+  // requested head refuses the merge, unless a `conductor_pr_review_clear`
+  // recorded at or after that round's own last activity has dispositioned it.
+  const blocking = deps.store.mergeBlockingReviews(project.name, prUrl, headSha);
+  if (blocking.length > 0) {
+    const b = blocking[0]!;
+    const phase =
+      b.settledAt !== undefined
+        ? `settled ${b.outcome ?? "failed"} with unaddressed findings`
+        : b.dispatchedAt !== undefined
+          ? "was dispatched and never finished (crashed mid-review)"
+          : "is queued and has not been addressed";
+    const more = blocking.length > 1 ? ` (+${blocking.length - 1} further blocking round(s) at this head)` : "";
+    // The advice names only clearances that exist (#913). Re-reviewing the
+    // same head was the old wording's suggestion and it provably does not
+    // work: `enqueueReviewRevision` appends to the pending row or opens a new
+    // unsettled one, so a fresh round at an unchanged head is another blocking
+    // round — and at the review-round ceiling there is no further round to
+    // spend at all.
+    return refuse(
+      "merge-blocked-by-review",
+      `refused: ${prUrl} cannot merge at ${headSha.slice(0, 12)} — review round ${b.round} at this exact head ` +
+        `${phase}${more}. Green checks do not clear durable review findings, and neither does re-reviewing ` +
+        "this head: a fresh `conductor_pr_review` at an unchanged head opens (or appends to) another " +
+        "blocking round rather than superseding one. The two clearances that exist are a corrected head " +
+        "pushed by the run — clearance follows the exact head, so a different head is not poisoned by this " +
+        "one — or an explicit `conductor_pr_review_clear` for this exact head, recorded with its reason.",
+      issue,
+    );
+  }
+
+  // Active release-composition gate (#850): while the project has a release
+  // declared as being assembled, only a PR named in that composition — or one
+  // with an explicit recorded operator override — may merge into it. Placed
+  // after identity resolution and before the merge lock and every tracker
+  // call, so an unrelated green PR is refused without spending a gh round
+  // trip: this is the mechanical form of "a patch contains no unrelated
+  // merges", not a status warning. The override bypasses only this check —
+  // authority, pause, base-red-freeze, exact-head, green-checks and
+  // single-flight all still apply below.
+  const composition = deps.store.activeReleaseComposition(project.name);
+  if (composition !== undefined && !composition.allowedPrUrls.includes(prUrl)) {
+    const overridden =
+      deps.store.releaseCompositionOverride(project.name, composition.campaign, prUrl) !== undefined;
+    if (!overridden) {
+      const allowed =
+        composition.allowedPrUrls.length === 0 ? "none yet" : composition.allowedPrUrls.join(", ");
+      return refuse(
+        "outside-active-release",
+        `refused: ${project.name} is assembling release ${composition.campaign} and ${prUrl} is not in it ` +
+          `(allowed so far: ${allowed}). Merging it would smuggle unrelated work into that release ` +
+          "(outside-active-release). The guard clears only through `omp-conductor release-composition " +
+          "complete|cancel`, or an explicit one-PR `omp-conductor release-composition override --pr <url> " +
+          "--reason <why>` — this call's merge reason is not an override.",
+        issue,
+      );
+    }
+  }
+
   // 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();
@@ -1184,8 +1320,21 @@ async function labelVerb(
     return refuse("action-failed", `refused: the tracker rejected the label change:\n${why}`, ref.issue);
   }
 
+  // A promotion that committed has made an issue claimable *now*, so the
+  // resident daemon is poked rather than leaving the candidate for the next
+  // scheduled pass (#878): three claimable issues once sat against `workers
+  // 0 / 3` for five minutes, which reads from outside exactly like a stalled
+  // queue. Only the queue label earns it — no other label changes what is
+  // dispatchable — and only after the tracker mutation above committed, so a
+  // refused or failed change never pokes anything. The pass it prompts applies
+  // every hold, drain, lane and budget gate as usual.
+  const woken =
+    action === "add" && label === project.queueLabel ? await wakeDispatch(project.name) : undefined;
+
   return allow(
-    echo === undefined ? outcome : `${outcome} File lane: ${echo}.`,
+    [echo === undefined ? outcome : `${outcome} File lane: ${echo}.`, woken]
+      .filter((part) => part !== undefined)
+      .join(" "),
     undefined,
     ref.issue,
   );
@@ -1395,10 +1544,27 @@ async function releaseVerb(
   }
 
   const tag = args["tag"];
+  const sha = args["sha"];
+  // A pinned commit is only meaningful for the two tag shapes; anywhere else it
+  // would be a decorative argument, which is exactly the silent fake this
+  // guards against. Refused rather than ignored, so the caller learns.
+  if (typeof sha === "string" && shape !== "git-tag" && shape !== "git-push-tags") {
+    return refuse(
+      "malformed-argument",
+      `refused: sha pins a tag to one commit and only git-tag and git-push-tags cut tags; you asked for ${shape}.`,
+    );
+  }
+  if (typeof sha === "string" && !FULL_OR_ABBREVIATED_SHA.test(sha)) {
+    return refuse(
+      "malformed-argument",
+      `refused: ${JSON.stringify(sha)} is not a commit id. Pass the exact hex sha the tag must point at.`,
+    );
+  }
   const outcome = await deps.actions.release({
     shape,
     repo,
     ...(typeof tag === "string" ? { tag } : {}),
+    ...(typeof sha === "string" ? { sha } : {}),
     ...(typeof artefact === "string" ? { artefact } : {}),
     ...(typeof environment === "string" ? { environment } : {}),
   });
@@ -1857,11 +2023,46 @@ async function prReviewVerb(
   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.",
+    // The ceiling no longer ends in an operator task (#873, #932). There are no
+    // worker rounds left — that part is unchanged and is the whole point of a
+    // ceiling — so what escalates is the AUTOMATION: this admits one bounded
+    // adjudication under the project's configured stronger role, and the
+    // daemon's next dispatch pass launches it.
+    //
+    // The head is the one already verified live and green above, so a moved head
+    // has refused (`head-stale`) before reaching here: an adjudication is never
+    // opened against a head nobody re-read. The findings being submitted travel
+    // with it — they are the most relevant single input the adjudicator gets,
+    // and dropping them on the floor would make it re-derive (or miss) exactly
+    // the concern that provoked the escalation.
+    const admitted = deps.store.openReviewAdjudication({
+      project: project.name,
+      issue,
+      prUrl,
+      headSha,
+      role: review.adjudicator,
+      findings,
+      requestedAt: deps.now(),
+    });
+    if (admitted.kind === "refused") {
+      return refuse(
+        "review-in-flight",
+        `refused: an adjudication is already live for ${prUrl} at ${admitted.record.headSha} ` +
+          `(${admitted.record.state}), and this call names ${headSha}. That PR moved while it was being ` +
+          "adjudicated; wait for the live adjudication to settle before returning a finding at the new head.",
+        issue,
+      );
+    }
+    // Idempotent by construction: a repeated call at the same head is told the
+    // row it already has, never given a second adjudicator.
+    return allow(
+      admitted.kind === "created"
+        ? `review round ceiling reached (${review.maxRounds}) — recorded a final adjudication for ${prUrl} at ` +
+            `${headSha} under the "${review.adjudicator}" model role. The daemon launches it on its next dispatch ` +
+            "pass; do not review, merge, close or repair this PR by hand."
+        : `an adjudication for ${prUrl} at ${headSha} already exists (${admitted.record.state}) under the ` +
+            `"${admitted.record.role}" role — nothing further to record. The daemon owns it from here.`,
+      undefined,
       issue,
     );
   }
@@ -1922,6 +2123,155 @@ async function prReviewVerb(
   );
 }
 
+/**
+ * Record that the durable review findings standing at one exact head are
+ * settled, so the #888 merge gate stops refusing that head (#913).
+ *
+ * The gate it feeds had no reachable clearance at an unchanged head. Its own
+ * refusal advised a fresh `conductor_pr_review`, and that provably does not
+ * work: `enqueueReviewRevision` either appends the finding to the pending row
+ * or inserts a new unsettled one, and both block. The only other clearances
+ * are a corrected head — which needs a worker — or a round settling
+ * `skipped`/`revised`, which nothing an orchestrator can call does. A PR at
+ * the review-round ceiling was therefore permanently unmergeable at that head:
+ * a gate that can deadlock a release with no way out.
+ *
+ * This is a separate verb rather than an argument on the merge, following
+ * #850's composition override exactly: a merge call's own `reason` is not an
+ * override, because an override that rides inside the act it authorizes leaves
+ * no separable record of the judgement. Here the judgement is its own ledger
+ * row, its own material event and its own append-only table row.
+ *
+ * Three gates, and each exists against a specific way of faking it:
+ *  - **ownership**, through the same `prReviewReadiness` the review verb uses,
+ *    but *without* its revisable-state requirement: the run legitimately sits
+ *    `pushed-green` here, and demanding revisability would make the clearance
+ *    unreachable for exactly the PRs it exists for;
+ *  - **exact head**, re-read live. Green is deliberately NOT required —
+ *    clearing findings and passing checks are different questions, and the
+ *    merge gate re-checks green itself immediately before merging;
+ *  - **non-vacuous**: a clearance at a head where nothing blocks is refused,
+ *    so one can never be banked "just in case" against a finding that has not
+ *    been written yet. Combined with the store's timestamp bound, a clearance
+ *    can only ever dispose of evidence that already existed when it was taken.
+ */
+async function prReviewClearVerb(
+  deps: VerbDeps,
+  project: ProjectConfig,
+  channel: VerbChannel,
+  args: Record<string, unknown>,
+  refuse: Refuse,
+  allow: Allow,
+): Promise<Verdict> {
+  const prUrl = String(args["prUrl"]);
+  const headSha = String(args["headSha"]);
+  const reason = String(args["reason"]);
+
+  // Ownership only: the newest project-owned run that recorded this PR. A
+  // `not-revisable` readiness is the *expected* answer — the run pushed green
+  // and is waiting on the merge — so only `no-owner` refuses here.
+  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 clearance disposes of evidence recorded against a run-owned PR only.",
+    );
+  }
+  const target = readiness.run;
+  if (!prInProjectRouting(project, prUrl)) {
+    return refuse(
+      "pr-not-this-run",
+      `refused: ${prUrl} is not in ${project.name}'s routed repositories ` +
+        `(${Object.values(project.routing.repos).map(repoSlugFor).join(", ") || "none"}).`,
+      target.issue,
+    );
+  }
+  const issue = target.issue;
+
+  if (reason.trim() === "") {
+    return refuse(
+      "malformed-argument",
+      "refused: conductor_pr_review_clear needs a non-empty reason — the reason IS the audit trail for " +
+        "merging a head a review round refused, and an unexplained clearance is indistinguishable from " +
+        "the blanket override this verb exists not to be.",
+      issue,
+    );
+  }
+
+  const paused = orchestratorPauseRefusal(deps, channel, target, refuse);
+  if (paused !== undefined) return paused;
+
+  // Exact head, read live. `verification.headSha` is the live head read in the
+  // same request, so the comparison is against what is on the branch now — not
+  // against the status verdict, which is why a red or pending PR is cleared
+  // just as well as a green one. The merge gate is what insists on green.
+  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}).`, issue);
+  }
+  if (verification === undefined) {
+    return refuse(
+      "head-unresolvable",
+      `refused: the live head of ${prUrl} could not be resolved. Refusing rather than clearing findings ` +
+        "against a head nobody re-read.",
+      issue,
+    );
+  }
+  if (verification.headSha.toLowerCase() !== headSha.toLowerCase()) {
+    return refuse(
+      "head-stale",
+      `refused: ${prUrl} is at ${verification.headSha}, not ${headSha}. A clearance names the exact head ` +
+        "whose findings it disposes of; the branch moved, so those findings no longer stand between this PR " +
+        "and a merge. Re-read the head and re-review it.",
+      issue,
+    );
+  }
+
+  // Non-vacuous. Read after the head check on purpose: if the caller named a
+  // head that moved, the honest refusal is the stale head, not "nothing to
+  // clear".
+  const blocking = deps.store.mergeBlockingReviews(project.name, prUrl, headSha);
+  if (blocking.length === 0) {
+    return refuse(
+      "review-clearance-vacuous",
+      `refused: nothing blocks merging ${prUrl} at ${headSha.slice(0, 12)} — there is no review evidence ` +
+        "at this head to dispose of. A clearance is a disposition of specific findings, never a standing " +
+        "pass recorded ahead of them: a later round at this head would not be cleared by it anyway.",
+      issue,
+    );
+  }
+
+  const cleared = deps.store.recordReviewClearance({
+    project: project.name,
+    prUrl,
+    headSha,
+    by: "orchestrator",
+    reason,
+    at: deps.now(),
+  });
+  deps.store.recordMaterialEvent({
+    project: project.name,
+    category: "review-clearance",
+    summary:
+      `#${issue} review findings cleared at ${headSha.slice(0, 12)} ` +
+      `(round(s) ${blocking.map((row) => row.round).join(", ")}): ${reason}`,
+    evidence: prUrl,
+    occurredAt: cleared.at,
+    recordedAt: cleared.at,
+  });
+  return allow(
+    `cleared ${blocking.length} blocking review round(s) (${blocking.map((row) => row.round).join(", ")}) ` +
+      `for ${prUrl} at ${headSha}: ${reason}. conductor_pr_merge may now proceed at this exact head; every ` +
+      "other gate still applies, and a finding recorded after this clearance blocks again.",
+    headSha,
+    issue,
+  );
+}
+
 /**
  * The run states a missing-PR recovery may act on (#806).
  *
@@ -1947,6 +2297,15 @@ const RECOVERABLE_RUN_STATES: Record<string, true> = {
 /** A complete commit SHA, as current workers record it. */
 const FULL_HEAD_SHA = /^[0-9a-f]{40}$/i;
 
+/**
+ * A commit id a release may pin a tag to (#695): full, or a git-legal
+ * abbreviation of at least 7 hex — the same lower bound the recovery path uses,
+ * because shorter prefixes are ambiguous. Syntax only; whether the commit
+ * exists and is on the released branch is the privileged half's answer, which
+ * needs the mirror.
+ */
+const FULL_OR_ABBREVIATED_SHA = /^[0-9a-f]{7,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
@@ -2416,6 +2775,86 @@ async function prRecoverVerb(
     // through and replace it with a real PR at the verified head.
   }
 
+  // The lane gate (#925), and the last check before anything is published.
+  //
+  // #899 released a worker-free branch's files: its worker is finished, nothing
+  // is writing through it, and holding its whole diff forever idled the fleet.
+  // The consequence is that by the time recovery runs, another worker may
+  // legitimately hold those same files — and publishing this frozen branch then
+  // puts an older diff into review, and into the merge queue, beside a live
+  // worker still rewriting it. That is the one reactivation nothing else
+  // catches: the merge gate reads checks and heads, never who else is mid-edit.
+  //
+  // This half fails CLOSED, unlike admission's interlock, and the asymmetry is
+  // the point. Admission runs unattended on every tick, so refusing there on an
+  // unreadable probe would stall the queue on a transient. Recovery is one
+  // deliberate call whose refusal is legible and retryable: it costs a retry and
+  // names the file, the holder and when to try again. Between "publish
+  // silently on an unproven lane" and "say what could not be read", only the
+  // second is defensible for a call that ends in a public pull request.
+  const leases = deps.store.leasedRuns(project.name).filter((run) => run.repo === target.repo && run.issue !== issue);
+  if (leases.length > 0) {
+    const base = routed.defaultBranch;
+    const mirror = join(project.mirrorRoot, `${target.repo}.git`);
+    const laneOf = async (run: RunRecord): Promise<LaneFile[]> =>
+      deps.lane.probeRunLane({
+        worktree: run.worktree,
+        baseRef: `refs/remotes/origin/${base}`,
+        ...(run.branch === "" ? {} : { branchRef: `refs/heads/${run.branch}` }),
+        mirror,
+      });
+    let carried: LaneFile[];
+    try {
+      carried = await laneOf(target);
+    } catch (err) {
+      return refuse(
+        "recovery-lane-unprovable",
+        `refused: the files preserved branch ${target.branch} carries could not be read ` +
+          `(${err instanceof Error ? err.message : String(err)}), and ${leases.length} live mutation lease(s) are ` +
+          `writing in ${identity}. Recovery will not publish a branch whose overlap with live work is unknown — ` +
+          "retry, or wait for those runs to settle.",
+        issue,
+      );
+    }
+    // A branch that carries nothing cannot collide with anything: no read of
+    // the leaseholders is needed, and none is made.
+    if (carried.length > 0) {
+      const wanted = new Set(carried.map(({ file }) => file));
+      for (const run of leases) {
+        let held: LaneFile[];
+        try {
+          held = await laneOf(run);
+        } catch (err) {
+          return refuse(
+            "recovery-lane-unprovable",
+            `refused: the lane of live run ${run.id} (#${run.issue}, ${run.state}) could not be read ` +
+              `(${err instanceof Error ? err.message : String(err)}), so recovery cannot prove ${target.branch} does ` +
+              "not overlap work in flight. Retry, or wait for that run to settle.",
+            issue,
+          );
+        }
+        // The run's own persisted declaration counts too: a leaseholder admitted
+        // on a lane it has not written yet still owns those files, exactly as
+        // admission's occupancy reads it (#744).
+        const occupies = [
+          ...held.map(({ file, source }) => ({ file, source: source as LaneSource | "declared" })),
+          ...(run.lane?.files ?? []).map((file) => ({ file, source: "declared" as const })),
+        ];
+        const collision = occupies.find(({ file }) => wanted.has(file));
+        if (collision !== undefined) {
+          return refuse(
+            "recovery-lane-occupied",
+            `refused: ${collision.file} is held by run ${run.id} for #${run.issue} (${run.state}, ${collision.source}), ` +
+              `and preserved branch ${target.branch} carries it. Publishing now would put this frozen diff into ` +
+              "review beside a worker still rewriting that file. The lease releases when that run settles — recover " +
+              "then, or land its work first.",
+            issue,
+          );
+        }
+      }
+    }
+  }
+
   // 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

package/src/wake.ts

@@ -0,0 +1,48 @@
+/**
+ * The one bounded client for the resident daemon's loopback wake (#878).
+ *
+ * Extracted from `resume` because three different successful transitions leave
+ * queued work waiting for the next scheduled pass — a promotion to the queue
+ * label, an unblock that restores eligibility, and `resume` itself — and each
+ * one waiting up to five minutes reads, from outside, exactly like a stalled
+ * queue. On 2026-08-21T17:57Z three claimable issues sat unadmitted against
+ * `workers 0 / 3` until the 18:02:33Z pass, and the operator reasonably asked
+ * whether a second dispatcher was needed. It was not: the resident daemon
+ * already owns claims and capacity, and `POST /wake` already exists — the
+ * transitions simply never used it.
+ *
+ * What a wake is NOT: it starts no pass of its own, claims nothing, and skips
+ * nothing. It shortens a sleep. The pass it prompts re-reads every pause file,
+ * drain fence, lane interlock, budget and routing rule exactly as a scheduled
+ * pass does, so a project that is held stays held. Anything else — a shorter
+ * interval, a second `daemon --once`, waking only from the tick — makes the
+ * delay look smaller while leaving idle slots or breaking single-owner safety.
+ *
+ * Every failure is honest and non-fatal: the caller's own mutation already
+ * committed, so a missing or unreachable daemon degrades to "the next scheduled
+ * pass will claim" rather than an error that suggests the mutation failed.
+ */
+
+import { livingDaemon } from "./lifecycle.ts";
+
+/** What the wake attempt did, as the line a human reads after the mutation. */
+export async function wakeDispatch(projectName: string): Promise<string> {
+  const daemon = livingDaemon();
+  if (daemon === undefined) {
+    return "daemon not running — claiming starts when the daemon next starts or ticks";
+  }
+  let response: Response;
+  try {
+    response = await fetch(`http://127.0.0.1:${daemon.port}/wake`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ project: projectName }),
+    });
+  } catch {
+    return "daemon wake failed — daemon unreachable; the next scheduled pass will claim";
+  }
+  if (!response.ok) {
+    return `daemon wake failed (HTTP ${response.status}); the next scheduled pass will claim`;
+  }
+  return "daemon dispatch loop woken — claiming starts on an immediate pass";
+}