audit-tools 0.28.1 → 0.28.3

package/dist/remediate/steps/dispatch.js

@@ -1,12 +1,13 @@
 import { mkdir, rename } from "node:fs/promises";
-import { existsSync, readdirSync, readFileSync, realpathSync, statSync, symlinkSync } from "node:fs";
-import { join, relative, dirname, resolve } from "node:path";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync } from "node:fs";
+import { join, relative, dirname, resolve, isAbsolute } from "node:path";
 import { OwnershipRegistry } from "../dispatch/ownershipRegistry.js";
 import { routeAmendmentRequest } from "../dispatch/amendmentClaim.js";
 import { toBlockId, fromBlockId } from "../contractPipeline/idRegistry.js";
 import { spawnSync } from "node:child_process";
 import { StateStore } from "../state/store.js";
-import { REMEDIATION_STEP, } from "../state/types.js";
+import { REMEDIATION_STEP, isClarificationCategory, } from "../state/types.js";
+import { resolveWindowsShimSpawnCommand } from "audit-tools/shared";
 import { AGENT_FEEDBACK_FILENAME, readJsonFile, readOptionalJsonFile, writeJsonFile, writeTextFile, withFsRetry, formatValidationIssues, detectRepoConventions, formatRepoConventions, toPromptPathToken, estimateTokensFromBytes, buildQuotaSource, severityRank, findingNeedsVerificationBeforeFix, compareTier, mostCapableTier, normalizeRepoPath, hasConfiguredOpenAiCompatible, } from "audit-tools/shared";
 import { validateImplementWorkerResult } from "../validation/artifacts.js";
 import { REMEDIATION_DISPATCH_PLAN_CONTRACT_VERSION, REMEDIATION_DISPATCH_QUOTA_CONTRACT_VERSION, REMEDIATION_WORKER_RESULT_CONTRACT_VERSION, } from "./types.js";
@@ -370,6 +371,40 @@ export function createWorktree(root, worktreePath, branchName) {
         throw new Error(`git worktree add failed (exit ${result.status ?? "unknown"}):\n${stderr || stdout}`);
     }
 }
+/**
+ * Materialize into a fresh worktree any of the node's declared target paths that
+ * exist in the main tree but are absent from the worktree — i.e. git-untracked or
+ * gitignored files that `git worktree add HEAD` does not bring over. Without this
+ * a node whose scope names an untracked config file (the dogfood hit
+ * `opencode.json` and an uncommitted `.gemini/commands/*.toml`) cannot see its own
+ * target, so the edit silently no-ops. The "absent in worktree" test is the
+ * discriminator: a tracked path is already materialized from HEAD, so only the
+ * genuinely-missing untracked/ignored declarations are copied — a tracked-but-dirty
+ * file keeps its clean-from-HEAD worktree content and is never clobbered. Paths are
+ * repo-relative (the declared scope contract); absolute/escaping paths are skipped.
+ * Best-effort: a copy failure must not abort the dispatch (logged, not thrown).
+ */
+export function seedUntrackedDeclaredPaths(root, worktreeRoot, declaredPaths) {
+    for (const rel of new Set(declaredPaths)) {
+        if (!rel || isAbsolute(rel))
+            continue;
+        // Reject paths that escape the root (defence-in-depth; declared scope is
+        // repo-relative and never `..`-prefixed in practice).
+        const dst = join(worktreeRoot, rel);
+        const src = join(root, rel);
+        if (relative(worktreeRoot, dst).startsWith(".."))
+            continue;
+        if (!existsSync(src) || existsSync(dst))
+            continue;
+        try {
+            mkdirSync(dirname(dst), { recursive: true });
+            cpSync(src, dst, { recursive: true });
+        }
+        catch (err) {
+            process.stderr.write(`[remediate-code] worktree seed: could not copy untracked declared path ${rel}: ${err.message}\n`);
+        }
+    }
+}
 /** Remove a git worktree. Best-effort: logs but does not throw on failure. */
 export function removeWorktree(root, worktreePath) {
     const result = spawnSync("git", ["worktree", "remove", "--force", worktreePath], { cwd: root, encoding: "utf8", shell: false });
@@ -398,17 +433,42 @@ export function resetNodeWorktreeAndBranch(root, worktreePath, branchName) {
     spawnSync("git", ["worktree", "prune"], { cwd: root, shell: false });
     // Force-delete the leftover branch from a prior attempt so `-b` recreates it.
     spawnSync("git", ["branch", "-D", branchName], { cwd: root, shell: false });
+    // Force-remove a leftover worktree DIRECTORY: when a prior attempt's worktree
+    // became an orphaned dir (registered admin entry gone but files remain),
+    // `git worktree remove` no-ops ("is not a working tree") and `git worktree add`
+    // then refuses because the path already exists. Deleting the dir makes the
+    // re-create succeed. Best-effort.
+    if (existsSync(worktreePath)) {
+        rmSync(worktreePath, { recursive: true, force: true });
+    }
 }
 /** Run each targeted command in the worktree directory. Returns pass/fail and combined output. */
+/**
+ * Package-manager / runner shim base names that must be spawned through the
+ * command shell on Windows (their PATH entries are `.cmd` wrappers that
+ * `spawnSync(..., { shell: false })` cannot exec). Routed through the shared
+ * `resolveWindowsShimSpawnCommand` so the verify step is OS-agnostic — on
+ * non-win32 these spawn directly. Without this, every node's first verify
+ * command (`npm run build`) errors on Windows and the whole rolling implement
+ * path blocks at triage.
+ */
+const VERIFY_SHIM_BASE_NAMES = ["npm", "npx", "pnpm", "yarn"];
 export function verifyNodeInWorktree(worktreePath, targetedCommands) {
     const outputs = [];
     for (const cmd of targetedCommands) {
-        const [bin, ...args] = cmd.split(" ");
-        const r = spawnSync(bin, args, {
+        const [bin, ...rawArgs] = cmd.split(" ");
+        const { command, args } = resolveWindowsShimSpawnCommand(bin, rawArgs, VERIFY_SHIM_BASE_NAMES);
+        const r = spawnSync(command, args, {
             cwd: worktreePath,
             encoding: "utf8",
             shell: false,
         });
+        if (r.error) {
+            // Spawn itself failed (e.g. a shim not exec'able without a shell) — surface
+            // it as a verify failure with the error text rather than a silent status.
+            outputs.push(`$ ${cmd}\n${r.error.message}`);
+            return { passed: false, output: outputs.join("\n---\n") };
+        }
         const combined = [r.stdout ?? "", r.stderr ?? ""].filter(Boolean).join("\n");
         outputs.push(`$ ${cmd}\n${combined}`);
         if (r.status !== 0) {
@@ -450,6 +510,116 @@ export function mergeWorktree(root, worktreePath, branchName) {
 export function worktreePath(root, blockId, runId) {
     return join(root, ".audit-tools", "worktrees", `remediate-${blockId}-${runId}`);
 }
+/**
+ * Deterministic name of the dedicated remediation branch for a run. Derived from
+ * the stable run id (= the plan id, constant for the whole remediation) so every
+ * wave and the final report resolve the SAME branch without persisting it. Ref-safe:
+ * any character outside [A-Za-z0-9._-] collapses to '-'. Distinct from the per-node
+ * worktree branches (`remediate-<blockId>-<runId>`) — this uses a `remediation/` ref
+ * namespace so the two never collide.
+ */
+function refSafeSegment(s, fallback) {
+    return (s
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/\.{2,}/g, ".") // ".." is invalid in a git ref name
+        .replace(/^[-.]+|[-.]+$/g, "") || fallback);
+}
+export function remediationBranchName(runId) {
+    return `remediation/${refSafeSegment(runId, "run")}`;
+}
+/** Durable ref under which a failed-but-committed node's commit is preserved. */
+function quarantineRef(runId, blockId) {
+    return `refs/remediation-quarantine/${refSafeSegment(runId, "run")}/${refSafeSegment(blockId, "node")}`;
+}
+/**
+ * Preserve a failed-but-committed node's work so it can never be lost. A node that
+ * committed real edits to its worktree branch but then failed verify / the
+ * write-scope gate / the cherry-pick is about to have its worktree removed and (on
+ * the next re-dispatch) its branch force-deleted — orphaning the commit. The dogfood
+ * lost a verified fix exactly this way (the worktree was pruned before recovery).
+ * Point a durable ref at the branch tip: a ref under refs/remediation-quarantine/
+ * survives `git branch -D` and `git worktree prune`, so the work stays reachable for
+ * a manual `git cherry-pick`. Best-effort; returns the ref + commit, or null.
+ */
+export function quarantineFailedNodeCommit(root, branch, runId, blockId) {
+    const rev = spawnSync("git", ["rev-parse", "--verify", "--quiet", `${branch}^{commit}`], {
+        cwd: root,
+        encoding: "utf8",
+        shell: false,
+    });
+    if (rev.status !== 0)
+        return null;
+    const commit = (rev.stdout ?? "").trim();
+    const ref = quarantineRef(runId, blockId);
+    const upd = spawnSync("git", ["update-ref", ref, commit], {
+        cwd: root,
+        encoding: "utf8",
+        shell: false,
+    });
+    if (upd.status !== 0) {
+        process.stderr.write(`[remediate-code] could not quarantine ${branch}: ${(upd.stderr ?? "").trim()}\n`);
+        return null;
+    }
+    process.stderr.write(`[remediate-code] preserved failed node ${blockId} commit ${commit.slice(0, 8)} at ${ref} for recovery\n`);
+    return { ref, commit };
+}
+/** Clear a node's quarantine ref (e.g. once a later re-dispatch landed successfully). Best-effort. */
+export function clearQuarantinedCommit(root, runId, blockId) {
+    spawnSync("git", ["update-ref", "-d", quarantineRef(runId, blockId)], {
+        cwd: root,
+        encoding: "utf8",
+        shell: false,
+    });
+}
+/** Quarantined failed-node commits still preserved for a run, for recovery surfacing in the report. */
+export function listQuarantinedCommits(root, runId) {
+    const prefix = `refs/remediation-quarantine/${refSafeSegment(runId, "run")}/`;
+    const res = spawnSync("git", ["for-each-ref", "--format=%(refname) %(objectname)", prefix], {
+        cwd: root,
+        encoding: "utf8",
+        shell: false,
+    });
+    if (res.status !== 0 || !res.stdout)
+        return [];
+    const out = [];
+    for (const line of res.stdout.split("\n")) {
+        const [ref, commit] = line.trim().split(/\s+/);
+        if (!ref || !commit)
+            continue;
+        out.push({ block: ref.slice(prefix.length), ref, commit });
+    }
+    return out;
+}
+/**
+ * Ensure the main checkout is on the dedicated remediation branch BEFORE any node
+ * commit is cherry-picked, so accepted work lands there and the user's base branch
+ * is NEVER modified — the run leaves a feature branch for review (it does not merge
+ * back). Idempotent across waves: creates the branch from the current HEAD (the base)
+ * the first time, checks it out on later waves. Best-effort on a non-git root (the
+ * worktree dispatch flow can't run there anyway): returns null without throwing so
+ * non-git callers/tests are unaffected. Returns the branch name on success.
+ */
+export function ensureRemediationBranchCheckedOut(root, runId) {
+    const top = gitTopLevel(root);
+    if (top === null || canonicalPathKey(top) !== canonicalPathKey(root))
+        return null;
+    const branch = remediationBranchName(runId);
+    const current = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd: root,
+        encoding: "utf8",
+        shell: false,
+    });
+    if (current.status === 0 && (current.stdout ?? "").trim() === branch)
+        return branch;
+    const args = gitBranchExists(root, branch) ? ["checkout", branch] : ["checkout", "-b", branch];
+    const co = spawnSync("git", args, { cwd: root, encoding: "utf8", shell: false });
+    if (co.status !== 0) {
+        process.stderr.write(`[remediate-code] could not switch to remediation branch ${branch}: ${(co.stderr ?? "").trim()}\n`);
+        return null;
+    }
+    process.stderr.write(`[remediate-code] remediation changes land on branch ${branch} (base branch left untouched)\n`);
+    return branch;
+}
 /**
  * Stage and commit all of a worktree's edits onto its branch. The TOOL owns this
  * commit (never the worker/host) so that the branch has a real commit for two
@@ -546,7 +716,7 @@ export function acceptNodeWorktree(params) {
     if (commit.error) {
         // Could not commit the worker's edits → cannot safely land; drop it.
         removeWorktree(root, wt);
-        return { outcome: "error", verifyPassed, merged };
+        return { outcome: "error", verifyPassed, merged, diagnostic: commit.error };
     }
     if (!commit.committed) {
         // Worker reported success but made no tracked edits — nothing to verify or merge.
@@ -560,14 +730,48 @@ export function acceptNodeWorktree(params) {
     verifyPassed = verify.passed;
     if (!verify.passed) {
         // Verify failed: do not merge; drop the worktree so the main tree stays clean.
+        // The node DID commit real edits, so preserve them under a durable quarantine
+        // ref before the worktree/branch go away — a tool-verify false-negative must
+        // not destroy a good fix (the dogfood lost one this way). Carry the failing
+        // command + output so triage isn't blind on outcome:error.
+        quarantineFailedNodeCommit(root, branch, runId, blockId);
         removeWorktree(root, wt);
-        return { outcome: "error", verifyPassed, merged };
+        return { outcome: "error", verifyPassed, merged, diagnostic: verify.output };
+    }
+    // Write-scope gate (OBL-DS-06), BEFORE the cherry-pick: an out-of-scope or
+    // seam-conflicting edit must never land in the main tree, so it is adjudicated
+    // against the branch's git diff (the ground truth) here rather than reported
+    // after `mergeWorktree` already merged it. A worker that legitimately needed a
+    // file outside its declared scope declares it via `amended_files`; an unowned
+    // amendment widens the effective scope, while one owned by another block blocks.
+    if (params.scope) {
+        const decision = enforceAcceptWriteScope({
+            root,
+            branch,
+            blockId,
+            allBlockScopes: params.scope.allBlockScopes,
+            amendedFiles: params.scope.amendedFiles,
+        });
+        if (decision.blocked) {
+            // Scope-blocked but the node committed real work — preserve it for recovery.
+            quarantineFailedNodeCommit(root, branch, runId, blockId);
+            removeWorktree(root, wt);
+            return { outcome: "error", verifyPassed, merged: false, diagnostic: decision.reason };
+        }
     }
     // mergeWorktree cherry-picks the verified branch and removes the worktree (on
     // success AND on conflict-abort), so no explicit cleanup is needed afterwards.
     const mergeRes = mergeWorktree(root, wt, branch);
     merged = mergeRes.success;
-    return { outcome: mergeRes.success ? "success" : "error", verifyPassed, merged };
+    if (!mergeRes.success) {
+        // Cherry-pick conflict: the committed work would otherwise be orphaned — preserve it.
+        quarantineFailedNodeCommit(root, branch, runId, blockId);
+        return { outcome: "error", verifyPassed, merged, diagnostic: mergeRes.error };
+    }
+    // Landed successfully: clear any quarantine ref left by a prior failed attempt
+    // for this node so the recovery report lists only genuinely-unrecovered work.
+    clearQuarantinedCommit(root, runId, blockId);
+    return { outcome: "success", verifyPassed, merged };
 }
 /**
  * Sidecar path for a node's tool-owned accept (verify/merge) outcome. Written by
@@ -593,6 +797,8 @@ export async function recordNodeAcceptOutcome(artifactsDir, runId, blockId, resu
         outcome: result.outcome,
         verify_passed: result.verifyPassed,
         merged: result.merged,
+        // Only present on a failure outcome; gives triage the failing command + output.
+        ...(result.diagnostic !== undefined ? { diagnostic: result.diagnostic } : {}),
     });
 }
 /** Load a node's recorded accept outcome, or null when none was written. */
@@ -600,7 +806,12 @@ export async function loadNodeAcceptOutcome(artifactsDir, runId, blockId) {
     const raw = await readOptionalJsonFile(nodeAcceptOutcomePath(artifactsDir, runId, blockId));
     if (!raw)
         return null;
-    return { outcome: raw.outcome, verifyPassed: raw.verify_passed, merged: raw.merged };
+    return {
+        outcome: raw.outcome,
+        verifyPassed: raw.verify_passed,
+        merged: raw.merged,
+        ...(raw.diagnostic !== undefined ? { diagnostic: raw.diagnostic } : {}),
+    };
 }
 /** Read the promoted DAG-node overlay fields off a Finding (all optional). */
 function nodeFieldsOf(finding) {
@@ -1157,7 +1368,10 @@ function implementPrompt(block, state, resultPath, conventions, repoRoot, feedba
             return [];
         // item_spec may be pre-populated from the plan DAG node or absent;
         // either way the implementer receives finding context directly.
-        return [{ finding, spec: item.item_spec }];
+        // clarification_context carries the user's answer when this item was re-opened
+        // from a clarification round (up-front gate or mid-run) — thread it through so
+        // the retry acts on the decided scope, not the original ambiguity.
+        return [{ finding, spec: item.item_spec, clarification: item.clarification_context }];
     });
     // When a worktreeRoot is supplied, the worker operates in the worktree, not
     // the main repo root. Source file paths are prefixed with the worktree root.
@@ -1197,12 +1411,12 @@ Set the shell/tool workdir to the repository root when running commands; do not
 ## Items
 
 ${items
-        .map(({ finding, spec }) => `
+        .map(({ finding, spec, clarification }) => `
 ### ${finding.id} - ${finding.title}
 
 - Files: ${itemReadFiles(finding, spec).map(resolveFilePath).join(", ")}
 - Summary: ${finding.summary}
-${groundingVerificationBullet(finding)}
+${clarification ? `- Clarified scope (decided with the user — act on THIS): ${clarification}\n` : ""}${groundingVerificationBullet(finding)}
 ${spec ? `- Concrete change: ${spec.concrete_change}
 - Tests to write: ${spec.tests_to_write
         .map((test) => `${test.name}: ${test.assertions.join("; ")}`)
@@ -1253,8 +1467,15 @@ ${items
 }
 \`\`\`
 
-For an item you cannot safely finish, set \`status\` to \`blocked\` and include
-\`failure_reason\`. Stop after writing the result JSON.
+For an item you cannot safely finish because of an EXECUTION failure (a test
+won't pass, a build breaks, the change is infeasible), set \`status\` to
+\`blocked\` and include \`failure_reason\`. If instead you are stuck on a SCOPING
+or JUDGMENT question — how far the fix should reach, which of several valid
+behaviors is intended, or whether the issue is real — do NOT guess and do NOT
+block: set \`status\` to \`needs_clarification\` and put the question in
+\`clarification_question\` (optionally \`clarification_category\`). It is routed to
+the user as a real question, then re-dispatched with the answer. Stop after
+writing the result JSON.
 
 ## File access
 
@@ -1310,6 +1531,13 @@ export async function prepareImplementDispatch(options, runId, onlyBlockId, wave
         }
         return false;
     });
+    // Before any node is dispatched (and therefore before any accepted commit is
+    // cherry-picked into the main tree), switch the main checkout onto the dedicated
+    // remediation branch so all landed work accumulates there and the base branch is
+    // never modified. Idempotent across waves; only when there is work to land.
+    if (candidateBlocks.length > 0 && options.root) {
+        ensureRemediationBranchCheckedOut(options.root, runId);
+    }
     // Walk the repo for test files ONCE per dispatch (not once per block) and cache
     // their contents; collectReferencingTests then matches in memory.
     const testIndex = buildTestFileIndex(options.root);
@@ -1528,6 +1756,68 @@ export function enforceWriteScope(declaredWritePaths, edited, root) {
             `amended_files set is not trusted for this gate.`,
     };
 }
+/** Each block's declared write scope from a dispatch plan — the seed for the
+ *  accept-time write-scope gate's ownership registry (so an amended path owned by
+ *  a sibling block is recognised as a seam conflict, not silently granted). */
+export function blockScopesFromPlan(plan) {
+    return plan.items.flatMap((item) => item.block_id && item.access
+        ? [{ block_id: item.block_id, write_paths: item.access.write_paths }]
+        : []);
+}
+/**
+ * A block's declared target paths (write ∪ read) from the persisted dispatch plan
+ * — the single source of the scope the worker actually received (same authority
+ * the accept-time write-scope gate reads). Used to seed untracked declared targets
+ * into a fresh worktree (see {@link seedUntrackedDeclaredPaths}).
+ */
+export function declaredPathsFromPlan(plan, blockId) {
+    const item = plan.items.find((i) => i.block_id === blockId);
+    if (!item?.access)
+        return [];
+    return [...(item.access.write_paths ?? []), ...(item.access.read_paths ?? [])];
+}
+/**
+ * Accept-time write-scope gate (OBL-DS-06), run from `acceptNodeWorktree` AFTER
+ * the verify and BEFORE the cherry-pick so a violation PREVENTS the merge rather
+ * than being reported once the edit already landed in main. It adjudicates the
+ * worker's self-reported `amended_files` against all blocks' declared scopes via
+ * an ephemeral `OwnershipRegistry` seeded from `allBlockScopes`: an unowned
+ * amended path is granted and widens this node's effective scope (the surfaced
+ * amend path — a too-narrow declared scope no longer blocks a correct fix); a path
+ * owned by another block is a seam conflict that blocks. The gate then diffs the
+ * worktree branch (the git ground truth, never the self-report) against the
+ * effective scope. Cross-sibling contention on a file two live nodes both amend is
+ * left to the merge-time lost-update detector (`detectOverlappingEdits`), which
+ * sees the full set of merged blocks a single accept cannot.
+ */
+export function enforceAcceptWriteScope(params) {
+    const { root, branch, blockId, allBlockScopes, amendedFiles } = params;
+    const registry = new OwnershipRegistry();
+    registry.initialize(allBlockScopes.map((b) => ({ node_id: b.block_id, write_paths: b.write_paths })));
+    if (amendedFiles.length > 0) {
+        const { seam_routed } = routeAmendmentRequest(registry, blockId, amendedFiles);
+        if (seam_routed.length > 0) {
+            const detail = seam_routed
+                .map((r) => {
+                const reason = r.reason;
+                if (reason.outcome === "owned")
+                    return `${r.path} owned by ${reason.owner_node_id}`;
+                if (reason.outcome === "contended") {
+                    return `${r.path} contended by ${reason.sibling_node_id}`;
+                }
+                return r.path;
+            })
+                .join("; ");
+            return {
+                blocked: true,
+                reason: `Worker amended files owned by another block (seam conflict): ${detail}. ` +
+                    `Resolve via the seam protocol before this node can land.`,
+            };
+        }
+    }
+    const effective = registry.getScope(blockId);
+    return enforceWriteScope(effective, gitEditedFilesForBranch(root, branch), root);
+}
 // ---------------------------------------------------------------------------
 // Merge-seam: obligation-id → node remap + multi-entry collapse (tolerance)
 // ---------------------------------------------------------------------------
@@ -1608,18 +1898,28 @@ export function collapseItemResults(itemResults, aliasMap, knownFindingIds) {
             byFinding.set(targetId, normalized);
             continue;
         }
-        // Collapse: blocked dominates; merge evidence; keep first failure_reason.
+        // Collapse precedence: blocked > needs_clarification > resolved >
+        // resolved_no_change. A hard failure dominates an unanswered scoping question,
+        // which dominates an actual change, which dominates a no-change claim (a
+        // no-change claim only survives if every entry agreed nothing changed). Merge
+        // evidence; keep first failure_reason / clarification question.
         const mergedEvidence = [
             ...new Set([...(existing.evidence ?? []), ...(normalized.evidence ?? [])]),
         ];
         const status = existing.status === "blocked" || normalized.status === "blocked"
             ? "blocked"
-            : "resolved";
+            : existing.status === "needs_clarification" || normalized.status === "needs_clarification"
+                ? "needs_clarification"
+                : existing.status === "resolved" || normalized.status === "resolved"
+                    ? "resolved"
+                    : "resolved_no_change";
         byFinding.set(targetId, {
             finding_id: targetId,
             status,
             evidence: mergedEvidence.length > 0 ? mergedEvidence : undefined,
             failure_reason: existing.failure_reason ?? normalized.failure_reason,
+            clarification_question: existing.clarification_question ?? normalized.clarification_question,
+            clarification_category: existing.clarification_category ?? normalized.clarification_category,
         });
     }
     return { collapsed: [...byFinding.values()], unresolved };
@@ -1928,9 +2228,11 @@ async function mergeImplementResultsIntoState(options, runId, plan, state) {
             if (isTerminalStatus(stateItem.status)) {
                 continue;
             }
-            if (itemResult.status === "resolved") {
+            if (itemResult.status === "resolved" || itemResult.status === "resolved_no_change") {
                 const spec = stateItem.item_spec;
-                const isNoChange = specIndicatesNoChange(spec);
+                // The worker's explicit `resolved_no_change` is a no-change signal in its
+                // own right; the spec heuristic is the fallback for a plain `resolved`.
+                const isNoChange = itemResult.status === "resolved_no_change" || specIndicatesNoChange(spec);
                 if (isNoChange && !hasExecutableEvidence(itemResult.evidence)) {
                     // No-prose closure: a "verified-already-satisfied" (no-change) claim must
                     // be backed by an executable assertion (a test/build/check command +
@@ -1964,6 +2266,31 @@ async function mergeImplementResultsIntoState(options, runId, plan, state) {
                     }
                 }
             }
+            else if (itemResult.status === "needs_clarification") {
+                // Mid-run escape hatch (note 3, part B): the worker hit scoping/judgment
+                // ambiguity. Route it to a clarification round (a real user question), not
+                // to triage's retry/ignore/halt. NOT terminal — the answer re-opens it.
+                stateItem.status = "needs_clarification";
+                const question = itemResult.clarification_question ??
+                    itemResult.failure_reason ??
+                    "The worker reported unresolved scoping/judgment ambiguity.";
+                stateItem.failure_reason = question;
+                const category = isClarificationCategory(itemResult.clarification_category)
+                    ? itemResult.clarification_category
+                    : "scope_of_fix";
+                const clarifications = state.clarifications ?? [];
+                if (!clarifications.some((c) => c.finding_id === itemResult.finding_id)) {
+                    clarifications.push({
+                        finding_id: itemResult.finding_id,
+                        category,
+                        description: question,
+                    });
+                }
+                state.clarifications = clarifications;
+                // The run is paused for the batched clarification round at the single
+                // post-loop status decision below (a needs_clarification item outranks
+                // implementing/triage), so the answer is applied before any more work.
+            }
             else {
                 stateItem.status = "blocked";
                 markTerminal(stateItem);
@@ -1971,44 +2298,22 @@ async function mergeImplementResultsIntoState(options, runId, plan, state) {
                     itemResult.failure_reason ?? "Implementation worker blocked.";
             }
         }
-        // Write-scope enforcement against the worker's ACTUAL git edits
-        // (OBL-DS-06): never trust self-reported amended_files for the gate. The
-        // enforcement ground truth is the worker's worktree diff; it is applied when
-        // this block was dispatched into an isolated worktree (the rolling-dispatch
-        // flow). On the interim main-tree path there is no per-worker isolation to
-        // diff against, so the gate is skipped here rather than mistaking ambient
-        // working-tree state for this worker's edits. The decision is a pure function
-        // (`enforceWriteScope`) so it is unit-tested directly against a known edit
-        // set, and fail-closed semantics apply when git is a repo but the probe fails.
+        // Per-block ACTUAL worktree-branch edits, collected for the post-loop
+        // lost-update / overlapping-edit detection (a file edited by more than one
+        // merged block). The write-scope gate itself is NOT applied here: it runs at
+        // ACCEPT time (`acceptNodeWorktree` → `enforceAcceptWriteScope`), BEFORE the
+        // cherry-pick, so an out-of-scope edit is prevented from landing rather than
+        // reported once already merged — and a node it blocks reaches the merge as
+        // `merged:false`, routed to triage by the merge-state gate below (with the
+        // write-scope reason carried in its diagnostic). A missing branch means the
+        // interim main-tree path was used (no per-worker diff): nothing to collect.
         const worktreeBranch = worktreeBranchForBlock(blockId, runId);
-        // Resolve this block's ACTUAL worktree-branch edits ONCE when the branch
-        // exists — reused for the write-scope gate below AND the post-loop
-        // lost-update detection. A missing branch means the interim main-tree path
-        // was used (no per-worker diff): skip both checks for this block.
         const branchEdited = gitBranchExists(options.root, worktreeBranch)
             ? gitEditedFilesForBranch(options.root, worktreeBranch)
             : null;
         if (branchEdited?.available) {
             editedByBlock.push({ block_id: blockId, files: branchEdited.files });
         }
-        // Activate the write-scope gate only when this block was actually dispatched
-        // through an isolated worktree (its branch exists). A missing branch means
-        // the interim main-tree path was used — there is no per-worker diff to
-        // enforce against, so the gate is skipped (NOT fail-closed: fail-closed is
-        // for a present repo whose diff genuinely errors).
-        if (resolvedFindingIds.length > 0 && item.access && branchEdited) {
-            const decision = enforceWriteScope(item.access.write_paths, branchEdited, options.root);
-            if (decision.blocked) {
-                for (const findingId of resolvedFindingIds) {
-                    const stateItem = state.items[findingId];
-                    if (!stateItem)
-                        continue;
-                    stateItem.status = "blocked";
-                    markTerminal(stateItem);
-                    stateItem.failure_reason = decision.reason;
-                }
-            }
-        }
         // Merge-state gate (authoritative, OBL-DS-06): a node that self-reported a
         // finding "resolved" but whose tool-owned verify/merge did NOT land its edits
         // (acceptNodeWorktree returned merged:false — verify failed, a cherry-pick
@@ -2031,7 +2336,10 @@ async function mergeImplementResultsIntoState(options, runId, plan, state) {
                         `Node ${blockId} reported finding ${findingId} resolved, but its tool-owned ` +
                             `verify/merge did not land the edits (outcome=${acceptOutcome.outcome}, ` +
                             `verify_passed=${acceptOutcome.verifyPassed}, merged=false); the fix is not in ` +
-                            `the main tree. Routed to triage.`;
+                            `the main tree. Routed to triage.` +
+                            (acceptOutcome.diagnostic
+                                ? `\nFailing command output:\n${acceptOutcome.diagnostic}`
+                                : "");
                 }
             }
         }
@@ -2161,12 +2469,19 @@ async function mergeImplementResultsIntoState(options, runId, plan, state) {
     }
     process.stderr.write(`[remediate-code] dispatch: merged ${implementResolved} implement result(s), ` +
         `${implementRejected} rejected\n`);
-    // Route back to implementing while pending work remains (later dependency
-    // waves, or blocks deferred this wave because a prerequisite was still
-    // running) so the next next-step dispatches the now-ready blocks; otherwise
-    // advance to implementing → triage.
+    // A worker that reported needs_clarification (note 3, part B) outranks both
+    // implementing and triage: pause the run for the batched clarification round so
+    // the user's answer is applied before any more work is dispatched or triaged.
+    // Otherwise route back to implementing while pending work remains (later
+    // dependency waves, or blocks deferred this wave because a prerequisite was
+    // still running); else advance to triage.
+    const needsClarification = Object.values(state.items).some((it) => it.status === "needs_clarification");
     const moreToImplement = Object.values(state.items).some((it) => it.status === "pending");
-    state.status = moreToImplement ? "implementing" : "triage";
+    state.status = needsClarification
+        ? "waiting_for_clarification"
+        : moreToImplement
+            ? "implementing"
+            : "triage";
     // Single commit: StateStore.mutate writes the returned state once, under the
     // lock it already holds (OBL-INV-RSD-02 / OBL-SEAM-RSD-04). No saveState here.
     return state;