agent-dealer 1.2.4 → 1.2.6

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

@@ -203,10 +203,11 @@ async function materializeWorkerMcpConfig(opts) {
     const mcpBase = getAgentDeckMcpUrl().replace(/\/mcp\/?$/, "");
     const mcpUrl = `${mcpBase}/mcp`;
     const headers = deckLaunchHeaders(opts.deckId, opts.worktreePath);
-    // Muse Code has no Agent Deck / MCP wiring (NOT-178 non-goal; NOT-181 owns it). Refuse before
-    // anything is written rather than fall through to the Claude config below.
+    // NOT-278: Muse Code settings come only from `prepareMuseAttempt`
+    // (runners/muse-config.ts) — never emit a Claude/Codex/Cursor config for Muse. Refuse
+    // before anything is written rather than fall through to the Claude config below.
     if (opts.runtime === "muse_code") {
-        throw new Error("Muse Code does not support Agent Deck MCP configuration");
+        throw new Error("Muse Code does not support Agent Deck MCP configuration via the shared materializer — its settings come only from prepareMuseAttempt");
     }
     if (opts.runtime === "codex_local") {
         const codexHome = path.join(getWorkerMcpConfigDir(), `codex-home-${opts.deckId.slice(0, 8)}-${randomUUID()}`);
@@ -370,6 +371,32 @@ async function verifyDeckConnection(opts) {
         }
     }
 }
+function toVerificationOutcome(verified) {
+    if (verified.ok)
+        return { ok: true };
+    return verified.kind === "deck_unavailable"
+        ? { ok: false, kind: "deck_unavailable", reason: `Agent Deck is unreachable — ${verified.reason}` }
+        : { ok: false, kind: "infra_failure", reason: `preflight failed: ${verified.reason}` };
+}
+/**
+ * NOT-278: live `get_bound_deck` (+ configured-playbook) preflight without materializing any
+ * runtime MCP config. Muse Code sessions use this: their settings.json comes only from
+ * `prepareMuseAttempt` (runners/muse-config.ts), so the shared materializer below must
+ * never run for them. Same result mapping as the materializing path: no response is
+ * `deck_unavailable`; a response that fails validation is `infra_failure` (surfaced by the
+ * effect as `deck_failure`).
+ */
+export async function verifyWorkerDeckConnection(opts) {
+    const timeoutMs = opts.timeoutMs ?? Number(process.env.DECK_BIND_TIMEOUT_MS ?? 30_000);
+    const verified = await verifyDeckConnection({
+        deckId: opts.deckId,
+        worktreePath: opts.worktreePath,
+        playbookIds: opts.playbookIds ?? [],
+        callTool: opts.callTool,
+        timeoutMs,
+    });
+    return toVerificationOutcome(verified);
+}
 /**
  * Materialize a per-attempt MCP config for the profile's deck and verify with
  * `get_bound_deck` and every configured playbook before spawn. No mint, no ledger, no
@@ -408,6 +435,9 @@ export async function prepareWorkerDeckConnection(opts) {
         catch {
             // best-effort
         }
+        // Same mapping as toVerificationOutcome, inlined so the result carries the
+        // materializing-path type (the shared helper's `ok: true` variant has no
+        // mcpConfigPath and is unreachable in this branch).
         return verified.kind === "deck_unavailable"
             ? { ok: false, kind: "deck_unavailable", reason: `Agent Deck is unreachable — ${verified.reason}` }
             : { ok: false, kind: "infra_failure", reason: `preflight failed: ${verified.reason}` };

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

@@ -12,7 +12,7 @@ import { parse as parseToml } from "smol-toml";
 import { StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-deckbind-"));
 const { migrate } = await import("../db/index.js");
-const { prepareWorkerDeckConnection, releaseWorkerDeckConnection, parseDeckToolResult, isDeckUnreachableError } = await import("./agent-deck-bind.js");
+const { prepareWorkerDeckConnection, releaseWorkerDeckConnection, parseDeckToolResult, isDeckUnreachableError, verifyWorkerDeckConnection } = await import("./agent-deck-bind.js");
 const { codexScopedConfigDeniesSendGate } = await import("./codex-scoped-config.js");
 const { roleCeiling } = await import("@agent-dealer/shared");
 /** Default worker policy: outboundMutation is false for BOTH roles (NOT-134). */
@@ -59,7 +59,65 @@ test("prepareWorkerDeckConnection verifies and writes a claude MCP config with d
         assert.equal(fs.existsSync(result.mcpConfigPath), false);
     }
 });
-test("prepareWorkerDeckConnection refuses Muse Code before writing any MCP config or verifying (NOT-178)", async () => {
+// NOT-278: Muse Code settings come only from prepareMuseAttempt — the shared materializer
+// must never run for Muse. Muse preflights through verifyWorkerDeckConnection instead.
+test("verifyWorkerDeckConnection preflights Muse without materializing any MCP config", async () => {
+    const calls = [];
+    const result = await verifyWorkerDeckConnection({
+        deckId: DECK,
+        worktreePath: WT,
+        callTool: async (name, args) => {
+            calls.push(name);
+            if (name === "get_bound_deck")
+                return textResult({ id: DECK, name: "personal-dev" });
+            return textResult({ id: args.playbook_id });
+        },
+    });
+    assert.equal(result.ok, true);
+    assert.deepEqual(calls, ["get_bound_deck"]);
+});
+test("verifyWorkerDeckConnection maps a wrong deck to infra_failure and silence to deck_unavailable", async () => {
+    const wrong = await verifyWorkerDeckConnection({
+        deckId: DECK,
+        worktreePath: WT,
+        callTool: async () => textResult({ id: "some-other-deck-id" }),
+    });
+    assert.equal(wrong.ok, false);
+    if (!wrong.ok) {
+        assert.equal(wrong.kind, "infra_failure");
+        assert.match(wrong.reason, /returned deck some-other-deck-id, expected/);
+    }
+    const silent = await verifyWorkerDeckConnection({
+        deckId: DECK,
+        worktreePath: WT,
+        callTool: async () => {
+            throw Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:1110"), { code: "ECONNREFUSED" });
+        },
+    });
+    assert.equal(silent.ok, false);
+    if (!silent.ok) {
+        assert.equal(silent.kind, "deck_unavailable");
+        assert.match(silent.reason, /unreachable/);
+    }
+});
+test("verifyWorkerDeckConnection maps a missing configured playbook to infra_failure (NOT-278)", async () => {
+    const missing = await verifyWorkerDeckConnection({
+        deckId: DECK,
+        worktreePath: WT,
+        playbookIds: ["pb-required"],
+        callTool: async (name, args) => {
+            if (name === "get_bound_deck")
+                return textResult({ id: DECK, name: "personal-dev" });
+            return errorResult(`playbook ${args.playbook_id} not found`);
+        },
+    });
+    assert.equal(missing.ok, false);
+    if (!missing.ok) {
+        assert.equal(missing.kind, "infra_failure");
+        assert.match(missing.reason, /preflight failed/);
+    }
+});
+test("prepareWorkerDeckConnection refuses Muse Code before writing any MCP config or verifying (NOT-278)", async () => {
     let verifyCalled = false;
     const result = await prepareWorkerDeckConnection({
         policy: DENIED,

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

@@ -4,6 +4,7 @@ import { CODEX_AUTH_REMEDIATION, MUSE_AUTH_REMEDIATION, cursorAuthIssueFromOutpu
 import { claudeBinExists, cursorBinExists, resolveClaudeBin, cursorInvokeArgs, resolveCursorBin, resolveCodexBin, codexBinExists, resolveMuseBin, museBinExists, resolveMuseAuthFile, MUSE_CLI_ENV, } from "../cli-env.js";
 import { checkAgentDeckHealth, checkAgentDeckMcpRegistration, fetchDecks, } from "./agent-deck.js";
 import { runtimeAvailability } from "../repository/runtime-availability.js";
+import { museCapabilityCheckInFlight, museCapabilityIssues, museCapabilitySettleCount, parseMuseVersion, resetMuseCapabilityStateForTests, } from "./muse-capability.js";
 const RUNTIME_LABEL = {
     claude_code: "Claude",
     cursor_local: "Cursor",
@@ -112,6 +113,7 @@ export function clearAgentHealthCaches() {
     githubIssueCache = null;
     cursorSoftFailStreak = 0;
     cursorLastHealthyAt = null;
+    resetMuseCapabilityStateForTests();
 }
 function isSoftCursorProbeIssue(issue) {
     return (issue.code === "runtime_auth" &&
@@ -195,6 +197,11 @@ async function cursorRuntimeIssues() {
  * billed `muse exec`, so a *present* but expired login is not detectable here — it surfaces at
  * the first run, which the same classifier reads from stderr. `auth.json` is tested for
  * existence only, never read.
+ *
+ * NOT-277: with CLI and credentials present, the reported version is handed to the capability
+ * check — a version not yet checked runs one real developer-shell probe (muse-capability.ts);
+ * `runtime_capability` blocks while it runs, when it finds shell/write missing, or when it could
+ * not complete.
  */
 async function museRuntimeIssues() {
     const bin = resolveMuseBin();
@@ -224,7 +231,17 @@ async function museRuntimeIssues() {
     if (!process.env.META_API_KEY && !fs.existsSync(resolveMuseAuthFile())) {
         return [{ code: "runtime_auth", message: MUSE_AUTH_REMEDIATION }];
     }
-    return [];
+    const version = parseMuseVersion(ver.output);
+    if (!version) {
+        return [
+            {
+                code: "runtime_unknown",
+                message: "Could not determine Muse Code health — `muse --version` printed no version",
+            },
+        ];
+    }
+    // A settled check drops the cached result so admission sees it on its next health read.
+    return museCapabilityIssues(version, () => runtimeIssueCache.delete("muse_code"));
 }
 /** Exported for direct testing — bypasses the 60s cache in runtimeIssues(). */
 export async function runtimeIssuesUncached(runtime) {
@@ -427,12 +444,18 @@ async function runtimeIssues(runtime) {
     if (cached && Date.now() - cached.at < ttl) {
         return [...capIssues, ...cached.issues];
     }
+    const museSettles = museCapabilitySettleCount();
     const issues = await runtimeIssuesUncached(runtime);
     const nonCap = issues.filter((i) => i.code !== "usage_capped");
+    // NOT-277: a capability check that settled during this read already superseded what it returned.
+    if (runtime === "muse_code" && museCapabilitySettleCount() !== museSettles) {
+        return runtimeIssues(runtime);
+    }
     // Soft fail (published or grace-held) uses a short TTL so a wake retry can clear quickly;
     // a sticky 60s cache of "Could not confirm" is what parked the queue after sleep (NOT-157).
     const softProbeFailure = nonCap.some(isSoftCursorProbeIssue) ||
-        (runtime === "cursor_local" && cursorSoftFailStreak > 0);
+        (runtime === "cursor_local" && cursorSoftFailStreak > 0) ||
+        (runtime === "muse_code" && museCapabilityCheckInFlight());
     runtimeIssueCache.set(runtime, { at: Date.now(), issues: nonCap, softProbeFailure });
     return [...capIssues, ...nonCap];
 }
@@ -446,10 +469,9 @@ function resolveMcpRegistration(mcpRegistered) {
 }
 function agentSpecificIssues(agent, agentDeckOnline, mcpRegistration, deckAccessResult) {
     const issues = [];
-    // NOT-181: a Muse Code worker gets no MCP servers and no Agent Deck, so a missing, offline or
-    // deleted deck cannot stop it. (The profile form still asks for one; Muse ignores it.)
-    if (agent.runtime === "muse_code")
-        return issues;
+    // NOT-278: a Muse Code developer session receives the selected deck exactly like the other
+    // developer runtimes, so `deck_missing`, `deck_offline`, and `deck_unauthorized` apply to
+    // Muse too. Only the Claude-only `mcp_not_registered` check below stays Claude-only.
     if (!agent.deckId) {
         issues.push({
             code: "deck_missing",

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

@@ -16,7 +16,10 @@ process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-ag
 const { migrate, getDb } = await import("../db/index.js");
 const { createAgent, getAgent } = await import("../repository/agents.js");
 const { healthForAgent, runtimeIssuesUncached, githubIssuesUncached, githubIssuesSync, classifyGithubAuthStatus, clearAgentHealthCaches, setCursorProbeTimingForTests, setRunCommandForTests, } = await import("./agent-health.js");
+const { setMuseCapabilityProbeForTests, settleMuseCapabilityCheckForTests } = await import("./muse-capability.js");
 migrate();
+// NOT-277: health never runs the real (billed) Muse capability probe in tests.
+setMuseCapabilityProbeForTests(async () => ({ status: "capable" }));
 const FAILURE = { ok: false, code: "DECK_UNAVAILABLE", message: "Agent Deck API error: 502" };
 /** Tests inject an empty github list so host `gh auth` does not pollute assertions. */
 const NO_GITHUB = [];
@@ -34,18 +37,20 @@ describe("agent-health", { concurrency: false }, () => {
         assert.equal(result.issues.some((i) => i.code === "deck_missing"), true);
         assert.equal(result.healthy, false);
     });
-    // NOT-181: a Muse Code worker gets no MCP servers and no Agent Deck, so no deck problem may park it.
-    test("muse_code ignores deck state: no deck, offline deck or unreadable deck raises a deck issue", async () => {
+    // NOT-278: a Muse Code developer session receives the selected deck exactly like the other
+    // developer runtimes, so deck_missing, deck_offline, and deck_unauthorized apply to Muse too.
+    test("muse_code reports deck state: missing deck, offline deck, and unreadable deck raise deck issues", async () => {
         const created = createAgent({ name: "muse-no-deck", runtime: "muse_code", deckId: randomUUID() });
         getDb().prepare("UPDATE agents SET deck_id = NULL WHERE id = ?").run(created.id);
-        for (const [agent, online] of [
-            [getAgent(created.id), true],
-            [createAgent({ name: "muse-offline", runtime: "muse_code", deckId: randomUUID() }), false],
-            [createAgent({ name: "muse-stale", runtime: "muse_code", deckId: randomUUID() }), true],
-        ]) {
+        const cases = [
+            { agent: getAgent(created.id), online: true, code: "deck_missing" },
+            { agent: createAgent({ name: "muse-offline", runtime: "muse_code", deckId: randomUUID() }), online: false, code: "deck_offline" },
+            { agent: createAgent({ name: "muse-stale", runtime: "muse_code", deckId: randomUUID() }), online: true, code: "deck_unauthorized" },
+        ];
+        for (const { agent, online, code } of cases) {
             const result = await healthForAgent(agent, online, new Map(), true, FAILURE, NO_GITHUB);
-            assert.deepEqual(result.issues, [], agent.name);
-            assert.equal(result.healthy, true);
+            assert.equal(result.issues.some((i) => i.code === code), true, `${agent.name} reports ${code}`);
+            assert.equal(result.healthy, false);
         }
     });
     test("agent deck offline: reports deck_offline, not deck_unauthorized", async () => {
@@ -414,8 +419,14 @@ The keychain item is stuck. Delete it and sign in again:
         const withLogin = emptyConfigHome();
         fs.mkdirSync(path.join(withLogin, "muse"));
         fs.writeFileSync(path.join(withLogin, "muse", "auth.json"), "{}");
-        assert.deepEqual(await withMuseEnv({ MUSE_CLI: stub.bin, configHome: withLogin }, () => runtimeIssuesUncached("muse_code")), []);
-        assert.deepEqual(await withMuseEnv({ MUSE_CLI: stub.bin, META_API_KEY: "k", configHome: emptyConfigHome() }, () => runtimeIssuesUncached("muse_code")), []);
+        // NOT-277: the first read of a version starts its one-time capability check; healthy once settled.
+        const settledIssues = async () => {
+            await runtimeIssuesUncached("muse_code");
+            await settleMuseCapabilityCheckForTests();
+            return runtimeIssuesUncached("muse_code");
+        };
+        assert.deepEqual(await withMuseEnv({ MUSE_CLI: stub.bin, configHome: withLogin }, settledIssues), []);
+        assert.deepEqual(await withMuseEnv({ MUSE_CLI: stub.bin, META_API_KEY: "k", configHome: emptyConfigHome() }, settledIssues), []);
     });
     test("muse probes run with MUSE_NO_AUTO_UPDATE=1 so the launcher cannot swap the pinned version", async () => {
         const stub = stubMuse("echo 'Muse Code 1.3.0 (1.3.0-R3401.1)'");
@@ -442,6 +453,50 @@ The keychain item is stuck. Delete it and sign in again:
             setCursorProbeTimingForTests(null);
         }
     });
+    // NOT-277: through the cached health path the agent list / admission read — a Muse auto-update
+    // fires the capability check exactly once for the new version, and the result (not a generic
+    // symptom) is what the unhealthy agent shows.
+    test("a Muse version change is capability-checked once and its named result surfaces on the agent", async () => {
+        const OLD = "1.3.0-R3401.1";
+        const NEW = "1.4.0-R4161.1";
+        const versionFile = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-ver-")), "v");
+        fs.writeFileSync(versionFile, `Muse Code 1.3.0 (${OLD})\n`);
+        const stub = stubMuse(`cat ${JSON.stringify(versionFile)}`);
+        const calls = [];
+        setMuseCapabilityProbeForTests(async (version) => {
+            calls.push(version);
+            return version === OLD
+                ? { status: "capable" }
+                : { status: "missing", detail: "probe session completed without running its shell command" };
+        });
+        const agent = createAgent({ name: "muse-updated", runtime: "muse_code", deckId: randomUUID() });
+        const health = () => healthForAgent(agent, true, undefined, true, null, NO_GITHUB);
+        try {
+            await withMuseEnv({ MUSE_CLI: stub.bin, META_API_KEY: "k", configHome: emptyConfigHome() }, async () => {
+                // The stub probe settles within this read; the health read must not cache its stale
+                // "verifying" block (the in-flight block itself is covered in muse-capability.test.ts).
+                await health();
+                await settleMuseCapabilityCheckForTests();
+                for (let i = 0; i < 3; i++)
+                    assert.deepEqual((await health()).issues, []);
+                assert.deepEqual(calls, [OLD]);
+                // Muse auto-updates. The 60s runtime cache notices on its next miss.
+                fs.writeFileSync(versionFile, `Muse Code 1.4.0 (${NEW})\n`);
+                await runtimeIssuesUncached("muse_code");
+                await settleMuseCapabilityCheckForTests();
+                for (let i = 0; i < 3; i++) {
+                    const after = await health();
+                    assert.equal(after.healthy, false);
+                    assert.deepEqual(after.issues.map((x) => x.code), ["runtime_capability"]);
+                    assert.match(after.issues[0].message, new RegExp(`Muse Code updated ${OLD} → ${NEW}: developer sessions no longer get shell/write access`));
+                }
+                assert.deepEqual(calls, [OLD, NEW]);
+            });
+        }
+        finally {
+            setMuseCapabilityProbeForTests(async () => ({ status: "capable" }));
+        }
+    });
     test("claude MCP endpoint mismatch surfaces a distinct message, not the generic setup hint", async () => {
         const agent = createAgent({
             name: "claude-mcp-mismatch",

package/bundle/server/dist/adapters/git-worktree.js

@@ -9,6 +9,7 @@
 // Lifted from archive/not-57-full-p0-slice and extended with role-aware creation,
 // safe (non-destructive) removal, and leftover inspection for crash recovery.
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { promisify } from "node:util";
@@ -192,14 +193,28 @@ export async function removeWorktree(opts) {
     args.push(opts.path);
     await git(opts.repo, args);
 }
+/**
+ * NOT-280: `git status --porcelain` without the opportunistic index refresh — plain status
+ * rewrites a stale-stat index, which would mutate a checkout a refusal path must leave
+ * untouched (outside root, wrong branch, unknown owner).
+ */
+async function readOnlyStatus(worktreePath) {
+    return (await git(worktreePath, ["--no-optional-locks", "status", "--porcelain"])).stdout;
+}
 export async function isWorktreeClean(worktreePath) {
-    const { stdout } = await git(worktreePath, ["status", "--porcelain"]);
-    return stdout.trim().length === 0;
+    return (await readOnlyStatus(worktreePath)).trim().length === 0;
 }
 /** Commit message for a timeout salvage tip (NOT-145). */
 export const SALVAGE_TIMEOUT_MESSAGE = "wip: timeout salvage";
 /** Commit message for a crash/non-zero exit salvage tip (NOT-145). */
 export const SALVAGE_CRASH_MESSAGE = "wip: crash salvage";
+/** Commit message for a dead predecessor's dirt salvaged before a new attempt (NOT-280). */
+export const SALVAGE_RESUME_MESSAGE = "wip: resume salvage";
+const SALVAGE_MESSAGES = {
+    timeout: SALVAGE_TIMEOUT_MESSAGE,
+    crash: SALVAGE_CRASH_MESSAGE,
+    resume: SALVAGE_RESUME_MESSAGE,
+};
 /**
  * NOT-145: stage everything and commit a clearly marked salvage tip so a timeout/crash
  * can remove the worktree for retry without silently discarding uncommitted WIP.
@@ -207,7 +222,7 @@ export const SALVAGE_CRASH_MESSAGE = "wip: crash salvage";
  * (parent NOT-143), not a preserved dirty checkout the next attempt cannot adopt.
  */
 export async function salvageDirtyWorktree(worktreePath, kind) {
-    const message = kind === "timeout" ? SALVAGE_TIMEOUT_MESSAGE : SALVAGE_CRASH_MESSAGE;
+    const message = SALVAGE_MESSAGES[kind];
     try {
         await git(worktreePath, ["add", "-A"]);
         // Explicit identity: coordinator-managed worktrees may lack user.name/email, and a
@@ -690,6 +705,96 @@ export function sessionIdFromRoleWorktreePath(worktreePath) {
     const m = /^(.*)-(developer|reviewer)$/.exec(base);
     return m?.[1] ?? null;
 }
+function sha256Hex(parts) {
+    return createHash("sha256").update(parts.join("\0")).digest("hex");
+}
+/**
+ * NOT-280: stable identity of a leftover's blocking state. Best-effort reads of HEAD and
+ * status: an unreadable checkout still fingerprints (by path + reason), so repeated
+ * Resumes against the same corrupt tree dedupe too.
+ */
+export async function leftoverFingerprint(worktreePath, reason) {
+    const head = await git(worktreePath, ["rev-parse", "HEAD"]).then((r) => r.stdout.trim(), () => "");
+    const status = await readOnlyStatus(worktreePath).catch(() => "");
+    return sha256Hex([tryRealpath(worktreePath), reason, head, status]);
+}
+/** Unmerged index entries (`git status --porcelain` XY codes) — a half-resolved merge. */
+const UNMERGED_STATUS = /^(DD|AU|UD|UA|DU|AA|UU) /m;
+/**
+ * NOT-280: commit a proven-dead predecessor's dirty managed checkout on the issue branch
+ * so the next attempt can continue from that tip. Inspects before touching anything:
+ * the checkout must be on exactly `refs/heads/<branch>` with no in-progress merge/
+ * cherry-pick/revert and no unmerged entries — anything else fails closed. A failed
+ * commit (e.g. a rejecting hook) restores the index it staged, so the checkout is left
+ * exactly as found.
+ */
+export async function salvagePredecessorWorktree(worktreePath, branchName) {
+    let headRef;
+    let status;
+    let indexTree;
+    // Branch identity first, so a wrong-branch checkout is refused before any status read.
+    try {
+        headRef = (await git(worktreePath, ["symbolic-ref", "-q", "HEAD"])).stdout.trim();
+    }
+    catch (err) {
+        return { ok: false, reason: `inspection failed: ${err.message}` };
+    }
+    if (headRef !== `refs/heads/${branchName}`) {
+        return { ok: false, reason: `checkout is on ${headRef || "a detached HEAD"}, not refs/heads/${branchName}` };
+    }
+    try {
+        status = await readOnlyStatus(worktreePath);
+    }
+    catch (err) {
+        return { ok: false, reason: `inspection failed: ${err.message}` };
+    }
+    if (UNMERGED_STATUS.test(status)) {
+        return { ok: false, reason: "checkout has unmerged paths (an unfinished merge/rebase)" };
+    }
+    for (const marker of ["MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD"]) {
+        if (await refExists(worktreePath, marker)) {
+            return { ok: false, reason: `checkout has an in-progress operation (${marker} exists)` };
+        }
+    }
+    try {
+        indexTree = (await git(worktreePath, ["write-tree"])).stdout.trim();
+    }
+    catch (err) {
+        return { ok: false, reason: `inspection failed: ${err.message}` };
+    }
+    const headBefore = await revParseHead(worktreePath);
+    const salvaged = await salvageDirtyWorktree(worktreePath, "resume");
+    if (salvaged.ok)
+        return salvaged;
+    // Undo the `git add -A` staging when the commit itself did not land; a landed commit
+    // with residual dirt keeps its commit (the work is saved) and still fails closed.
+    // A failed rollback leaves the salvage's staging in place, so it is reported alongside
+    // the commit failure rather than claiming the checkout was left as found.
+    const headAfter = await revParseHead(worktreePath).catch(() => null);
+    if (headAfter === headBefore) {
+        try {
+            await git(worktreePath, ["read-tree", indexTree]);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                reason: `${salvaged.reason}; restoring the index afterwards also failed (git read-tree ${indexTree}): ${err.message} — files in ${worktreePath} are untouched but \`git add -A\` staging remains`,
+            };
+        }
+    }
+    return { ok: false, reason: salvaged.reason };
+}
+/** Whether HEAD's subject is a resume-salvage tip (restart after the commit landed). */
+async function headIsResumeSalvage(worktreePath) {
+    try {
+        const { stdout } = await git(worktreePath, ["log", "-1", "--format=%H%x00%s"]);
+        const [sha, subject] = stdout.trim().split("\0");
+        return subject === SALVAGE_RESUME_MESSAGE && sha ? sha : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * The developer-setup half of design §"Worktree lifecycle and concurrency"'s crash-recovery
  * requirement: a leftover worktree from an earlier round/escalation on the SAME issue branch
@@ -707,31 +812,40 @@ export function sessionIdFromRoleWorktreePath(worktreePath) {
  */
 export async function resolveDeveloperWorktree(opts) {
     return withRepoLock(opts.repo, async () => {
-        await pruneWorktrees(opts.repo);
-        // NOT-219: a repair round reuses an existing issue branch, so first fetch
+        // NOT-280: no up-front `git worktree prune` — it deletes `.git/worktrees/*` admin
+        // entries, so it runs only once no refusal (outside root, live owner, dirt, unreadable
+        // checkout) applies: for a vanished leftover here, otherwise right before the add below.
+        // NOT-219: a repair round reuses an existing issue branch, so fetch
         // `origin/<branch>` — the worktree must start at exactly what Dealer pushed,
         // never the managed clone's possibly-stale local ref. A failed fetch defers the
         // start (`base_unavailable`) instead of falling back to the stale local branch.
+        // NOT-280: the fetch runs only once every refusal check (outside root, live owner,
+        // unknown-owner dirt, unreadable checkout) has passed, so a refused leftover leaves
+        // the shared repository's refs, FETCH_HEAD and objects untouched.
+        const fetchReuse = async () => opts.reuseBranch
+            ? fetchReusedBranch(opts.repo, opts.branchName, opts.fetchTimeoutMs)
+            : { ok: true, remoteSha: null };
         let reuseRemoteSha = null;
-        if (opts.reuseBranch) {
-            const reused = await fetchReusedBranch(opts.repo, opts.branchName, opts.fetchTimeoutMs);
-            if (!reused.ok) {
-                return { kind: "base_unavailable", reason: reused.reason };
-            }
-            reuseRemoteSha = reused.remoteSha;
+        let existing = await findWorktreeForBranch(opts.repo, opts.branchName);
+        if (existing && !fs.existsSync(existing)) {
+            // A registered checkout whose directory is gone is a stale administrative entry
+            // (pre-NOT-280 this was pruned before the lookup): prune it and look again.
+            await pruneWorktrees(opts.repo);
+            existing = await findWorktreeForBranch(opts.repo, opts.branchName);
         }
-        const existing = await findWorktreeForBranch(opts.repo, opts.branchName);
         if (existing) {
             const managedRoot = opts.worktreePath
                 ? tryRealpath(path.dirname(opts.worktreePath))
                 : tryRealpath(worktreesRoot(opts.repo));
             const underRoot = tryRealpath(existing).startsWith(managedRoot + path.sep);
             if (!underRoot) {
+                const reason = `Branch ${opts.branchName} is already checked out at ${existing}, outside the coordinator's managed worktrees — it cannot be safely reused or removed automatically.`;
                 return {
                     kind: "conflict",
                     path: existing,
-                    reason: `Branch ${opts.branchName} is already checked out at ${existing}, outside the coordinator's managed worktrees — it cannot be safely reused or removed automatically.`,
+                    reason,
                     recoveryCommands: [`git -C ${opts.repo} worktree list`, `# free the branch, then Resume: cd ${existing} && git status`],
+                    fingerprint: await leftoverFingerprint(existing, reason),
                 };
             }
             // Live owner first — clean/dirty are only meaningful once the predecessor is gone.
@@ -744,8 +858,45 @@ export async function resolveDeveloperWorktree(opts) {
                     reason: `Developer worktree for branch ${opts.branchName} at ${existing} is still in use by session ${owner.sessionId} (live process) — refusing to adopt it or escalate as a worktree conflict.`,
                 };
             }
-            const state = await inspectLeftoverWorktree(existing);
+            // NOT-280: only a known Dealer session proven dead may have its dirt salvaged.
+            const deadPredecessor = owner.state === "dead" ? (owner.sessionId ?? null) : null;
+            let state = await inspectLeftoverWorktree(existing);
+            let salvage;
+            let salvageFailure = null;
+            if (state === "dirty_or_unpushed" && deadPredecessor) {
+                const salvaged = await salvagePredecessorWorktree(existing, opts.branchName);
+                if (salvaged.ok) {
+                    salvage = {
+                        commitSha: salvaged.commitSha,
+                        message: salvaged.message,
+                        predecessorSessionId: deadPredecessor,
+                        recovered: false,
+                    };
+                    state = await inspectLeftoverWorktree(existing);
+                }
+                else {
+                    salvageFailure = salvaged.reason;
+                }
+            }
+            else if (state === "clean" && deadPredecessor) {
+                // Restart after the salvage commit landed but before the attempt continued: the
+                // saved tip is detected, never re-committed.
+                const landed = await headIsResumeSalvage(existing);
+                if (landed) {
+                    salvage = {
+                        commitSha: landed,
+                        message: SALVAGE_RESUME_MESSAGE,
+                        predecessorSessionId: deadPredecessor,
+                        recovered: true,
+                    };
+                }
+            }
             if (state === "clean") {
+                const reused = await fetchReuse();
+                if (!reused.ok) {
+                    return { kind: "base_unavailable", reason: reused.reason };
+                }
+                reuseRemoteSha = reused.remoteSha;
                 // NOT-219: a clean leftover holding a stale local branch advances to the
                 // fetched remote tip when that is a strict fast-forward (nothing unique to
                 // lose — the local tip is already an ancestor of the remote one). Any other
@@ -758,19 +909,26 @@ export async function resolveDeveloperWorktree(opts) {
                         await git(existing, ["merge", "--ff-only", "-q", `origin/${opts.branchName}`]).catch(() => null);
                     }
                 }
-                return { kind: "reused", path: tryRealpath(existing) };
+                return { kind: "reused", path: tryRealpath(existing), ...(salvage ? { salvage } : {}) };
             }
             if (state === "dirty_or_unpushed") {
+                const base = `A previous developer worktree for branch ${opts.branchName} still holds it at ${existing} with uncommitted changes.`;
+                const reason = salvageFailure
+                    ? `${base} Automatic salvage of dead session ${deadPredecessor}'s work failed and the checkout was preserved (not removed or reset): ${salvageFailure}`
+                    : salvage
+                        ? `${base} Salvage tip ${salvage.commitSha.slice(0, 7)} landed but the checkout is still dirty.`
+                        : base;
                 return {
                     kind: "conflict",
                     path: existing,
-                    reason: `A previous developer worktree for branch ${opts.branchName} still holds it at ${existing} with uncommitted changes.`,
+                    reason,
                     recoveryCommands: [
                         `cd ${existing}`,
                         "git status",
                         "git log --oneline -5",
                         `# once the work there is safe (pushed or intentionally discarded): git -C ${opts.repo} worktree remove ${existing} --force`,
                     ],
+                    fingerprint: await leftoverFingerprint(existing, reason),
                 };
             }
             // inspectLeftoverWorktree reports "missing" for ANY `git status` failure, not just a
@@ -780,23 +938,34 @@ export async function resolveDeveloperWorktree(opts) {
             // below — a narrower repeat of the exact loop this function exists to close). Only a
             // truly gone directory is safe to treat as a stale administrative entry.
             if (fs.existsSync(existing)) {
+                const reason = `A previous developer worktree for branch ${opts.branchName} exists at ${existing} but its status could not be determined.`;
                 return {
                     kind: "conflict",
                     path: existing,
-                    reason: `A previous developer worktree for branch ${opts.branchName} exists at ${existing} but its status could not be determined.`,
+                    reason,
                     recoveryCommands: [
                         `cd ${existing}`,
                         "git status",
                         `# once resolved: git -C ${opts.repo} worktree remove ${existing} --force`,
                     ],
+                    fingerprint: await leftoverFingerprint(existing, reason),
                 };
             }
-            await pruneWorktrees(opts.repo);
         }
+        // Clear stale registrations (e.g. a vanished checkout at the target path) before the
+        // add — every refusal path above has already returned without mutating anything.
+        await pruneWorktrees(opts.repo);
         // NOT-197: a fresh issue branch starts from the freshly fetched
         // `origin/<baseBranch>` tip — never the cached clone's possibly-stale local base.
         // A failed fetch returns `base_unavailable` (no branch is created) instead of
         // silently falling back to the stale local branch.
+        if (opts.reuseBranch) {
+            const reused = await fetchReuse();
+            if (!reused.ok) {
+                return { kind: "base_unavailable", reason: reused.reason };
+            }
+            reuseRemoteSha = reused.remoteSha;
+        }
         let ref;
         let newBranch;
         let baseSha = null;