@dev-loops/core 1.0.4-pre.0 → 1.0.4-pre.2

package/src/github/copilot-helpers.mjs

@@ -264,7 +264,7 @@ export function sanitizeCopilotSummonTokens(text) {
 // line) from `text`, leaving only bare-text markdown to scan. Unlike
 // transformNonFencedLines, fenced content here must be REMOVED, not kept:
 // leaving it would let bare text inside a fence still match the summon scan.
-function stripMarkdownCodeForScan(text) {
+export function stripMarkdownCodeForScan(text) {
   const lines = String(text).split(/\r?\n/);
   let inFencedBlock = false;
   let fencedDelimiter = "";
@@ -310,7 +310,8 @@ export function normalizeTimestamp(value) {
 export function extractReviewCommitSha(review) {
   const graphqlSha = typeof review?.commit?.oid === "string" ? review.commit.oid.trim() : "";
   const restSha = typeof review?.commit_id === "string" ? review.commit_id.trim() : "";
-  const sha = graphqlSha || restSha;
+  const camelCaseSha = typeof review?.commitId === "string" ? review.commitId.trim() : "";
+  const sha = graphqlSha || restSha || camelCaseSha;
   return sha.length > 0 ? sha : null;
 }
 
@@ -768,6 +769,11 @@ export function summarizeCopilotReviews(reviews, { headSha, draftGateResetAtMs }
   let hasSubmittedReviewOnCurrentHead = false;
   let latestSubmittedReviewOnCurrentHeadAt = null;
   let hasBodyFindingOnCurrentHead = false;
+  // The id of the review whose body set hasBodyFindingOnCurrentHead: the
+  // review a copilot-body-disposition record must name to clear the finding.
+  // Updated on every branch that updates hasBodyFindingOnCurrentHead so the two
+  // never drift.
+  let bodyFindingReviewId = null;
   let completedCopilotReviewRounds = 0;
 
   for (const review of effectiveReviews) {
@@ -793,21 +799,28 @@ export function summarizeCopilotReviews(reviews, { headSha, draftGateResetAtMs }
       const submittedAt = typeof review?.submittedAt === "string"
         ? review.submittedAt
         : (typeof review?.submitted_at === "string" ? review.submitted_at : null);
+      const reviewId = review?.id !== null && review?.id !== undefined ? String(review.id) : null;
       if (submittedAt !== null && (latestSubmittedReviewOnCurrentHeadAt === null || submittedAt > latestSubmittedReviewOnCurrentHeadAt)) {
         latestSubmittedReviewOnCurrentHeadAt = submittedAt;
         hasBodyFindingOnCurrentHead = copilotReviewBodySignalsChanges(state, review?.body);
-      } else if (submittedAt !== null && submittedAt === latestSubmittedReviewOnCurrentHeadAt) {
-        // Equal-timestamp tie on the same head: fail toward surfacing so array
-        // order never silently drops a finding when two reviews share a timestamp.
-        hasBodyFindingOnCurrentHead = hasBodyFindingOnCurrentHead || copilotReviewBodySignalsChanges(state, review?.body);
-      } else if (submittedAt === null && latestSubmittedReviewOnCurrentHeadAt === null) {
-        hasBodyFindingOnCurrentHead = hasBodyFindingOnCurrentHead || copilotReviewBodySignalsChanges(state, review?.body);
+        bodyFindingReviewId = hasBodyFindingOnCurrentHead ? reviewId : null;
+      } else if (submittedAt === latestSubmittedReviewOnCurrentHeadAt) {
+        // Equal-timestamp (or both-null) tie on the same head: fail toward
+        // surfacing so array order never silently drops a finding. When two
+        // tied reviews both signal, no single review owns the finding, so
+        // bodyFindingReviewId is null and no disposition record can clear it.
+        const tieSignals = copilotReviewBodySignalsChanges(state, review?.body);
+        if (tieSignals) {
+          bodyFindingReviewId = hasBodyFindingOnCurrentHead ? null : reviewId;
+        }
+        hasBodyFindingOnCurrentHead = hasBodyFindingOnCurrentHead || tieSignals;
       }
     }
   }
 
   return {
     copilotReviews,
+    effectiveCopilotReviews: effectiveReviews,
     copilotReviewIds: copilotReviews
       .map((review) => review?.id)
       .filter((id) => id !== null && id !== undefined)
@@ -818,5 +831,6 @@ export function summarizeCopilotReviews(reviews, { headSha, draftGateResetAtMs }
     hasSubmittedReviewOnCurrentHead,
     latestSubmittedReviewOnCurrentHeadAt,
     hasBodyFindingOnCurrentHead,
+    bodyFindingReviewId,
   };
 }

package/src/github/gh.mjs

@@ -67,7 +67,8 @@ export async function ghJson(args, { env, ghCommand = "gh", runChild = defaultRu
  * @param {typeof defaultRunChild} [runChild] - injectable child-exec seam.
  * @param {object} [opts]
  * @param {boolean} [opts.allowErrors] - when true, a GraphQL `errors` array
- *   in the response is returned instead of thrown.
+ *   in the response is returned instead of thrown. This includes a non-zero
+ *   `gh` exit whose stdout is JSON with an `errors` array.
  */
 export async function ghGraphql(query, vars, env, runChild = defaultRunChild, { allowErrors = false } = {}) {
   const fieldArgs = [];
@@ -80,6 +81,18 @@ export async function ghGraphql(query, vars, env, runChild = defaultRunChild, {
     env,
   );
   if (result.code !== 0) {
+    // `gh api graphql` exits non-zero when the response carries GraphQL
+    // `errors` (e.g. NOT_FOUND) but still prints the JSON on stdout. With
+    // allowErrors the caller wants that errors array, so return it.
+    if (allowErrors) {
+      let errorPayload = null;
+      try {
+        errorPayload = JSON.parse(result.stdout);
+      } catch {
+        // not JSON: fall through to GH_API_ERROR
+      }
+      if (Array.isArray(errorPayload?.errors)) return errorPayload;
+    }
     const detail = result.stderr.trim() || `exit code ${result.code}`;
     throw Object.assign(new Error(`gh api graphql failed: ${detail}`), { code: "GH_API_ERROR" });
   }

package/src/github/review-threads.mjs

@@ -121,6 +121,11 @@ export function parseReviewThreads(payload) {
   const threads = rawThreads.map((thread, threadIndex) => {
     const threadId = normalizeId(thread?.id ?? thread?.databaseId, `thread-${threadIndex + 1}`);
     const isResolved = Boolean(thread?.isResolved);
+    // The review that opened the thread: the root (first) comment's
+    // pullRequestReview id. null when the payload does not carry it, so a
+    // consumer that needs attribution treats the thread as unattributed.
+    const rootReviewId = extractRawComments(thread)[0]?.pullRequestReview?.id;
+    const reviewId = typeof rootReviewId === "string" && rootReviewId.length > 0 ? rootReviewId : null;
     const normalizedComments = extractRawComments(thread)
       .map((comment, commentIndex) => normalizeComment(comment, threadId, commentIndex, { isResolved }))
       .sort((left, right) => compareIds(left.id, right.id));
@@ -141,6 +146,7 @@ export function parseReviewThreads(payload) {
     return {
       id: threadId,
       isResolved,
+      reviewId,
       isActionable: actionableCommentIds.length > 0,
       commentIds,
       commentDatabaseIds,

package/src/loop/copilot-loop-state.mjs

@@ -198,6 +198,7 @@ export function buildSnapshotFromPrFacts({
   failureDetails = [],
   excludedFailureDetails,
   copilotBodyFeedbackUnresolved = false,
+  copilotPriorHeadBodyFeedbackUnresolved = false,
 }) {
   const prState = typeof prData?.state === "string" ? prData.state.toUpperCase() : "OPEN";
   const prMerged = prState === "MERGED";
@@ -228,6 +229,7 @@ export function buildSnapshotFromPrFacts({
     failureDetails,
     excludedFailureDetails: excludedFailureDetails ?? rollupDerivation.excludedFailureDetails,
     copilotBodyFeedbackUnresolved,
+    copilotPriorHeadBodyFeedbackUnresolved,
   });
 }
 
@@ -298,6 +300,10 @@ export function normalizeSnapshot(raw) {
     failureDetails: Array.isArray(raw.failureDetails) ? raw.failureDetails : [],
     excludedFailureDetails: Array.isArray(raw.excludedFailureDetails) ? raw.excludedFailureDetails : [],
     copilotBodyFeedbackUnresolved: Boolean(raw.copilotBodyFeedbackUnresolved),
+    // A body-only changes-recommended/unrecognized latest Copilot review on an
+    // earlier head with no trusted disposition record. Consumed only at the
+    // round cap, where no fresh Copilot review can supersede it.
+    copilotPriorHeadBodyFeedbackUnresolved: Boolean(raw.copilotPriorHeadBodyFeedbackUnresolved),
   };
 }
 
@@ -357,7 +363,8 @@ export function applyConfirmedReviewRequest(snapshot, reviewRequestStatus) {
  *   nextAction: string,
  *   autoRerequestEligible: boolean,
  *   sameHeadCleanConverged: boolean,
- *   roundCapCleanEligible: boolean
+ *   roundCapCleanEligible: boolean,
+ *   roundCapReopenEligible: boolean
  * }}
  */
 export function interpretLoopState(snapshot, refinementConfig) {
@@ -402,12 +409,18 @@ export function interpretLoopState(snapshot, refinementConfig) {
   const maxRounds = refinementConfig?.maxCopilotRounds;
   const reviewInFlight = s.copilotReviewRequestStatus === "requested"
     || s.copilotReviewRequestStatus === "already-requested";
+  // Clean at the cap except for an earlier-head body-only finding. That finding
+  // blocks the clean fallback, but a significant post-convergence change still
+  // opens a new Copilot cycle, whose review supersedes it.
+  let roundCapBlockedOnlyByPriorHeadBody = false;
   if (isCopilotRoundCapReached({ copilotReviewRoundCount: s.copilotReviewRoundCount, maxCopilotRounds: maxRounds })
       && state !== STATE.NO_PR && state !== STATE.DONE
       && state !== STATE.PR_DRAFT && state !== STATE.REVIEW_REQUEST_UNAVAILABLE
       && state !== STATE.BLOCKED_NEEDS_USER_DECISION) {
     const ciClean = s.ciStatus === "success" || s.ciStatus === "crediblyGreen" || !preApprovalRequireCi;
-    const cleanThreads = s.unresolvedThreadCount === 0 && !s.copilotBodyFeedbackUnresolved;
+    const cleanCurrentHead = s.unresolvedThreadCount === 0 && !s.copilotBodyFeedbackUnresolved;
+    const cleanThreads = cleanCurrentHead && !s.copilotPriorHeadBodyFeedbackUnresolved;
+    roundCapBlockedOnlyByPriorHeadBody = cleanCurrentHead && ciClean && !cleanThreads && !reviewInFlight;
     if (cleanThreads && ciClean) {
       state = STATE.ROUND_CAP_CLEAN_FALLBACK;
     } else if (!reviewInFlight) {
@@ -432,8 +445,12 @@ export function interpretLoopState(snapshot, refinementConfig) {
       // A current-head Copilot request is still active/pending and must settle before gate progression.
       state = STATE.WAITING_FOR_COPILOT_REVIEW;
     } else if (s.copilotReviewPresent) {
-      // Copilot has reviewed at least once; all threads resolved
-      if (ciBlocks) {
+      // Copilot has reviewed at least once; all threads resolved. A later
+      // body-only finding on an earlier commit outranks a clean current-head
+      // review, and merge refuses on it. A re-request would stop at the
+      // same-head clean suppression, so only a copilot-body-disposition record
+      // naming that review clears it.
+      if (ciBlocks || (s.copilotReviewOnCurrentHead && s.copilotPriorHeadBodyFeedbackUnresolved)) {
         state = STATE.BLOCKED_NEEDS_USER_DECISION;
       } else if (ciWaits) {
         state = STATE.WAITING_FOR_CI;
@@ -483,6 +500,9 @@ export function interpretLoopState(snapshot, refinementConfig) {
   }
 
   const roundCapCleanEligible = state === STATE.ROUND_CAP_CLEAN_FALLBACK;
+  // Cap states where a significant post-convergence change reopens a Copilot cycle.
+  const roundCapReopenEligible = roundCapCleanEligible
+    || (state === STATE.ROUND_CAP_REACHED && roundCapBlockedOnlyByPriorHeadBody);
 
   return {
     state,
@@ -491,6 +511,26 @@ export function interpretLoopState(snapshot, refinementConfig) {
     autoRerequestEligible,
     sameHeadCleanConverged,
     roundCapCleanEligible,
+    roundCapReopenEligible,
+  };
+}
+
+/**
+ * Reopen a Copilot cycle at the round cap after a significant post-convergence
+ * change landed on a newer head (see `roundCapReopenEligible`).
+ *
+ * @param {object} interpretation - interpretLoopState() output
+ * @returns {object} the interpretation routed to READY_TO_REREQUEST_REVIEW
+ */
+export function reopenRoundCapCycle(interpretation) {
+  return {
+    ...interpretation,
+    state: STATE.READY_TO_REREQUEST_REVIEW,
+    nextAction: NEXT_ACTIONS[STATE.READY_TO_REREQUEST_REVIEW],
+    allowedTransitions: [...TRANSITIONS[STATE.READY_TO_REREQUEST_REVIEW]],
+    autoRerequestEligible: true,
+    roundCapCleanEligible: false,
+    roundCapReopenEligible: false,
   };
 }
 

package/src/loop/finding-cluster.mjs

@@ -257,13 +257,13 @@ export function dedupeActListByCluster(actFindings, clusters, allFindings) {
 }
 
 /**
- * A "clean" verdict means no finding at a BLOCKING severity remains open. It is
- * invalid only when a finding at a blocking severity was acted on — that is
- * unresolved blocking work, so the round cannot be clean. Acting on a
- * NON-BLOCKING finding (a medium in the fix window, a low the fixer triages) is
- * expected under a clean verdict per `GATE-EXEC-BLOCKING-ONLY-FIX`: the fix
- * cycle covers non-blocking findings even though they never block clean, so a
- * clean verdict routinely carries non-blocking act findings.
+ * A "clean" ledger severity verdict means no finding at a BLOCKING severity
+ * remains open. It is invalid only when a finding at a blocking severity was
+ * acted on — that is unresolved blocking work, so the round cannot be clean.
+ * The ledger's severity verdict may stay clean with NON-BLOCKING act findings
+ * (a medium in the fix window, a low the fixer triages). The posted review
+ * verdict is composed with the act list (ADR 0089), so such a round posts
+ * findings_present until its act items are fixed.
  *
  * Throws a clear Error on `overallVerdict === "clean"` with any act finding at a
  * blocking severity; returns `overallVerdict` unchanged otherwise.
@@ -288,8 +288,8 @@ export function assertCleanImpliesNoBlockingAct(overallVerdict, actFindings, blo
     const severities = [...new Set(offending.map((f) => normalizeSeverity(f?.severity)))].join(", ");
     throw new Error(
       `clean verdict is invalid with ${offending.length} acted finding(s) at a blocking severity (${severities}): ` +
-        `a blocking-severity finding acted on this round cannot be clean. Non-blocking act findings are allowed under ` +
-        `a clean verdict (GATE-EXEC-BLOCKING-ONLY-FIX).`,
+        `a blocking-severity finding acted on this round cannot be clean. The ledger's severity verdict may be clean with ` +
+        `non-blocking act findings; the posted review verdict is composed with the act list (ADR 0089).`,
     );
   }
   return overallVerdict;

package/src/loop/gate-fanin.mjs

@@ -1046,6 +1046,27 @@ export function applyJudgeDispositions(findings, judgeVerdict) {
   return { findings: enriched, scopeDrift: validated.scopeDrift };
 }
 
+/**
+ * The judge's act list: the findings this PR must still fix. Pure.
+ * @param {unknown} findings
+ * @returns {Array<object>}
+ */
+export function listOpenActItems(findings) {
+  return (Array.isArray(findings) ? findings : []).filter((f) => f && f.judgeDisposition === "act");
+}
+
+/**
+ * Compose a round's review verdict with the judge act list (ADR 0089): a
+ * non-empty act list keeps a `clean` severity verdict from `clean`. Never
+ * lowers a verdict; the blockCleanOnFindingSeverities floor already applied.
+ * @param {"clean"|"findings_present"|"blocked"} overallVerdict
+ * @param {unknown} findings
+ * @returns {"clean"|"findings_present"|"blocked"}
+ */
+export function composeReviewVerdict(overallVerdict, findings) {
+  return overallVerdict === "clean" && listOpenActItems(findings).length > 0 ? "findings_present" : overallVerdict;
+}
+
 /**
  * Map consolidated findings into the `--findings` JSON shape consumed by
  * scripts/github/write-gate-findings-log.mjs (severity, angle, summary,

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 };
 }
 
 /**