agent-dealer 1.2.5 → 1.2.7

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

@@ -469,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

@@ -37,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 () => {

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;