agent-dealer 1.3.1 → 1.3.3

package/bundle/server/dist/coordinator/auto-merge.js

@@ -34,6 +34,7 @@ import { triggerLinearPostMerge } from "./linear-merge-verify.js";
 import { startBaseAdvancedScan } from "./base-advanced-scan.js";
 import { runHeldWork } from "../power/host-awake-lifecycle.js";
 import { OPERATOR_VERIFICATION_RESPONSE_OPTIONS, formatOperatorCriteria, getOperatorCriteriaForIssue, hasOperatorVerificationForHead, operatorVerificationRequestId, } from "./operator-criteria.js";
+import { readVisualEvidenceHold } from "./reviewer-visual-evidence.js";
 const run = promisify(execFile);
 /** Bound each `gh` shell-out so a hang cannot freeze the coordinator process. */
 export const GH_MERGE_TIMEOUT_MS = 20_000;
@@ -339,6 +340,12 @@ async function finalizeAutoMergeOnce(issueId) {
         startBaseAdvancedScan(getIssue(issueId) ?? issue);
     return merged;
 }
+/** One visual-evidence hold, for the gate's reason/question. */
+function formatVisualHold(hold) {
+    return (`CI visual evidence for this head is ${hold.state}: ${hold.reason} ` +
+        `Head: \`${hold.headSha}\`. ` +
+        `Missing/unusable artifacts: ${hold.missingArtifacts.map((name) => `\`${name}\``).join(", ")}.`);
+}
 /**
  * NOT-314: the `[operator]` merge gate. After reviewer approve and before the
  * `gh` merge: when the frozen snapshot holds operator criteria and no result is
@@ -347,9 +354,16 @@ async function finalizeAutoMergeOnce(issueId) {
  * unmerged and the issue parks in `needs_human` with an `operator_verification`
  * action listing each criterion and its command.
  *
- * Returns null when the merge may proceed (no operator criteria, a recorded
- * result for this head, or no workflow to gate). Idempotent: a second finalize
- * for the same head reuses the open action instead of raising another.
+ * NOT-384: a UI-affecting head whose recorded CI visual evidence is `missing`
+ * or `failed` holds at the same gate — same action type, same intent, same
+ * verified/waive/repair resolutions. One open action covers the whole head
+ * (criteria and visual items together), so one recorded result releases it;
+ * no repair round is ever queued for missing evidence alone.
+ *
+ * Returns null when the merge may proceed (no operator criteria, no visual
+ * hold, a recorded result for this head, or no workflow to gate). Idempotent:
+ * a second finalize for the same head reuses the open action instead of
+ * raising another.
  *
  * Fail-closed: when operator criteria exist, every non-proceed path returns a
  * result (never null), so a missing head SHA or an unexpected status blocks the
@@ -364,9 +378,10 @@ export function gateOperatorVerification(issueId) {
         if (!active)
             return null;
         const criteria = getOperatorCriteriaForIssue(current);
-        if (criteria.length === 0)
-            return null;
         const head = current.headSha;
+        const visualHold = head ? readVisualEvidenceHold(issueId, head) : null;
+        if (criteria.length === 0 && !visualHold)
+            return null;
         if (head && hasOperatorVerificationForHead(issueId, head))
             return null;
         if (current.status === "done")
@@ -447,6 +462,8 @@ export function gateOperatorVerification(issueId) {
                 triggerReflect: false,
             };
         }
+        // One open action covers the whole head — criteria items, visual hold, or
+        // both — so reuse is by head alone, never per hold flavor.
         const existing = findOpenHumanAction(issueId, "operator_verification");
         if (existing && operatorActionHeadSha(existing) === head) {
             if (current.status !== "needs_human") {
@@ -465,15 +482,30 @@ export function gateOperatorVerification(issueId) {
             };
         }
         const shortHead = head.slice(0, 8);
-        const reason = `Reviewer approved ${shortHead}, but ${criteria.length} acceptance ` +
+        const criteriaReason = `Reviewer approved ${shortHead}, but ${criteria.length} acceptance ` +
             `${criteria.length === 1 ? "criterion requires" : "criteria require"} a human operator ` +
             `to verify (tagged [operator] in the frozen task snapshot) and no result is recorded ` +
             `for this head. The PR stays unmerged until the result is recorded:\n` +
             formatOperatorCriteria(criteria).join("\n");
+        // Criteria-only keeps the exact NOT-314 text; a visual hold appends its
+        // own section (or stands alone), always naming the head SHA and the
+        // missing artifacts.
+        const reason = !visualHold
+            ? criteriaReason
+            : criteria.length === 0
+                ? `Reviewer approved ${shortHead}, but the head changes the web app and no result is recorded ` +
+                    `for this head. The PR stays unmerged until the result is recorded:\n` +
+                    formatVisualHold(visualHold)
+                : `${criteriaReason}\nAdditionally, the head changes the web app: ${formatVisualHold(visualHold)}`;
         transitionIssue(issueId, "needs_human", {
             currentOwner: "human",
             currentIntent: OPERATOR_VERIFICATION_INTENT,
         });
+        const questionSuffix = visualHold && criteria.length === 0
+            ? `Verify the rendered UI for this head by hand and paste what you checked, waive with a reason, ` +
+                `or send the work back for another repair round?`
+            : `Paste the probe output to record verification, waive with a reason, ` +
+                `or send the work back for another repair round?`;
         // Head-pinned request_id: a concurrent finalize for the same head dedupes
         // onto this action through createHumanAction's open-request conflict path;
         // new commits after the gate get a fresh action with their own commands.
@@ -482,9 +514,14 @@ export function gateOperatorVerification(issueId) {
             workflowInstanceId: active.id,
             actionType: "operator_verification",
             reason,
-            question: `${reason}\n\nPaste the probe output to record verification, waive with a reason, ` +
-                `or send the work back for another repair round?`,
-            evidence: { operatorVerification: { criteria, headSha: head } },
+            question: `${reason}\n\n${questionSuffix}`,
+            evidence: {
+                operatorVerification: {
+                    criteria,
+                    headSha: head,
+                    ...(visualHold ? { visualEvidence: visualHold } : {}),
+                },
+            },
             responseOptions: [...OPERATOR_VERIFICATION_RESPONSE_OPTIONS],
             requestId: operatorVerificationRequestId(head),
         });

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

@@ -103,6 +103,12 @@ export function getTaskSnapshot(issue) {
  * NOT-358: the same parked-edit surface covers an open `policy_escalation` (e.g. after a
  * developer budget failure) so the owner can swap the developer and/or reviewer agent
  * profile and resume in the same worktree instead of recreating the issue.
+ *
+ * NOT-422: an open `product_scope_decision` on an active workflow is contract-editable
+ * the same way — title/description/acceptance-criteria only (no agent swap, see
+ * `parkedEditableFields`) — so the operator can adopt an amended contract and resume
+ * without aborting. A running session is checked separately by `applyParkedEdit` and
+ * the PATCH guard, which fail closed with 409.
  */
 export function canEditParkedIssue(issue) {
     if (issue.status !== "needs_human")
@@ -110,7 +116,8 @@ export function canEditParkedIssue(issue) {
     if (!getActiveWorkflowInstance(issue.id))
         return false;
     if (!findOpenHumanAction(issue.id, "attempts_exhausted") &&
-        !findOpenHumanAction(issue.id, "policy_escalation")) {
+        !findOpenHumanAction(issue.id, "policy_escalation") &&
+        !findOpenHumanAction(issue.id, "product_scope_decision")) {
         return false;
     }
     return !listWorkItemsForIssue(issue.id).some((w) => w.status === "pending" || w.status === "leased");
@@ -156,6 +163,36 @@ export const PARKED_EDITABLE_FIELDS = new Set([
     "developerAgentId",
     "reviewerAgentId",
 ]);
+/**
+ * NOT-422: the task-text subset of `PARKED_EDITABLE_FIELDS`. A product-scope pause
+ * adopts an amended contract only — repository, agents, policy, rounds, PR, branch
+ * and worktree all stay exactly as the running workflow saw them, so an agent swap
+ * at that park is a 409, not a silent accept.
+ */
+export const PARKED_TASK_EDITABLE_FIELDS = new Set([
+    "title",
+    "description",
+    "acceptanceCriteria",
+]);
+/**
+ * NOT-422: which parked-edit fields the issue's open actions allow. An open
+ * `attempts_exhausted` or `policy_escalation` keeps the full re-scope-plus-swap
+ * surface; a pure `product_scope_decision` park (neither of those open) allows
+ * the task-text subset only.
+ */
+export function parkedEditableFields(issueId) {
+    if (findOpenHumanAction(issueId, "attempts_exhausted") ||
+        findOpenHumanAction(issueId, "policy_escalation")) {
+        return PARKED_EDITABLE_FIELDS;
+    }
+    return PARKED_TASK_EDITABLE_FIELDS;
+}
+/** Human-readable field list for the parked-edit 409, matching the allowed set. */
+export function parkedEditableFieldsLabel(issueId) {
+    return parkedEditableFields(issueId) === PARKED_EDITABLE_FIELDS
+        ? "title, description, acceptanceCriteria, developerAgentId and reviewerAgentId"
+        : "title, description and acceptanceCriteria";
+}
 /**
  * NOT-358: applies a parked-issue edit (re-scope and/or agent swap) as one short
  * transaction: guard re-check + agent-profile existence + row write + `issue.reassigned`
@@ -176,12 +213,13 @@ export function applyParkedEdit(issueId, patch) {
             if (!getActiveWorkflowInstance(issueId) || !canEditParkedIssue(fresh)) {
                 return { ok: false, code: 409, error: "Cannot edit an issue with an active workflow" };
             }
-            const blocked = Object.keys(patch).filter((k) => !PARKED_EDITABLE_FIELDS.has(k));
+            const allowed = parkedEditableFields(issueId);
+            const blocked = Object.keys(patch).filter((k) => !allowed.has(k));
             if (blocked.length > 0) {
                 return {
                     ok: false,
                     code: 409,
-                    error: `Only title, description, acceptanceCriteria, developerAgentId and reviewerAgentId can be edited while parked (got: ${blocked.join(", ")})`,
+                    error: `Only ${parkedEditableFieldsLabel(issueId)} can be edited while parked (got: ${blocked.join(", ")})`,
                 };
             }
             for (const role of ["developerAgentId", "reviewerAgentId"]) {
@@ -224,12 +262,30 @@ export function applyParkedEdit(issueId, patch) {
     }
 }
 /**
- * Re-freezes the snapshot when the operator edited title/description/criteria
- * (or the contract compiled from the description); returns the changed fields
- * (empty = no-op). Source and compiled contract always re-freeze atomically —
- * one artifact write carries both, so they can never diverge.
+ * Stable identity-plus-bytes key for one attachment manifest entry. blobPath is
+ * excluded: it is content-addressed from the compared fields under an
+ * environment-local root, so it must never count as a task change.
  */
-function refreshTaskSnapshotIfEdited(issue) {
+function attachmentDiffKey(r) {
+    return JSON.stringify({
+        linearAttachmentId: r.linearAttachmentId,
+        kind: r.kind,
+        title: r.title,
+        safeFileName: r.safeFileName ?? null,
+        contentType: r.contentType ?? null,
+        sizeBytes: r.sizeBytes ?? null,
+        sha256: r.sha256 ?? null,
+        url: r.url,
+        subtitle: r.subtitle ?? null,
+        source: r.source ?? null,
+    });
+}
+/**
+ * Live-vs-frozen task diff behind both the resume re-freeze and the Issue Detail
+ * pending-snapshot notice: the fields a resume would re-freeze (empty = in sync).
+ * Read-only — freezing stays with `refreshTaskSnapshotIfEdited` below.
+ */
+export function diffTaskSnapshotFromLive(issue) {
     const frozen = getTaskSnapshot(issue);
     const liveContract = tryCompileContract(issue.description);
     const changed = [];
@@ -242,6 +298,26 @@ function refreshTaskSnapshotIfEdited(issue) {
     if (JSON.stringify(frozen.executionContract ?? null) !== JSON.stringify(liveContract ?? null)) {
         changed.push("executionContract");
     }
+    // NOT-422: a parked Linear reload can swap the attachment rows without
+    // touching the text. Without this, an attachment-only change never
+    // re-freezes on resume — the next round keeps the stale manifest (and its
+    // pruned blobs) and the amended inputs are never shown as pending.
+    const frozenManifest = (frozen.sourceAttachments ?? []).map(attachmentDiffKey).sort();
+    const liveManifest = listSourceAttachments(issue.id).map(attachmentDiffKey).sort();
+    if (JSON.stringify(frozenManifest) !== JSON.stringify(liveManifest)) {
+        changed.push("sourceAttachments");
+    }
+    return changed;
+}
+/**
+ * Re-freezes the snapshot when the operator edited title/description/criteria,
+ * the attachment manifest (or the contract compiled from the description);
+ * returns the changed fields (empty = no-op). Source and compiled contract
+ * always re-freeze atomically — one artifact write carries both, so they can
+ * never diverge.
+ */
+function refreshTaskSnapshotIfEdited(issue) {
+    const changed = diffTaskSnapshotFromLive(issue);
     if (changed.length > 0)
         freezeTaskSnapshot(issue);
     return changed;
@@ -2057,8 +2133,12 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
         // read the re-scoped task. An unedited issue writes nothing.
         // NOT-358: a policy_escalation park is editable the same way (title/description/
         // criteria as well as agent profiles), so its resume re-freezes too.
+        // NOT-422: a product_scope_decision resume re-freezes the amended contract the
+        // same way — the pre-start branch returned above, so this is the active-workflow
+        // pause only. The one-shot scope note still rides the next developer payload.
         if ((action.actionType === "attempts_exhausted" && resolution.choice === "retry") ||
-            (action.actionType === "policy_escalation" && resolution.choice === "resume")) {
+            (action.actionType === "policy_escalation" && resolution.choice === "resume") ||
+            (action.actionType === "product_scope_decision" && resolution.choice === "resume")) {
             const changedFields = refreshTaskSnapshotIfEdited(issueNow);
             if (changedFields.length > 0) {
                 ev.emit("task_snapshot.refreshed", { actorType: "human", payload: { actionId: action.id, changedFields } });

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

@@ -12,12 +12,13 @@ const { parseProfileSnapshot } = await import("@agent-dealer/shared");
 const { randomUUID } = await import("node:crypto");
 const { createIssue, getIssue, updateIssue } = await import("../repository/issues.js");
 const { listWorkflowEventsForIssue, getActiveWorkflowInstance } = await import("../repository/workflow-events.js");
-const { createHumanAction, getHumanAction, listHumanActionsForIssue } = await import("../repository/human-actions.js");
+const { createHumanAction, getHumanAction, listHumanActionsForIssue, resolveHumanAction } = await import("../repository/human-actions.js");
 const { setResumeLiveHeadReaderForTests } = await import("./resume-live-head.js");
 const { listFindingsForIssue, reconcileFinding } = await import("../repository/findings.js");
 const { cancelWorkItem, claimWorkItem, listWorkItemsForIssue, getWorkItem, enqueueWorkItem } = await import("../repository/work-items.js");
 const { createWorkerSession, completeSession, startSession, listWorkerSessionsForIssue } = await import("../repository/worker-sessions.js");
-const { startWorkflow, applyCompletion, applyParkedEdit, capWaitForIssue, resolveHumanActionAndAdvance, resolveHumanActionAndAdvanceAsync, getTaskSnapshot, canEditParkedIssue, parkCapWait, TASK_SNAPSHOT_ARTIFACT_KIND, checkIssueReadiness, abortIssue } = await import("./commands.js");
+const { startWorkflow, applyCompletion, applyParkedEdit, capWaitForIssue, resolveHumanActionAndAdvance, resolveHumanActionAndAdvanceAsync, getTaskSnapshot, diffTaskSnapshotFromLive, canEditParkedIssue, parkCapWait, TASK_SNAPSHOT_ARTIFACT_KIND, checkIssueReadiness, abortIssue } = await import("./commands.js");
+const { replaceSourceAttachments, listSourceAttachments } = await import("../repository/source-attachments.js");
 const { ReviewerResult } = await import("./reviewer-result.js");
 const { listArtifactsForIssue } = await import("../repository/artifacts-for-issue.js");
 const { setMergePrForTests, clearFinalizeInflightForTests } = await import("./auto-merge.js");
@@ -397,6 +398,231 @@ test("NOT-185: closing an edited attempts_exhausted issue does not re-freeze the
     assert.equal(resolved.ok, true);
     assert.equal(snapshotArtifacts(issueId).length, 1);
 });
+/** NOT-422: park at an active-workflow `product_scope_decision` the way a reviewer's escalated verdict does. */
+async function parkAtProductScope() {
+    const issueId = newIssue();
+    startWorkflow(issueId);
+    await complete(issueId, cleanHandoff);
+    await complete(issueId, {
+        kind: "verdict",
+        result: { ...okReview("escalated"), productScopeQuestion: "Should deleted users retain sessions?" },
+    });
+    const action = listHumanActionsForIssue(issueId).find((a) => a.actionType === "product_scope_decision");
+    return { issueId, actionId: action.id };
+}
+test("NOT-422: canEditParkedIssue is true at an open product_scope_decision with nothing pending or leased", async () => {
+    const { issueId } = await parkAtProductScope();
+    assert.equal(canEditParkedIssue(getIssue(issueId)), true);
+    const instance = getActiveWorkflowInstance(issueId);
+    const item = enqueueWorkItem({
+        issueId,
+        workflowInstanceId: instance.id,
+        kind: "developer",
+        round: 1,
+        payload: {},
+        idempotencyKey: `${instance.id}:test:n422-pending`,
+    });
+    assert.equal(canEditParkedIssue(getIssue(issueId)), false, "a pending work item blocks the edit");
+    const leased = claim(issueId);
+    assert.equal(leased.id, item.id);
+    assert.equal(canEditParkedIssue(getIssue(issueId)), false, "a leased work item blocks the edit");
+    cancelWorkItem(item.id);
+    assert.equal(canEditParkedIssue(getIssue(issueId)), true);
+});
+test("NOT-422: other open action types keep the parked-edit surface closed", async () => {
+    const { issueId, actionId } = await parkAtProductScope();
+    // Close the scope decision without advancing (repository-level): needs_human +
+    // active workflow + no open action is not contract-editable.
+    resolveHumanAction(actionId, "test", { choice: "resume" });
+    assert.equal(getIssue(issueId).status, "needs_human");
+    assert.equal(canEditParkedIssue(getIssue(issueId)), false, "no open action");
+    // And a non-contract-editable open action does not open it either.
+    createHumanAction({
+        issueId,
+        actionType: "final_review",
+        reason: "r",
+        question: "q",
+        responseOptions: [{ choice: "merge", label: "Merge" }],
+    });
+    assert.equal(canEditParkedIssue(getIssue(issueId)), false, "final_review is not contract-editable");
+    // applyParkedEdit fails closed the same way, with no row or event change.
+    const before = getIssue(issueId);
+    const eventsBefore = listWorkflowEventsForIssue(issueId).length;
+    const refused = applyParkedEdit(issueId, { title: "Nope" });
+    assert.equal(refused.ok, false);
+    if (refused.ok !== false)
+        return;
+    assert.equal(refused.code, 409);
+    assert.deepEqual(getIssue(issueId), before);
+    assert.equal(listWorkflowEventsForIssue(issueId).length, eventsBefore);
+});
+test("NOT-422: applyParkedEdit at a scope pause accepts task text but rejects swaps, locked fields, pending items and running sessions", async () => {
+    const { issueId, actionId } = await parkAtProductScope();
+    const before = getIssue(issueId);
+    const edited = applyParkedEdit(issueId, {
+        title: "Rescoped title",
+        description: "d2",
+        acceptanceCriteria: "It works, and also does Y",
+    });
+    assert.equal(edited.ok, true);
+    if (edited.ok !== true)
+        return;
+    assert.equal(edited.issue.title, "Rescoped title");
+    assert.equal(edited.issue.description, "d2");
+    assert.equal(edited.issue.acceptanceCriteria, "It works, and also does Y");
+    // Everything else stays as the running workflow saw it, the scope action
+    // stays open, and the snapshot still carries the old text until Resume.
+    assert.equal(edited.issue.repo, before.repo);
+    assert.equal(edited.issue.baseBranch, before.baseBranch);
+    assert.equal(edited.issue.developerAgentId, before.developerAgentId);
+    assert.equal(edited.issue.reviewerAgentId, before.reviewerAgentId);
+    assert.equal(edited.issue.branch, before.branch);
+    assert.equal(edited.issue.headSha, before.headSha);
+    assert.equal(getHumanAction(actionId).status, "open");
+    assert.equal(snapshotArtifacts(issueId).length, 1);
+    assert.equal(getTaskSnapshot(getIssue(issueId)).description, "d");
+    // An agent swap at a scope pause is a 409 — the task-text allowlist names no roles.
+    const swap = applyParkedEdit(issueId, { developerAgentId: BUILTIN_AGENT_CURSOR_ID });
+    assert.equal(swap.ok, false);
+    if (swap.ok !== false)
+        return;
+    assert.equal(swap.code, 409);
+    assert.match(swap.error, /Only title, description and acceptanceCriteria can be edited while parked/);
+    assert.equal(getIssue(issueId).developerAgentId, before.developerAgentId);
+    for (const patch of [{ repo: "acme/other" }, { maxReviewRounds: 5 }, { autoMerge: true }]) {
+        const blocked = applyParkedEdit(issueId, patch);
+        assert.equal(blocked.ok, false, JSON.stringify(patch));
+        if (blocked.ok !== false)
+            return;
+        assert.equal(blocked.code, 409);
+    }
+    // A pending work item blocks the edit; cancelling it re-opens the surface.
+    const instance = getActiveWorkflowInstance(issueId);
+    const item = enqueueWorkItem({
+        issueId,
+        workflowInstanceId: instance.id,
+        kind: "developer",
+        round: 1,
+        payload: {},
+        idempotencyKey: `${instance.id}:test:n422-pending-2`,
+    });
+    const queued = applyParkedEdit(issueId, { title: "Racing edit" });
+    assert.equal(queued.ok, false);
+    if (queued.ok !== false)
+        return;
+    assert.equal(queued.code, 409);
+    cancelWorkItem(item.id);
+    assert.equal(applyParkedEdit(issueId, { title: "After cancel" }).ok, true);
+    // An actively running session blocks the edit even with nothing pending/leased.
+    const session = createWorkerSession({
+        issueId,
+        role: "developer",
+        round: 1,
+        agentId: BUILTIN_AGENT_CLAUDE_ID,
+        runtime: "claude_code",
+    });
+    startSession(session.id);
+    const running = applyParkedEdit(issueId, { title: "Racing session" });
+    assert.equal(running.ok, false);
+    if (running.ok !== false)
+        return;
+    assert.equal(running.code, 409);
+    assert.match(running.error, /actively running session/);
+    completeSession(session.id, { status: "done" });
+    const afterSession = applyParkedEdit(issueId, { title: "After session" });
+    assert.equal(afterSession.ok, true);
+});
+test("NOT-422: product-scope resume after an edit freezes one new snapshot before repair.started, note still riding", async () => {
+    const { issueId, actionId } = await parkAtProductScope();
+    assert.equal(snapshotArtifacts(issueId).length, 1);
+    updateIssue(issueId, { description: "d2", acceptanceCriteria: "It works, and also does Y" });
+    const resolved = resolveHumanActionAndAdvance(actionId, "yusuke", "resume", { note: "Scope says Y" });
+    assert.equal(resolved.ok, true);
+    assert.equal(snapshotArtifacts(issueId).length, 2);
+    const snap = getTaskSnapshot(getIssue(issueId));
+    assert.equal(snap.description, "d2");
+    assert.equal(snap.acceptanceCriteria, "It works, and also does Y");
+    assert.equal(snap.title, "Coordinate me");
+    const events = listWorkflowEventsForIssue(issueId);
+    const refreshed = events.filter((e) => e.type === "task_snapshot.refreshed");
+    assert.equal(refreshed.length, 1);
+    assert.deepEqual(JSON.parse(refreshed[0].payloadJson).changedFields, ["description", "acceptanceCriteria"]);
+    assert.equal(JSON.parse(refreshed[0].payloadJson).actionId, actionId);
+    assert.equal(refreshed[0].actorType, "human");
+    const types = events.map((e) => e.type);
+    assert.ok(types.indexOf("task_snapshot.refreshed") < types.lastIndexOf("repair.started"));
+    const pending = listWorkItemsForIssue(issueId).filter((i) => i.status === "pending");
+    assert.deepEqual(pending.map((i) => [i.kind, i.round]), [["developer", 1]]);
+    // The one-shot scope-decision note still accompanies that same work item.
+    assert.equal(JSON.parse(pending[0].payloadJson).scopeDecisionNote, "Scope says Y");
+});
+test("NOT-422: product-scope resume with no edit creates no new snapshot artifact or refresh event", async () => {
+    const { issueId, actionId } = await parkAtProductScope();
+    const resolved = resolveHumanActionAndAdvance(actionId, "yusuke", "resume");
+    assert.equal(resolved.ok, true);
+    assert.equal(snapshotArtifacts(issueId).length, 1);
+    assert.equal(listWorkflowEventsForIssue(issueId).filter((e) => e.type === "task_snapshot.refreshed").length, 0);
+});
+test("NOT-422: attachment-only row change re-freezes the manifest on product-scope resume", async () => {
+    const { issueId, actionId } = await parkAtProductScope();
+    assert.equal(snapshotArtifacts(issueId).length, 1);
+    // The post-reload row state with the text untouched: a new file manifest.
+    replaceSourceAttachments(issueId, [
+        {
+            linearAttachmentId: "att-file-1",
+            kind: "file",
+            title: "repro.tar.gz",
+            safeFileName: "repro.tar.gz",
+            blobPath: "/blobs/repro.tar.gz",
+            contentType: "application/gzip",
+            sizeBytes: 12,
+            sha256: "v2-sha",
+            url: "https://uploads.linear.app/abc/repro.tar.gz",
+        },
+    ]);
+    assert.deepEqual(diffTaskSnapshotFromLive(getIssue(issueId)), ["sourceAttachments"]);
+    const resolved = resolveHumanActionAndAdvance(actionId, "yusuke", "resume");
+    assert.equal(resolved.ok, true);
+    assert.equal(snapshotArtifacts(issueId).length, 2);
+    assert.deepEqual(getTaskSnapshot(getIssue(issueId)).sourceAttachments, listSourceAttachments(issueId));
+    const events = listWorkflowEventsForIssue(issueId);
+    const refreshed = events.filter((e) => e.type === "task_snapshot.refreshed");
+    assert.equal(refreshed.length, 1);
+    assert.deepEqual(JSON.parse(refreshed[0].payloadJson).changedFields, ["sourceAttachments"]);
+    const types = events.map((e) => e.type);
+    assert.ok(types.indexOf("task_snapshot.refreshed") < types.lastIndexOf("repair.started"));
+});
+test("NOT-422: product-scope resume with an unchanged attachment manifest creates no refresh", async () => {
+    const issueId = newIssue();
+    replaceSourceAttachments(issueId, [
+        {
+            linearAttachmentId: "att-file-1",
+            kind: "file",
+            title: "repro.tar.gz",
+            safeFileName: "repro.tar.gz",
+            blobPath: "/blobs/repro.tar.gz",
+            contentType: "application/gzip",
+            sizeBytes: 12,
+            sha256: "v1-sha",
+            url: "https://uploads.linear.app/abc/repro.tar.gz",
+        },
+        { linearAttachmentId: "att-link-1", kind: "link", title: "Design doc", url: "https://docs.example.com/spec" },
+    ]);
+    startWorkflow(issueId);
+    await complete(issueId, cleanHandoff);
+    await complete(issueId, {
+        kind: "verdict",
+        result: { ...okReview("escalated"), productScopeQuestion: "Still needed?" },
+    });
+    const action = listHumanActionsForIssue(issueId).find((a) => a.actionType === "product_scope_decision");
+    // Rows frozen at start, untouched since — the diff must be empty, not a
+    // false-positive manifest change from the row round-trip.
+    assert.deepEqual(diffTaskSnapshotFromLive(getIssue(issueId)), []);
+    const resolved = resolveHumanActionAndAdvance(action.id, "yusuke", "resume");
+    assert.equal(resolved.ok, true);
+    assert.equal(snapshotArtifacts(issueId).length, 1);
+    assert.equal(listWorkflowEventsForIssue(issueId).filter((e) => e.type === "task_snapshot.refreshed").length, 0);
+});
 test("resolving policy_escalation:resume resets the infra-attempt budget without spending a review round", async () => {
     const issueId = newIssue({ maxInfraAttempts: 1 });
     startWorkflow(issueId);

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

@@ -22,6 +22,8 @@ import { getTaskSnapshot } from "./commands.js";
 import { materializeSourceAttachments, SourceAttachmentError, } from "./source-attachments.js";
 import { extractOperatorCriteria } from "./operator-criteria.js";
 import { buildDeveloperPrompt } from "./prompts.js";
+import { VISUAL_QA_EXCLUDE_LINE, collectDeveloperVisualQa } from "./visual-qa.js";
+import { ensureWorktreeExcluded } from "../adapters/worktree-exclude.js";
 import { guidanceForNextSession } from "./guidance.js";
 import { realDeveloperSpawn, developerSessionLogPath } from "./spawn.js";
 import { ensureWorktreeDeps, worktreeDepsTimeoutMs, } from "../adapters/worktree-deps.js";
@@ -1093,6 +1095,16 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
             : `source attachment materialization failed: ${String(err)}`;
         return { kind: "adapter_failure", reason };
     }
+    // NOT-381: git-ignore the transient visual-QA directory before the session
+    // spawns, so worker screenshots neither dirty the tree (which would break the
+    // verification receipt's clean gate and the handoff's clean check) nor get
+    // swept into a salvage commit — screenshots must never reach the product repo.
+    try {
+        ensureWorktreeExcluded(worktreePath, VISUAL_QA_EXCLUDE_LINE);
+    }
+    catch (err) {
+        return { kind: "adapter_failure", reason: `visual-QA worktree exclude failed: ${String(err)}` };
+    }
     // NOT-172: capture the worktree HEAD as this session's input-SHA baseline before
     // the agent spawns — developer work items are never enqueued with an input SHA,
     // so without this the sampler's HEAD diff (and the session_end fallback) have
@@ -1255,6 +1267,9 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
             worktreePath,
             deckId: snapshot?.deckId ?? null,
             museDeveloper: isMuse,
+            // NOT-381: runtime-aware visual-QA guidance (Muse preflight vs the
+            // capable-runtime in-session attempt).
+            runtime,
             guidance: guidance.length ? guidance : undefined,
             scopeDecisionNote,
             conflictRepair,
@@ -1947,6 +1962,27 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
                 publishable: { branch: branchName },
             };
         }
+        // NOT-381: collect the structured Visual QA receipt against the just-pushed
+        // head, before the checks wait. Accepted screenshots move to Dealer-owned
+        // storage and the transient worktree directory is removed; a rejection is
+        // persisted loudly but never blocks the handoff — visual QA is evidence
+        // for review, not a gate, so a bad receipt must not burn another round.
+        try {
+            const visual = collectDeveloperVisualQa({
+                issueId: issue.id,
+                sessionId,
+                worktreePath,
+                conclusion: extractConclusion(spawned.transcript),
+                expectedHeadSha: localHead,
+            });
+            if (visual.kind === "rejected") {
+                console.warn(`[dealer] visual QA receipt rejected for ${issue.id}: ${visual.reason}`);
+            }
+        }
+        catch (err) {
+            // Evidence must never fail the handoff it describes.
+            console.warn(`[dealer] visual QA collection failed for ${issue.id}: ${String(err)}`);
+        }
         milestone("checks.started", `Developer · waiting on checks (round ${round})`, {
             prNumber: prView.number,
             headSha: prView.headRefOid,