agent-dealer 1.2.7 → 1.2.9

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

@@ -248,7 +248,238 @@ test("NOT-278: a non-Muse developer prompt has the deck bootstrap but no cron pr
     assert.match(prompt, /bind_workspace/);
     assert.doesNotMatch(prompt, /cron_create/);
 });
+// NOT-303: a Muse developer prompt carries the screenshot-path preflight verdict.
+// Default (no headless shell installed): unusable, naming the Chrome.app abort and
+// requiring an explicit `Visual QA: not run` conclusion line — never sandbox
+// widening. Env is scrubbed so the test is hermetic.
+test("NOT-303: museDeveloper prompt carries the visual-QA preflight (unusable by default)", () => {
+    const saved = process.env.MUSE_HEADLESS_SHELL_BIN;
+    delete process.env.MUSE_HEADLESS_SHELL_BIN;
+    try {
+        const prompt = buildDeveloperPrompt({ taskSnapshot, round: 1, deckId: "deck-1", worktreePath: "/wt", museDeveloper: true });
+        assert.match(prompt, /## Visual QA/);
+        assert.match(prompt, /Google Chrome\.app/);
+        assert.match(prompt, /RegisterApplication/);
+        assert.match(prompt, /do not spend steps probing/i);
+        assert.match(prompt, /Visual QA: not run/);
+        assert.doesNotMatch(prompt, /--disable-sandbox/);
+        assert.doesNotMatch(prompt, /--yolo/);
+    }
+    finally {
+        if (saved !== undefined)
+            process.env.MUSE_HEADLESS_SHELL_BIN = saved;
+    }
+});
+test("NOT-303: museDeveloper prompt names the pre-installed headless shell when injected", () => {
+    const prompt = buildDeveloperPrompt({
+        taskSnapshot,
+        round: 1,
+        deckId: "deck-1",
+        worktreePath: "/wt",
+        museDeveloper: true,
+        museVisualQa: {
+            usable: true,
+            binary: "/opt/headless/chrome-headless-shell",
+            args: ["--screenshot=<png>", "--window-size=1280,800"],
+            reason: "pre-installed headless shell",
+        },
+    });
+    assert.match(prompt, /\/opt\/headless\/chrome-headless-shell/);
+    assert.match(prompt, /--screenshot=<png>/);
+    assert.match(prompt, /Google Chrome\.app/);
+});
+test("NOT-303: a non-Muse developer prompt has no visual-QA section", () => {
+    const prompt = buildDeveloperPrompt({ taskSnapshot, round: 1, deckId: "deck-1", worktreePath: "/wt" });
+    assert.doesNotMatch(prompt, /## Visual QA/);
+});
+test("NOT-303: reviewer prompt states a missing screenshot is never a pass", () => {
+    const prompt = buildReviewerPrompt(reviewerBase);
+    assert.match(prompt, /missing screenshot/i);
+    assert.match(prompt, /visual QA not run/);
+    assert.match(prompt, /do not read the absence as a pass/);
+});
 test("a deckless developer prompt still fails closed", () => {
     const prompt = buildDeveloperPrompt({ taskSnapshot, round: 1, deckId: null });
     assert.match(prompt, /misconfigured: Agent Deck is required but missing/);
 });
+// NOT-310: the conflict-repair directive renders the base, the branch, and the
+// conflicting files first — the developer merges the base before any other work.
+test("NOT-310: conflict repair directive renders base, branch, and files before the task", () => {
+    const prompt = buildDeveloperPrompt({
+        taskSnapshot,
+        round: 3,
+        conflictRepair: { baseBranch: "main", branch: "issue-9", files: ["a.ts", "b.ts"] },
+    });
+    assert.match(prompt, /## Merge conflict with main/);
+    assert.ok(prompt.includes("`issue-9`"), "branch must be named");
+    assert.ok(prompt.includes("`a.ts`") && prompt.includes("`b.ts`"), "files must be named");
+    assert.ok(prompt.includes("git fetch origin main"), "must fetch the base");
+    assert.ok(prompt.includes("git merge origin/main"), "must merge the base");
+    assert.match(prompt, /never force-push/i);
+    assert.match(prompt, /never rebase/i);
+    assert.ok(prompt.indexOf("## Merge conflict") < prompt.indexOf("## Task"), "conflict section must precede the task");
+});
+test("NOT-310: unknown conflicting files render the discover-from-merge instruction", () => {
+    const prompt = buildDeveloperPrompt({
+        taskSnapshot,
+        round: 2,
+        conflictRepair: { baseBranch: "main", branch: "issue-9", files: [] },
+    });
+    assert.match(prompt, /## Merge conflict with main/);
+    assert.match(prompt, /conflicting files are unknown/);
+});
+test("NOT-310: no conflict directive produces byte-for-byte the same prompt as before", () => {
+    const base = { taskSnapshot, round: 2 };
+    const without = buildDeveloperPrompt(base);
+    assert.doesNotMatch(without, /## Merge conflict/);
+    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);
 });