@dev-loops/core 1.0.3 → 1.0.4-pre.1

package/src/loop/main-checkout-ff.mjs

@@ -1,5 +1,5 @@
 /**
- * Main-checkout fast-forward command shape (#1596).
+ * Main-checkout fast-forward flow.
  *
  * The dev-loop merges remotely (`gh pr merge` → origin/main) but neither the merge
  * procedure nor the post-merge hooks fast-forwarded the main checkout's local
@@ -8,7 +8,7 @@
  * code — re-introducing the CI-wait stall every PR (e.g. #1531's fix was invisible
  * until the main checkout caught up).
  *
- * This module owns the shared, dependency-free command string both harness hooks
+ * This module owns the shared, dependency-free step-wise flow both harness hooks
  * (Pi `post-merge-update`, Claude `post-tool-use-merge`) run after a successful
  * merge. It is best-effort and NON-BLOCKING: `--ff-only` refuses a diverged `main`
  * without rewriting history, so a diverged checkout fails the merge step cleanly and
@@ -16,10 +16,11 @@
  * push). `mainCheckout` is POSIX single-quoted so consumer checkout paths containing
  * spaces or shell metacharacters cannot break or inject into the shell string.
  *
- * The `merge --ff-only` is guarded to only run when the main checkout is currently on
- * `main`, so a non-`main` checkout (detached HEAD, or another branch checked out)
- * warns-and-continues instead of fast-forwarding the wrong branch. No `git switch` is
- * performed (a state change) — only the guard test runs.
+ * `syncMainCheckout` inspects the current ref BEFORE submitting any merge command, so
+ * a non-`main` checkout (detached HEAD, or another branch checked out) is classified
+ * and reported as an action-required diagnostic instead of fast-forwarding the wrong
+ * branch. No `git switch`/`checkout`/`reset` command is ever submitted for a non-main
+ * checkout — only read-only inspection commands run.
  *
  * No imports so this file vendors into the `.claude/hooks/` bundle unchanged
  * (vendored modules may only import `node:` builtins or relative paths).
@@ -27,15 +28,18 @@
 import path from "node:path";
 
 /**
- * Timeout (ms) for the `git worktree list` resolution step (the fetch-half budget;
- * a separate fetch timeout isn't applied — the fetch runs inline within the merge
- * command under `MAIN_CHECKOUT_FF_MERGE_TIMEOUT_MS`).
+ * Timeout (ms) for the `git worktree list` resolution step (the harness hook's own
+ * budget; `syncMainCheckout`'s step-wise `fetch`/`rev-parse`/`merge` commands each
+ * run under `MAIN_CHECKOUT_FF_MERGE_TIMEOUT_MS` instead).
  */
 export const MAIN_CHECKOUT_FF_FETCH_TIMEOUT_MS = 60_000;
 
-/** Timeout (ms) for the `git merge --ff-only origin/main` half. */
+/** Timeout (ms) for each step of `syncMainCheckout`'s fetch/rev-parse/merge flow. */
 export const MAIN_CHECKOUT_FF_MERGE_TIMEOUT_MS = 60_000;
 
+/** Stable diagnostic kind for a main checkout proven not to be on `main`. */
+export const MAIN_CHECKOUT_NOT_ON_MAIN_KIND = "main_checkout_not_on_main";
+
 /**
  * POSIX single-quote a path so spaces/shell metacharacters in a consumer's checkout
  * path cannot break or inject into the shell string.
@@ -45,17 +49,165 @@ function shellQuotePath(value) {
 }
 
 /**
- * Build the best-effort main-checkout fast-forward command string.
+ * Classify a main checkout's current full symbolic ref (`git rev-parse
+ * --symbolic-full-name HEAD` output) into one of the four states `syncMainCheckout`
+ * acts on. `--symbolic-full-name` (unlike `--abbrev-ref`) is never subject to
+ * `core.warnAmbiguousRefs` renaming a branch to `heads/<name>` when a tag or other ref
+ * shares its short name.
+ *
+ * @param {unknown} symbolicFullName - Raw (already-trimmed or not) `--symbolic-full-name
+ *   HEAD` output.
+ * @returns {"main" | "other_branch" | "detached" | "unreadable"}
+ */
+export function classifyMainCheckoutRef(symbolicFullName) {
+  if (typeof symbolicFullName !== "string") {
+    return "unreadable";
+  }
+  const trimmed = symbolicFullName.trim();
+  if (!trimmed) {
+    return "unreadable";
+  }
+  if (trimmed === "HEAD") {
+    return "detached";
+  }
+  if (trimmed === "refs/heads/main") {
+    return "main";
+  }
+  if (trimmed.startsWith("refs/heads/")) {
+    return "other_branch";
+  }
+  return "unreadable";
+}
+
+/**
+ * Build the `main_checkout_not_on_main` diagnostic, or `null` when any required field
+ * is missing or invalid. The one shared rendered `message` names the kind, the
+ * absolute checkout path, the current ref, the behind count, that no fast-forward
+ * happened, that the action is non-fatal, and the manual recovery — never a
+ * reset/force suggestion.
+ *
+ * @param {{ mainCheckout: unknown, ref: unknown, behindCount: unknown }} fields
+ * @returns {{ kind: string, severity: "error", mainCheckout: string, ref: string, behindCount: number, message: string } | null}
+ */
+export function buildMainCheckoutNotOnMainDiagnostic({ mainCheckout, ref, behindCount } = {}) {
+  if (typeof mainCheckout !== "string" || !path.isAbsolute(mainCheckout)) {
+    return null;
+  }
+  if (typeof ref !== "string" || !ref.trim()) {
+    return null;
+  }
+  if (!Number.isInteger(behindCount) || behindCount < 0) {
+    return null;
+  }
+  const message =
+    `[dev-loops] post-merge: ${MAIN_CHECKOUT_NOT_ON_MAIN_KIND} — the main checkout at '${mainCheckout}' ` +
+    `is on ${ref}, ${behindCount} commit(s) behind origin/main after fetch. No fast-forward was performed; ` +
+    `this is non-fatal. Reconcile manually: preserve any local-only commits, then check out main and ` +
+    `fast-forward it to origin/main.`;
+  return { kind: MAIN_CHECKOUT_NOT_ON_MAIN_KIND, severity: "error", mainCheckout, ref, behindCount, message };
+}
+
+/**
+ * Run one shell-command step through the harness-supplied `run` adapter, normalizing
+ * a thrown/rejected `run` into the same `{ ok: false, reason }` shape as an adapter
+ * that resolves a failure — callers never need a second failure path.
+ *
+ * @param {(command: string) => Promise<{ ok: boolean, stdout?: string, reason?: string }>} run
+ * @param {string} command
+ * @returns {Promise<{ ok: true, stdout: string } | { ok: false, reason: string }>}
+ */
+async function runStep(run, command) {
+  try {
+    const result = await run(command);
+    if (result?.ok) {
+      return { ok: true, stdout: typeof result.stdout === "string" ? result.stdout : "" };
+    }
+    return { ok: false, reason: result?.reason || "command failed" };
+  } catch (error) {
+    return { ok: false, reason: error?.message || String(error) };
+  }
+}
+
+/**
+ * Best-effort, step-wise main-checkout sync.
+ *
+ * After a successful `fetch origin main`, inspects the checkout's current ref BEFORE
+ * submitting any merge command:
+ *   - `main` → `git merge --ff-only origin/main`; ok → `fast_forwarded`; a diverged
+ *     main fails the merge step cleanly → `skipped`.
+ *   - detached HEAD or another named branch → never merged/switched/reset; instead
+ *     the post-fetch `HEAD..origin/main` behind count is measured and reported as a
+ *     `not_on_main` diagnostic (see `buildMainCheckoutNotOnMainDiagnostic`).
+ * Any step that cannot prove its outcome (fetch failure, unreadable ref, a failed or
+ * empty short-SHA resolution, a failed or non-numeric behind-count read) is reported
+ * as `skipped` instead of a partial diagnostic.
  *
  * @param {string} mainCheckout - Absolute path to the main (primary) git checkout.
- * @returns {string} `git -C '<main>' fetch origin main && [ "$(git -C '<main>' rev-parse --abbrev-ref HEAD)" = main ] && git -C '<main>' merge --ff-only origin/main` (path POSIX single-quoted; merge only runs when the main checkout is on `main`)
+ * @param {(command: string) => Promise<{ ok: boolean, stdout?: string, reason?: string }>} run
+ *   Harness adapter that executes one shell command and resolves its outcome (may also
+ *   throw — treated as a failed step).
+ * @returns {Promise<
+ *   | { status: "fast_forwarded" }
+ *   | { status: "skipped", reason: string }
+ *   | { status: "not_on_main", diagnostic: ReturnType<typeof buildMainCheckoutNotOnMainDiagnostic> }
+ * >}
  */
-export function buildMainCheckoutFastForwardCommand(mainCheckout) {
+export async function syncMainCheckout(mainCheckout, run) {
   const quoted = shellQuotePath(mainCheckout);
-  // ponytail: guard with a `[ ... = main ]` test instead of switching branches — a
-  // non-main checkout fails the && chain (warn-and-continue) rather than ff-ing the
-  // wrong branch. No state change, no git switch.
-  return `git -C ${quoted} fetch origin main && [ "$(git -C ${quoted} rev-parse --abbrev-ref HEAD)" = main ] && git -C ${quoted} merge --ff-only origin/main`;
+
+  const fetchResult = await runStep(run, `git -C ${quoted} fetch origin main`);
+  if (!fetchResult.ok) {
+    return { status: "skipped", reason: fetchResult.reason };
+  }
+
+  const refResult = await runStep(run, `git -C ${quoted} rev-parse --symbolic-full-name HEAD`);
+  if (!refResult.ok) {
+    return { status: "skipped", reason: refResult.reason };
+  }
+  const symbolicRef = refResult.stdout.trim();
+  const classification = classifyMainCheckoutRef(symbolicRef);
+  if (classification === "unreadable") {
+    return { status: "skipped", reason: `could not determine the current branch (got: ${JSON.stringify(symbolicRef)})` };
+  }
+
+  if (classification === "main") {
+    const mergeResult = await runStep(run, `git -C ${quoted} merge --ff-only origin/main`);
+    if (!mergeResult.ok) {
+      return { status: "skipped", reason: mergeResult.reason };
+    }
+    return { status: "fast_forwarded" };
+  }
+
+  let ref;
+  if (classification === "detached") {
+    const shortShaResult = await runStep(run, `git -C ${quoted} rev-parse --short HEAD`);
+    if (!shortShaResult.ok) {
+      return { status: "skipped", reason: shortShaResult.reason };
+    }
+    const shortSha = shortShaResult.stdout.trim();
+    if (!shortSha) {
+      return { status: "skipped", reason: "could not resolve a short SHA for the detached HEAD" };
+    }
+    ref = `detached@${shortSha}`;
+  } else {
+    ref = symbolicRef.slice("refs/heads/".length);
+  }
+
+  const behindResult = await runStep(run, `git -C ${quoted} rev-list --count HEAD..origin/main`);
+  if (!behindResult.ok) {
+    return { status: "skipped", reason: behindResult.reason };
+  }
+  const behindStdout = behindResult.stdout.trim();
+  if (!/^\d+$/.test(behindStdout)) {
+    return { status: "skipped", reason: `could not read the behind count (got: ${JSON.stringify(behindStdout)})` };
+  }
+  const behindCount = Number.parseInt(behindStdout, 10);
+
+  const diagnostic = buildMainCheckoutNotOnMainDiagnostic({ mainCheckout, ref, behindCount });
+  if (!diagnostic) {
+    return { status: "skipped", reason: "incomplete main_checkout_not_on_main diagnostic" };
+  }
+  return { status: "not_on_main", diagnostic };
 }
 
 /**

package/src/loop/merge-approval.mjs

@@ -11,13 +11,16 @@
  *
  * It reuses, never re-derives, the existing precondition set:
  * `resolveSizeBudgetHumanApprovalRequired` (size-budget-merge-gate),
- * `findBlockingTitleMarkers` (pr-title-markers), and the detect-checkpoint-evidence
+ * `findBlockingTitleMarkers` (pr-title-markers), the detect-checkpoint-evidence
  * `preMergeGateCheck` bundle (draft/pre-approval verdicts, threads, runner lock,
- * fan-out provenance). This module adds ONLY the human-approver identity, the
- * merge-class split, and the aggregate naming.
+ * fan-out provenance), and `classifyCopilotReviewBodyDisposition` (copilot-helpers,
+ * the same current-head Copilot disposition detection the loop's
+ * `copilotBodyFeedbackUnresolved` reads). This module adds ONLY the
+ * human-approver identity, the merge-class split, the Copilot-convergence
+ * precondition, and the aggregate naming.
  */
 
-import { isCopilotLogin } from "../github/copilot-helpers.mjs";
+import { isCopilotLogin, classifyCopilotReviewBodyDisposition, COPILOT_DISPOSITION, SUBMITTED_REVIEW_STATES, extractReviewCommitSha } from "../github/copilot-helpers.mjs";
 import { findBlockingTitleMarkers } from "./pr-title-markers.mjs";
 import { resolveSizeBudgetHumanApprovalRequired } from "./size-budget-merge-gate.mjs";
 import { deriveLoopCiStatusFromRollup } from "./copilot-ci-status.mjs";
@@ -81,6 +84,15 @@ function reviewCommit(entry) {
   return null;
 }
 
+// Copilot-only login extraction for evaluateCopilotConvergence: accepts the
+// `gh pr view` GraphQL shape (author.login) in addition to the REST shape
+// (user.login | login) reviewLogin reads. Scoped to the Copilot-convergence
+// eval so verifyFreshHumanApproval's human-approval matching is unchanged.
+function copilotConvergenceReviewLogin(entry) {
+  if (typeof entry?.author?.login === "string" && entry.author.login.length > 0) return entry.author.login;
+  return reviewLogin(entry);
+}
+
 /**
  * Verify a fresh, agent-unforgeable, head-pinned human approval by `approvedBy`.
  *
@@ -150,6 +162,147 @@ export function verifyFreshHumanApproval({ approvedBy, currentHeadSha, reviews =
   };
 }
 
+export const COPILOT_CONVERGENCE_STATE = Object.freeze({
+  CURRENT_HEAD_CLEAN: "current_head_clean",
+  CURRENT_HEAD_FINDINGS: "current_head_findings",
+  NO_CURRENT_HEAD_REVIEW: "no_current_head_review",
+});
+
+/** ADR 0012 end states that may satisfy convergence without a current-head review. */
+export const COPILOT_ABSENT_REVIEW_DISPOSITION = Object.freeze({
+  ROUND_CAP_CLEAN_FALLBACK: "round_cap_clean_fallback",
+  DOCS_ONLY_SUPPRESSION: "docs_only_suppression",
+  COPILOT_GATE_DISABLED: "copilot_gate_disabled",
+});
+const SANCTIONED_ABSENT_REVIEW_DISPOSITIONS = new Set(Object.values(COPILOT_ABSENT_REVIEW_DISPOSITION));
+
+/**
+ * Shared Copilot-convergence evaluation for pre-approval entry and merge.
+ * Both treat a thread-clean 🔵 as conductor-overridable; unresolved threads
+ * still block independently. Fail-closed.
+ *
+ * Only the LATEST Copilot review pinned to `currentHeadSha` is judged, so a
+ * stale non-approval at an earlier head never blocks and a later same-head 🟢
+ * clears an earlier same-head finding.
+ *
+ * Policy (operator-resolved during the v1.0.4 drain):
+ *   🟡 "Changes recommended" on the current head -> BLOCK (actionable; the review
+ *      body is unresolved feedback even with zero inline threads — the exact
+ *      body-only fail-open the loop detects and this precondition enforces at merge).
+ *   🔵 "Needs a closer look" -> conductor-OVERRIDABLE (soft), NOT blocked here.
+ *      Unresolved threads still gate it (detect-checkpoint-evidence refuses any
+ *      unresolved review thread), so a 🔵 merges only with zero unresolved
+ *      threads — the conductor's override is choosing to run the merge on a
+ *      thread-clean 🔵.
+ *   unrecognized disposition -> BLOCK (fail closed on a Copilot format change).
+ *   🟢 clean / headerless -> PASS.
+ *
+ * Three distinct states (`state` on the result):
+ *   current_head_clean     a current-head review passes (🟢 / headerless / 🔵);
+ *   current_head_findings  a current-head review blocks (🟡 / unrecognized);
+ *   no_current_head_review no current-head Copilot review exists (none yet, or
+ *                          every review is on an earlier head). This state
+ *                          passes ONLY through a sanctioned disposition recorded
+ *                          for the current head (`absentReviewDisposition`
+ *                          `{ kind, headSha }`, kind in
+ *                          COPILOT_ABSENT_REVIEW_DISPOSITION). Absence alone never
+ *                          converges, and a stale earlier-head review is never
+ *                          inherited as the current-head verdict.
+ *
+ * @returns {{ ok: boolean, state: string|null, disposition: string|null, reason: string|null }}
+ */
+export function evaluateCopilotConvergence({ currentHeadSha = null, reviews = [], absentReviewDisposition = null } = {}) {
+  const head = typeof currentHeadSha === "string" ? currentHeadSha.trim() : "";
+  // Head unknown: no current-head review can be pinned. Fail closed (matches
+  // verifyFreshHumanApproval), so this precondition can never pass without a
+  // known head to pin the Copilot disposition to.
+  if (head.length === 0) return { ok: false, state: null, disposition: null, reason: "current head SHA is unknown; cannot pin a Copilot review to it" };
+
+  // Mirror summarizeCopilotReviews' current-head finding selection BYTE-FOR-BYTE
+  // so the merge gate and the loop can never diverge (they already share
+  // classifyCopilotReviewBodyDisposition at the detection layer). Use the SAME
+  // comparison the loop uses — the RAW submittedAt string (a non-string is null),
+  // compared with `>`/`===`, NOT a parsed timestamp: parsing would diverge on a
+  // malformed/mixed-offset submittedAt (an invalid-timestamp 🟡 that the loop
+  // keeps as latest could otherwise be superseded here — a fail-open). Consider
+  // only SUBMITTED current-head reviews, skip PENDING drafts (a PENDING never
+  // sets the finding), pick the latest by submittedAt string, and on an
+  // equal-string tie (or both-null) fold toward the most-blocking disposition so
+  // array order never silently drops a finding.
+  let latestDisposition = null;
+  let latestAt = null;
+  for (const entry of Array.isArray(reviews) ? reviews : []) {
+    // Shape-tolerant Copilot-login + commit extraction: the merge gate feeds
+    // REST-shaped reviews (user.login/commit_id) while the gate-ENTRY detector
+    // feeds `gh pr view` GraphQL-shaped reviews (author.login/commit.oid). Both
+    // call sites route through this one evaluateCopilotConvergence, so it must
+    // recognize BOTH shapes to produce ONE convergence verdict. Only Copilot
+    // reviews matter here, so broadening the login read to author.login cannot
+    // affect verifyFreshHumanApproval (which keeps its own REST-only
+    // reviewLogin/reviewCommit).
+    const login = copilotConvergenceReviewLogin(entry);
+    if (login === null || !isCopilotLogin(login)) continue;
+    if (extractReviewCommitSha(entry) !== head) continue; // only current-head reviews
+    const state = typeof entry?.state === "string" ? entry.state.toUpperCase() : "";
+    if (state === "PENDING" || !SUBMITTED_REVIEW_STATES.has(state)) continue; // PENDING/unknown never sets the finding
+    const disposition = classifyCopilotReviewBodyDisposition(state, entry?.body);
+    const submittedAt = typeof entry?.submittedAt === "string"
+      ? entry.submittedAt
+      : (typeof entry?.submitted_at === "string" ? entry.submitted_at : null);
+    if (submittedAt !== null && (latestAt === null || submittedAt > latestAt)) {
+      latestDisposition = disposition; // a lexicographically-later submittedAt supersedes (matches summarize)
+      latestAt = submittedAt;
+    } else if (submittedAt !== null && submittedAt === latestAt) {
+      latestDisposition = latestDisposition === null ? disposition : moreBlockingDisposition(latestDisposition, disposition);
+    } else if (submittedAt === null && latestAt === null) {
+      latestDisposition = latestDisposition === null ? disposition : moreBlockingDisposition(latestDisposition, disposition);
+    }
+    // a null submittedAt once a non-null latest exists is ignored (mirrors summarize)
+  }
+  if (latestDisposition === null) {
+    const absent = COPILOT_CONVERGENCE_STATE.NO_CURRENT_HEAD_REVIEW;
+    const kind = absentReviewDisposition?.kind;
+    if (SANCTIONED_ABSENT_REVIEW_DISPOSITIONS.has(kind) && absentReviewDisposition?.headSha === head) {
+      return { ok: true, state: absent, disposition: kind, reason: null };
+    }
+    return {
+      ok: false,
+      state: absent,
+      disposition: null,
+      reason: `no current-head Copilot review exists on head ${head}; convergence requires a clean current-head review or a sanctioned disposition recorded for this head (${[...SANCTIONED_ABSENT_REVIEW_DISPOSITIONS].join(", ")})`,
+    };
+  }
+
+  const findings = COPILOT_CONVERGENCE_STATE.CURRENT_HEAD_FINDINGS;
+  if (latestDisposition === COPILOT_DISPOSITION.CHANGES_RECOMMENDED) {
+    return { ok: false, state: findings, disposition: latestDisposition, reason: `current-head Copilot review is "Changes recommended" (🟡, actionable non-approval); converge to "Approval recommended" (🟢) or resolve the feedback before merge` };
+  }
+  if (latestDisposition === COPILOT_DISPOSITION.UNRECOGNIZED) {
+    return { ok: false, state: findings, disposition: latestDisposition, reason: `current-head Copilot review carries an unrecognized disposition header (fail closed); a recognized "Approval recommended" (🟢) is required` };
+  }
+  // CLEAN, NONE, and NEEDS_CLOSER_LOOK (🔵, conductor-overridable) pass.
+  return { ok: true, state: COPILOT_CONVERGENCE_STATE.CURRENT_HEAD_CLEAN, disposition: latestDisposition, reason: null };
+}
+
+// Disposition blocking precedence, most-blocking first. Used to fold an
+// equal-timestamp same-head tie toward the most-blocking disposition so a tied
+// 🟡/unrecognized is never silently dropped by a co-timestamped 🟢/🔵.
+const COPILOT_DISPOSITION_BLOCKING_ORDER = [
+  COPILOT_DISPOSITION.CHANGES_RECOMMENDED,
+  COPILOT_DISPOSITION.UNRECOGNIZED,
+  COPILOT_DISPOSITION.NEEDS_CLOSER_LOOK,
+  COPILOT_DISPOSITION.CLEAN,
+  COPILOT_DISPOSITION.NONE,
+];
+function moreBlockingDisposition(a, b) {
+  const ia = COPILOT_DISPOSITION_BLOCKING_ORDER.indexOf(a);
+  const ib = COPILOT_DISPOSITION_BLOCKING_ORDER.indexOf(b);
+  // A value absent from the order (defensive) sorts last.
+  const ra = ia === -1 ? COPILOT_DISPOSITION_BLOCKING_ORDER.length : ia;
+  const rb = ib === -1 ? COPILOT_DISPOSITION_BLOCKING_ORDER.length : ib;
+  return ra <= rb ? a : b;
+}
+
 /**
  * Decide whether merge is authorized given the class, the standing
  * authorization signal, and any fresh per-merge approval.
@@ -227,6 +380,8 @@ export function evaluateMergePreconditions({
   comments = [],
   standingAuthorized = false,
   stableRelease = false,
+  copilotAbsentReviewDisposition = null,
+  copilotBodyDisposition = null,
 } = {}) {
   const failures = [];
 
@@ -273,11 +428,37 @@ export function evaluateMergePreconditions({
     failures.push({ precondition: "size_budget_human_approval", reason: "size-budget requires a human APPROVED review OR a head-pinned \"approve merge <headSha>\" operator comment, with zero unresolved CHANGES_REQUESTED, for this escalated/T1 PR" });
   }
 
+  // Copilot-convergence precondition: refuse a current-head Copilot non-approval
+  // body disposition, mirroring the loop's copilotBodyFeedbackUnresolved.
+  // A trusted copilot-body-disposition record resolved for the current head
+  // (`{ headSha, reviewId, ... }`) clears a current-head finding, as it does
+  // at gate entry.
+  const copilotConvergence = evaluateCopilotConvergence({ currentHeadSha, reviews, absentReviewDisposition: copilotAbsentReviewDisposition });
+  const head = typeof currentHeadSha === "string" ? currentHeadSha.trim().toLowerCase() : "";
+  const bodyCleared = copilotConvergence.state === COPILOT_CONVERGENCE_STATE.CURRENT_HEAD_FINDINGS
+    && head.length > 0
+    && typeof copilotBodyDisposition?.headSha === "string" && copilotBodyDisposition.headSha.toLowerCase() === head;
+  if (!copilotConvergence.ok && !bodyCleared) {
+    failures.push({ precondition: "copilot_convergence", reason: copilotConvergence.reason });
+  }
+
   const mergeClass = resolveMergeClass({ sizeOutcome, touchesT1, stableRelease });
   const decision = resolveMergeApprovalDecision({ mergeClass, standingAuthorized, freshApproval });
   if (!decision.authorized) {
     failures.push({ precondition: "merge_approval", reason: decision.reason });
   }
 
-  return { ok: failures.length === 0, failures, mergeClass, approvalVia: decision.authorized ? decision.via : null };
+  return {
+    ok: failures.length === 0,
+    failures,
+    mergeClass,
+    approvalVia: decision.authorized ? decision.via : null,
+    // Audit trace: which convergence state applied and what settled it (the
+    // current-head review disposition, or the sanctioned disposition kind when
+    // no current-head review exists), so a merge on a conductor-overridable 🔵
+    // or without a current-head review is recorded, never invisible.
+    copilotConvergenceState: copilotConvergence.state,
+    copilotDisposition: copilotConvergence.disposition,
+    copilotBodyDisposition: bodyCleared ? copilotBodyDisposition : null,
+  };
 }