@thaut/claude-ide 0.0.0-stage → 1.0.0

package/server/live-session.ts

@@ -0,0 +1,1165 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import {
+  query,
+  getSessionInfo,
+  type Query,
+  type SDKMessage,
+  type SDKUserMessage,
+  type CanUseTool,
+  type PermissionResult,
+} from "@anthropic-ai/claude-agent-sdk";
+import type {
+  LiveEvent,
+  LiveSnapshot,
+  PendingAnswer,
+  PendingRequest,
+  SeqEvent,
+  SessionState,
+  ImageInput,
+  CronInfo,
+  BgTask,
+  SdkMessageLike,
+  AgentTask,
+} from "../shared/protocol.ts";
+import { StreamingReplay } from "../shared/message-window.ts";
+import { responseModel } from "../shared/agent-model.ts";
+import { isSubagentTaskType } from "../shared/task-types.ts";
+import { currentAgentTask } from "../shared/agent-tasks.ts";
+import { config } from "./config.ts";
+import { db } from "./db.ts";
+import { noteTerminalCommands } from "./cli-info.ts";
+import { runBang, bangMessage } from "./bang.ts";
+import { lastCostState } from "./session-file.ts";
+import { CronExpressionParser } from "cron-parser";
+import { sessionDirs } from "./session-dirs.ts";
+import { childEnv } from "./child-env.ts";
+import { durableTasks, durableTasksForSession, type DurableTask } from "./durable-tasks.ts";
+import { idecron, type IdeCronMode } from "./idecron.ts";
+import { ideCronServer } from "./idecron-mcp.ts";
+import { ideMessagesServer } from "./ide-messages-mcp.ts";
+import { needsInheritedGoalCleanup, markGoalIsolated } from "./btw-policy.ts";
+import { WRITES_DISABLED, READ_ONLY_TOOLS, SIDE_AGENT_TOOLS } from "../shared/write-policy.ts";
+import { conversationInstructions } from "./btw-instructions.ts";
+
+/** Push-based async iterable that never ends until closed — keeps the CLI process alive. */
+class InputQueue implements AsyncIterable<SDKUserMessage> {
+  private items: SDKUserMessage[] = [];
+  private waiters: ((r: IteratorResult<SDKUserMessage>) => void)[] = [];
+  private closed = false;
+
+  push(item: SDKUserMessage) {
+    if (this.closed) throw new Error("会话输入已关闭，请重试。");
+    const w = this.waiters.shift();
+    if (w) w({ value: item, done: false });
+    else this.items.push(item);
+  }
+
+  close() {
+    this.closed = true;
+    this.items.length = 0;
+    for (const w of this.waiters.splice(0)) w({ value: undefined, done: true });
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<SDKUserMessage> {
+    return {
+      next: () => {
+        const item = this.items.shift();
+        if (item) return Promise.resolve({ value: item, done: false });
+        if (this.closed) return Promise.resolve({ value: undefined, done: true });
+        return new Promise((resolve) => this.waiters.push(resolve));
+      },
+    };
+  }
+}
+
+function isLocalCommandOutput(content: unknown): boolean {
+  const text = typeof content === "string" ? content : Array.isArray(content) ? String((content[0] as { text?: unknown })?.text ?? "") : "";
+  return /^\s*<local-command-std(out|err)>/.test(text);
+}
+
+/** The SDK's query(); unit tests swap in a scripted fake to control event order and timing. */
+let queryImpl: typeof query = query;
+export function setQueryImplForTests(fn: typeof query) {
+  queryImpl = fn;
+}
+
+const EVENT_BUFFER_LIMIT = 5000;
+const DELTA_FLUSH_MS = 50;
+const QUESTIONS_DISABLED = "本会话已禁用 AskUserQuestion。不要再次调用提问工具；请根据已有信息作出合理判断并继续任务。缺少必要信息、无法继续时，请直接在回复中说明。";
+
+/** System subtypes that are pure noise for the UI. */
+const DROP_SYSTEM = new Set(["init", "thinking_tokens", "hook_started", "hook_progress", "hook_response", "files_persisted"]);
+
+type Pending = { req: PendingRequest; resolve: (r: PermissionResult) => void; input: Record<string, unknown> };
+
+export type LiveSessionListener = (seq: number, ev: LiveEvent) => void;
+export type LiveTextPart = { id: string; sessionId: string; text: string };
+
+/**
+ * One CLI session held by the server. The query stays open between turns so that
+ * queued messages, background tasks and scheduled tasks keep working without a browser.
+ */
+export class LiveSession {
+  readonly events: SeqEvent[] = [];
+  seq = 0;
+  state: SessionState = "idle";
+  model?: string;
+  effort?: string;
+  planMode = false;
+  askQuestionsEnabled = true;
+  writeEnabled = true;
+  costUsd?: number;
+  /** Cumulative cost at the previous result; each turn's cost is the difference. */
+  private prevCost?: number;
+  lastActivity = Date.now();
+
+  private q?: Query;
+  private pumpDone?: Promise<void>;
+  private input?: InputQueue;
+  private inheritedGoalCommand?: string;
+  private contextAppendCommand?: string;
+  private pending = new Map<string, Pending>();
+  private listeners = new Set<LiveSessionListener>();
+  private deltaBuf = new Map<string, Extract<LiveEvent, { k: "delta" }>>();
+  private deltaTimer?: NodeJS.Timeout;
+  private currentMsgId = new Map<string | null, string>();
+  private blockKinds = new Map<string, "text" | "thinking" | "other">();
+  /** Extra directories last handed to the current CLI process (undefined = none yet). */
+  private appliedDirs?: string[];
+
+  /** Scheduled tasks and background tasks, as last reported by the CLI. */
+  crons: CronInfo[] = [];
+  /** A persisted list exists, but the current CLI process has not confirmed it yet. */
+  cronsStale = false;
+  /** The stale marker came from a durable-only row, so it can be cleared when the file disappears. */
+  private staleFromDurable = false;
+  /** The next idle transition is an internal refresh, not a user-visible turn. */
+  private silentTurn = false;
+  tasks: BgTask[] = [];
+  private agentTasks = new Map<string, AgentTask>();
+  private streamingReplay = new StreamingReplay();
+
+  /** Changes only when this session view is invalidated, independently of replay clipping. */
+  historyRevision: string = crypto.randomUUID();
+
+  get streamingCheckpoints(): SeqEvent[] { return this.streamingReplay.checkpoints; }
+
+  constructor(
+    readonly sessionId: string,
+    public cwd: string,
+    private readonly onChange: () => void,
+    /** Turn finished, or the session started waiting for the user. */
+    private readonly onTransition: (from: SessionState, to: SessionState, turn: { failed: boolean; silent: boolean }) => void = () => {},
+    private readonly onTextPart: (part: LiveTextPart) => void = () => {},
+  ) {
+    const view = db.prepare("SELECT ask_questions_enabled, write_enabled FROM session_view WHERE session_id=?").get(sessionId) as { ask_questions_enabled: number; write_enabled: number } | undefined;
+    this.askQuestionsEnabled = view?.ask_questions_enabled !== 0;
+    this.writeEnabled = view?.write_enabled !== 0;
+  }
+
+  subscribe(fn: LiveSessionListener): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  snapshot(): LiveSnapshot {
+    return {
+      state: this.state,
+      pending: [...this.pending.values()].map((p) => p.req),
+      model: this.model,
+      effort: this.effort,
+      planMode: this.planMode,
+      askQuestionsEnabled: this.askQuestionsEnabled,
+      writeEnabled: this.writeEnabled,
+      costUsd: this.costUsd,
+      crons: this.allCrons(),
+      cronsStale: this.cronsStale,
+      tasks: this.tasks,
+      agentTasks: [...this.agentTasks.values()],
+    };
+  }
+
+  /** Events after `seq`, or undefined if they are no longer buffered. */
+  eventsSince(seq: number): SeqEvent[] | undefined {
+    if (seq === this.seq) return [];
+    const first = this.events[0];
+    if (!first || seq < first.seq - 1 || seq > this.seq) return undefined;
+    return this.events.filter((e) => e.seq > seq);
+  }
+
+  get isStarted() {
+    return !!this.q;
+  }
+
+  private emit(ev: LiveEvent) {
+    if (ev.k !== "delta") this.flushDeltas();
+    // Attribution must outlive the capped task status map, even for a browser
+    // first connecting after the invocation's lifecycle frames left replay.
+    const parent = ev.k === "sdk" ? ev.m.parent_tool_use_id : ev.k === "delta" ? ev.parent : undefined;
+    const agentId = parent ? this.agentTasks.get(parent)?.taskId : undefined;
+    if (agentId && (ev.k === "sdk" || ev.k === "delta")) ev = { ...ev, agentId };
+    this.lastActivity = Date.now();
+    const seq = ++this.seq;
+    const settled = this.streamingReplay.push({ seq, ev });
+    if (ev.k === "sdk" && settled.indexes.length) ev = { ...ev, m: { ...ev.m, _streamBlocks: settled.indexes,
+      ...(Object.keys(settled.thinking).length ? { _streamThinking: settled.thinking } : {}) } };
+    this.events.push({ seq, ev });
+    if (this.events.length > EVENT_BUFFER_LIMIT) this.events.splice(0, this.events.length - EVENT_BUFFER_LIMIT);
+    for (const l of this.listeners) l(seq, ev);
+  }
+
+  private setState(state: SessionState) {
+    if (this.state === state) return;
+    const from = this.state;
+    this.state = state;
+    // A stop we initiated (rewind, config reload, delete) is not a finished turn: no notification.
+    // An internal cron refresh is also silent: it only exists to let the Stop hook report state.
+    const silent = this.stopping !== undefined || this.silentTurn;
+    if (state === "running") this.fireDeferredIdle(); // a previous turn's notification goes out first
+    if (state === "idle" && from !== "idle" && !silent && !this.resultThisTurn) {
+      // The turn's result (success or failure) may still be on its way: decide when it arrives.
+      this.deferredIdleFrom = from;
+      this.deferredIdleTimer = setTimeout(() => this.fireDeferredIdle(), 3000);
+    } else {
+      this.onTransition(from, state, { failed: this.lastTurnFailed, silent });
+    }
+    if (state === "running") {
+      this.lastTurnFailed = false;
+      this.userInterrupted = false;
+      this.resultThisTurn = false;
+    }
+    if (state === "idle") {
+      this.silentTurn = false;
+      this.maybeReloadConfig();
+    }
+    this.emit({ k: "state", state });
+    this.onChange();
+  }
+
+  /** Conversation rewind waiting for the next message: keep the transcript up to this record. */
+  get rewindAnchor(): string | undefined {
+    const row = db.prepare("SELECT rewind_anchor FROM session_view WHERE session_id = ?").get(this.sessionId) as { rewind_anchor: string | null } | undefined;
+    return row?.rewind_anchor ?? undefined;
+  }
+
+  // Serialize management operations, not the model turn: later prompts can still queue immediately.
+  private operations: Promise<void> = Promise.resolve();
+  private awaitingCommands = new Set<string>();
+
+  private operate<T>(fn: () => Promise<T>): Promise<T> {
+    const result = this.operations.then(fn);
+    this.operations = result.then(() => {}, () => {});
+    return result;
+  }
+
+  private maybeReloadConfig() {
+    if (this.configStale && this.state === "idle" && this.awaitingCommands.size === 0) {
+      void this.reloadConfig().catch((err) => this.emit({ k: "error", message: String(err) }));
+    }
+  }
+
+  private starting?: Promise<void>;
+
+  /** Start the CLI once; concurrent callers (two devices sending at once) share the same start. */
+  private ensureStarted(): Promise<void> {
+    if (this.closed) return Promise.reject(new Error("这个会话已被删除。"));
+    // While a start is in progress (q may already exist, extra dirs not yet applied), wait for it.
+    if (this.starting) return this.starting;
+    if (this.q && !this.stopping) return Promise.resolve();
+    this.starting ??= this.start().finally(() => (this.starting = undefined));
+    return this.starting;
+  }
+
+  /** Bring the CLI process up without sending anything (e.g. to restore scheduled tasks). */
+  async wake() {
+    return this.operate(() => this.ensureStarted());
+  }
+
+  /**
+   * Ask the CLI to report restored scheduled tasks. The Stop hook is the only public source,
+   * so this deliberately runs one tiny internal turn. The turn is user-visible (the CLI only
+   * reports Stop state for real turns) but its completion notification is suppressed.
+   */
+  async refreshCrons() {
+    if (this.closed) throw new Error("这个会话已被删除。");
+    if (this.state !== "idle" || this.awaitingCommands.size) throw new Error("会话正在运行，稍后再刷新定时任务。");
+    if (this.rewindAnchor) throw new Error("会话正在等待回退，先发送消息或取消回退再刷新定时任务。");
+    return this.operate(async () => {
+      await this.ensureStarted();
+      if (this.closed || !this.q || !this.input) throw new Error("会话进程已停止，请重试。");
+      if (this.state !== "idle" || this.awaitingCommands.size) throw new Error("会话正在运行，稍后再刷新定时任务。");
+      const uuid = crypto.randomUUID();
+      const text = "系统恢复，请调用一次 CronList 工具，列出当前定时任务。";
+      this.silentTurn = true;
+      try {
+        this.input.push({
+          type: "user",
+          uuid: uuid as never,
+          session_id: this.sessionId,
+          parent_tool_use_id: null,
+          message: { role: "user", content: text },
+        });
+      } catch (err) {
+        this.silentTurn = false;
+        throw err;
+      }
+      this.awaitingCommands.add(uuid);
+      this.emit({ k: "user", uuid, text, ts: Date.now() });
+      this.setState("running");
+    });
+  }
+
+  private async start() {
+    if (this.stopping) await this.stopping;
+    if (this.closed) throw new Error("这个会话已被删除。");
+    if (this.q) return;
+    // e.g. a session of a worktree that has been cleaned up: its history stays readable, but the CLI can't run there.
+    try {
+      await fs.promises.access(this.cwd);
+    } catch {
+      throw new Error(`会话的工作目录已不存在（${this.cwd}），无法继续这个会话；它的历史仍可查看。`);
+    }
+    const existing = await getSessionInfo(this.sessionId, { dir: this.cwd }).catch(() => undefined);
+    if (this.closed) throw new Error("这个会话已被删除。");
+    this.input = new InputQueue();
+    // total_cost_usd stays cumulative across a resume (restored from the jsonl's cost-state).
+    this.prevCost = existing ? ((await lastCostState(this.cwd, this.sessionId)) ?? 0) : 0;
+    this.costUsd ??= existing ? this.prevCost : undefined;
+    const model = config.modelOverride ?? this.model;
+    const clearInheritedGoal = await needsInheritedGoalCleanup(this.cwd, this.sessionId);
+    this.q = queryImpl({
+      prompt: this.input,
+      options: {
+        cwd: this.cwd,
+        ...(existing ? { resume: this.sessionId } : { sessionId: this.sessionId }),
+        // A pending conversation rewind continues from the kept part of the transcript.
+        ...(existing && this.rewindAnchor ? { resumeSessionAt: this.rewindAnchor } : {}),
+        ...(model ? { model } : {}),
+        ...(this.effort ? { effort: this.effort as never } : {}),
+        permissionMode: this.planMode ? "plan" : "bypassPermissions",
+        allowDangerouslySkipPermissions: true,
+        includePartialMessages: true,
+        settingSources: ["user", "project", "local"],
+        enableFileCheckpointing: true,
+        perTaskStopAffordance: true,
+        mcpServers: { IDECron: ideCronServer(this.sessionId, () => this.cwd), IDEMessages: ideMessagesServer(this.sessionId) },
+        canUseTool: this.canUseTool,
+        // The Stop hook is where the CLI reports scheduled tasks (/loop, CronCreate) and background tasks.
+        hooks: {
+          // Re-evaluate at prompt time, including after resume or promotion.
+          // A fixed startup system prompt would retain the old role in a live CLI.
+          UserPromptSubmit: [{ hooks: [async () => {
+            const row = db.prepare("SELECT btw_parent, btw_prompt_uuid, btw_question FROM session_view WHERE session_id=?").get(this.sessionId) as { btw_parent: string | null; btw_prompt_uuid: string | null; btw_question: string | null } | undefined;
+            const context = conversationInstructions(!!row?.btw_parent, !!(row?.btw_prompt_uuid || row?.btw_question), this.writeEnabled);
+            return context ? { hookSpecificOutput: { hookEventName: "UserPromptSubmit" as const, additionalContext: context } } : {};
+          }] }],
+          // Runs for main and child agent tools, including bypassPermissions.
+          // Read the live flag on each check; never capture its startup value.
+          PreToolUse: [{ hooks: [async (input) => {
+            const denied = input.hook_event_name === "PreToolUse" ? this.toolDenial(input.tool_name) : undefined;
+            return denied ? { hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "deny" as const, permissionDecisionReason: denied } } : {};
+          }] }],
+          Stop: [
+            {
+              hooks: [
+                async (input) => {
+                  const i = input as { session_crons?: { id: string; schedule: string; recurring: boolean; prompt: string }[]; background_tasks?: { id: string; type: string; status: string; description: string; command?: string }[] };
+                  if (i.session_crons) this.setCrons(i.session_crons);
+                  if (i.background_tasks) {
+                    const byId = new Map(this.tasks.map((t) => [t.id, t]));
+                    for (const t of i.background_tasks) byId.set(t.id, { id: t.id, type: t.type, description: t.description, status: t.status, command: t.command });
+                    this.setTasks([...byId.values()].slice(-30));
+                  }
+                  return {};
+                },
+              ],
+            },
+          ],
+        },
+        // A non-SDK entrypoint keeps web sessions in the CLI's /resume list (see NOTES.md).
+        env: childEnv({
+          CLAUDE_CODE_ENTRYPOINT: "claude-ide",
+          // Task tools (the todo list) are off in SDK mode unless asked for.
+          CLAUDE_CODE_ENABLE_TODO_TOOLS: "1",
+          CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1",
+        }),
+      },
+    });
+    this.pumpDone = this.pump(this.q);
+    // Extra directories (/add-dir) go through the flag layer so they can also be removed live.
+    await this.setAdditionalDirectories(sessionDirs(this.sessionId));
+    if (clearInheritedGoal) {
+      // forkSession copies goal_status attachments. Clear the CLI's restored
+      // Stop goal before the question, without editing the parent's transcript
+      // or involving the model. A durable marker survives promotion/resume.
+      const uuid = crypto.randomUUID();
+      this.inheritedGoalCommand = uuid;
+      this.input.push({ type: "user", uuid: uuid as never, session_id: this.sessionId, parent_tool_use_id: null,
+        message: { role: "user", content: "/goal clear" }, shouldQuery: false });
+      this.awaitingCommands.add(uuid);
+    }
+  }
+
+  /** /add-dir: the session's extra directories, applied to the running CLI process (see server/add-dirs.ts). */
+  async setAdditionalDirectories(dirs: string[]) {
+    if (!this.q) return; // applied when the process starts
+    const applied = this.appliedDirs;
+    this.appliedDirs = dirs;
+    if ((applied === undefined && dirs.length === 0) || JSON.stringify(applied) === JSON.stringify(dirs)) return;
+    await this.q.applyFlagSettings({ permissions: { additionalDirectories: dirs } } as never).catch((err: unknown) => {
+      this.emit({ k: "error", message: `额外目录没能生效：${err instanceof Error ? err.message : String(err)}` });
+    });
+  }
+
+  private async pump(q: Query) {
+    try {
+      for await (const m of q) {
+        if (this.q === q) this.handle(m);
+      }
+    } catch (err) {
+      this.emit({ k: "error", message: err instanceof Error ? err.message : String(err) });
+    } finally {
+      if (this.q === q) {
+        // The CLI went away by itself mid-turn (crash, killed): that turn failed.
+        if (this.state !== "idle") this.lastTurnFailed = true;
+        this.q = undefined;
+        this.appliedDirs = undefined;
+        this.input = undefined;
+        this.awaitingCommands.clear();
+        this.inheritedGoalCommand = undefined;
+        this.contextAppendCommand = undefined;
+        this.endAgentTasks();
+        this.dropPending();
+        this.setState("idle");
+      }
+    }
+  }
+
+  private handle(m: SDKMessage) {
+    const initializationCommand = this.inheritedGoalCommand ?? this.contextAppendCommand;
+    if (initializationCommand) {
+      // Initialization runs ahead of the question without querying the model.
+      // Its local result must not finish the question or produce a toast.
+      if (m.type === "result" && m.num_turns === 0 && (m.user_message_uuids?.includes(initializationCommand) || !m.user_message_uuids?.length)) {
+        const commandUuid = initializationCommand;
+        const clearingGoal = commandUuid === this.inheritedGoalCommand;
+        this.awaitingCommands.delete(commandUuid);
+        if (clearingGoal) this.inheritedGoalCommand = undefined;
+        else this.contextAppendCommand = undefined;
+        if (m.is_error || m.subtype !== "success") {
+          this.emit({ k: "error", message: clearingGoal ? "旁支会话的继承目标未能清除，请重试。" : "旁支会话的历史边界未能写入，请重试。" });
+          this.input?.close();
+          this.q?.close();
+        } else if (clearingGoal) markGoalIsolated(this.sessionId, commandUuid);
+        return;
+      }
+      if ((m.type === "system" && m.subtype === "session_state_changed")
+        || (m.type === "assistant" && m.message.model === "<synthetic>")) return;
+    }
+    // The SDK omits timestamp on some live emitters; give every displayable frame one
+    // receive-time stamp so the transcript and its frozen history agree.
+    if (m.type === "user" || m.type === "assistant" || m.type === "result" || m.type === "system") {
+      const stamped = m as unknown as { timestamp?: unknown };
+      if (typeof stamped.timestamp !== "string") stamped.timestamp = new Date().toISOString();
+    }
+    this.trackAgentTasks(m as SdkMessageLike);
+    // Complete text blocks only: partial deltas and the later result must not be pushed again.
+    // SDK frame uuid (not message.id) distinguishes consecutive blocks of one API message.
+    if (m.type === "assistant" && !m.parent_tool_use_id && !m.error && !m.aborted && m.message.model !== "<synthetic>") {
+      m.message.content.forEach((block, index) => {
+        if (block.type === "text" && block.text) this.onTextPart({ id: `${m.uuid}:${index}`, sessionId: this.sessionId, text: block.text });
+      });
+    }
+    // Terminal lifecycle frames also cover no-model commands (!bash and slash commands).
+    const lifecycle = m as unknown as { type: string; state?: string; command_uuid?: string };
+    if (lifecycle.type === "command_lifecycle" && ["completed", "cancelled"].includes(lifecycle.state ?? "") && lifecycle.command_uuid) {
+      this.awaitingCommands.delete(lifecycle.command_uuid);
+      this.maybeReloadConfig();
+    }
+    if (m.type === "stream_event") return this.handleStreamEvent(m);
+    if (m.type === "system") {
+      if (m.subtype === "session_state_changed") return this.setState(m.state);
+      if (m.subtype === "init") noteTerminalCommands(m.terminal_slash_commands);
+      if (m.subtype === "background_tasks_changed") {
+        // The full set of live tasks each time. Tasks that left it are kept (finished) so their output stays reachable.
+        const live = new Map(m.tasks.map((t) => [t.task_id, t]));
+        const merged: BgTask[] = this.tasks.map((t) => (live.has(t.id) || t.status !== "running" ? t : { ...t, status: "completed" }));
+        for (const t of m.tasks) {
+          if (!merged.some((x) => x.id === t.task_id)) merged.push({ id: t.task_id, type: t.task_type, description: t.description, status: "running" });
+        }
+        this.setTasks(merged.slice(-30));
+      }
+      if ((m.subtype === "task_updated" || m.subtype === "task_notification") && this.tasks.some((t) => t.id === m.task_id)) {
+        const status = m.subtype === "task_updated" ? m.patch?.status : m.status;
+        if (status) this.setTasks(this.tasks.map((t) => (t.id === m.task_id ? { ...t, status } : t)));
+      }
+      if (DROP_SYSTEM.has(m.subtype)) return;
+    }
+    if (m.type === "result") {
+      for (const uuid of m.user_message_uuids ?? []) this.awaitingCommands.delete(uuid);
+      this.maybeReloadConfig();
+      // A failed turn (API error, max turns…) notifies as an error; a turn the user interrupted does not.
+      this.lastTurnFailed = (m.is_error || m.subtype !== "success") && !this.userInterrupted;
+      this.userInterrupted = false;
+      this.resultThisTurn = true;
+      this.fireDeferredIdle();
+      let turnCost: number | undefined;
+      if (typeof m.total_cost_usd === "number") {
+        this.costUsd = m.total_cost_usd;
+        if (this.prevCost !== undefined) turnCost = Math.max(0, m.total_cost_usd - this.prevCost);
+        this.prevCost = m.total_cost_usd;
+      }
+      this.onChange();
+      // The CLI writes the session title about a second after the turn ends.
+      setTimeout(this.onChange, 1500);
+      this.emit({ k: "sdk", m: { ...(m as SdkMessageLike), turn_cost_usd: turnCost } });
+      return;
+    }
+    // Our own prompts are echoed (isReplay) — clients already show them.
+    // Except CLI-generated output in that echo, e.g. a skill whose `!command` preamble failed
+    // (/security-review without origin/HEAD) — the only explanation the user gets [实测].
+    if (m.type === "user" && "isReplay" in m && m.isReplay && !isLocalCommandOutput(m.message?.content)) return;
+    this.emit({ k: "sdk", m: m as never });
+  }
+
+  private trackAgentTasks(m: SdkMessageLike) {
+    let changed = false;
+    const put = (task: AgentTask) => {
+      if (JSON.stringify(this.agentTasks.get(task.toolUseId)) === JSON.stringify(task)) return;
+      this.agentTasks.delete(task.toolUseId);
+      this.agentTasks.set(task.toolUseId, task);
+      changed = true;
+    };
+    // message_start is not forwarded as a transcript event. Keep its actual
+    // model in bounded task metadata so it also survives replay eviction.
+    const model = responseModel(m);
+    const owner = m.parent_tool_use_id ? this.agentTasks.get(m.parent_tool_use_id) : undefined;
+    if (model && owner) put({ ...owner, model });
+    const blocks = (m.message as { content?: unknown })?.content;
+    if (m.type === "assistant" && Array.isArray(blocks)) {
+      for (const block of blocks as { type: string; id: string; name?: string; input?: Record<string, unknown> }[]) {
+        if (block.type !== "tool_use" || !["Agent", "Task"].includes(block.name ?? "")) continue;
+        if (this.agentTasks.has(block.id)) continue;
+        const input = block.input ?? {};
+        put({ toolUseId: block.id, ...(m.parent_tool_use_id ? { parentToolUseId: m.parent_tool_use_id } : {}), status: "running", description: String(input.description ?? "").slice(0, 512), agentType: String(input.subagent_type ?? "").slice(0, 128), background: !!input.run_in_background });
+      }
+    } else if (m.type === "user" && Array.isArray(blocks)) {
+      for (const block of blocks as { type: string; tool_use_id: string; is_error?: boolean }[]) {
+        const task = this.agentTasks.get(block.tool_use_id);
+        if (block.type === "tool_result" && task && (!task.background || block.is_error)) put({ ...task, status: block.is_error ? "failed" : "completed" });
+      }
+    } else if (m.type === "result") {
+      for (const task of this.agentTasks.values()) {
+        const parent = task.parentToolUseId ?? (task.parentTaskId
+          ? [...this.agentTasks.values()].find((candidate) => candidate.taskId === task.parentTaskId)?.toolUseId
+          : undefined);
+        // A main result cannot settle work owned by an independently running agent.
+        // An unresolved parent task is still nested, even if its tool call was evicted.
+        if (task.background || (parent ?? (task.parentTaskId ? "unknown-parent" : null)) !== (m.parent_tool_use_id ?? null) || !["pending", "running", "paused"].includes(task.status)) continue;
+        put({ ...task, status: this.userInterrupted ? "stopped" : m.is_error || m.subtype !== "success" ? "failed" : "completed" });
+      }
+    } else if (m.type === "system" && m.subtype?.startsWith("task_")) {
+      const existing = typeof m.tool_use_id === "string" ? this.agentTasks.get(m.tool_use_id)
+        : typeof m.task_id === "string" ? currentAgentTask(this.agentTasks.values(), m.task_id) : undefined;
+      const isAgent = existing || isSubagentTaskType(m.task_type) || m.subagent_type !== undefined;
+      const toolUseId = existing?.toolUseId ?? (typeof m.tool_use_id === "string" ? m.tool_use_id : undefined);
+      if (isAgent && toolUseId) {
+        const runId = typeof m.run_id === "string" ? m.run_id : undefined;
+        if (existing?.runId && runId && runId < existing.runId) return;
+        const patch = m.patch as Record<string, unknown> | undefined;
+        const status = m.status ?? patch?.status ?? (m.subtype === "task_started" ? "running" : existing?.status ?? "running");
+        const description = m.description ?? patch?.description;
+        put({ ...existing, toolUseId, taskId: typeof m.task_id === "string" ? m.task_id : existing?.taskId,
+          runId: runId ?? existing?.runId, status: status as AgentTask["status"],
+          ...(typeof m.parent_task_id === "string" ? { parentTaskId: m.parent_task_id } : {}),
+          ...(m.parent_tool_use_id ? { parentToolUseId: m.parent_tool_use_id } : {}),
+          ...(description !== undefined ? { description: String(description).slice(0, 512) } : {}),
+          ...(m.subagent_type !== undefined ? { agentType: String(m.subagent_type).slice(0, 128) } : {}),
+          ...(typeof (m.is_backgrounded ?? patch?.is_backgrounded) === "boolean" ? { background: (m.is_backgrounded ?? patch?.is_backgrounded) as boolean } : {}) });
+      }
+    }
+    while (this.agentTasks.size > 128) {
+      const terminal = [...this.agentTasks.values()].find((task) => !["pending", "running", "paused"].includes(task.status));
+      this.agentTasks.delete(terminal?.toolUseId ?? this.agentTasks.keys().next().value!);
+    }
+    if (changed) this.emit({ k: "agent_tasks", tasks: [...this.agentTasks.values()] });
+  }
+
+  private endAgentTasks() {
+    this.flushDeltas();
+    let changed = false;
+    for (const [id, task] of this.agentTasks) {
+      if (!["pending", "running", "paused"].includes(task.status)) continue;
+      this.agentTasks.set(id, { ...task, status: "stopped" });
+      changed = true;
+    }
+    this.streamingReplay.clear();
+    if (changed) this.emit({ k: "agent_tasks", tasks: [...this.agentTasks.values()] });
+  }
+
+  private handleStreamEvent(m: Extract<SDKMessage, { type: "stream_event" }>) {
+    const e = m.event;
+    const parent = m.parent_tool_use_id;
+    if (e.type === "message_start") {
+      this.currentMsgId.set(parent, e.message.id);
+      return;
+    }
+    const msgId = this.currentMsgId.get(parent);
+    if (!msgId) return;
+    if (e.type === "content_block_start") {
+      const t = e.content_block.type;
+      this.blockKinds.set(`${msgId}:${e.index}`, t === "text" ? "text" : t === "thinking" ? "thinking" : "other");
+      return;
+    }
+    if (e.type !== "content_block_delta") return;
+    let kind: "text" | "thinking";
+    let text: string;
+    if (e.delta.type === "text_delta") {
+      kind = "text";
+      text = e.delta.text;
+    } else if (e.delta.type === "thinking_delta") {
+      kind = "thinking";
+      text = e.delta.thinking;
+    } else return;
+    const key = `${msgId}:${e.index}`;
+    const buf = this.deltaBuf.get(key);
+    if (buf) buf.text += text;
+    else this.deltaBuf.set(key, { k: "delta", msgId, index: e.index, kind, text, parent });
+    this.deltaTimer ??= setTimeout(() => this.flushDeltas(), DELTA_FLUSH_MS);
+  }
+
+  private flushDeltas() {
+    if (this.deltaTimer) clearTimeout(this.deltaTimer);
+    this.deltaTimer = undefined;
+    if (this.deltaBuf.size === 0) return;
+    const bufs = [...this.deltaBuf.values()];
+    this.deltaBuf.clear();
+    for (const d of bufs) this.emit(d);
+  }
+
+  private toolDenial(toolName: string): string | undefined {
+    if (!this.writeEnabled && !READ_ONLY_TOOLS.has(toolName)) return WRITES_DISABLED;
+    if (SIDE_AGENT_TOOLS.has(toolName) && db.prepare("SELECT 1 FROM session_view WHERE session_id=? AND btw_parent IS NOT NULL").get(this.sessionId)) {
+      return "btw 旁支只用于问答和轻量探索，不能创建或操作子代理，也不能向其他会话发送消息。需要执行任务时，请先转为普通会话。";
+    }
+  }
+
+  private canUseTool: CanUseTool = (toolName, input, { signal, toolUseID }) => {
+    const denied = this.toolDenial(toolName);
+    if (denied) return Promise.resolve({ behavior: "deny", message: denied });
+    let req: PendingRequest;
+    const id = crypto.randomUUID();
+    if (toolName === "AskUserQuestion") {
+      if (!this.askQuestionsEnabled) return Promise.resolve({ behavior: "deny", message: QUESTIONS_DISABLED });
+      req = { id, kind: "ask", toolUseId: toolUseID, input: input as never };
+    } else if (toolName === "ExitPlanMode") {
+      req = { id, kind: "plan", toolUseId: toolUseID, input: { plan: String(input.plan ?? "") } };
+    } else {
+      // Only bypassPermissions/plan are offered; never prompt for ordinary tools.
+      return Promise.resolve({ behavior: "allow", updatedInput: input });
+    }
+    return new Promise<PermissionResult>((resolve) => {
+      this.pending.set(id, { req, resolve, input });
+      signal.addEventListener("abort", () => this.resolvePending(id, { kind: "cancel", message: "Aborted" }));
+      this.emit({ k: "pending", req });
+      this.onChange();
+    });
+  };
+
+  resolvePending(id: string, answer: PendingAnswer): boolean {
+    const p = this.pending.get(id);
+    if (!p) return false;
+    this.pending.delete(id);
+    if (answer.kind === "ask") {
+      p.resolve({ behavior: "allow", updatedInput: { ...p.input, answers: answer.answers } });
+    } else if (answer.kind === "plan" && answer.approve) {
+      p.resolve({ behavior: "allow", updatedInput: p.input });
+      this.planMode = false;
+      void this.q?.setPermissionMode("bypassPermissions").catch(() => {});
+      this.emitSettings();
+    } else if (answer.kind === "plan") {
+      p.resolve({ behavior: "deny", message: answer.feedback || "The user rejected the plan." });
+    } else {
+      p.resolve({ behavior: "deny", message: answer.message ?? "The user dismissed this request." });
+    }
+    this.emit({ k: "resolved", id });
+    this.onChange();
+    return true;
+  }
+
+  private emitSettings() {
+    this.emit({ k: "settings", model: this.model, effort: this.effort, planMode: this.planMode, askQuestionsEnabled: this.askQuestionsEnabled, writeEnabled: this.writeEnabled });
+  }
+
+  /** Optional context is a visible user message appended before this prompt, without its own model turn. */
+  async send(uuid: string, text: string, images: ImageInput[] = [], precedingText?: string) {
+    return this.operate(() => this.sendLocked(uuid, text, images, undefined, precedingText));
+  }
+
+  /** Deliver an IDECron task. `next_turn` leaves the row due until the session is idle. */
+  async sendScheduled(uuid: string, text: string, mode: IdeCronMode): Promise<boolean> {
+    return this.operate(async () => {
+      if (this.closed) throw new Error("这个会话已被删除。");
+      if (this.rewindAnchor) return false;
+      if (mode === "next_turn" && (this.state !== "idle" || this.awaitingCommands.size || this.pending.size)) return false;
+      if (mode === "interrupt" && this.state !== "idle") await this.q?.interrupt().catch(() => {});
+      const priority = mode === "steer" && this.state !== "idle" ? "next" as const : undefined;
+      return this.sendLocked(uuid, text, [], undefined, undefined, priority, true);
+    });
+  }
+
+  get queuedMessageCount() { return this.awaitingCommands.size; }
+
+  /** HTTP subscription messages share the live query but are never CLI slash commands. */
+  async sendExternalText(uuid: string, text: string, stillActive: () => boolean) {
+    return this.operate(() => this.sendLocked(uuid, text, [], stillActive));
+  }
+
+  /** Peer messages cannot consume a pending user rewind or grow an unbounded queue.
+   * Keep these checks inside the operation lock and repeat after asynchronous start. */
+  async sendPeerText(uuid: string, text: string, stillActive: () => boolean): Promise<boolean> {
+    return this.operate(() => this.sendLocked(uuid, text, [], () => {
+      if (!stillActive()) return false;
+      if (this.rewindAnchor) throw new Error("目标会话有待处理的回退，请先在该会话确认输入。");
+      if (this.awaitingCommands.size >= 32) throw new Error("目标会话的消息队列已满，请稍后重试。");
+      return true;
+    }));
+  }
+
+  private async sendLocked(uuid: string, text: string, images: ImageInput[], stillActive?: () => boolean, precedingText?: string, priority?: "next", scheduled?: boolean) {
+    if (stillActive && !stillActive()) return false;
+    const content: SDKUserMessage["message"]["content"] = [
+      ...images.map((img) => ({
+        type: "image" as const,
+        source: { type: "base64" as const, media_type: img.mediaType as "image/png", data: img.data },
+      })),
+      ...(text ? [{ type: "text" as const, text }] : []),
+    ];
+    let input: InputQueue;
+    try {
+      await this.ensureStarted();
+      if (this.closed || !this.q || !this.input) throw new Error("会话进程已停止，请重试。");
+      input = this.input;
+    } catch (err) {
+      if (stillActive) throw err;
+      this.emit({ k: "error", message: err instanceof Error ? err.message : String(err) });
+      return false;
+    }
+    if (stillActive && !stillActive()) return false;
+    if (precedingText) {
+      const contextUuid = crypto.randomUUID();
+      this.contextAppendCommand = contextUuid;
+      input.push({ type: "user", uuid: contextUuid as never, session_id: this.sessionId, parent_tool_use_id: null,
+        message: { role: "user", content: precedingText }, shouldQuery: false });
+      this.awaitingCommands.add(contextUuid);
+      this.emit({ k: "user", uuid: contextUuid, text: precedingText, ts: Date.now() });
+    }
+    input.push({
+      type: "user",
+      uuid: uuid as never,
+      session_id: this.sessionId,
+      parent_tool_use_id: null,
+      message: { role: "user", content },
+      ...(priority ? { client_composed: true as const, priority } : stillActive ? { client_composed: true as const, priority: "next" as const } : scheduled ? { client_composed: true as const } : {}),
+    });
+    this.awaitingCommands.add(uuid);
+    this.emit({ k: "user", uuid, text, images: images.length || undefined, ts: Date.now(), imageData: images.length ? images : undefined, ...(scheduled ? { scheduled: true } : {}) });
+    this.setState("running");
+    // The rewound branch now exists in the transcript; the anchor has done its job.
+    if (this.rewindAnchor) {
+      db.prepare("UPDATE session_view SET rewind_anchor = NULL, rewind_text = NULL, rewind_id = NULL WHERE session_id = ?").run(this.sessionId);
+    }
+    return true;
+  }
+
+  private stopping?: Promise<void>;
+  /** Deleted: never start a CLI process for it again. */
+  private closed = false;
+
+  /** Stop for good (session deleted): pending and future starts are refused. */
+  async shutdown() {
+    this.closed = true;
+    clearTimeout(this.deferredIdleTimer);
+    this.deferredIdleFrom = undefined;
+    await this.stop();
+  }
+
+  /** Stop the CLI process (if any) and wait until its output stream has ended. */
+  async stop() {
+    return this.operate(() => this.stopLocked());
+  }
+
+  private async stopLocked() {
+    if (this.stopping) return this.stopping;
+    this.stopping = this.doStop().finally(() => (this.stopping = undefined));
+    return this.stopping;
+  }
+
+  private async doStop() {
+    // A start in progress would otherwise create its CLI process after we "stopped".
+    if (this.starting) await this.starting.catch(() => {});
+    const q = this.q;
+    if (!q) return;
+    const done = this.pumpDone;
+    if (this.state !== "idle") await q.interrupt().catch(() => {});
+    this.input?.close();
+    q.close();
+    this.q = undefined;
+    this.input = undefined;
+    this.appliedDirs = undefined;
+    this.awaitingCommands.clear();
+    this.inheritedGoalCommand = undefined;
+    this.contextAppendCommand = undefined;
+    this.endAgentTasks();
+    await done;
+    // Questions/plans the old process was waiting on can no longer be answered.
+    this.dropPending();
+    this.setState("idle");
+  }
+
+  /**
+   * Free an idle CLI process (each holds ~200 MB). Kept while anything lives in it: a question
+   * waiting for the user, scheduled tasks, running background work. Resume restores the rest.
+   */
+  reapIfIdle(maxIdleMs: number): boolean {
+    if (!this.q || this.starting || this.stopping || this.state !== "idle") return false;
+    if (this.awaitingCommands.size || this.pending.size || this.hasScheduledWork() || this.tasks.some((t) => t.status === "running")) return false;
+    if (Date.now() - this.lastActivity < maxIdleMs) return false;
+    void this.operate(async () => {
+      // A send may have arrived since the reaper inspected this session.
+      if (this.state === "idle" && !this.awaitingCommands.size && !this.pending.size && !this.hasScheduledWork() && !this.tasks.some((t) => t.status === "running") && Date.now() - this.lastActivity >= maxIdleMs) await this.stopLocked();
+    });
+    return true;
+  }
+
+  private dropPending() {
+    for (const [id, p] of this.pending) {
+      p.resolve({ behavior: "deny", message: "Session ended" });
+      this.emit({ k: "resolved", id });
+    }
+    this.pending.clear();
+  }
+
+  /** Tell every viewer to drop live events and reload history. */
+  private resetView() {
+    this.agentTasks.clear();
+    this.events.length = 0;
+    this.historyRevision = crypto.randomUUID();
+    this.emit({ k: "reset", historyRevision: this.historyRevision });
+    this.events.length = 0;
+  }
+
+  /** Rewind the conversation so the next message continues after `anchor` (undefined clears it). */
+  async rewindConversation(projectPath: string, anchor: string, text: string, rewindId = crypto.randomUUID()) {
+    return this.operate(() => this.rewindConversationLocked(projectPath, anchor, text, rewindId));
+  }
+
+  private async rewindConversationLocked(projectPath: string, anchor: string, text: string, rewindId: string) {
+    await this.stopLocked();
+    db.prepare(
+      `INSERT INTO session_view (session_id, project_path, rewind_anchor, rewind_text, rewind_id) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(session_id) DO UPDATE SET rewind_anchor = excluded.rewind_anchor, rewind_text = excluded.rewind_text, rewind_id = excluded.rewind_id`,
+    ).run(this.sessionId, projectPath, anchor, text, rewindId);
+    this.resetView();
+    this.onChange();
+    return rewindId;
+  }
+
+  /** Restore files changed by Edit/Write since `userMessageUuid` was sent (dryRun only previews). */
+  async rewindFiles(userMessageUuid: string, dryRun: boolean) {
+    return this.operate(() => this.rewindFilesLocked(userMessageUuid, dryRun));
+  }
+
+  private async rewindFilesLocked(userMessageUuid: string, dryRun: boolean) {
+    if (this.rewindAnchor && this.q) await this.stopLocked();
+    await this.ensureStarted();
+    return this.q!.rewindFiles(userMessageUuid, { dryRun });
+  }
+
+  async exportText(): Promise<{ text: string; filename: string }> {
+    return this.operate(() => this.exportTextLocked());
+  }
+
+  private async exportTextLocked() {
+    await this.ensureStarted();
+    const r = (await (this.q as unknown as { exportConversation(): Promise<{ text: string; default_filename?: string }> }).exportConversation());
+    return { text: r.text, filename: r.default_filename ?? `${this.sessionId}.txt` };
+  }
+
+  /** Rename through the running CLI so its cached title does not overwrite ours later. */
+  /** /cd: move the running CLI (and its transcript) to another directory. */
+  async changeDir(dir: string, commit?: () => void) {
+    return this.operate(() => this.changeDirLocked(dir, commit));
+  }
+
+  private async changeDirLocked(dir: string, commit?: () => void) {
+    await this.ensureStarted();
+    type SetCwd = (p: string, o?: { trustAccepted?: boolean; trustedDirectory?: string }) => Promise<Record<string, unknown> | undefined>;
+    const setCwd = (this.q as unknown as { setCwd: SetCwd }).setCwd.bind(this.q);
+    // Two steps, like the CLI's trust dialog: an untrusted directory answers needs_trust with the directory
+    // to trust; the user chose it explicitly with /cd, so accept and echo it back.
+    const first = await setCwd(dir);
+    const trustDir = (first?.trusted_directory ?? first?.trustedDirectory) as string | undefined;
+    const result = first?.needs_trust || first?.status === "needs_trust" || trustDir
+      ? await setCwd(dir, { trustAccepted: true, trustedDirectory: trustDir ?? dir }) : first;
+    if (result?.error || result?.success === false || result?.needs_trust || ["error", "needs_trust"].includes(String(result?.status))) throw new Error(String(result?.error ?? "CLI 未能切换目录。"));
+    this.cwd = dir;
+    commit?.();
+  }
+
+  /** /feedback: report about Claude Code itself to Anthropic, optionally with this transcript. */
+  async submitFeedback(description: string, attachTranscript: boolean) {
+    await this.ensureStarted();
+    return (this.q as unknown as { submitFeedback(d: string, o: object): Promise<unknown> }).submitFeedback(description, { attach_transcript: attachTranscript });
+  }
+
+  async renameLive(title: string): Promise<boolean> {
+    if (!this.q) return false;
+    await (this.q as unknown as { renameSession(title: string): Promise<void> }).renameSession(title);
+    return true;
+  }
+
+  /** `!command`: run it in the project dir and add the output to the conversation without starting a turn. */
+  async runBash(uuid: string, command: string) {
+    return this.operate(() => this.runBashLocked(uuid, command));
+  }
+
+  private async runBashLocked(uuid: string, command: string) {
+    if (this.closed) throw new Error("这个会话已被删除。");
+    if (!this.writeEnabled) throw new Error(WRITES_DISABLED);
+    this.emit({ k: "bash", uuid, command, ts: Date.now() });
+    const out = await runBang(command, this.cwd);
+    const text = bangMessage(command, out);
+    this.emit({ k: "user", uuid, text, ts: Date.now() });
+    let input: InputQueue;
+    try {
+      await this.ensureStarted();
+      if (this.closed || !this.q || !this.input) throw new Error("会话进程已停止，请重试。");
+      input = this.input;
+    } catch (err) {
+      this.emit({ k: "error", message: err instanceof Error ? err.message : String(err) });
+      return;
+    }
+    input.push({
+      type: "user",
+      uuid: uuid as never,
+      session_id: this.sessionId,
+      parent_tool_use_id: null,
+      message: { role: "user", content: text },
+      shouldQuery: false,
+    });
+    this.awaitingCommands.add(uuid);
+  }
+
+  /** Context window usage (cheap 'summary' detail); undefined until the CLI process runs. */
+  async contextUsage() {
+    if (!this.q) return undefined;
+    return this.q.getContextUsage({ detail: "summary" });
+  }
+
+  /** Set by the session manager: keeps sessions with scheduled tasks resumable after a restart. */
+  onCronsChanged?: (crons: CronInfo[], hasDurable: boolean) => void;
+
+  /** Durable tasks in this session's cwd that belong to it (or predate ownership). */
+  private ownDurableCrons(): CronInfo[] {
+    return durableTasksForSession(this.cwd, this.sessionId).map((t) => this.durableCron(t));
+  }
+
+  /** Every durable task in this session's cwd; the panel shows the project's tasks to every session. */
+  private projectDurableCrons(): CronInfo[] {
+    return durableTasks(this.cwd).map((t) => this.durableCron(t));
+  }
+
+  private durableCron(t: DurableTask): CronInfo {
+    return {
+      id: t.id,
+      schedule: t.cron,
+      recurring: t.recurring,
+      prompt: t.prompt,
+      nextRun: nextRun(t.cron),
+      durable: true,
+      ...(t.createdBySessionId ? { createdBySessionId: t.createdBySessionId } : {}),
+    };
+  }
+
+  /** Everything the UI should show: in-process, durable file, then IDECron server tasks. */
+  private allCrons(): CronInfo[] {
+    const out = [...this.crons, ...this.projectDurableCrons()];
+    const ids = new Set(out.map((c) => c.id));
+    for (const c of idecron.cronsFor(this.sessionId)) if (!ids.has(c.id)) out.push(c);
+    return out;
+  }
+
+  /** Re-emit after an IDECron create/cancel/fire without touching the CLI task list. */
+  emitCronList() {
+    this.emit({ k: "crons", crons: this.allCrons() });
+    this.onChange();
+  }
+
+  /** True when the durable file has tasks belonging to this session. */
+  hasDurableWork(): boolean {
+    return this.ownDurableCrons().length > 0;
+  }
+
+  /** True while anything in the CLI process (or its durable file) can wake this session. */
+  hasScheduledWork(): boolean {
+    const durable = this.hasDurableWork();
+    if (this.cronsStale && this.staleFromDurable && !this.crons.length && !durable) {
+      // The durable file was removed after the row was written. The stale marker no longer
+      // describes any scheduled work, so stop protecting an otherwise idle process.
+      this.cronsStale = false;
+      this.staleFromDurable = false;
+      this.onCronsChanged?.([], false);
+      this.emit({ k: "crons", crons: this.allCrons() });
+      this.onChange();
+    }
+    return this.cronsStale || this.crons.length > 0 || durable;
+  }
+
+  /** Restore the last list reported by the CLI before the server restarted. */
+  hydrateCrons(list: CronInfo[], stale: boolean, staleFromDurable = false) {
+    this.crons = list.map((c) => ({ ...c, nextRun: nextRun(c.schedule) }));
+    this.cronsStale = stale;
+    this.staleFromDurable = stale && staleFromDurable;
+  }
+
+  /** Mark a durable-only row stale; unlike a legacy cached row, this can be cleared by the file. */
+  markStaleDurable() {
+    this.cronsStale = true;
+    this.staleFromDurable = true;
+  }
+
+  /** Persist a row for a durable-only session too, so a restart brings its owner back. */
+  noteScheduled() {
+    this.onCronsChanged?.(this.crons, this.ownDurableCrons().length > 0);
+  }
+
+  private setCrons(list: { id: string; schedule: string; recurring: boolean; prompt: string }[]) {
+    this.crons = list.map((c) => ({ ...c, nextRun: nextRun(c.schedule) }));
+    this.cronsStale = false;
+    this.staleFromDurable = false;
+    this.onCronsChanged?.(this.crons, this.ownDurableCrons().length > 0);
+    this.emit({ k: "crons", crons: this.allCrons() });
+    this.onChange();
+  }
+
+  private setTasks(tasks: BgTask[]) {
+    this.tasks = tasks;
+    this.emit({ k: "tasks", tasks });
+  }
+
+  private configStale = false;
+
+  /**
+   * Make the CLI see changed config (MCP servers, plugins, hooks, agents, settings).
+   * An idle session restarts its CLI process (resume keeps the conversation); a busy one
+   * does so when the turn ends. Scheduled tasks and background work live in the process,
+   * so then only plugins and skills are reloaded in place.
+   */
+  async reloadConfig() {
+    return this.operate(() => this.reloadConfigLocked());
+  }
+
+  private async reloadConfigLocked() {
+    const q = this.q;
+    if (!q) return;
+    const holdsWork = this.hasScheduledWork() || this.tasks.some((t) => t.status === "running");
+    if (holdsWork) {
+      await q.reloadPlugins().catch(() => {});
+      await q.reloadSkills().catch(() => {});
+      return;
+    }
+    if (this.state === "idle" && this.awaitingCommands.size === 0) {
+      this.configStale = false;
+      await this.stopLocked();
+    } else this.configStale = true;
+  }
+
+  async taskOutput(taskId: string): Promise<{ output: string; truncated?: boolean }> {
+    if (!this.q) return { output: "" };
+    const r = await (this.q as unknown as { getTaskOutput(id: string): Promise<{ output: string; truncated?: boolean }> }).getTaskOutput(taskId);
+    return { output: r.output, truncated: r.truncated };
+  }
+
+  async stopTask(taskId: string) {
+    await this.q?.stopTask(taskId);
+  }
+
+  /** A live control request, so it must not wait behind the foreground command. */
+  async backgroundTask(toolUseId: string): Promise<boolean> {
+    if (!toolUseId.trim()) throw new Error("缺少工具调用 ID");
+    if (!this.q) return false;
+    return this.q.backgroundTasks(toolUseId);
+  }
+
+  private lastTurnFailed = false;
+  private userInterrupted = false;
+  private resultThisTurn = false;
+  private deferredIdleFrom?: SessionState;
+  private deferredIdleTimer?: NodeJS.Timeout;
+
+  /** Send the "turn ended" notification that was waiting for the turn's result. */
+  private fireDeferredIdle() {
+    if (this.deferredIdleFrom === undefined) return;
+    clearTimeout(this.deferredIdleTimer);
+    const from = this.deferredIdleFrom;
+    this.deferredIdleFrom = undefined;
+    this.onTransition(from, "idle", { failed: this.lastTurnFailed, silent: false });
+  }
+
+  async interrupt() {
+    if (!this.q) return;
+    // Only an interrupt of a turn in progress; otherwise the flag would hide the next real failure.
+    if (this.state !== "idle") this.userInterrupted = true;
+    await this.q.interrupt().catch(() => {});
+  }
+
+  async setModel(model: string) {
+    this.model = model;
+    if (this.q && !config.modelOverride) await this.q.setModel(model).catch(() => {});
+    this.emitSettings();
+  }
+
+  async setEffort(effort: string) {
+    this.effort = effort;
+    if (this.q) await this.q.applyFlagSettings({ effortLevel: effort } as never).catch(() => {});
+    this.emitSettings();
+  }
+
+  async setPlanMode(on: boolean) {
+    this.planMode = on;
+    if (this.q) await this.q.setPermissionMode(on ? "plan" : "bypassPermissions").catch(() => {});
+    this.emitSettings();
+  }
+
+  setAskQuestionsEnabled(on: boolean) {
+    this.askQuestionsEnabled = on;
+    if (!on) {
+      for (const [id, pending] of [...this.pending]) {
+        if (pending.req.kind === "ask") this.resolvePending(id, { kind: "cancel", message: QUESTIONS_DISABLED });
+      }
+    }
+    this.emitSettings();
+  }
+
+  setWriteEnabled(on: boolean) {
+    this.writeEnabled = on;
+    this.emitSettings();
+  }
+
+  close() {
+    this.endAgentTasks();
+    this.input?.close();
+    this.q?.close();
+  }
+}
+
+/** Next fire time of a 5-field cron expression in local time, or undefined if it cannot be parsed. */
+function nextRun(schedule: string): number | undefined {
+  try {
+    return CronExpressionParser.parse(schedule).next().getTime();
+  } catch {
+    return undefined;
+  }
+}