agent-dealer 1.2.3 → 1.2.5

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

@@ -401,6 +401,91 @@ test("NOT-178: a Muse Code developer without credentials is refused at admission
         setAdmissionHealthCheckerForTests(async () => ({ ok: true }));
     }
 });
+// NOT-277: a Muse Code auto-update is re-validated automatically. A version whose developer
+// shell/write check passes is admitted with no manual step; one that lost it is refused with the
+// versions and capability named; one whose check could not complete is refused, never assumed ok.
+test("NOT-277: a Muse Code update is admitted when capable, refused by name when not", async () => {
+    const { clearAgentHealthCaches, runtimeIssuesUncached } = await import("../adapters/agent-health.js");
+    const { setMuseCapabilityProbeForTests, settleMuseCapabilityCheckForTests } = await import("../adapters/muse-capability.js");
+    const OLD = "1.3.0-R3401.1";
+    const NEW = "1.4.0-R4161.1";
+    const BROKEN = "1.4.0-R4302.1";
+    const stubDir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-stub-"));
+    const versionFile = path.join(stubDir, "version");
+    const stub = path.join(stubDir, "muse");
+    fs.writeFileSync(stub, `#!/bin/sh\ncat ${JSON.stringify(versionFile)}\n`);
+    fs.chmodSync(stub, 0o755);
+    // The real checker's async path runs `gh auth status` too; CI runners have no gh login,
+    // so a logged-in stub keeps the `ok: true` assertions about Muse alone.
+    const ghStub = path.join(stubDir, "gh");
+    fs.writeFileSync(ghStub, "#!/bin/sh\necho 'Logged in to github.com account dealer-test'\nexit 0\n");
+    fs.chmodSync(ghStub, 0o755);
+    const probed = [];
+    setMuseCapabilityProbeForTests(async (version) => {
+        probed.push(version);
+        if (version === BROKEN)
+            return { status: "missing", detail: "probe session completed without running its shell command" };
+        if (version === "9.9.9-R1")
+            throw new Error("probe session timed out");
+        return { status: "capable" };
+    });
+    const saved = {
+        MUSE_CLI: process.env.MUSE_CLI,
+        META_API_KEY: process.env.META_API_KEY,
+        SKIP: process.env.AGENT_DEALER_SKIP_AGENT_HEALTH,
+        PATH: process.env.PATH,
+    };
+    process.env.MUSE_CLI = stub;
+    process.env.PATH = `${stubDir}${path.delimiter}${process.env.PATH ?? ""}`;
+    process.env.META_API_KEY = "k";
+    delete process.env.AGENT_DEALER_SKIP_AGENT_HEALTH;
+    setAdmissionHealthCheckerForTests(null);
+    clearAgentHealthCaches();
+    /** Muse reports `version`; the next health read sees it and its one-time check settles. */
+    const museReports = async (version) => {
+        fs.writeFileSync(versionFile, `Muse Code ${version.split("-")[0]} (${version})\n`);
+        await runtimeIssuesUncached("muse_code");
+        await settleMuseCapabilityCheckForTests();
+    };
+    try {
+        const issue = readyIssue("muse-updated", { runtimes: { dev: "muse_code", rev: "codex_local" } });
+        const developerHealth = () => checkRoleAgentHealthy(issue, "developer", { deckOnline: true });
+        await museReports(OLD);
+        assert.deepEqual(await developerHealth(), { ok: true });
+        await museReports(NEW);
+        assert.deepEqual(await developerHealth(), { ok: true });
+        assert.deepEqual(probed, [OLD, NEW]);
+        await museReports(BROKEN);
+        enqueueIssue(issue.id);
+        assert.equal(await admitNext(), null);
+        assert.equal(getIssue(issue.id).status, "ready");
+        assert.equal(getActiveWorkflowInstance(issue.id), null);
+        const reason = getQueuedEntryForIssue(issue.id).waitReason;
+        assert.match(reason, /developer unhealthy/);
+        assert.match(reason, new RegExp(`Muse Code updated ${NEW} → ${BROKEN}: developer sessions no longer get shell/write access`));
+        await museReports("9.9.9-R1");
+        const unverified = await developerHealth();
+        assert.equal(unverified.ok, false);
+        assert.match(unverified.reason, new RegExp(`Could not verify Muse Code developer shell/write access after version change \\(${BROKEN} → 9\\.9\\.9-R1\\)`));
+        assert.deepEqual(probed, [OLD, NEW, BROKEN, "9.9.9-R1"]);
+    }
+    finally {
+        for (const [key, value] of Object.entries({
+            MUSE_CLI: saved.MUSE_CLI,
+            META_API_KEY: saved.META_API_KEY,
+            AGENT_DEALER_SKIP_AGENT_HEALTH: saved.SKIP,
+            PATH: saved.PATH,
+        })) {
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+        setMuseCapabilityProbeForTests(null);
+        clearAgentHealthCaches();
+        setAdmissionHealthCheckerForTests(async () => ({ ok: true }));
+    }
+});
 // NOT-178: Muse Code is developer-only, so it is never a healthy reviewer — even with the
 // unit-test health skip on, and without probing the CLI.
 test("NOT-178: a Muse Code reviewer is refused regardless of CLI health", async () => {

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

@@ -28,7 +28,7 @@ import { reasonForWorkerFailedEvent } from "./failure-reason.js";
 import { recordCausesForWorkerFailedEvent } from "./failure-cause.js";
 import { routeDeveloperOutcome, routeReviewerOutcome, } from "./routing.js";
 import { projectDeveloperRoute, projectReviewerRoute } from "./projection.js";
-import { MERGE_FAILURE_EVIDENCE_KEY, MERGE_FAILURE_RESPONSE_OPTIONS, PUSH_DIVERGENCE_EVIDENCE_KEY, PUSH_DIVERGENCE_RESPONSE_OPTIONS, parseHumanResolution, resolveHumanActionOutcome, } from "./human-resolution.js";
+import { MERGE_FAILURE_EVIDENCE_KEY, MERGE_FAILURE_RESPONSE_OPTIONS, PUSH_DIVERGENCE_EVIDENCE_KEY, PUSH_DIVERGENCE_RESPONSE_OPTIONS, normalizeResolutionNote, parseHumanResolution, resolveHumanActionOutcome, } from "./human-resolution.js";
 import { AUTO_MERGE_INTENT, finalizeAutoMerge } from "./auto-merge.js";
 import { externalMergeStateForIssue } from "./external-merge.js";
 import { detectNonConvergence, formatNonConvergenceReason, reviewHistoryFromEvents, } from "./non-convergence.js";
@@ -197,7 +197,7 @@ export function activeWorkflowConflictMessage(issueId) {
  * the gate stays on startWorkflow; clearing a stale gate after AC lands lives here so
  * admitNext cannot leave it dangling.
  */
-export function startWorkflowCore(issueId) {
+export function startWorkflowCore(issueId, opts) {
     const issue = getIssue(issueId);
     if (!issue)
         throw new StartPreconditionError(404, "Issue not found");
@@ -233,7 +233,12 @@ export function startWorkflowCore(issueId) {
         workflowInstanceId: instance.id,
         kind: "developer",
         round: 1,
-        payload: { profileSnapshot: queuedProfileSnapshot(issue, "developer") },
+        payload: {
+            profileSnapshot: queuedProfileSnapshot(issue, "developer"),
+            // NOT-272: carry the scope decision only on this first round's payload — later
+            // rounds never see it (the prompt reads it from here, not from the DB).
+            ...(opts?.scopeDecisionNote ? { scopeDecisionNote: opts.scopeDecisionNote } : {}),
+        },
         idempotencyKey: `${instance.id}:developer:1`,
     });
     // NOT-103: every successful start is a force-admit — keep queue state in sync whether
@@ -982,10 +987,23 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
         return { ok: false, code: 404, error: "Human action not found" };
     if (action.status !== "open")
         return { ok: false, code: 409, error: "Human action already resolved" };
-    const resolution = parseHumanResolution(action.actionType, choice);
+    // NOT-272: same shape validation as the HTTP route (which already applied it) —
+    // defense in depth for direct/CLI callers of this sync entry point.
+    const normalizedNote = normalizeResolutionNote(opts?.note);
+    if (!normalizedNote.ok)
+        return { ok: false, code: 400, error: normalizedNote.error };
+    const resolution = parseHumanResolution(action.actionType, choice, normalizedNote.note);
     if (!resolution) {
         return { ok: false, code: 400, error: `Invalid choice "${choice}" for ${action.actionType}` };
     }
+    // NOT-272: the typed resolution carries the note only for product_scope_decision
+    // (parseHumanResolution drops it for every other action type).
+    const scopeDecisionNote = resolution.actionType === "product_scope_decision" && "note" in resolution
+        ? resolution.note
+        : undefined;
+    const storedResolution = scopeDecisionNote
+        ? { choice, note: scopeDecisionNote }
+        : { choice };
     // NOT-194: narrow policy_escalation choices per action. A merge-failure action offers
     // retry_merge/repair/close only (resume would re-run development on approved work);
     // every other policy_escalation keeps resume/close only. Pre-NOT-194 open merge-failure
@@ -1077,7 +1095,7 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
         }
         try {
             return getDb().transaction(() => {
-                resolveHumanAction(actionId, resolvedBy, { choice });
+                resolveHumanAction(actionId, resolvedBy, storedResolution);
                 appendWorkflowEvent({
                     issueId: issue.id,
                     type: "human_action.resolved",
@@ -1086,7 +1104,10 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
                     stage: issue.status,
                     payload: { actionType: action.actionType, choice },
                 });
-                const { workItem } = startWorkflowCore(issue.id);
+                // NOT-272: this branch is always product_scope_decision (legacy terminal
+                // actions returned above) — the note rides the round-1 payload so the very
+                // next developer round reads it in its prompt.
+                const { workItem } = startWorkflowCore(issue.id, { scopeDecisionNote: scopeDecisionNote });
                 return {
                     ok: true,
                     issueStatus: getIssue(issue.id).status,
@@ -1165,7 +1186,7 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
                     : {};
     return getDb().transaction(() => {
         resolveHumanAction(actionId, resolvedBy, {
-            choice,
+            ...storedResolution,
             // NOT-226: record the re-pin so the resolved action itself shows which head the
             // reviewer was re-queued at when the branch had moved while parked.
             ...(rePinnedResumeHeadSha
@@ -1285,7 +1306,12 @@ export function resolveHumanActionAndAdvance(actionId, resolvedBy, choice, opts)
                 workflowInstanceId: instance.id,
                 kind: "developer",
                 round: issueNow.currentRound,
-                payload: { profileSnapshot: queuedProfileSnapshot(issue, "developer") },
+                payload: {
+                    profileSnapshot: queuedProfileSnapshot(issue, "developer"),
+                    // NOT-272: a product_scope_decision note rides only this next round's
+                    // payload — later rounds never see it.
+                    ...(scopeDecisionNote ? { scopeDecisionNote } : {}),
+                },
                 idempotencyKey: `${instance.id}:developer:resume:${action.id}`,
             });
         return {
@@ -1347,6 +1373,7 @@ export async function resolveHumanActionAndAdvanceAsync(actionId, resolvedBy, ch
     const result = resolveHumanActionAndAdvance(actionId, resolvedBy, choice, {
         resumeLiveHeadSha,
         externalMergeState,
+        note: opts?.note,
     });
     if (!result.ok || !result.pendingMerge)
         return result;

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

@@ -782,6 +782,11 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
         const openFindings = listFindingsForIssue(issue.id).filter((f) => f.status === "open" || f.status === "recurring");
         const guidance = guidanceForNextSession(issue.id, sessionId);
         const retryReason = payload.retryReason ?? undefined;
+        // NOT-272: the scope note rides only the work item queued by the resolution —
+        // exactly this round reads it; nothing is re-read from the DB.
+        const scopeDecisionNote = typeof payload.scopeDecisionNote === "string" && payload.scopeDecisionNote.trim()
+            ? payload.scopeDecisionNote.trim()
+            : undefined;
         let priorConclusion;
         let priorVerificationReceipt;
         if (retryReason) {
@@ -816,6 +821,7 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
             deckId: isMuse ? null : (snapshot?.deckId ?? null),
             noAgentDeck: isMuse,
             guidance: guidance.length ? guidance : undefined,
+            scopeDecisionNote,
         });
         // NOT-83 review finding: the session is marked `running` (worker-loop.ts) before this
         // handler ever runs, so an abort landing during worktree setup/deck-bind above already
@@ -1286,13 +1292,41 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
             author: "system",
             blobPath: spawned.logPath,
         });
+        // NOT-275: a clean exit (exitCode 0, not timed out, no usage cap) that leaves
+        // the worktree dirty hit the same escalation as a crash before this — the
+        // session did real ticket-scoped work but never ran `git commit`. Salvage
+        // first (same mechanism as the crash/timeout path above): on success fall
+        // through to push/PR as if the agent had committed itself; only when the
+        // salvage commit itself fails do we escalate dirty_worktree with recovery.
         if (!(await isWorktreeClean(worktreePath))) {
-            return {
-                kind: "dirty_worktree",
-                reason: reasonForDirtyWorktree(spawned.logPath, runtime),
-                path: worktreePath,
-                recoveryCommands: dirtyWorktreeRecoveryCommands(repoPath, worktreePath),
-            };
+            const salvaged = await salvageDirtyWorktree(worktreePath, "crash");
+            if (!salvaged.ok) {
+                return {
+                    kind: "dirty_worktree",
+                    reason: `${reasonForDirtyWorktree(spawned.logPath, runtime)} Auto-commit salvage failed: ${salvaged.reason}`,
+                    path: worktreePath,
+                    recoveryCommands: dirtyWorktreeRecoveryCommands(repoPath, worktreePath),
+                };
+            }
+            // NOT-172: durable salvage-commit checkpoint at the existing success point.
+            try {
+                emitCheckpointObserved({
+                    issueId: issue.id,
+                    workflowInstanceId: instance.id,
+                    workerSessionId: sessionId,
+                    role: "developer",
+                    stage,
+                    round,
+                    kind: "commit",
+                    observedSha: salvaged.commitSha,
+                    origin: "salvage",
+                    inputSha: samplerInputSha,
+                    branch: branchName,
+                });
+            }
+            catch {
+                // checkpoint evidence must never fail the attempt itself
+            }
         }
         const ahead = await commitsAhead({ worktreePath, baseRef: `origin/${baseBranch}` });
         if (ahead === 0) {

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

@@ -109,11 +109,6 @@ const commitingSpawn = async (input) => {
 };
 /** Never touches the worktree — nothing to push, the no_pr outcome. */
 const noopSpawn = async () => ({ exitCode: 0, transcript: "", logPath: "/dev/null", timedOut: false });
-/** Leaves an untracked file uncommitted — the dirty_worktree outcome. */
-const dirtySpawn = async (input) => {
-    fs.writeFileSync(path.join(input.cwd, "scratch.txt"), "oops\n");
-    return { exitCode: 0, transcript: "", logPath: "/dev/null", timedOut: false };
-};
 const crashingSpawn = async () => ({ exitCode: 1, transcript: "boom", logPath: "/dev/null", timedOut: false });
 const timedOutSpawn = async () => ({ exitCode: 1, transcript: "", logPath: "/dev/null", timedOut: true });
 /**
@@ -253,9 +248,95 @@ test("the branch created on a retried round is reused, not re-created — no 'br
     assert.match(prompts[1], /\*\*Last failure:\*\* Developer session produced no PR\./);
     assert.doesNotMatch(prompts[1], /fresh branch/);
 });
-test("dirty_worktree: an uncommitted file escalates without consuming a round", async () => {
+test("dirty_worktree: an uncommitted file whose salvage commit fails escalates without consuming a round", async () => {
+    // NOT-275: a clean exit (exitCode 0) that leaves the worktree dirty is salvaged
+    // first — escalation only happens when the salvage commit itself fails. Force
+    // that failure with a rejecting pre-commit hook (same technique as the NOT-145
+    // salvage-failure test).
+    const issueId = await makeIssue();
+    const salvageBlockedSpawn = async (input) => {
+        fs.writeFileSync(path.join(input.cwd, "scratch.txt"), "oops\n");
+        const common = git(input.cwd, "rev-parse", "--git-common-dir");
+        const hooks = path.isAbsolute(common) ? path.join(common, "hooks") : path.join(input.cwd, common, "hooks");
+        fs.mkdirSync(hooks, { recursive: true });
+        const hookPath = path.join(hooks, "pre-commit");
+        fs.writeFileSync(hookPath, "#!/bin/sh\necho salvage-blocked >&2\nexit 1\n");
+        fs.chmodSync(hookPath, 0o755);
+        return { exitCode: 0, transcript: "", logPath: "/dev/null", timedOut: false };
+    };
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: salvageBlockedSpawn, github: fakeGithub() }));
+    startWorkflow(issueId);
+    await pump(1);
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "needs_human");
+    assert.equal(issue.currentRound, 1, "dirty worktree never consumes a round");
+    const action = listHumanActionsForIssue(issueId).find((a) => a.actionType === "policy_escalation");
+    assert.ok(action, "expected a policy_escalation human action");
+    assert.match(action.reason, /Auto-commit salvage failed|salvage-blocked/i);
+    // NOT-145 / NOT-137: dirty escalations carry path + recovery like worktree_conflict.
+    assert.match(action.reason, /Recovery:/);
+    assert.match(action.reason, /git status/);
+    // Cleanup hook so later tests in this file aren't poisoned (worktrees share
+    // .git/hooks via the common dir).
+    const round1 = listWorkerSessionsForIssue(issueId).find((s) => s.role === "developer");
+    const leftover = roleWorktreePath(repo, round1.id, "developer");
+    assert.ok(fs.existsSync(path.join(leftover, "scratch.txt")), "failed salvage must not wipe WIP");
+    const common = git(repo, "rev-parse", "--git-common-dir");
+    const hooks = path.isAbsolute(common) ? path.join(common, "hooks") : path.join(repo, common, "hooks");
+    fs.rmSync(path.join(hooks, "pre-commit"), { force: true });
+    fs.rmSync(leftover, { recursive: true, force: true });
+    await withRepoLock(repo, async () => execFileSync("git", ["worktree", "prune"], { cwd: repo }));
+});
+test("NOT-275: a clean exit that leaves tracked + untracked changes salvages a checkpoint and proceeds to push/PR", async () => {
+    // The session exits 0 (not timed out, no usage cap) but never ran `git commit`.
+    // The effect must auto-commit the WIP as a salvage checkpoint on the issue
+    // branch and continue exactly as if the agent had committed the work itself —
+    // it must NOT return kind: "dirty_worktree".
+    const issueId = await makeIssue();
+    const cleanExitDirtySpawn = async (input) => {
+        fs.appendFileSync(path.join(input.cwd, "README.md"), "more docs\n");
+        fs.writeFileSync(path.join(input.cwd, "feature.txt"), "implemented\n");
+        return { exitCode: 0, transcript: "Implementation conclusion: added the widget.", logPath: "/dev/null", timedOut: false };
+    };
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: cleanExitDirtySpawn, github: fakeGithub() }));
+    startWorkflow(issueId);
+    await pump(1);
+    const issue = getIssue(issueId);
+    assert.equal(issue.status, "reviewing", "salvaged clean-exit work proceeds to push/PR like a self-committed session");
+    assert.equal(issue.currentRound, 1);
+    assert.ok(issue.headSha, "push happened — head SHA recorded");
+    assert.ok(issue.prNumber, "draft PR opened");
+    assert.equal(git(repo, "ls-remote", "origin", `refs/heads/${issue.branch}`).length > 0, true);
+    const branch = issueBranchName(issueId);
+    assert.equal(git(repo, "log", "-1", "--pretty=%s", branch), "wip: crash salvage");
+    assert.ok(git(repo, "show", `${branch}:feature.txt`).includes("implemented"), "untracked WIP is in the salvage tip");
+    assert.ok(git(repo, "show", `${branch}:README.md`).includes("more docs"), "tracked WIP is in the salvage tip");
+    const dev = listWorkerSessionsForIssue(issueId).find((s) => s.role === "developer");
+    assert.equal(dev.status, "done");
+    assert.ok(!listHumanActionsForIssue(issueId).find((a) => a.actionType === "policy_escalation"), "no dirty_worktree escalation");
+    // Deliverable 1: the salvage path emits the commit checkpoint evidence event.
+    const salvageCommits = listWorkflowEventsForIssue(issueId)
+        .filter((e) => e.type === "checkpoint.observed")
+        .map((e) => JSON.parse(e.payloadJson))
+        .filter((p) => p.kind === "commit" && p.origin === "salvage");
+    assert.equal(salvageCommits.length, 1, "salvage emits exactly one salvage-origin commit checkpoint");
+    assert.equal(salvageCommits[0].observedSha, issue.headSha, "the checkpoint vouches for the salvaged tip");
+});
+test("NOT-275: a clean exit with dirty worktree still returns dirty_worktree when the salvage commit itself fails", async () => {
     const issueId = await makeIssue();
-    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: dirtySpawn, github: fakeGithub() }));
+    const failingSalvageSpawn = async (input) => {
+        fs.appendFileSync(path.join(input.cwd, "README.md"), "more docs\n");
+        fs.writeFileSync(path.join(input.cwd, "feature.txt"), "implemented\n");
+        // Reject the coordinator's salvage commit so we exercise the escalate-and-preserve path.
+        const common = git(input.cwd, "rev-parse", "--git-common-dir");
+        const hooks = path.isAbsolute(common) ? path.join(common, "hooks") : path.join(input.cwd, common, "hooks");
+        fs.mkdirSync(hooks, { recursive: true });
+        const hookPath = path.join(hooks, "pre-commit");
+        fs.writeFileSync(hookPath, "#!/bin/sh\necho salvage-blocked >&2\nexit 1\n");
+        fs.chmodSync(hookPath, 0o755);
+        return { exitCode: 0, transcript: "", logPath: "/dev/null", timedOut: false };
+    };
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: failingSalvageSpawn, github: fakeGithub() }));
     startWorkflow(issueId);
     await pump(1);
     const issue = getIssue(issueId);
@@ -263,9 +344,18 @@ test("dirty_worktree: an uncommitted file escalates without consuming a round",
     assert.equal(issue.currentRound, 1, "dirty worktree never consumes a round");
     const action = listHumanActionsForIssue(issueId).find((a) => a.actionType === "policy_escalation");
     assert.ok(action, "expected a policy_escalation human action");
-    // NOT-145 / NOT-137: exit-0 dirty escalations carry path + recovery like worktree_conflict.
+    assert.match(action.reason, /Auto-commit salvage failed|salvage-blocked/i);
     assert.match(action.reason, /Recovery:/);
     assert.match(action.reason, /git status/);
+    const round1 = listWorkerSessionsForIssue(issueId).find((s) => s.role === "developer");
+    const leftover = roleWorktreePath(repo, round1.id, "developer");
+    assert.ok(fs.existsSync(path.join(leftover, "feature.txt")), "failed salvage must not wipe WIP");
+    // Cleanup hook so later tests in this file aren't poisoned.
+    const common = git(repo, "rev-parse", "--git-common-dir");
+    const hooks = path.isAbsolute(common) ? path.join(common, "hooks") : path.join(repo, common, "hooks");
+    fs.rmSync(path.join(hooks, "pre-commit"), { force: true });
+    fs.rmSync(leftover, { recursive: true, force: true });
+    await withRepoLock(repo, async () => execFileSync("git", ["worktree", "prune"], { cwd: repo }));
 });
 test("session_failed: the agent process exits non-zero — retried like no_pr", async () => {
     const issueId = await makeIssue();
@@ -924,11 +1014,22 @@ test("NOT-88: a leftover clean worktree from a resolved unpushed_commit escalati
 });
 test("NOT-88: a leftover dirty worktree escalates as an actionable worktree_conflict on every Resume — no infra budget burned, no opaque crash loop", async () => {
     const issueId = await makeIssue();
-    // Round 1 exits 0 but leaves the worktree dirty — dirty_worktree escalation preserves the
-    // checkout (NOT-145 salvage applies only to timeout/crash infra deaths). That leftover is
+    // Round 1 exits 0 but leaves the worktree dirty with salvage blocked (NOT-275
+    // salvages clean-exit dirt first, so a rejecting pre-commit hook forces the
+    // dirty_worktree escalation that preserves the checkout). That leftover is
     // the setup NOT-88's collision needs: round 2 must find that SAME dirty leftover still
     // holding the branch.
-    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: dirtySpawn, github: fakeGithub() }));
+    const salvageBlockedDirtySpawn = async (input) => {
+        fs.writeFileSync(path.join(input.cwd, "scratch.txt"), "oops\n");
+        const common = git(input.cwd, "rev-parse", "--git-common-dir");
+        const hooks = path.isAbsolute(common) ? path.join(common, "hooks") : path.join(input.cwd, common, "hooks");
+        fs.mkdirSync(hooks, { recursive: true });
+        const hookPath = path.join(hooks, "pre-commit");
+        fs.writeFileSync(hookPath, "#!/bin/sh\necho salvage-blocked >&2\nexit 1\n");
+        fs.chmodSync(hookPath, 0o755);
+        return { exitCode: 0, transcript: "", logPath: "/dev/null", timedOut: false };
+    };
+    registerEffectHandler("developer", (ctx) => runDeveloperEffect(ctx, { deckCallTool: okDeckCallTool, spawn: salvageBlockedDirtySpawn, github: fakeGithub() }));
     startWorkflow(issueId);
     await pump(1);
     const round1Session = listWorkerSessionsForIssue(issueId).find((s) => s.role === "developer");
@@ -950,6 +1051,11 @@ test("NOT-88: a leftover dirty worktree escalates as an actionable worktree_conf
     assert.ok(secondAction, "a fresh, actionable escalation — not silence and not a crash");
     assert.match(secondAction.reason, /uncommitted changes/);
     assert.match(secondAction.reason, new RegExp(leftoverPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+    // Cleanup the salvage-blocking hook too (worktrees share .git/hooks via the
+    // common dir — leaving it would reject commits in every later test).
+    const commonDir = git(repo, "rev-parse", "--git-common-dir");
+    const hooksDir = path.isAbsolute(commonDir) ? path.join(commonDir, "hooks") : path.join(repo, commonDir, "hooks");
+    fs.rmSync(path.join(hooksDir, "pre-commit"), { force: true });
     fs.rmSync(leftoverPath, { recursive: true, force: true });
     await withRepoLock(repo, async () => execFileSync("git", ["worktree", "prune"], { cwd: repo }));
 });
@@ -1650,7 +1756,10 @@ test("NOT-130: a green suite on a dirty worktree is not persisted as tip evidenc
     startWorkflow(issueId);
     await pump(1);
     assert.equal(listArtifactsForIssue(issueId).some((a) => a.kind === "verification_receipt"), false, "dirty tree must not mint a tip-scoped verification receipt");
-    assert.equal(getIssue(issueId).status, "needs_human");
+    // NOT-275: the post-suite dirt is salvaged and the handoff proceeds (the receipt
+    // check above stays the point of this test — the suite ran on a dirty tree, so
+    // no tip-scoped receipt may exist even after the salvaged push/PR).
+    assert.equal(getIssue(issueId).status, "reviewing");
 });
 test("NOT-130: checks_failed retry does not carry a prior green receipt into the prompt", async () => {
     const issueId = await makeIssue();

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

@@ -22,6 +22,31 @@ export const PUSH_DIVERGENCE_RESPONSE_OPTIONS = [
     { choice: "resume", label: "Resume development" },
     { choice: "close", label: "Close" },
 ];
+/**
+ * NOT-272: cap for the optional human note on a `product_scope_decision` resolution.
+ * Introduced here (no route-level text cap convention exists to mirror) — long enough
+ * for a real scope decision, short enough to fit verbatim in the next round's prompt.
+ */
+export const PRODUCT_SCOPE_NOTE_MAX_CHARS = 4000;
+/**
+ * NOT-272: normalizes the raw `note` body field of POST /api/human-actions/:id/resolve.
+ * Absent/blank is "no note" (today's behavior); a present non-string or an over-long
+ * string is a caller error. Scoping to `product_scope_decision` happens in
+ * `parseHumanResolution` / the resolve path — this only validates the shape.
+ */
+export function normalizeResolutionNote(note) {
+    if (note === undefined || note === null)
+        return { ok: true };
+    if (typeof note !== "string")
+        return { ok: false, error: "note must be a string" };
+    const trimmed = note.trim();
+    if (!trimmed)
+        return { ok: true };
+    if (trimmed.length > PRODUCT_SCOPE_NOTE_MAX_CHARS) {
+        return { ok: false, error: `note must be at most ${PRODUCT_SCOPE_NOTE_MAX_CHARS} characters` };
+    }
+    return { ok: true, note: trimmed };
+}
 /**
  * The only choices resolveHumanActionOutcome accepts per action type — the stored "response
  * options." `reflection_interaction_required` and `outbound_delivery_interaction_required`
@@ -58,7 +83,7 @@ const VALID_CHOICES = {
  * Run-scoped, has no Issue/workflow_instance to advance, and its only legal resolver is
  * `resolveOutboundDeliveryAction` (queue/approve-deliver.ts).
  */
-export function parseHumanResolution(actionType, choice) {
+export function parseHumanResolution(actionType, choice, note) {
     if (actionType === "reflection_interaction_required" || actionType === "outbound_delivery_interaction_required") {
         return null;
     }
@@ -66,6 +91,11 @@ export function parseHumanResolution(actionType, choice) {
         return null;
     if (!VALID_CHOICES[actionType].includes(choice))
         return null;
+    // NOT-272: `note` is declared only on the product_scope_decision variant — a note
+    // arriving with any other action type is dropped here, never stored or threaded.
+    if (actionType === "product_scope_decision" && note) {
+        return { actionType, choice, note };
+    }
     return { actionType, choice };
 }
 /**

package/bundle/server/dist/coordinator/muse-spawn.js

@@ -22,6 +22,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { MUSE_CODE_CONTRIBUTOR_MODEL } from "@agent-dealer/shared";
 import { resolveMuseAuthFile, resolveMuseBin } from "../cli-env.js";
+import { museVersionRequiredForWork } from "../adapters/muse-capability.js";
 import { ensureWorktreeExcluded } from "../adapters/worktree-exclude.js";
 import { buildMuseDeveloperInvocation } from "../runners/muse-code-args.js";
 import { buildMuseDeveloperSettings } from "../runners/muse-code-settings.js";
@@ -159,12 +160,21 @@ function refreshMuseCapacityAfterSession() {
  */
 async function runMuseServeLane(input, model, onAdmitted) {
     const { getMuseCapacityHost } = await import("../capacity/muse-host.js");
+    const host = getMuseCapacityHost();
+    // NOT-277: admission gated on the capability check of the on-disk binary; a long-lived host can
+    // still run an older (possibly broken) build. Serve only on a host known to run the confirmed
+    // version (restarted onto it when idle); otherwise the work runs on the checked exec lane.
+    const required = museVersionRequiredForWork();
+    if (required === null)
+        return null;
+    if (required !== undefined && !(await host.ensureStartedOnVersion(required)))
+        return null;
     // Only this call may fall back: it resolves `admitted:false` (or throws)
     // strictly before any model work starts. Everything below runs after
     // admission — the caller's no-double-execution rule (via onAdmitted)
     // keeps those errors loud instead of falling back to exec.
     const turn = await runMuseServeTurn({
-        host: getMuseCapacityHost(),
+        host,
         prompt: input.prompt,
         model,
         cwd: input.cwd,
@@ -229,7 +239,7 @@ export async function runMuseDeveloperSession(input) {
     // executing the work a second time on the exec lane.
     // `AGENT_DEALER_MUSE_RUNNER=exec` skips the serve lane entirely
     // (operator escape hatch).
-    if (museServeLaneEnabled()) {
+    if (museServeLaneEnabled() && !input.execLaneOnly) {
         let admitted = false;
         try {
             const served = await runMuseServeLane(input, model, () => {

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

@@ -9,6 +9,19 @@ function guidanceSection(guidance) {
         ...guidance.flatMap((g) => [g.trim(), ``]),
     ];
 }
+/** NOT-272: a resolved product_scope_decision's human note, verbatim. Empty/absent
+ * renders nothing so noteless resolves produce byte-for-byte the prompt they always did. */
+function scopeDecisionSection(note) {
+    if (!note?.trim())
+        return [];
+    return [
+        `## Human decision`,
+        `A human resolved the product-scope question that was holding this work. This is the decision — follow it. Do not re-derive it, do not re-escalate the same question, and do not write this decision into source comments; it is recorded on the human action.`,
+        ``,
+        note.trim(),
+        ``,
+    ];
+}
 /**
  * An agent with a deckId is launched with that deck already equipped in its MCP session
  * (NOT-106). `bind_workspace` confirms the equipped deck for this session cwd — it does
@@ -63,6 +76,8 @@ export function buildDeveloperPrompt(input) {
             parts.push(...formatVerificationReceiptSection(input.priorVerificationReceipt));
         }
     }
+    // NOT-272: the scope decision leads — the developer reads it before the task itself.
+    parts.push(...scopeDecisionSection(input.scopeDecisionNote));
     parts.push(`## Task`, input.taskSnapshot.title, input.taskSnapshot.description, ``, `## Acceptance criteria`, input.taskSnapshot.acceptanceCriteria, ``);
     if (input.findings?.length) {
         parts.push(`## Findings to address`);

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

@@ -133,6 +133,26 @@ test("no guidance section when there is none", () => {
     const prompt = buildDeveloperPrompt({ taskSnapshot, round: 1 });
     assert.doesNotMatch(prompt, /## Guidance from the team/);
 });
+// NOT-272: a product_scope_decision note reaches the very next developer round verbatim
+// under its own heading, positioned before the task so it is read before acting.
+test("NOT-272: scope decision note renders verbatim under its own heading before the task", () => {
+    const note = "The muse_code runner migration IS in scope for this ticket — proceed with it.";
+    const prompt = buildDeveloperPrompt({ taskSnapshot, round: 2, scopeDecisionNote: note });
+    assert.match(prompt, /## Human decision/);
+    assert.ok(prompt.includes(note), "note text must appear verbatim");
+    assert.ok(prompt.indexOf("## Human decision") < prompt.indexOf("## Task"), "Human decision section must precede the task");
+    assert.match(prompt, /do not re-escalate the same question/i);
+});
+// NOT-272: resolving without a note changes nothing — absent, empty, and blank notes all
+// produce byte-for-byte the prompt built before this change.
+test("NOT-272: no scope decision note produces byte-for-byte the same prompt as before", () => {
+    const base = { taskSnapshot, round: 2, findings: [{ fingerprint: "f1", severity: "blocking", title: "Bug", rationale: "It breaks", file: "a.ts", line: 10, status: "open", firstRound: 1, lastRound: 1, issueId: "i" }], guidance: ["Use the new logging util instead."] };
+    const without = buildDeveloperPrompt(base);
+    assert.doesNotMatch(without, /## Human decision/);
+    assert.equal(buildDeveloperPrompt({ ...base, scopeDecisionNote: undefined }), without);
+    assert.equal(buildDeveloperPrompt({ ...base, scopeDecisionNote: "" }), without);
+    assert.equal(buildDeveloperPrompt({ ...base, scopeDecisionNote: "   \n  " }), without);
+});
 test("guidance since the last session is surfaced in the reviewer prompt", () => {
     const prompt = buildReviewerPrompt({
         taskSnapshot,

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

@@ -17,6 +17,7 @@ import { resolveClaudeBin, resolveCodexBin, resolveCursorBin, resolveMuseBin } f
 import { spawnCli } from "../runners/spawn-cli.js";
 import { buildDeveloperArgs, buildReviewerArgs } from "./args.js";
 import { assertReviewerReadOnly } from "./permissions.js";
+import { assertWorktreeCwd } from "./worktree-cwd-guard.js";
 import { extractResultTranscript } from "./usage.js";
 import { runMuseDeveloperSession } from "./muse-spawn.js";
 export function developerSessionLogPath(sessionId) {
@@ -32,6 +33,9 @@ const BIN_FOR = {
     muse_code: resolveMuseBin,
 };
 export const realDeveloperSpawn = async (input) => {
+    // NOT-273: never spawn a worker outside a managed worktree — throws before
+    // any child process exists (the effect reports it as "could not start").
+    assertWorktreeCwd(input.cwd);
     if (input.runtime === "muse_code") {
         // Own argv, per-attempt XDG dirs and result parsing; deck/MCP are never wired for Muse.
         return runMuseDeveloperSession({
@@ -51,6 +55,9 @@ export const realDeveloperSpawn = async (input) => {
  * loosens a reviewer's tools can never silently reach a live spawn.
  */
 export const realReviewerSpawn = async (input) => {
+    // NOT-273: same worktree-cwd guard as the developer path — throws before
+    // any child process exists.
+    assertWorktreeCwd(input.cwd);
     const args = buildReviewerArgs(input.runtime, input.prompt, input.model ?? undefined, input.policy, input.mcpConfigPath, input.effort);
     assertReviewerReadOnly(args, { mcpConfigPath: input.mcpConfigPath, mcpEnv: input.mcpEnv });
     const logPath = input.logPath ?? reviewerSessionLogPath(input.sessionId);