agent-dealer 1.3.1 → 1.3.3

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

package/bundle/server/dist/coordinator/reviewer-browser-probe.js

@@ -492,6 +492,26 @@ const defaultDeps = {
     now: () => new Date(),
     randomId: () => randomUUID(),
 };
+/**
+ * NOT-382: wait for an already-started spawn race to settle, up to `graceMs`.
+ * Returns null on grace expiry — the caller proceeds to cleanup regardless so
+ * a spawn that never settles cannot wedge the probe past its own deadline.
+ */
+async function awaitSpawnSettled(outcome, graceMs) {
+    let graceTimer;
+    try {
+        return await Promise.race([
+            outcome,
+            new Promise((resolve) => {
+                graceTimer = setTimeout(() => resolve(null), graceMs);
+            }),
+        ]);
+    }
+    finally {
+        if (graceTimer)
+            clearTimeout(graceTimer);
+    }
+}
 /**
  * Run one probe through Dealer's real reviewer spawn path and return the
  * deterministic manifest. Every outcome — success, timeout, cancellation,
@@ -506,6 +526,7 @@ export async function runReviewerBrowserProbe(opts, deps = {}) {
     const appRoute = opts.appRoute ?? "/issues";
     const appInteraction = opts.appInteraction ?? "open the first issue and expand its timeline";
     const timeoutMs = opts.timeoutMs ?? reviewerSessionTimeoutMs();
+    const spawnSettleGraceMs = opts.spawnSettleGraceMs ?? 10_000;
     if (!SHA_HEX_RE.test(opts.headSha)) {
         throw new Error(`probe headSha must be a 40-char hex SHA (got ${JSON.stringify(opts.headSha)})`);
     }
@@ -687,7 +708,7 @@ export async function runReviewerBrowserProbe(opts, deps = {}) {
                 startedAt,
                 endedAt,
                 timedOut: false,
-                cancelled: false,
+                cancelled: Boolean(opts.signal?.aborted),
                 exitCode: null,
                 launch: { bin, argv, cwd: worktreePath ?? opts.repoPath, mcpConfigPath: null, mcpEnvKeys: [], policy },
                 cleanup,
@@ -711,7 +732,7 @@ export async function runReviewerBrowserProbe(opts, deps = {}) {
                     startedAt,
                     endedAt: d.now().toISOString(),
                     timedOut: false,
-                    cancelled: false,
+                    cancelled: Boolean(opts.signal?.aborted),
                     exitCode: null,
                     launch: {
                         bin,
@@ -745,7 +766,7 @@ export async function runReviewerBrowserProbe(opts, deps = {}) {
                     startedAt,
                     endedAt: d.now().toISOString(),
                     timedOut: false,
-                    cancelled: false,
+                    cancelled: Boolean(opts.signal?.aborted),
                     exitCode: null,
                     launch: {
                         bin,
@@ -800,10 +821,61 @@ export async function runReviewerBrowserProbe(opts, deps = {}) {
                 childPids.push(pid);
             },
         };
-        const spawned = await d.spawn(spawnInput);
-        exitCode = spawned.exitCode;
-        timedOut = spawned.timedOut;
-        transcript = spawned.transcript;
+        // NOT-382: enforce the deadline HERE, not only inside the spawn. The probe
+        // used to `await d.spawn(...)` bare: a spawn that never settles (wedged
+        // CLI, or a fake that ignores timeoutMs/signal) hung the probe forever
+        // with neither timedOut nor cancelled recorded. The spawn's own
+        // timeout/signal handling still does the actual killing; the probe owns
+        // the deadline so the manifest always records which bound fired.
+        const spawnOutcome = d.spawn(spawnInput).then((result) => ({ kind: "spawned", result }), (error) => ({ kind: "spawn-error", error }));
+        let probeTimer;
+        const probeTimeout = new Promise((resolve) => {
+            // Deliberately NOT unref'd: the deadline must hold the event loop even
+            // when the spawn left no live handles behind.
+            probeTimer = setTimeout(() => resolve({ kind: "timeout" }), timeoutMs);
+        });
+        let onProbeAbort;
+        const probeAborted = new Promise((resolve) => {
+            if (!opts.signal)
+                return; // no signal: stays pending, the race ignores it
+            if (opts.signal.aborted) {
+                resolve({ kind: "aborted" });
+                return;
+            }
+            onProbeAbort = () => resolve({ kind: "aborted" });
+            opts.signal.addEventListener("abort", onProbeAbort, { once: true });
+        });
+        try {
+            const winner = await Promise.race([spawnOutcome, probeTimeout, probeAborted]);
+            if (winner.kind === "spawn-error")
+                throw winner.error;
+            if (winner.kind === "spawned") {
+                exitCode = winner.result.exitCode;
+                timedOut = winner.result.timedOut;
+                transcript = winner.result.transcript;
+            }
+            else {
+                // The probe deadline fired first (timeout) or the caller aborted: stop
+                // waiting, but give the real spawn's kill path a bounded grace to
+                // settle so cleanup observes the reaped child instead of racing it. A
+                // spawn that never settles still proceeds after the grace.
+                if (winner.kind === "timeout")
+                    timedOut = true;
+                const late = await awaitSpawnSettled(spawnOutcome, spawnSettleGraceMs);
+                if (late?.kind === "spawned") {
+                    exitCode = late.result.exitCode;
+                    transcript = late.result.transcript;
+                }
+                // A late spawn-error changes nothing: the deadline outcome already won.
+                // `cancelled` is recorded from opts.signal.aborted at manifest time.
+            }
+        }
+        finally {
+            if (probeTimer)
+                clearTimeout(probeTimer);
+            if (onProbeAbort)
+                opts.signal?.removeEventListener("abort", onProbeAbort);
+        }
         const report = parseReviewerBrowserProbeReport(transcript);
         let headShaVerified = false;
         try {
@@ -998,7 +1070,14 @@ export function overlayPlaywrightMcpConfig(opts) {
         return { ok: false, reason: err instanceof Error ? err.message : String(err) };
     }
 }
-/** Manifest filename for one (runtime, contract) probe. */
-export function probeManifestFilename(runtime, contract) {
-    return `${runtime}.${contract}.probe.json`;
+/**
+ * Manifest filename for one (runtime, contract) probe. Control runs take a
+ * `.timeout` / `.cancel` suffix when the matching CLI flag is set, so the four
+ * NOT-382 operator controls never overwrite the positive manifest or each
+ * other when they share one --out-dir.
+ */
+export function probeManifestFilename(runtime, contract, opts) {
+    const timeoutSuffix = opts?.timeout ? ".timeout" : "";
+    const cancelSuffix = opts?.cancel ? ".cancel" : "";
+    return `${runtime}.${contract}${timeoutSuffix}${cancelSuffix}.probe.json`;
 }

package/bundle/server/dist/coordinator/reviewer-browser-probe.test.js

@@ -4,6 +4,7 @@
 // behavior for missing fields or an unexecuted probe.
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
@@ -646,9 +647,108 @@ test("manifest filenames are unique per (runtime, contract)", () => {
     }
     assert.equal(probeManifestFilename("claude_code", "direct"), "claude_code.direct.probe.json");
 });
+test("control-run manifest filenames never overwrite the positive manifest (NOT-382)", () => {
+    assert.equal(probeManifestFilename("claude_code", "direct", { timeout: true }), "claude_code.direct.timeout.probe.json");
+    assert.equal(probeManifestFilename("claude_code", "direct", { cancel: true }), "claude_code.direct.cancel.probe.json");
+    assert.equal(probeManifestFilename("codex_local", "direct", { timeout: true, cancel: true }), "codex_local.direct.timeout.cancel.probe.json");
+    // All four operator controls + the positive manifest are distinct files.
+    const names = new Set([
+        probeManifestFilename("claude_code", "direct"),
+        probeManifestFilename("claude_code", "direct", { timeout: true }),
+        probeManifestFilename("claude_code", "direct", { cancel: true }),
+        probeManifestFilename("codex_local", "direct"),
+        probeManifestFilename("codex_local", "direct", { timeout: true }),
+        probeManifestFilename("codex_local", "direct", { cancel: true }),
+    ]);
+    assert.equal(names.size, 6);
+});
 test("canonical JSON sorts keys deterministically", () => {
     assert.equal(canonicalProbeJson({ b: 1, a: { d: 4, c: 3 } }), `{\n  "a": {\n    "c": 3,\n    "d": 4\n  },\n  "b": 1\n}\n`);
 });
+test("runner enforces its own timeout when the spawn never settles (NOT-382)", async () => {
+    // A real but already-reaped pid: proves the child-process accounting runs on
+    // the timeout path (reaped → zero remaining).
+    const reapedPid = spawnSync("true").pid;
+    assert.ok(typeof reapedPid === "number" && reapedPid > 0, "expected a reaped pid from spawnSync(true)");
+    const manifest = await runReviewerBrowserProbe({
+        runtime: "claude_code",
+        contract: "direct",
+        repoPath: "/tmp/fake-repo",
+        headSha: HEAD,
+        deckId: "deck-1",
+        probeId: "probe-timeout-382",
+        timeoutMs: 50,
+        spawnSettleGraceMs: 25,
+    }, {
+        createWorktree: (async () => ({ path: "/tmp/wt", role: "reviewer", ref: HEAD, detached: true })),
+        removeWorktree: (async () => ({ removed: true })),
+        prepareDeck: async () => ({ ok: true, mcpConfigPath: "/tmp/fake-deck.json" }),
+        releaseDeck: async () => { },
+        readHead: (async () => HEAD),
+        now: () => new Date("2026-10-08T00:00:00.000Z"),
+        // Never settles and ignores timeoutMs/signal — pre-fix the probe hung on
+        // this await forever with neither timedOut nor cancelled recorded.
+        spawn: (async (input) => {
+            input.onSpawn?.(reapedPid);
+            await new Promise(() => { });
+            throw new Error("unreachable");
+        }),
+    });
+    assert.equal(manifest.timedOut, true);
+    assert.equal(manifest.cancelled, false);
+    assert.equal(manifest.status, "not_run");
+    assert.match(manifest.statusReason, /timed out/);
+    assert.equal(manifest.cleanup.childProcessesRemaining, 0);
+    assert.equal(manifest.cleanup.tempDirRemoved, true);
+});
+test("runner records cancellation when the signal aborts mid-session (NOT-382)", async () => {
+    const controller = new AbortController();
+    const manifest = await runReviewerBrowserProbe({
+        runtime: "claude_code",
+        contract: "direct",
+        repoPath: "/tmp/fake-repo",
+        headSha: HEAD,
+        deckId: "deck-1",
+        probeId: "probe-cancel-382",
+        timeoutMs: 60_000,
+        spawnSettleGraceMs: 500,
+        signal: controller.signal,
+    }, {
+        createWorktree: (async () => ({ path: "/tmp/wt", role: "reviewer", ref: HEAD, detached: true })),
+        removeWorktree: (async () => ({ removed: true })),
+        prepareDeck: async () => ({ ok: true, mcpConfigPath: "/tmp/fake-deck.json" }),
+        releaseDeck: async () => { },
+        readHead: (async () => HEAD),
+        now: () => new Date("2026-10-08T00:00:00.000Z"),
+        // Never settles on its own; kills its real child on abort exactly like
+        // spawnCli does, so the probe must observe zero survivors. The abort is
+        // scheduled from inside the fake so it lands mid-session.
+        spawn: (async (input) => {
+            const child = spawn("sleep", ["30"]);
+            assert.ok(child.pid, "expected sleep to spawn");
+            child.unref();
+            child.on("error", () => { });
+            input.onSpawn?.(child.pid);
+            input.signal?.addEventListener("abort", () => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    // already gone — the probe's kill(0) check confirms it
+                }
+            }, { once: true });
+            setTimeout(() => controller.abort(new Error("--cancel-after-ms elapsed (test)")), 20);
+            await new Promise(() => { });
+            throw new Error("unreachable");
+        }),
+    });
+    assert.equal(manifest.cancelled, true);
+    assert.equal(manifest.timedOut, false);
+    assert.equal(manifest.status, "not_run");
+    assert.match(manifest.statusReason, /cancelled/);
+    assert.equal(manifest.cleanup.childProcessesRemaining, 0);
+    assert.equal(manifest.cleanup.tempDirRemoved, true);
+});
 test("withManifestHash is stable for identical manifests", () => {
     const launch = {
         bin: "b",

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

@@ -28,10 +28,12 @@ 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 { cleanupStagedVisualArtifacts, resolveReviewerVisualEvidence, toReviewerVisualEvidenceInput, } from "./reviewer-visual-evidence.js";
+import { readLatestVisualQa } from "./visual-qa.js";
 import { guidanceForNextSession } from "./guidance.js";
 import { realReviewerSpawn, reviewerSessionLogPath } from "./spawn.js";
 import { parseReviewerResult, normalizeReviewerResult, INCOMPLETE_REVIEW_FINGERPRINT, ReviewerResult as ReviewerResultSchema, } from "./reviewer-result.js";
-import { createRoleWorktree, safeRemoveWorktree, isWorktreeClean, mergeBase, fetchRef, diffShas, } from "../adapters/git-worktree.js";
+import { createRoleWorktree, safeRemoveWorktree, isWorktreeClean, listChangedFiles, mergeBase, fetchRef, diffShas, } from "../adapters/git-worktree.js";
 import { ensureIssueRepoCheckout, roleWorktreePathForResolution, resolveCheckoutBaseBranch, } from "../adapters/managed-repo.js";
 import { prepareWorkerDeckConnection, releaseWorkerDeckConnection } from "../adapters/agent-deck-bind.js";
 import { realGithubAdapter } from "../adapters/github.js";
@@ -104,6 +106,14 @@ const EVENT_FOR_VERDICT = {
 };
 /** Best-effort: the worker never writes, so a non-clean checkout here is unexpected, not valuable work. */
 async function bestEffortRemove(repo, worktreePath) {
+    try {
+        // NOT-384: staged visual evidence goes first, so no residue survives the
+        // attempt even when the worktree removal below fails.
+        cleanupStagedVisualArtifacts(worktreePath);
+    }
+    catch {
+        // same courtesy as below — staging cleanup must never fail the attempt
+    }
     try {
         await safeRemoveWorktree({ repo, path: worktreePath, role: "reviewer" });
     }
@@ -335,12 +345,29 @@ export async function runReviewerEffect(ctx, deps = defaultDeps) {
             const baseSha = await mergeBase({ repo: worktreePath, base: `origin/${baseBranch}`, head: headSha });
             const diff = await diffShas({ worktreePath, baseSha, headSha });
             const { truncated: diffTruncated, omittedPaths } = formatDiffForPrompt(diff);
+            // NOT-384: SHA-bound CI visual evidence for this head (never throws —
+            // every failure mode resolves to `missing` with a reason, and a missing
+            // or failed capture never counts as a visual pass).
+            const changedFiles = await listChangedFiles({ worktreePath, baseSha, headSha }).catch(() => null);
+            const visualEvidence = toReviewerVisualEvidenceInput(await resolveReviewerVisualEvidence({
+                issueId: issue.id,
+                workerSessionId: sessionId,
+                worktreePath,
+                baseSha,
+                headSha,
+                changedFiles,
+                github: deps.github,
+                fetcher: deps.visualEvidenceFetcher ?? null,
+            }));
             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);
+            // NOT-381: the latest coordinator-validated visual receipt (or loud
+            // rejection), SHA-checked against the pinned head inside the prompt section.
+            const visualQaRecord = readLatestVisualQa(issue.id);
             const prompt = buildReviewerPrompt({
                 taskSnapshot,
                 round: workItem.round,
@@ -354,6 +381,8 @@ export async function runReviewerEffect(ctx, deps = defaultDeps) {
                 deckId: snapshot?.deckId ?? null,
                 guidance: guidance.length ? guidance : undefined,
                 operatorCriteria: operatorCriteria.length > 0 ? operatorCriteria : undefined,
+                visualEvidence,
+                visualQa: visualQaRecord ? { record: visualQaRecord, pinnedHeadSha: headSha } : 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

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

@@ -728,3 +728,57 @@ test("NOT-225 regression: a non-zero reviewer exit keeps its session_failed beha
     const crashReason = outcome.reason ?? "";
     assert.ok(!crashReason.includes("could not start"), "a spawned-then-crashed session is not a setup failure");
 });
+test("NOT-384: available visual evidence stages CI artifacts under the reviewer worktree and cites them", async () => {
+    const { isWorktreeClean } = await import("../adapters/git-worktree.js");
+    const { reviewerVisualStagingDir } = await import("./reviewer-visual-evidence.js");
+    const issueId = await makeIssue();
+    const github = fakeGithub();
+    const uiSpawn = async (input) => {
+        fs.mkdirSync(path.join(input.cwd, "apps", "web", "src"), { recursive: true });
+        fs.writeFileSync(path.join(input.cwd, "apps", "web", "src", "app.tsx"), "export const App = () => null;\n");
+        git(input.cwd, "add", ".");
+        git(input.cwd, "-c", "user.email=agent@test", "-c", "user.name=Agent", "commit", "-q", "-m", "ui change");
+        return { exitCode: 0, transcript: "Implementation conclusion: changed the web app.", logPath: "/dev/null", timedOut: false };
+    };
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: uiSpawn, github }));
+    startWorkflow(issueId);
+    await pump(1);
+    assert.equal(getIssue(issueId).status, "reviewing", "test setup: UI change did not reach reviewing");
+    let seenPrompt = "";
+    let seenCwd = "";
+    let cleanDuringSpawn = null;
+    const fetcher = {
+        async findRunForHead({ headSha }) {
+            return { databaseId: 4242, headSha, conclusion: "success", status: "completed" };
+        },
+        async downloadArtifact({ name, destDir }) {
+            fs.mkdirSync(destDir, { recursive: true });
+            fs.writeFileSync(path.join(destDir, "issues-home-1440x900.png"), `png-${name}`);
+            fs.writeFileSync(path.join(destDir, "issues-home-390x800.png"), `png-${name}`);
+            if (name === "ui-diff")
+                fs.writeFileSync(path.join(destDir, "SUMMARY.md"), "## UI diff\n\nhead: `h`\n");
+        },
+    };
+    const capturingSpawn = async (input) => {
+        seenPrompt = input.prompt;
+        seenCwd = input.cwd;
+        cleanDuringSpawn = await isWorktreeClean(input.cwd);
+        return verdictSpawn({ verdict: "approved" })(input);
+    };
+    registerEffectHandler("reviewer", (ctx) => runReviewerEffect(ctx, { deckCallTool: okDeckCallTool, spawn: capturingSpawn, github, visualEvidenceFetcher: fetcher }));
+    await pump(1);
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "final_review");
+    const stagingDir = reviewerVisualStagingDir(seenCwd);
+    assert.ok(stagingDir.startsWith(seenCwd + path.sep), "staging dir is inside the reviewer worktree");
+    assert.ok(seenPrompt.includes(stagingDir), "reviewer input must name the staged directory");
+    assert.ok(seenPrompt.includes(issue.headSha), "reviewer input must cite the head SHA");
+    assert.ok(seenPrompt.includes("## UI diff"), "reviewer input must embed the diff summary");
+    assert.match(seenPrompt, /1440x900 and 390x800/);
+    assert.equal(cleanDuringSpawn, true, "the worktree reports clean with staged evidence present");
+    const visual = listArtifactsForIssue(issueId).find((a) => a.kind === "visual_evidence");
+    assert.ok(visual, "expected a recorded visual_evidence artifact");
+    assert.equal(JSON.parse(visual.contentJson).state, "available");
+    assert.equal(fs.existsSync(stagingDir), false, "the staging directory is gone after the attempt");
+    assert.equal(fs.existsSync(seenCwd), false, "the reviewer worktree is removed after the attempt");
+});