agent-dealer 1.2.8 → 1.2.9

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

@@ -1,5 +1,7 @@
+import { MUSE_SANDBOX_CAPABILITIES } from "../runners/muse-code-args.js";
 import { checkMuseVisualQa, museVisualQaPromptSection, } from "../adapters/muse-visual-qa.js";
 import { formatVerificationReceiptSection, } from "./verification-receipt.js";
+import { formatOperatorCriteria, } from "./operator-criteria.js";
 /**
  * NOT-306: render the frozen execution contract as dedicated sections. These
  * are the ticket's own execution semantics — the worker follows them as
@@ -67,6 +69,113 @@ function conflictRepairSection(directive) {
         ``,
     ];
 }
+/** NOT-314: the frozen snapshot's `[operator]` criteria for the developer.
+ * Empty/absent renders nothing so operator-free tasks produce byte-for-byte
+ * the prompt they always did. */
+function operatorDeveloperSection(criteria) {
+    if (!criteria?.length)
+        return [];
+    return [
+        `## Operator verification required ([operator] criteria)`,
+        `These acceptance criteria can only be proven by a human operator with real credentials, a real login, or a paid session — Dealer blocks the merge until the operator records the result, so do not work around the gate. Do not attempt these; ship the ready-to-run probe and a doc, put the exact command in the PR body:`,
+        ``,
+        ...formatOperatorCriteria(criteria),
+        ``,
+    ];
+}
+/** NOT-314: an operator_verification `repair` note, verbatim. Empty/absent
+ * renders nothing so ordinary rounds produce byte-for-byte the prompt they always did. */
+function operatorRepairSection(note) {
+    if (!note?.trim())
+        return [];
+    return [
+        `## Operator verification feedback`,
+        `A human reviewed the operator-gated criteria and sent the work back instead of verifying. Address this before anything else, and do not ask the operator to re-verify the same head without fixing it:`,
+        ``,
+        note.trim(),
+        ``,
+    ];
+}
+/** NOT-314: the frozen snapshot's `[operator]` criteria for the reviewer.
+ * Missing operator evidence is NOT a defect (Dealer gates the merge itself) —
+ * but the probe and the doc must exist. Empty/absent renders nothing. */
+function operatorReviewerSection(criteria) {
+    if (!criteria?.length)
+        return [];
+    return [
+        `## Operator-gated criteria ([operator]) — not yours to verify`,
+        `Missing operator evidence is NOT a defect: Dealer blocks the merge until a human operator records the result, so never raise a blocking finding and never escalate for an unverified [operator] criterion. What you MUST check instead is that the probe and doc exist: the diff must ship the ready-to-run probe for each criterion below, the doc must name the exact command, and the PR body must carry it. A missing probe or doc IS a blocking finding.`,
+        ``,
+        ...formatOperatorCriteria(criteria),
+        ``,
+    ];
+}
+/**
+ * NOT-316: the Muse developer sandbox limits, rendered from
+ * `MUSE_SANDBOX_CAPABILITIES` (which is tied by test to the real
+ * `--sandbox-network` launch flag) instead of hand-written prose, so the
+ * prompt cannot drift from what the sandbox actually does. Muse developers
+ * only — returns [] otherwise, so non-Muse prompts are byte-for-byte
+ * unchanged.
+ */
+function museEnvironmentLimitsSection() {
+    const caps = MUSE_SANDBOX_CAPABILITIES;
+    return [
+        `## Environment limits (sandbox network: ${caps.sandboxNetwork})`,
+        `This session runs inside the Muse sandbox with network \`${caps.network}\` — these limits come from the launch flags and cannot be worked around:`,
+        ``,
+        `- Network: ${caps.network} (no DNS — the npm registry and GitHub API are unreachable).`,
+        `- Loopback listeners: ${caps.loopbackListen ? "yes" : "no"} — \`listen()\` fails with EPERM, so do not start servers.`,
+        `- Browser: ${caps.browser ? "yes" : "no"}.`,
+        `- Credentials/Keychain: ${caps.credentialsKeychain ? "yes" : "no"}.`,
+        `After one failed attempt at something the environment cannot do (install, listen, browser, credentials), stop and hand off; do not work around the sandbox.`,
+        ``,
+    ];
+}
+function acceptanceCriteriaHasTag(acceptanceCriteria, tag) {
+    return acceptanceCriteria.includes(tag);
+}
+/**
+ * NOT-316: what `[agent]` / `[ci]` tags on acceptance criteria mean for a Muse
+ * developer. Rendered only when the AC text carries the tag (per-tag lines)
+ * and only for Muse developers — otherwise returns [] so untagged and
+ * non-Muse prompts are byte-for-byte what they always were. `[operator]`
+ * criteria are owned by the operator-gate section (`operatorDeveloperSection`)
+ * and deliberately not duplicated here.
+ */
+function tagSemanticsDeveloperSection(acceptanceCriteria) {
+    const lines = [];
+    if (acceptanceCriteriaHasTag(acceptanceCriteria, "[agent]")) {
+        lines.push(`- \`[agent]\`: verify yourself — prove the criterion with your own in-session runs (targeted tests); your verification is the evidence.`);
+    }
+    if (acceptanceCriteriaHasTag(acceptanceCriteria, "[ci]")) {
+        lines.push(`- \`[ci]\`: implement or extend the named CI job/test and push — CI is the evidence, do not reproduce it locally.`);
+    }
+    if (!lines.length)
+        return [];
+    return [`## Acceptance-criterion tags ([agent] / [ci])`, ...lines, ``];
+}
+/**
+ * NOT-316: how the reviewer judges tagged criteria. Rendered only when the AC
+ * text carries the tag (per-tag lines) — untagged reviewer prompts are
+ * byte-for-byte what they always were. `[ci]` is judged by the PR check
+ * status in the evidence, never by local runs; an `[operator]` criterion is
+ * gated by Dealer and missing operator evidence is never a defect (the
+ * probe/doc existence check lives in `operatorReviewerSection` and is not
+ * duplicated here).
+ */
+function tagSemanticsReviewerSection(acceptanceCriteria) {
+    const lines = [];
+    if (acceptanceCriteriaHasTag(acceptanceCriteria, "[ci]")) {
+        lines.push(`- Judge \`[ci]\` criteria by the PR check status in the evidence (the CI checks section), not by local runs.`);
+    }
+    if (acceptanceCriteriaHasTag(acceptanceCriteria, "[operator]")) {
+        lines.push(`- Do not mark an \`[operator]\` criterion as a defect — it is gated by Dealer.`);
+    }
+    if (!lines.length)
+        return [];
+    return [`## Criterion tags ([ci] / [operator]) — how to judge`, ...lines, ``];
+}
 /** NOT-272: a resolved product_scope_decision's human note, verbatim. Empty/absent
  * renders nothing so noteless resolves produce byte-for-byte the prompt they always did. */
 function scopeDecisionSection(note) {
@@ -140,7 +249,18 @@ export function buildDeveloperPrompt(input) {
     parts.push(...conflictRepairSection(input.conflictRepair));
     // NOT-272: the scope decision leads — the developer reads it before the task itself.
     parts.push(...scopeDecisionSection(input.scopeDecisionNote));
-    parts.push(`## Task`, input.taskSnapshot.title, input.taskSnapshot.description, ``, `## Acceptance criteria`, input.taskSnapshot.acceptanceCriteria, ``, ...executionContractSection(input.taskSnapshot.executionContract));
+    // NOT-314: operator repair feedback leads for the same reason.
+    parts.push(...operatorRepairSection(input.operatorRepairNote));
+    parts.push(`## Task`, input.taskSnapshot.title, input.taskSnapshot.description, ``, `## Acceptance criteria`, input.taskSnapshot.acceptanceCriteria, ``, 
+    // NOT-314: operator criteria render separately right after the criteria —
+    // the worker must not attempt them, only ship the probe + doc.
+    ...operatorDeveloperSection(input.operatorCriteria), 
+    // NOT-316: tag semantics render only for Muse developers whose AC text
+    // carries the tags — otherwise nothing, so untagged and non-Muse prompts
+    // stay byte-for-byte.
+    ...(input.museDeveloper
+        ? tagSemanticsDeveloperSection(input.taskSnapshot.acceptanceCriteria)
+        : []), ...executionContractSection(input.taskSnapshot.executionContract));
     if (input.findings?.length) {
         parts.push(`## Findings to address`);
         for (const f of input.findings) {
@@ -153,6 +273,10 @@ export function buildDeveloperPrompt(input) {
     parts.push(...agentDeckSection(input.worktreePath, input.deckId));
     if (input.museDeveloper)
         parts.push(...museCronProhibitionSection());
+    // NOT-316: sandbox limits rendered from MUSE_SANDBOX_CAPABILITIES — Muse
+    // developers only, so non-Muse prompts are untouched.
+    if (input.museDeveloper)
+        parts.push(...museEnvironmentLimitsSection());
     // NOT-303: the screenshot-path preflight verdict is embedded before the session
     // starts, so the worker reads it instead of discovering the Chrome.app abort
     // mid-session. Non-Muse developers are untouched.
@@ -160,6 +284,9 @@ export function buildDeveloperPrompt(input) {
         parts.push(...museVisualQaPromptSection(input.museVisualQa ?? checkMuseVisualQa()));
     }
     parts.push(`## Required`, 
+    // NOT-315: the coordinator provisions dependencies before the session spawns —
+    // the sandbox has no network, so an in-session install can never work.
+    `Dependencies are installed; do not run npm install (no network).`, 
     // NOT-115: encourage incremental commits so a mid-session death leaves less
     // uncommitted work for dirty_worktree escalation — soft mitigation only.
     // NOT-146: timed-spawn handoff bar is commits + targeted tests for the change.
@@ -251,6 +378,12 @@ export function buildReviewerPrompt(input) {
         `## Acceptance criteria`,
         input.taskSnapshot.acceptanceCriteria,
         ``,
+        // NOT-314: missing operator evidence is NOT a defect — but the probe and
+        // doc must exist. Only rendered when the snapshot carries operator criteria.
+        ...operatorReviewerSection(input.operatorCriteria),
+        // NOT-316: tagged-criterion judging lines — only when the AC text carries
+        // the tags, so untagged reviewer prompts stay byte-for-byte.
+        ...tagSemanticsReviewerSection(input.taskSnapshot.acceptanceCriteria),
         ...executionContractSection(input.taskSnapshot.executionContract),
         `## Diff (base ${input.baseSha.slice(0, 8)} → head ${input.headSha.slice(0, 8)})`,
         "```diff",

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

@@ -335,3 +335,151 @@ test("NOT-310: no conflict directive produces byte-for-byte the same prompt as b
     assert.equal(buildDeveloperPrompt({ ...base, conflictRepair: undefined }), without);
     assert.equal(buildDeveloperPrompt({ ...base, conflictRepair: { baseBranch: "", branch: "", files: [] } }), without);
 });
+// NOT-314: the developer prompt lists operator criteria separately — the worker
+// ships the probe + doc and never attempts the criterion itself.
+test("NOT-314: developer prompt lists operator criteria with the do-not-attempt instruction", () => {
+    const prompt = buildDeveloperPrompt({
+        taskSnapshot,
+        round: 1,
+        operatorCriteria: [
+            {
+                text: "Operator can sign in with SSO and see the org dashboard [operator]",
+                commands: ["`npm run probe:sso -- --env staging`"],
+            },
+        ],
+    });
+    assert.match(prompt, /## Operator verification required/);
+    assert.match(prompt, /Do not attempt these; ship the ready-to-run probe and a doc, put the exact command in the PR body/);
+    assert.match(prompt, /sign in with SSO/);
+    assert.match(prompt, /npm run probe:sso -- --env staging/);
+});
+test("NOT-314: no operator criteria produces byte-for-byte the same developer prompt as before", () => {
+    const base = { taskSnapshot, round: 2 };
+    const without = buildDeveloperPrompt(base);
+    assert.doesNotMatch(without, /## Operator verification/);
+    assert.equal(buildDeveloperPrompt({ ...base, operatorCriteria: undefined }), without);
+    assert.equal(buildDeveloperPrompt({ ...base, operatorCriteria: [] }), without);
+});
+test("NOT-314: operator repair note renders verbatim under its own heading before the task", () => {
+    const note = "The probe 404s — its path moved; fix the script and the doc.";
+    const prompt = buildDeveloperPrompt({ taskSnapshot, round: 2, operatorRepairNote: note });
+    assert.match(prompt, /## Operator verification feedback/);
+    assert.ok(prompt.includes(note), "note text must appear verbatim");
+    assert.ok(prompt.indexOf("## Operator verification feedback") < prompt.indexOf("## Task"), "repair feedback must precede the task");
+    const without = buildDeveloperPrompt({ taskSnapshot, round: 2 });
+    assert.doesNotMatch(without, /## Operator verification feedback/);
+    assert.equal(buildDeveloperPrompt({ taskSnapshot, round: 2, operatorRepairNote: "  " }), without);
+});
+// NOT-314: the reviewer must not flag missing operator evidence — Dealer gates
+// the merge — but the probe and doc must exist.
+test("NOT-314: reviewer prompt states missing operator evidence is not a defect, probe and doc must exist", () => {
+    const prompt = buildReviewerPrompt({
+        ...reviewerBase,
+        operatorCriteria: [
+            {
+                text: "Operator can complete a paid checkout [operator]",
+                commands: ["`npm run probe:checkout -- --env staging`"],
+            },
+        ],
+    });
+    assert.match(prompt, /## Operator-gated criteria/);
+    assert.match(prompt, /Missing operator evidence is NOT a defect/);
+    assert.match(prompt, /never raise a blocking finding/);
+    assert.match(prompt, /probe and doc/);
+    assert.match(prompt, /A missing probe or doc IS a blocking finding/);
+    assert.match(prompt, /paid checkout/);
+    assert.match(prompt, /npm run probe:checkout/);
+});
+test("NOT-314: no operator criteria produces byte-for-byte the same reviewer prompt as before", () => {
+    const without = buildReviewerPrompt(reviewerBase);
+    assert.doesNotMatch(without, /Operator-gated criteria/);
+    assert.equal(buildReviewerPrompt({ ...reviewerBase, operatorCriteria: undefined }), without);
+    assert.equal(buildReviewerPrompt({ ...reviewerBase, operatorCriteria: [] }), without);
+});
+// NOT-315: dependencies arrive installed (coordinator-side `npm ci`); the sandbox has
+// no network, so the worker must never try to install them itself.
+test("NOT-315: developer prompt tells the worker dependencies are installed and not to run npm install", () => {
+    for (const round of [1, 2]) {
+        const prompt = buildDeveloperPrompt({ taskSnapshot, round });
+        assert.match(prompt, /Dependencies are installed; do not run npm install \(no network\)\./);
+    }
+    const retry = buildDeveloperPrompt({ taskSnapshot, round: 1, retryReason: "Developer session failed or crashed." });
+    assert.match(retry, /Dependencies are installed; do not run npm install \(no network\)\./);
+});
+// NOT-316: a Muse developer learns the sandbox limits from its prompt — the
+// section is rendered from MUSE_SANDBOX_CAPABILITIES, not hand-written prose.
+// Other runtimes are unchanged.
+test("NOT-316: museDeveloper prompt contains the Environment limits section; other runtimes do not", async () => {
+    const { MUSE_SANDBOX_CAPABILITIES } = await import("../runners/muse-code-args.js");
+    const muse = buildDeveloperPrompt({ taskSnapshot, round: 1, museDeveloper: true });
+    assert.match(muse, /## Environment limits/);
+    assert.ok(muse.includes(`sandbox network: ${MUSE_SANDBOX_CAPABILITIES.sandboxNetwork}`), "section header names the sandbox-network value from the constant");
+    assert.ok(muse.includes(`Network: ${MUSE_SANDBOX_CAPABILITIES.network}`), "network limit comes from the constant");
+    assert.match(muse, /listen.*EPERM/i);
+    assert.match(muse, /Browser: no/);
+    assert.match(muse, /Credentials\/Keychain: no/);
+    assert.match(muse, /After one failed attempt.*stop and hand off; do not work around the sandbox\./);
+    const other = buildDeveloperPrompt({ taskSnapshot, round: 1 });
+    assert.doesNotMatch(other, /## Environment limits/);
+    assert.doesNotMatch(other, /do not work around the sandbox/);
+});
+// NOT-316: tag semantics appear only when the AC text carries the tags, per
+// tag, and only for Muse developers — an untagged ticket's prompt carries no
+// tag section at all.
+test("NOT-316: developer tag semantics render per tag only for a Muse developer with tagged ACs", () => {
+    const taggedBoth = {
+        ...taskSnapshot,
+        acceptanceCriteria: "- [ ] [agent] Widget renders in the preview.\n- [ ] [ci] Extend the `verify` workflow for widgets.",
+    };
+    const museBoth = buildDeveloperPrompt({ taskSnapshot: taggedBoth, round: 1, museDeveloper: true });
+    assert.match(museBoth, /## Acceptance-criterion tags/);
+    assert.match(museBoth, /`\[agent\]`: verify yourself/);
+    assert.match(museBoth, /`\[ci\]`: implement or extend the named CI job\/test and push/);
+    assert.match(museBoth, /CI is the evidence, do not reproduce it locally/);
+    const agentOnly = buildDeveloperPrompt({
+        taskSnapshot: { ...taskSnapshot, acceptanceCriteria: "- [ ] [agent] Widget renders." },
+        round: 1,
+        museDeveloper: true,
+    });
+    assert.match(agentOnly, /`\[agent\]`: verify yourself/);
+    assert.doesNotMatch(agentOnly, /`\[ci\]`: implement or extend/);
+    const ciOnly = buildDeveloperPrompt({
+        taskSnapshot: { ...taskSnapshot, acceptanceCriteria: "- [ ] [ci] Extend the `verify` workflow." },
+        round: 1,
+        museDeveloper: true,
+    });
+    assert.match(ciOnly, /`\[ci\]`: implement or extend the named CI job\/test and push/);
+    assert.doesNotMatch(ciOnly, /`\[agent\]`: verify yourself/);
+    // Untagged Muse prompt: no tag section — snapshot-style byte check that the
+    // tag feature adds nothing beyond the section itself.
+    const untaggedMuse = buildDeveloperPrompt({ taskSnapshot, round: 1, museDeveloper: true });
+    assert.doesNotMatch(untaggedMuse, /## Acceptance-criterion tags/);
+    assert.doesNotMatch(untaggedMuse, /`\[agent\]`: verify yourself/);
+    assert.doesNotMatch(untaggedMuse, /`\[ci\]`: implement or extend/);
+    assert.equal(buildDeveloperPrompt({ taskSnapshot, round: 1, museDeveloper: true }), untaggedMuse);
+    // Non-Muse prompts never carry tag semantics, even with tagged ACs.
+    const otherTagged = buildDeveloperPrompt({ taskSnapshot: taggedBoth, round: 1 });
+    assert.doesNotMatch(otherTagged, /## Acceptance-criterion tags/);
+    assert.doesNotMatch(otherTagged, /## Environment limits/);
+});
+// NOT-316: the reviewer judges [ci] by the PR check status and never flags a
+// missing [operator] result as a defect.
+test("NOT-316: reviewer prompt judges [ci] by check status and never defects [operator]", () => {
+    const tagged = buildReviewerPrompt({
+        ...reviewerBase,
+        taskSnapshot: {
+            ...taskSnapshot,
+            acceptanceCriteria: "- [ ] [ci] The `verify` workflow covers widgets.\n- [ ] [operator] Operator completes a paid checkout.",
+        },
+    });
+    assert.match(tagged, /## Criterion tags/);
+    assert.match(tagged, /Judge `\[ci\]` criteria by the PR check status in the evidence/);
+    assert.match(tagged, /not by local runs/);
+    assert.match(tagged, /Do not mark an `\[operator\]` criterion as a defect/);
+    assert.match(tagged, /gated by Dealer/);
+});
+test("NOT-316: untagged reviewer prompt carries no tag-judging section", () => {
+    const without = buildReviewerPrompt(reviewerBase);
+    assert.doesNotMatch(without, /## Criterion tags/);
+    assert.equal(buildReviewerPrompt(reviewerBase), without);
+});

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

@@ -26,23 +26,72 @@
 // effect; and one item that fails to route never rolls back the others.
 import { canTransitionIssue } from "@agent-dealer/shared";
 import { getDb } from "../db/index.js";
-import { getIssue, incrementIssueInfraAttempts, transitionIssue } from "../repository/issues.js";
+import { getIssue, incrementIssueInfraAttempts, listIssues, transitionIssue } from "../repository/issues.js";
 import { appendWorkflowEvent, getActiveWorkflowInstance } from "../repository/workflow-events.js";
 import { completeSession, getWorkerSession } from "../repository/worker-sessions.js";
 import { runtimeAvailability } from "../repository/runtime-availability.js";
-import { deferWorkItem, finishWorkItem, listExpiredLeases, refreshHeartbeat, requeueWorkItem, } from "../repository/work-items.js";
+import { deferWorkItem, enqueueWorkItem, finishWorkItem, listExpiredLeases, listWorkItemsForIssue, refreshHeartbeat, requeueWorkItem, } from "../repository/work-items.js";
 import { infraAttemptsRemain } from "./routing.js";
 import { activeClockJumpGrace } from "./clock-jump.js";
 import { inspectWorkerProcess, terminateWorkerProcess } from "./process-liveness.js";
 import { maxAliveHoldMsFor } from "./session-timeouts.js";
 import { emitHostSuspended } from "./agent-boundaries.js";
-import { routeAppliedOutcome } from "./commands.js";
+import { queuedProfileSnapshot, routeAppliedOutcome } from "./commands.js";
 import { recoverStrandedAutoMerges } from "./auto-merge.js";
 import { workerSessionPayload } from "./session-progress.js";
 import { PRESUMED_DEAD_REASON, presumedDeadReclaimReason } from "./failure-reason.js";
 import { recordCausesForWorkerFailedEvent } from "./failure-cause.js";
 import { baseRefCandidates, developerBranchName, hasPublishableWork, inspectBranchProgress, } from "./branch-progress.js";
 const num = (name, dflt) => Number(process.env[name] ?? dflt);
+/**
+ * NOT-333: an issue parked in `reviewing` with an open workflow instance but no
+ * pending/leased work item is stranded — nothing will ever claim it (the NOT-200
+ * shape: a resume round that pushed nothing deduped its reviewer enqueue against the
+ * already-terminal reviewer row). Re-enqueue one reviewer round at the current head.
+ *
+ * Bounded by construction: the fresh pending row makes the very next pass a no-op, so
+ * this fires at most once per stranding. Item history is required — reaching
+ * `reviewing` always enqueues a reviewer, so a bare row with no work items at all has
+ * nothing to resume and is left alone.
+ */
+export function recoverStrandedReviewing() {
+    const recovered = [];
+    for (const issue of listIssues("reviewing")) {
+        const instance = getActiveWorkflowInstance(issue.id);
+        if (!instance)
+            continue;
+        const items = listWorkItemsForIssue(issue.id);
+        if (items.length === 0)
+            continue;
+        if (items.some((w) => w.status === "pending" || w.status === "leased"))
+            continue;
+        const headSha = issue.headSha ?? null;
+        const baseKey = `${instance.id}:reviewer:${issue.currentRound}${headSha ? `:${headSha}` : ""}:stranded-recovery`;
+        const taken = new Set(items.map((w) => w.idempotencyKey));
+        let key = baseKey;
+        for (let n = 2; taken.has(key); n++)
+            key = `${baseKey}:${n}`;
+        console.warn("[coordinator] issue stranded in reviewing with no active work — re-enqueueing reviewer", {
+            issueId: issue.id,
+            workflowInstanceId: instance.id,
+            round: issue.currentRound,
+            headSha,
+        });
+        const next = enqueueWorkItem({
+            issueId: issue.id,
+            workflowInstanceId: instance.id,
+            kind: "reviewer",
+            round: issue.currentRound,
+            payload: {
+                ...(headSha ? { inputSha: headSha } : {}),
+                profileSnapshot: queuedProfileSnapshot(issue, "reviewer"),
+            },
+            idempotencyKey: key,
+        });
+        recovered.push(next.id);
+    }
+    return recovered;
+}
 /** Fail a worker_session still `running` for an item whose worker is gone. */
 function failOrphanSession(workerSessionId) {
     if (!workerSessionId)
@@ -489,6 +538,10 @@ export async function recoverCoordinator(opts) {
         console.warn(`[coordinator] ${republished.length} reclaim(s) routed to republish — branch already had commits, no new agent session`, { workItemIds: republished });
     }
     const stranded = await recoverStrandedAutoMerges();
+    // NOT-333: re-enqueue a reviewer for issues stranded in `reviewing` with no active
+    // work (runs every tick alongside the lease reclaim above — the fresh pending row
+    // makes the next pass a no-op, so this recovers exactly once per stranding).
+    const strandedReviewingRecovered = recoverStrandedReviewing();
     return {
         reclaimed,
         republished,
@@ -499,5 +552,6 @@ export async function recoverCoordinator(opts) {
         unverifiedOrphans,
         heldAcrossClockJump,
         autoMergesFinalized: stranded.finalized,
+        strandedReviewingRecovered,
     };
 }

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

@@ -9,10 +9,11 @@ process.env.MAX_COORDINATOR_CONCURRENCY = "2";
 process.env.COORDINATOR_FAIL_BACKOFF_MS = "0";
 const { migrate, getDb } = await import("../db/index.js");
 const { BUILTIN_AGENT_CLAUDE_ID, BUILTIN_AGENT_CURSOR_ID } = await import("@agent-dealer/shared");
-const { createIssue, getIssue } = await import("../repository/issues.js");
+const { createIssue, getIssue, transitionIssue } = await import("../repository/issues.js");
+const { getActiveWorkflowInstance } = await import("../repository/workflow-events.js");
 const { listHumanActionsForIssue } = await import("../repository/human-actions.js");
 const { listWorkerSessionsForIssue, createWorkerSession, startSession } = await import("../repository/worker-sessions.js");
-const { getWorkItem, listWorkItemsForIssue, claimWorkItem, bindWorkItemSession, finishWorkItem, refreshHeartbeat } = await import("../repository/work-items.js");
+const { getWorkItem, listWorkItemsForIssue, claimWorkItem, bindWorkItemSession, enqueueWorkItem, finishWorkItem, refreshHeartbeat } = await import("../repository/work-items.js");
 const { startWorkflow } = await import("./commands.js");
 const { recoverCoordinator } = await import("./recovery.js");
 const FUTURE = () => Date.now() + 3_600_000; // a clock well past any test lease
@@ -126,7 +127,7 @@ test("recovery ignores a lease that has not expired", async () => {
     const issueId = newIssue();
     startWorkflow(issueId);
     claimWorkItem("healthy", { leaseMs: 600_000 });
-    assert.deepEqual(await recoverCoordinator({ now: Date.now() }), { reclaimed: [], republished: [], deadLettered: [], deferredForCap: [], heldAlive: [], heldAliveExpired: [], unverifiedOrphans: [], heldAcrossClockJump: [], autoMergesFinalized: [] });
+    assert.deepEqual(await recoverCoordinator({ now: Date.now() }), { reclaimed: [], republished: [], deadLettered: [], deferredForCap: [], heldAlive: [], heldAliveExpired: [], unverifiedOrphans: [], heldAcrossClockJump: [], autoMergesFinalized: [], strandedReviewingRecovered: [] });
 });
 test("recovery leaves a lease alone when a heartbeat renewed it after the snapshot", async () => {
     // Regression for the reviewer's "recovery can reclaim a freshly renewed lease".
@@ -138,7 +139,7 @@ test("recovery leaves a lease alone when a heartbeat renewed it after the snapsh
     // …but before its CAS runs, the worker heartbeats and renews the lease:
     refreshHeartbeat(devItem.id, claimed.leaseToken, { leaseMs: 600_000 });
     const res = await recoverCoordinator({ now: Date.now() + 1_000 });
-    assert.deepEqual(res, { reclaimed: [], republished: [], deadLettered: [], deferredForCap: [], heldAlive: [], heldAliveExpired: [], unverifiedOrphans: [], heldAcrossClockJump: [], autoMergesFinalized: [] });
+    assert.deepEqual(res, { reclaimed: [], republished: [], deadLettered: [], deferredForCap: [], heldAlive: [], heldAliveExpired: [], unverifiedOrphans: [], heldAcrossClockJump: [], autoMergesFinalized: [], strandedReviewingRecovered: [] });
     assert.equal(getWorkItem(devItem.id).status, "leased");
 });
 test("an expired lease past the infra-attempt limit is dead-lettered AND routed in one step", async () => {
@@ -162,7 +163,7 @@ test("an expired lease past the infra-attempt limit is dead-lettered AND routed
     const last = JSON.parse(failed[failed.length - 1].payloadJson);
     assert.match(last.reason ?? "", /presumed dead/);
     // A second recovery pass is a no-op — the item is already dead, nothing to reclaim.
-    assert.deepEqual(await recoverCoordinator({ now: FUTURE() }), { reclaimed: [], republished: [], deadLettered: [], deferredForCap: [], heldAlive: [], heldAliveExpired: [], unverifiedOrphans: [], heldAcrossClockJump: [], autoMergesFinalized: [] });
+    assert.deepEqual(await recoverCoordinator({ now: FUTURE() }), { reclaimed: [], republished: [], deadLettered: [], deferredForCap: [], heldAlive: [], heldAliveExpired: [], unverifiedOrphans: [], heldAcrossClockJump: [], autoMergesFinalized: [], strandedReviewingRecovered: [] });
     assert.equal(listHumanActionsForIssue(issueId).filter((a) => a.status === "open").length, 1, "no duplicate human action from a second recovery");
 });
 test("recovery loses its CAS to a worker that completed concurrently", async () => {
@@ -172,7 +173,7 @@ test("recovery loses its CAS to a worker that completed concurrently", async ()
     const claimed = claimWorkItem("o", { leaseMs: 1 });
     // Worker finishes just before recovery's transaction runs.
     finishWorkItem(devItem.id, claimed.leaseToken, { status: "done", result: { kind: "no_pr" } });
-    assert.deepEqual(await recoverCoordinator({ now: FUTURE() }), { reclaimed: [], republished: [], deadLettered: [], deferredForCap: [], heldAlive: [], heldAliveExpired: [], unverifiedOrphans: [], heldAcrossClockJump: [], autoMergesFinalized: [] });
+    assert.deepEqual(await recoverCoordinator({ now: FUTURE() }), { reclaimed: [], republished: [], deadLettered: [], deferredForCap: [], heldAlive: [], heldAliveExpired: [], unverifiedOrphans: [], heldAcrossClockJump: [], autoMergesFinalized: [], strandedReviewingRecovered: [] });
     assert.equal(getWorkItem(devItem.id).status, "done");
 });
 test("an expired lease on a usage-capped runtime is deferred, not dead-lettered (NOT-111 recovery gap)", async () => {
@@ -210,7 +211,8 @@ test("an expired lease on a usage-capped runtime is deferred, not dead-lettered
             heldAliveExpired: [],
             unverifiedOrphans: [],
             heldAcrossClockJump: [],
-            autoMergesFinalized: []
+            autoMergesFinalized: [],
+            strandedReviewingRecovered: []
         });
         assert.equal(getWorkItem(devItem.id).status, "pending");
         assert.equal(getWorkItem(devItem.id).attemptCount, 0, "claim's attempt bump is reverted, like a live cap deferral");
@@ -223,5 +225,62 @@ test("an expired lease on a usage-capped runtime is deferred, not dead-lettered
     }
 });
 test("recoverCoordinator is a no-op on a clean queue", async () => {
-    assert.deepEqual(await recoverCoordinator({ now: FUTURE() }), { reclaimed: [], republished: [], deadLettered: [], deferredForCap: [], heldAlive: [], heldAliveExpired: [], unverifiedOrphans: [], heldAcrossClockJump: [], autoMergesFinalized: [] });
+    assert.deepEqual(await recoverCoordinator({ now: FUTURE() }), { reclaimed: [], republished: [], deadLettered: [], deferredForCap: [], heldAlive: [], heldAliveExpired: [], unverifiedOrphans: [], heldAcrossClockJump: [], autoMergesFinalized: [], strandedReviewingRecovered: [] });
+});
+/** Settles an issue's developer round so the test can park the issue in `reviewing`. */
+function settleDeveloper(issueId) {
+    const dev = claimWorkItem(`seed-${issueId}`, { leaseMs: 600_000 });
+    assert.equal(dev.issueId, issueId);
+    assert.equal(finishWorkItem(dev.id, dev.leaseToken, { status: "done", result: { kind: "no_pr" } }).status, "done");
+}
+test("NOT-333: recovery re-enqueues exactly once for an issue stranded in reviewing, and is a no-op otherwise", async () => {
+    // The NOT-200 stranding: reviewing, open instance, head pinned, but every work
+    // item terminal — the resume round's reviewer enqueue deduped against the done row.
+    const strandedId = newIssue();
+    startWorkflow(strandedId);
+    settleDeveloper(strandedId);
+    transitionIssue(strandedId, "reviewing", { headSha: "abc123" });
+    const instance = getActiveWorkflowInstance(strandedId);
+    const oldReviewer = enqueueWorkItem({
+        issueId: strandedId,
+        workflowInstanceId: instance.id,
+        kind: "reviewer",
+        round: 1,
+        payload: { inputSha: "abc123" },
+        idempotencyKey: `${instance.id}:reviewer:1:abc123`,
+    });
+    const leasedOld = claimWorkItem(`seed-rev-${strandedId}`, { leaseMs: 600_000 });
+    assert.equal(leasedOld.id, oldReviewer.id);
+    assert.equal(finishWorkItem(oldReviewer.id, leasedOld.leaseToken, { status: "done", result: { kind: "verdict" } }).status, "done");
+    // A healthy issue: reviewing WITH a pending reviewer must be left alone.
+    const healthyId = newIssue();
+    startWorkflow(healthyId);
+    settleDeveloper(healthyId);
+    transitionIssue(healthyId, "reviewing", { headSha: "def456" });
+    const healthyInstance = getActiveWorkflowInstance(healthyId);
+    const healthyReviewer = enqueueWorkItem({
+        issueId: healthyId,
+        workflowInstanceId: healthyInstance.id,
+        kind: "reviewer",
+        round: 1,
+        payload: { inputSha: "def456" },
+        idempotencyKey: `${healthyInstance.id}:reviewer:1:def456`,
+    });
+    // First tick recovers the stranded issue exactly once.
+    const first = await recoverCoordinator({ now: Date.now() });
+    assert.equal(first.strandedReviewingRecovered.length, 1);
+    const recovered = getWorkItem(first.strandedReviewingRecovered[0]);
+    assert.equal(recovered.issueId, strandedId);
+    assert.equal(recovered.kind, "reviewer");
+    assert.equal(recovered.status, "pending");
+    assert.notEqual(recovered.id, oldReviewer.id);
+    assert.equal(JSON.parse(recovered.payloadJson).inputSha, "abc123");
+    // ...and touches nothing else.
+    assert.equal(listWorkItemsForIssue(healthyId).length, 2);
+    assert.equal(getWorkItem(healthyReviewer.id).status, "pending");
+    // Second tick is a no-op — the fresh pending row bounds the guard, no loop.
+    const second = await recoverCoordinator({ now: Date.now() });
+    assert.deepEqual(second.strandedReviewingRecovered, []);
+    assert.equal(listWorkItemsForIssue(strandedId).filter((i) => i.kind === "reviewer").length, 2);
+    assert.equal(listWorkItemsForIssue(strandedId).filter((i) => i.kind === "reviewer" && i.status === "pending").length, 1);
 });

package/bundle/server/dist/coordinator/repair-cycle.integration.test.js

@@ -197,6 +197,7 @@ test("developer round 1 → reviewer changes_requested → developer round 2 on
     assert.equal(issue.status, "final_review", "the cycle must end at a human final_review, not stuck or escalated");
     assert.equal(issue.currentRound, 2, "exactly one genuine repair round — changes_requested — was spent");
     assert.equal(issue.infraAttempts, 0, "nothing in this run was an infra failure");
+    assert.equal(issue.ciAttempts, 0, "nothing in this run was a CI failure either");
     assert.ok(listHumanActionsForIssue(issueId).find((a) => a.actionType === "final_review" && a.status === "open"));
     // Same branch reused across both rounds — never re-created.
     const branch = issueBranchName(issueId);

package/bundle/server/dist/coordinator/reviewer-effect.js

@@ -26,6 +26,7 @@ import os from "node:os";
 import path from "node:path";
 import { parseProfileSnapshot, roleCeiling } from "@agent-dealer/shared";
 import { getTaskSnapshot } from "./commands.js";
+import { extractOperatorCriteria } from "./operator-criteria.js";
 import { buildReviewerPrompt, formatDiffForPrompt, TOTAL_DIFF_LIMIT } from "./prompts.js";
 import { guidanceForNextSession } from "./guidance.js";
 import { realReviewerSpawn, reviewerSessionLogPath } from "./spawn.js";
@@ -336,6 +337,10 @@ export async function runReviewerEffect(ctx, deps = defaultDeps) {
             const { truncated: diffTruncated, omittedPaths } = formatDiffForPrompt(diff);
             const openFindings = listFindingsForIssue(issue.id).filter((f) => f.status === "open" || f.status === "recurring");
             const guidance = guidanceForNextSession(issue.id, sessionId);
+            // NOT-314: the frozen snapshot's operator criteria — the reviewer must not
+            // treat missing operator evidence as a defect (Dealer gates the merge), but
+            // the probe and doc must exist. Rendered only when non-empty.
+            const operatorCriteria = extractOperatorCriteria(taskSnapshot.acceptanceCriteria);
             const prompt = buildReviewerPrompt({
                 taskSnapshot,
                 round: workItem.round,
@@ -348,6 +353,7 @@ export async function runReviewerEffect(ctx, deps = defaultDeps) {
                 worktreePath,
                 deckId: snapshot?.deckId ?? null,
                 guidance: guidance.length ? guidance : undefined,
+                operatorCriteria: operatorCriteria.length > 0 ? operatorCriteria : undefined,
             });
             // NOT-83 review finding — see developer-effect.ts's identical check for the full
             // rationale: re-verify this item is still leased right before the real spawn, since an