@songsid/agend 2.2.0 → 2.2.5

package/dist/daemon.js

@@ -1,5 +1,6 @@
 import { AGENT_WHATS_NEW, agendVersion, planWhatsNew, readWhatsNewRecord, recordWhatsNew, whatsNewNotice } from "./agent-whats-new.js";
-import { join, dirname, basename, resolve } from "node:path";
+import { join, dirname, resolve } from "node:path";
+import { checkoutTarget, readCheckouts, releaseCandidate, reposRoot, verifyWorktree, writeCheckouts } from "./repo-worktree-guard.js";
 import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, unlinkSync, rmSync, appendFileSync, statSync, renameSync } from "node:fs";
 import { COMPACT_WATCH_TIMEOUT_MS, launchIdentity } from "./compact-watch.js";
 import { KIRO_COMPACT_PANE_LINES, KiroCompactPaneFollower } from "./kiro-compact-pane.js";
@@ -19,6 +20,9 @@ import { TranscriptTurnLedger } from "./transcript-turns.js";
 import { credentialProfileStoreHome, resolveCredentialProfile } from "./backend/credential-profile.js";
 import { resolveToolSet } from "./tool-permissions.js";
 import { getAgendHome } from "./paths.js";
+import { readAgentEffect, sendEffectInParts } from "./web-effect-upload.js";
+import { readAgentFile } from "./agent-file-read.js";
+import { ASSET_UPLOAD_MAX_BYTES, MOD_FILE, MOD_MAX_PARTS, MOD_UPLOAD_MAX_BYTES, receiveFiles, receivePreview, sendAssetInParts, writeModFile, writePreview } from "./web-asset-parts.js";
 import { LOGIN_FLOWS } from "./login-flows.js";
 import { ProgressAccumulator, summarizeProgress } from "./tool-progress.js";
 import { assembleSystemPrompt, resolveWorkflowText } from "./prompt-file-ref.js";
@@ -52,9 +56,33 @@ import { codexLiveRowMatches } from "./backend/codex.js";
 import { claudeConfigDirFor, claudeProfileConfigDir, claudeSwitchDialog, claudeSwitchTargetMatches } from "./backend/claude-code.js";
 import { InteractionObservation, INTERACTION_CONFIRM_MS, sameInteractionOwner } from "./interaction-observation.js";
 import { unrecognisedPromptShape } from "./unrecognised-prompt.js";
+/** #2140: deliveries that may carry an unwritten what's-new notice before it is recorded anyway. */
+const WHATS_NEW_MAX_UNWRITTEN = 3;
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Tool routing sets — module-level to avoid re-creation on every handleToolCall
+/** #1629: the caller's own web theme tools, each its own typed IPC message (one tool per type, for the permission check). */
+const WEB_THEME_IPC = Object.freeze({
+    get_web_theme: "fleet_get_web_theme", set_web_theme: "fleet_set_web_theme",
+    set_web_theme_asset: "fleet_set_web_theme_asset", reset_web_theme: "fleet_reset_web_theme",
+    // r4 §1: how it appears — read-only; a preview's files are written here, on the agent's side.
+    get_web_appearance: "fleet_get_web_appearance", preview_web_appearance: "fleet_preview_web_appearance",
+    // r4-4: its own declarative widgets.
+    set_web_widget: "fleet_set_web_widget", remove_web_widget: "fleet_remove_web_widget",
+    // #2117: its own declarative ambient.
+    set_web_ambient: "fleet_set_web_ambient", clear_web_ambient: "fleet_clear_web_ambient",
+    // r4-5b: mods — an export's file is written here, a proposal's file read here (on the agent's side).
+    export_web_mod: "fleet_export_web_mod", propose_web_mod: "fleet_propose_web_mod",
+    upload_web_effect: "fleet_upload_web_effect",
+    list_web_effects: "fleet_list_web_effects",
+    preview_web_effect: "fleet_preview_web_effect",
+    profile_web_effect: "fleet_profile_web_effect",
+    apply_web_effect: "fleet_apply_web_effect",
+    remove_web_effect: "fleet_remove_web_effect",
+    delete_web_effect: "fleet_delete_web_effect",
+});
+/** The largest picture any slot may take (a card slot's ceiling; the fleet checks the limit in force): read no more. */
+const WEB_THEME_ASSET_MAX_BYTES = ASSET_UPLOAD_MAX_BYTES;
 const CROSS_INSTANCE_TOOLS = new Set(["send_to_instance", "broadcast", "list_instances", "start_instance", "restart_instance", "create_instance", "delete_instance", "replace_instance", "request_information", "delegate_task", "report_result", "delivery_status", "describe_instance"]);
 const SCHEDULE_TOOLS = new Set(["create_schedule", "list_schedules", "update_schedule", "delete_schedule"]);
 const DECISION_TOOLS = new Set(["post_decision", "list_decisions", "update_decision"]);
@@ -1073,7 +1101,7 @@ export class BlockingProcessDetector {
 /** Response types the fleet sends back for tool calls the daemon forwarded. */
 const FLEET_RESPONSE_TYPES = new Set([
     "fleet_schedule_response", "fleet_outbound_response", "fleet_decision_response", "fleet_task_response",
-    "fleet_display_name_response", "fleet_description_response", "fleet_persona_emoji_response",
+    "fleet_display_name_response", "fleet_description_response", "fleet_persona_emoji_response", "fleet_web_theme_response",
 ]);
 export class Daemon extends EventEmitter {
     name;
@@ -1466,6 +1494,8 @@ export class Daemon extends EventEmitter {
     pendingInstructionsNotice = false;
     /** #1633: the one-time "what's new for you" notice, pasted before the next real delivery; recorded once pasted. */
     pendingWhatsNew = null;
+    /** #2140: deliveries tried for the pending what's-new notice that never reached the pane (capped: never before every message). */
+    whatsNewUnwritten = 0;
     // Whether the warmup steering-reload notice should be injected after spawn.
     // Set in trySpawn by comparing the freshly-built instructions against the
     // last value the agent was told about (prev-instructions). Skipped when
@@ -1535,6 +1565,7 @@ export class Daemon extends EventEmitter {
     windowQueryFailureTicks = 0;
     mcpRestartPending = false;
     mcpRestartStaleTimer = null;
+    mcpRestartCooldownTimer = null;
     /** In-flight replacement grace; also the guard against three triggers stacking. */
     mcpRestartGraceTimer = null;
     /**
@@ -2553,6 +2584,24 @@ export class Daemon extends EventEmitter {
             this.fireMcpRestartRequest("already_idle");
         }
     }
+    /** Keep a cooldown-suppressed revival alive without bypassing the idle gate. */
+    deferMcpRestart(delayMs) {
+        this.clearMcpRestartRequest();
+        if (this.config.mcp_auto_restart === false || this.authFailureUnresolved
+            || this.mcpRestartCancelledByRecovery("cooldown"))
+            return;
+        this.mcpRestartPending = true;
+        this.mcpRestartCooldownTimer = setTimeout(() => {
+            this.mcpRestartCooldownTimer = null;
+            if (this.mcpRestartCancelledByRecovery("cooldown_expired"))
+                return;
+            this.clearMcpRestartRequest();
+            if (this.config.mcp_auto_restart === false || this.authFailureUnresolved || this.mcpServerAlive().alive)
+                return;
+            this.armMcpRestartWhenIdle();
+        }, Math.max(0, delayMs));
+        this.mcpRestartCooldownTimer.unref?.();
+    }
     /**
      * Single chokepoint for all three revival triggers (already_idle, idle_edge,
      * stale_timeout) — and therefore the one place worth re-checking reality.
@@ -2570,6 +2619,8 @@ export class Daemon extends EventEmitter {
     fireMcpRestartRequest(trigger) {
         if (this.mcpRestartCancelledByRecovery(trigger))
             return;
+        if (this.mcpRestartCooldownTimer)
+            return;
         // Authoritative re-read — the CLI may have replaced the server since the
         // health tick that armed this.
         if (this.mcpServerAlive().alive) {
@@ -2764,6 +2815,10 @@ export class Daemon extends EventEmitter {
     }
     clearMcpRestartRequest() {
         this.mcpRestartPending = false;
+        if (this.mcpRestartCooldownTimer) {
+            clearTimeout(this.mcpRestartCooldownTimer);
+            this.mcpRestartCooldownTimer = null;
+        }
         if (this.mcpRestartStaleTimer) {
             clearTimeout(this.mcpRestartStaleTimer);
             this.mcpRestartStaleTimer = null;
@@ -6770,15 +6825,30 @@ export class Daemon extends EventEmitter {
                 const whatsNew = this.pendingWhatsNew ? this.currentWhatsNew(this.pendingWhatsNew) : null;
                 if (whatsNew) {
                     // #1633: here, inside the delivery lock and ahead of a real delivery — never into a busy turn, never to an
-                    // instance nobody writes to. Recorded only once pasted: a failed or cancelled paste stays pending.
-                    const pasted = await this.deliverMessage(whatsNew.notice, undefined, { deliveryEpoch });
-                    if (pasted && this.pendingWhatsNew === whatsNew) {
-                        this.pendingWhatsNew = null;
-                        try {
-                            recordWhatsNew(this.instanceDir, whatsNew.ids, whatsNew.version);
-                        }
-                        catch (err) {
-                            this.logger.warn({ err }, "what's-new record not written — the notice may repeat once");
+                    // instance nobody writes to. #2140: told at most once. Once its paste reached the pane it is recorded, proven
+                    // submitted or not. A system paste has no unique id: its only pane proof is its opening line on the screen, and
+                    // a long notice (every entry since an old session began) scrolls that line above the captured rows once Claude
+                    // paints it — unproven, though the agent read it. One that never reached the pane (cancelled, never idle) is
+                    // tried again, at most WHATS_NEW_MAX_UNWRITTEN times, then recorded with a warning.
+                    const attempt = { reached: false };
+                    const pasted = await this.deliverMessage(whatsNew.notice, undefined, { deliveryEpoch, verdict: attempt });
+                    if (this.pendingWhatsNew === whatsNew) {
+                        const written = pasted || attempt.paneWriteStarted === true;
+                        if (!written)
+                            this.whatsNewUnwritten++;
+                        if (written || this.whatsNewUnwritten >= WHATS_NEW_MAX_UNWRITTEN) {
+                            if (!pasted) {
+                                this.logger.warn({ entries: whatsNew.ids, written, attempts: this.whatsNewUnwritten, phase: attempt.phase, proof: attempt.proof }, written ? "what's-new notice pasted but its submission could not be proven — recorded so it is not sent again"
+                                    : "what's-new notice did not reach the pane after several deliveries — recorded so it is not sent again");
+                            }
+                            this.pendingWhatsNew = null;
+                            this.whatsNewUnwritten = 0;
+                            try {
+                                recordWhatsNew(this.instanceDir, whatsNew.ids, whatsNew.version);
+                            }
+                            catch (err) {
+                                this.logger.warn({ err }, "what's-new record not written — the notice may repeat once");
+                            }
                         }
                     }
                     if (!this.isDeliveryEpochCurrent(deliveryEpoch))
@@ -9945,6 +10015,169 @@ export class Daemon extends EventEmitter {
             });
             return;
         }
+        // #1629: the caller's own web theme. set_web_theme_asset's file is read HERE, on the agent's side (in its working
+        // directory, no symlink, size-capped): the fleet receives bytes, never a workspace path.
+        if (Object.hasOwn(WEB_THEME_IPC, tool)) {
+            // Answered exactly once, whatever happens on the way (#1887 review: a throw here once left the call unanswered).
+            let answered = false;
+            const reply = (result, error) => { if (answered)
+                return; answered = true; respond(result, error); };
+            // One fleet request; resolves with its answer, or an error string (never rejects).
+            const ask = (payload) => new Promise((resolve) => {
+                const fleetReqId = `theme_${++this.fleetRequestSeq}_${requestId}`;
+                const timeout = setTimeout(() => {
+                    this.pendingIpcRequests.delete(fleetReqId);
+                    resolve({ result: null, error: `${tool} timed out` });
+                }, daemonBudgetMs(tool));
+                this.pendingIpcRequests.set(fleetReqId, (respMsg) => {
+                    clearTimeout(timeout);
+                    resolve({ result: respMsg.result, error: respMsg.error });
+                });
+                this.ipcServer?.broadcast({ type: WEB_THEME_IPC[tool], payload, meta: { instance_name: this.name }, fleetRequestId: fleetReqId });
+            });
+            void (async () => {
+                if (tool === "preview_web_appearance") {
+                    // The fleet builds the SVGs (whole, or in parts); they are written here, in the working directory.
+                    const first = await ask({ ...(args.modes !== undefined ? { modes: args.modes } : {}) });
+                    if (first.error) {
+                        reply(null, first.error);
+                        return;
+                    }
+                    let failed;
+                    const got = await receivePreview((first.result && typeof first.result === "object" ? first.result : {}), async (payload) => {
+                        const r = await ask(payload);
+                        if (r.error) {
+                            failed = r.error;
+                            return { error: r.error };
+                        }
+                        return (r.result && typeof r.result === "object" ? r.result : {});
+                    });
+                    if (failed) {
+                        reply(null, failed);
+                        return;
+                    }
+                    if ("error" in got) {
+                        reply(got, undefined);
+                        return;
+                    }
+                    const written = await writePreview(got.files, { workspace: this.config.working_directory, configuredWorkspace: this.config.working_directory, stateDir: getAgendHome(), instance: this.name });
+                    if ("error" in written) {
+                        reply(null, `preview_web_appearance: ${written.error}`);
+                        return;
+                    }
+                    reply(written, undefined);
+                    return;
+                }
+                if (tool === "export_web_mod") {
+                    // The fleet builds the file (whole, or in parts); it is written here, in the working directory.
+                    const first = await ask(args);
+                    if (first.error) {
+                        reply(null, first.error);
+                        return;
+                    }
+                    let failed;
+                    const firstResult = (first.result && typeof first.result === "object" ? first.result : {});
+                    const got = await receiveFiles(firstResult, async (payload) => {
+                        const r = await ask(payload);
+                        if (r.error) {
+                            failed = r.error;
+                            return { error: r.error };
+                        }
+                        return (r.result && typeof r.result === "object" ? r.result : {});
+                    }, { name: MOD_FILE, idKey: "transfer", what: "export", maxParts: MOD_MAX_PARTS });
+                    if (failed) {
+                        reply(null, failed);
+                        return;
+                    }
+                    if ("error" in got) {
+                        reply(got, undefined);
+                        return;
+                    }
+                    const written = await writeModFile(got.files, { workspace: this.config.working_directory, configuredWorkspace: this.config.working_directory, stateDir: getAgendHome(), instance: this.name });
+                    if ("error" in written) {
+                        reply(null, `export_web_mod: ${written.error}`);
+                        return;
+                    }
+                    reply({ ...written, ...(firstResult.effects_omitted ? { effects_omitted: firstResult.effects_omitted } : {}) }, undefined);
+                    return;
+                }
+                if (tool === "propose_web_mod") {
+                    const read = await readAgentFile(args.file, { workspace: this.config.working_directory, configuredWorkspace: this.config.working_directory, stateDir: getAgendHome(), instance: this.name, maxBytes: MOD_UPLOAD_MAX_BYTES });
+                    const named = typeof args.file === "string" ? args.file.slice(0, 200) : "the file argument";
+                    if (!read.ok) {
+                        reply(null, `propose_web_mod: ${named} — ${read.reason}`);
+                        return;
+                    }
+                    let failed;
+                    const answer = await sendAssetInParts("mod", read.bytes, async (payload) => {
+                        const r = await ask(payload);
+                        if (r.error) {
+                            failed = r.error;
+                            return { error: r.error };
+                        }
+                        return (r.result && typeof r.result === "object" ? r.result : {});
+                    });
+                    reply(failed ? null : answer, failed);
+                    return;
+                }
+                if (tool === "upload_web_effect") {
+                    const owner = { fence: this.launchFenceEpoch, spawn: this.spawnGeneration, boot: this.bootId, ipc: this.ipcServer };
+                    const current = () => !!owner.ipc && owner.ipc === this.ipcServer && owner.fence === this.launchFenceEpoch && owner.spawn === this.spawnGeneration && owner.boot === this.bootId && !this.deliveryWritesStopping && !this.startupAborted;
+                    if (!current()) {
+                        reply(null, "upload_web_effect: launch no longer current");
+                        return;
+                    }
+                    const read = await readAgentEffect(args.dir, { workspace: this.config.working_directory, configuredWorkspace: this.config.working_directory, stateDir: getAgendHome(), instance: this.name });
+                    if (!current()) {
+                        reply(null, "upload_web_effect: launch no longer current");
+                        return;
+                    }
+                    if (!read.ok) {
+                        reply(null, `upload_web_effect: ${read.reason}`);
+                        return;
+                    }
+                    let failed;
+                    const answer = await sendEffectInParts(read.files, async (payload) => {
+                        if (!current()) {
+                            failed = "upload_web_effect: launch no longer current";
+                            return { error: failed };
+                        }
+                        const r = await ask(payload);
+                        if (r.error) {
+                            failed = r.error;
+                            return { error: r.error };
+                        }
+                        return (r.result && typeof r.result === "object" ? r.result : {});
+                    });
+                    reply(failed ? null : answer, failed);
+                    return;
+                }
+                if (tool !== "set_web_theme_asset") {
+                    const r = await ask(args);
+                    reply(r.result, r.error);
+                    return;
+                }
+                const read = await readAgentFile(args.file, { workspace: this.config.working_directory, configuredWorkspace: this.config.working_directory, stateDir: getAgendHome(), instance: this.name, maxBytes: WEB_THEME_ASSET_MAX_BYTES });
+                // The path as the agent gave it — only a string is shown (an object from raw JSON args is never coerced).
+                const named = typeof args.file === "string" ? args.file.slice(0, 200) : "the file argument";
+                if (!read.ok) {
+                    reply(null, `set_web_theme_asset: ${named} — ${read.reason}`);
+                    return;
+                }
+                // A picture larger than one IPC message goes up in parts (r4 §1: a card portrait may be megabytes).
+                let failed;
+                const answer = await sendAssetInParts(args.slot, read.bytes, async (payload) => {
+                    const r = await ask(payload);
+                    if (r.error) {
+                        failed = r.error;
+                        return { error: r.error };
+                    }
+                    return (r.result && typeof r.result === "object" ? r.result : {});
+                });
+                reply(failed ? null : answer, failed);
+            })().catch((err) => reply(null, `${tool} failed: ${err instanceof Error ? err.message : "error"}`));
+            return;
+        }
         if (tool === TASK_TOOL) {
             const fleetReqId = `task_${++this.fleetRequestSeq}_${requestId}`;
             const timeout = setTimeout(() => {
@@ -11198,14 +11431,39 @@ export class Daemon extends EventEmitter {
         }
         if (ids.length === pending.ids.length)
             return pending;
-        const narrowed = { notice: whatsNewNotice(pending.version, AGENT_WHATS_NEW.filter(e => ids.includes(e.id))), ids, version: pending.version };
+        // #2163: rebuilt as planned — only the entries this instance's roles are told; the rest are recorded with them.
+        const roles = this.whatsNewRoles();
+        const shown = AGENT_WHATS_NEW.filter(e => ids.includes(e.id) && (!e.audience || e.audience.some(r => roles.includes(r))));
+        if (!shown.length) {
+            this.pendingWhatsNew = null;
+            try {
+                recordWhatsNew(this.instanceDir, ids, pending.version);
+            }
+            catch (err) {
+                this.logger.warn({ err }, "what's-new record not written — the notice may repeat once");
+            }
+            return null;
+        }
+        const narrowed = { notice: whatsNewNotice(pending.version, shown), ids, version: pending.version };
         this.pendingWhatsNew = narrowed;
         return narrowed;
     }
+    /**
+     * #2163: who this instance is to the what's-new notices — a ClassicBot room's agent, General, or a fleet worker (with
+     * `coordinator` too when its tool set is coordinator or full, the ones that carry get_/set_web_settings).
+     */
+    whatsNewRoles() {
+        if (this.runtimeIdentity?.kind === "classic")
+            return ["classic"];
+        if (this.config.general_topic === true || this.name === "general")
+            return ["general"];
+        const set = resolveToolSet(this.config, this.name);
+        return set === "coordinator" || set === "full" ? ["worker", "coordinator"] : ["worker"];
+    }
     /** #1633: what this instance has not been told about its AgEnD version yet (see agent-whats-new.ts). */
     prepareWhatsNew(fresh, version = agendVersion()) {
         try {
-            const plan = planWhatsNew({ record: readWhatsNewRecord(this.instanceDir), fresh, version });
+            const plan = planWhatsNew({ record: readWhatsNewRecord(this.instanceDir), fresh, version, roles: this.whatsNewRoles() });
             if (!plan) {
                 this.pendingWhatsNew = null;
                 return;
@@ -11216,6 +11474,7 @@ export class Daemon extends EventEmitter {
                 return;
             }
             this.pendingWhatsNew = plan;
+            this.whatsNewUnwritten = 0;
             this.logger.info({ entries: plan.ids }, "what's-new notice pending for the next delivery");
         }
         catch (err) {
@@ -12055,16 +12314,29 @@ export class Daemon extends EventEmitter {
             respond(null, `Not a git repository: ${source}`);
             return;
         }
-        const repoDir = join(this.instanceDir, "repos");
-        mkdirSync(repoDir, { recursive: true });
-        const safeName = `${basename(source)}-${branch.replace(/\//g, "-")}`;
-        const worktreePath = join(repoDir, safeName);
+        mkdirSync(join(this.instanceDir, "repos"), { recursive: true });
+        // Only a fresh direct child of a real repos/ directory (never through a symlinked repos/, never an existing path).
+        const target = checkoutTarget(this.instanceDir, source, branch);
+        if (!target.ok) {
+            respond(null, `checkout_repo: ${target.reason}`);
+            return;
+        }
+        const worktreePath = target.path;
         try {
-            // Resolve branch/ref to verify it exists. Use `--` so git never treats
-            // branch as an option flag (defense in depth on top of the regex above).
-            await execFileAsync("git", ["rev-parse", "--verify", "--", branch], { cwd: source });
-            await execFileAsync("git", ["worktree", "add", "--detach", worktreePath, branch], { cwd: source });
+            // Resolve branch/ref to verify it exists. `--end-of-options` keeps git from ever reading branch as an option
+            // flag (defense in depth on top of the regex above). Not `--`: rev-parse then reads branch as a path, and
+            // `--verify` fails for every ref ("Needed a single revision"), which broke checkout_repo entirely.
+            await execFileAsync("git", ["rev-parse", "--verify", "--end-of-options", `${branch}^{commit}`], { cwd: source });
+            await execFileAsync("git", ["worktree", "add", "--detach", worktreePath, "--end-of-options", branch], { cwd: source });
             const { stdout: commitHash } = await execFileAsync("git", ["rev-parse", "--short", "HEAD"], { cwd: worktreePath });
+            // Recorded so release_repo can tell this instance's checkout of this repository from anything else.
+            try {
+                const { stdout: common } = await execFileAsync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd: worktreePath });
+                const root = reposRoot(this.instanceDir);
+                if (root.ok)
+                    writeCheckouts(root.path, { ...readCheckouts(root.path), [worktreePath]: common.trim() });
+            }
+            catch { /* unrecorded: release still requires a listed linked worktree */ }
             respond({ path: worktreePath, branch, source, commit: commitHash.trim() });
         }
         catch (err) {
@@ -12072,26 +12344,50 @@ export class Daemon extends EventEmitter {
         }
     }
     async handleReleaseRepo(args, respond) {
-        const repoPath = args.path;
-        const reposDir = join(this.instanceDir, "repos");
-        // Safety: only allow releasing paths under our repos/ directory
-        if (!repoPath.startsWith(reposDir)) {
-            respond(null, `Cannot release path outside instance repos directory`);
+        // Containment first (real paths, strictly inside this instance's repos/), then proof it is a git worktree.
+        // Nothing that fails either check is ever removed.
+        const candidate = releaseCandidate(this.instanceDir, args.path);
+        if (!candidate.ok) {
+            respond(null, `Cannot release: ${candidate.reason}`);
+            return;
+        }
+        const root = reposRoot(this.instanceDir);
+        if (!root.ok) {
+            respond(null, `Cannot release: ${root.reason}`);
+            return;
+        }
+        const { execFile: execFileCb } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const execFileAsync = promisify(execFileCb);
+        const git = async (gitArgs, cwd) => (await execFileAsync("git", gitArgs, { cwd })).stdout;
+        const worktree = await verifyWorktree(root.path, candidate.path, git);
+        if (!worktree.ok) {
+            respond(null, `Cannot release: ${worktree.reason}`);
             return;
         }
+        const repoPath = candidate.path;
         try {
-            const { execFile: execFileCb } = await import("node:child_process");
-            const { promisify } = await import("node:util");
-            const execFileAsync = promisify(execFileCb);
-            await execFileAsync("git", ["worktree", "remove", "--force", repoPath]);
+            await git(["--git-dir", worktree.commonDir, "worktree", "remove", "--force", repoPath], worktree.commonDir);
         }
         catch {
-            // Fallback: rm directly if git worktree remove fails
+            // Fallback for a verified worktree only: remove it, then let its repository forget it.
             try {
                 rmSync(repoPath, { recursive: true, force: true });
             }
             catch { /* best effort */ }
+            try {
+                await git(["--git-dir", worktree.commonDir, "worktree", "prune"], worktree.commonDir);
+            }
+            catch { /* best effort */ }
+        }
+        try {
+            const records = readCheckouts(root.path);
+            if (repoPath in records) {
+                delete records[repoPath];
+                writeCheckouts(root.path, records);
+            }
         }
+        catch { /* the worktree is gone; a stale record only refuses a later, different repo at this path */ }
         respond({ released: true, path: repoPath });
     }
     buildSnapshotPrompt() {