agent-dealer 1.2.7 → 1.2.9

package/bundle/server/dist/coordinator/auto-merge.integration.test.js

@@ -17,6 +17,8 @@ const { startWorkflow, applyCompletion } = await import("./commands.js");
 const { ReviewerResult } = await import("./reviewer-result.js");
 const { setMergePrForTests, clearFinalizeInflightForTests } = await import("./auto-merge.js");
 const { managedRepoPath } = await import("../adapters/managed-repo.js");
+const { buildDeveloperPrompt } = await import("./prompts.js");
+const { defaultSyncGitExec, setConflictSyncGithubForTests, setConflictSyncGitExecForTests, } = await import("./merge-conflict-sync.js");
 /** Real local checkout so resolveAutoMergeCwd accepts the default legacy repo. */
 let fixtureRepo = "";
 function initFixtureRepo() {
@@ -48,10 +50,14 @@ beforeEach(() => {
   `);
     clearFinalizeInflightForTests();
     setMergePrForTests(async () => ({ ok: true }));
+    setConflictSyncGitExecForTests(null);
+    setConflictSyncGithubForTests(null);
 });
 afterEach(() => {
     setMergePrForTests(null);
     clearFinalizeInflightForTests();
+    setConflictSyncGitExecForTests(null);
+    setConflictSyncGithubForTests(null);
 });
 function newIssue(opts = {}) {
     return createIssue({
@@ -388,6 +394,276 @@ test("success txn dismisses stale needs_human policy_escalation from a racing fa
     const resolved = listHumanActionsForIssue(issueId).find((a) => a.actionType === "policy_escalation" && a.status === "resolved");
     assert.ok(resolved, "expected the racing escalation to be marked resolved");
 });
+/** NOT-310: origin + local clone where branch `issue-1` (commit B) is behind a moved
+ * base (commit C). With `conflict`, C edits the same line of shared.txt that B
+ * touched; otherwise C adds an unrelated file and merges cleanly. With
+ * `upToDate`, C lands before the branch is cut, so the branch already contains
+ * the base tip (a "not mergeable" failure there is a policy block, not
+ * staleness) — the conflict flag is then meaningless and must be false. */
+function initNot310Repos(opts) {
+    assert.equal(opts.upToDate === true && opts.conflict === true, false, "upToDate fixtures cannot also conflict");
+    const origin = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-not310-origin-"));
+    execFileSync("git", ["init", "-b", "main"], { cwd: origin });
+    execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: origin });
+    execFileSync("git", ["config", "user.name", "Test"], { cwd: origin });
+    fs.writeFileSync(path.join(origin, "base.txt"), "v1\n");
+    fs.writeFileSync(path.join(origin, "shared.txt"), "line1\nline2\n");
+    execFileSync("git", ["add", "."], { cwd: origin });
+    execFileSync("git", ["commit", "-m", "A base"], { cwd: origin });
+    const commitC = () => {
+        if (opts.conflict) {
+            fs.writeFileSync(path.join(origin, "shared.txt"), "line1\nbase change\n");
+        }
+        else {
+            fs.writeFileSync(path.join(origin, "other.txt"), "c\n");
+        }
+        execFileSync("git", ["add", "."], { cwd: origin });
+        execFileSync("git", ["commit", "-m", "C base moved"], { cwd: origin });
+    };
+    if (opts.upToDate)
+        commitC();
+    const local = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-not310-local-"));
+    fs.rmSync(local, { recursive: true, force: true });
+    execFileSync("git", ["clone", origin, local]);
+    execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: local });
+    execFileSync("git", ["config", "user.name", "Test"], { cwd: local });
+    execFileSync("git", ["checkout", "-b", "issue-1"], { cwd: local });
+    fs.writeFileSync(path.join(local, "shared.txt"), "line1\nfeature change\n");
+    execFileSync("git", ["add", "."], { cwd: local });
+    execFileSync("git", ["commit", "-m", "B feature"], { cwd: local });
+    execFileSync("git", ["push", "-u", "origin", "issue-1"], { cwd: local });
+    // Like a production managed clone, the main checkout rests on the base — the
+    // issue branch must not be checked out anywhere for the sync to proceed.
+    execFileSync("git", ["checkout", "-q", "main"], { cwd: local });
+    if (!opts.upToDate)
+        commitC();
+    const baseMovedSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd: origin, encoding: "utf8" }).trim();
+    return { origin, local, baseMovedSha };
+}
+function branchContains(repo, sha, branch) {
+    try {
+        execFileSync("git", ["merge-base", "--is-ancestor", sha, branch], { cwd: repo });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const NOT_MERGEABLE = "Pull request #42 is not mergeable: the merge commit cannot be cleanly created";
+test("NOT-310: cleanly-mergeable base syncs, pushes without force, polls checks, merges untouched", async () => {
+    const { origin, local, baseMovedSha } = initNot310Repos({ conflict: false });
+    const gitArgs = [];
+    setConflictSyncGitExecForTests(async (args, opts) => {
+        gitArgs.push(args);
+        return defaultSyncGitExec(args, opts);
+    });
+    let checksPolls = 0;
+    setConflictSyncGithubForTests({
+        checksSnapshot: async () => {
+            checksPolls += 1;
+            return "success";
+        },
+    });
+    const mergeCalls = [];
+    let merges = 0;
+    setMergePrForTests(async (opts) => {
+        mergeCalls.push(opts);
+        merges += 1;
+        return merges === 1 ? { ok: false, reason: NOT_MERGEABLE } : { ok: true };
+    });
+    const issueId = newIssue({ autoMerge: true, repo: local });
+    startWorkflow(issueId);
+    await complete(issueId, cleanHandoff);
+    await complete(issueId, { kind: "verdict", result: okReview("approved") });
+    assert.equal(merges, 2, "one failing merge plus one post-sync retry");
+    assert.deepEqual(mergeCalls, [
+        { cwd: local, number: 42 },
+        { cwd: local, number: 42 },
+    ]);
+    assert.equal(getIssue(issueId).status, "done");
+    assert.equal(getActiveWorkflowInstance(issueId), null);
+    assert.equal(listHumanActionsForIssue(issueId).filter((a) => a.status === "open").length, 0, "no human action when the sync resolves the staleness");
+    assert.ok(checksPolls >= 1, "expected the checks poll to run after the sync push");
+    // The sync merged the moved base and pushed it: origin's branch contains C.
+    assert.equal(branchContains(origin, baseMovedSha, "issue-1"), true);
+    // No force-push anywhere in the new path.
+    const pushes = gitArgs.filter((a) => a[0] === "push");
+    assert.ok(pushes.length >= 1, "expected at least one push");
+    for (const args of pushes) {
+        assert.ok(args.every((a) => !/^(-f|--force)/.test(a)), `push must never force: ${args.join(" ")}`);
+    }
+    assert.ok(gitArgs.some((a) => a.includes("merge") && a.includes("origin/main")), "expected a merge of the fetched base");
+    const root = path.join(local, ".agent-dealer-worktrees");
+    const leftovers = fs.existsSync(root) ? fs.readdirSync(root).filter((e) => e.startsWith("merge-sync-")) : [];
+    assert.deepEqual(leftovers, []);
+});
+test("NOT-310: retry_merge runs the same conflict sync (commands.ts retry path)", async () => {
+    const { resolveHumanActionAndAdvanceAsync } = await import("./commands.js");
+    const { cancelWorkItem } = await import("../repository/work-items.js");
+    const { createHumanAction } = await import("../repository/human-actions.js");
+    const { transitionIssue } = await import("../repository/issues.js");
+    const { origin, local, baseMovedSha } = initNot310Repos({ conflict: false });
+    setConflictSyncGithubForTests({ checksSnapshot: async () => "success" });
+    let merges = 0;
+    setMergePrForTests(async () => {
+        merges += 1;
+        return merges === 1 ? { ok: false, reason: NOT_MERGEABLE } : { ok: true };
+    });
+    const issueId = newIssue({ autoMerge: true, repo: local });
+    startWorkflow(issueId);
+    await complete(issueId, cleanHandoff);
+    // Park like a merge failure did: drop the pending reviewer round, go
+    // needs_human with a merge-failure action offering retry_merge.
+    for (const item of listWorkItemsForIssue(issueId)) {
+        if (item.status === "pending" || item.status === "leased")
+            cancelWorkItem(item.id);
+    }
+    transitionIssue(issueId, "needs_human", {
+        currentOwner: "human",
+        currentIntent: `Auto-merge failed: ${NOT_MERGEABLE}`,
+    });
+    const action = createHumanAction({
+        issueId,
+        workflowInstanceId: getActiveWorkflowInstance(issueId).id,
+        actionType: "policy_escalation",
+        reason: `Auto-merge failed: ${NOT_MERGEABLE}`,
+        question: `Auto-merge failed: ${NOT_MERGEABLE} Retry the merge, queue another repair round, or close the issue?`,
+        evidence: { mergeFailure: true },
+        responseOptions: [
+            { choice: "retry_merge", label: "Retry merge" },
+            { choice: "repair", label: "Another repair round" },
+            { choice: "close", label: "Close" },
+        ],
+    });
+    const resolved = await resolveHumanActionAndAdvanceAsync(action.id, "op", "retry_merge");
+    assert.equal(resolved.ok, true);
+    assert.equal(merges, 2, "retry_merge must sync + retry, not just re-run gh");
+    assert.equal(getIssue(issueId).status, "done");
+    assert.equal(listHumanActionsForIssue(issueId).filter((a) => a.status === "open").length, 0);
+    assert.equal(branchContains(origin, baseMovedSha, "issue-1"), true);
+});
+test("NOT-310: up-to-date branch that stays not mergeable escalates directly, no repair round", async () => {
+    const { local, baseMovedSha } = initNot310Repos({ conflict: false, upToDate: true });
+    setConflictSyncGithubForTests({ checksSnapshot: async () => "success" });
+    const policyReason = "Pull request #42 is not mergeable: base branch policy prohibits the merge";
+    let merges = 0;
+    setMergePrForTests(async () => {
+        merges += 1;
+        return { ok: false, reason: policyReason };
+    });
+    const issueId = newIssue({ autoMerge: true, repo: local });
+    startWorkflow(issueId);
+    await complete(issueId, cleanHandoff);
+    await complete(issueId, { kind: "verdict", result: okReview("approved") });
+    assert.equal(merges, 2, "failing merge plus one post-sync retry");
+    assert.equal(getIssue(issueId).status, "needs_human");
+    assert.equal(listWorkItemsForIssue(issueId).filter((i) => i.status === "pending").length, 0, "a policy block must not spend a conflict-repair round");
+    const open = listHumanActionsForIssue(issueId).filter((a) => a.status === "open");
+    assert.equal(open.length, 1);
+    assert.equal(open[0].actionType, "policy_escalation");
+    assert.match(open[0].reason, /base branch policy prohibits the merge/);
+    assert.match(open[0].reason, /already contains main .* — not a staleness conflict/);
+    const evidence = JSON.parse(open[0].evidenceJson);
+    assert.equal(evidence.mergeFailure, true);
+    assert.ok(!("conflictingFiles" in evidence), "no file list when nothing conflicted");
+    assert.equal(branchContains(local, baseMovedSha, "issue-1"), true);
+});
+test("NOT-310: base advancing during the checks poll still earns the repair round", async () => {
+    const { origin, local } = initNot310Repos({ conflict: false });
+    // D lands on origin/main while the sync poll runs — a genuine new conflict.
+    let advanced = false;
+    setConflictSyncGithubForTests({
+        checksSnapshot: async () => {
+            if (!advanced) {
+                advanced = true;
+                fs.writeFileSync(path.join(origin, "shared.txt"), "line1\nbase change\n");
+                execFileSync("git", ["add", "."], { cwd: origin });
+                execFileSync("git", ["commit", "-m", "D base moved again"], { cwd: origin });
+            }
+            return "success";
+        },
+    });
+    let merges = 0;
+    setMergePrForTests(async () => {
+        merges += 1;
+        return { ok: false, reason: NOT_MERGEABLE };
+    });
+    const issueId = newIssue({ autoMerge: true, repo: local });
+    startWorkflow(issueId);
+    await complete(issueId, cleanHandoff);
+    await complete(issueId, { kind: "verdict", result: okReview("approved") });
+    assert.equal(merges, 2);
+    assert.equal(getIssue(issueId).status, "repairing");
+    assert.equal(listHumanActionsForIssue(issueId).filter((a) => a.status === "open").length, 0);
+    const pending = listWorkItemsForIssue(issueId).filter((i) => i.status === "pending");
+    assert.equal(pending.length, 1);
+    const payload = JSON.parse(pending[0].payloadJson);
+    assert.deepEqual(payload.conflictRepair, { baseBranch: "main", branch: "issue-1", files: [] });
+});
+test("NOT-310: textual conflict aborts the sync and queues a conflict-repair round, no human action yet", async () => {
+    const { local, baseMovedSha } = initNot310Repos({ conflict: true });
+    let merges = 0;
+    setMergePrForTests(async () => {
+        merges += 1;
+        return { ok: false, reason: NOT_MERGEABLE };
+    });
+    const issueId = newIssue({ autoMerge: true, repo: local });
+    startWorkflow(issueId);
+    await complete(issueId, cleanHandoff);
+    await complete(issueId, { kind: "verdict", result: okReview("approved") });
+    assert.equal(merges, 1);
+    assert.equal(getIssue(issueId).status, "repairing");
+    assert.equal(listHumanActionsForIssue(issueId).filter((a) => a.status === "open").length, 0, "no human action is opened before the conflict-repair round runs");
+    const pending = listWorkItemsForIssue(issueId).filter((i) => i.status === "pending");
+    assert.equal(pending.length, 1);
+    assert.equal(pending[0].kind, "developer");
+    const payload = JSON.parse(pending[0].payloadJson);
+    assert.deepEqual(payload.conflictRepair, { baseBranch: "main", branch: "issue-1", files: ["shared.txt"] });
+    const prompt = buildDeveloperPrompt({
+        taskSnapshot: { title: "t", description: "d", acceptanceCriteria: "a", repo: local, baseBranch: "main" },
+        round: pending[0].round,
+        conflictRepair: payload.conflictRepair,
+    });
+    assert.ok(prompt.includes("main"), "repair prompt names the base branch");
+    assert.ok(prompt.includes("shared.txt"), "repair prompt names the conflicting files");
+    // The worktree merge was aborted: the branch still lacks the moved base ...
+    assert.equal(branchContains(local, baseMovedSha, "issue-1"), false);
+    // ... and no merge-sync checkout is left behind.
+    const root = path.join(local, ".agent-dealer-worktrees");
+    const leftovers = fs.existsSync(root) ? fs.readdirSync(root).filter((e) => e.startsWith("merge-sync-")) : [];
+    assert.deepEqual(leftovers, []);
+});
+test("NOT-310: still conflicting after the conflict-repair round escalates once, listing files", async () => {
+    const { local } = initNot310Repos({ conflict: true });
+    let merges = 0;
+    setMergePrForTests(async () => {
+        merges += 1;
+        return { ok: false, reason: NOT_MERGEABLE };
+    });
+    const issueId = newIssue({ autoMerge: true, repo: local });
+    startWorkflow(issueId);
+    await complete(issueId, cleanHandoff);
+    await complete(issueId, { kind: "verdict", result: okReview("approved") });
+    assert.equal(getIssue(issueId).status, "repairing");
+    // The conflict-repair round runs and hands off; the reviewer approves again.
+    await complete(issueId, cleanHandoff);
+    await complete(issueId, { kind: "verdict", result: okReview("approved") });
+    assert.equal(merges, 2);
+    assert.equal(getIssue(issueId).status, "needs_human");
+    assert.equal(listWorkItemsForIssue(issueId).filter((i) => i.status === "pending").length, 0);
+    const open = listHumanActionsForIssue(issueId).filter((a) => a.status === "open");
+    assert.equal(open.length, 1, "exactly one policy_escalation exists");
+    assert.equal(open[0].actionType, "policy_escalation");
+    assert.match(open[0].reason, /shared\.txt/);
+    assert.deepEqual(JSON.parse(open[0].responseOptionsJson), [
+        { choice: "retry_merge", label: "Retry merge" },
+        { choice: "repair", label: "Another repair round" },
+        { choice: "close", label: "Close" },
+    ]);
+    const evidence = JSON.parse(open[0].evidenceJson);
+    assert.equal(evidence.mergeFailure, true);
+    assert.deepEqual(evidence.conflictingFiles, ["shared.txt"]);
+});
 test("escalate txn no-ops when a racing success already marked the issue done", async () => {
     const { finalizeAutoMerge } = await import("./auto-merge.js");
     const { transitionIssue } = await import("../repository/issues.js");

package/bundle/server/dist/coordinator/auto-merge.js

@@ -27,13 +27,27 @@ import { classifyIssueRepo } from "../adapters/managed-repo.js";
 import { getDb } from "../db/index.js";
 import { getIssue, listIssues, transitionIssue } from "../repository/issues.js";
 import { appendWorkflowEvent, completeWorkflowInstance, getActiveWorkflowInstance, } from "../repository/workflow-events.js";
-import { createHumanAction, findOpenHumanAction, resolveHumanAction, } from "../repository/human-actions.js";
+import { createHumanAction, findOpenHumanAction, findOpenHumanActionByRequestId, resolveHumanAction, } from "../repository/human-actions.js";
 import { MERGE_FAILURE_EVIDENCE_KEY, MERGE_FAILURE_RESPONSE_OPTIONS } from "./human-resolution.js";
+import { isMergeConflictFailure, runMergeConflictSync } from "./merge-conflict-sync.js";
+import { OPERATOR_VERIFICATION_RESPONSE_OPTIONS, formatOperatorCriteria, getOperatorCriteriaForIssue, hasOperatorVerificationForHead, operatorVerificationRequestId, } from "./operator-criteria.js";
 const run = promisify(execFile);
 /** Bound each `gh` shell-out so a hang cannot freeze the coordinator process. */
 export const GH_MERGE_TIMEOUT_MS = 20_000;
 /** Must match projection.ts's auto_merge currentIntent — recovery keys off this string. */
 export const AUTO_MERGE_INTENT = "Auto-merging approved PR";
+/**
+ * NOT-314: the issue intent while an `[operator]` gate holds the merge. Named
+ * verbatim by the ticket: the PR stays unmerged in `needs_human` under this intent
+ * until the human records a result or waives the criterion.
+ */
+export const OPERATOR_VERIFICATION_INTENT = "Operator verification required before merge";
+/**
+ * NOT-314 fail-closed: the stable request id for the no-head escalation, so
+ * repeat finalizes dedupe onto the one open `policy_escalation` instead of
+ * stacking a new one per tick.
+ */
+export const OPERATOR_VERIFICATION_NO_HEAD_REQUEST_ID = "operator-verification-blocked:no-head";
 const ALREADY_MERGED = /already (been )?merged|pull request is not mergeable:.*merged/i;
 /**
  * Map issue.repo (portable identity or legacy local path) to a real filesystem cwd for
@@ -183,11 +197,55 @@ async function finalizeAutoMergeOnce(issueId) {
     if (issue.prNumber == null) {
         return escalateMergeFailure(issue, instance.id, "Reviewer approved but the issue has no PR number to merge.");
     }
+    // NOT-314 seam: this finalize is the single path from reviewer-approve to the
+    // `gh` merge — auto-merge-on routes here from applyCompletion, auto-merge-off
+    // arrives via final_review:merge / policy_escalation:retry_merge, and crash
+    // recovery re-enters through recoverStrandedAutoMerges. An `[operator]`
+    // criterion in the frozen snapshot blocks here (PR unmerged, needs_human)
+    // until a human records the result for the current head.
+    const operatorBlock = gateOperatorVerification(issue.id);
+    if (operatorBlock)
+        return operatorBlock;
     const resolvedCwd = resolveAutoMergeCwd(issue.repo);
     if (!resolvedCwd.ok) {
         return escalateMergeFailure(issue, instance.id, `Auto-merge failed: ${resolvedCwd.reason}`);
     }
-    const merge = await mergePrImpl({ cwd: resolvedCwd.cwd, number: issue.prNumber });
+    let merge = await mergePrImpl({ cwd: resolvedCwd.cwd, number: issue.prNumber });
+    // NOT-310: a not-mergeable failure is staleness Dealer can resolve itself —
+    // sync the base, re-verify, retry — instead of escalating with no way forward.
+    // Anything the sync refuses or cannot fix degrades to today's escalation.
+    // retry_merge parks into this same finalize, so it is covered automatically.
+    if (!merge.ok && isMergeConflictFailure(merge.reason) && issue.branch) {
+        const sync = await runMergeConflictSync({
+            issueId: issue.id,
+            instanceId: instance.id,
+            repo: issue.repo,
+            branch: issue.branch,
+            baseBranch: issue.baseBranch,
+            prNumber: issue.prNumber,
+            mergeReason: merge.reason,
+            mergePr: mergePrImpl,
+        });
+        if (sync.outcome === "merged") {
+            merge = { ok: true };
+        }
+        else if (sync.outcome === "repair_queued") {
+            return {
+                applied: true,
+                issueStatus: "repairing",
+                nextWorkItemId: sync.workItemId,
+                humanActionId: null,
+                instanceCompleted: false,
+                triggerReflect: false,
+            };
+        }
+        else if (sync.outcome === "escalate") {
+            return escalateMergeFailure(issue, instance.id, sync.reason, sync.evidence);
+        }
+        else {
+            return escalateMergeFailure(issue, instance.id, `Auto-merge failed: ${merge.reason}`);
+        }
+    }
     if (!merge.ok) {
         return escalateMergeFailure(issue, instance.id, `Auto-merge failed: ${merge.reason}`);
     }
@@ -251,7 +309,189 @@ async function finalizeAutoMergeOnce(issueId) {
         };
     })();
 }
-function escalateMergeFailure(issue, workflowInstanceId, reason) {
+/**
+ * NOT-314: the `[operator]` merge gate. After reviewer approve and before the
+ * `gh` merge: when the frozen snapshot holds operator criteria and no result is
+ * recorded for the current head (a `verified` artifact or a
+ * `operator_verification.waived` event — both head-pinned), the PR stays
+ * unmerged and the issue parks in `needs_human` with an `operator_verification`
+ * action listing each criterion and its command.
+ *
+ * Returns null when the merge may proceed (no operator criteria, a recorded
+ * result for this head, or no workflow to gate). Idempotent: a second finalize
+ * for the same head reuses the open action instead of raising another.
+ *
+ * Fail-closed: when operator criteria exist, every non-proceed path returns a
+ * result (never null), so a missing head SHA or an unexpected status blocks the
+ * `gh` merge instead of letting it through.
+ */
+export function gateOperatorVerification(issueId) {
+    return getDb().transaction(() => {
+        const current = getIssue(issueId);
+        if (!current)
+            return null;
+        const active = getActiveWorkflowInstance(issueId);
+        if (!active)
+            return null;
+        const criteria = getOperatorCriteriaForIssue(current);
+        if (criteria.length === 0)
+            return null;
+        const head = current.headSha;
+        if (head && hasOperatorVerificationForHead(issueId, head))
+            return null;
+        if (current.status === "done")
+            return null;
+        // Only the auto-merge park (or an already-gated issue) is gated — any other
+        // status is a racer or a non-parked issue; do not invent an action there,
+        // but do not let the merge through either — park the finalize as a no-op.
+        if (current.status !== "final_review" && current.status !== "needs_human") {
+            return {
+                applied: true,
+                issueStatus: current.status,
+                nextWorkItemId: null,
+                humanActionId: null,
+                instanceCompleted: false,
+                triggerReflect: false,
+            };
+        }
+        // No head SHA to pin the verification to (no handoff recorded one): the
+        // gate cannot name a head, so escalate instead of merging — retry_merge
+        // re-enters this same finalize once a head exists and gates normally.
+        // Repeat finalizes reuse the one open escalation (no duplicate action or
+        // event), and the transition is skipped when already parked
+        // (needs_human has no self-loop).
+        if (!head) {
+            const retry = findOpenHumanActionByRequestId(issueId, "policy_escalation", OPERATOR_VERIFICATION_NO_HEAD_REQUEST_ID);
+            if (retry) {
+                if (current.status !== "needs_human") {
+                    transitionIssue(issueId, "needs_human", {
+                        currentOwner: "human",
+                        currentIntent: OPERATOR_VERIFICATION_INTENT,
+                    });
+                }
+                return {
+                    applied: true,
+                    issueStatus: "needs_human",
+                    nextWorkItemId: null,
+                    humanActionId: retry.id,
+                    instanceCompleted: false,
+                    triggerReflect: false,
+                };
+            }
+            const reason = `Reviewer approved, but ${criteria.length} acceptance ` +
+                `${criteria.length === 1 ? "criterion requires" : "criteria require"} a human operator ` +
+                `to verify (tagged [operator] in the frozen task snapshot) and no head SHA is ` +
+                `recorded to pin the verification to. The PR stays unmerged.`;
+            if (current.status !== "needs_human") {
+                transitionIssue(issueId, "needs_human", {
+                    currentOwner: "human",
+                    currentIntent: reason,
+                });
+            }
+            const action = createHumanAction({
+                issueId,
+                workflowInstanceId: active.id,
+                actionType: "policy_escalation",
+                reason,
+                question: `${reason} Retry the merge once a head is recorded, queue another repair round, or close the issue?`,
+                evidence: { [MERGE_FAILURE_EVIDENCE_KEY]: true, operatorVerificationBlocked: true },
+                responseOptions: [...MERGE_FAILURE_RESPONSE_OPTIONS],
+                requestId: OPERATOR_VERIFICATION_NO_HEAD_REQUEST_ID,
+            });
+            appendWorkflowEvent({
+                issueId,
+                workflowInstanceId: active.id,
+                workerSessionId: null,
+                type: "human_action.requested",
+                actorType: "system",
+                stage: "needs_human",
+                round: current.currentRound,
+                payload: { actionType: "policy_escalation", actionId: action.id, operatorVerificationBlocked: true },
+            });
+            return {
+                applied: true,
+                issueStatus: "needs_human",
+                nextWorkItemId: null,
+                humanActionId: action.id,
+                instanceCompleted: false,
+                triggerReflect: false,
+            };
+        }
+        const existing = findOpenHumanAction(issueId, "operator_verification");
+        if (existing && operatorActionHeadSha(existing) === head) {
+            if (current.status !== "needs_human") {
+                transitionIssue(issueId, "needs_human", {
+                    currentOwner: "human",
+                    currentIntent: OPERATOR_VERIFICATION_INTENT,
+                });
+            }
+            return {
+                applied: true,
+                issueStatus: "needs_human",
+                nextWorkItemId: null,
+                humanActionId: existing.id,
+                instanceCompleted: false,
+                triggerReflect: false,
+            };
+        }
+        const shortHead = head.slice(0, 8);
+        const reason = `Reviewer approved ${shortHead}, but ${criteria.length} acceptance ` +
+            `${criteria.length === 1 ? "criterion requires" : "criteria require"} a human operator ` +
+            `to verify (tagged [operator] in the frozen task snapshot) and no result is recorded ` +
+            `for this head. The PR stays unmerged until the result is recorded:\n` +
+            formatOperatorCriteria(criteria).join("\n");
+        transitionIssue(issueId, "needs_human", {
+            currentOwner: "human",
+            currentIntent: OPERATOR_VERIFICATION_INTENT,
+        });
+        // Head-pinned request_id: a concurrent finalize for the same head dedupes
+        // onto this action through createHumanAction's open-request conflict path;
+        // new commits after the gate get a fresh action with their own commands.
+        const action = createHumanAction({
+            issueId,
+            workflowInstanceId: active.id,
+            actionType: "operator_verification",
+            reason,
+            question: `${reason}\n\nPaste the probe output to record verification, waive with a reason, ` +
+                `or send the work back for another repair round?`,
+            evidence: { operatorVerification: { criteria, headSha: head } },
+            responseOptions: [...OPERATOR_VERIFICATION_RESPONSE_OPTIONS],
+            requestId: operatorVerificationRequestId(head),
+        });
+        appendWorkflowEvent({
+            issueId,
+            workflowInstanceId: active.id,
+            workerSessionId: null,
+            type: "human_action.requested",
+            actorType: "system",
+            stage: "needs_human",
+            round: current.currentRound,
+            payload: { actionType: "operator_verification", actionId: action.id, headSha: head },
+        });
+        return {
+            applied: true,
+            issueStatus: "needs_human",
+            nextWorkItemId: null,
+            humanActionId: action.id,
+            instanceCompleted: false,
+            triggerReflect: false,
+        };
+    })();
+}
+/** The head SHA an `operator_verification` action gates (null when unreadable). */
+function operatorActionHeadSha(action) {
+    if (!action.evidenceJson)
+        return null;
+    try {
+        const evidence = JSON.parse(action.evidenceJson);
+        const headSha = evidence.operatorVerification?.headSha;
+        return typeof headSha === "string" && headSha ? headSha : null;
+    }
+    catch {
+        return null;
+    }
+}
+function escalateMergeFailure(issue, workflowInstanceId, reason, evidence = { [MERGE_FAILURE_EVIDENCE_KEY]: true }) {
     return getDb().transaction(() => {
         const current = getIssue(issue.id);
         // Concurrent success already completed — never open a dangling escalation on done.
@@ -304,7 +544,7 @@ function escalateMergeFailure(issue, workflowInstanceId, reason) {
             actionType: "policy_escalation",
             reason,
             question: `${reason} Retry the merge, queue another repair round, or close the issue?`,
-            evidence: { [MERGE_FAILURE_EVIDENCE_KEY]: true },
+            evidence,
             responseOptions: [...MERGE_FAILURE_RESPONSE_OPTIONS],
         });
         appendWorkflowEvent({

package/bundle/server/dist/coordinator/checks-wait-config.js

@@ -0,0 +1,19 @@
+// packages/server/src/coordinator/checks-wait-config.ts
+//
+// NOT-311: how long one work item may wait on CI before the wait itself escalates.
+// The per-poll bound (CHECKS_POLL_TIMEOUT_MS, default 10 min) only ends a single
+// poll with a `checks_pending` deferral; this ceiling bounds the whole wait measured
+// from the first poll, across deferrals. Past it the item stops re-queueing and a
+// human is asked to look at the stuck CI run instead of waiting forever.
+/** Overall CI-wait ceiling measured from the first checks poll (default 2 h). */
+export function checksWaitCeilingMs() {
+    const parsed = Number(process.env.CHECKS_WAIT_CEILING_MS ?? 2 * 60 * 60_000);
+    return Number.isFinite(parsed) ? parsed : 2 * 60 * 60_000;
+}
+/** True once `nowMs` is at or past the ceiling after the first wait started. */
+export function checksWaitCeilingExceeded(firstWaitStartedAt, nowMs = Date.now()) {
+    const start = Date.parse(firstWaitStartedAt);
+    if (!Number.isFinite(start))
+        return false;
+    return nowMs - start >= checksWaitCeilingMs();
+}