agent-dealer 1.2.8 → 1.2.9

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

@@ -27,14 +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
@@ -184,6 +197,15 @@ 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}`);
@@ -287,6 +309,188 @@ async function finalizeAutoMergeOnce(issueId) {
         };
     })();
 }
+/**
+ * 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);

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();
+}

package/bundle/server/dist/coordinator/commands.js

@@ -9,7 +9,7 @@
 import fs from "node:fs";
 import { canTransitionIssue, tryCompileContract } from "@agent-dealer/shared";
 import { getDb } from "../db/index.js";
-import { getIssue, incrementIssueRound, incrementIssueInfraAttempts, resetIssueInfraAttempts, grantReviewRetry, transitionIssue, } from "../repository/issues.js";
+import { getIssue, incrementIssueRound, incrementIssueInfraAttempts, incrementIssueCiAttempts, resetIssueInfraAttempts, resetIssueCiAttempts, grantReviewRetry, transitionIssue, } from "../repository/issues.js";
 import { appendWorkflowEvent, completeWorkflowInstance, getActiveWorkflowInstance, getWorkflowInstance, listWorkflowEventsForIssue, startWorkflowInstance, WorkflowAlreadyActiveError, } from "../repository/workflow-events.js";
 import { createHumanAction, findOpenHumanAction, getHumanAction, listHumanActionsForIssue, reopenHumanAction, resolveHumanAction, updateOpenHumanAction, } from "../repository/human-actions.js";
 import { pushLeaseToSha, readRemoteTip } from "../adapters/git-worktree.js";
@@ -20,7 +20,7 @@ import { getAgent } from "../repository/agents.js";
 import { githubIssuesSync, invalidateMuseHealthCache } from "../adapters/agent-health.js";
 import { recordMuseCapabilityOverride } from "../adapters/muse-capability.js";
 import { createIssueArtifact, latestIssueArtifact } from "../repository/artifacts.js";
-import { cancelWorkItem, enqueueWorkItem, finishWorkItem, getWorkItem, listWorkItemsForIssue, } from "../repository/work-items.js";
+import { cancelWorkItem, enqueueWorkItem, finishWorkItem, getWorkItem, getWorkItemByIdempotencyKey, listWorkItemsForIssue, } from "../repository/work-items.js";
 import { completeSession, getWorkerSession, listWorkerSessionsForIssue } from "../repository/worker-sessions.js";
 import { killRunProcess } from "../runners/spawn-cli.js";
 import { buildProfileSnapshot, serializeProfileSnapshot } from "./profile-snapshot.js";
@@ -31,9 +31,10 @@ import { routeDeveloperOutcome, routeReviewerOutcome, } from "./routing.js";
 import { projectDeveloperRoute, projectReviewerRoute } from "./projection.js";
 import { MERGE_FAILURE_EVIDENCE_KEY, MERGE_FAILURE_RESPONSE_OPTIONS, PUSH_DIVERGENCE_EVIDENCE_KEY, PUSH_DIVERGENCE_RESPONSE_OPTIONS, WORKTREE_BLOCKER_EVIDENCE_KEY, normalizeResolutionNote, parseHumanResolution, resolveHumanActionOutcome, } from "./human-resolution.js";
 import { AUTO_MERGE_INTENT, finalizeAutoMerge } from "./auto-merge.js";
+import { OPERATOR_VERIFICATION_ARTIFACT_KIND, OPERATOR_VERIFICATION_RESPONSE_OPTIONS, } from "./operator-criteria.js";
 import { externalMergeStateForIssue } from "./external-merge.js";
 import { detectNonConvergence, formatNonConvergenceReason, reviewHistoryFromEvents, } from "./non-convergence.js";
-import { capEscalationEvents, deferLeasedWorkItemForBaseFetch, deferLeasedWorkItemForDeckOutage, deferLeasedWorkItemForUsageCap, formatCapEscalationReason, usageCapDeferralStartedAt, } from "./usage-cap-defer.js";
+import { capEscalationEvents, checksWaitDeferralStartedAt, deferLeasedWorkItemForBaseFetch, deferLeasedWorkItemForChecksPending, deferLeasedWorkItemForDeckOutage, deferLeasedWorkItemForUsageCap, formatCapEscalationReason, formatChecksWaitEscalationReason, usageCapDeferralStartedAt, } from "./usage-cap-defer.js";
 import { dequeueIssue, getQueuedEntryForIssue, markQueueEntryAdmitted, } from "../repository/queue-entries.js";
 import { fetchResumeLiveHeadSha } from "./resume-live-head.js";
 import { getWorkflow } from "./workflows/registry.js";
@@ -136,7 +137,11 @@ function freezeTaskSnapshot(issue) {
  * never changes the eventual session. The worker loop consumes this off the payload and
  * only falls back to a live resolve for a legacy item queued before snapshots were carried.
  */
-function queuedProfileSnapshot(issue, kind) {
+/**
+ * NOT-333: shared with recovery's stranded-reviewer re-enqueue so a recovered round
+ * carries the same frozen profile as a normally routed one.
+ */
+export function queuedProfileSnapshot(issue, kind) {
     const agentId = kind === "developer" ? issue.developerAgentId : issue.reviewerAgentId;
     const agent = agentId ? getAgent(agentId) : null;
     return agent ? serializeProfileSnapshot(buildProfileSnapshot(agent, kind)) : null;
@@ -327,6 +332,12 @@ export async function applyCompletion(workItemId, leaseToken, outcome) {
     if (outcome.kind === "base_fetch_failed") {
         return applyBaseFetchDeferralCompletion(workItemId, leaseToken, outcome);
     }
+    // NOT-311: CI still queued/running (or not yet registered) at the poll timeout —
+    // the session ended cleanly, so the item waits on backoff and re-polls instead of
+    // spending an infra attempt. Past the wait ceiling this escalates to a human.
+    if (outcome.kind === "checks_pending") {
+        return applyChecksPendingCompletion(workItemId, leaseToken, outcome);
+    }
     const routed = getDb().transaction(() => {
         const before = getWorkItem(workItemId);
         if (!before)
@@ -415,6 +426,68 @@ function applyDeckOutageCompletion(workItemId, leaseToken, outage) {
 function applyBaseFetchDeferralCompletion(workItemId, leaseToken, failure) {
     return applyDeferralCompletion(workItemId, leaseToken, failure, (item, issue, instance) => deferLeasedWorkItemForBaseFetch(item, leaseToken, failure, issue, instance));
 }
+/**
+ * NOT-311: CI still pending at the poll timeout — defer with backoff, no attempt
+ * spent. Unlike a deck outage the wait has a ceiling, so the escalation arm raises a
+ * human action naming the stuck PR/SHA once CI has waited too long.
+ */
+function applyChecksPendingCompletion(workItemId, leaseToken, pending) {
+    return applyDeferralCompletion(workItemId, leaseToken, pending, (item, issue, instance) => deferLeasedWorkItemForChecksPending(item, leaseToken, pending, issue, instance), (issue, instance, item) => routeChecksWaitEscalation(issue, instance, item, pending));
+}
+/**
+ * NOT-311: the CI wait passed its ceiling — hand to a human with the PR and head SHA
+ * CI never proved, without spending infra attempts. Mirrors the usage-cap ceiling
+ * escalation (worker.failed + needs_human + policy_escalation).
+ */
+export function routeChecksWaitEscalation(issue, instance, item, pending) {
+    const payload = parseWorkItemPayload(item.payloadJson);
+    const firstDeferredAt = checksWaitDeferralStartedAt(payload) ?? pending.waitStartedAt;
+    const reason = formatChecksWaitEscalationReason(pending, firstDeferredAt);
+    const role = item.kind === "developer" ? "developer" : "reviewer";
+    const ev = eventEmitter(issue, instance, item.workerSessionId, "needs_human", issue.currentRound);
+    for (const type of capEscalationEvents()) {
+        const session = item.workerSessionId ? getWorkerSession(item.workerSessionId) : null;
+        ev.emit(type, {
+            actorType: role,
+            payload: {
+                ...workerSessionPayload({
+                    runtime: session?.runtime ?? null,
+                    model: session?.model ?? null,
+                    sessionId: item.workerSessionId ?? "",
+                    worktreePath: session?.worktreePath,
+                }),
+                outcome: "checks_pending",
+                reason: pending.reason,
+                branch: pending.branch,
+                prNumber: pending.prNumber,
+                headSha: pending.headSha,
+            },
+        });
+    }
+    applyProjectionTransition(issue, {
+        issueStatus: "needs_human",
+        currentOwner: "human",
+        currentIntent: reason,
+        events: capEscalationEvents(),
+    }, {});
+    const action = createHumanAction({
+        issueId: issue.id,
+        workflowInstanceId: instance.id,
+        actionType: "policy_escalation",
+        reason,
+        question: questionFor("policy_escalation", reason),
+        evidence: { checksPending: { ...pending, firstDeferredAt } },
+        responseOptions: responseOptionsFor("policy_escalation"),
+    });
+    ev.emit("human_action.requested", { payload: { actionType: "policy_escalation", actionId: action.id } });
+    return {
+        applied: true,
+        issueStatus: "needs_human",
+        nextWorkItemId: null,
+        humanActionId: action.id,
+        instanceCompleted: false,
+    };
+}
 /**
  * Deferral ceiling exceeded — escalate with cap evidence without spending infra attempts.
  * Used when applyCompletion or the worker loop cannot defer any longer.
@@ -525,6 +598,8 @@ function applyDeveloper(issue, instance, item, outcome) {
         maxReviewRounds: issue.maxReviewRounds,
         infraAttempts: issue.infraAttempts,
         maxInfraAttempts: issue.maxInfraAttempts,
+        ciAttempts: issue.ciAttempts,
+        maxCiAttempts: issue.maxCiAttempts,
     });
     const { projection, effect, advance } = projectDeveloperRoute(route, issue.status, issue.currentRound);
     const ev = eventEmitter(issue, instance, item.workerSessionId, projection.issueStatus, issue.currentRound);
@@ -607,6 +682,9 @@ function applyDeveloper(issue, instance, item, outcome) {
         incrementIssueRound(issue.id);
     else if (advance === "infra")
         incrementIssueInfraAttempts(issue.id);
+    // NOT-313: a CI-repair retry spends ci_attempts, never infra_attempts.
+    else if (advance === "ci")
+        incrementIssueCiAttempts(issue.id);
     const issueNow = getIssue(issue.id);
     return applyEffect(issue, instance, effect, route, issueNow, ev, item.id);
 }
@@ -740,9 +818,10 @@ function findNonConvergence(issue, instance, result) {
     });
     return detectNonConvergence(history, issue.currentRound, floorRound);
 }
-/** Every route that spends an infra attempt (projection.ts's advance === "infra") repeats
- * the same round/head, so its enqueue needs a suffix the plain round/head key doesn't
- * provide to avoid colliding with the previous (terminal) attempt's key.
+/** Every route that spends an infra or CI attempt (projection.ts's advance === "infra"
+ * or "ci") repeats the same round/head, so its enqueue needs a suffix the plain
+ * round/head key doesn't provide to avoid colliding with the previous (terminal)
+ * attempt's key.
  * retry_reviewer_at_new_head belongs here too — a head that cycles A→B→A would otherwise
  * re-derive attempt A's ORIGINAL key (same round, same head) and collide with that
  * now-terminal work item, leaving the issue "reviewing" with no pending item. */
@@ -773,6 +852,21 @@ function applyEffect(issue, instance, effect, route, issueNow, ev, causativeItem
         const attemptSuffix = isInfraRetry(route) ? `:retry-of:${causativeItemId}` : "";
         if (route.next === "retry_developer_with_findings")
             ev.emit("repair.started");
+        let idempotencyKey = `${instance.id}:${kind}:${issueNow.currentRound}${headSuffix}${attemptSuffix}`;
+        // NOT-333: a developer round that pushes nothing (e.g. a resume round that only
+        // updates the PR description) re-derives the exact key of the already-terminal
+        // reviewer item it follows — same instance, same round, same head — so the enqueue
+        // dedupes against that done row and strands the issue in `reviewing` with no pending
+        // work. A terminal duplicate gets the same `:retry-of:<causative work item id>`
+        // shape the infra-retry path uses, so a new row is created; a still-active
+        // (pending/leased) duplicate keeps deduping.
+        if (kind === "reviewer" && attemptSuffix === "") {
+            const existing = getWorkItemByIdempotencyKey(idempotencyKey);
+            if (existing &&
+                (existing.status === "done" || existing.status === "dead" || existing.status === "cancelled")) {
+                idempotencyKey += `:retry-of:${causativeItemId}`;
+            }
+        }
         const next = enqueueWorkItem({
             issueId: issue.id,
             workflowInstanceId: instance.id,
@@ -785,7 +879,7 @@ function applyEffect(issue, instance, effect, route, issueNow, ev, causativeItem
                 ...(effect.branch ? { branch: effect.branch } : {}),
                 profileSnapshot: queuedProfileSnapshot(issue, kind),
             },
-            idempotencyKey: `${instance.id}:${kind}:${issueNow.currentRound}${headSuffix}${attemptSuffix}`,
+            idempotencyKey,
         });
         return { ...base, nextWorkItemId: next.id };
     }
@@ -996,6 +1090,12 @@ function questionFor(actionType, reason, resumeAsReviewer = false, mergeFailure
             // directly with its own question text (NOT-308). Case exists only so this
             // function stays total over HumanActionType.
             throw new Error("muse_capability is not raised through applyEffect");
+        case "operator_verification":
+            // Never raised through applyEffect — auto-merge.ts's operator gate creates
+            // this action directly with a question listing each criterion and its
+            // command (NOT-314). Case exists only so this function stays total over
+            // HumanActionType.
+            throw new Error("operator_verification is not raised through applyEffect");
     }
 }
 /** Exported for db/migrate-to-issues.ts, which must populate the same response options on
@@ -1042,6 +1142,11 @@ export function responseOptionsFor(actionType, resumeAsReviewer = false, opts =
             // admits on that Muse version (missing) or dismisses (unverified). Never raised
             // through applyEffect; case exists only so this function stays total.
             return [{ choice: "acknowledge", label: "Acknowledge" }];
+        case "operator_verification":
+            // Raised by auto-merge.ts's operator gate with these exact options (the
+            // shared constant keeps the two from drifting); listed here so the table
+            // stays total over HumanActionType.
+            return [...OPERATOR_VERIFICATION_RESPONSE_OPTIONS];
     }
 }
 function parseContinuationPreview(json) {
@@ -1080,6 +1185,17 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
     const normalizedNote = normalizeResolutionNote(opts?.note);
     if (!normalizedNote.ok)
         return { ok: false, code: 400, error: normalizedNote.error };
+    // NOT-314: every operator_verification choice requires a non-empty note — the
+    // recorded result (verified), the waiver reason (waive), or what to fix
+    // (repair). parseHumanResolution below also rejects a missing note; this
+    // names the requirement instead of misreporting a valid choice as invalid.
+    if (action.actionType === "operator_verification" && !normalizedNote.note) {
+        return {
+            ok: false,
+            code: 400,
+            error: 'A non-empty note is required to resolve operator_verification (verified: the result, e.g. pasted output; waive: why it is waived; repair: what the next round must fix)',
+        };
+    }
     // NOT-308: a Muse capability escalation resolves without touching the workflow — it
     // has no round to spend and no merge to park, and parseHumanResolution (below)
     // deliberately rejects it since there is no workflow outcome to map. Acknowledging a
@@ -1140,13 +1256,17 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
         return { ok: false, code: 400, error: `Invalid choice "${choice}" for ${action.actionType}` };
     }
     // NOT-272: the typed resolution carries the note only for product_scope_decision
-    // (parseHumanResolution drops it for every other action type).
+    // (parseHumanResolution drops it for every other action type — except
+    // operator_verification, whose note is required and always carried).
     const scopeDecisionNote = resolution.actionType === "product_scope_decision" && "note" in resolution
         ? resolution.note
         : undefined;
-    const storedResolution = scopeDecisionNote
-        ? { choice, note: scopeDecisionNote }
-        : { choice };
+    // NOT-314: the repair instruction rides the next developer round's payload;
+    // the verified/waived note is stored on the artifact / waiver event below.
+    const operatorNote = resolution.actionType === "operator_verification" && "note" in resolution
+        ? resolution.note
+        : undefined;
+    const storedResolution = scopeDecisionNote ?? operatorNote ? { choice, note: scopeDecisionNote ?? operatorNote } : { choice };
     // NOT-194: narrow policy_escalation choices per action. A merge-failure action offers
     // retry_merge/repair/close only (resume would re-run development on approved work);
     // every other policy_escalation keeps resume/close only. Pre-NOT-194 open merge-failure
@@ -1191,12 +1311,56 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
     // Park like auto-merge, then the async wrapper runs finalizeAutoMerge outside this txn.
     // NOT-194: a merge-failure retry_merge parks the same way — the old action is resolved
     // first, so a second failure escalates exactly one fresh action with the new reason.
-    if (instance &&
-        ((resolution.actionType === "final_review" &&
-            (resolution.choice === "merge" || resolution.choice === "complete")) ||
-            (resolution.actionType === "policy_escalation" && resolution.choice === "retry_merge"))) {
+    // NOT-314: an operator_verification verified/waive parks the same way — the recorded
+    // result satisfies the gate, so finalizeAutoMerge merges on the very next pass.
+    // (repair takes the generic repair-round path below, never this park.)
+    const parksForMerge = (resolution.actionType === "final_review" &&
+        (resolution.choice === "merge" || resolution.choice === "complete")) ||
+        (resolution.actionType === "policy_escalation" && resolution.choice === "retry_merge") ||
+        (resolution.actionType === "operator_verification" &&
+            (resolution.choice === "verified" || resolution.choice === "waive"));
+    if (instance && parksForMerge) {
         return getDb().transaction(() => {
-            resolveHumanAction(actionId, resolvedBy, { choice });
+            resolveHumanAction(actionId, resolvedBy, storedResolution);
+            // NOT-314: durably record what the merge is authorized by, in the same txn as
+            // the park — `verified` stores the result as an issue artifact (kind
+            // operator_verification, author human) pinned to this head; `waive`
+            // appends an operator_verification.waived workflow event. A later finalize
+            // re-checks the record against the then-current head, so new commits
+            // re-block the gate.
+            if (resolution.actionType === "operator_verification" && operatorNote) {
+                if (resolution.choice === "verified") {
+                    createIssueArtifact({
+                        issueId: issue.id,
+                        kind: OPERATOR_VERIFICATION_ARTIFACT_KIND,
+                        author: "human",
+                        content: {
+                            headSha: issue.headSha,
+                            note: operatorNote,
+                            verifiedBy: resolvedBy,
+                            verifiedAt: new Date().toISOString(),
+                        },
+                    });
+                }
+                else {
+                    appendWorkflowEvent({
+                        issueId: issue.id,
+                        workflowInstanceId: instance.id,
+                        type: "operator_verification.waived",
+                        actorType: "human",
+                        actorRef: resolvedBy,
+                        stage: issue.status,
+                        round: issue.currentRound,
+                        payload: {
+                            actionType: "operator_verification",
+                            choice: "waive",
+                            headSha: issue.headSha,
+                            waivedBy: resolvedBy,
+                            note: operatorNote,
+                        },
+                    });
+                }
+            }
             appendWorkflowEvent({
                 issueId: issue.id,
                 workflowInstanceId: instance.id,
@@ -1205,7 +1369,12 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
                 actorRef: resolvedBy,
                 stage: resolution.actionType === "final_review" ? "final_review" : issue.status,
                 round: issue.currentRound,
-                payload: { actionType: action.actionType, choice: resolution.choice, pendingMerge: true },
+                payload: {
+                    actionType: action.actionType,
+                    choice: resolution.choice,
+                    pendingMerge: true,
+                    ...(operatorNote ? { note: operatorNote } : {}),
+                },
             });
             transitionIssue(issue.id, "final_review", {
                 currentOwner: "system",
@@ -1411,7 +1580,10 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
                 incrementIssueRound(issue.id);
                 break;
             case "infra":
+                // NOT-313: a resume past an infra OR CI-checks escalation grants a fresh
+                // budget of both kinds — the CI budget is not a review-round spend either.
                 resetIssueInfraAttempts(issue.id);
+                resetIssueCiAttempts(issue.id);
                 if (advancesRound)
                     incrementIssueRound(issue.id);
                 break;
@@ -1455,6 +1627,10 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
                     // NOT-272: a product_scope_decision note rides only this next round's
                     // payload — later rounds never see it.
                     ...(scopeDecisionNote ? { scopeDecisionNote } : {}),
+                    // NOT-314: same one-shot ride for an operator_verification repair
+                    // note — only the repair choice reaches this path (verified/waive
+                    // park for merge above), and only this round reads it.
+                    ...(operatorNote ? { operatorRepairNote: operatorNote } : {}),
                 },
                 idempotencyKey: resumeKey,
             });

package/bundle/server/dist/coordinator/commands.test.js

@@ -635,6 +635,53 @@ test("fail → retry → exhaust → resume → fail again does not collide with
     assert.equal(pending.length, 1, "a fresh item must be enqueued — the old (round, infraAttempts)-keyed row must not be silently reused");
     assert.notEqual(pending[0].id, firstRetryItem.id, "must be a NEW work item, not the pre-escalation retry's now-terminal row");
 });
+test("NOT-333: a resume round that pushes nothing still enqueues a fresh reviewer instead of deduping against the terminal one", async () => {
+    // The NOT-200 shape: reviewer round 1 at head H escalates with a product scope
+    // question, the human resumes, and the developer round changes nothing — so its
+    // handoff re-derives the exact idempotency key of the already-done reviewer item.
+    const issueId = newIssue();
+    startWorkflow(issueId);
+    await complete(issueId, cleanHandoff);
+    const firstReviewer = listWorkItemsForIssue(issueId).find((i) => i.kind === "reviewer");
+    await complete(issueId, {
+        kind: "verdict",
+        result: { ...okReview("escalated"), productScopeQuestion: "Should deleted users retain sessions?" },
+    });
+    const action = listHumanActionsForIssue(issueId).find((a) => a.actionType === "product_scope_decision");
+    const resolved = resolveHumanActionAndAdvance(action.id, "yusuke", "resume");
+    assert.equal(resolved.ok, true);
+    assert.equal(getIssue(issueId).status, "developing");
+    // The resume round pushes nothing: the handoff carries the very same head SHA.
+    const { result } = await complete(issueId, cleanHandoff);
+    assert.equal(result.applied, true);
+    assert.equal(getIssue(issueId).status, "reviewing");
+    assert.equal(getWorkItem(firstReviewer.id).status, "done");
+    const reviewers = listWorkItemsForIssue(issueId).filter((i) => i.kind === "reviewer");
+    const pending = reviewers.filter((i) => i.status === "pending");
+    assert.equal(pending.length, 1, "a fresh reviewer round must be queued, not dropped via a key collision");
+    assert.notEqual(pending[0].id, firstReviewer.id, "must be a NEW work item, not the escalated round's now-terminal row");
+    assert.match(pending[0].idempotencyKey, /:retry-of:/, "the terminal duplicate is disambiguated like an infra retry");
+    assert.equal(JSON.parse(pending[0].payloadJson).inputSha, cleanHandoff.headSha);
+});
+test("NOT-333: a duplicate developer completion while the reviewer is still pending or leased enqueues no second reviewer", async () => {
+    const issueId = newIssue();
+    startWorkflow(issueId);
+    const item = claim(issueId);
+    const first = await applyCompletion(item.id, item.leaseToken, cleanHandoff);
+    assert.equal(first.applied, true);
+    // A retried callback redelivers the same completion while the reviewer is pending.
+    const second = await applyCompletion(item.id, item.leaseToken, cleanHandoff);
+    assert.equal(second.applied, false);
+    // Same while the reviewer is leased — still exactly one active reviewer row.
+    const reviewer = claim(issueId);
+    assert.equal(reviewer.kind, "reviewer");
+    const third = await applyCompletion(item.id, item.leaseToken, cleanHandoff);
+    assert.equal(third.applied, false);
+    const active = listWorkItemsForIssue(issueId).filter((i) => i.kind === "reviewer" && (i.status === "pending" || i.status === "leased"));
+    assert.equal(active.length, 1);
+    assert.equal(active[0].id, reviewer.id);
+    assert.equal(listWorkItemsForIssue(issueId).filter((i) => i.kind === "reviewer").length, 1);
+});
 test("resolving product_scope_decision:resume after a reviewer's escalated+question resumes as the developer", async () => {
     const issueId = newIssue();
     startWorkflow(issueId);