agent-dealer 1.2.4 → 1.2.6

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

@@ -1,45 +1,29 @@
 // packages/server/src/coordinator/muse-spawn.ts
 //
-// NOT-181: the native Muse Code developer spawn. Wires the already-tested pieces — binary
-// resolution (cli-env.ts), argv (runners/muse-code-args.ts), JSONL/session-log parsing
-// (runners/muse-code-jsonl.ts) — into the existing developer-effect contract without changing
-// either side:
+// NOT-278: the native Muse Code developer spawn. Every deck-enabled Muse developer turn runs the
+// isolated `muse exec` lane: one exact, fail-closed per-attempt home built by
+// `prepareMuseAttempt` (runners/muse-config.ts) — settings.json with exactly one required
+// `agent-deck` server (deck/workspace headers), filtered env, stdin-only API key — verified
+// immediately before spawn and removed afterwards on every outcome.
 //
-//   1. a per-attempt config + data dir under the worktree (`.dealer-muse/<attempt>/`, kept out of
-//      git via info/exclude): `settings.json` with no MCP servers, a symlinked `auth.json`;
-//   2. `spawnCli` with `XDG_CONFIG_HOME`/`XDG_DATA_HOME` pointed at it;
-//   3. the on-disk session log (usage + confirmed model exist only there) read while the dir still
-//      exists, then the dir is removed on success *and* failure;
-//   4. the raw stdout archived next to the log, and the log itself rewritten as Claude/Cursor-shaped
-//      events, so every existing log reader (usage, result text, auth/usage-cap classification,
-//      activity strip) works unchanged.
+// The shared Muse serve host cannot carry per-session MCP configuration or deck/workspace
+// headers (`session/start` accepts only command, workspace, model, and approval mode), so the
+// serve lane is never used here. Fresh 5H/1W observation from the serve host is deliberately
+// suspended while deck-enabled work is forced to exec; capacity stays honest N/A/stale with
+// last-good rows preserved. Per-session Agent Deck support in the serve protocol is a non-goal.
 //
 // Muse cannot disable `cron_*` (NOT-177). The tool activity is checked here after the fact and
 // surfaced as `cronCalls`; the effect turns that into a `muse_cron_used` escalation. It detects,
 // it does not prevent.
-import { randomUUID } from "node:crypto";
 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 { ensureWorktreeExcluded } from "../adapters/worktree-exclude.js";
-import { buildMuseDeveloperInvocation } from "../runners/muse-code-args.js";
-import { buildMuseDeveloperSettings } from "../runners/muse-code-settings.js";
-import { normalizeMuseRun, parseMuseRun, } from "../runners/muse-code-jsonl.js";
-import { runMuseServeTurn } from "../runners/muse-serve-session.js";
+import { getAgentDeckMcpUrl } from "../adapters/agent-deck.js";
+import { getWorkerMcpConfigDir } from "../paths.js";
+import { prepareMuseAttempt, } from "../runners/muse-config.js";
+import { parseMuseRun, } from "../runners/muse-code-jsonl.js";
 import { spawnCli } from "../runners/spawn-cli.js";
-/**
- * NOT-270: execution lane selection. Default is the server-owned serve host
- * (real turns through it are the NOT-269 precondition for 5H/1W capacity).
- * `AGENT_DEALER_MUSE_RUNNER=exec` forces the legacy `muse exec` subprocess
- * lane — the operator escape hatch if the serve lane ever misbehaves in
- * production (capacity then reads honest N/A until serve runs again).
- */
-function museServeLaneEnabled() {
-    return process.env.AGENT_DEALER_MUSE_RUNNER !== "exec";
-}
-/** Worktree-relative home of every per-attempt Muse config/data dir. */
-export const MUSE_ATTEMPT_ROOT = ".dealer-muse";
 /**
  * Step cap when the profile sets no `maxTurns`. High on purpose (the PoC's value): the developer
  * wall-clock timeout is the real limit, the cap only stops a runaway loop.
@@ -81,32 +65,24 @@ function readSessionLog(dataDir, museSessionId) {
     };
     return visit(root, 0);
 }
-function prepareAttemptDirs(worktreePath) {
-    ensureWorktreeExcluded(worktreePath, `/${MUSE_ATTEMPT_ROOT}/`);
-    const root = path.join(worktreePath, MUSE_ATTEMPT_ROOT, randomUUID());
-    const configHome = path.join(root, "config");
-    const dataHome = path.join(root, "data");
-    fs.mkdirSync(path.join(configHome, "muse"), { recursive: true, mode: 0o700 });
-    fs.mkdirSync(dataHome, { recursive: true, mode: 0o700 });
-    // mkdir's mode is masked by the umask; the dirs hold a login symlink and the session log.
-    fs.chmodSync(root, 0o700);
-    fs.chmodSync(configHome, 0o700);
-    fs.chmodSync(dataHome, 0o700);
-    fs.writeFileSync(path.join(configHome, "muse", "settings.json"), JSON.stringify(buildMuseDeveloperSettings(), null, 2) + "\n", { mode: 0o600 });
-    // Linked, never read or copied. Absent when the operator authenticates with META_API_KEY.
-    const auth = resolveMuseAuthFile();
-    if (fs.existsSync(auth))
-        fs.symlinkSync(auth, path.join(configHome, "muse", "auth.json"));
-    return { root, configHome, dataHome };
-}
-function removeAttemptDirs(worktreePath, root) {
-    fs.rmSync(root, { recursive: true, force: true });
+/**
+ * NOT-278: the attempt's credential. A saved login is linked, never read or copied; otherwise
+ * the API key travels on stdin only (`--api-key-stdin`, written once by the launcher and never
+ * logged). Missing credentials fail before spawn — nothing is written and no process starts.
+ */
+function resolveMuseCredential() {
+    const authFile = resolveMuseAuthFile();
     try {
-        fs.rmdirSync(path.join(worktreePath, MUSE_ATTEMPT_ROOT)); // only when no sibling attempt remains
+        if (fs.existsSync(authFile))
+            return { kind: "auth-file", path: authFile };
     }
     catch {
-        // not empty or already gone
+        // An unreadable auth path is the same as a missing one: fall through to the API key.
     }
+    const apiKey = process.env.META_API_KEY;
+    if (apiKey !== undefined && apiKey.trim() !== "")
+        return { kind: "api-key", apiKey };
+    throw new Error("Muse Code auth required: run `muse login` or set META_API_KEY");
 }
 function splitSpawnLog(raw) {
     const idx = raw.indexOf(STDERR_MARKER);
@@ -123,11 +99,9 @@ function splitSpawnLog(raw) {
  * safe point is contractual, not opportunistic — a recent Agents-page poll
  * must never skip it. This creates no model turn of its own (the capacity
  * client only ever sends the read-only handshake/`usage/read` allowlist)
- * and never affects the session result. Serve-lane turns observed the host,
- * so this hook is the final read that populates 5H/1W; after an exec-lane
- * fallback the host stays unobserved by construction (the NOT-269
- * structural precondition) and the read stays honest N/A with last-good
- * rows preserved.
+ * and never affects the session result. Exec-lane turns leave the host
+ * unobserved by construction (the NOT-269 structural precondition), so the
+ * read stays honest N/A with last-good rows preserved.
  */
 function refreshMuseCapacityAfterSession() {
     void (async () => {
@@ -143,129 +117,63 @@ function refreshMuseCapacityAfterSession() {
     })();
 }
 /**
- * NOT-270: run the real developer turn through the server-owned serve host.
- * Returns null when no turn was admitted (host unavailable, session/start
- * or turn/start rejected) — the caller then runs the legacy `muse exec`
- * lane. Never returns null after admission: an admitted turn is real work
- * and its verdict is reported honestly, never retried on the other lane.
+ * NOT-278: run the deck-enabled developer turn as one isolated `muse exec` attempt. Fails before
+ * spawn without a frozen profile deck (the effect already maps that to `deck_failure`; this is
+ * the defense in depth that keeps a deckless launch from ever reaching a child process).
+ *
+ * The attempt is built with `prepareMuseAttempt({ role: "developer", ... })` on a Dealer-owned
+ * base directory outside the worktree and outside OS temp (the worker MCP config root), with
+ * `agentDeck.url` set to the configured Agent Deck MCP endpoint ending in `/mcp` (overridable
+ * for deckless infra callers), `deckId` to the frozen profile value, and `workspace` to the
+ * real worktree path. Immediately before spawn the exact cwd/argv/env/stdin about to be
+ * launched is verified; the child receives exactly
+ * `attempt.env` (no `process.env` merge) and `attempt.stdin`, so ambient `META_API_KEY`,
+ * `MUSE_*`, `CODEX_HOME`, and unrelated variables can never reach it.
  *
- * The serve lane needs no per-attempt XDG config/data dirs: the host runs
- * under its own server-owned home (`prepareMuseServeHome` in
- * capacity/muse-host.ts — same worker settings as the exec lane's
- * per-attempt settings.json plus a symlink to the ambient login, so runner
- * and capacity can never diverge on identity or posture). `onSpawn` is
- * deliberately not called: there is no per-attempt pid to persist, and
- * recovery must never treat the shared host as an attempt process.
+ * Settings, data, and the auth link are removed in `finally` on success, Muse failure,
+ * timeout, abort, and spawn error — operator credentials are never touched.
  */
-async function runMuseServeLane(input, model, onAdmitted) {
-    const { getMuseCapacityHost } = await import("../capacity/muse-host.js");
-    // 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(),
-        prompt: input.prompt,
-        model,
-        cwd: input.cwd,
-        timeoutMs: input.timeoutMs,
-        signal: input.signal,
-        onAdmitted: () => onAdmitted(),
-    });
-    if (!turn.admitted)
-        return null;
-    const cronCalls = turn.tools
-        .map((t) => t.name)
-        .filter((n) => n !== null && CRON_TOOL_RE.test(n));
-    const summary = {
-        museSessionId: turn.sessionId ?? randomUUID(),
-        confirmedModel: turn.confirmedModel,
-        usage: turn.usage,
-        failure: turn.failure,
-        cronCalls,
-        runCount: 1,
-        rawLogPath: null,
-    };
-    // Same normalized evidence both lanes write: the raw folded history, then
-    // the Claude/Cursor-shaped stream every existing log reader consumes.
-    const rawLogPath = `${input.logPath.replace(/\.ndjson$/, "")}.muse-raw.jsonl`;
-    try {
-        fs.writeFileSync(rawLogPath, `${turn.viewItems.map((i) => JSON.stringify(i)).join("\n")}\n`);
-        summary.rawLogPath = rawLogPath;
-    }
-    catch {
-        // evidence copy is best-effort; the normalized log below still carries the outcome
-    }
-    const events = normalizeMuseRun({
-        sessionId: summary.museSessionId,
-        confirmedModel: turn.confirmedModel,
-        tools: turn.tools,
-        finalText: turn.finalText,
-        usage: turn.usage,
-        failure: turn.failure,
-    }).map((e) => e.type === "result" ? { ...e, muse: { ...summary, usage: turn.usage } } : e);
-    fs.writeFileSync(input.logPath, `${events.map((e) => JSON.stringify(e)).join("\n")}\n`);
-    // The real session above is the observation opportunity: kick the
-    // best-effort capacity refresh (no synthetic turn, never throws, never
-    // blocks this result).
-    refreshMuseCapacityAfterSession();
-    // A failed session must not read as success. 124 mirrors spawn-cli's
-    // timeout exit so timeout handling downstream sees the same signal.
-    const exitCode = turn.timedOut ? 124 : turn.failure ? 1 : turn.terminal === "completed" ? 0 : 1;
-    return {
-        exitCode,
-        transcript: turn.finalText ?? "",
-        logPath: input.logPath,
-        timedOut: turn.timedOut,
-        muse: summary,
-    };
-}
 export async function runMuseDeveloperSession(input) {
-    const model = input.model ?? MUSE_CODE_CONTRIBUTOR_MODEL;
-    const museSessionId = randomUUID();
-    // Serve-first: real turns through the owned host observe it (NOT-269
-    // precondition for 5H/1W). Pre-admission failure falls back to exec; an
-    // admitted turn never falls back — its errors propagate loudly instead of
-    // 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()) {
-        let admitted = false;
-        try {
-            const served = await runMuseServeLane(input, model, () => {
-                admitted = true;
-            });
-            if (served)
-                return served;
-        }
-        catch (err) {
-            if (admitted)
-                throw err;
-            // Pre-admission serve-lane error: fall through to the exec lane below.
-        }
+    const deckId = typeof input.deckId === "string" && input.deckId.trim() !== "" ? input.deckId : null;
+    if (!deckId) {
+        throw new Error("Muse developer session requires a frozen profile deckId — workers never start without one");
     }
-    const invocation = buildMuseDeveloperInvocation({
-        model,
-        maxModelSteps: input.maxModelSteps ?? DEFAULT_MUSE_MAX_MODEL_STEPS,
-        sessionId: museSessionId,
+    const model = input.model ?? MUSE_CODE_CONTRIBUTOR_MODEL;
+    const mcpUrl = typeof input.agentDeckUrl === "string" && input.agentDeckUrl.trim() !== ""
+        ? input.agentDeckUrl
+        : `${getAgentDeckMcpUrl().replace(/\/mcp\/?$/, "")}/mcp`;
+    // prepareMuseAttempt validates everything (role controls, deck identity, credential shape,
+    // unsafe paths) and writes the per-attempt dir; it removes its own dir when setup fails.
+    const attempt = prepareMuseAttempt({
+        role: "developer",
+        worktreePath: input.cwd,
+        baseDir: getWorkerMcpConfigDir(),
+        agentDeck: { url: mcpUrl, deckId, workspace: input.cwd },
+        credential: resolveMuseCredential(),
+        sessionId: input.sessionId,
         prompt: input.prompt,
+        maxModelSteps: input.maxModelSteps ?? DEFAULT_MUSE_MAX_MODEL_STEPS,
     });
     const { logPath } = input;
-    const dirs = prepareAttemptDirs(input.cwd);
     let spawned;
     let sessionLog;
     try {
-        spawned = await spawnCli(input.sessionId, resolveMuseBin(), invocation.args, input.cwd, {
+        // The exact launch about to happen — a tampered settings file or a differing
+        // cwd/argv/env/stdin fails here, before any process exists.
+        attempt.verify({ cwd: attempt.cwd, argv: [...attempt.argv], env: { ...attempt.env }, stdin: attempt.stdin });
+        spawned = await spawnCli(input.sessionId, resolveMuseBin(), [...attempt.argv], attempt.cwd, {
             logPath,
             timeoutMs: input.timeoutMs,
-            env: { ...invocation.env, XDG_CONFIG_HOME: dirs.configHome, XDG_DATA_HOME: dirs.dataHome },
+            env: { ...attempt.env },
+            exactEnv: true,
+            stdin: attempt.stdin,
             signal: input.signal,
             onSpawn: input.onSpawn,
         });
-        sessionLog = readSessionLog(dirs.dataHome, museSessionId);
+        sessionLog = readSessionLog(attempt.env.XDG_DATA_HOME, input.sessionId);
     }
     finally {
-        removeAttemptDirs(input.cwd, dirs.root);
+        attempt.cleanup();
     }
     const rawLog = fs.existsSync(logPath) ? fs.readFileSync(logPath, "utf8") : spawned.transcript;
     const { stdout, stderr } = splitSpawnLog(rawLog);
@@ -278,7 +186,7 @@ export async function runMuseDeveloperSession(input) {
     });
     const cronCalls = run.tools.map((t) => t.name).filter((n) => n !== null && CRON_TOOL_RE.test(n));
     const summary = {
-        museSessionId,
+        museSessionId: input.sessionId,
         confirmedModel: run.confirmedModel,
         usage: run.usage,
         failure: run.failure,

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

@@ -60,6 +60,7 @@ export function projectDeveloperRoute(route, currentStatus, round) {
                     ...("pushDivergence" in route && route.pushDivergence
                         ? { pushDivergence: route.pushDivergence }
                         : {}),
+                    ...(route.blockerFingerprint ? { blockerFingerprint: route.blockerFingerprint } : {}),
                 },
                 advance: "none",
             };

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
@@ -23,16 +36,18 @@ function guidanceSection(guidance) {
  *
  * Workers never start without a deckId (fail-closed at admission/effect).
  */
-function noAgentDeckSection() {
+/**
+ * NOT-278: Muse cannot mechanically disable `cron_*`, so its developer prompt carries this
+ * prohibition on top of the standard deck bootstrap. A session that calls one is failed as
+ * `muse_cron_used` and escalated to the operator.
+ */
+function museCronProhibitionSection() {
     return [
-        `This session has no Agent Deck and no MCP servers. The Task and Acceptance criteria above are the complete brief — if they only reference a ticket id you cannot look it up, so say so in your conclusion instead of guessing.`,
         `Never call \`cron_create\`, \`cron_list\` or \`cron_delete\` and never schedule anything: a session that does is failed and escalated to the operator.`,
         ``,
     ];
 }
-function agentDeckSection(worktreePath, deckId, noAgentDeck) {
-    if (noAgentDeck)
-        return noAgentDeckSection();
+function agentDeckSection(worktreePath, deckId) {
     if (!deckId || !worktreePath) {
         return [
             `This session is misconfigured: Agent Deck is required but missing. Stop and report the bootstrap failure — do not improvise without the deck.`,
@@ -63,6 +78,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`);
@@ -73,7 +90,9 @@ export function buildDeveloperPrompt(input) {
         parts.push(``);
     }
     parts.push(...guidanceSection(input.guidance));
-    parts.push(...agentDeckSection(input.worktreePath, input.deckId, input.noAgentDeck));
+    parts.push(...agentDeckSection(input.worktreePath, input.deckId));
+    if (input.museDeveloper)
+        parts.push(...museCronProhibitionSection());
     parts.push(`## Required`, 
     // NOT-115: encourage incremental commits so a mid-session death leaves less
     // uncommitted work for dirty_worktree escalation — soft mitigation only.

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,
@@ -210,17 +230,25 @@ test("reviewer prompt deck section requires bind_workspace first, matching the d
     assert.match(prompt, /do not web-fetch Linear/);
     assert.doesNotMatch(prompt, /get_playbook\(/);
 });
-// NOT-181: a Muse Code worker has no Agent Deck, so it must not be told the session is
-// misconfigured (the deckless default) nor to bind a deck; it is told never to touch cron_*.
-test("NOT-181: noAgentDeck prompt states there is no deck/MCP and forbids cron_* instead of the misconfigured stop", () => {
-    const prompt = buildDeveloperPrompt({ taskSnapshot, round: 1, noAgentDeck: true, deckId: null, worktreePath: "/wt" });
-    assert.match(prompt, /no Agent Deck and no MCP servers/);
+// NOT-278: a Muse Code developer gets the standard Agent Deck bootstrap gate plus the
+// Muse-specific cron_* prohibition (detected post-run as muse_cron_used).
+test("NOT-278: museDeveloper prompt carries the standard deck bootstrap and forbids cron_*", () => {
+    const prompt = buildDeveloperPrompt({ taskSnapshot, round: 1, deckId: "deck-1", worktreePath: "/wt", museDeveloper: true });
+    assert.match(prompt, /bind_workspace\(\{ deckId: "deck-1", workspaceRoot: "\/wt" \}\)/);
+    assert.match(prompt, /bootstrap is a hard gate/i);
+    assert.match(prompt, /do not improvise without the deck/i);
+    assert.match(prompt, /call_service_tool/);
     assert.match(prompt, /cron_create/);
-    assert.doesNotMatch(prompt, /misconfigured/);
-    assert.doesNotMatch(prompt, /bind_workspace/);
+    assert.match(prompt, /cron_list/);
+    assert.match(prompt, /cron_delete/);
     assert.match(prompt, /do NOT push and do NOT open a pull request/);
 });
-test("NOT-181: without noAgentDeck a deckless prompt still fails closed", () => {
+test("NOT-278: a non-Muse developer prompt has the deck bootstrap but no cron prohibition", () => {
+    const prompt = buildDeveloperPrompt({ taskSnapshot, round: 1, deckId: "deck-1", worktreePath: "/wt" });
+    assert.match(prompt, /bind_workspace/);
+    assert.doesNotMatch(prompt, /cron_create/);
+});
+test("a deckless developer prompt still fails closed", () => {
     const prompt = buildDeveloperPrompt({ taskSnapshot, round: 1, deckId: null });
     assert.match(prompt, /misconfigured: Agent Deck is required but missing/);
 });

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

@@ -72,6 +72,7 @@ export function routeDeveloperOutcome(outcome, limits) {
                 next: "human_action",
                 actionType: "policy_escalation",
                 reason: `${outcome.reason} Recovery:\n${outcome.recoveryCommands.join("\n")}`,
+                ...(outcome.fingerprint ? { blockerFingerprint: outcome.fingerprint } : {}),
             };
         case "muse_cron_used":
             // Spends no budget and never retries: a policy breach the operator must look at, like a

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

@@ -99,6 +99,26 @@ test("worktree conflict always escalates immediately — never retried, regardle
     assert.match(reason, /old-session-developer/);
     assert.match(reason, /git status/);
 });
+test("NOT-280: worktree_conflict carries its blocker fingerprint through routing and projection to the action effect", async () => {
+    const { projectDeveloperRoute } = await import("./projection.js");
+    const outcome = {
+        kind: "worktree_conflict",
+        path: "/data/worktrees/old-session-developer",
+        reason: "Automatic salvage failed: git commit failed: hook rejected",
+        recoveryCommands: ["git status"],
+        fingerprint: "fp-1",
+    };
+    const result = routeDeveloperOutcome(outcome, REVIEW_ROUNDS_LEFT);
+    assert.equal(result.next, "human_action");
+    assert.equal(result.blockerFingerprint, "fp-1");
+    const { effect, advance } = projectDeveloperRoute(result, "developing", 1);
+    assert.equal(advance, "none", "a worktree blocker never spends any budget");
+    assert.equal(effect.kind, "human_action");
+    assert.equal(effect.blockerFingerprint, "fp-1");
+    const { fingerprint: _omit, ...legacy } = outcome;
+    const plain = routeDeveloperOutcome(legacy, REVIEW_ROUNDS_LEFT);
+    assert.equal("blockerFingerprint" in plain, false);
+});
 test("NOT-127: live_owner retries on the infra budget — never escalates as worktree_conflict", () => {
     const outcome = {
         kind: "live_owner",

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,8 +33,12 @@ 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.
+        // NOT-278: isolated deck-configured exec attempt (prepareMuseAttempt); the shared serve
+        // lane cannot carry per-session deck/workspace identity, so it is never used here.
         return runMuseDeveloperSession({
             ...input,
             maxModelSteps: input.maxModelSteps ?? undefined,
@@ -51,6 +56,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);

package/bundle/server/dist/coordinator/worktree-cwd-guard.js

@@ -0,0 +1,48 @@
+// packages/server/src/coordinator/worktree-cwd-guard.ts
+//
+// NOT-273: defensive guard on the developer/reviewer spawn path. The worktree
+// resolution (`resolveDeveloperWorktree` / `roleWorktreePathForResolution`) is
+// correct today, but nothing asserts the resolved cwd before a child process
+// is spawned — a regression there would run agent CLIs against the wrong
+// directory (in the worst case the primary repo checkout itself, where a
+// worker's `git add . && git commit` lands real commits on the checkout).
+// Every real developer/reviewer spawn calls `assertWorktreeCwd` first and
+// throws instead of spawning when the cwd is not a recognized
+// coordinator-managed worktree path.
+import path from "node:path";
+/** Basename shape the worktree manager itself uses: `<sessionId>-<role>`. */
+const ROLE_SUFFIX_RE = /-(developer|reviewer)$/;
+/**
+ * Parent directory names under which coordinator-managed role worktrees live:
+ * - legacy layout: `<repo>/.agent-dealer-worktrees/<sessionId>-<role>`
+ * - managed layout (NOT-149): `<executionRoot>/worktrees/<identity>/<sessionId>-<role>`
+ * - dev-mode equivalent: `<dataDir>/worktrees/...`
+ */
+const WORKTREE_PARENT_NAMES = new Set([".agent-dealer-worktrees", "worktrees"]);
+/**
+ * True when `cwd` looks like a coordinator-managed role worktree path: its
+ * basename carries the `-developer`/`-reviewer` role suffix AND one of its
+ * parent directories is a recognized worktrees root. In particular the
+ * primary repo root itself never matches (no role suffix, no worktrees
+ * parent), nor does the ambient `process.cwd()` of a dev checkout.
+ */
+export function isManagedWorktreeCwd(cwd) {
+    if (typeof cwd !== "string" || cwd.length === 0)
+        return false;
+    const normalized = path.normalize(cwd);
+    if (!ROLE_SUFFIX_RE.test(path.basename(normalized)))
+        return false;
+    const segments = normalized.split(path.sep).filter(Boolean);
+    return segments.slice(0, -1).some((segment) => WORKTREE_PARENT_NAMES.has(segment));
+}
+/**
+ * Throw instead of spawning when `cwd` is not a recognized managed-worktree
+ * path. Called at the top of `realDeveloperSpawn`/`realReviewerSpawn`, before
+ * any child process exists — the effects turn this pre-spawn throw into a
+ * `session_failed` "could not start" outcome, never a run against the repo.
+ */
+export function assertWorktreeCwd(cwd) {
+    if (!isManagedWorktreeCwd(cwd)) {
+        throw new Error(`Refusing to spawn a worker outside a managed worktree (NOT-273): ${cwd}`);
+    }
+}

package/bundle/server/dist/coordinator/worktree-cwd-guard.test.js

@@ -0,0 +1,83 @@
+// packages/server/src/coordinator/worktree-cwd-guard.test.ts
+//
+// NOT-273: the developer/reviewer spawn path refuses to spawn outside a
+// recognized coordinator-managed worktree — in particular the primary repo
+// root itself — before any child process exists.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const { assertWorktreeCwd, isManagedWorktreeCwd } = await import("./worktree-cwd-guard.js");
+const { realDeveloperSpawn, realReviewerSpawn } = await import("./spawn.js");
+const SESSION_ID = "00000000-0000-4000-8000-000000000001";
+test("real worktree-shaped paths pass the guard", () => {
+    // Legacy layout: <repo>/.agent-dealer-worktrees/<sessionId>-<role>.
+    assert.equal(isManagedWorktreeCwd(`/repo/.agent-dealer-worktrees/${SESSION_ID}-developer`), true);
+    assert.equal(isManagedWorktreeCwd(`/repo/.agent-dealer-worktrees/${SESSION_ID}-reviewer`), true);
+    // Managed layout (NOT-149): <executionRoot>/worktrees/<identity>/<sessionId>-<role>.
+    assert.equal(isManagedWorktreeCwd(`/data/execution/worktrees/github.com/acme/app/${SESSION_ID}-developer`), true);
+    assert.equal(isManagedWorktreeCwd(`/data/execution/worktrees/github.com/acme/app/${SESSION_ID}-reviewer`), true);
+    // Dev-mode equivalent under a dev data dir.
+    assert.equal(isManagedWorktreeCwd(path.join(os.homedir(), ".agent-dealer-dev", "worktrees", "github.com", "acme", "app", `${SESSION_ID}-developer`)), true);
+    assert.doesNotThrow(() => assertWorktreeCwd(`/repo/.agent-dealer-worktrees/${SESSION_ID}-developer`));
+});
+test("the primary repo root and other non-worktree paths are rejected", () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-guard-repo-"));
+    // A plain checkout dir (what the ambient process cwd is in a normal dev
+    // checkout). Deliberately synthetic, never `process.cwd()` itself: the
+    // runner's own cwd is environment-dependent and may itself be
+    // worktree-shaped (e.g. a `<uuid>-developer` dir under a `worktrees`
+    // parent), which the guard correctly accepts per the naming convention.
+    const checkoutDir = path.join(repoRoot, "checkout");
+    fs.mkdirSync(checkoutDir);
+    try {
+        assert.equal(isManagedWorktreeCwd(repoRoot), false, "primary repo root itself");
+        assert.equal(isManagedWorktreeCwd(checkoutDir), false, "ambient-checkout-shaped cwd");
+        assert.equal(isManagedWorktreeCwd(os.tmpdir()), false, "bare temp dir");
+        assert.equal(isManagedWorktreeCwd(path.join(os.tmpdir(), `${SESSION_ID}-developer`)), false, "role suffix without a worktrees parent");
+        assert.equal(isManagedWorktreeCwd("/repo/.agent-dealer-worktrees"), false, "worktrees root without a session dir");
+        assert.equal(isManagedWorktreeCwd(""), false, "empty cwd");
+        assert.throws(() => assertWorktreeCwd(repoRoot), /managed worktree/);
+        assert.throws(() => assertWorktreeCwd(checkoutDir), /managed worktree/);
+    }
+    finally {
+        fs.rmSync(repoRoot, { recursive: true, force: true });
+    }
+});
+test("realDeveloperSpawn refuses the primary repo root before any process is spawned", async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-guard-dev-"));
+    try {
+        await assert.rejects(realDeveloperSpawn({
+            sessionId: SESSION_ID,
+            runtime: "claude_code",
+            policy: { worktreeWrite: true },
+            model: null,
+            prompt: "Implement it",
+            cwd: repoRoot,
+            timeoutMs: 1000,
+        }), /managed worktree/, "repo-root cwd throws instead of spawning");
+    }
+    finally {
+        fs.rmSync(repoRoot, { recursive: true, force: true });
+    }
+});
+test("realReviewerSpawn refuses the primary repo root before any process is spawned", async () => {
+    // Synthetic repo-root stand-in, never `process.cwd()`: the runner's own
+    // cwd is environment-dependent and may itself be worktree-shaped.
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-guard-rev-"));
+    try {
+        await assert.rejects(realReviewerSpawn({
+            sessionId: SESSION_ID,
+            runtime: "claude_code",
+            policy: { worktreeWrite: false },
+            model: null,
+            prompt: "Review it",
+            cwd: repoRoot,
+            timeoutMs: 1000,
+        }), /managed worktree/, "repo-root cwd throws instead of spawning");
+    }
+    finally {
+        fs.rmSync(repoRoot, { recursive: true, force: true });
+    }
+});