wave-code 1.5.1 → 1.6.1

package/src/stdio/daemonServer.ts

@@ -1,6 +1,7 @@
 /**
- * DaemonServer — JSON-RPC server over a unix socket for remote background
- * sessions (spec: docs/specs/desktop/desktop-sessions.md 「SSH 远程后台会话」).
+ * DaemonServer — JSON-RPC server over a local socket (a unix domain socket on
+ * POSIX, a Windows named pipe) for remote background sessions (spec:
+ * docs/specs/desktop/desktop-remote.md 「SSH 远程后台会话」).
  *
  * The desktop app launches `wave --daemon <socket>` on the remote host via
  * nohup/setsid, then tunnels the socket back with `ssh -L`. All connections
@@ -18,6 +19,10 @@ import net from "net";
 import * as fs from "fs";
 import { AgentBridge, type AgentBridgeOptions } from "./agentBridge.js";
 import { JsonRpcConnection } from "./jsonRpcConnection.js";
+import {
+  describeListenError,
+  isWindowsPipeName,
+} from "../daemon/socketPath.js";
 import type { RemoteControlSink } from "../remote/remoteControlSink.js";
 
 export interface DaemonServerOptions {
@@ -98,37 +103,43 @@ export class DaemonServer {
    * unlinked outright; socket files are probe-connected — ECONNREFUSED means
    * no listener (stale → unlink and listen), anything else means a live
    * daemon owns the path (reject).
+   *
+   * A Windows named pipe has no file to go stale: it disappears with its
+   * listener, so the probe/unlink pass is skipped and a name already in use
+   * surfaces as EADDRINUSE from `listen` (translated in `listen`).
    */
   start(): Promise<void> {
     return new Promise((resolve, reject) => {
       const server = this.server;
       if (!server) return resolve();
-      try {
-        const st = fs.statSync(this.socketPath);
-        if (st.isSocket()) {
-          const probe = net.connect(this.socketPath);
-          probe.once("connect", () => {
-            probe.destroy();
-            reject(
-              new Error(
-                `Another wave daemon is already listening on ${this.socketPath}`,
-              ),
-            );
-          });
-          probe.once("error", (err: NodeJS.ErrnoException) => {
-            probe.destroy();
-            if (err.code === "ECONNREFUSED") {
-              fs.unlinkSync(this.socketPath);
-              this.listen(server, resolve, reject);
-            } else {
-              reject(err);
-            }
-          });
-          return;
+      if (!isWindowsPipeName(this.socketPath)) {
+        try {
+          const st = fs.statSync(this.socketPath);
+          if (st.isSocket()) {
+            const probe = net.connect(this.socketPath);
+            probe.once("connect", () => {
+              probe.destroy();
+              reject(
+                new Error(
+                  `Another wave daemon is already listening on ${this.socketPath}`,
+                ),
+              );
+            });
+            probe.once("error", (err: NodeJS.ErrnoException) => {
+              probe.destroy();
+              if (err.code === "ECONNREFUSED") {
+                fs.unlinkSync(this.socketPath);
+                this.listen(server, resolve, reject);
+              } else {
+                reject(err);
+              }
+            });
+            return;
+          }
+          fs.unlinkSync(this.socketPath);
+        } catch {
+          // ENOENT — no stale socket, listen directly.
         }
-        fs.unlinkSync(this.socketPath);
-      } catch {
-        // ENOENT — no stale socket, listen directly.
       }
       this.listen(server, resolve, reject);
     });
@@ -139,9 +150,11 @@ export class DaemonServer {
     resolve: () => void,
     reject: (err: Error) => void,
   ): void {
-    server.once("error", reject);
+    const onError = (err: NodeJS.ErrnoException) =>
+      reject(describeListenError(this.socketPath, err));
+    server.once("error", onError);
     server.listen(this.socketPath, () => {
-      server.removeListener("error", reject);
+      server.removeListener("error", onError);
       resolve();
     });
   }
@@ -174,10 +187,13 @@ export class DaemonServer {
     this.sockets.clear();
     this.server?.close();
     this.server = undefined;
-    try {
-      fs.unlinkSync(this.socketPath);
-    } catch {
-      // Already gone — a stale file is probed/unlinked on next start.
+    // A pipe name disappears with its listener; only a file socket needs unlinking.
+    if (!isWindowsPipeName(this.socketPath)) {
+      try {
+        fs.unlinkSync(this.socketPath);
+      } catch {
+        // Already gone — a stale file is probed/unlinked on next start.
+      }
     }
     try {
       process.exit(0);

package/src/stdio/hostSlashCommands.ts

@@ -18,7 +18,7 @@
  * **What each entry claims**: `surfaces` is the set of front ends that really
  * implement it. It is a capability statement, not a label: an entry listed for
  * a surface that has no handling behind it produces exactly the defect spec
- * ui/remote-control.md 场景 24 forbids — a row in the popup that does nothing
+ * remote/remote-web.md 场景 21 forbids — a row in the popup that does nothing
  * when picked. `hostSlashCommands.test.ts` pins each surface's set, and the
  * remote-page set is also cross-checked there against the remote allowlist,
  * which is the other half of the same promise (popup lists it ⇒ picking it
@@ -96,7 +96,7 @@ export const HOST_SLASH_COMMANDS: readonly HostSlashCommandSpec[] = [
     description: "清除对话历史并重置会话",
     runOnSelect: true,
     // 桌面端整端移除了 `/clear`（2026-09-05 拍板，见 clear-command.md 与
-    // ui/remote-control.md 场景 24）。
+    // remote/remote-web.md 场景 21）。
     surfaces: ["vscode", "jetbrains", "remote-page"],
   },
   {
@@ -148,8 +148,13 @@ export const HOST_SLASH_COMMANDS: readonly HostSlashCommandSpec[] = [
     id: "resume",
     description: "恢复历史对话",
     runOnSelect: true,
-    // 页面的会话列表只报进程内的活会话，磁盘历史会话在那边不渲染（场景 24）。
-    surfaces: GUIS,
+    // 桌面端 / IDE 与 daemon、GUI 的 `--stdio` 子进程都能执行它；**前台 CLI 那
+    // 个承接进程不能**（它只有一条会话槽位，恢复磁盘会话等于把用户正看着的那条
+    // 换掉）——所以这一条是表第一次出现「入口一致、宿主再收窄」：这里给的是
+    // `remote-page` 的上限，`RemoteControlCliHost` 在回包前删掉它（见
+    // `remoteControlCliHost.ts` 的 `getSlashCommands`）。桌面侧栏与远控页的取数
+    // 不同：侧栏只报进程内活会话，`/resume` 才是磁盘历史会话的入口。
+    surfaces: ALL,
   },
   {
     id: "btw",

package/src/stdio/startupStage.ts

@@ -0,0 +1,22 @@
+/**
+ * 首次启动的进度上报（spec `ui/stdio-transport.md`「首次启动的进度文案」）。
+ *
+ * 走的是同一条 stdout 上的 JSON-RPC 通知通道（一条一行），只是没有 `sessionId`
+ * ——这些阶段发生在任何会话存在之前。宿主侧 `NotificationRouter` 的全局处理器
+ * 收下它，把它变成加载动画下方那一行文案。
+ *
+ * **旁路**：通知发不出去（stdout 已关、宿主已经退出）不是启动错误，写失败一律
+ * 吞掉；上报也不参与任何完成条件，没有宿主消费时启动照旧。
+ */
+
+import type { StartupStage } from "wave-agent-sdk";
+
+export function reportStartupStage(stage: StartupStage): void {
+  try {
+    process.stdout.write(
+      `${JSON.stringify({ method: "startupStage", params: { stage } })}\n`,
+    );
+  } catch {
+    // 见文件头：上报失败不影响启动。
+  }
+}

package/src/stdio/uiPayload.ts

@@ -15,6 +15,12 @@
  * them. This is a wire cut, not a memory model: stripping `images` where the
  * SDK writes the block would break the next turn, so do not move it there.
  *
+ * **User pasted images are different.** Their bytes live in the message block
+ * (spec ui/image-pasting.md「已发送图片的标签点开就能看」) so every GUI host can
+ * preview them without asking anybody for a file — those go out to local hosts
+ * untouched, and only the remote Web page gets them cut (`messageForRemote`,
+ * spec remote/remote-channel.md「远端通道只开一个白名单」场景 10).
+ *
  * Copies are shallow and made only where the field is actually present — the
  * common message (no images) keeps its identity and costs nothing.
  */
@@ -53,6 +59,49 @@ export function toolBlockUpdateForUi(
   return rest;
 }
 
+/**
+ * The remote Web page's copy of a message: `messageForUi`, plus user image
+ * bytes blanked out (docs/specs/remote/remote-channel.md「远端通道只开一个白名单」
+ * 场景 10).
+ *
+ * Image bytes stay in the block for GUI hosts (they preview them in place), but
+ * they must not go over the relay: one screenshot is commonly 1–3 MB of base64,
+ * far past the 512 KiB frame budget, and the page could not use the bytes even
+ * if they arrived. The array keeps its **length and order** — the `[imageN]`
+ * tags in the text block are positional — so the page still shows a tag per
+ * image, just not a clickable one. `imagePaths` goes too: it is a path on the
+ * session host, which the page cannot read.
+ */
+export function messageForRemote(message: Message): Message {
+  const forUi = messageForUi(message);
+  const { blocks } = forUi;
+  if (!Array.isArray(blocks)) return forUi;
+  let changed = false;
+  const blanked = blocks.map((block) => {
+    if (block.type !== "image") return block;
+    const { imagePaths, ...rest } = block;
+    if (!imagePaths && !rest.imageUrls?.length) return block;
+    changed = true;
+    return { ...rest, imageUrls: (rest.imageUrls ?? []).map(() => "") };
+  });
+  return changed ? { ...forUi, blocks: blanked } : forUi;
+}
+
+/**
+ * `messageForRemote` over the `getMessages` answer — the shape the remote
+ * service actually holds (an untyped JSON result). Anything that is not a
+ * message list passes through untouched.
+ */
+export function resultForRemote(result: unknown): unknown {
+  if (!result || typeof result !== "object") return result;
+  const { messages, ...rest } = result as { messages?: unknown };
+  if (!Array.isArray(messages)) return result;
+  return {
+    ...rest,
+    messages: messages.map((message) => messageForRemote(message as Message)),
+  };
+}
+
 function hasImages(block: ToolBlock): boolean {
   return Array.isArray(block.images) && block.images.length > 0;
 }

package/src/stdio-cli.ts

@@ -8,6 +8,7 @@
 
 import { ensureRuntimeDeps, setTelemetryStdoutProtected } from "wave-agent-sdk";
 import { StdioServer } from "./stdio/stdioServer.js";
+import { reportStartupStage } from "./stdio/startupStage.js";
 import { createRemoteControlSinkFactory } from "./remote/remoteControlSink.js";
 import { logger } from "./utils/logger.js";
 
@@ -64,7 +65,11 @@ export async function startStdioCli(): Promise<void> {
   // answering any RPC (see cli.tsx). Blocking here is what closes the race: the
   // host's `initialize` — and with it the webview's initial state — only lands
   // once a pasted image can be handled. Failures are non-fatal.
-  await ensureRuntimeDeps();
+  //
+  // The ~25MB this can pull is the longest silent stretch of a first launch, so
+  // it is reported (a warm cache reports nothing: `ensureRuntimeDeps` only
+  // fires `onStage` when something is actually missing).
+  await ensureRuntimeDeps({ onStage: reportStartupStage });
   // Registered here (stdio mode only): the interactive CLI keeps Node's
   // default behavior so the terminal shows the crash stack directly.
   process.on("uncaughtException", (error) =>
@@ -79,6 +84,9 @@ export async function startStdioCli(): Promise<void> {
     // same machine — is what serves a paired phone.
     createRemoteSink: createRemoteControlSinkFactory(process.cwd()),
   });
+  // Last startup stage: from here the process is up and what the user is waiting
+  // for is `initialize` (and, on the restore path, the transcript replay).
+  reportStartupStage("startingSession");
   server.start();
 
   // Keep the process alive — readline on stdin handles the event loop.

package/src/utils/argvCompat.ts

@@ -0,0 +1,23 @@
+/**
+ * Keep yargs' `hideBin()` slicing argv the way a plain `node script.js` run
+ * does, even when the CLI is executed by the Electron runtime.
+ *
+ * Electron RUN_AS_NODE (the desktop / vscode bundled runtime, `process.execPath`
+ * + `ELECTRON_RUN_AS_NODE=1`) leaves `process.versions.electron` set, so
+ * `hideBin()` mistakes the process for a *packaged* Electron app, slices argv
+ * from index 0 instead of 1, and keeps the script path as a positional
+ * argument — yargs then prints its help and exits 1 with
+ * `Unknown argument: <script>`, i.e. the host sees a CLI that dies on launch.
+ * `process.defaultApp` is exactly the signal `hideBin()` reads as "plain node".
+ *
+ * `bin/wave-code.js` carries the same guard for the shim entry; this module
+ * covers the bundle entry (`dist/bundle/wave.mjs`), which a host runs directly
+ * whenever `WAVE_CLI_PATH` points at the workspace build — the documented dev
+ * setup — instead of the shim.
+ */
+export function ensurePlainNodeArgv(): void {
+  if (process.versions.electron && process.env.ELECTRON_RUN_AS_NODE === "1") {
+    // `defaultApp` is an Electron-only property, absent from @types/node.
+    (process as NodeJS.Process & { defaultApp?: boolean }).defaultApp = true;
+  }
+}

package/src/utils/printOutput.ts

@@ -96,7 +96,7 @@ export class PrintOutput {
    * init 之前写出的事件先存这里，`init()` 时先写 init 再按序补上。
    *
    * `Agent.create()` 期间就可能落事件：初始化阶段加的错误块会走
-   * `onErrorBlockAdded`（真机：`-r <非法 session id>` 时 `initializationService`
+   * `onNoticeAdded`（`level: "error"`）（真机：`-r <非法 session id>` 时 `initializationService`
    * 抛错前先落了一个错误块），而 init 只能等 agent 建好才有 session/model 可报。
    * 不缓冲的话首行会是 error，按首行判类型的消费方就判错了。
    */

package/src/utils/worktree.ts

@@ -21,6 +21,12 @@ const execFileAsync = promisify(execFile);
 export interface WorktreeSession {
   name: string;
   path: string;
+  /**
+   * The branch the worktree was CREATED on — `worktree-<name>` for a worktree
+   * wave created, and what callers must record and hand back to
+   * `removeWorktree`. It is not read back from the worktree: an agent may have
+   * checked another branch out in there (see `removeWorktree`).
+   */
   branch: string;
   repoRoot: string;
   hasUncommittedChanges: boolean;
@@ -39,6 +45,12 @@ export interface WorktreeSession {
 const VALID_WORKTREE_SLUG_SEGMENT = /^[a-zA-Z0-9._-]+$/;
 const MAX_WORKTREE_SLUG_LENGTH = 64;
 
+/** Where `createWorktree` puts worktrees, relative to the repo root. */
+const WORKTREE_PARENT_SEGMENTS = [".wave", "worktrees"];
+
+/** Branch prefix `createWorktree` gives a worktree it creates. */
+const WORKTREE_BRANCH_PREFIX = "worktree-";
+
 /**
  * Validate a worktree name before any side effects. Names are slash-separated
  * slugs: every segment must be non-empty and contain only letters, digits,
@@ -164,8 +176,8 @@ async function createWorktreeInternal(
   options?: { baseRef?: "fresh" | "head"; baseBranch?: string },
 ): Promise<WorktreeSession> {
   const repoRoot = getGitMainRepoRoot(cwd);
-  const worktreePath = path.join(repoRoot, ".wave", "worktrees", name);
-  const branchName = `worktree-${name}`;
+  const worktreePath = path.join(repoRoot, ...WORKTREE_PARENT_SEGMENTS, name);
+  const branchName = `${WORKTREE_BRANCH_PREFIX}${name}`;
   const useHead = options?.baseRef === "head";
   const resolvedBaseBranch =
     options?.baseBranch ?? (useHead ? "HEAD" : getDefaultRemoteBranch(cwd));
@@ -384,6 +396,43 @@ function rmWorktreeDirWithFs(worktreePath: string): unknown | null {
   }
 }
 
+/**
+ * Waits between `fs.rmSync` attempts on the worktree directory. Mutable so
+ * tests can zero them out.
+ *
+ * The first attempt still runs immediately; these only spread the retries.
+ * Windows keeps a directory alive for as long as any process holds it as its
+ * cwd (a killed shell, `node --watch`, a test runner), and that handle is
+ * released asynchronously — the caller's teardown may well have returned before
+ * the OS let go (issue #2763: the same `rm -rf` succeeds a few seconds later by
+ * hand). Three attempts over ~0.9s covers the release lag without turning a
+ * genuinely locked directory into a multi-second stall.
+ */
+export const worktreeRemoveRetry = { delaysMs: [300, 600] };
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * `rmWorktreeDirWithFs` with the short retry above. Returns null once the
+ * directory is gone (or the deletion reported success), the last error
+ * otherwise. Existence is deliberately not probed here: the caller already
+ * decides "did it actually go" from the filesystem, and an extra stat per
+ * attempt would only make that harder to reason about.
+ */
+async function rmWorktreeDirWithRetries(
+  worktreePath: string,
+): Promise<unknown | null> {
+  let error = rmWorktreeDirWithFs(worktreePath);
+  for (const delayMs of worktreeRemoveRetry.delaysMs) {
+    if (!error) return null;
+    await sleep(delayMs);
+    error = rmWorktreeDirWithFs(worktreePath);
+  }
+  return error;
+}
+
 /**
  * Describe what is still on disk after a failed removal. Without this a
  * failure log cannot distinguish "directory already gone" from "the whole
@@ -410,10 +459,19 @@ export interface WorktreeChanges {
 /**
  * The linked worktree a directory sits in, derived from the filesystem only.
  * Same field semantics as `createWorktree`'s result, so a caller can hand it
- * straight to `removeWorktree`.
+ * straight to `removeWorktree` — except for `branch`, which is read off the
+ * worktree's HEAD and is therefore **the branch it has checked out now**, not
+ * the branch it was created on. Removal must pass the creation branch (the
+ * session's snapshot, or `worktreeCreationBranch`); see `removeWorktree`.
  */
 export interface DerivedWorktree {
   path: string;
+  /**
+   * The branch checked out in the worktree right now (`<gitdir>/HEAD`), or `""`
+   * for a detached HEAD. Informational: never use it as "the worktree's branch"
+   * for deletion — an agent may have checked a branch of the user's out in
+   * there.
+   */
   branch: string;
   repoRoot: string;
   hookBased: boolean;
@@ -504,6 +562,62 @@ export function deriveWorktreeInfo(
   }
 }
 
+/**
+ * The branch `createWorktree` created for a worktree, recovered from where that
+ * worktree sits: `<repoRoot>/.wave/worktrees/<name>` is on
+ * `worktree-<name>` (see `createWorktreeInternal`).
+ *
+ * This exists because git keeps no record of it. `git worktree list
+ * --porcelain` and `<gitdir>/HEAD` both report the branch a worktree has
+ * checked out *at the moment you ask*, so once an agent runs `git checkout
+ * <something-else>` inside the worktree they name that branch instead — the
+ * branch the user owns, possibly holding commits reachable from nowhere else.
+ * A removal must delete the branch wave created, and the path is the only
+ * surviving record of it besides a caller's own snapshot.
+ *
+ * The name is taken from the **tail** of `path` — every segment below
+ * `.wave/worktrees` — and the parent directory is never string-compared
+ * against `repoRoot`. The two paths reach us from different sources: `path` is
+ * whatever the OS or host handed over (`fs.mkdtempSync`, a session's cwd, a
+ * transcript header), while `repoRoot` is the path **git** canonicalized and
+ * wrote into `<gitdir>/commondir`. On Windows the same directory routinely
+ * arrives in two forms — 8.3 short name (`C:\Users\RUNNER~1\…`), unexpanded
+ * symlink/junction, drive-letter case — and Windows compares paths
+ * case-insensitively while a string compare does not, so the old
+ * `path.startsWith(parentDir)` called a legitimate worktree "not wave's" and
+ * the creation branch was never deleted. That is what turned `check-windows`
+ * red on main after #2721. Whether the path really sits in *this* repo's
+ * directory is not decidable from the strings anyway; `removeWorktree` asks git
+ * whether the branch it is about to delete exists there instead.
+ *
+ * Returns `undefined` for a path that is not laid out under a
+ * `.wave/worktrees` directory (a hand-made `git worktree add`, a hook-managed
+ * one): its branch is not wave's to name — and for an unknown `repoRoot`,
+ * because a caller that cannot resolve the repository has nothing to look a
+ * branch up in.
+ */
+export function worktreeCreationBranch(
+  worktree: Pick<DerivedWorktree, "path" | "repoRoot">,
+): string | undefined {
+  if (!worktree.repoRoot || !worktree.path) return undefined;
+  const segments = path.resolve(worktree.path).split(path.sep).filter(Boolean);
+  // Deepest `.wave/worktrees` pair first: a repository checked out *inside*
+  // another wave worktree still names the innermost worktree.
+  for (let i = segments.length - 2; i >= 0; i--) {
+    if (
+      segments[i] !== WORKTREE_PARENT_SEGMENTS[0] ||
+      segments[i + 1] !== WORKTREE_PARENT_SEGMENTS[1]
+    ) {
+      continue;
+    }
+    // Names are slug paths (see validateWorktreeSlug), so the branch keeps the
+    // slashes; a path that ends at `worktrees` itself names nothing.
+    const name = segments.slice(i + 2).join("/");
+    return name ? `${WORKTREE_BRANCH_PREFIX}${name}` : undefined;
+  }
+  return undefined;
+}
+
 /**
  * Count what deleting a worktree would throw away, so the caller can warn
  * before it happens. Both counts are best-effort: an unknown base branch (never
@@ -547,18 +661,35 @@ export async function getWorktreeChanges(
 }
 
 /**
- * Remove a git worktree and its associated branch
- * @param session Worktree session details
+ * Remove a git worktree and the branch it was created on.
+ * @param session Worktree session details. `branch` must be the branch the
+ *   worktree was CREATED on (a snapshot the caller recorded at creation time,
+ *   or `worktreeCreationBranch`) — never the branch that directory happens to
+ *   have checked out, which an in-session `git checkout` can change.
  *
  * Removal is best-effort: `git worktree remove --force` deletes the worktree
  * metadata before the working directory, and on Windows its recursive deletion
  * is MAX_PATH-limited — deep paths (e.g. node_modules) can fail with "Filename
  * too long", leaving an orphan directory. When git fails we fall back to
  * fs.rmSync with an extended-length path (bypasses MAX_PATH) and prune stale
- * metadata. Failures are logged; when the directory survives, its branch is
- * deliberately kept so the leftover checkout stays reachable through git.
+ * metadata. The fallback retries a couple of times (`worktreeRemoveRetry`): a
+ * directory locked by a process that is only now exiting — the usual Windows
+ * case — becomes deletable a moment later. Failures are logged; when the
+ * directory still survives, its branch is deliberately kept so the leftover
+ * checkout stays reachable through git.
+ *
+ * Returns whether the directory is actually gone (not whether the removal was
+ * attempted) — a caller that reports the outcome to a user must print it rather
+ * than assume success, because every failure mode above is silent by design.
+ *
+ * The branch is deleted only when `repoRoot` actually has it (`branchExists`),
+ * so a name inferred from the path — which no longer depends on how the two
+ * path strings are spelled, see `worktreeCreationBranch` — can never delete
+ * something else.
  */
-export async function removeWorktree(session: WorktreeSession): Promise<void> {
+export async function removeWorktree(
+  session: WorktreeSession,
+): Promise<boolean> {
   // Hook-based worktrees are removed by the WorktreeRemove hook; wave never
   // runs `git worktree remove` for them. If no WorktreeRemove hook is
   // configured, the worktree is left in place with a warning (CC semantics).
@@ -578,7 +709,9 @@ export async function removeWorktree(session: WorktreeSession): Promise<void> {
         `No WorktreeRemove hook configured, hook-based worktree left at: ${session.path}`,
       );
     }
-    return;
+    // The hook decides what it deletes (it may be a VCS wave knows nothing
+    // about), so the filesystem is the only honest answer.
+    return !fs.existsSync(session.path);
   }
 
   const repoRoot = session.repoRoot;
@@ -602,7 +735,7 @@ export async function removeWorktree(session: WorktreeSession): Promise<void> {
           `path=${session.path} residue=${probeResidue(session.path)} — ` +
           `deleting with fs.rmSync instead`,
       );
-      const rmError = rmWorktreeDirWithFs(session.path);
+      const rmError = await rmWorktreeDirWithRetries(session.path);
       if (rmError) {
         logger.error(
           `Failed to remove worktree or branch: path=${session.path} ` +
@@ -617,7 +750,7 @@ export async function removeWorktree(session: WorktreeSession): Promise<void> {
       `git worktree remove failed, falling back to fs.rmSync: ${describeGitFailure(error)}`,
       error,
     );
-    const rmError = rmWorktreeDirWithFs(session.path);
+    const rmError = await rmWorktreeDirWithRetries(session.path);
     if (rmError) {
       // Removal failures are best-effort, so this line is often the only trace
       // of an orphaned worktree directory: record which stage failed, why, and
@@ -645,16 +778,39 @@ export async function removeWorktree(session: WorktreeSession): Promise<void> {
   // still on disk, and the branch is the only ref still leading back to it.
   if (fs.existsSync(session.path)) {
     logger.warn(
-      `Worktree directory survived removal — keeping ${session.branch} so the ` +
-        `leftover checkout stays reachable: path=${session.path} ` +
-        `residue=${probeResidue(session.path)}`,
+      `Worktree directory survived removal — keeping ` +
+        `${session.branch || "its branches"} so the leftover checkout stays ` +
+        `reachable: path=${session.path} residue=${probeResidue(session.path)}`,
     );
-    return;
+    return false;
   }
 
   // Delete the worktree's own branch. Branches the user checked out inside the
   // worktree are never touched — they may hold commits that are not reachable
-  // from anywhere else (aligned with Claude Code).
+  // from anywhere else (aligned with Claude Code). That is why `session.branch`
+  // has to be the creation-time branch: reading it back from the worktree (its
+  // HEAD) would name whatever was checked out last, i.e. exactly the branch
+  // that must survive. An unknown branch deletes nothing at all.
+  if (!session.branch) {
+    logger.warn(
+      `No branch recorded for the worktree at ${session.path} — keeping every ` +
+        `branch rather than deleting the one it had checked out`,
+    );
+    return true;
+  }
+  // A name derived from the worktree's path layout (rather than snapshotted at
+  // creation) is only a candidate: the layout says what name wave *would* have
+  // used, not that this repository has that branch. Ask git before deleting —
+  // a name that does not resolve here means the guess was wrong or the branch
+  // is already gone, and either way the safe outcome is to delete nothing.
+  if (!(await branchExists(repoRoot, session.branch))) {
+    logger.warn(
+      `No branch ${session.branch} in ${repoRoot} — keeping every branch ` +
+        `(the worktree at ${session.path} was not created on it, or it is ` +
+        `already gone)`,
+    );
+    return true;
+  }
   try {
     await execFileAsync("git", ["branch", "-D", session.branch], {
       cwd: repoRoot,
@@ -662,4 +818,54 @@ export async function removeWorktree(session: WorktreeSession): Promise<void> {
   } catch {
     // Ignore errors deleting original branch
   }
+  return true;
+}
+
+/**
+ * What to tell the user when `removeWorktree` returned `false`: where the
+ * directory still is, which branch was kept for it (removal keeps that ref so
+ * the leftover checkout stays reachable through git), and the two commands that
+ * finish the job by hand.
+ *
+ * Single-sourced because every CLI entry point that removes a worktree used to
+ * print a flat "Done." whether or not anything was deleted — TUI exit, `-p`, and
+ * `wave daemon destroy --remove-worktree` (issue #2763). One wording, one place.
+ */
+export function describeWorktreeSurvival(worktree: {
+  path: string;
+  branch: string;
+  repoRoot: string;
+}): string {
+  const branch = worktree.branch ? `branch ${worktree.branch}` : "every branch";
+  return (
+    `Worktree directory survived at ${worktree.path}; kept ${branch} so the ` +
+    `leftover checkout stays reachable\n` +
+    `Clean up manually: rm -rf ${worktree.path}` +
+    (worktree.branch
+      ? ` && git -C ${worktree.repoRoot} branch -D ${worktree.branch}`
+      : "")
+  );
+}
+
+/**
+ * Does `repoRoot` have a local branch called exactly `branch`?
+ *
+ * `git branch --list` takes a glob pattern, so the listing is compared back
+ * against the exact name instead of trusting "it printed something". Any git
+ * failure counts as "no such branch" — the caller then keeps every branch.
+ */
+async function branchExists(
+  repoRoot: string,
+  branch: string,
+): Promise<boolean> {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["branch", "--list", "--format=%(refname:short)", branch],
+      { cwd: repoRoot, encoding: "utf8" },
+    );
+    return stdout.trim() === branch;
+  } catch {
+    return false;
+  }
 }