agent-dealer 1.3.1 → 1.3.3

package/bundle/server/dist/coordinator/operator-verification.integration.test.js

@@ -13,7 +13,8 @@ const { createIssue, getIssue, updateIssue, transitionIssue } = await import("..
 const { listHumanActionsForIssue } = await import("../repository/human-actions.js");
 const { listArtifactsForIssueByKind } = await import("../repository/artifacts-for-issue.js");
 const { listWorkflowEventsForIssue, getActiveWorkflowInstance } = await import("../repository/workflow-events.js");
-const { claimWorkItem, getWorkItem } = await import("../repository/work-items.js");
+const { claimWorkItem, getWorkItem, listWorkItemsForIssue } = await import("../repository/work-items.js");
+const { createIssueArtifact } = await import("../repository/artifacts.js");
 const { startWorkflow, applyCompletion, resolveHumanActionAndAdvance, resolveHumanActionAndAdvanceAsync, responseOptionsFor, } = await import("./commands.js");
 const { ReviewerResult } = await import("./reviewer-result.js");
 const { setMergePrForTests, clearFinalizeInflightForTests, finalizeAutoMerge, gateOperatorVerification, OPERATOR_VERIFICATION_INTENT, } = await import("./auto-merge.js");
@@ -345,3 +346,103 @@ test("responseOptionsFor(operator_verification) matches the gate's stored option
         { choice: "repair", label: "Another repair round" },
     ]);
 });
+// NOT-384: a UI-affecting head whose recorded CI visual evidence is `missing`
+// holds at the same gate — one operator_verification action naming the head
+// SHA and the missing artifacts, no merge, and crucially no repair round.
+function recordVisualEvidence(issueId, opts) {
+    createIssueArtifact({
+        issueId,
+        kind: "visual_evidence",
+        content: {
+            headSha: opts.headSha,
+            baseSha: "base1",
+            uiAffecting: true,
+            state: opts.state,
+            runId: opts.state === "missing" ? null : 42,
+            artifactNames: opts.state === "available" ? ["ui-screenshots", "ui-baseline", "ui-diff"] : [],
+            reason: opts.state === "available"
+                ? null
+                : opts.state === "failed"
+                    ? "Visual run 42 for this head concluded failure — its captures are unusable"
+                    : "no Visual workflow run found for head abc123",
+        },
+        author: "system",
+    });
+}
+function assertNoRepairWorkScheduled(issueId) {
+    const pending = listWorkItemsForIssue(issueId).filter((item) => item.status === "pending" || item.status === "leased");
+    assert.deepEqual(pending.map((item) => item.kind), [], "missing visual evidence must never schedule a repair round");
+}
+for (const state of ["missing", "failed"]) {
+    test(`NOT-384: ${state} visual evidence on a UI head raises operator_verification and never a repair round`, async () => {
+        let merges = 0;
+        setMergePrForTests(async () => {
+            merges += 1;
+            return { ok: true };
+        });
+        const issueId = newIssue("It works");
+        startWorkflow(issueId);
+        recordVisualEvidence(issueId, { headSha: "abc123", state });
+        const result = await approve(issueId);
+        assert.equal(result.applied, true);
+        if (result.applied) {
+            assert.equal(result.issueStatus, "needs_human");
+            assert.equal(result.nextWorkItemId, null, "the gate queues no repair round");
+            assert.ok(result.humanActionId);
+        }
+        assert.equal(merges, 0, "the merge adapter must not run behind the gate");
+        assertNoRepairWorkScheduled(issueId);
+        const action = openOperatorAction(issueId);
+        assert.match(action.question, /abc123/, "the action names the head SHA");
+        assert.match(action.question, /ui-screenshots/, "the action names the missing artifacts");
+        assert.match(action.question, new RegExp(state), "the action names the evidence state");
+        const evidence = JSON.parse(action.evidenceJson);
+        assert.equal(evidence.operatorVerification.headSha, "abc123");
+        assert.equal(evidence.operatorVerification.visualEvidence.state, state);
+        assert.ok(evidence.operatorVerification.visualEvidence.missingArtifacts.length > 0);
+        const options = JSON.parse(action.responseOptionsJson);
+        assert.deepEqual(options.map((o) => o.choice), ["verified", "waive", "repair"]);
+    });
+}
+test("NOT-384: available visual evidence on a UI head merges normally", async () => {
+    const calls = [];
+    setMergePrForTests(async (opts) => {
+        calls.push(opts);
+        return { ok: true };
+    });
+    const issueId = newIssue("It works");
+    startWorkflow(issueId);
+    recordVisualEvidence(issueId, { headSha: "abc123", state: "available" });
+    const result = await approve(issueId);
+    assert.equal(result.applied, true);
+    if (result.applied)
+        assert.equal(result.issueStatus, "done");
+    assert.deepEqual(calls, [{ cwd: managedCwd, number: 42 }]);
+    assert.equal(getIssue(issueId).status, "done");
+});
+test("NOT-384: [operator] criteria plus a visual hold raise one action naming both", async () => {
+    let merges = 0;
+    setMergePrForTests(async () => {
+        merges += 1;
+        return { ok: true };
+    });
+    const issueId = newIssue();
+    startWorkflow(issueId);
+    recordVisualEvidence(issueId, { headSha: "abc123", state: "missing" });
+    await approve(issueId);
+    assert.equal(merges, 0);
+    const open = listHumanActionsForIssue(issueId).filter((a) => a.status === "open");
+    assert.equal(open.length, 1, "criteria and visual hold share one action for the head");
+    assert.equal(open[0].actionType, "operator_verification");
+    assert.match(open[0].question, /sign in with SSO/);
+    assert.match(open[0].question, /ui-screenshots/);
+    const evidence = JSON.parse(open[0].evidenceJson);
+    assert.equal(evidence.operatorVerification.criteria.length, 1);
+    assert.equal(evidence.operatorVerification.visualEvidence.state, "missing");
+    // One recorded result releases the combined action — a second finalize for
+    // the same head reuses it instead of raising another.
+    const again = await finalizeAutoMerge(issueId);
+    assert.equal(again.humanActionId, open[0].id);
+    assert.equal(listHumanActionsForIssue(issueId).filter((a) => a.status === "open").length, 1);
+    assert.equal(merges, 0);
+});

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) {