omp-conductor 0.18.2 → 0.19.1

package/src/verbs/actions.ts

@@ -321,6 +321,46 @@ export function githubVerbActions(
       : { ok: true, sha };
   };
 
+  /**
+   * Resolve a caller-pinned release commit and prove it belongs on the released
+   * branch (#695).
+   *
+   * Two questions, both fail-closed. `rev-parse <sha>^{commit}` answers "does
+   * this commit exist in the released repository at all" — an abbreviation is
+   * expanded here, so what the tag receives is always a full id. `merge-base
+   * --is-ancestor` answers the one that matters: a tag pointing at a commit
+   * that is not on the released branch is a release of code nobody merged, and
+   * that is the failure a decorative `sha` argument would create. The ancestor
+   * check accepts the branch tip itself, which is the ordinary case.
+   */
+  const pinnedReleaseCommit = async (
+    mirror: string,
+    repo: RepoTarget,
+    sha: string,
+  ): Promise<CommitOutcome> => {
+    const resolved = await readCommit(mirror, ["rev-parse", `${sha}^{commit}`], `pinned commit ${sha}`);
+    if (!resolved.ok) {
+      return {
+        ok: false,
+        stderr:
+          `refusing release: ${sha} is not a commit in ${repo.name}. ` +
+          `Pass a commit that exists on ${repo.defaultBranch}.\n${resolved.stderr}`,
+      };
+    }
+    const branchRef = `refs/remotes/origin/${repo.defaultBranch}`;
+    const reachable = await git(mirror, ["merge-base", "--is-ancestor", resolved.sha, branchRef]);
+    if (!reachable.result.ok) {
+      return {
+        ok: false,
+        stderr:
+          `refusing release: ${resolved.sha} is not reachable from ${repo.name}'s ${repo.defaultBranch}. ` +
+          "A tag must never point at a commit that is not on the released branch — check the sha, or " +
+          "wait for the commit to land.",
+      };
+    }
+    return resolved;
+  };
+
   const releaseTargetMoved = (repo: RepoTarget, target: string, live: string): { ok: false; stderr: string } => ({
     ok: false,
     stderr:
@@ -636,6 +676,38 @@ export function githubVerbActions(
       };
     },
 
+    // Closing a rejected PR is the one destructive half of an adjudication's
+    // disposition (#876), and it is REST rather than `gh pr close` for the same
+    // reason `updatePrBranch` is: a selective GraphQL outage must not leave a
+    // rejected PR open, permanently blocking the issue's reimplementation.
+    closePr: async (prUrl, comment) => {
+      const parts = prUrlParts(prUrl);
+      if (parts === undefined) {
+        return { ok: false, stderr: `could not parse ${prUrl} as a pull request URL` };
+      }
+      // The comment first, and only then the close: a closed PR still shows its
+      // comments, but a close that succeeds while the explanation fails leaves a
+      // PR nobody can account for. Ordering the durable explanation before the
+      // irreversible act is the same rule the merge path follows.
+      const said = await gh([
+        "api",
+        "--method",
+        "POST",
+        `repos/${parts.owner}/${parts.repo}/issues/${parts.number}/comments`,
+        "-f",
+        `body=${comment}`,
+      ]);
+      if (!said.ok) return { ok: false, stderr: said.stderr };
+      return gh([
+        "api",
+        "--method",
+        "PATCH",
+        `repos/${parts.owner}/${parts.repo}/pulls/${parts.number}`,
+        "-f",
+        "state=closed",
+      ]);
+    },
+
     updatePr: async (prUrl, fields) => {
       const argv = ["pr", "edit", prUrl];
       if (fields.title !== undefined) argv.push("--title", fields.title);
@@ -682,15 +754,31 @@ export function githubVerbActions(
       if (!prepared.ok) return prepared;
       const mirror = prepared.path;
       if (execution.shape === "git-tag") {
-        const target = await readCommit(
-          mirror,
-          ["rev-parse", `refs/remotes/origin/${execution.repo.defaultBranch}^{commit}`],
-          `refreshed ${execution.repo.defaultBranch}`,
-        );
+        // A pinned commit (#695) is the whole point of the argument: the tag
+        // points where the caller says, so the branch moving afterwards — which
+        // is what reaching a quiet release window requires — cannot strand it.
+        // The moved-branch guards below exist to catch main shifting under an
+        // implicit "current main" target; for an explicit commit they would
+        // refuse exactly the case the pin was asked for, so they are skipped
+        // and the reachability check is the invariant instead.
+        const pinned =
+          execution.sha === undefined
+            ? undefined
+            : await pinnedReleaseCommit(mirror, execution.repo, execution.sha);
+        if (pinned !== undefined && !pinned.ok) return pinned;
+        const target =
+          pinned ??
+          (await readCommit(
+            mirror,
+            ["rev-parse", `refs/remotes/origin/${execution.repo.defaultBranch}^{commit}`],
+            `refreshed ${execution.repo.defaultBranch}`,
+          ));
         if (!target.ok) return target;
-        const liveBefore = await liveDefaultHead(mirror, execution.repo);
-        if (!liveBefore.ok) return liveBefore;
-        if (target.sha !== liveBefore.sha) return releaseTargetMoved(execution.repo, target.sha, liveBefore.sha);
+        if (pinned === undefined) {
+          const liveBefore = await liveDefaultHead(mirror, execution.repo);
+          if (!liveBefore.ok) return liveBefore;
+          if (target.sha !== liveBefore.sha) return releaseTargetMoved(execution.repo, target.sha, liveBefore.sha);
+        }
 
         const versionReady = await releaseVersionRefusal(mirror, execution.repo, target.sha, tag);
         if (!versionReady.ok) return versionReady;
@@ -736,7 +824,12 @@ export function githubVerbActions(
         ]);
         if (!tagged.result.ok) return failed(tagged.result, tagged.argv);
 
-        const liveAfter = await liveDefaultHead(mirror, execution.repo);
+        // Only meaningful for an implicit target: a pinned tag is *expected* to
+        // sit behind a branch that has moved on.
+        const liveAfter =
+          pinned === undefined
+            ? await liveDefaultHead(mirror, execution.repo)
+            : ({ ok: true, sha: target.sha } as const);
         if (!liveAfter.ok || liveAfter.sha !== target.sha) {
           const rollback = previousSha !== undefined
             ? await git(mirror, [
@@ -774,6 +867,27 @@ export function githubVerbActions(
       const target = await readCommit(mirror, ["rev-parse", `refs/tags/${tag}^{commit}`], `tag ${tag}`);
       if (!target.ok) return target;
       let tagSha = target.sha;
+      // A pinned push publishes the tag EXACTLY as it was cut (#695). Without
+      // this the retarget-to-live-main path below would quietly move a pinned
+      // tag onto whatever merged since — which is the same stranding, inverted:
+      // the caller would get a published tag pointing somewhere it never asked
+      // for. The pin is re-proven against the branch and against the local tag,
+      // so a mismatch is a refusal rather than a silent move.
+      const pinnedPush =
+        execution.sha === undefined
+          ? undefined
+          : await pinnedReleaseCommit(mirror, execution.repo, execution.sha);
+      if (pinnedPush !== undefined) {
+        if (!pinnedPush.ok) return pinnedPush;
+        if (pinnedPush.sha !== tagSha) {
+          return {
+            ok: false,
+            stderr:
+              `refusing release: ${tag} is at ${tagSha} locally, and you asked to publish it at ` +
+              `${pinnedPush.sha}. A published tag is never force-moved; cut the tag you mean to push.`,
+          };
+        }
+      }
       const live = await liveDefaultHead(mirror, execution.repo);
       if (!live.ok) return live;
 
@@ -795,7 +909,7 @@ export function githubVerbActions(
       if (!versionReady.ok) return versionReady;
 
       let oldSha: string | undefined;
-      if (tagSha !== live.sha) {
+      if (pinnedPush === undefined && tagSha !== live.sha) {
         const fresh = await readCommit(
           mirror,
           ["rev-parse", `refs/remotes/origin/${execution.repo.defaultBranch}^{commit}`],

package/src/verbs/protocol.ts

@@ -286,6 +286,14 @@ export const VERB_SPECS: Readonly<Record<VerbName, VerbSpec>> = {
         required: false,
         description: "Tag to prepare or cut, for version-bump-pr, git-tag, and github-release.",
       },
+      sha: {
+        type: "string",
+        required: false,
+        description:
+          "Pin the tag to this exact commit instead of whatever the released repo's default branch " +
+          "is at cut time (#695), for git-tag and git-push-tags. The commit must be reachable from " +
+          "that branch, or the release is refused naming it. Omit it and the behaviour is unchanged.",
+      },
       artefact: {
         type: "string",
         required: false,
@@ -371,6 +379,47 @@ export const VERB_SPECS: Readonly<Record<VerbName, VerbSpec>> = {
     roleRefusalText: (role) =>
       `review authority is the orchestrator's; this is a ${role} session, and a worker never returns its own PR for revision.`,
   },
+  conductor_pr_review_clear: {
+    name: "conductor_pr_review_clear",
+    mutating: true,
+    allowedRoles: ["orchestrator"],
+    description:
+      "Record that the durable review findings standing at one exact head are settled, so " +
+      "`conductor_pr_merge` stops refusing that head with merge-blocked-by-review (#913). This is the " +
+      "only clearance reachable at an UNCHANGED head: a re-review at the same head opens or appends to " +
+      "another blocking round rather than superseding one, and nothing settles a round from outside a " +
+      "worker. The clearance applies strictly backwards — it suppresses the evidence recorded up to the " +
+      "moment it is taken, never a finding recorded afterwards — and to that one head only. It bypasses " +
+      "nothing else: authority, pause, base-red-freeze, exact-head, green checks, release composition and " +
+      "single-flight all still apply to the merge. Refused for a PR no run of this project owns, a head " +
+      "that is not the live head, and a head where nothing is blocking.",
+    args: {
+      prUrl: {
+        type: "string",
+        required: true,
+        description:
+          "Full pull request URL — one a run of this project recorded, in a routed repository.",
+      },
+      headSha: {
+        type: "string",
+        required: true,
+        description:
+          "The exact head being cleared. Must equal the live head; checks are not re-read here " +
+          "(the merge gate re-checks green itself).",
+      },
+      reason: {
+        type: "string",
+        required: true,
+        description:
+          "Why this evidence is settled, in your own words. Non-empty, recorded verbatim in the " +
+          "ledger and the digest — this is the audit trail for a merge that a review round refused.",
+      },
+      rationale: RATIONALE_ARG,
+    },
+    roleRefusalText: (role) =>
+      `clearing review findings is the orchestrator's disposition; this is a ${role} session, ` +
+      "and a worker never clears the findings standing against its own pull request.",
+  },
   conductor_pr_recover: {
     name: "conductor_pr_recover",
     mutating: true,
@@ -570,13 +619,32 @@ export function parseVerbRequest(raw: unknown): VerbParse {
     if (arg.oneOf !== undefined && !arg.oneOf.some((allowed) => allowed === value)) {
       // `reason` is the field #129 closed on purpose, so it gets its own
       // refusal code: an out-of-enum reason is vocabulary drift, not a typo.
+      const reasonDrift = key === "reason";
+      // Measured on this fleet 2026-08-23: this is the largest single refusal
+      // cause in the ledger — 99 of 241, across the four verbs whose `reason`
+      // is a closed set, still firing. Every one of the 99 carried a real
+      // explanation ("landed directly in PR #940; queue label would re-dispatch
+      // finished work"), which is exactly the audit content the ledger exists
+      // to hold, and 7578 characters of it were discarded. None of the 99
+      // supplied `rationale` — the field built for it — because the moment a
+      // caller has a sentence to record is the moment they are told only that
+      // `reason` is closed (#968).
+      //
+      // Keyed on the spec rather than a hardcoded verb list: a verb with an
+      // enum `reason` and no `rationale` must not be told to use a field it
+      // would then refuse as `unknown-argument`, turning one wasted round trip
+      // into two.
+      const carriesRationale = reasonDrift && spec.args["rationale"] !== undefined;
       return {
         ok: false,
         verb,
-        refusal: key === "reason" ? "reason-not-in-enum" : "malformed-argument",
+        refusal: reasonDrift ? "reason-not-in-enum" : "malformed-argument",
         detail:
           `refused: ${verb} argument "${key}" must be one of ${arg.oneOf.join(", ")}, ` +
-          `got ${JSON.stringify(value)}.`,
+          `got ${JSON.stringify(value)}.` +
+          (carriesRationale
+            ? ' Pick the enum value that fits and put that sentence in "rationale", which is logged verbatim.'
+            : ""),
       };
     }
   }