agent-dealer 1.0.0 → 1.0.1

package/bundle/server/dist/adapters/managed-repo.js

@@ -26,6 +26,17 @@ async function git(cwd, args) {
 export function managedRepoPath(identity) {
     return path.join(getExecutionRoot(), "repos", identity);
 }
+/**
+ * Test helper: mark a managed identity as having a local clone so merge cwd resolution
+ * (and similar) does not fail closed. Does not create a real git repo.
+ */
+export function stubManagedCloneForTests(repoInput) {
+    const classified = classifyIssueRepo(repoInput);
+    if (classified.kind === "managed") {
+        fs.mkdirSync(path.join(classified.repoPath, ".git"), { recursive: true });
+    }
+    return classified.repoPath;
+}
 export function managedWorktreePath(identity, sessionId, role) {
     return path.join(getExecutionRoot(), "worktrees", identity, `${sessionId}-${role}`);
 }

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

@@ -1,9 +1,11 @@
 // NOT-102 acceptance: auto-merge on/off, merge failure escalation, recent repos.
+// NOT-151: portable github.com/… issue.repo must resolve to managed clone cwd, not the identity.
 import { test, before, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-not102-"));
 const { migrate, getDb } = await import("../db/index.js");
 const { BUILTIN_AGENT_CLAUDE_ID, BUILTIN_AGENT_CURSOR_ID } = await import("@agent-dealer/shared");
@@ -14,7 +16,23 @@ const { claimWorkItem, listWorkItemsForIssue } = await import("../repository/wor
 const { startWorkflow, applyCompletion } = await import("./commands.js");
 const { ReviewerResult } = await import("./reviewer-result.js");
 const { setMergePrForTests, clearFinalizeInflightForTests } = await import("./auto-merge.js");
-before(() => migrate());
+const { managedRepoPath } = await import("../adapters/managed-repo.js");
+/** Real local checkout so resolveAutoMergeCwd accepts the default legacy repo. */
+let fixtureRepo = "";
+function initFixtureRepo() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-not102-repo-"));
+    execFileSync("git", ["init", "-b", "main"], { cwd: dir });
+    execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: dir });
+    execFileSync("git", ["config", "user.name", "Test"], { cwd: dir });
+    fs.writeFileSync(path.join(dir, "README.md"), "hi\n");
+    execFileSync("git", ["add", "."], { cwd: dir });
+    execFileSync("git", ["commit", "-m", "init"], { cwd: dir });
+    return dir;
+}
+before(() => {
+    migrate();
+    fixtureRepo = initFixtureRepo();
+});
 beforeEach(() => {
     getDb().exec(`
     DELETE FROM work_items;
@@ -40,7 +58,7 @@ function newIssue(opts = {}) {
         title: "Coordinate me",
         description: "d",
         acceptanceCriteria: "It works",
-        repo: opts.repo ?? "/repo/a",
+        repo: opts.repo ?? fixtureRepo,
         developerAgentId: BUILTIN_AGENT_CLAUDE_ID,
         reviewerAgentId: BUILTIN_AGENT_CURSOR_ID,
         baseBranch: "main",
@@ -110,7 +128,7 @@ test("autoMerge off: final_review complete undrafts+merges then marks done", asy
         assert.equal(resolved.instanceCompleted, true);
         assert.equal(resolved.triggerReflect, true);
     }
-    assert.deepEqual(calls, [{ cwd: "/repo/a", number: 42 }]);
+    assert.deepEqual(calls, [{ cwd: fixtureRepo, number: 42 }]);
     assert.equal(getIssue(issueId).status, "done");
     assert.equal(getActiveWorkflowInstance(issueId), null);
     assert.equal(listHumanActionsForIssue(issueId).filter((a) => a.status === "open").length, 0);
@@ -153,9 +171,42 @@ test("autoMerge on: reviewer approve merges PR, marks done, skips final_review h
     assert.equal(issue.status, "done");
     assert.equal(getActiveWorkflowInstance(issueId), null);
     assert.equal(listHumanActionsForIssue(issueId).filter((a) => a.actionType === "final_review").length, 0);
-    assert.deepEqual(calls, [{ cwd: "/repo/a", number: 42 }]);
+    assert.deepEqual(calls, [{ cwd: fixtureRepo, number: 42 }]);
     assert.ok(listWorkflowEventsForIssue(issueId).some((e) => e.type === "issue.completed"));
 });
+test("NOT-151: portable github.com repo merges via managed clone path, not identity string", async () => {
+    const identity = "github.com/not-so-fat/agent-dealer";
+    const managed = managedRepoPath(identity);
+    fs.mkdirSync(path.join(managed, ".git"), { recursive: true });
+    const calls = [];
+    setMergePrForTests(async (opts) => {
+        calls.push(opts);
+        return { ok: true };
+    });
+    const issueId = newIssue({ autoMerge: true, repo: identity });
+    startWorkflow(issueId);
+    await complete(issueId, cleanHandoff);
+    await complete(issueId, { kind: "verdict", result: okReview("approved") });
+    assert.equal(getIssue(issueId).status, "done");
+    assert.deepEqual(calls, [{ cwd: managed, number: 42 }]);
+    assert.notEqual(calls[0]?.cwd, identity);
+});
+test("NOT-151: missing managed clone escalates clearly without spawn gh ENOENT", async () => {
+    let mergeCalled = false;
+    setMergePrForTests(async () => {
+        mergeCalled = true;
+        return { ok: true };
+    });
+    const issueId = newIssue({ autoMerge: true, repo: "github.com/missing/no-clone" });
+    startWorkflow(issueId);
+    await complete(issueId, cleanHandoff);
+    await complete(issueId, { kind: "verdict", result: okReview("approved") });
+    assert.equal(mergeCalled, false);
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "needs_human");
+    assert.match(issue.currentIntent ?? "", /Managed clone missing/);
+    assert.doesNotMatch(issue.currentIntent ?? "", /ENOENT/);
+});
 test("autoMerge on: merge failure escalates to policy_escalation; issue not left half-done as final_review", async () => {
     setMergePrForTests(async () => ({ ok: false, reason: "required status checks failed" }));
     const issueId = newIssue({ autoMerge: true });

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

@@ -15,8 +15,15 @@
 //
 // Concurrency: finalizeAutoMerge is single-flight per issueId (in-process). Success and
 // escalate txns are also defensive if a racer already wrote done / needs_human.
+//
+// NOT-151: issue.repo is a portable GitHub identity after NOT-149 — never pass it to
+// execFile as cwd (Node reports that as misleading `spawn gh ENOENT`). Resolve via
+// classifyIssueRepo → managed/legacy local path first.
 import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
 import { promisify } from "node:util";
+import { classifyIssueRepo } from "../adapters/managed-repo.js";
 import { getDb } from "../db/index.js";
 import { getIssue, listIssues, transitionIssue } from "../repository/issues.js";
 import { appendWorkflowEvent, completeWorkflowInstance, getActiveWorkflowInstance, } from "../repository/workflow-events.js";
@@ -27,17 +34,69 @@ export const GH_MERGE_TIMEOUT_MS = 20_000;
 /** Must match projection.ts's auto_merge currentIntent — recovery keys off this string. */
 export const AUTO_MERGE_INTENT = "Auto-merging approved PR";
 const ALREADY_MERGED = /already (been )?merged|pull request is not mergeable:.*merged/i;
+/**
+ * Map issue.repo (portable identity or legacy local path) to a real filesystem cwd for
+ * `gh pr merge`. Missing managed clones fail closed with a clear reason — never hand the
+ * identity string to execFile.
+ */
+export function resolveAutoMergeCwd(repoField) {
+    try {
+        const classified = classifyIssueRepo(repoField);
+        const cwd = classified.repoPath;
+        if (classified.kind === "managed") {
+            const hasGit = fs.existsSync(path.join(cwd, ".git")) || fs.existsSync(path.join(cwd, "HEAD"));
+            if (!hasGit) {
+                return {
+                    ok: false,
+                    reason: `Managed clone missing for ${classified.identity} (${cwd}). Re-run the developer step so Dealer can clone it, or restore the checkout under execution/repos.`,
+                };
+            }
+        }
+        return { ok: true, cwd };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 /** True when Node killed the child for exceeding `timeout` (promisify(execFile)). */
 export function isGhTimeoutError(err) {
     const e = err;
     return Boolean(e.killed || e.signal === "SIGTERM");
 }
+/** True when Node failed to spawn (missing binary *or* missing cwd — both surface ENOENT). */
+export function isGhSpawnEnoent(err) {
+    const e = err;
+    if (e.code === "ENOENT")
+        return true;
+    const msg = (e.message ?? "").toLowerCase();
+    return msg.includes("spawn") && msg.includes("enoent");
+}
+/**
+ * Distinguish "cwd is not a real directory" from "gh missing on PATH" — both look like
+ * `spawn gh ENOENT` from Node. Prefer checking the cwd on disk over trusting the message.
+ */
+export function ghSpawnEnoentReason(err, cwd) {
+    if (!isGhSpawnEnoent(err))
+        return null;
+    if (!fs.existsSync(cwd)) {
+        return `invalid merge cwd (${cwd}) — path does not exist (portable issue.repo must not be used as cwd)`;
+    }
+    return "gh not on PATH — install GitHub CLI (`gh`) and ensure the daemon can see it";
+}
 /** Map an execFile failure to a stable reason string (timeout vs stderr/stdout). */
-export function ghErrorReason(err, fallback) {
+export function ghErrorReason(err, fallback, cwd) {
     const e = err;
     if (isGhTimeoutError(err)) {
         return `gh timed out after ${GH_MERGE_TIMEOUT_MS}ms`;
     }
+    if (cwd) {
+        const spawnReason = ghSpawnEnoentReason(err, cwd);
+        if (spawnReason)
+            return spawnReason;
+    }
     return (e.stderr || e.stdout || e.message || fallback).trim() || fallback;
 }
 /** Production: mark draft ready (ignore if already), then squash-merge — async + timed. */
@@ -52,7 +111,12 @@ export const realMergePr = async ({ cwd, number }) => {
     catch (err) {
         // Timeout is a hang, not "already ready" — fail closed so we do not burn another 20s on merge.
         if (isGhTimeoutError(err)) {
-            return { ok: false, reason: ghErrorReason(err, "gh pr ready failed") };
+            return { ok: false, reason: ghErrorReason(err, "gh pr ready failed", cwd) };
+        }
+        // Bad cwd / missing gh on the ready step would also fail merge — surface now.
+        const spawnReason = ghSpawnEnoentReason(err, cwd);
+        if (spawnReason) {
+            return { ok: false, reason: spawnReason };
         }
         // Already ready / not a draft — ignore; merge is the authority.
     }
@@ -65,7 +129,7 @@ export const realMergePr = async ({ cwd, number }) => {
         return { ok: true };
     }
     catch (err) {
-        const reason = ghErrorReason(err, "gh pr merge failed");
+        const reason = ghErrorReason(err, "gh pr merge failed", cwd);
         // Crash between a successful merge and the done-transition: retry must not escalate.
         if (ALREADY_MERGED.test(reason))
             return { ok: true };
@@ -118,7 +182,11 @@ async function finalizeAutoMergeOnce(issueId) {
     if (issue.prNumber == null) {
         return escalateMergeFailure(issue, instance.id, "Reviewer approved but the issue has no PR number to merge.");
     }
-    const merge = await mergePrImpl({ cwd: issue.repo, number: issue.prNumber });
+    const resolvedCwd = resolveAutoMergeCwd(issue.repo);
+    if (!resolvedCwd.ok) {
+        return escalateMergeFailure(issue, instance.id, `Auto-merge failed: ${resolvedCwd.reason}`);
+    }
+    const merge = await mergePrImpl({ cwd: resolvedCwd.cwd, number: issue.prNumber });
     if (!merge.ok) {
         return escalateMergeFailure(issue, instance.id, `Auto-merge failed: ${merge.reason}`);
     }

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

@@ -1,7 +1,17 @@
-// Unit coverage for bounded gh timeout classification (NOT-102 review finding).
-import { test } from "node:test";
+// Unit coverage for bounded gh timeout classification (NOT-102) and NOT-151 spawn ENOENT mapping.
+import { test, before } from "node:test";
 import assert from "node:assert/strict";
-import { GH_MERGE_TIMEOUT_MS, ghErrorReason, isGhTimeoutError, } from "./auto-merge.js";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-not151-unit-"));
+const { GH_MERGE_TIMEOUT_MS, ghErrorReason, ghSpawnEnoentReason, isGhTimeoutError, resolveAutoMergeCwd, } = await import("./auto-merge.js");
+const { managedRepoPath } = await import("../adapters/managed-repo.js");
+before(async () => {
+    const { migrate } = await import("../db/index.js");
+    migrate();
+});
 test("isGhTimeoutError detects killed / SIGTERM from execFile timeout", () => {
     assert.equal(isGhTimeoutError({ killed: true }), true);
     assert.equal(isGhTimeoutError({ signal: "SIGTERM" }), true);
@@ -12,3 +22,35 @@ test("ghErrorReason maps timeout before stderr", () => {
     assert.equal(ghErrorReason({ stderr: " checks failed \n" }, "fallback"), "checks failed");
     assert.equal(ghErrorReason({}, "gh pr merge failed"), "gh pr merge failed");
 });
+test("NOT-151: ghSpawnEnoentReason distinguishes bad cwd from missing gh", () => {
+    const missing = path.join(os.tmpdir(), "dealer-missing-merge-cwd-xyz");
+    assert.match(ghSpawnEnoentReason({ code: "ENOENT", message: "spawn gh ENOENT" }, missing) ?? "", /invalid merge cwd/);
+    const existing = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-merge-cwd-"));
+    assert.match(ghSpawnEnoentReason({ code: "ENOENT", message: "spawn gh ENOENT" }, existing) ?? "", /gh not on PATH/);
+    assert.equal(ghSpawnEnoentReason({ stderr: "checks failed" }, existing), null);
+});
+test("NOT-151: resolveAutoMergeCwd maps portable identity to managed path when clone exists", () => {
+    const identity = "github.com/not-so-fat/agent-dealer";
+    const managed = managedRepoPath(identity);
+    fs.mkdirSync(path.join(managed, ".git"), { recursive: true });
+    const ok = resolveAutoMergeCwd(identity);
+    assert.equal(ok.ok, true);
+    if (ok.ok)
+        assert.equal(ok.cwd, managed);
+});
+test("NOT-151: resolveAutoMergeCwd fails closed when managed clone is missing", () => {
+    const missing = resolveAutoMergeCwd("github.com/missing/not-cloned");
+    assert.equal(missing.ok, false);
+    if (!missing.ok) {
+        assert.match(missing.reason, /Managed clone missing/);
+        assert.doesNotMatch(missing.reason, /ENOENT/);
+    }
+});
+test("NOT-151: resolveAutoMergeCwd accepts a real legacy local checkout", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "legacy-merge-cwd-"));
+    execFileSync("git", ["init", "-b", "main"], { cwd: dir });
+    const ok = resolveAutoMergeCwd(dir);
+    assert.equal(ok.ok, true);
+    if (ok.ok)
+        assert.equal(ok.cwd, dir);
+});

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

@@ -3,6 +3,7 @@ import { getIssue, incrementIssueRound, incrementIssueInfraAttempts, resetIssueI
 import { appendWorkflowEvent, completeWorkflowInstance, getActiveWorkflowInstance, getWorkflowInstance, startWorkflowInstance, WorkflowAlreadyActiveError, } from "../repository/workflow-events.js";
 import { createHumanAction, findOpenHumanAction, getHumanAction, listHumanActionsForIssue, resolveHumanAction, } from "../repository/human-actions.js";
 import { reconcileFinding } from "../repository/findings.js";
+import { normalizeReviewerResult } from "./reviewer-result.js";
 import { getAgent } from "../repository/agents.js";
 import { githubIssuesSync } from "../adapters/agent-health.js";
 import { createIssueArtifact, latestIssueArtifact } from "../repository/artifacts.js";
@@ -499,12 +500,14 @@ function applyReviewer(issue, instance, item, outcome) {
         autoMerge: issue.autoMerge,
     }, issue.headSha);
     const hasVerdict = outcome.kind === "verdict";
+    // Normalize before emit/finding reconcile so remapped blocking findings (NOT-150) persist.
+    const verdictResult = outcome.kind === "verdict" ? normalizeReviewerResult(outcome.result) : null;
     const { projection, effect, advance } = projectReviewerRoute(route, issue.currentRound, hasVerdict);
     const ev = eventEmitter(issue, instance, item.workerSessionId, projection.issueStatus, issue.currentRound);
     const patch = {};
     for (const type of projection.events) {
-        if (type === "review.submitted" && outcome.kind === "verdict") {
-            ev.emit("review.submitted", { actorType: "reviewer", payload: outcome.result });
+        if (type === "review.submitted" && verdictResult) {
+            ev.emit("review.submitted", { actorType: "reviewer", payload: verdictResult });
         }
         else if (type === "worker.completed" || type === "worker.failed") {
             const session = item.workerSessionId ? getWorkerSession(item.workerSessionId) : null;
@@ -544,8 +547,8 @@ function applyReviewer(issue, instance, item, outcome) {
         patch.headSha = outcome.currentHeadSha;
     }
     // Thread reviewer findings across rounds (PRD §6.4) — every blocking/non-blocking finding.
-    if (outcome.kind === "verdict") {
-        for (const f of outcome.result.findings) {
+    if (verdictResult) {
+        for (const f of verdictResult.findings) {
             reconcileFinding({
                 issueId: issue.id,
                 fingerprint: f.fingerprint,
@@ -651,7 +654,7 @@ function applyEffect(issue, instance, effect, route, issueNow, ev, causativeItem
 function questionFor(actionType, reason, resumeAsReviewer = false) {
     switch (actionType) {
         case "final_review":
-            return "Accept and merge this work, send it back for another repair round, or close it?";
+            return "Merge this work, send it back for another repair round, or close it?";
         case "attempts_exhausted":
             return "The review-round limit is reached. Retry with a fresh round, or close the issue?";
         case "policy_escalation":
@@ -684,9 +687,9 @@ export function responseOptionsFor(actionType, resumeAsReviewer = false) {
     switch (actionType) {
         case "final_review":
             return [
-                { choice: "complete", label: "Accept — merge & mark done" },
+                { choice: "merge", label: "Merge" },
                 { choice: "repair", label: "Another repair round" },
-                { choice: "close", label: "Close without accepting" },
+                { choice: "close", label: "Close" },
             ];
         case "attempts_exhausted":
             return [
@@ -748,9 +751,11 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice) {
     if (!issue)
         return { ok: false, code: 404, error: "Issue not found" };
     const instance = getActiveWorkflowInstance(action.issueId);
-    // NOT-102: human accept must undraft+merge (never mark done while leaving a draft PR).
+    // NOT-102 / NOT-150: human Merge (or legacy "complete") must undraft+merge.
     // Park like auto-merge, then the async wrapper runs finalizeAutoMerge outside this txn.
-    if (instance && resolution.actionType === "final_review" && resolution.choice === "complete") {
+    if (instance &&
+        resolution.actionType === "final_review" &&
+        (resolution.choice === "merge" || resolution.choice === "complete")) {
         return getDb().transaction(() => {
             resolveHumanAction(actionId, resolvedBy, { choice });
             appendWorkflowEvent({
@@ -761,7 +766,7 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice) {
                 actorRef: resolvedBy,
                 stage: "final_review",
                 round: issue.currentRound,
-                payload: { actionType: "final_review", choice: "complete", pendingMerge: true },
+                payload: { actionType: "final_review", choice: resolution.choice, pendingMerge: true },
             });
             transitionIssue(issue.id, "final_review", {
                 currentOwner: "system",
@@ -966,7 +971,8 @@ function resolveLegacyTerminalAction(action, issue, resolvedBy, resolution) {
     if (resolution.choice === "close") {
         nextStatus = "closed";
     }
-    else if (resolution.actionType === "final_review" && resolution.choice === "complete") {
+    else if (resolution.actionType === "final_review" &&
+        (resolution.choice === "merge" || resolution.choice === "complete")) {
         nextStatus = "done";
     }
     else if (resolution.actionType === "final_review" && resolution.choice === "repair") {

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

@@ -17,11 +17,13 @@ const { startWorkflow, applyCompletion, resolveHumanActionAndAdvance, resolveHum
 const { ReviewerResult } = await import("./reviewer-result.js");
 const { listArtifactsForIssue } = await import("../repository/artifacts-for-issue.js");
 const { setMergePrForTests, clearFinalizeInflightForTests } = await import("./auto-merge.js");
+const { stubManagedCloneForTests } = await import("../adapters/managed-repo.js");
 before(() => migrate());
 beforeEach(() => {
     getDb().exec("DELETE FROM work_items");
     clearFinalizeInflightForTests();
     setMergePrForTests(async () => ({ ok: true }));
+    stubManagedCloneForTests("acme/app");
 });
 function newIssue(opts = {}) {
     return createIssue({
@@ -400,13 +402,16 @@ test("fail → retry → exhaust → resume → fail again does not collide with
     assert.equal(pending.length, 1, "a fresh item must be enqueued — the old (round, infraAttempts)-keyed row must not be silently reused");
     assert.notEqual(pending[0].id, firstRetryItem.id, "must be a NEW work item, not the pre-escalation retry's now-terminal row");
 });
-test("resolving policy_escalation:resume after a reviewer's escalated verdict (a real code-level question) still resumes as the developer", async () => {
+test("resolving product_scope_decision:resume after a reviewer's escalated+question resumes as the developer", async () => {
     const issueId = newIssue();
     startWorkflow(issueId);
     await complete(issueId, cleanHandoff);
-    await complete(issueId, { kind: "verdict", result: okReview("escalated") });
-    const action = listHumanActionsForIssue(issueId).find((a) => a.actionType === "policy_escalation");
-    assert.equal(action.continuationPreviewJson, null, "an escalated-verdict policy_escalation carries no reviewer-resume continuation");
+    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");
+    assert.ok(action, "true product escalate opens product_scope_decision, not policy_escalation");
     const resolved = resolveHumanActionAndAdvance(action.id, "yusuke", "resume");
     assert.equal(resolved.ok, true);
     const issue = getIssue(issueId);
@@ -414,6 +419,18 @@ test("resolving policy_escalation:resume after a reviewer's escalated verdict (a
     const pending = listWorkItemsForIssue(issueId).filter((i) => i.status === "pending");
     assert.deepEqual(pending.map((i) => i.kind), ["developer"]);
 });
+test("NOT-150: bare escalated verdict remaps to automatic repair, not policy_escalation", async () => {
+    const issueId = newIssue();
+    startWorkflow(issueId);
+    await complete(issueId, cleanHandoff);
+    await complete(issueId, { kind: "verdict", result: okReview("escalated") });
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "repairing");
+    assert.ok(!listHumanActionsForIssue(issueId).find((a) => a.actionType === "policy_escalation"));
+    assert.equal(listWorkItemsForIssue(issueId).filter((i) => i.kind === "developer" && i.status === "pending").length, 1);
+    const findings = listFindingsForIssue(issueId);
+    assert.ok(findings.some((f) => f.severity === "blocking"), "bare escalate remap must thread a blocking finding into repair");
+});
 test("a stale review re-queues a reviewer at the new head without consuming a round", async () => {
     const issueId = newIssue();
     startWorkflow(issueId);

package/bundle/server/dist/coordinator/human-resolution.js

@@ -8,7 +8,8 @@
  * reopen an issue or enqueue developer/reviewer work).
  */
 const VALID_CHOICES = {
-    final_review: ["complete", "repair", "close"],
+    // "complete" kept as a synonym for "merge" so older open actions / CLI callers still resolve.
+    final_review: ["merge", "complete", "repair", "close"],
     attempts_exhausted: ["retry", "close"],
     policy_escalation: ["resume", "close"],
     product_scope_decision: ["resume"],
@@ -52,8 +53,10 @@ export function parseHumanResolution(actionType, choice) {
 export function resolveHumanActionOutcome(resolution) {
     switch (resolution.actionType) {
         case "final_review":
-            if (resolution.choice === "complete")
+            // Merge (and legacy "complete") undraft+merge via commands.ts, then mark done.
+            if (resolution.choice === "merge" || resolution.choice === "complete") {
                 return { issueStatus: "done", workflowOutcome: "done", triggerReflect: true };
+            }
             if (resolution.choice === "repair")
                 return { issueStatus: "repairing", startNewRound: true, roundKind: "review" };
             if (resolution.choice === "close")

package/bundle/server/dist/coordinator/human-resolution.test.js

@@ -23,12 +23,24 @@ test("parseHumanResolution rejects reflection_interaction_required even though V
 test("resolveHumanActionOutcome throws rather than silently closing on an invalid choice reaching it directly", () => {
     assert.throws(() => resolveHumanActionOutcome({ actionType: "final_review", choice: "bogus" }), /Unrecognized final_review choice/);
 });
-test("final_review complete marks the issue done and triggers reflect", () => {
+test("final_review merge marks the issue done and triggers reflect", () => {
+    const result = resolveHumanActionOutcome({ actionType: "final_review", choice: "merge" });
+    assert.equal(result.issueStatus, "done");
+    assert.equal(result.workflowOutcome, "done");
+    assert.equal(result.triggerReflect, true);
+});
+test("final_review complete (legacy synonym) still marks done", () => {
     const result = resolveHumanActionOutcome({ actionType: "final_review", choice: "complete" });
     assert.equal(result.issueStatus, "done");
     assert.equal(result.workflowOutcome, "done");
     assert.equal(result.triggerReflect, true);
 });
+test("parseHumanResolution accepts merge for final_review", () => {
+    assert.deepStrictEqual(parseHumanResolution("final_review", "merge"), {
+        actionType: "final_review",
+        choice: "merge",
+    });
+});
 test("final_review repair sends the issue back for another round without reflect", () => {
     const result = resolveHumanActionOutcome({ actionType: "final_review", choice: "repair" });
     assert.equal(result.issueStatus, "repairing");

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

@@ -73,16 +73,18 @@ export function buildDeveloperPrompt(input) {
 }
 const REVIEWER_RESULT_SHAPE = '{"verdict":"approved"|"changes_requested"|"escalated","baseSha":"...","headSha":"...","acceptanceCriteriaAssessment":"...","evidenceAssessment":"...","findings":[{"fingerprint":"stable-slug","severity":"blocking"|"non_blocking","title":"...","rationale":"...","file":"...","line":0}],"risks":["..."],"productScopeQuestion":"..."}';
 function reviewerContractSection(baseSha, headSha) {
+    // Verdict table matches docs/PRD_ISSUE_COORDINATION.md §6.4 / design NOT-150 — do not drift.
     return [
         `## Required final JSON block`,
         `End your reply with exactly one fenced \`\`\`json block shaped like:`,
         REVIEWER_RESULT_SHAPE,
-        `Rules:`,
+        `Rules (verdict contract):`,
         `- Set "baseSha" to exactly "${baseSha}" and "headSha" to exactly "${headSha}" — these are the coordinator-verified SHAs you were checked out at, not values you compute.`,
         `- "fingerprint" must be a short, stable slug for the finding (e.g. "missing-null-check-args-ts") so the same issue re-found next round is recognized as recurring, not duplicated.`,
         `- "findings" holds every blocking AND non-blocking observation; "risks" is uncertainties that are not findings tied to a location.`,
-        `- Use "changes_requested" whenever any finding is "blocking". Use "approved" only when there are none.`,
-        `- Use "escalated" only when the acceptance criteria themselves are ambiguous, contradictory, or the diff reveals a missing product decision — not for ordinary code problems. Set "productScopeQuestion" to that question; omit it otherwise.`,
+        `- "approved": AC met for this tip and no finding is "blocking" (non_blocking nits allowed).`,
+        `- "changes_requested": any "blocking" finding a coding pass can address — including incomplete review because AC-critical files were omitted/truncated from the diff. List omitted paths in a blocking finding.`,
+        `- "escalated": only when acceptance criteria / product scope are ambiguous, contradictory, or need a human product call — not ordinary code defects, not "diff too large". You MUST set non-empty "productScopeQuestion"; omit the field otherwise.`,
         `- You cannot edit files, push, or publish anything — you only return this JSON. The coordinator publishes it to GitHub on your behalf.`,
     ];
 }
@@ -91,37 +93,43 @@ function reviewerContractSection(baseSha, headSha) {
  * earlier, much smaller per-file cap still truncated mid-file on a genuinely large PR,
  * cutting off before the code under review). Whole files only — never a mid-hunk cut,
  * which would be actively misleading — so a file either fits completely or is entirely
- * omitted and counted in `truncated`. `runReviewerEffect` treats `truncated: true` as
- * grounds to override whatever verdict the reviewer reports: the reviewer cannot see the
- * full revision, so no verdict against it can be trusted, and this must be enforced in
- * code — a prompt instruction alone is not a structural guarantee (the same reasoning
- * `args.ts`/`permissions.ts` already apply to enforcement in general).
+ * omitted and listed in `omittedPaths`. Truncation policy (PRD §6.4 / NOT-150): coordinator
+ * remaps illegal escalate / approved+blocking; never blind escalate → Resume|Close.
  */
 export const TOTAL_DIFF_LIMIT = 300_000;
+function pathFromDiffGitHeader(headerLine) {
+    // `diff --git a/path b/path` — prefer the b/ side; fall back to a/.
+    const m = headerLine.match(/^diff --git a\/(.+?) b\/(.+)$/);
+    if (!m)
+        return null;
+    return m[2] || m[1] || null;
+}
 export function formatDiffForPrompt(diff) {
     const trimmed = diff.trim();
     if (!trimmed)
-        return { text: "(empty diff)", truncated: false };
+        return { text: "(empty diff)", truncated: false, omittedPaths: [] };
     const blocks = trimmed.split(/(?=^diff --git )/m).filter(Boolean);
     const manifest = blocks.map((b) => b.slice(0, b.indexOf("\n"))).join("\n");
     const pieces = [];
+    const omittedPaths = [];
     let total = 0;
-    let omittedFiles = 0;
     for (const block of blocks) {
         if (total + block.length > TOTAL_DIFF_LIMIT) {
-            omittedFiles++;
+            const header = block.slice(0, block.indexOf("\n"));
+            omittedPaths.push(pathFromDiffGitHeader(header) ?? (header || "unknown"));
             continue;
         }
         pieces.push(block);
         total += block.length;
     }
-    const truncated = omittedFiles > 0;
+    const truncated = omittedPaths.length > 0;
     const footer = truncated
-        ? `\n... [${omittedFiles} changed file(s) omitted — this diff exceeds ${TOTAL_DIFF_LIMIT} characters. You cannot examine the complete revision; the coordinator will not accept "approved" or "changes_requested" from this session regardless of what you report.]`
+        ? `\n... [${omittedPaths.length} changed file(s) omitted — diff exceeds ${TOTAL_DIFF_LIMIT} characters. Omitted: ${omittedPaths.join(", ")}. If any omitted path is AC-critical, verdict MUST be "changes_requested" with a blocking finding listing those paths. If AC is still certifiable from the visible tip with only non_blocking findings, "approved" is allowed. Do NOT use "escalated" for truncation — escalate only with productScopeQuestion for a true product gap.]`
         : "";
     return {
         text: `Changed files (${blocks.length}):\n${manifest}\n\n${pieces.join("\n")}${footer}`,
         truncated,
+        omittedPaths,
     };
 }
 export function buildReviewerPrompt(input) {

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

@@ -145,6 +145,27 @@ test("reviewer prompt embeds the diff, echoes the exact SHAs to report, and forb
     assert.match(prompt, /"headSha" to exactly "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"/);
     assert.match(prompt, /You cannot edit files, push, or publish anything/);
 });
+test("NOT-150: reviewer verdict rules match the design table (blocking ⇒ changes_requested; escalate needs productScopeQuestion)", () => {
+    const prompt = buildReviewerPrompt(reviewerBase);
+    assert.match(prompt, /"approved": AC met/);
+    assert.match(prompt, /no finding is "blocking"/);
+    assert.match(prompt, /"changes_requested": any "blocking" finding/);
+    assert.match(prompt, /"escalated": only when acceptance criteria/);
+    assert.match(prompt, /MUST set non-empty "productScopeQuestion"/);
+    assert.match(prompt, /not ordinary code defects/);
+    assert.match(prompt, /not "diff too large"/);
+});
+test("NOT-150: truncated-diff footer does not reject approved/changes_requested; forbids escalate-for-truncation", async () => {
+    const { formatDiffForPrompt, TOTAL_DIFF_LIMIT } = await import("./prompts.js");
+    const big = "x".repeat(TOTAL_DIFF_LIMIT + 1);
+    const diff = `diff --git a/small.ts b/small.ts\n+ok\n\ndiff --git a/huge.ts b/huge.ts\n+${big}\n`;
+    const formatted = formatDiffForPrompt(diff);
+    assert.equal(formatted.truncated, true);
+    assert.ok(formatted.omittedPaths.some((p) => p.includes("huge.ts")));
+    assert.match(formatted.text, /changes_requested/);
+    assert.match(formatted.text, /Do NOT use "escalated" for truncation/);
+    assert.doesNotMatch(formatted.text, /will not accept "approved" or "changes_requested"/);
+});
 test("reviewer prompt includes the developer's conclusion, checks summary, and prior findings when given", () => {
     const prompt = buildReviewerPrompt({
         ...reviewerBase,

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

@@ -29,7 +29,7 @@ import { getTaskSnapshot } from "./commands.js";
 import { buildReviewerPrompt, formatDiffForPrompt, TOTAL_DIFF_LIMIT } from "./prompts.js";
 import { guidanceForNextSession } from "./guidance.js";
 import { realReviewerSpawn, reviewerSessionLogPath } from "./spawn.js";
-import { parseReviewerResult, ReviewerResult as ReviewerResultSchema } from "./reviewer-result.js";
+import { parseReviewerResult, normalizeReviewerResult, INCOMPLETE_REVIEW_FINGERPRINT, ReviewerResult as ReviewerResultSchema, } from "./reviewer-result.js";
 import { createRoleWorktree, safeRemoveWorktree, isWorktreeClean, mergeBase, fetchRef, diffShas, } from "../adapters/git-worktree.js";
 import { ensureIssueRepoCheckout, roleWorktreePathForResolution, resolveCheckoutBaseBranch, } from "../adapters/managed-repo.js";
 import { prepareWorkerDeckConnection, releaseWorkerDeckConnection } from "../adapters/agent-deck-bind.js";
@@ -108,6 +108,47 @@ async function bestEffortRemove(repo, worktreePath) {
         // leave it for crash-recovery inspection — cleanup is a courtesy, not part of the contract
     }
 }
+/** Inject a stable blocking incomplete-review finding listing omitted paths (NOT-150). */
+function withIncompleteReviewFinding(result, omittedPaths) {
+    if (result.findings.some((f) => f.fingerprint === INCOMPLETE_REVIEW_FINGERPRINT)) {
+        const { productScopeQuestion: _drop, ...rest } = result;
+        return { ...rest, verdict: "changes_requested" };
+    }
+    const paths = omittedPaths.length > 0 ? omittedPaths.join(", ") : "(unlisted omitted files)";
+    const { productScopeQuestion: _drop, ...rest } = result;
+    return {
+        ...rest,
+        verdict: "changes_requested",
+        findings: [
+            ...result.findings,
+            {
+                fingerprint: INCOMPLETE_REVIEW_FINGERPRINT,
+                severity: "blocking",
+                title: "Diff truncated — incomplete review",
+                rationale: `Reviewer prompt omitted path(s): ${paths}. Cannot fully certify acceptance criteria without them; shrink the change set or split the PR so the next review sees the full AC-critical surface.`,
+            },
+        ],
+    };
+}
+/**
+ * Truncation remap (PRD §6.4 / design NOT-150): never blind escalate → Resume|Close.
+ * Shippable approved (no blocking) stays approved; otherwise ensure changes_requested with
+ * the incomplete-review finding listing omitted paths (in addition to any other blocking).
+ */
+function applyTruncationVerdictPolicy(result, omittedPaths) {
+    const normalized = normalizeReviewerResult(result);
+    const hasProductQ = !!normalized.productScopeQuestion?.trim();
+    const hasBlocking = normalized.findings.some((f) => f.severity === "blocking");
+    if (normalized.verdict === "escalated" && hasProductQ) {
+        return normalized;
+    }
+    if (normalized.verdict === "approved" && !hasBlocking) {
+        return normalized;
+    }
+    // Truncated + not shippable-approved → changes_requested with incomplete-review (omitted paths).
+    const { productScopeQuestion: _drop, ...rest } = normalized;
+    return withIncompleteReviewFinding({ ...rest, verdict: "changes_requested" }, omittedPaths);
+}
 function readImplementationConclusion(issueId) {
     const artifact = latestIssueArtifact(issueId, "implementation_conclusion");
     if (!artifact?.contentJson)
@@ -281,7 +322,7 @@ export async function runReviewerEffect(ctx, deps = defaultDeps) {
             await fetchRef(worktreePath, baseBranch);
             const baseSha = await mergeBase({ repo: worktreePath, base: `origin/${baseBranch}`, head: headSha });
             const diff = await diffShas({ worktreePath, baseSha, headSha });
-            const { truncated: diffTruncated } = formatDiffForPrompt(diff);
+            const { truncated: diffTruncated, omittedPaths } = formatDiffForPrompt(diff);
             const openFindings = listFindingsForIssue(issue.id).filter((f) => f.status === "open" || f.status === "recurring");
             const guidance = guidanceForNextSession(issue.id, sessionId);
             const prompt = buildReviewerPrompt({
@@ -402,20 +443,23 @@ export async function runReviewerEffect(ctx, deps = defaultDeps) {
                 return { kind: "session_failed" };
             }
             result = parsed;
-            // A prompt instruction alone ("don't approve an incomplete diff") is not a structural
-            // guarantee — the same reasoning this codebase already applies to tool permissions
-            // (args.ts/permissions.ts). If the diff had to be truncated, the reviewer's verdict is
-            // overridden to "escalated" in code, regardless of what it actually reported, so a
-            // truncated review can never reach final_review or an automatic repair loop.
-            if (diffTruncated && result.verdict !== "escalated") {
+            // Truncation policy (PRD §6.4 / design NOT-150): never blind-escalate to Resume|Close.
+            // Persist evidence; remap bare escalate / approved+blocking; keep shippable approved.
+            if (diffTruncated) {
+                const reportedVerdict = result.verdict;
+                result = applyTruncationVerdictPolicy(result, omittedPaths);
                 createIssueArtifact({
                     issueId: issue.id,
                     workerSessionId: sessionId,
                     kind: "diff_truncated_evidence",
                     author: "system",
-                    content: { reportedVerdict: result.verdict, overriddenTo: "escalated", diffCharLimit: TOTAL_DIFF_LIMIT },
+                    content: {
+                        reportedVerdict,
+                        overriddenTo: result.verdict,
+                        diffCharLimit: TOTAL_DIFF_LIMIT,
+                        omittedPaths,
+                    },
                 });
-                result = { ...result, verdict: "escalated" };
             }
         }
         catch {
@@ -456,7 +500,8 @@ export async function runReviewerEffect(ctx, deps = defaultDeps) {
                 // diff). A `row` with no recorded result (still `claimed` after every wait
                 // attempt, or the winner itself failed) has nothing safe to report — escalate.
                 if (claim.row?.state === "published" && claim.row.resultJson) {
-                    const winnerResult = ReviewerResultSchema.parse(JSON.parse(claim.row.resultJson));
+                    const winnerParsed = ReviewerResultSchema.parse(JSON.parse(claim.row.resultJson));
+                    const winnerResult = normalizeReviewerResult(winnerParsed);
                     return { kind: "verdict", result: winnerResult };
                 }
                 return { kind: "publish_failed" };

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

@@ -447,7 +447,7 @@ test("publish claim: a prior claimant that recorded failure is safely reclaimed
     assert.equal(outcome.kind, "verdict", "reclaiming a failed prior claim must let publication proceed normally");
     assert.equal(github.publishCallCount(), 1);
 });
-test("diff truncated: an oversized diff forces the verdict to escalate in code, regardless of what the reviewer reports", async () => {
+test("diff truncated: AC-met approved (no blocking) stays on the approve path — never bare escalate", async () => {
     const issueId = await makeIssue();
     const github = fakeGithub();
     // A single file whose diff alone exceeds prompts.ts's TOTAL_DIFF_LIMIT (300,000 chars).
@@ -465,12 +465,70 @@ test("diff truncated: an oversized diff forces the verdict to escalate in code,
     registerEffectHandler("reviewer", (ctx) => runReviewerEffect(ctx, { deckCallTool: okDeckCallTool, spawn: verdictSpawn({ verdict: "approved" }), github }));
     await pump(1);
     const issue = getIssue(issueId);
-    assert.equal(issue.status, "needs_human", "an oversized diff must never reach final_review, even though the reviewer reported approved");
-    assert.ok(listArtifactsForIssue(issueId).find((a) => a.kind === "diff_truncated_evidence"));
-    // The override still publishes — as a COMMENT (escalated's mapped event), never as the
-    // reviewer's actually-reported APPROVE.
+    assert.equal(issue.status, "final_review", "Fixture A: truncated + approved + no blocking → final_review, not opaque escalate");
+    const truncateEvidence = listArtifactsForIssue(issueId).find((a) => a.kind === "diff_truncated_evidence");
+    assert.ok(truncateEvidence);
+    const truncateBody = JSON.parse(truncateEvidence.contentJson);
+    assert.equal(truncateBody.overriddenTo, "approved");
     const published = listArtifactsForIssue(issueId).find((a) => a.kind === "review_published");
-    assert.equal(JSON.parse(published.contentJson).event, "COMMENT");
+    assert.equal(JSON.parse(published.contentJson).event, "APPROVE");
+});
+test("diff truncated: blocking incomplete-review finding remaps to changes_requested repair, not escalate", async () => {
+    const issueId = await makeIssue();
+    const github = fakeGithub();
+    const bigFileSpawn = async (input) => {
+        const lines = Array.from({ length: 20_000 }, (_, i) => `line ${i} of a very large generated file`);
+        fs.writeFileSync(path.join(input.cwd, "big.txt"), `${lines.join("\n")}\n`);
+        git(input.cwd, "add", ".");
+        git(input.cwd, "-c", "user.email=agent@test", "-c", "user.name=Agent", "commit", "-q", "-m", "add a big file");
+        return { exitCode: 0, transcript: "Implementation conclusion: added a big file.", logPath: "/dev/null", timedOut: false };
+    };
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: bigFileSpawn, github }));
+    startWorkflow(issueId);
+    await pump(1);
+    const finding = {
+        fingerprint: "diff-omits-shared-schema-files",
+        severity: "blocking",
+        title: "Shared schema omitted",
+        rationale: "AC-critical shared schema files cannot be certified without seeing them.",
+    };
+    // Fixture B: model reported approved despite blocking (footer used to discourage changes_requested).
+    registerEffectHandler("reviewer", (ctx) => runReviewerEffect(ctx, {
+        deckCallTool: okDeckCallTool,
+        spawn: verdictSpawn({ verdict: "approved", findings: [finding] }),
+        github,
+    }));
+    await pump(1);
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "repairing", "Fixture B: blocking incomplete review → automatic repair");
+    assert.equal(issue.currentRound, 2);
+    const truncateEvidence = listArtifactsForIssue(issueId).find((a) => a.kind === "diff_truncated_evidence");
+    assert.ok(truncateEvidence);
+    assert.equal(JSON.parse(truncateEvidence.contentJson).overriddenTo, "changes_requested");
+    assert.ok(!listHumanActionsForIssue(issueId).find((a) => a.actionType === "policy_escalation"));
+});
+test("diff truncated: bare escalated remaps to changes_requested with incomplete-review finding", async () => {
+    const issueId = await makeIssue();
+    const github = fakeGithub();
+    const bigFileSpawn = async (input) => {
+        const lines = Array.from({ length: 20_000 }, (_, i) => `line ${i} of a very large generated file`);
+        fs.writeFileSync(path.join(input.cwd, "big.txt"), `${lines.join("\n")}\n`);
+        git(input.cwd, "add", ".");
+        git(input.cwd, "-c", "user.email=agent@test", "-c", "user.name=Agent", "commit", "-q", "-m", "add a big file");
+        return { exitCode: 0, transcript: "Implementation conclusion: added a big file.", logPath: "/dev/null", timedOut: false };
+    };
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: bigFileSpawn, github }));
+    startWorkflow(issueId);
+    await pump(1);
+    registerEffectHandler("reviewer", (ctx) => runReviewerEffect(ctx, { deckCallTool: okDeckCallTool, spawn: verdictSpawn({ verdict: "escalated" }), github }));
+    await pump(1);
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "repairing");
+    const truncateEvidence = listArtifactsForIssue(issueId).find((a) => a.kind === "diff_truncated_evidence");
+    assert.equal(JSON.parse(truncateEvidence.contentJson).overriddenTo, "changes_requested");
+    assert.ok(!listHumanActionsForIssue(issueId).find((a) => a.actionType === "policy_escalation"));
+    const findings = listFindingsForIssue(issueId);
+    assert.ok(findings.some((f) => f.fingerprint === "diff-truncated-incomplete-review"), "truncated bare escalate must keep incomplete-review with omitted paths");
 });
 test("changes_requested: findings thread onto the issue and a fresh developer repair round is queued", async () => {
     const issueId = await makeIssue();
@@ -500,15 +558,15 @@ test("escalated with a product scope question opens product_scope_decision", asy
     assert.ok(action);
     assert.equal(action.reason, "Should this support X?");
 });
-test("escalated with no product scope question opens policy_escalation", async () => {
+test("escalated with no product scope question remaps to automatic repair (NOT-150)", async () => {
     const issueId = await makeIssue();
     const github = fakeGithub();
     await advanceToReviewing(issueId, github);
     registerEffectHandler("reviewer", (ctx) => runReviewerEffect(ctx, { deckCallTool: okDeckCallTool, spawn: verdictSpawn({ verdict: "escalated" }), github }));
     await pump(1);
     const issue = getIssue(issueId);
-    assert.equal(issue.status, "needs_human");
-    assert.ok(listHumanActionsForIssue(issueId).find((a) => a.actionType === "policy_escalation"));
+    assert.equal(issue.status, "repairing");
+    assert.ok(!listHumanActionsForIssue(issueId).find((a) => a.actionType === "policy_escalation"));
 });
 test("stale: a head that moved since the reviewer was queued is re-reviewed at the new head, not silently published against the old one", async () => {
     const issueId = await makeIssue();

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

@@ -19,6 +19,54 @@ export const ReviewerResult = z.object({
     /** Present only when verdict is "escalated" and the reviewer identifies a missing product call. */
     productScopeQuestion: z.string().optional(),
 });
+/** Stable fingerprint for coordinator-injected incomplete-review findings (truncated diff). */
+export const INCOMPLETE_REVIEW_FINGERPRINT = "diff-truncated-incomplete-review";
+/** Stable fingerprint when bare escalate is remapped without a product question (NOT-150). */
+export const BARE_ESCALATE_REMAP_FINGERPRINT = "escalated-without-product-scope-question";
+/**
+ * Enforce PRD §6.4 / design NOT-150 invariants:
+ * - `escalated` requires a non-empty `productScopeQuestion` (else remap to `changes_requested`
+ *   with a blocking finding — never empty-findings repair)
+ * - any `blocking` finding forbids `approved` (remap to `changes_requested`)
+ * - bare escalate is never a valid routing input (avoids Resume|Close `policy_escalation`)
+ */
+export function normalizeReviewerResult(raw) {
+    const hasBlocking = raw.findings.some((f) => f.severity === "blocking");
+    const question = raw.productScopeQuestion?.trim() || undefined;
+    if (raw.verdict === "escalated") {
+        if (question) {
+            return { ...raw, productScopeQuestion: question };
+        }
+        const { productScopeQuestion: _drop, ...rest } = raw;
+        if (hasBlocking) {
+            return { ...rest, verdict: "changes_requested" };
+        }
+        return {
+            ...rest,
+            verdict: "changes_requested",
+            findings: [
+                ...raw.findings,
+                {
+                    fingerprint: BARE_ESCALATE_REMAP_FINGERPRINT,
+                    severity: "blocking",
+                    title: "Escalated without a product scope question",
+                    rationale: "Reviewer returned escalated without productScopeQuestion. Remapped to changes_requested so a coding repair can proceed; escalate only for true product ambiguity with a concrete question.",
+                },
+            ],
+        };
+    }
+    // Drop a stray productScopeQuestion on non-escalate verdicts.
+    const withoutQuestion = question
+        ? (() => {
+            const { productScopeQuestion: _drop, ...rest } = raw;
+            return rest;
+        })()
+        : raw;
+    if (withoutQuestion.verdict === "approved" && hasBlocking) {
+        return { ...withoutQuestion, verdict: "changes_requested" };
+    }
+    return withoutQuestion;
+}
 /** Mirrors the plan-triage/reflect JSON-fence parsing pattern already used elsewhere. */
 export function parseReviewerResult(text) {
     const trimmed = text.trim();
@@ -28,7 +76,7 @@ export function parseReviewerResult(text) {
         try {
             const parsed = ReviewerResult.safeParse(JSON.parse(candidate));
             if (parsed.success)
-                return parsed.data;
+                return normalizeReviewerResult(parsed.data);
         }
         catch {
             // try next candidate

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

@@ -35,11 +35,49 @@ test("accepts an escalated verdict carrying a productScopeQuestion", () => {
     const result = parseReviewerResult(`\`\`\`json\n${JSON.stringify(escalated)}\n\`\`\``);
     assert.deepEqual(result, escalated);
 });
+test("NOT-150: escalated without productScopeQuestion remaps to changes_requested", () => {
+    const bare = { ...valid, verdict: "escalated" };
+    const result = parseReviewerResult(`\`\`\`json\n${JSON.stringify(bare)}\n\`\`\``);
+    assert.equal(result?.verdict, "changes_requested");
+    assert.equal(result?.productScopeQuestion, undefined);
+    assert.ok(result?.findings.some((f) => f.severity === "blocking"));
+    assert.ok(result?.findings.some((f) => f.fingerprint === "escalated-without-product-scope-question"));
+});
+test("NOT-150: bare escalate with existing blocking findings keeps those findings", () => {
+    const bare = {
+        ...valid,
+        verdict: "escalated",
+        findings: [{ fingerprint: "real-bug", severity: "blocking", title: "Bug", rationale: "breaks" }],
+    };
+    const result = parseReviewerResult(`\`\`\`json\n${JSON.stringify(bare)}\n\`\`\``);
+    assert.equal(result?.verdict, "changes_requested");
+    assert.equal(result?.findings.length, 1);
+    assert.equal(result?.findings[0]?.fingerprint, "real-bug");
+});
+test("NOT-150: approved with a blocking finding remaps to changes_requested", () => {
+    const bad = {
+        ...valid,
+        verdict: "approved",
+        findings: [{ fingerprint: "diff-omits-shared-schema-files", severity: "blocking", title: "Omitted", rationale: "AC-critical" }],
+    };
+    const result = parseReviewerResult(`\`\`\`json\n${JSON.stringify(bad)}\n\`\`\``);
+    assert.equal(result?.verdict, "changes_requested");
+    assert.equal(result?.findings[0]?.fingerprint, "diff-omits-shared-schema-files");
+});
 test("findings carry file/line and severity through unchanged", () => {
     const withFindings = {
         ...valid,
+        verdict: "changes_requested",
         findings: [{ fingerprint: "f1", severity: "blocking", title: "Bug", rationale: "It breaks", file: "a.ts", line: 10 }],
     };
     const result = parseReviewerResult(`\`\`\`json\n${JSON.stringify(withFindings)}\n\`\`\``);
     assert.deepEqual(result, withFindings);
 });
+test("non_blocking findings on approved pass through without remapping", () => {
+    const withNits = {
+        ...valid,
+        findings: [{ fingerprint: "nit", severity: "non_blocking", title: "Nit", rationale: "Style" }],
+    };
+    const result = parseReviewerResult(`\`\`\`json\n${JSON.stringify(withNits)}\n\`\`\``);
+    assert.deepEqual(result, withNits);
+});

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

@@ -1,3 +1,5 @@
+// packages/server/src/coordinator/routing.ts
+import { normalizeReviewerResult } from "./reviewer-result.js";
 function roundsRemain(limits) {
     return limits.currentRound < limits.maxReviewRounds;
 }
@@ -145,7 +147,9 @@ export function routeReviewerOutcome(outcome, limits, pinnedHeadSha) {
     }
 }
 function routeVerdict(result, limits) {
-    switch (result.verdict) {
+    // Defense in depth: same invariants as parseReviewerResult / PRD §6.4 (NOT-150).
+    const normalized = normalizeReviewerResult(result);
+    switch (normalized.verdict) {
         case "approved":
             return limits.autoMerge ? { next: "auto_merge" } : { next: "final_review" };
         case "changes_requested":
@@ -153,8 +157,15 @@ function routeVerdict(result, limits) {
                 ? { next: "retry_developer_with_findings" }
                 : { next: "human_action", actionType: "attempts_exhausted", reason: "Reviewer requested changes and the review-round limit is reached." };
         case "escalated":
-            return result.productScopeQuestion
-                ? { next: "human_action", actionType: "product_scope_decision", reason: result.productScopeQuestion }
-                : { next: "human_action", actionType: "policy_escalation", reason: "Reviewer escalated without a resolvable code change." };
+            return normalized.productScopeQuestion
+                ? { next: "human_action", actionType: "product_scope_decision", reason: normalized.productScopeQuestion }
+                : // Illegal bare escalate — treat as changes_requested so repair can run (NOT-150).
+                    roundsRemain(limits)
+                        ? { next: "retry_developer_with_findings" }
+                        : {
+                            next: "human_action",
+                            actionType: "attempts_exhausted",
+                            reason: "Reviewer escalated without a product scope question and the review-round limit is reached.",
+                        };
     }
 }

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

@@ -253,13 +253,28 @@ test("escalated with a product scope question routes to product_scope_decision",
     const result = routeReviewerOutcome(outcome, REVIEW_ROUNDS_LEFT, PINNED_HEAD);
     assert.equal(result.actionType, "product_scope_decision");
 });
-test("escalated without a product scope question routes to policy_escalation", () => {
+test("escalated without a product scope question remaps to automatic repair (NOT-150)", () => {
     const outcome = {
         kind: "verdict",
         result: { verdict: "escalated", baseSha: "b", headSha: "h", acceptanceCriteriaAssessment: "unclear", evidenceAssessment: "ok", findings: [], risks: [] },
     };
     const result = routeReviewerOutcome(outcome, REVIEW_ROUNDS_LEFT, PINNED_HEAD);
-    assert.equal(result.actionType, "policy_escalation");
+    assert.deepStrictEqual(result, { next: "retry_developer_with_findings" });
+});
+test("approved with blocking finding remaps to changes_requested repair (NOT-150)", () => {
+    const outcome = {
+        kind: "verdict",
+        result: {
+            verdict: "approved",
+            baseSha: "b",
+            headSha: "h",
+            acceptanceCriteriaAssessment: "ok",
+            evidenceAssessment: "ok",
+            findings: [{ fingerprint: "f1", severity: "blocking", title: "Bug", rationale: "breaks" }],
+            risks: [],
+        },
+    };
+    assert.deepStrictEqual(routeReviewerOutcome(outcome, REVIEW_ROUNDS_LEFT, PINNED_HEAD), { next: "retry_developer_with_findings" });
 });
 test("stale review retries the reviewer at the freshly verified head while infra attempts remain", () => {
     const outcome = { kind: "stale", currentHeadSha: "new-head" };

package/bundle/server/dist/coordinator/worker-loop.test.js

@@ -25,6 +25,7 @@ const { runCoordinatorTick, drainCoordinator, activeAttemptCount, startCoordinat
 const { recoverCoordinator } = await import("./recovery.js");
 const { ReviewerResult } = await import("./reviewer-result.js");
 const { setMergePrForTests, clearFinalizeInflightForTests } = await import("./auto-merge.js");
+const { stubManagedCloneForTests } = await import("../adapters/managed-repo.js");
 before(() => migrate());
 // claimWorkItem / recovery scan the whole table (one loop in production); start each
 // case from an empty queue so a prior test's un-processed item is never claimed here.
@@ -32,6 +33,7 @@ beforeEach(() => {
     getDb().exec("DELETE FROM work_items");
     clearFinalizeInflightForTests();
     setMergePrForTests(async () => ({ ok: true }));
+    stubManagedCloneForTests("acme/app");
 });
 afterEach(() => resetEffectHandlers());
 function newIssue(maxReviewRounds = 3) {

package/bundle/server/dist/db/migrate-to-issues.test.js

@@ -135,6 +135,7 @@ test("a legacy run left in 'review' seeds an open final_review human action", ()
 });
 test("a migrated final_review action is resolvable end to end through the real coordinator function, for every choice", () => {
     for (const [choice, expectedStatus] of [
+        ["merge", "done"],
         ["complete", "done"],
         ["repair", "needs_human"],
         ["close", "closed"],

package/bundle/server/dist/dev-review-cli-happy-path.integration.test.js

@@ -304,8 +304,9 @@ test("agent-operated CLI: discover profiles, create + start a Dev-review issue,
     const actions = cliJson(await runCli(["action", "list"]));
     const finalReviewAction = actions.find((a) => a.issueId === issueId && a.actionType === "final_review" && a.status === "open");
     assert.ok(finalReviewAction, "the open final_review human action must be listable via `action list`");
-    assert.ok(finalReviewAction.choices.some((c) => c.choice === "complete"), "the CLI must expose the action's valid choices, including `complete`");
-    const resolved = cliJson(await runCli(["action", "resolve", finalReviewAction.id, "--choice", "complete", "--by", "cli-agent"]));
+    assert.ok(finalReviewAction.choices.some((c) => c.choice === "merge" || c.choice === "complete"), "the CLI must expose the action's valid choices, including Merge");
+    const mergeChoice = finalReviewAction.choices.find((c) => c.choice === "merge")?.choice ?? "complete";
+    const resolved = cliJson(await runCli(["action", "resolve", finalReviewAction.id, "--choice", mergeChoice, "--by", "cli-agent"]));
     assert.equal(resolved.issueStatus, "done");
     // 8. Final state, including sessions/artifacts/usage/evidence, all via the CLI.
     const final = cliJson(await runCli(["issue", "show", issueId, "--include", "evidence"]));

package/bundle/server/dist/routes/human-actions.test.js

@@ -17,6 +17,7 @@ const { listArtifactsForIssue } = await import("../repository/artifacts-for-issu
 const { createRun, getRun, transitionRun, addArtifact, updateRunFields } = await import("../repository/runs.js");
 const { pendingSendCount, getPendingOutboundDraft } = await import("../repository/outbound-drafts.js");
 const { setMergePrForTests, clearFinalizeInflightForTests } = await import("../coordinator/auto-merge.js");
+const { stubManagedCloneForTests } = await import("../adapters/managed-repo.js");
 before(() => {
     migrate();
 });
@@ -27,6 +28,7 @@ beforeEach(() => {
     clearFinalizeInflightForTests();
     // final_review:complete now undrafts+merges — never hit real `gh` from route tests.
     setMergePrForTests(async () => ({ ok: true }));
+    stubManagedCloneForTests("acme/app");
 });
 async function buildApp() {
     const app = Fastify();

package/bundle/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "main": "dist/index.js",
   "files": [
@@ -22,7 +22,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@agent-dealer/shared": "1.0.0",
+    "@agent-dealer/shared": "1.0.1",
     "@fastify/cors": "^11.0.1",
     "@fastify/static": "^8.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",

package/bundle/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/shared",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/dist/action.test.js

@@ -12,7 +12,7 @@ test("action list calls GET /api/human-actions and surfaces parsed choices", asy
             reason: "done",
             question: "Accept?",
             evidenceJson: null,
-            responseOptionsJson: JSON.stringify([{ choice: "complete", label: "Accept — merge & mark done" }]),
+            responseOptionsJson: JSON.stringify([{ choice: "merge", label: "Merge" }]),
             continuationPreviewJson: null,
             status: "open",
             resolutionJson: null,
@@ -31,7 +31,7 @@ test("action list calls GET /api/human-actions and surfaces parsed choices", asy
         assert.equal(code, 0);
         stub.assertCalled();
         const [action] = JSON.parse(printed);
-        assert.deepEqual(action.choices, [{ choice: "complete", label: "Accept — merge & mark done" }]);
+        assert.deepEqual(action.choices, [{ choice: "merge", label: "Merge" }]);
     }
     finally {
         console.log = originalLog;

package/dist/install.js

@@ -53,7 +53,7 @@ export async function runInstall(args, deps = {}) {
     if (migrateCli) {
         console.log("Prefer ~/.local/bin ahead of any npm global agent-dealer on PATH.");
     }
-    console.log("Next: agent-dealer doctor && agent-dealer start --daemon --open");
+    console.log("Next: gh auth login -h github.com (if needed) && agent-dealer doctor && agent-dealer start --daemon --open");
     if (purgeGlobal) {
         const code = deps.purgeGlobal
             ? await deps.purgeGlobal()

package/dist/lifecycle.contract.test.js

@@ -38,12 +38,12 @@ test("agent-operated CLI contract: discover profiles/issues, start, inspect choi
             { choice: "close", label: "Close" },
         ]),
         openAction("00000000-0000-4000-a000-000000000024", "final_review", [
-            { choice: "complete", label: "Accept — merge & mark done" },
+            { choice: "merge", label: "Merge" },
             { choice: "repair", label: "Request repair" },
             { choice: "close", label: "Close" },
         ]),
     ];
-    const resolutions = ["resume", "resume", "retry", "complete"];
+    const resolutions = ["resume", "resume", "retry", "merge"];
     const expected = [
         {
             path: "/api/agents",

package/dist/setup.js

@@ -18,7 +18,11 @@ export async function runSetup(options = {}) {
     fs.copyFileSync(template, envFile);
     console.log(`Created ${envFile}`);
     console.log(`Data directory: ${home}`);
-    console.log("Next: agent-dealer start --daemon");
+    console.log("Next:");
+    console.log("  1. brew install gh && gh auth login -h github.com");
+    console.log("  2. Prefer ~/.local/bin on PATH (managed install); drop shadowed npm -g binaries");
+    console.log("  3. agent-dealer doctor   # GitHub must be green before kicking issues");
+    console.log("  4. agent-dealer start --daemon");
     return 0;
 }
 export function printSetupHelp() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dealer",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Human control plane for agent execution — queue, plan approval, audit",
   "license": "MIT",
   "type": "module",