agent-dealer 1.0.3 → 1.0.4

package/bundle/server/dist/adapters/agent-deck.js

@@ -154,34 +154,89 @@ export async function updatePlaybookBody(playbookId, body) {
 export function readClaudeMcpConfigPath() {
     return process.env.CLAUDE_MCP_CONFIG ?? path.join(process.env.HOME ?? "", ".claude.json");
 }
-export function isAgentDeckMcpRegistered() {
+function expectedAgentDeckMcpEndpoint() {
+    const expected = new URL(getAgentDeckMcpUrl().replace(/\/mcp\/?$/, "") + "/mcp");
+    const port = expected.port || (expected.protocol === "https:" ? "443" : "80");
+    return { hostname: expected.hostname, port };
+}
+function isAgentDeckMcpServerName(name) {
+    const lower = name.toLowerCase();
+    return lower.includes("agent-deck") || name === "agent-deck";
+}
+/** Basename of `agent-deck` (PATH lookup or absolute install path). */
+function commandInvokesAgentDeck(command) {
+    if (!command?.trim())
+        return false;
+    const base = path.basename(command.trim()).replace(/\.(cmd|exe|bat)$/i, "");
+    return base === "agent-deck";
+}
+function argsIncludeMcpLaunch(args) {
+    return Array.isArray(args) && args.some((a) => a === "mcp-launch");
+}
+/**
+ * Classify Claude MCP config for Agent Deck.
+ * Accepts legacy HTTP `url` entries and current `agent-deck mcp-launch` stdio + env ports
+ * from `agent-deck setup --client claude`.
+ */
+export function checkAgentDeckMcpRegistration() {
     try {
         const configPath = readClaudeMcpConfigPath();
         if (!fs.existsSync(configPath))
-            return false;
+            return { status: "missing" };
         const raw = fs.readFileSync(configPath, "utf8");
         const config = JSON.parse(raw);
-        const expected = new URL(getAgentDeckMcpUrl().replace(/\/mcp\/?$/, "") + "/mcp");
+        const expected = expectedAgentDeckMcpEndpoint();
+        let mismatch = null;
         for (const [name, server] of Object.entries(config.mcpServers ?? {})) {
-            if (!name.toLowerCase().includes("agent-deck") && name !== "agent-deck")
+            if (!isAgentDeckMcpServerName(name))
                 continue;
-            if (!server.url)
+            if (server.url) {
+                try {
+                    const u = new URL(server.url);
+                    const foundPort = u.port || (u.protocol === "https:" ? "443" : "80");
+                    if (u.hostname === expected.hostname && foundPort === expected.port) {
+                        return { status: "registered" };
+                    }
+                    mismatch = {
+                        status: "endpoint_mismatch",
+                        expectedHost: expected.hostname,
+                        expectedPort: expected.port,
+                        foundHost: u.hostname,
+                        foundPort,
+                    };
+                }
+                catch {
+                    // skip invalid url
+                }
                 continue;
-            try {
-                const u = new URL(server.url);
-                if (u.hostname === expected.hostname && u.port === expected.port)
-                    return true;
             }
-            catch {
-                // skip invalid url
+            // Current Claude setup: stdio `agent-deck mcp-launch` with AGENT_DECK_* env.
+            if (commandInvokesAgentDeck(server.command) && argsIncludeMcpLaunch(server.args)) {
+                const foundHost = server.env?.AGENT_DECK_HOST?.trim() || "127.0.0.1";
+                const foundPort = server.env?.AGENT_DECK_MCP_PORT?.trim() ?? "";
+                if (foundHost === expected.hostname && foundPort === expected.port) {
+                    return { status: "registered" };
+                }
+                mismatch = {
+                    status: "endpoint_mismatch",
+                    expectedHost: expected.hostname,
+                    expectedPort: expected.port,
+                    foundHost,
+                    foundPort: foundPort || "(missing)",
+                };
             }
         }
-        return false;
+        if (mismatch)
+            return mismatch;
+        return { status: "missing" };
     }
     catch {
-        return false;
+        return { status: "missing" };
     }
 }
+export function isAgentDeckMcpRegistered() {
+    return checkAgentDeckMcpRegistration().status === "registered";
+}
 /** Map PRD toolCall to deck MCP call_service_tool args (serviceName → serviceId). */
 export function toCallServiceToolPayload(toolCall) {
     return {

package/bundle/server/dist/adapters/agent-deck.test.js

@@ -8,8 +8,30 @@ import os from "node:os";
 import path from "node:path";
 process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-agentdeck-"));
 const { migrate } = await import("../db/index.js");
-const { fetchDecks, fetchAuthorizedDecks } = await import("./agent-deck.js");
+const { fetchDecks, fetchAuthorizedDecks, isAgentDeckMcpRegistered, checkAgentDeckMcpRegistration, } = await import("./agent-deck.js");
 migrate();
+function writeClaudeMcpFixture(mcpServers) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "claude-mcp-"));
+    const configPath = path.join(dir, ".claude.json");
+    fs.writeFileSync(configPath, JSON.stringify({ mcpServers }, null, 2));
+    return configPath;
+}
+function withClaudeMcpConfig(configPath, fn) {
+    const prev = process.env.CLAUDE_MCP_CONFIG;
+    if (configPath === null)
+        delete process.env.CLAUDE_MCP_CONFIG;
+    else
+        process.env.CLAUDE_MCP_CONFIG = configPath;
+    try {
+        return fn();
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.CLAUDE_MCP_CONFIG;
+        else
+            process.env.CLAUDE_MCP_CONFIG = prev;
+    }
+}
 test("fetchDecks returns decks on success from /api/launch/decks", async () => {
     let capturedUrl = "";
     const fetchMock = mock.method(globalThis, "fetch", async (url, init) => {
@@ -61,3 +83,71 @@ test("fetchDecks reports DECK_UNAVAILABLE on a network error, never an empty lis
 test("fetchAuthorizedDecks is an alias of fetchDecks", () => {
     assert.equal(fetchAuthorizedDecks, fetchDecks);
 });
+// Default Agent Deck MCP endpoint under a fresh AGENT_DEALER_HOME is 127.0.0.1:1110
+// (API port 1111 − 1). Fixtures below match that unless noted.
+test("isAgentDeckMcpRegistered: stdio mcp-launch with matching env is registered (no url)", () => {
+    const configPath = writeClaudeMcpFixture({
+        "agent-deck": {
+            type: "stdio",
+            command: "agent-deck",
+            args: ["mcp-launch"],
+            env: { AGENT_DECK_MCP_PORT: "1110", AGENT_DECK_HOST: "127.0.0.1" },
+        },
+    });
+    withClaudeMcpConfig(configPath, () => {
+        assert.equal(isAgentDeckMcpRegistered(), true);
+        assert.equal(checkAgentDeckMcpRegistration().status, "registered");
+    });
+});
+test("isAgentDeckMcpRegistered: legacy HTTP url with matching host/port is registered", () => {
+    const configPath = writeClaudeMcpFixture({
+        "agent-deck": { url: "http://127.0.0.1:1110/mcp" },
+    });
+    withClaudeMcpConfig(configPath, () => {
+        assert.equal(isAgentDeckMcpRegistered(), true);
+    });
+});
+test("isAgentDeckMcpRegistered: missing entry returns false / missing", () => {
+    const configPath = writeClaudeMcpFixture({
+        other: { url: "http://127.0.0.1:9999/mcp" },
+    });
+    withClaudeMcpConfig(configPath, () => {
+        assert.equal(isAgentDeckMcpRegistered(), false);
+        assert.equal(checkAgentDeckMcpRegistration().status, "missing");
+    });
+});
+test("checkAgentDeckMcpRegistration: wrong stdio port is endpoint_mismatch, not registered", () => {
+    const configPath = writeClaudeMcpFixture({
+        "agent-deck": {
+            type: "stdio",
+            command: "agent-deck",
+            args: ["mcp-launch"],
+            env: { AGENT_DECK_MCP_PORT: "9999", AGENT_DECK_HOST: "127.0.0.1" },
+        },
+    });
+    withClaudeMcpConfig(configPath, () => {
+        assert.equal(isAgentDeckMcpRegistered(), false);
+        const result = checkAgentDeckMcpRegistration();
+        assert.equal(result.status, "endpoint_mismatch");
+        if (result.status === "endpoint_mismatch") {
+            assert.equal(result.expectedPort, "1110");
+            assert.equal(result.foundPort, "9999");
+            assert.equal(result.expectedHost, "127.0.0.1");
+            assert.equal(result.foundHost, "127.0.0.1");
+        }
+    });
+});
+test("isAgentDeckMcpRegistered: stdio without mcp-launch args is not registered", () => {
+    const configPath = writeClaudeMcpFixture({
+        "agent-deck": {
+            type: "stdio",
+            command: "agent-deck",
+            args: ["mcp"],
+            env: { AGENT_DECK_MCP_PORT: "1110", AGENT_DECK_HOST: "127.0.0.1" },
+        },
+    });
+    withClaudeMcpConfig(configPath, () => {
+        assert.equal(isAgentDeckMcpRegistered(), false);
+        assert.equal(checkAgentDeckMcpRegistration().status, "missing");
+    });
+});

package/bundle/server/dist/adapters/agent-health.js

@@ -1,7 +1,7 @@
 import { spawn, spawnSync } from "node:child_process";
 import { CODEX_AUTH_REMEDIATION, cursorAuthIssueFromOutput, runtimeAuthIssueFromOutput, } from "@agent-dealer/shared";
 import { claudeBinExists, cursorBinExists, resolveClaudeBin, cursorInvokeArgs, resolveCursorBin, resolveCodexBin, codexBinExists, } from "../cli-env.js";
-import { checkAgentDeckHealth, fetchDecks, isAgentDeckMcpRegistered } from "./agent-deck.js";
+import { checkAgentDeckHealth, checkAgentDeckMcpRegistration, fetchDecks, } from "./agent-deck.js";
 import { runtimeAvailability } from "../repository/runtime-availability.js";
 const RUNTIME_LABEL = {
     claude_code: "Claude",
@@ -345,7 +345,15 @@ async function runtimeIssues(runtime) {
     runtimeIssueCache.set(runtime, { at: Date.now(), issues: nonCap, softProbeFailure });
     return [...capIssues, ...nonCap];
 }
-function agentSpecificIssues(agent, agentDeckOnline, mcpRegistered, deckAccessResult) {
+function resolveMcpRegistration(mcpRegistered) {
+    if (mcpRegistered === undefined)
+        return checkAgentDeckMcpRegistration();
+    if (typeof mcpRegistered === "boolean") {
+        return mcpRegistered ? { status: "registered" } : { status: "missing" };
+    }
+    return mcpRegistered;
+}
+function agentSpecificIssues(agent, agentDeckOnline, mcpRegistration, deckAccessResult) {
     const issues = [];
     if (!agent.deckId) {
         issues.push({
@@ -372,11 +380,19 @@ function agentSpecificIssues(agent, agentDeckOnline, mcpRegistered, deckAccessRe
             });
         }
     }
-    if (agent.runtime === "claude_code" && agentDeckOnline && !mcpRegistered) {
-        issues.push({
-            code: "mcp_not_registered",
-            message: "Run agent-deck setup --client claude --start (Claude MCP not registered)",
-        });
+    if (agent.runtime === "claude_code" && agentDeckOnline) {
+        if (mcpRegistration.status === "endpoint_mismatch") {
+            issues.push({
+                code: "mcp_not_registered",
+                message: `Claude MCP points at ${mcpRegistration.foundHost}:${mcpRegistration.foundPort}, expected ${mcpRegistration.expectedHost}:${mcpRegistration.expectedPort} — update AGENT_DECK_HOST/AGENT_DECK_MCP_PORT (or the HTTP url) in Claude MCP config`,
+            });
+        }
+        else if (mcpRegistration.status === "missing") {
+            issues.push({
+                code: "mcp_not_registered",
+                message: "Run agent-deck setup --client claude --start (Claude MCP not registered)",
+            });
+        }
     }
     return issues;
 }
@@ -384,12 +400,12 @@ export async function healthForAgent(agent, agentDeckOnline, runtimeIssuesByRunt
     const runtime = runtimeIssuesByRuntime !== undefined
         ? (runtimeIssuesByRuntime.get(agent.runtime) ?? [])
         : await runtimeIssues(agent.runtime);
-    const deckMcpOk = mcpRegistered ?? isAgentDeckMcpRegistered();
+    const mcpRegistration = resolveMcpRegistration(mcpRegistered);
     const github = githubIssuesList ?? (await githubIssues());
     const issues = [
         ...runtime,
         ...github,
-        ...agentSpecificIssues(agent, agentDeckOnline, deckMcpOk, deckAccessResult),
+        ...agentSpecificIssues(agent, agentDeckOnline, mcpRegistration, deckAccessResult),
     ];
     return {
         ...agent,
@@ -399,7 +415,7 @@ export async function healthForAgent(agent, agentDeckOnline, runtimeIssuesByRunt
 }
 export async function listAgentsWithHealth(agents) {
     const agentDeckOnline = await checkAgentDeckHealth();
-    const mcpRegistered = isAgentDeckMcpRegistered();
+    const mcpRegistration = checkAgentDeckMcpRegistration();
     const needsDeckAccess = agents.some((a) => a.deckId);
     const deckAccessResult = agentDeckOnline && needsDeckAccess ? await fetchDecks() : null;
     const runtimes = [...new Set(agents.map((a) => a.runtime))];
@@ -410,5 +426,5 @@ export async function listAgentsWithHealth(agents) {
         })),
         githubIssues(),
     ]);
-    return Promise.all(agents.map((a) => healthForAgent(a, agentDeckOnline, runtimeIssuesByRuntime, mcpRegistered, deckAccessResult, githubIssuesList)));
+    return Promise.all(agents.map((a) => healthForAgent(a, agentDeckOnline, runtimeIssuesByRuntime, mcpRegistration, deckAccessResult, githubIssuesList)));
 }

package/bundle/server/dist/adapters/agent-health.test.js

@@ -343,4 +343,23 @@ The keychain item is stuck. Delete it and sign in again:
             clearAgentHealthCaches();
         }
     });
+    test("claude MCP endpoint mismatch surfaces a distinct message, not the generic setup hint", async () => {
+        const agent = createAgent({
+            name: "claude-mcp-mismatch",
+            runtime: "claude_code",
+            deckId: randomUUID(),
+        });
+        const result = await healthForAgent(agent, true, new Map(), {
+            status: "endpoint_mismatch",
+            expectedHost: "127.0.0.1",
+            expectedPort: "1110",
+            foundHost: "127.0.0.1",
+            foundPort: "9999",
+        }, null, NO_GITHUB);
+        const issue = result.issues.find((i) => i.code === "mcp_not_registered");
+        assert.ok(issue, "expected mcp_not_registered");
+        assert.match(issue.message, /points at 127\.0\.0\.1:9999/);
+        assert.match(issue.message, /expected 127\.0\.0\.1:1110/);
+        assert.equal(issue.message.includes("Run agent-deck setup"), false);
+    });
 }); // describe agent-health (serial)

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

@@ -55,36 +55,47 @@ function listOccupyingIssues() {
     return listIssues([...occupyingStatuses]).map((i) => ({ id: i.id, status: i.status }));
 }
 let healthChecker = null;
-/** Tests inject a pure checker so admission does not hit real CLIs. */
+/** Tests inject a pure checker so admission / pre-spawn health do not hit real CLIs. */
 export function setAdmissionHealthCheckerForTests(checker) {
     healthChecker = checker;
 }
-async function defaultAgentHealth(agent, deckOnline) {
+async function defaultAgentHealth(agent, role, deckOnline) {
+    // Unit/CI tests must not call real CLIs / Agent Deck — runners usually have no deck MCP.
+    // Production leaves this unset. NOT-133 clears it so the real auth classifier still runs.
+    if (process.env.AGENT_DEALER_SKIP_AGENT_HEALTH === "1") {
+        return { ok: true };
+    }
     const health = await healthForAgent(agent, deckOnline);
     // usage_capped is owned by runtimeAvailable — keep agentsHealthy for CLI/workspace/deck.
     const nonCap = health.issues.filter((i) => i.code !== "usage_capped");
     if (nonCap.length > 0) {
         return {
             ok: false,
-            reason: `agent unhealthy: ${agent.name} — ${nonCap.map((i) => i.message).join("; ")}`,
+            // NOT-156: name the role so a parked review is not read as a blocked developer admit.
+            reason: `${role} unhealthy: ${agent.name} — ${nonCap.map((i) => i.message).join("; ")}`,
         };
     }
     return { ok: true };
 }
+/**
+ * Fail-closed health for one role (NOT-156). Admission checks the role about to start
+ * (developer for `startWorkflowCore`); the worker loop re-checks the leased item's role
+ * before spawn so a later reviewer round parks without burning infra when only the
+ * reviewer is unhealthy.
+ */
+export async function checkRoleAgentHealthy(issue, role, ctx) {
+    const agentId = role === "developer" ? issue.developerAgentId : issue.reviewerAgentId;
+    if (!agentId)
+        return { ok: false, reason: `missing ${role} agent` };
+    const agent = getAgent(agentId);
+    if (!agent)
+        return { ok: false, reason: `${role} agent not found` };
+    const check = healthChecker ?? ((a, r) => defaultAgentHealth(a, r, ctx.deckOnline));
+    return check(agent, role);
+}
 async function checkAgentsHealthy(issue, ctx) {
-    const check = healthChecker ?? ((agent) => defaultAgentHealth(agent, ctx.deckOnline));
-    for (const role of ["developer", "reviewer"]) {
-        const agentId = role === "developer" ? issue.developerAgentId : issue.reviewerAgentId;
-        if (!agentId)
-            return { ok: false, reason: `missing ${role} agent` };
-        const agent = getAgent(agentId);
-        if (!agent)
-            return { ok: false, reason: `${role} agent not found` };
-        const result = await check(agent);
-        if (!result.ok)
-            return result;
-    }
-    return { ok: true };
+    // Admit always starts a developer round — do not require reviewer health yet (NOT-156).
+    return checkRoleAgentHealthy(issue, "developer", ctx);
 }
 /**
  * Status must be startable (`ready`, or `needs_human` with no active workflow) and
@@ -107,20 +118,20 @@ function issueReadinessRule(issue) {
     return { ok: true };
 }
 function runtimeAvailableRule(issue) {
-    for (const role of ["developer", "reviewer"]) {
-        const agentId = role === "developer" ? issue.developerAgentId : issue.reviewerAgentId;
-        if (!agentId)
-            continue;
-        const agent = getAgent(agentId);
-        if (!agent)
-            continue;
-        const avail = runtimeAvailability(agent.runtime);
-        if (!avail.available) {
-            return {
-                ok: false,
-                reason: `runtime capped: ${agent.runtime} until ${avail.until} (${avail.reason})`,
-            };
-        }
+    // NOT-156: only the developer runtime gates admit; reviewer caps are enforced at lease
+    // time in the worker loop (same place as role health for the active work item).
+    const agentId = issue.developerAgentId;
+    if (!agentId)
+        return { ok: true };
+    const agent = getAgent(agentId);
+    if (!agent)
+        return { ok: true };
+    const avail = runtimeAvailability(agent.runtime);
+    if (!avail.available) {
+        return {
+            ok: false,
+            reason: `runtime capped: ${agent.runtime} until ${avail.until} (${avail.reason})`,
+        };
     }
     return { ok: true };
 }

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

@@ -310,7 +310,10 @@ test("NOT-133: a logged-out Cursor runtime is not admitted; it waits with an aut
     fs.writeFileSync(stub, `#!/bin/sh\ncat ${JSON.stringify(fixture)}\nexit 0\n`);
     fs.chmodSync(stub, 0o755);
     const prev = process.env.CURSOR_CLI;
+    const prevSkipHealth = process.env.AGENT_DEALER_SKIP_AGENT_HEALTH;
     process.env.CURSOR_CLI = stub;
+    // Real classifier path — must not short-circuit via the unit-test skip.
+    delete process.env.AGENT_DEALER_SKIP_AGENT_HEALTH;
     setAdmissionHealthCheckerForTests(null);
     clearAgentHealthCaches();
     try {
@@ -323,7 +326,7 @@ test("NOT-133: a logged-out Cursor runtime is not admitted; it waits with an aut
         assert.equal(getActiveWorkflowInstance(issue.id), null);
         const entry = getQueuedEntryForIssue(issue.id);
         assert.equal(entry?.state, "queued");
-        assert.match(entry.waitReason, /agent unhealthy/);
+        assert.match(entry.waitReason, /developer unhealthy/);
         assert.match(entry.waitReason, /not authenticated/i);
         assert.match(entry.waitReason, /cursor-agent login/);
     }
@@ -332,10 +335,56 @@ test("NOT-133: a logged-out Cursor runtime is not admitted; it waits with an aut
             delete process.env.CURSOR_CLI;
         else
             process.env.CURSOR_CLI = prev;
+        if (prevSkipHealth === undefined)
+            delete process.env.AGENT_DEALER_SKIP_AGENT_HEALTH;
+        else
+            process.env.AGENT_DEALER_SKIP_AGENT_HEALTH = prevSkipHealth;
         clearAgentHealthCaches();
         setAdmissionHealthCheckerForTests(async () => ({ ok: true }));
     }
 });
+// NOT-156: reviewer health must not block developer admit; developer health still fails closed.
+test("NOT-156: developer healthy + reviewer unhealthy still admits and leases developer work", async () => {
+    const { listWorkItemsForIssue } = await import("../repository/work-items.js");
+    const issue = readyIssue("rev-unhealthy");
+    setAdmissionHealthCheckerForTests(async (_agent, role) => {
+        if (role === "reviewer") {
+            return {
+                ok: false,
+                reason: `reviewer unhealthy: ${_agent.name} — Run agent-deck setup --client claude --start (Claude MCP not registered)`,
+            };
+        }
+        return { ok: true };
+    });
+    enqueueIssue(issue.id);
+    const result = await admitNext();
+    assert.equal(result?.issueId, issue.id);
+    assert.equal(getIssue(issue.id).status, "developing");
+    assert.ok(getActiveWorkflowInstance(issue.id));
+    const developerItems = listWorkItemsForIssue(issue.id).filter((w) => w.kind === "developer");
+    assert.equal(developerItems.length, 1);
+    assert.equal(developerItems[0].status, "pending");
+});
+test("NOT-156: developer unhealthy + reviewer healthy parks with a developer-named wait_reason", async () => {
+    const issue = readyIssue("dev-unhealthy");
+    setAdmissionHealthCheckerForTests(async (_agent, role) => {
+        if (role === "developer") {
+            return {
+                ok: false,
+                reason: `developer unhealthy: ${_agent.name} — not authenticated — run cursor-agent login`,
+            };
+        }
+        return { ok: true };
+    });
+    enqueueIssue(issue.id);
+    assert.equal(await admitNext(), null);
+    assert.equal(getIssue(issue.id).status, "ready");
+    assert.equal(getActiveWorkflowInstance(issue.id), null);
+    const entry = getQueuedEntryForIssue(issue.id);
+    assert.equal(entry.state, "queued");
+    assert.match(entry.waitReason ?? "", /developer unhealthy/);
+    assert.doesNotMatch(entry.waitReason ?? "", /reviewer unhealthy/);
+});
 // NOT-157: soft probe failure wait_reason must name the probe, not "not authenticated".
 test("NOT-157: soft Cursor probe timeout waits with probe-timeout reason, not logged-out copy", async () => {
     const { clearAgentHealthCaches, setCursorProbeTimingForTests, } = await import("../adapters/agent-health.js");
@@ -346,7 +395,9 @@ test("NOT-157: soft Cursor probe timeout waits with probe-timeout reason, not lo
     fs.writeFileSync(stub, "#!/bin/sh\nsleep 30\n");
     fs.chmodSync(stub, 0o755);
     const prev = process.env.CURSOR_CLI;
+    const prevSkipHealth = process.env.AGENT_DEALER_SKIP_AGENT_HEALTH;
     process.env.CURSOR_CLI = stub;
+    delete process.env.AGENT_DEALER_SKIP_AGENT_HEALTH;
     setCursorProbeTimingForTests({ timeoutMs: 150, retryBackoffsMs: [20] });
     setAdmissionHealthCheckerForTests(null);
     clearAgentHealthCaches();
@@ -358,7 +409,7 @@ test("NOT-157: soft Cursor probe timeout waits with probe-timeout reason, not lo
         assert.equal(await admitNext(), null);
         const entry = getQueuedEntryForIssue(issue.id);
         assert.equal(entry?.state, "queued");
-        assert.match(entry.waitReason, /agent unhealthy/);
+        assert.match(entry.waitReason, /developer unhealthy/);
         assert.match(entry.waitReason, /probe timed out/i);
         assert.doesNotMatch(entry.waitReason, /not authenticated/i);
     }
@@ -367,6 +418,10 @@ test("NOT-157: soft Cursor probe timeout waits with probe-timeout reason, not lo
             delete process.env.CURSOR_CLI;
         else
             process.env.CURSOR_CLI = prev;
+        if (prevSkipHealth === undefined)
+            delete process.env.AGENT_DEALER_SKIP_AGENT_HEALTH;
+        else
+            process.env.AGENT_DEALER_SKIP_AGENT_HEALTH = prevSkipHealth;
         setCursorProbeTimingForTests(null);
         clearAgentHealthCaches();
         setAdmissionHealthCheckerForTests(async () => ({ ok: true }));

package/bundle/server/dist/coordinator/usage-cap-defer.js

@@ -179,6 +179,43 @@ export function deferLeasedWorkItemForDeckOutage(item, leaseToken, outage, issue
         });
     })();
 }
+export function agentUnhealthyDeferralStartedAt(payload) {
+    const v = payload.agentUnhealthySince;
+    return typeof v === "string" && v ? v : null;
+}
+export function agentUnhealthyDeferralCount(payload) {
+    const v = payload.agentUnhealthyDeferrals;
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0;
+}
+/**
+ * NOT-156: the active role failed health before spawn. Same shape as a deck outage — no
+ * infra burn, exponential backoff, never escalate (a false `mcp_not_registered` must not
+ * open a human gate; the role recovers when health does).
+ */
+export function deferLeasedWorkItemForAgentUnhealthy(item, leaseToken, unhealthy, issue, instance, nowMs = Date.now()) {
+    return getDb().transaction(() => {
+        const live = liveLeasedItem(item.id, leaseToken);
+        if (!live)
+            return { deferred: false, escalated: false, reason: "lease_lost" };
+        const payload = parsePayload(live.payloadJson);
+        const firstDeferredAt = agentUnhealthyDeferralStartedAt(payload) ?? new Date(nowMs).toISOString();
+        const priorDeferrals = agentUnhealthyDeferralCount(payload);
+        const until = new Date(nowMs + deckOutageBackoffMs(priorDeferrals)).toISOString();
+        return applyDeferral(live, leaseToken, issue, instance, {
+            until,
+            reason: unhealthy.reason,
+            outcome: "agent_unhealthy",
+            error: { kind: "agent_unhealthy", until, reason: unhealthy.reason, evidence: unhealthy.evidence },
+            payloadJson: JSON.stringify({
+                ...payload,
+                agentUnhealthySince: firstDeferredAt,
+                agentUnhealthyDeferrals: priorDeferrals + 1,
+            }),
+            // Reason is already role-prefixed (`reviewer unhealthy: …`).
+            intent: (_role, untilLabel) => `${unhealthy.reason} (retrying ${untilLabel})`,
+        });
+    })();
+}
 export function formatCapEscalationReason(cap, firstDeferredAt) {
     const hours = Math.round(usageCapDeferralCeilingMs() / 3_600_000);
     return `${cap.reason} Work deferred for over ${hours}h (since ${firstDeferredAt}).`;

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

@@ -21,11 +21,12 @@ import { parseProfileSnapshot } from "@agent-dealer/shared";
 import { buildProfileSnapshot, serializeProfileSnapshot } from "./profile-snapshot.js";
 import { recoverCoordinator } from "./recovery.js";
 import { observeClockJump } from "./clock-jump.js";
-import { admitNext } from "./admission.js";
+import { admitNext, checkRoleAgentHealthy } from "./admission.js";
 import { workerSessionPayload } from "./session-progress.js";
 import { runtimeAvailability } from "../repository/runtime-availability.js";
-import { deferLeasedWorkItemForUsageCap } from "./usage-cap-defer.js";
+import { deferLeasedWorkItemForUsageCap, deferLeasedWorkItemForAgentUnhealthy, } from "./usage-cap-defer.js";
 import { outcomeShouldRecordError, reasonForWorkerFailedEvent } from "./failure-reason.js";
+import { checkAgentDeckHealth } from "../adapters/agent-deck.js";
 const num = (name, dflt) => Number(process.env[name] ?? dflt);
 export const coordinatorConfig = {
     get maxConcurrency() {
@@ -167,6 +168,9 @@ async function processWorkItem(claimed) {
     // leaves a running session that recovery (which keys off work_items) cannot locate. The
     // bind is fenced on the lease token: if this attempt lost its lease between claim and
     // here, the transaction rolls back (session creation undone) and the attempt is dropped.
+    //
+    // Session setup stays synchronous until the first await below so `runCoordinatorTick`
+    // callers (and abort fences) still see a bound running session when started ≥ 1.
     let session;
     try {
         session = getDb().transaction(() => {
@@ -210,6 +214,20 @@ async function processWorkItem(claimed) {
         console.error("[coordinator] session setup", claimed.id, err);
         return; // lost the lease — recovery will reprocess the item when the lease expires
     }
+    // NOT-156: fail-closed for the role about to spawn only. Reviewer health must not have
+    // blocked developer admit; once a reviewer item is leased, park here (after bind, before
+    // the effect) instead of crashing into a deck/CLI failure loop. Checked after session
+    // bind so an await does not leave a leased item with no session for abort to fence.
+    {
+        const deckOnline = await checkAgentDeckHealth();
+        const health = await checkRoleAgentHealthy(issue, role, { deckOnline });
+        if (!health.ok) {
+            const live = getWorkItem(claimed.id) ?? claimed;
+            deferLeasedWorkItemForAgentUnhealthy(live, leaseToken, { kind: "agent_unhealthy", reason: health.reason }, issue, instance);
+            safeCompleteSession(session.id, "cancelled", { reason: health.reason });
+            return;
+        }
+    }
     const controller = new AbortController();
     const heartbeat = setInterval(() => {
         if (refreshHeartbeat(claimed.id, leaseToken, { leaseMs: coordinatorConfig.leaseMs })) {

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

@@ -17,7 +17,7 @@ const { BUILTIN_AGENT_CLAUDE_ID, BUILTIN_AGENT_CURSOR_ID } = await import("@agen
 const { createIssue, getIssue } = await import("../repository/issues.js");
 const { getActiveWorkflowInstance, listWorkflowEventsForIssue } = await import("../repository/workflow-events.js");
 const { listHumanActionsForIssue } = await import("../repository/human-actions.js");
-const { listWorkerSessionsForIssue, createWorkerSession, startSession } = await import("../repository/worker-sessions.js");
+const { listWorkerSessionsForIssue, createWorkerSession, startSession, getWorkerSession } = await import("../repository/worker-sessions.js");
 const { listWorkItemsForIssue, claimWorkItem, getWorkItem, bindWorkItemSession } = await import("../repository/work-items.js");
 const { startWorkflow, applyCompletion, resolveHumanActionAndAdvanceAsync } = await import("./commands.js");
 const { registerEffectHandler, resetEffectHandlers } = await import("./effect-registry.js");
@@ -26,6 +26,7 @@ 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");
+const { setAdmissionHealthCheckerForTests } = await import("./admission.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.
@@ -34,8 +35,12 @@ beforeEach(() => {
     clearFinalizeInflightForTests();
     setMergePrForTests(async () => ({ ok: true }));
     stubManagedCloneForTests("acme/app");
+    setAdmissionHealthCheckerForTests(async () => ({ ok: true }));
+});
+afterEach(() => {
+    resetEffectHandlers();
+    setAdmissionHealthCheckerForTests(null);
 });
-afterEach(() => resetEffectHandlers());
 function newIssue(maxReviewRounds = 3) {
     return createIssue({
         title: "Loop me",
@@ -327,3 +332,51 @@ test("placeholder handlers escalate rather than fabricating a PR", async () => {
     assert.equal(getIssue(issueId).status, "needs_human");
     assert.equal(listHumanActionsForIssue(issueId).find((a) => a.status === "open").actionType, "policy_escalation");
 });
+// NOT-156: after developer handoff, an unhealthy reviewer parks (explicit reason) instead of
+// spawning into a crash loop. Infra / attempt budgets stay untouched.
+test("NOT-156: reviewer unhealthy at review start parks with reviewer wait reason", async () => {
+    const prevBackoff = process.env.DECK_OUTAGE_BACKOFF_BASE_MS;
+    process.env.DECK_OUTAGE_BACKOFF_BASE_MS = "60000";
+    try {
+        const issueId = newIssue();
+        let reviewerSpawns = 0;
+        registerEffectHandler("developer", async () => cleanHandoff());
+        registerEffectHandler("reviewer", async () => {
+            reviewerSpawns++;
+            return approvedVerdict;
+        });
+        // Developer round is healthy; only the reviewer role fails health when lease time comes.
+        setAdmissionHealthCheckerForTests(async (_agent, role) => {
+            if (role === "reviewer") {
+                return {
+                    ok: false,
+                    reason: `reviewer unhealthy: ${_agent.name} — Run agent-deck setup --client claude --start (Claude MCP not registered)`,
+                };
+            }
+            return { ok: true };
+        });
+        startWorkflow(issueId);
+        await pump(5);
+        assert.equal(getIssue(issueId).status, "reviewing");
+        assert.equal(reviewerSpawns, 0, "unhealthy reviewer must not spawn");
+        assert.match(getIssue(issueId).currentIntent ?? "", /reviewer unhealthy/);
+        assert.match(getIssue(issueId).currentIntent ?? "", /MCP not registered/);
+        const reviewerItem = listWorkItemsForIssue(issueId).find((w) => w.kind === "reviewer");
+        assert.ok(reviewerItem);
+        assert.equal(reviewerItem.status, "pending");
+        assert.equal(reviewerItem.attemptCount, 0, "health park must not spend attempt budget");
+        assert.ok(Date.parse(reviewerItem.availableAt) > Date.now());
+        // Session is bound before the health await (abort fence), then cancelled on park —
+        // never left running, and the effect must not have run.
+        assert.ok(reviewerItem.workerSessionId, "park after bind still records the session");
+        assert.equal(getWorkerSession(reviewerItem.workerSessionId).status, "cancelled");
+        assert.ok(listWorkflowEventsForIssue(issueId).some((e) => e.type === "worker.deferred"), "timeline must record the park");
+        assert.equal(listHumanActionsForIssue(issueId).filter((a) => a.status === "open").length, 0, "must not open a human gate for a recoverable health wait");
+    }
+    finally {
+        if (prevBackoff === undefined)
+            delete process.env.DECK_OUTAGE_BACKOFF_BASE_MS;
+        else
+            process.env.DECK_OUTAGE_BACKOFF_BASE_MS = prevBackoff;
+    }
+});

package/bundle/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/server",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "type": "module",
   "main": "dist/index.js",
   "files": [
@@ -22,7 +22,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@agent-dealer/shared": "1.0.3",
+    "@agent-dealer/shared": "1.0.4",
     "@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.3",
+  "version": "1.0.4",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/package.json

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