wave-code 1.2.0 → 1.4.0

package/src/daemon/commands.ts

@@ -103,7 +103,9 @@ function startDaemon(socketPath: string): void {
  * connection (or daemonStartTimeout.ms elapses). Exits (nonzero) with the
  * spec'd error when the daemon cannot be started/reached.
  */
-async function connectDaemonOrExit(socketPath: string): Promise<SocketClient> {
+export async function connectDaemonOrExit(
+  socketPath: string,
+): Promise<SocketClient> {
   try {
     return await connectDaemon(socketPath);
   } catch (err) {
@@ -135,15 +137,82 @@ interface DaemonSessionEntry {
   sessionId: string;
   workingDirectory: string;
   isLoading: boolean;
+  /**
+   * The other two halves of the idle predicate `wait` / `status` share with
+   * `wave -p` (print mode). A session can have ended its foreground turn while a
+   * background bash task or subagent is still running, and the last such task
+   * flips to `completed` before its completion notification is enqueued for the
+   * main agent's follow-up turn — `isLoading` alone reports "done" in both cases.
+   *
+   * Optional because the daemon is long-lived: upgrading the CLI does not
+   * restart it, so this client can talk to an older daemon that does not report
+   * them. An absent field reads as `false`, which degrades to the old
+   * `isLoading`-only predicate instead of misreading.
+   */
+  hasRunningBackgroundWork?: boolean;
+  hasPendingMessages?: boolean;
   messageCount: number;
 }
 
+/**
+ * "This session is idle", with the same three conditions `wave -p` (print mode)
+ * waits on: no turn running, no background task / subagent running, and nothing
+ * queued. The third one closes the TOCTOU window where the last background task
+ * has already flipped to `completed` (so the first two read false) but its
+ * completion notification has not been consumed yet and is about to start a
+ * follow-up turn. Shared by `wait` and `status` so the two commands cannot
+ * disagree about whether a session is idle.
+ */
+function isIdleSession(entry: DaemonSessionEntry): boolean {
+  return (
+    !entry.isLoading &&
+    entry.hasRunningBackgroundWork !== true &&
+    entry.hasPendingMessages !== true
+  );
+}
+
 interface PendingPermission {
   requestId: string;
   sessionId?: string;
   context: ToolPermissionContext;
 }
 
+/**
+ * Session-scoped notification filter for the `wave daemon` subcommands.
+ *
+ * The daemon broadcasts every session-scoped notification to EVERY attached
+ * client (`DaemonServer`'s emit loops over all connections) and only annotates
+ * the envelope with the owning `sessionId` — demultiplexing is the client's job,
+ * which is how the hosts do it (the SDK/JB `NotificationRouter` drops
+ * notifications for sessions it has not registered). These subcommands instead
+ * applied every push to their own local state, so another session's turn ending
+ * (`loadingChange:false`) settled a `wait` that was watching a still-generating
+ * session: exit code 0 with a `Status: idle` snapshot, and a foreign
+ * `loadingChange:true` satisfied `--from-busy` for a session that never went busy.
+ *
+ * A notification without a `sessionId` is a global one (e.g. `authUrl`), never
+ * another session's state, so it passes.
+ *
+ * The filter is bound to a session only once `initialize` returns, but the
+ * subscription must be installed BEFORE it — the attach replay that carries the
+ * settle-time snapshot is emitted from inside `restoreSession`
+ * (spec: 订阅早于 initialize/restoreSession 以接收重放). Until `bind` runs
+ * nothing matches, which is correct: no session of ours can push yet. See
+ * `attachSession`'s `onInitialized` for that hand-off point.
+ */
+function sessionNotificationFilter(): {
+  bind: (sessionId: string) => void;
+  accepts: (sessionId: string | undefined) => boolean;
+} {
+  let attached: string | undefined;
+  return {
+    bind: (sessionId) => {
+      attached = sessionId;
+    },
+    accepts: (sessionId) => sessionId === undefined || sessionId === attached,
+  };
+}
+
 /**
  * Attach to a session; returns the initialized sessionId + working directory.
  * Exits (nonzero) with the spec'd error when the session exists neither in the
@@ -153,12 +222,27 @@ interface PendingPermission {
 async function attachSession(
   client: SocketClient,
   sessionId: string,
+  options: {
+    /**
+     * Called with the sessionId `initialize` resolved — after `initialize`,
+     * before `restoreSession`. That is the only moment a caller's notification
+     * filter can learn which session this connection is attached to: the
+     * subscription itself is installed earlier, the attach replay arrives later
+     * (see `sessionNotificationFilter`).
+     */
+    onInitialized?: (sessionId: string) => void;
+  } = {},
 ): Promise<{ sessionId: string; workingDirectory: string }> {
   const init = (await client.request("initialize", {
     workdir: process.cwd(),
     restoreSessionId: sessionId,
+    // A daemon restart leaves the session on disk and re-hosts it here; the
+    // re-hosting client is the CLI, and the session file carries no record of
+    // its original creator (see the entrypoint story in the telemetry spec).
+    entrypoint: "cli",
   })) as { sessionId: string; workingDirectory: string };
   const initId = init.sessionId;
+  options.onInitialized?.(initId);
   try {
     await client.request("restoreSession", { sessionId }, initId);
   } catch (err) {
@@ -182,10 +266,52 @@ async function listPendingPermissions(
   return result.requests ?? [];
 }
 
+/**
+ * The daemon's in-memory registry entry for `sessionId`, or undefined when the
+ * session is no longer hosted.
+ *
+ * The registry (not notifications) is the authority on both facts the waiter
+ * needs: existence and whether the session is still busy. `destroy` drops
+ * the entry, and the only notifications that come with it are side effects of
+ * the agent teardown — `loadingChange:false` (destroy aborts, which clears the
+ * loading flag) plus a few no-op state re-emits. A `loading:false` push is
+ * indistinguishable from "the turn finished", so it can never be read as "the
+ * session is gone"; and it happens once, during the destroy, so a waiter that
+ * does not act on it is left with no further event and blocks forever.
+ *
+ * The same reasoning applies to the busy flags themselves: a pushed
+ * `loadingChange` can be a transient (an aborted turn re-dispatches a queued one
+ * a millisecond later) and — since the daemon broadcasts to every client, see
+ * `sessionNotificationFilter` — it can even describe a different session. So
+ * `wait` / `status` read the idle predicate (`isIdleSession`, three flags) from
+ * here on every wake and treat the pushes as pure wake-up signals.
+ */
+async function findHostedSession(
+  client: SocketClient,
+  sessionId: string,
+): Promise<DaemonSessionEntry | undefined> {
+  const result = (await client.request("listDaemonSessions")) as {
+    sessions: DaemonSessionEntry[];
+  };
+  return (result.sessions ?? []).find((s) => s.sessionId === sessionId);
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/** sleep() that can be cancelled, so a lost race never leaves a live timer behind. */
+function sleepCancellable(ms: number): {
+  promise: Promise<void>;
+  cancel: () => void;
+} {
+  let timer: ReturnType<typeof setTimeout>;
+  const promise = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, ms);
+  });
+  return { promise, cancel: () => clearTimeout(timer) };
+}
+
 // ── create ─────────────────────────────────────────────────────
 
 export interface CreateOptions {
@@ -237,6 +363,9 @@ export async function daemonCreateCommand(
       workdir,
       permissionMode: mode,
       model: options.model,
+      // The daemon hosts sessions built from several front ends; this one is
+      // being created by the CLI (`wave daemon create`).
+      entrypoint: "cli",
     })) as { sessionId: string };
     console.log(result.sessionId);
     if (worktreePath !== undefined) {
@@ -264,7 +393,10 @@ export async function daemonListCommand(socketPath: string): Promise<void> {
     if (sessions.length > 0) {
       const rows = sessions.map((s) => ({
         sessionId: s.sessionId,
-        status: s.isLoading ? "generating" : "idle",
+        // Same idle predicate as `status` / `wait` (`isIdleSession`), so the
+        // three cannot disagree about a session that ended its turn but still
+        // owns running background work.
+        status: isIdleSession(s) ? "idle" : "generating",
         messageCount: String(s.messageCount),
         workingDirectory: s.workingDirectory,
       }));
@@ -398,23 +530,101 @@ function parseAskUserQuestionAnswer(
   return answers;
 }
 
+interface SessionSnapshot {
+  sessionId: string;
+  workingDirectory: string;
+  /** `idle` / `generating` / `waiting for approval`. */
+  status: string;
+  pending: PendingPermission[];
+  messages: Message[];
+  /** Trailing messages to render; 0 renders no message text at all. */
+  lines: number;
+}
+
+/**
+ * Render the session snapshot shared by `status` and `wait` (they must be
+ * byte-compatible so `msg=$(wave daemon wait <id>)` yields exactly what
+ * `wave daemon status <id>` prints): the header, the `Status:` line, the pending
+ * approval list (AskUserQuestion rendered in full, see renderAskUserQuestions)
+ * and the last `lines` messages. `lines <= 0` renders no message text at all —
+ * the status-line-only shape for monitors. Guards against 0 because
+ * `Array.prototype.slice(-0)` means `slice(0)`, i.e. the WHOLE history.
+ */
+function renderSessionSnapshot(snapshot: SessionSnapshot): void {
+  console.log(`Session: ${snapshot.sessionId}`);
+  console.log(`Working directory: ${snapshot.workingDirectory}`);
+  console.log(`Status: ${snapshot.status}`);
+
+  if (snapshot.pending.length > 0) {
+    console.log("");
+    console.log("Pending approval requests:");
+    for (const r of snapshot.pending) {
+      if (r.context.toolName === ASK_USER_QUESTION_TOOL_NAME) {
+        const questions = renderAskUserQuestions(r.context);
+        if (questions) {
+          console.log(`  ${r.requestId}  ${r.context.toolName}`);
+          console.log(questions);
+          continue;
+        }
+      }
+      const params = summarizeToolInput(r.context);
+      console.log(
+        `  ${r.requestId}  ${r.context.toolName}${params ? `  ${params}` : ""}`,
+      );
+    }
+  }
+
+  const recent =
+    snapshot.lines > 0 ? snapshot.messages.slice(-snapshot.lines) : [];
+  if (recent.length > 0) {
+    console.log("");
+    console.log(`Recent messages (${recent.length}):`);
+    for (const m of recent) {
+      const text = getMessageContent(m).replace(/\s+/g, " ").trim();
+      if (!text) continue; // tool-only messages carry no readable text
+      console.log(`  [${m.role}] ${text}`);
+    }
+  }
+}
+
+/**
+ * `wave daemon status <sessionId> [--lines N]`.
+ *
+ * `lines` is the number of trailing messages to render (default 1 — the last
+ * message alone, so the default output stays bounded even when one message is a
+ * multi-thousand-character report). `lines <= 0` renders no message text at all
+ * (just the session header + `Status:` line) — the polling shape for monitors
+ * that only watch the status. A one-shot snapshot that always returns
+ * immediately; blocking on a state change is `daemonWaitCommand`.
+ *
+ * `Status:` uses the same idle predicate `wait` blocks on (`isIdleSession`):
+ * `generating` covers "the turn is running" AND "the turn ended but background
+ * work is still running", so `status` never says `idle` for a session a `wait`
+ * would keep blocking on.
+ */
 export async function daemonStatusCommand(
   socketPath: string,
   sessionId: string,
-  lines = 20,
+  lines = 1,
 ): Promise<void> {
   let client: SocketClient | undefined;
   try {
     client = await connectDaemonOrExit(socketPath);
 
     // Subscribe BEFORE initialize/restoreSession so the replayed loadingChange
-    // snapshot is captured (spec: 依据重放的 loadingChange 快照显示状态).
+    // snapshot is captured (spec: 依据重放的 loadingChange 快照显示状态); drop
+    // other sessions' pushes so the snapshot reports THIS session (a foreign
+    // turn's loadingChange used to flip this flag).
     let loading = false;
-    client.onNotification("loadingChange", (params) => {
+    const filter = sessionNotificationFilter();
+    client.onNotification("loadingChange", (params, sessionId) => {
+      if (!filter.accepts(sessionId)) return;
       loading = (params as { loading: boolean }).loading;
     });
 
-    const init = await attachSession(client, sessionId);
+    const init = await attachSession(client, sessionId, {
+      onInitialized: filter.bind,
+    });
     const initId = init.sessionId;
 
     // listPendingPermissions is the authoritative "waiting for approval" signal
@@ -422,6 +632,14 @@ export async function daemonStatusCommand(
     const pending = (await listPendingPermissions(client)).filter(
       (r) => r.sessionId === initId || r.sessionId === sessionId,
     );
+    // The idle decision uses the SAME predicate `wait` blocks on (`isIdleSession`,
+    // three flags) so the two commands cannot disagree: a session whose turn ended
+    // while background work keeps running (or with a completion notification still
+    // queued) is not idle, and reporting idle here would contradict a `wait` still
+    // blocked on it. The registry answers authoritatively; the replayed
+    // `loadingChange` snapshot above is the fallback for a session that vanished
+    // between the attach and this read.
+    const hosted = await findHostedSession(client, initId);
     const messages = (await client.request(
       "getMessages",
       undefined,
@@ -430,51 +648,328 @@ export async function daemonStatusCommand(
       messages: Message[];
     };
 
+    const busy = hosted ? !isIdleSession(hosted) : loading;
     const status =
       pending.length > 0
         ? "waiting for approval"
-        : loading
+        : busy
           ? "generating"
           : "idle";
-    console.log(`Session: ${initId}`);
-    console.log(`Working directory: ${init.workingDirectory}`);
-    console.log(`Status: ${status}`);
-
-    if (pending.length > 0) {
-      console.log("");
-      console.log("Pending approval requests:");
-      for (const r of pending) {
-        if (r.context.toolName === ASK_USER_QUESTION_TOOL_NAME) {
-          const questions = renderAskUserQuestions(r.context);
-          if (questions) {
-            console.log(`  ${r.requestId}  ${r.context.toolName}`);
-            console.log(questions);
-            continue;
-          }
+    renderSessionSnapshot({
+      sessionId: initId,
+      workingDirectory: init.workingDirectory,
+      status,
+      pending,
+      messages: messages.messages,
+      lines,
+    });
+  } catch (err) {
+    fail(`wave daemon status failed: ${(err as Error).message}`);
+  } finally {
+    await client?.dispose();
+  }
+  process.exit(0);
+}
+
+// ── wait ───────────────────────────────────────────────────────
+
+export interface WaitOptions {
+  /** Recent messages to render on exit (default 1; 0 = status line only). */
+  lines?: number;
+  /** Require at least one observed busy phase before accepting idle. */
+  fromBusy?: boolean;
+  /** Seconds to wait before giving up; undefined waits forever. */
+  timeout?: number;
+}
+
+/**
+ * How often the wait re-asks the daemon registry (`listDaemonSessions`) and the
+ * pending-approval list (`listPendingPermissions`) — the facts that cannot be
+ * trusted to a push. Approvals push nothing at all (spec: 单凭消息无法区分等审批与执行中);
+ * a destroyed session pushes only `loadingChange:false`, which is what a
+ * finished turn looks like; and the loading flag itself is re-read from the
+ * registry rather than taken from the push. This is "go ask the daemon about
+ * the facts", not the "poll the status every N seconds" pattern the push-driven
+ * wait exists to replace (spec: `wait` 的退出码是契约): a wake-up still comes
+ * from our own session's `loadingChange`, and this tick is only the backstop for
+ * pushes that never arrive. A local socket round-trip is cheap but busy-polling
+ * it is still wrong — never faster than 1s. Mutable so tests can shorten it.
+ */
+export const waitPollInterval = { ms: 2_000 };
+
+/**
+ * `wave daemon wait <sessionId> [--lines N] [--from-busy] [--timeout <秒>]`.
+ *
+ * Block until the session settles, print the final snapshot — byte-compatible
+ * with `wave daemon status <sessionId> --lines N`, so
+ * `msg=$(wave daemon wait <id>)` captures the report itself — and exit:
+ * `0` = idle, `3` = waiting for permission approval (returned immediately,
+ * never waited out), `1` = error (unreachable daemon / unknown session /
+ * `--timeout` elapsed). stdout carries the snapshot only; progress goes to
+ * stderr.
+ *
+ * Idle is decided from the daemon registry, woken by pushes. The
+ * `loadingChange` / `backgroundTasksChange` subscriptions (installed BEFORE
+ * initialize/restoreSession, so the attach replay is not missed) are filtered to
+ * THIS session and used purely as wake-ups: the loop then re-reads the
+ * authoritative idle predicate (`isIdleSession`) from the registry it already
+ * queries for the existence check — the daemon is never polled for status on a
+ * timer. Reading the flags from the registry rather than from a notification
+ * matters because a pushed `loadingChange` can be a transient (an aborted turn
+ * re-dispatches a queued one a millisecond later) and, since the daemon
+ * broadcasts to every client, it can even describe another session
+ * (`sessionNotificationFilter`).
+ *
+ * "Idle" is the same three conditions `wave -p` (print mode) waits on — no turn
+ * running, no background task / subagent running, nothing queued — because
+ * `isLoading` alone reports "done" for a session whose foreground turn ended
+ * while the background work it launched is still going (the turn-end clears the
+ * flag; the background task's completion notification only arrives later and
+ * starts a follow-up turn). `backgroundTasksChange` is therefore a wake source
+ * of its own: without it, "the background task started/finished" would only be
+ * noticed on the 2s backstop tick.
+ *
+ * Decision order is existence → pending (3) → idle (0) → timeout (1).
+ * Existence comes first because a destroyed session's only announcement is
+ * `loadingChange:false` (destroy aborts the turn), which is indistinguishable
+ * from a finish: read as idle it reports a false "done" for a session that is
+ * gone, and a waiter that does not act on it gets no further event at all and
+ * hangs (which is what happened before this check existed).
+ *
+ * A session that gets RE-KEYED while we block on it is followed, not mourned:
+ * `clearMessages` / `initializeFromSession` / a recovery-recreating
+ * `updateConfig` move the daemon registry entry to a new sessionId and announce
+ * it with `sessionIdChange` (envelope = the id we know, payload = the new one),
+ * so the waiter rebinds its filter and its id and keeps watching the same
+ * session — a re-key is not a destroy (spec: 换键不等于销毁).
+ */
+export async function daemonWaitCommand(
+  socketPath: string,
+  sessionId: string,
+  options: WaitOptions = {},
+): Promise<void> {
+  const lines = options.lines ?? 1;
+  const fromBusy = options.fromBusy ?? false;
+  const timeoutMs =
+    options.timeout !== undefined ? options.timeout * 1000 : undefined;
+
+  let client: SocketClient | undefined;
+  let exitCode = 0;
+  try {
+    const socket = await connectDaemonOrExit(socketPath);
+    client = socket;
+
+    let sawBusy = false;
+    // Push-driven wake: the deferred is re-armed on every bump and the loop
+    // re-reads the registry after every await, so no state change can be
+    // missed. Foreign sessions are filtered out so a crowded daemon cannot turn
+    // their pushes into wake-ups (spec: 只认本会话的推送).
+    let resolveWake: (() => void) | undefined;
+    let wakePromise = new Promise<void>((resolve) => {
+      resolveWake = resolve;
+    });
+    const bump = () => {
+      const resolve = resolveWake;
+      wakePromise = new Promise<void>((r) => {
+        resolveWake = r;
+      });
+      resolve?.();
+    };
+    const filter = sessionNotificationFilter();
+    socket.onNotification("loadingChange", (params, sid) => {
+      if (!filter.accepts(sid)) return;
+      // The payload is only a hint that OUR session changed: `--from-busy`
+      // accepts it as one way to observe the busy phase, while the idle
+      // decision below comes from the registry.
+      if ((params as { loading: boolean }).loading) sawBusy = true;
+      bump();
+    });
+    // Background tasks starting or finishing change the idle predicate without
+    // touching `isLoading` (a foreground turn can end while its background bash
+    // task / subagent keeps running), so this push is a wake source too —
+    // otherwise "it finished" would only be seen on the low-frequency backstop
+    // tick. Payload is ignored: the registry is re-read, exactly as above.
+    socket.onNotification("backgroundTasksChange", (_params, sid) => {
+      if (!filter.accepts(sid)) return;
+      bump();
+    });
+
+    // A session can be RE-KEYED while we block on it — `clearMessages` (which
+    // mints a fresh id) or `initializeFromSession` with another id moves the
+    // daemon registry entry to a new sessionId; `updateConfig` does the same when
+    // its recreate cannot restore the transcript. The re-key is announced (this
+    // notification, envelope = the id we know, payload = the new one) and the
+    // registry key moves in the same tick, so a waiter that keeps using the old id
+    // both misses it in `listDaemonSessions` (⇒ false "no longer exists", exit 1,
+    // for a session that is alive) and stops receiving its pushes. Follow the
+    // rename instead: same session, new id — nothing about it was destroyed.
+    // `watch.id` is the id this waiter tracks: empty until the attach below binds
+    // it, then the live id, re-pointed by every rename we see.
+    const watch = { id: "" };
+    socket.onNotification("sessionIdChange", (params, sid) => {
+      const next = (params as { sessionId?: string }).sessionId;
+      // Envelope-less renames are fired while an agent is being CREATED (its
+      // context has no id yet): they belong to the attach handshake below, whose
+      // reply carries the final id, so there is nothing to follow here. A rename
+      // seen before we know our id would mean the daemon re-keyed the session mid
+      // handshake — the attach itself gives up on that (its `restoreSession` still
+      // carries the pre-rename id), which is a separate, pre-existing gap.
+      if (sid === undefined || !next || !watch.id) return;
+      if (!filter.accepts(sid)) return; // another session's rename
+      watch.id = next;
+      filter.bind(next);
+      bump();
+    });
+
+    const init = await attachSession(socket, sessionId, {
+      onInitialized: (id) => {
+        watch.id = id;
+        filter.bind(id);
+      },
+    });
+
+    // Read against the tracked session, retrying when a re-key lands while the
+    // read is in flight. The daemon announces the rename and moves the registry
+    // entry in one tick, but a request sent moments earlier under the OLD id is
+    // answered only afterwards — and its answer then describes an id that no
+    // longer exists: a miss for a session that is very much alive ("no longer
+    // exists" / exit 1) or a "Session not found" from the settle read. An answer
+    // that a re-key invalidated is not evidence, so ask again on the new id. The
+    // loop only repeats when a rename notification actually arrived, so it cannot
+    // spin without the daemon re-keying the session over and over.
+    const read = async <T>(fn: (id: string) => Promise<T>): Promise<T> => {
+      for (;;) {
+        const id = watch.id;
+        try {
+          const result = await fn(id);
+          if (watch.id !== id) continue;
+          return result;
+        } catch (err) {
+          if (watch.id !== id) continue;
+          throw err;
         }
-        const params = summarizeToolInput(r.context);
-        console.log(
-          `  ${r.requestId}  ${r.context.toolName}${params ? `  ${params}` : ""}`,
-        );
       }
-    }
+    };
+
+    // listPendingPermissions is the authoritative "waiting for approval" signal
+    // (spec: 单凭消息无法区分等审批与执行中，须结合 listPendingPermissions).
+    const pendingForSession = (): Promise<PendingPermission[]> =>
+      read(async (id) => {
+        const all = await listPendingPermissions(socket);
+        return all.filter(
+          (r) =>
+            r.sessionId === id ||
+            r.sessionId === init.sessionId ||
+            r.sessionId === sessionId,
+        );
+      });
 
-    const recent = messages.messages.slice(-lines);
-    if (recent.length > 0) {
-      console.log("");
-      console.log(`Recent messages (${recent.length}):`);
-      for (const m of recent) {
-        const text = getMessageContent(m).replace(/\s+/g, " ").trim();
-        if (!text) continue; // tool-only messages carry no readable text
-        console.log(`  [${m.role}] ${text}`);
+    const settle = async (status: string, pending: PendingPermission[]) => {
+      const result = (await read(
+        (id) =>
+          socket.request("getMessages", undefined, id) as Promise<{
+            messages: Message[];
+          }>,
+      )) as {
+        messages: Message[];
+      };
+      renderSessionSnapshot({
+        sessionId: watch.id,
+        workingDirectory: init.workingDirectory,
+        status,
+        pending,
+        messages: result.messages ?? [],
+        lines,
+      });
+    };
+
+    const deadline =
+      timeoutMs !== undefined ? Date.now() + timeoutMs : undefined;
+    let announced = false;
+    while (true) {
+      // Session existence FIRST (spec: 阻塞等待会话空闲 场景 10). A session
+      // destroyed by another client — `wave daemon destroy <id>` while this
+      // daemon keeps running — announces itself only as `loadingChange:false`
+      // (destroy aborts the turn, which clears the loading flag) plus a few
+      // no-op state re-emits. That is not a usable signal: `loading:false` is
+      // exactly what "the turn finished" looks like, so a waiter that does not
+      // act on the wake is left with no further event and blocks forever —
+      // which is what happened before this check existed. Ask the registry
+      // instead: this query also carries the authoritative idle predicate
+      // (`isIdleSession`) the decision below uses. It rides the same
+      // low-frequency fallback tick as the approval check — that tick is the
+      // backstop, while the ordinary wake-ups are our own session's
+      // `loadingChange` / `backgroundTasksChange`. The order matters: the
+      // destroy's `loadingChange:false` describes a session whose registry entry
+      // is about to disappear, so deciding idle first could report a settled
+      // session that no longer exists — a false success is worse than hanging.
+      // A miss is never an unfollowed rename: the daemon writes
+      // `sessionIdChange` and moves the registry entry in the same tick, and a
+      // read answered under an id a rename superseded is retried rather than
+      // trusted (`read` above). What is left is a session that really is gone.
+      const hosted = await read((id) => findHostedSession(socket, id));
+      if (!hosted) {
+        fail(
+          `wave daemon wait failed: Session ${sessionId} no longer exists (destroyed while waiting)`,
+        );
+      }
+      const idle = isIdleSession(hosted);
+      // A busy reading from the registry is an observed busy phase too:
+      // `--from-busy` must not depend on having caught a `loadingChange:true`
+      // push (a turn that started before this waiter attached pushes none, and
+      // the replay is only as fresh as the moment of the attach). "Busy" is the
+      // complement of the idle predicate, so a session that is only running
+      // background work (or has a completion notification still queued) counts as
+      // observed busy — otherwise `--from-busy` would wait for a busy phase that
+      // has already happened and never accept the idle that follows.
+      if (!idle) sawBusy = true;
+      // Approvals beat idle, and the check runs BEFORE the idle decision — a
+      // session frozen on an approval keeps `loading: true` (so it would never
+      // settle) and one that just turned `loading: false` must not be mistaken
+      // for finished before the pending list is consulted.
+      const pending = await pendingForSession();
+      if (pending.length > 0) {
+        await settle("waiting for approval", pending);
+        exitCode = 3;
+        break;
       }
+      // Idle comes from the registry, never from a single push: already idle at
+      // call time settles immediately — never hanging beats winning the race.
+      // --from-busy holds out for an observed busy phase first: right after an
+      // async `send` the replayed snapshot can still be a stale loading:false
+      // (the turn has not started yet).
+      if (idle && (!fromBusy || sawBusy)) {
+        await settle("idle", []);
+        break;
+      }
+      if (deadline !== undefined && Date.now() >= deadline) {
+        fail(
+          `Timed out waiting for session ${sessionId} to become idle (waited ${options.timeout}s); it is still busy (generating, or running background work)`,
+        );
+      }
+      if (!announced) {
+        announced = true;
+        console.error(`Waiting for session ${watch.id} to become idle…`);
+      }
+      const tick = sleepCancellable(waitPollInterval.ms);
+      const timer =
+        deadline !== undefined
+          ? sleepCancellable(Math.max(0, deadline - Date.now()))
+          : undefined;
+      await Promise.race([
+        wakePromise,
+        tick.promise,
+        ...(timer ? [timer.promise] : []),
+      ]);
+      tick.cancel();
+      timer?.cancel();
     }
   } catch (err) {
-    fail(`wave daemon status failed: ${(err as Error).message}`);
+    fail(`wave daemon wait failed: ${(err as Error).message}`);
   } finally {
     await client?.dispose();
   }
-  process.exit(0);
+  process.exit(exitCode);
 }
 
 // ── send ───────────────────────────────────────────────────────
@@ -503,6 +998,11 @@ export interface SendOptions {
  * (userMessageAdded), and the reply is the last assistantMessageAdded observed
  * after it. A stale loading:false can then never satisfy the wait condition
  * early (the reply has not been added yet).
+ *
+ * The tracked session id follows a re-key (`sessionIdChange`) for the same reason
+ * `wait` does: the reply arrives on the NEW id, so a waiter still bound to the old
+ * one would drop the pushes that complete it and report a false timeout, and its
+ * `getMessages` would come back "Session not found".
  */
 export async function daemonSendCommand(
   socketPath: string,
@@ -517,21 +1017,48 @@ export async function daemonSendCommand(
   let sent = false;
   let ourUserMessageId: string | undefined;
   let replyMessageId: string | undefined;
-  client.onNotification("userMessageAdded", (params) => {
+  // Only THIS session's pushes may move the state below: the daemon broadcasts
+  // every session's notifications to every client, so an unfiltered
+  // `userMessageAdded` / `assistantMessageAdded` / `loadingChange` from a
+  // concurrent session could report "sent" before our message landed and pair
+  // the reply tracking with another conversation's messages
+  // (see sessionNotificationFilter).
+  const filter = sessionNotificationFilter();
+  // `watch.id` is the session this send is attached to — empty until the attach
+  // binds it, then the live id, re-pointed when the daemon re-keys the session
+  // (see the matching handler in daemonWaitCommand): completion is detected from
+  // THIS session's pushes, so a waiter left on the pre-rename id would drop them
+  // and report a false `--wait` timeout for a turn that is still running.
+  const watch = { id: "" };
+  client.onNotification("sessionIdChange", (params, sessionId) => {
+    const next = (params as { sessionId?: string }).sessionId;
+    if (sessionId === undefined || !next || !watch.id) return;
+    if (!filter.accepts(sessionId)) return;
+    watch.id = next;
+    filter.bind(next);
+  });
+  client.onNotification("userMessageAdded", (params, sessionId) => {
+    if (!filter.accepts(sessionId)) return;
     if (!sent) return; // ignore messages added during attach
     ourUserMessageId = (params as { message: Message }).message.id;
   });
-  client.onNotification("assistantMessageAdded", (params) => {
+  client.onNotification("assistantMessageAdded", (params, sessionId) => {
+    if (!filter.accepts(sessionId)) return;
     if (!sent || ourUserMessageId === undefined) return; // not our turn yet
     replyMessageId = (params as { message: Message }).message.id;
   });
-  client.onNotification("loadingChange", (params) => {
+  client.onNotification("loadingChange", (params, sessionId) => {
+    if (!filter.accepts(sessionId)) return;
     loading = (params as { loading: boolean }).loading;
   });
 
-  let initId: string;
   try {
-    initId = (await attachSession(client, sessionId)).sessionId;
+    await attachSession(client, sessionId, {
+      onInitialized: (id) => {
+        watch.id = id;
+        filter.bind(id);
+      },
+    });
     sent = true;
   } catch (err) {
     client.dispose();
@@ -551,10 +1078,11 @@ export async function daemonSendCommand(
     const sendPromise = client.request(
       "sendMessage",
       { text: message },
-      initId,
+      watch.id,
     );
     const userMessage = new Promise<"userMessageAdded">((resolve) => {
-      client.onNotification("userMessageAdded", () => {
+      client.onNotification("userMessageAdded", (params, sessionId) => {
+        if (!filter.accepts(sessionId)) return;
         if (ourUserMessageId !== undefined) resolve("userMessageAdded");
       });
     });
@@ -570,7 +1098,7 @@ export async function daemonSendCommand(
   }
 
   try {
-    await client.request("sendMessage", { text: message }, initId);
+    await client.request("sendMessage", { text: message }, watch.id);
   } catch (err) {
     client.dispose();
     fail(`wave daemon send failed: ${(err as Error).message}`);
@@ -586,7 +1114,7 @@ export async function daemonSendCommand(
       // Timeout backstop: the most likely cause is a session waiting on a
       // permission approval — point the user at respond (spec: 不无限期挂起).
       const pending = (await listPendingPermissions(client)).filter(
-        (r) => r.sessionId === sessionId || r.sessionId === initId,
+        (r) => r.sessionId === sessionId || r.sessionId === watch.id,
       );
       client.dispose();
       if (pending.length > 0) {
@@ -602,7 +1130,11 @@ export async function daemonSendCommand(
   }
 
   try {
-    const result = (await client.request("getMessages", undefined, initId)) as {
+    const result = (await client.request(
+      "getMessages",
+      undefined,
+      watch.id,
+    )) as {
       messages: Message[];
     };
     const reply = result.messages.find((m) => m.id === replyMessageId);
@@ -844,7 +1376,7 @@ export const daemonStopTimeout = { ms: 10_000 };
 const DAEMON_STOP_POLL_INTERVAL_MS = 200;
 
 /** Connect to the daemon socket without starting one; undefined when it is not running. */
-async function tryConnectDaemon(
+export async function connectDaemonIfRunning(
   socketPath: string,
 ): Promise<SocketClient | undefined> {
   try {
@@ -858,7 +1390,7 @@ async function tryConnectDaemon(
 async function waitForDaemonExit(socketPath: string): Promise<void> {
   const deadline = Date.now() + daemonStopTimeout.ms;
   while (Date.now() < deadline) {
-    const client = await tryConnectDaemon(socketPath);
+    const client = await connectDaemonIfRunning(socketPath);
     if (!client) return;
     client.dispose();
     await sleep(DAEMON_STOP_POLL_INTERVAL_MS);
@@ -876,7 +1408,7 @@ async function waitForDaemonExit(socketPath: string): Promise<void> {
  * Throws when a running daemon fails to exit in time.
  */
 async function stopDaemon(socketPath: string): Promise<boolean> {
-  const client = await tryConnectDaemon(socketPath);
+  const client = await connectDaemonIfRunning(socketPath);
   if (!client) return false;
   try {
     // The daemon may drop the socket before responding to the RPC — the wait