agent-dealer 1.3.1 → 1.3.2

package/bundle/server/dist/coordinator/product-scope-contract.test.js

@@ -0,0 +1,249 @@
+// NOT-422: the NOT-405-like product-scope sequence end to end — reviewer
+// escalation → amended Linear ticket adopted at the pause → Resume → next
+// developer and reviewer enforce only the amended snapshot, on the same
+// workflow, PR, branch, and worktree.
+import { test, before, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-scope-contract-"));
+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 { startWorkflow, applyCompletion, applyParkedEdit, resolveHumanActionAndAdvance, getTaskSnapshot, diffTaskSnapshotFromLive, TASK_SNAPSHOT_ARTIFACT_KIND, } = await import("./commands.js");
+const { reloadIssueSourceFromLinear } = await import("./source-reload.js");
+const { claimWorkItem, listWorkItemsForIssue } = await import("../repository/work-items.js");
+const { listHumanActionsForIssue } = await import("../repository/human-actions.js");
+const { getActiveWorkflowInstance, listWorkflowEventsForIssue } = await import("../repository/workflow-events.js");
+const { listArtifactsForIssue } = await import("../repository/artifacts-for-issue.js");
+const { listWorkerSessionsForIssue } = await import("../repository/worker-sessions.js");
+const { ReviewerResult } = await import("./reviewer-result.js");
+const { buildDeveloperPrompt, buildReviewerPrompt } = await import("./prompts.js");
+const { stubManagedCloneForTests } = await import("../adapters/managed-repo.js");
+before(() => migrate());
+beforeEach(() => {
+    getDb().exec(`
+    DELETE FROM work_items;
+    DELETE FROM human_actions;
+    DELETE FROM workflow_events;
+    DELETE FROM worker_sessions;
+    DELETE FROM artifacts;
+    DELETE FROM workflow_instances;
+    DELETE FROM queue_entries;
+    DELETE FROM issues;
+  `);
+    stubManagedCloneForTests("acme/app");
+});
+// The ticket as frozen at workflow start: clean-machine proof is still an
+// [operator] criterion the reviewer escalates on.
+const CONTRACT_V1 = [
+    "Ship the friend-path run command.",
+    "",
+    "## Builder execution mode",
+    "feature",
+    "",
+    "## Non-goals",
+    "- Rewriting the installer",
+    "",
+    "## Exit predicate",
+    "The friend-path run command works on a clean machine with operator proof.",
+    "",
+    "## One-PR stopping point",
+    "Stop after the run command lands with its regression test.",
+    "",
+    "## Acceptance criteria",
+    "- [ ] Friend-path run works",
+    "  Evidence: run fixtures | run the tests | green",
+    "- [ ] [operator] Clean-machine proof attached",
+    "  Evidence: operator run | paste the output | reviewed",
+    "",
+].join("\n");
+// The amended ticket: clean-machine proof moved out, simulator proof in.
+const CONTRACT_V2 = [
+    "Ship the friend-path run command.",
+    "",
+    "## Builder execution mode",
+    "feature",
+    "",
+    "## Non-goals",
+    "- Rewriting the installer",
+    "",
+    "## Exit predicate",
+    "The friend-path run command works with simulator proof; clean-machine proof moved out.",
+    "",
+    "## One-PR stopping point",
+    "Stop after the run command lands with its regression test.",
+    "",
+    "## Acceptance criteria",
+    "- [ ] Friend-path run works",
+    "  Evidence: run fixtures | run the tests | green",
+    "- [ ] Simulator proof attached",
+    "  Evidence: simulator run | paste the output | reviewed",
+    "",
+].join("\n");
+const REMOVED_CRITERION = "[operator] Clean-machine proof attached";
+const AMENDED_EXIT = "The friend-path run command works with simulator proof; clean-machine proof moved out.";
+async function adoptViaReload(issueId) {
+    // The operator reloads the amended Linear ticket at the pause (injected
+    // fetch — no network; the CommonJS fetch mock lives in the route suites).
+    const reloaded = await reloadIssueSourceFromLinear(issueId, {
+        fetchLinearIssue: async (externalId) => ({
+            id: externalId,
+            identifier: "NOT-405",
+            title: "Friend-path run, rescoped",
+            description: CONTRACT_V2,
+            url: "https://linear.app/not-so-fat/issue/NOT-405/x",
+            attachments: [],
+        }),
+    });
+    assert.equal(reloaded.ok, true);
+}
+async function adoptViaLocalEdit(issueId) {
+    // The Dealer-local path: the same amended contract saved through the
+    // parked-edit surface instead of a Linear reload.
+    const { compileExecutionContract } = await import("@agent-dealer/shared");
+    const edited = applyParkedEdit(issueId, {
+        title: "NOT-405: friend-path run, rescoped",
+        description: CONTRACT_V2,
+        acceptanceCriteria: compileExecutionContract(CONTRACT_V2).acceptanceCriteria,
+    });
+    assert.equal(edited.ok, true);
+}
+async function runScopePauseAdoptionFlow(adopt) {
+    const issueId = createIssue({
+        title: "NOT-405: friend-path run",
+        description: CONTRACT_V1,
+        repo: "acme/app",
+        baseBranch: "main",
+        developerAgentId: BUILTIN_AGENT_CLAUDE_ID,
+        reviewerAgentId: BUILTIN_AGENT_CURSOR_ID,
+        source: "linear",
+        externalId: "linear-uuid-405",
+        externalLabel: "NOT-405",
+        externalUrl: "https://linear.app/not-so-fat/issue/NOT-405/x",
+    }).id;
+    assert.equal(startWorkflow(issueId).ok, true);
+    // Round 1: developer hands off, reviewer escalates a product-scope question.
+    const dev1 = claimWorkItem("scope-contract-test", { leaseMs: 60_000 });
+    await applyCompletion(dev1.id, dev1.leaseToken, {
+        kind: "clean_handoff",
+        branch: "dealer/not-405",
+        headSha: "abc123",
+        baseSha: "base1",
+        prNumber: 42,
+        prUrl: "https://gh/pr/42",
+    });
+    const rev1 = claimWorkItem("scope-contract-test", { leaseMs: 60_000 });
+    await applyCompletion(rev1.id, rev1.leaseToken, {
+        kind: "verdict",
+        result: ReviewerResult.parse({
+            verdict: "escalated",
+            productScopeQuestion: "Is clean-machine operator proof still required?",
+            baseSha: "b",
+            headSha: "h",
+            acceptanceCriteriaAssessment: "ok",
+            evidenceAssessment: "ok",
+            findings: [],
+            risks: [],
+        }),
+    });
+    const action = listHumanActionsForIssue(issueId).find((a) => a.actionType === "product_scope_decision");
+    const instanceBefore = getActiveWorkflowInstance(issueId);
+    const issueBefore = getIssue(issueId);
+    assert.equal(issueBefore.status, "needs_human");
+    // The frozen snapshot still enforces the old operator criterion.
+    assert.ok(getTaskSnapshot(issueBefore).acceptanceCriteria.includes(REMOVED_CRITERION));
+    // The operator adopts the amended contract at the pause — reload or local
+    // edit depending on the variant under test.
+    await adopt(issueId);
+    // The amended task is pending inspection: live rows changed, the open
+    // action and every workflow identity preserved, the snapshot untouched.
+    const parked = getIssue(issueId);
+    assert.equal(parked.description, CONTRACT_V2);
+    assert.equal(parked.executionContract?.exitPredicate, AMENDED_EXIT);
+    assert.equal(listHumanActionsForIssue(issueId).find((a) => a.id === action.id).status, "open");
+    assert.equal(getActiveWorkflowInstance(issueId).id, instanceBefore.id);
+    assert.equal(parked.prNumber, 42);
+    assert.equal(parked.branch, "dealer/not-405");
+    assert.ok(getTaskSnapshot(parked).acceptanceCriteria.includes(REMOVED_CRITERION));
+    assert.ok(diffTaskSnapshotFromLive(parked).length > 0);
+    // Resume freezes exactly one new snapshot before the next developer item.
+    const sessionsBeforeResume = listWorkerSessionsForIssue(issueId);
+    const snapshotsBefore = listArtifactsForIssue(issueId).filter((a) => a.kind === TASK_SNAPSHOT_ARTIFACT_KIND).length;
+    const resolved = resolveHumanActionAndAdvance(action.id, "operator", "resume", {
+        note: "Clean-machine proof moved to NOT-421; enforce simulator proof.",
+    });
+    assert.equal(resolved.ok, true);
+    const snapshotsAfter = listArtifactsForIssue(issueId).filter((a) => a.kind === TASK_SNAPSHOT_ARTIFACT_KIND);
+    assert.equal(snapshotsAfter.length, snapshotsBefore + 1);
+    const events = listWorkflowEventsForIssue(issueId);
+    const refreshed = events.filter((e) => e.type === "task_snapshot.refreshed");
+    assert.equal(refreshed.length, 1);
+    const types = events.map((e) => e.type);
+    assert.ok(types.indexOf("task_snapshot.refreshed") < types.lastIndexOf("repair.started"));
+    const resumed = getIssue(issueId);
+    assert.equal(getActiveWorkflowInstance(issueId).id, instanceBefore.id);
+    assert.equal(resumed.prNumber, issueBefore.prNumber);
+    assert.equal(resumed.prUrl, issueBefore.prUrl);
+    assert.equal(resumed.branch, issueBefore.branch);
+    assert.deepEqual(listWorkerSessionsForIssue(issueId), sessionsBeforeResume);
+    const pendingDev = listWorkItemsForIssue(issueId).filter((i) => i.status === "pending");
+    assert.equal(pendingDev.length, 1);
+    assert.equal(pendingDev[0].kind, "developer");
+    assert.equal(pendingDev[0].workflowInstanceId, instanceBefore.id);
+    const devPayload = JSON.parse(pendingDev[0].payloadJson);
+    assert.equal(devPayload.scopeDecisionNote, "Clean-machine proof moved to NOT-421; enforce simulator proof.");
+    // The next developer prompt — built the way the developer effect builds it,
+    // from this work item's own round and one-shot note over the frozen
+    // snapshot — enforces only the amended snapshot.
+    const developerPrompt = buildDeveloperPrompt({
+        taskSnapshot: getTaskSnapshot(resumed),
+        round: pendingDev[0].round,
+        scopeDecisionNote: devPayload.scopeDecisionNote,
+    });
+    assert.ok(developerPrompt.includes(AMENDED_EXIT));
+    assert.ok(developerPrompt.includes("Simulator proof attached"));
+    assert.ok(!developerPrompt.includes(REMOVED_CRITERION));
+    assert.ok(!developerPrompt.includes("clean machine with operator proof"));
+    // The developer completes; the following reviewer prompt enforces the same
+    // amended snapshot — no escalation for the removed criterion can recur.
+    const dev2 = claimWorkItem("scope-contract-test", { leaseMs: 60_000 });
+    assert.equal(dev2.id, pendingDev[0].id);
+    await applyCompletion(dev2.id, dev2.leaseToken, {
+        kind: "clean_handoff",
+        branch: "dealer/not-405",
+        headSha: "def456",
+        baseSha: "base1",
+        prNumber: 42,
+        prUrl: "https://gh/pr/42",
+    });
+    const reviewRound = getIssue(issueId);
+    assert.equal(reviewRound.status, "reviewing");
+    assert.equal(getActiveWorkflowInstance(issueId).id, instanceBefore.id);
+    assert.equal(reviewRound.branch, "dealer/not-405");
+    // The following reviewer work item — claimed the way the effect worker
+    // claims it — carries the same workflow instance, and its prompt inputs
+    // (this item's round over the frozen snapshot) enforce the amended
+    // snapshot with no escalation for the removed criterion recurring.
+    const rev2 = claimWorkItem("scope-contract-test", { leaseMs: 60_000 });
+    assert.equal(rev2.kind, "reviewer");
+    assert.equal(rev2.workflowInstanceId, instanceBefore.id);
+    const reviewerPrompt = buildReviewerPrompt({
+        taskSnapshot: getTaskSnapshot(reviewRound),
+        round: rev2.round,
+        baseSha: "a".repeat(40),
+        headSha: "b".repeat(40),
+        diff: "diff --git a/x b/x\n+added line\n",
+    });
+    assert.ok(reviewerPrompt.includes(AMENDED_EXIT));
+    assert.ok(reviewerPrompt.includes("Simulator proof attached"));
+    assert.ok(!reviewerPrompt.includes(REMOVED_CRITERION));
+    assert.ok(!reviewerPrompt.includes("clean machine with operator proof"));
+}
+test("NOT-422: reviewer escalation → scope-pause reload → Resume → both roles enforce only the amended snapshot", async () => {
+    await runScopePauseAdoptionFlow(adoptViaReload);
+});
+test("NOT-422: reviewer escalation → scope-pause local edit → Resume → both roles enforce only the amended snapshot", async () => {
+    await runScopePauseAdoptionFlow(adoptViaLocalEdit);
+});

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

@@ -1,6 +1,7 @@
 import { sourceAttachmentsDeveloperSection, sourceAttachmentsReviewerSection, } from "./source-attachments.js";
 import { MUSE_SANDBOX_CAPABILITIES } from "../runners/muse-code-args.js";
 import { checkMuseVisualQa, museVisualQaPromptSection, } from "../adapters/muse-visual-qa.js";
+import { capableDeveloperVisualQaPromptSection, developerVisualQaPolicy, visualQaReviewerSection, } from "./visual-qa.js";
 import { formatVerificationReceiptSection, } from "./verification-receipt.js";
 import { formatOperatorCriteria, } from "./operator-criteria.js";
 /**
@@ -284,10 +285,15 @@ export function buildDeveloperPrompt(input) {
         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.
-    if (input.museDeveloper) {
+    // mid-session. NOT-381: non-Muse runtimes get the capable-runtime in-session
+    // attempt instead of the old blanket no-browser assumption.
+    const visualQaPolicy = input.museDeveloper ? "muse" : developerVisualQaPolicy(input.runtime);
+    if (visualQaPolicy === "muse") {
         parts.push(...museVisualQaPromptSection(input.museVisualQa ?? checkMuseVisualQa()));
     }
+    else {
+        parts.push(...capableDeveloperVisualQaPromptSection());
+    }
     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.
@@ -370,6 +376,49 @@ export function formatDiffForPrompt(diff) {
         omittedPaths,
     };
 }
+/**
+ * NOT-384: SHA-bound CI visual evidence for this head. `available` names the
+ * staged paths, both SHAs, and the diff summary, and instructs the reviewer to
+ * judge the screenshots and the base-vs-head diff at both viewports. `missing`
+ * and `failed` name the state and forbid a visual pass — and forbid a blocking
+ * finding about the missing evidence itself, since Dealer holds the head for a
+ * human operator automatically (a repair round must never start solely for
+ * missing visual evidence). Absent renders nothing.
+ */
+function visualEvidenceSection(evidence) {
+    if (!evidence)
+        return [];
+    const head8 = evidence.headSha.slice(0, 8);
+    if (evidence.state === "available") {
+        const staged = evidence.staged;
+        const lines = [
+            `## Visual evidence (CI-captured at ${head8})`,
+            `The \`Visual\` CI workflow captured this exact head (\`${evidence.headSha}\`, base \`${evidence.baseSha}\`${evidence.runId != null ? `, run ${evidence.runId}` : ""}) at the required viewports (1440x900 and 390x800), running each route's interaction steps before the screenshot. Judge the screenshots and the base-vs-head diff at both viewports — a nonzero pixel diff is evidence, never an automatic failure; decide whether the rendered changes match the task. A genuine rendered defect IS a coding finding; captures you cannot judge are a risk, never a pass.`,
+            ``,
+        ];
+        if (staged) {
+            lines.push(`- Head captures: \`${staged.screenshotsDir}/\``, `- Baseline captures: \`${staged.baselineDir}/\``, `- Diffs and summary: \`${staged.diffDir}/\``, ``);
+        }
+        if (evidence.files) {
+            for (const name of ["ui-screenshots", "ui-baseline", "ui-diff"]) {
+                const listing = evidence.files[name];
+                const extra = listing.total > listing.files.length ? ` (+${listing.total - listing.files.length} more)` : "";
+                lines.push(`\`${name}/\` (${listing.total} files${extra}): ${listing.files.map((f) => `\`${f}\``).join(", ") || "(empty)"}`);
+            }
+            lines.push(``);
+        }
+        lines.push(`### Diff summary (\`SUMMARY.md\`${staged?.summaryPath ? ` at \`${staged.summaryPath}\`` : ""})`, evidence.summary ?? "(the staged ui-diff directory has no SUMMARY.md — judge the diff PNGs directly)", ``, `Read the PNGs with your file tools — every path above is inside your read-only checkout. Record \`visual QA: verified (<n> shots at ${head8})\` in \`evidenceAssessment\`, naming the shots you judged.`, ``);
+        return lines;
+    }
+    const reason = evidence.reason ?? "no usable CI visual captures";
+    return [
+        `## Visual evidence: ${evidence.state} — no usable CI captures for this head`,
+        `The \`Visual\` CI workflow produced no usable screenshots for this exact head (\`${evidence.headSha}\`, base \`${evidence.baseSha}\`): ${reason}.`,
+        ``,
+        `Do NOT report a visual pass: write \`visual QA: not run (${evidence.state})\` in \`evidenceAssessment\`. Do not raise a blocking finding about the missing evidence itself — Dealer holds this head for a human operator automatically, and a repair round must never start solely for missing visual evidence. Judge only the code in the diff.`,
+        ``,
+    ];
+}
 export function buildReviewerPrompt(input) {
     const parts = [
         input.round === 1
@@ -405,6 +454,12 @@ export function buildReviewerPrompt(input) {
     if (input.checksSummary) {
         parts.push(`## CI checks`, input.checksSummary, ``);
     }
+    // NOT-384: SHA-bound CI captures for this head (or the missing/failed
+    // notice) — rendered only when the coordinator resolved visual evidence.
+    parts.push(...visualEvidenceSection(input.visualEvidence));
+    // NOT-381: the coordinator-validated visual receipt (or loud rejection),
+    // SHA-bound to the pinned head — the raw conclusion line above is unverified.
+    parts.push(...visualQaReviewerSection(input.visualQa?.record ?? null, input.visualQa?.pinnedHeadSha ?? input.headSha));
     if (input.findings?.length) {
         parts.push(`## Findings from prior rounds (verify each is actually resolved)`);
         for (const f of input.findings) {

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

@@ -288,9 +288,64 @@ test("NOT-303: museDeveloper prompt names the pre-installed headless shell when
     assert.match(prompt, /--screenshot=<png>/);
     assert.match(prompt, /Google Chrome\.app/);
 });
-test("NOT-303: a non-Muse developer prompt has no visual-QA section", () => {
+// NOT-381: non-Muse runtimes attempt in-session browser verification instead of
+// the old blanket no-browser assumption — the prompt carries the bounded probe,
+// the real-app requirement, the default viewports, and the receipt format.
+test("NOT-381: a non-Muse developer prompt carries the capable-runtime visual-QA section", () => {
     const prompt = buildDeveloperPrompt({ taskSnapshot, round: 1, deckId: "deck-1", worktreePath: "/wt" });
-    assert.doesNotMatch(prompt, /## Visual QA/);
+    assert.match(prompt, /## Visual QA \(in-session browser verification\)/);
+    assert.match(prompt, /ONE bounded capability probe/);
+    assert.match(prompt, /REAL backend and frontend/);
+    assert.match(prompt, /1440x900/);
+    assert.match(prompt, /390x800/);
+    assert.match(prompt, /do not install browsers or packages/);
+    assert.match(prompt, /do not retry the failed capability/);
+    assert.match(prompt, /do not weaken any sandbox flag/);
+    assert.match(prompt, /never commit it/);
+    assert.doesNotMatch(prompt, /RegisterApplication/);
+});
+// NOT-381: the policy is runtime-aware — Muse (boolean or runtime id) keeps the
+// NOT-303 preflight, Claude Code / Codex Local / Cursor Local get the attempt.
+test("NOT-381: runtime policy keeps Muse behavior and gives capable runtimes the attempt", () => {
+    const saved = process.env.MUSE_HEADLESS_SHELL_BIN;
+    delete process.env.MUSE_HEADLESS_SHELL_BIN;
+    try {
+        for (const runtime of ["claude_code", "codex_local", "cursor_local"]) {
+            const prompt = buildDeveloperPrompt({
+                taskSnapshot,
+                round: 1,
+                deckId: "deck-1",
+                worktreePath: "/wt",
+                runtime,
+            });
+            assert.match(prompt, /## Visual QA \(in-session browser verification\)/, runtime);
+            assert.match(prompt, /ONE bounded capability probe/, runtime);
+            assert.doesNotMatch(prompt, /RegisterApplication/);
+        }
+        const museByRuntime = buildDeveloperPrompt({
+            taskSnapshot,
+            round: 1,
+            deckId: "deck-1",
+            worktreePath: "/wt",
+            runtime: "muse_code",
+        });
+        assert.match(museByRuntime, /## Visual QA \(screenshots\)/);
+        assert.match(museByRuntime, /RegisterApplication/);
+        assert.match(museByRuntime, /Visual QA: not run/);
+        const museByFlag = buildDeveloperPrompt({
+            taskSnapshot,
+            round: 1,
+            deckId: "deck-1",
+            worktreePath: "/wt",
+            museDeveloper: true,
+            runtime: "claude_code",
+        });
+        assert.match(museByFlag, /RegisterApplication/, "museDeveloper flag keeps the Muse preflight");
+    }
+    finally {
+        if (saved !== undefined)
+            process.env.MUSE_HEADLESS_SHELL_BIN = saved;
+    }
 });
 test("NOT-303: reviewer prompt states a missing screenshot is never a pass", () => {
     const prompt = buildReviewerPrompt(reviewerBase);
@@ -542,6 +597,96 @@ test("NOT-364: attachment-free developer prompts render no source-attachment sec
     assert.doesNotMatch(without, /## Source attachments/);
     assert.equal(buildDeveloperPrompt({ taskSnapshot, round: 1 }), without);
 });
+// NOT-381: the reviewer input carries the coordinator-validated visual receipt
+// SHA-bound to the pinned head; unavailable is a routing state, never a pass.
+test("NOT-381: reviewer prompt includes the validated visual receipt bound to the pinned head", () => {
+    const headSha = "b".repeat(40);
+    const prompt = buildReviewerPrompt({
+        ...reviewerBase,
+        visualQa: {
+            pinnedHeadSha: headSha,
+            record: {
+                kind: "receipt",
+                createdAt: "2026-10-08T00:00:00.000Z",
+                content: {
+                    status: "verified",
+                    headSha,
+                    realApp: "real (no mocks)",
+                    scenario: "/widgets/new — fill the form and submit",
+                    viewports: ["1440x900", "390x800"],
+                    commands: "npm run dev; capture",
+                    screenshots: [
+                        { fileName: "0-desktop.png", blobPath: "/blobs/0-desktop.png", sizeBytes: 10, sha256: "ab".repeat(32) },
+                    ],
+                    capability: null,
+                    note: null,
+                    recordedAt: "2026-10-08T00:00:00.000Z",
+                },
+            },
+        },
+    });
+    assert.match(prompt, /## Visual QA \(developer receipt — SHA-bound to this head\)/);
+    assert.match(prompt, new RegExp(headSha));
+    assert.match(prompt, /real \(no mocks\)/);
+    assert.match(prompt, /0-desktop\.png/);
+});
+test("NOT-381: reviewer prompt presents unavailable and not-required receipts without normalizing to a pass", () => {
+    const unavailable = buildReviewerPrompt({
+        ...reviewerBase,
+        visualQa: {
+            pinnedHeadSha: reviewerBase.headSha,
+            record: {
+                kind: "receipt",
+                createdAt: "2026-10-08T00:00:00.000Z",
+                content: {
+                    status: "unavailable",
+                    headSha: reviewerBase.headSha,
+                    realApp: null,
+                    scenario: null,
+                    viewports: [],
+                    commands: null,
+                    screenshots: [],
+                    capability: "loopback listen: EPERM",
+                    note: null,
+                    recordedAt: "2026-10-08T00:00:00.000Z",
+                },
+            },
+        },
+    });
+    assert.match(unavailable, /## Visual QA \(UNAVAILABLE — not verified\)/);
+    assert.match(unavailable, /loopback listen: EPERM/);
+    assert.match(unavailable, /never a pass/);
+    assert.doesNotMatch(unavailable, /SHA-bound to this head/);
+    const notRequired = buildReviewerPrompt({
+        ...reviewerBase,
+        visualQa: {
+            pinnedHeadSha: reviewerBase.headSha,
+            record: {
+                kind: "receipt",
+                createdAt: "2026-10-08T00:00:00.000Z",
+                content: {
+                    status: "not_required",
+                    headSha: null,
+                    realApp: null,
+                    scenario: null,
+                    viewports: [],
+                    commands: null,
+                    screenshots: [],
+                    capability: null,
+                    note: null,
+                    recordedAt: "2026-10-08T00:00:00.000Z",
+                },
+            },
+        },
+    });
+    assert.match(notRequired, /## Visual QA \(not required/);
+    assert.doesNotMatch(notRequired, /SHA-bound to this head/);
+    const without = buildReviewerPrompt(reviewerBase);
+    assert.doesNotMatch(without, /## Visual QA \(developer receipt/);
+    assert.doesNotMatch(without, /## Visual QA \(UNAVAILABLE/);
+    assert.equal(buildReviewerPrompt({ ...reviewerBase, visualQa: undefined }), without);
+    assert.equal(buildReviewerPrompt({ ...reviewerBase, visualQa: null }), without);
+});
 // NOT-364: reviewers get the immutable manifest as metadata only — no
 // worktree path, no server blob path, no file contents.
 test("NOT-364: reviewer prompt carries manifest metadata without file paths", () => {
@@ -576,3 +721,92 @@ test("NOT-364: reviewer prompt carries manifest metadata without file paths", ()
     const without = buildReviewerPrompt(reviewerBase);
     assert.doesNotMatch(without, /## Source attachments/);
 });
+// NOT-384: available visual evidence cites the staged paths, both SHAs, and
+// the diff summary, and instructs the reviewer to judge both viewports.
+test("NOT-384: reviewer prompt cites staged SHA-bound screenshots and diff for available evidence", () => {
+    const prompt = buildReviewerPrompt({
+        ...reviewerBase,
+        visualEvidence: {
+            state: "available",
+            headSha: "b".repeat(40),
+            baseSha: "a".repeat(40),
+            runId: 42,
+            staged: {
+                stagedDir: "/wt/.agent-dealer-visual",
+                screenshotsDir: "/wt/.agent-dealer-visual/ui-screenshots",
+                baselineDir: "/wt/.agent-dealer-visual/ui-baseline",
+                diffDir: "/wt/.agent-dealer-visual/ui-diff",
+                summaryPath: "/wt/.agent-dealer-visual/ui-diff/SUMMARY.md",
+            },
+            summary: "## UI diff (base vs head, report-only)\n\n| `issues-home` | 1440x900 | 12 |",
+            files: {
+                "ui-screenshots": { files: ["issues-home-1440x900.png"], total: 8 },
+                "ui-baseline": { files: ["issues-home-1440x900.png"], total: 8 },
+                "ui-diff": { files: ["SUMMARY.md", "diff-issues-home-1440x900.png"], total: 9 },
+            },
+            reason: null,
+        },
+    });
+    assert.match(prompt, /## Visual evidence \(CI-captured at b{8}\)/);
+    assert.ok(prompt.includes("/wt/.agent-dealer-visual/ui-screenshots/"), "staged head captures must be named");
+    assert.ok(prompt.includes("/wt/.agent-dealer-visual/ui-baseline/"), "staged baseline must be named");
+    assert.ok(prompt.includes("/wt/.agent-dealer-visual/ui-diff/"), "staged diff must be named");
+    assert.ok(prompt.includes("`bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb`"), "head SHA must be cited");
+    assert.ok(prompt.includes("`aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`"), "base SHA must be cited");
+    assert.match(prompt, /run 42/);
+    assert.match(prompt, /1440x900 and 390x800/);
+    assert.match(prompt, /Judge the screenshots and the base-vs-head diff at both viewports/);
+    assert.match(prompt, /nonzero pixel diff is evidence, never an automatic failure/);
+    assert.match(prompt, /## UI diff \(base vs head, report-only\)/);
+    assert.match(prompt, /visual QA: verified/);
+});
+// NOT-384: missing and failed evidence name the state and forbid a visual
+// pass — and forbid a blocking finding about the evidence itself, since Dealer
+// holds the head for an operator instead of queuing a repair round.
+test("NOT-384: reviewer prompt forbids a visual pass for missing evidence", () => {
+    const prompt = buildReviewerPrompt({
+        ...reviewerBase,
+        visualEvidence: {
+            state: "missing",
+            headSha: "b".repeat(40),
+            baseSha: "a".repeat(40),
+            runId: null,
+            staged: null,
+            summary: null,
+            files: null,
+            reason: "no Visual workflow run found for head bbbbbbbb",
+        },
+    });
+    assert.match(prompt, /## Visual evidence: missing/);
+    assert.ok(prompt.includes("`bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb`"), "head SHA must be named");
+    assert.match(prompt, /no Visual workflow run found/);
+    assert.match(prompt, /Do NOT report a visual pass/);
+    assert.match(prompt, /visual QA: not run \(missing\)/);
+    assert.match(prompt, /Do not raise a blocking finding about the missing evidence itself/);
+    assert.match(prompt, /never start solely for missing visual evidence/);
+});
+test("NOT-384: reviewer prompt forbids a visual pass for failed evidence", () => {
+    const prompt = buildReviewerPrompt({
+        ...reviewerBase,
+        visualEvidence: {
+            state: "failed",
+            headSha: "b".repeat(40),
+            baseSha: "a".repeat(40),
+            runId: 43,
+            staged: null,
+            summary: null,
+            files: null,
+            reason: "Visual run 43 for this head concluded failure — its captures are unusable",
+        },
+    });
+    assert.match(prompt, /## Visual evidence: failed/);
+    assert.match(prompt, /concluded failure/);
+    assert.match(prompt, /Do NOT report a visual pass/);
+    assert.match(prompt, /visual QA: not run \(failed\)/);
+    assert.match(prompt, /Do not raise a blocking finding about the missing evidence itself/);
+});
+test("NOT-384: no visual evidence produces byte-for-byte the same reviewer prompt as before", () => {
+    const without = buildReviewerPrompt(reviewerBase);
+    assert.doesNotMatch(without, /## Visual evidence/);
+    assert.equal(buildReviewerPrompt({ ...reviewerBase, visualEvidence: undefined }), without);
+});