agent-dealer 1.3.1 → 1.3.2

package/bundle/server/dist/adapters/git-worktree.js

@@ -18,6 +18,17 @@ import { withRepoLock } from "../runners/process-registry.js";
  * Kept inside the repo (not `$AGENT_DEALER_HOME`) so `agent-deck use` grants cover the
  * worker cwd and `bind_workspace` to that path can succeed. */
 export const WORKTREES_DIR_NAME = ".agent-dealer-worktrees";
+/** Directory name for coordinator-staged CI visual artifacts inside a reviewer
+ * worktree (NOT-384). The reviewer has no shell, so it cannot list the worktree
+ * root itself — but its file tools read paths the prompt names, and only paths
+ * inside the worktree are readable under Claude Code's `--restricted` file
+ * confinement. The directory is untracked and ignored by `isWorktreeClean`
+ * below, so staged evidence never reads as reviewer dirt. It only ever exists
+ * in detached-HEAD reviewer checkouts (developer sessions never create it); a
+ * developer-side file of the same hidden name would be ignored by the clean
+ * check too, but salvage (`git add -A`) still sweeps it up, so nothing is lost —
+ * and the coordinator never stages it anywhere but a reviewer worktree. */
+export const REVIEWER_VISUAL_STAGING_DIR_NAME = ".agent-dealer-visual";
 const execFileAsync = promisify(execFile);
 const gitCommandObservers = new Set();
 /** Registers `observer` for every adapter `git` invocation; returns the unsubscribe. */
@@ -214,8 +225,34 @@ export async function removeWorktree(opts) {
 async function readOnlyStatus(worktreePath) {
     return (await git(worktreePath, ["--no-optional-locks", "status", "--porcelain"])).stdout;
 }
+/** True when a `git status --porcelain` line names only the coordinator-staged
+ * visual-evidence directory (NOT-384) — `?? .agent-dealer-visual/` for the
+ * untracked dir, or a path under it. Anything else on the line means real dirt. */
+function isVisualStagingStatusLine(line) {
+    const entry = line.slice(0, 2);
+    if (entry !== "??")
+        return false;
+    const shown = line.slice(3).trim().replace(/^"|"$/g, "");
+    return shown === REVIEWER_VISUAL_STAGING_DIR_NAME || shown.startsWith(`${REVIEWER_VISUAL_STAGING_DIR_NAME}/`);
+}
 export async function isWorktreeClean(worktreePath) {
-    return (await readOnlyStatus(worktreePath)).trim().length === 0;
+    const out = (await readOnlyStatus(worktreePath)).trim();
+    if (!out)
+        return true;
+    return out
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0)
+        .every(isVisualStagingStatusLine);
+}
+/** Repo-relative paths changed between `baseSha` and `headSha` (NOT-384: the
+ * UI-affecting classifier's input). Empty when the SHAs match. */
+export async function listChangedFiles(opts) {
+    const { stdout } = await git(opts.worktreePath, ["diff", "--name-only", opts.baseSha, opts.headSha]);
+    return stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
 }
 /** Commit message for a timeout salvage tip (NOT-145). */
 export const SALVAGE_TIMEOUT_MESSAGE = "wip: timeout salvage";

package/bundle/server/dist/adapters/github.js

@@ -334,6 +334,17 @@ export function formatChecksFailureDetails(opts) {
     }
     return parts.join("\n");
 }
+export function parseWorkflowRunInfo(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const row = raw;
+    if (typeof row.databaseId !== "number" || typeof row.headSha !== "string" || !row.headSha) {
+        return null;
+    }
+    const conclusion = typeof row.conclusion === "string" && row.conclusion ? row.conclusion : null;
+    const status = typeof row.status === "string" && row.status ? row.status : null;
+    return { databaseId: row.databaseId, headSha: row.headSha, conclusion, status };
+}
 const NO_COMMITS_PATTERN = /no commits between/i;
 const defaultExec = (args, opts) => run("gh", args, { cwd: opts.cwd, maxBuffer: opts.maxBuffer });
 async function ghPrView(exec, cwd, fields, selector) {
@@ -407,6 +418,45 @@ export function createGithubAdapter(exec = defaultExec) {
                 return "UNKNOWN";
             }
         },
+        async listWorkflowRunsForCommit({ cwd, workflow, commitSha }) {
+            try {
+                const { stdout } = await exec([
+                    "run",
+                    "list",
+                    "--workflow",
+                    workflow,
+                    "--commit",
+                    commitSha,
+                    "--limit",
+                    "5",
+                    "--json",
+                    "databaseId,headSha,conclusion,status",
+                ], { cwd });
+                const rows = JSON.parse(stdout);
+                if (!Array.isArray(rows))
+                    return [];
+                const runs = [];
+                for (const row of rows) {
+                    const parsed = parseWorkflowRunInfo(row);
+                    if (parsed)
+                        runs.push(parsed);
+                }
+                return runs;
+            }
+            catch (err) {
+                const message = err.stderr ?? err.message;
+                throw new Error(`gh run list failed: ${message}`);
+            }
+        },
+        async downloadRunArtifact({ cwd, runId, name, destDir }) {
+            try {
+                await exec(["run", "download", String(runId), "--name", name, "--dir", destDir], { cwd });
+            }
+            catch (err) {
+                const message = err.stderr ?? err.message;
+                throw new Error(`gh run download failed: ${message}`);
+            }
+        },
         async publishReview({ cwd, number, event, bodyFilePath }) {
             const result = await runReview(exec, cwd, number, event, bodyFilePath);
             if (result.ok || event === "COMMENT" || !OWN_PR_REVIEW_PATTERN.test(result.reason)) {

package/bundle/server/dist/adapters/github.test.js

@@ -1,7 +1,7 @@
 // packages/server/src/adapters/github.test.ts
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { parsePrView, summarizeChecks, pollPrChecks, pollPrChecksDetailed, baseRefHasPullRequestWorkflow, workflowHasPullRequestTrigger, createGithubAdapter, fetchChecksFailureEvidence, sanitizeCiText, sanitizeUrl, extractActionsRunId, buildFailureExcerpt, formatChecksFailureDetails, CHECKS_EVIDENCE_MAX_EXCERPT_CHARS, CHECKS_EVIDENCE_MAX_EXCERPT_LINES, CHECKS_EVIDENCE_MAX_RAW_LOG_CHARS_PER_RUN, CHECKS_EVIDENCE_GH_LOG_MAX_BUFFER, CHECKS_FAILURE_GENERIC_REASON, PR_VIEW_FIELDS, } from "./github.js";
+import { parsePrView, summarizeChecks, pollPrChecks, pollPrChecksDetailed, baseRefHasPullRequestWorkflow, workflowHasPullRequestTrigger, createGithubAdapter, fetchChecksFailureEvidence, sanitizeCiText, sanitizeUrl, extractActionsRunId, buildFailureExcerpt, formatChecksFailureDetails, CHECKS_EVIDENCE_MAX_EXCERPT_CHARS, CHECKS_EVIDENCE_MAX_EXCERPT_LINES, CHECKS_EVIDENCE_MAX_RAW_LOG_CHARS_PER_RUN, CHECKS_EVIDENCE_GH_LOG_MAX_BUFFER, CHECKS_FAILURE_GENERIC_REASON, PR_VIEW_FIELDS, parseWorkflowRunInfo, } from "./github.js";
 test("parsePrView extracts the ground-truth handoff fields, including draft status", () => {
     const view = parsePrView(JSON.stringify({
         number: 7,
@@ -814,3 +814,91 @@ test("NOT-252: formatChecksFailureDetails labels the excerpt as untrusted, not i
     });
     assert.match(noExcerpt, /excerpt unavailable/);
 });
+test("NOT-384: listWorkflowRunsForCommit filters by workflow and exact commit, parsing runs", async () => {
+    const { exec, calls } = queuedExec([
+        {
+            stdout: JSON.stringify([
+                { databaseId: 42, headSha: HEAD_SHA, conclusion: "success", status: "completed" },
+                { databaseId: 41, headSha: "other", conclusion: null, status: "in_progress" },
+            ]),
+        },
+    ]);
+    const runs = await createGithubAdapter(exec).listWorkflowRunsForCommit({
+        cwd: "/repo",
+        workflow: "visual.yml",
+        commitSha: HEAD_SHA,
+    });
+    assert.deepEqual(calls[0], [
+        "run",
+        "list",
+        "--workflow",
+        "visual.yml",
+        "--commit",
+        HEAD_SHA,
+        "--limit",
+        "5",
+        "--json",
+        "databaseId,headSha,conclusion,status",
+    ]);
+    assert.deepEqual(runs, [
+        { databaseId: 42, headSha: HEAD_SHA, conclusion: "success", status: "completed" },
+        { databaseId: 41, headSha: "other", conclusion: null, status: "in_progress" },
+    ]);
+});
+test("NOT-384: listWorkflowRunsForCommit returns [] when the workflow never ran, skips malformed rows, throws on gh failure", async () => {
+    const empty = queuedExec([{ stdout: "[]" }]);
+    assert.deepEqual(await createGithubAdapter(empty.exec).listWorkflowRunsForCommit({
+        cwd: "/repo",
+        workflow: "visual.yml",
+        commitSha: HEAD_SHA,
+    }), []);
+    const malformed = queuedExec([
+        {
+            stdout: JSON.stringify([
+                { databaseId: "nope", headSha: HEAD_SHA },
+                { databaseId: 42 },
+                null,
+                { databaseId: 43, headSha: HEAD_SHA, conclusion: "", status: "" },
+            ]),
+        },
+    ]);
+    assert.deepEqual(await createGithubAdapter(malformed.exec).listWorkflowRunsForCommit({
+        cwd: "/repo",
+        workflow: "visual.yml",
+        commitSha: HEAD_SHA,
+    }), [{ databaseId: 43, headSha: HEAD_SHA, conclusion: null, status: null }]);
+    const failing = queuedExec([{ error: "HTTP 401" }]);
+    await assert.rejects(createGithubAdapter(failing.exec).listWorkflowRunsForCommit({
+        cwd: "/repo",
+        workflow: "visual.yml",
+        commitSha: HEAD_SHA,
+    }), /gh run list failed/);
+});
+test("NOT-384: parseWorkflowRunInfo rejects rows without a numeric id and head SHA", () => {
+    assert.equal(parseWorkflowRunInfo(null), null);
+    assert.equal(parseWorkflowRunInfo({ databaseId: 1 }), null);
+    assert.equal(parseWorkflowRunInfo({ databaseId: 1, headSha: "" }), null);
+    assert.deepEqual(parseWorkflowRunInfo({ databaseId: 1, headSha: "h" }), {
+        databaseId: 1,
+        headSha: "h",
+        conclusion: null,
+        status: null,
+    });
+});
+test("NOT-384: downloadRunArtifact downloads one named artifact into the dest dir, throwing on gh failure", async () => {
+    const { exec, calls } = queuedExec([{ stdout: "" }]);
+    await createGithubAdapter(exec).downloadRunArtifact({
+        cwd: "/repo",
+        runId: 42,
+        name: "ui-diff",
+        destDir: "/store/ui-diff",
+    });
+    assert.deepEqual(calls[0], ["run", "download", "42", "--name", "ui-diff", "--dir", "/store/ui-diff"]);
+    const failing = queuedExec([{ error: "no such artifact" }]);
+    await assert.rejects(createGithubAdapter(failing.exec).downloadRunArtifact({
+        cwd: "/repo",
+        runId: 42,
+        name: "ui-diff",
+        destDir: "/store/ui-diff",
+    }), /gh run download failed/);
+});

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