@thaut/claude-ide 0.0.0-stage → 1.0.0

package/server/sessions.ts

@@ -0,0 +1,638 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { deleteSession, forkSession, getSessionInfo, getSessionMessages, listSessions, renameSession } from "@anthropic-ai/claude-agent-sdk";
+import { decodeProjectId, encodeProjectId, type CronInfo, type ProjectInfo, type SessionFileInfo, type SessionListItem, type SessionState } from "../shared/protocol.ts";
+import { db } from "./db.ts";
+import { LiveSession, type LiveTextPart } from "./live-session.ts";
+import { forkedFrom } from "./cli-files.ts";
+import { localCommandOutputs, sessionFile } from "./session-file.ts";
+import { historyPage, historyMessage, historyReadPath, type PageOptions } from "./history-pages.ts";
+import { draftCwds, historyCwd, sessionCwd, setSessionCwd, worktreeName, worktreeTranscriptCwds } from "./session-dirs.ts";
+import { durableTasksForSession } from "./durable-tasks.ts";
+import { idecron } from "./idecron.ts";
+import { projectWorktrees } from "./worktree-git.ts";
+import { beginSessionDeletion, configureSessionMessaging } from "./session-messaging.ts";
+import { removeSessionAliases } from "./session-aliases.ts";
+
+// ---------- projects (view state: which directories the user works in) ----------
+
+export async function listProjects(): Promise<ProjectInfo[]> {
+  const rows = db.prepare("SELECT path FROM projects ORDER BY sort_order, added_at").all() as { path: string }[];
+  return Promise.all(rows.map((r) => projectInfo(r.path)));
+}
+
+export async function projectInfo(p: string): Promise<ProjectInfo> {
+  return { id: encodeProjectId(p), path: p, name: path.basename(p) || p, exists: await isDir(p) };
+}
+
+async function isDir(p: string) {
+  try {
+    return (await fs.stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function pathExists(p: string) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function addProject(raw: string): Promise<ProjectInfo> {
+  const p = path.resolve(raw.trim());
+  if (!path.isAbsolute(raw.trim())) throw new Error("请填写绝对路径");
+  if (!(await isDir(p))) throw new Error("目录不存在");
+  db.prepare("INSERT OR IGNORE INTO projects (path, added_at) VALUES (?, ?)").run(p, Date.now());
+  return projectInfo(p);
+}
+
+export function removeProject(id: string) {
+  db.prepare("DELETE FROM projects WHERE path = ?").run(decodeProjectId(id));
+}
+
+/** Resolve a project id from the client to a registered project path. */
+export function projectPath(id: string): string {
+  const p = decodeProjectId(id);
+  const row = db.prepare("SELECT path FROM projects WHERE path = ?").get(p);
+  if (!row) throw new HttpError(404, "项目不存在");
+  return p;
+}
+
+export class HttpError extends Error {
+  constructor(
+    public status: 400 | 404 | 409,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+db.exec(`CREATE TABLE IF NOT EXISTS scheduled_sessions (session_id TEXT PRIMARY KEY, project_path TEXT NOT NULL, crons_json TEXT NOT NULL DEFAULT '[]', has_durable INTEGER NOT NULL DEFAULT 0)`);
+// Existing databases predate the cached task list and the durable-only marker.
+const scheduledColumns = db.prepare("PRAGMA table_info(scheduled_sessions)").all() as { name: string }[];
+if (!scheduledColumns.some((c) => c.name === "crons_json")) {
+  db.exec(`ALTER TABLE scheduled_sessions ADD COLUMN crons_json TEXT NOT NULL DEFAULT '[]'`);
+}
+if (!scheduledColumns.some((c) => c.name === "has_durable")) {
+  db.exec(`ALTER TABLE scheduled_sessions ADD COLUMN has_durable INTEGER NOT NULL DEFAULT 0`);
+}
+
+type ScheduledRow = { project_path: string; crons_json: string; has_durable: number };
+function scheduledRow(sessionId: string): ScheduledRow | undefined {
+  return db.prepare("SELECT project_path, crons_json, has_durable FROM scheduled_sessions WHERE session_id = ?").get(sessionId) as ScheduledRow | undefined;
+}
+
+function storedCrons(raw: string): CronInfo[] {
+  try {
+    const value = JSON.parse(raw) as unknown;
+    if (!Array.isArray(value)) return [];
+    return value.flatMap((c) => {
+      if (!c || typeof c !== "object") return [];
+      const v = c as Record<string, unknown>;
+      if (typeof v.id !== "string" || typeof v.schedule !== "string" || typeof v.prompt !== "string") return [];
+      return [{ id: v.id, schedule: v.schedule, recurring: v.recurring === true, prompt: v.prompt }];
+    });
+  } catch {
+    return [];
+  }
+}
+
+// ---------- live sessions ----------
+
+type ChangeListener = (projectId: string) => void;
+export type Activity = { projectId: string; sessionId: string; kind: "done" | "attention" | "error"; title: string };
+type ActivityListener = (a: Activity) => void;
+
+class SessionManager {
+  private live = new Map<string, LiveSession>();
+  private changeListeners = new Set<ChangeListener>();
+  private textListeners = new Set<(part: LiveTextPart) => void>();
+  private dropListeners = new Set<(sessionId: string) => void>();
+
+  onTextPart(fn: (part: LiveTextPart) => void) {
+    this.textListeners.add(fn);
+    return () => this.textListeners.delete(fn);
+  }
+
+  onSessionDropped(fn: (sessionId: string) => void) {
+    this.dropListeners.add(fn);
+    return () => this.dropListeners.delete(fn);
+  }
+
+  onSessionsChanged(fn: ChangeListener) {
+    this.changeListeners.add(fn);
+    return () => this.changeListeners.delete(fn);
+  }
+
+  private activityListeners = new Set<ActivityListener>();
+
+  onActivity(fn: ActivityListener) {
+    this.activityListeners.add(fn);
+    return () => this.activityListeners.delete(fn);
+  }
+
+  /** A turn ended or the session started waiting: tell everyone (notifications). */
+  /** Project each live session belongs to (its cwd may be a worktree of it). */
+  readonly projectOf = new Map<string, string>();
+
+  private transition(sessionId: string, projectPath: string, cwd: string, from: SessionState, to: SessionState, failed: boolean) {
+    const kind = to === "requires_action" ? "attention" : from !== "idle" && to === "idle" ? (failed ? "error" : "done") : undefined;
+    if (!kind) return;
+    void getSessionInfo(sessionId, { dir: cwd })
+      .catch(() => undefined)
+      .then((info) => {
+        const title = info?.customTitle ?? info?.summary ?? "会话";
+        for (const fn of this.activityListeners) fn({ projectId: encodeProjectId(projectPath), sessionId, kind, title });
+      });
+  }
+
+  notifyChanged(projectPath: string) {
+    const id = encodeProjectId(projectPath);
+    for (const fn of this.changeListeners) fn(id);
+  }
+
+  /** Stop a session's CLI process and forget it. Waits for the process so it cannot write afterwards. */
+  async drop(sessionId: string) {
+    for (const listener of this.dropListeners) listener(sessionId);
+    db.prepare("DELETE FROM scheduled_sessions WHERE session_id = ?").run(sessionId);
+    idecron.cancelSession(sessionId);
+    const s = this.live.get(sessionId);
+    if (!s) return;
+    // Stay registered (closed) until stopped, so a client can't create a fresh instance meanwhile.
+    await s.shutdown();
+    if (this.live.get(sessionId) === s) this.live.delete(sessionId);
+  }
+
+  get(sessionId: string): LiveSession | undefined {
+    return this.live.get(sessionId);
+  }
+
+  /** `projectPath` is the project; the CLI runs in the session's own cwd (a worktree of it, or the project). */
+  async getOrCreate(sessionId: string, projectPath: string, stillActive?: () => boolean): Promise<LiveSession> {
+    if (stillActive && !stillActive()) throw new Error("会话已删除或正在删除。");
+    let s = this.live.get(sessionId);
+    if (!s) {
+      // A stale URL must not reclaim a session moved by /cd before a server restart.
+      const scheduled = scheduledRow(sessionId);
+      const owner = viewRow(sessionId)?.project_path ?? scheduled?.project_path ?? projectPath;
+      const cwd = await sessionCwd(owner, sessionId);
+      if (stillActive && !stillActive()) throw new Error("会话已删除或正在删除。");
+      // A concurrent call may have created the session while we awaited the transcript.
+      s = this.live.get(sessionId);
+      if (s) return s;
+      s = new LiveSession(
+        sessionId,
+        cwd,
+        () => this.notifyChanged(this.projectOf.get(sessionId) ?? owner),
+        (from, to, turn) => !turn.silent && this.transition(sessionId, this.projectOf.get(sessionId) ?? owner, s!.cwd, from, to, turn.failed),
+        (part) => { for (const listener of this.textListeners) listener(part); },
+      );
+      this.projectOf.set(sessionId, owner);
+      // Scheduled tasks live in the CLI process: remember which sessions have them, so a server
+      // restart can resume those sessions (the CLI restores the tasks from the transcript).
+      s.onCronsChanged = (crons, hasDurable) => {
+        if (crons.length || hasDurable) {
+          db.prepare("INSERT OR REPLACE INTO scheduled_sessions (session_id, project_path, crons_json, has_durable) VALUES (?, ?, ?, ?)")
+            .run(sessionId, this.projectOf.get(sessionId) ?? owner, JSON.stringify(crons), hasDurable ? 1 : 0);
+        } else {
+          db.prepare("DELETE FROM scheduled_sessions WHERE session_id = ?").run(sessionId);
+        }
+      };
+      if (scheduled) {
+        // The task list survives a restart; the current process still has to confirm it.
+        const cached = storedCrons(scheduled.crons_json);
+        if (cached.length) {
+          s.hydrateCrons(cached, false);
+        } else if (scheduled.has_durable) {
+          // A durable-only row: if the file is gone, there is no scheduled work left to protect.
+          if (s.hasDurableWork()) {
+            s.hydrateCrons([], true, true);
+          } else {
+            db.prepare("DELETE FROM scheduled_sessions WHERE session_id = ?").run(sessionId);
+            s.hydrateCrons([], false);
+          }
+        } else {
+          // A legacy row with no cached list: session-level tasks may still be restored by resume.
+          s.hydrateCrons([], true);
+        }
+      } else {
+        // A durable file may be the only evidence that this session owns scheduled work.
+        s.noteScheduled();
+        if (s.hasDurableWork()) s.markStaleDurable();
+      }
+      this.live.set(sessionId, s);
+    }
+    return s;
+  }
+
+  /** CLI config changed on disk (settings pages): let every live session reload it. */
+  async configChanged() {
+    await Promise.all([...this.live.values()].map((s) => s.reloadConfig().catch(() => {})));
+  }
+
+  /** Sessions that are running or waiting for the user, across all projects. */
+  active() {
+    return [...this.live.values()].filter((s) => {
+      const snap = s.snapshot();
+      return s.state !== "idle" || snap.pending.length > 0 || snap.crons.length > 0;
+    });
+  }
+
+  /** After a restart: bring back sessions that had scheduled tasks, so the tasks keep firing. */
+  async resumeScheduled() {
+    const rows = db.prepare("SELECT session_id, project_path, crons_json, has_durable FROM scheduled_sessions").all() as (ScheduledRow & { session_id: string })[];
+    for (const r of rows) {
+      try {
+        // Rows written before has_durable existed may be durable-only. Mark them now so a later
+        // file deletion can clear the stale state instead of keeping the process alive forever.
+        if (!r.has_durable && storedCrons(r.crons_json).length === 0) {
+          try {
+            if (durableTasksForSession(await sessionCwd(r.project_path, r.session_id), r.session_id).length > 0) {
+              db.prepare("UPDATE scheduled_sessions SET has_durable = 1 WHERE session_id = ?").run(r.session_id);
+              r.has_durable = 1;
+            }
+          } catch {
+            // A broken cwd must not prevent the other scheduled sessions from resuming.
+          }
+        }
+        await (await this.getOrCreate(r.session_id, r.project_path)).wake();
+        console.log(`resumed scheduled session ${r.session_id}`);
+      } catch (err) {
+        console.warn(`could not resume scheduled session ${r.session_id}: ${err instanceof Error ? err.message : err}`);
+        db.prepare("DELETE FROM scheduled_sessions WHERE session_id = ?").run(r.session_id);
+      }
+    }
+  }
+
+  /** Periodically stop CLI processes of sessions that have been idle for a while. */
+  startReaper(maxIdleMs: number) {
+    const timer = setInterval(() => {
+      for (const s of this.live.values()) s.reapIfIdle(maxIdleMs);
+    }, 60_000);
+    timer.unref();
+  }
+
+  closeAll() {
+    for (const s of this.live.values()) s.close();
+  }
+}
+
+export const sessions = new SessionManager();
+
+/** Resolve identity before creating any live wrapper. Unknown IDs must never create sessions. */
+export async function resolveMessagingSession(id: string) {
+  const view = viewRow(id);
+  const scheduled = scheduledRow(id);
+  const live = sessions.get(id);
+  const liveProject = live ? sessions.projectOf.get(id) : undefined;
+  const knownProject = view?.project_path ?? scheduled?.project_path;
+  const candidate = async (projectPath: string, recordedCwd?: string) => {
+    const cwd = recordedCwd ?? await historyCwd(projectPath, id);
+    if (!(await isDir(cwd))) throw new Error("目标会话的工作目录不存在，无法投递消息。");
+    return { sessionId: id, projectPath, cwd };
+  };
+  if (knownProject) return candidate(knownProject);
+  // History reads can create an idle wrapper for arbitrary IDs. Such wrappers are
+  // not evidence of a real session; active first prompts, however, are.
+  if (live && liveProject) {
+    if (live.state !== "idle" || live.queuedMessageCount > 0) return candidate(liveProject, live.cwd);
+    const info = await getSessionInfo(id, { dir: await historyCwd(liveProject, id) }).catch(() => undefined);
+    if (info) return candidate(liveProject, info.cwd);
+  }
+  // Imported CLI sessions may have no IDE view row. Search managed projects and
+  // their transcript worktrees without reading whole histories or changing state.
+  const projects = db.prepare("SELECT path FROM projects ORDER BY sort_order, added_at").all() as { path: string }[];
+  for (const { path: project } of projects) {
+    const info = await getSessionInfo(id, { dir: project }).catch(() => undefined);
+    if (info) return candidate(project, info.cwd ?? project);
+    for (const cwd of await worktreeTranscriptCwds(project)) {
+      const info = await getSessionInfo(id, { dir: cwd }).catch(() => undefined);
+      if (info) return candidate(project, cwd);
+    }
+  }
+  return undefined;
+}
+
+configureSessionMessaging({
+  resolveExistingSession: resolveMessagingSession,
+  getOrCreate: (id, project, stillActive) => sessions.getOrCreate(id, project, stillActive),
+  assertAllowed: (id, action) => {
+    const row = db.prepare("SELECT write_enabled, btw_parent FROM session_view WHERE session_id = ?").get(id) as { write_enabled: number; btw_parent: string | null } | undefined;
+    if (row?.write_enabled === 0 || sessions.get(id)?.writeEnabled === false) throw new Error("只读会话不能发送跨会话消息或修改 Alias。");
+    if (action === "send" && row?.btw_parent) throw new Error("旁支会话不能发送跨会话消息。");
+  },
+});
+
+idecron.setDelivery({
+  canDeliver: (task) => {
+    const live = sessions.get(task.sessionId);
+    return !live || (live.state === "idle" && live.snapshot().pending.length === 0);
+  },
+  deliver: async (task) => (await sessions
+    .getOrCreate(task.sessionId, task.projectPath))
+    .sendScheduled(crypto.randomUUID(), task.prompt, task.mode),
+});
+idecron.onChange = (sessionId) => sessions.get(sessionId)?.emitCronList();
+
+// ---------- session list (CLI files are the source of truth) ----------
+
+type ViewRow = { session_id: string; pinned: number; archived: number; btw_parent: string | null };
+
+export async function listProjectSessions(projectPathStr: string): Promise<SessionListItem[]> {
+  // Worktrees are listed explicitly (M4); merging them here would also pull in the
+  // parent repo's sessions when a project is a subdirectory of another checkout.
+  const infos: Awaited<ReturnType<typeof listSessions>> = await listSessions({ dir: projectPathStr, includeWorktrees: false }).catch(() => []);
+  // Sessions in the project's own worktrees (<repo>/.claude/worktrees/<name>), listed with it.
+  const wts = await projectWorktrees(projectPathStr).catch(() => undefined);
+  // Plus worktrees that were cleaned up: their transcripts remain and stay reachable.
+  const wtCwds = new Set<string>();
+  for (const w of wts?.worktrees ?? []) if (await pathExists(w.cwd)) wtCwds.add(w.cwd);
+  for (const c of await worktreeTranscriptCwds(projectPathStr)) wtCwds.add(c);
+  for (const cwd of wtCwds) {
+    for (const info of await listSessions({ dir: cwd, includeWorktrees: false }).catch(() => [])) {
+      setSessionCwd(info.sessionId, cwd);
+      infos.push({ ...info, cwd });
+    }
+  }
+  const views = new Map(
+    (db.prepare("SELECT session_id, pinned, archived, btw_parent FROM session_view WHERE project_path = ?").all(projectPathStr) as ViewRow[]).map(
+      (r) => [r.session_id, r],
+    ),
+  );
+  const items: SessionListItem[] = [];
+  const seen = new Set<string>();
+  for (const info of infos) {
+    seen.add(info.sessionId);
+    const v = views.get(info.sessionId);
+    if (v?.btw_parent) continue;
+    const live = sessions.get(info.sessionId);
+    items.push({
+      id: info.sessionId,
+      title: info.customTitle ?? info.summary ?? "",
+      lastModified: info.lastModified,
+      createdAt: info.createdAt,
+      state: live?.state ?? "idle",
+      pinned: !!v?.pinned,
+      archived: !!v?.archived,
+      draft: false,
+      tag: info.tag,
+      forkedFrom: (await forkedFrom(projectPathStr, info.sessionId))?.sessionId,
+      needsAttention: live?.state === "requires_action",
+      ...worktreeFields(projectPathStr, info.cwd),
+    });
+  }
+  const cwds = draftCwds([...views.keys()]);
+  // Sessions created in the web UI that the CLI has not written yet.
+  for (const v of views.values()) {
+    if (seen.has(v.session_id) || v.btw_parent) continue;
+    const live = sessions.get(v.session_id);
+    const lastModified = live?.lastActivity ?? Date.now();
+    items.push({
+      id: v.session_id,
+      title: "",
+      lastModified,
+      state: live?.state ?? "idle",
+      pinned: !!v.pinned,
+      archived: !!v.archived,
+      draft: true,
+      needsAttention: live?.state === "requires_action",
+      ...worktreeFields(projectPathStr, cwds.get(v.session_id)),
+    });
+  }
+  items.sort((a, b) => Number(b.pinned) - Number(a.pinned) || b.lastModified - a.lastModified);
+  return items;
+}
+
+function worktreeFields(projectPathStr: string, cwd: string | undefined): { cwd?: string; worktree?: string } {
+  if (!cwd || cwd === projectPathStr) return {};
+  const name = worktreeName(cwd);
+  return name ? { cwd, worktree: name } : {};
+}
+
+export function createDraftSession(projectPathStr: string): string {
+  const id = crypto.randomUUID();
+  db.prepare("INSERT INTO session_view (session_id, project_path) VALUES (?, ?)").run(id, projectPathStr);
+  sessions.notifyChanged(projectPathStr);
+  return id;
+}
+
+/** The transcript path (and cwd) shown in the session info dialog; undefined for an unknown session. */
+export async function sessionFileInfo(sessionId: string, projectPathStr: string): Promise<SessionFileInfo | undefined> {
+  const dir = await historyCwd(projectPathStr, sessionId);
+  const file = (await sessionFile(dir, sessionId)) ?? null;
+  if (!file && !viewRow(sessionId)) return undefined;
+  return { id: sessionId, cwd: await sessionCwd(projectPathStr, sessionId), file };
+}
+
+export async function sessionHistory(sessionId: string, projectPathStr: string) {
+  const msgs = await rawHistory(sessionId, projectPathStr);
+  // getSessionMessages leaves out system/local_command (the output of /cost, /context…): put it back after its command.
+  const outputs = await localCommandOutputs(await historyCwd(projectPathStr, sessionId), sessionId);
+  if (outputs.size === 0) return msgs;
+  return (msgs as unknown[]).flatMap((m) => {
+    const extra = outputs.get((m as { uuid?: string }).uuid ?? "") ?? [];
+    return [m, ...extra.map((o) => ({ type: "system", subtype: "local_command", uuid: o.uuid, content: o.content, parent_tool_use_id: null }))];
+  });
+}
+
+export async function sessionHistoryPage(sessionId: string, projectPathStr: string, options: PageOptions = {}) {
+  const historyRevision = (await sessions.getOrCreate(sessionId, projectPathStr)).historyRevision;
+  const page = await historyPage(await sessionFile(await historyCwd(projectPathStr, sessionId), sessionId), { ...options, anchor: viewRow(sessionId)?.rewind_anchor });
+  return { ...page, historyRevision };
+}
+
+export async function sessionHistoryMessage(sessionId: string, projectPathStr: string, uuid: string) {
+  return historyMessage(await sessionFile(await historyCwd(projectPathStr, sessionId), sessionId), uuid, viewRow(sessionId)?.rewind_anchor);
+}
+
+export async function sessionReadPath(sessionId: string, projectPathStr: string, toolId: string) {
+  return historyReadPath(await sessionFile(await historyCwd(projectPathStr, sessionId), sessionId), toolId, viewRow(sessionId)?.rewind_anchor);
+}
+
+/** Transcript messages of the current branch, cut at a pending conversation rewind. */
+async function rawHistory(sessionId: string, projectPathStr: string) {
+  // Read from where the transcript lives (a worktree, possibly already removed), not the project root.
+  const msgs = await getSessionMessages(sessionId, { dir: await historyCwd(projectPathStr, sessionId) }).catch(() => []);
+  // A pending conversation rewind hides everything after its anchor until the next message.
+  const anchor = viewRow(sessionId)?.rewind_anchor;
+  if (anchor) {
+    const idx = msgs.findIndex((m) => m.uuid === anchor);
+    if (idx !== -1) return msgs.slice(0, idx + 1);
+  }
+  return msgs;
+}
+
+type FullViewRow = ViewRow & { project_path: string; rewind_anchor: string | null; rewind_text: string | null };
+
+function viewRow(sessionId: string): FullViewRow | undefined {
+  return db.prepare("SELECT * FROM session_view WHERE session_id = ?").get(sessionId) as FullViewRow | undefined;
+}
+
+function upsertView(sessionId: string, projectPathStr: string, patch: Partial<Record<"pinned" | "archived" | "ask_questions_enabled" | "write_enabled", number>>) {
+  db.prepare("INSERT OR IGNORE INTO session_view (session_id, project_path) VALUES (?, ?)").run(sessionId, projectPathStr);
+  for (const [k, v] of Object.entries(patch)) db.prepare(`UPDATE session_view SET ${k} = ? WHERE session_id = ?`).run(v, sessionId);
+}
+
+export async function updateSession(sessionId: string, projectPathStr: string, patch: { title?: string; pinned?: boolean; archived?: boolean; askQuestionsEnabled?: boolean; writeEnabled?: boolean }) {
+  if (patch.title !== undefined) {
+    const title = patch.title.trim();
+    if (!title) throw new HttpError(400, "标题不能为空");
+    const renamedLive = await sessions.get(sessionId)?.renameLive(title).catch(() => false);
+    // The transcript may live in a worktree of the project, not under the project root.
+    if (!renamedLive) await renameSession(sessionId, title, { dir: await historyCwd(projectPathStr, sessionId) });
+  }
+  const view: Partial<Record<"pinned" | "archived" | "ask_questions_enabled" | "write_enabled", number>> = {};
+  if (patch.pinned !== undefined) view.pinned = patch.pinned ? 1 : 0;
+  if (patch.archived !== undefined) view.archived = patch.archived ? 1 : 0;
+  if (patch.askQuestionsEnabled !== undefined) view.ask_questions_enabled = patch.askQuestionsEnabled ? 1 : 0;
+  if (patch.writeEnabled !== undefined) view.write_enabled = patch.writeEnabled ? 1 : 0;
+  if (Object.keys(view).length) upsertView(sessionId, projectPathStr, view);
+  if (patch.askQuestionsEnabled !== undefined) sessions.get(sessionId)?.setAskQuestionsEnabled(patch.askQuestionsEnabled);
+  if (patch.writeEnabled !== undefined) sessions.get(sessionId)?.setWriteEnabled(patch.writeEnabled);
+  sessions.notifyChanged(projectPathStr);
+}
+
+export async function removeSession(sessionId: string, projectPathStr: string) {
+  const finishDeletion = beginSessionDeletion(sessionId);
+  try {
+    await sessions.drop(sessionId);
+    const cwd = await historyCwd(projectPathStr, sessionId);
+    // Metadata may omit a transcript without a usable summary. Delete by file
+    // existence, and keep aliases if the CLI deletion fails. Drafts have no file.
+    if (await sessionFile(cwd, sessionId, true)) await deleteSession(sessionId, { dir: cwd });
+    if (await sessionFile(cwd, sessionId, true)) throw new Error("会话记录仍然存在，未完成删除。");
+    db.prepare("DELETE FROM session_view WHERE session_id = ?").run(sessionId);
+    removeSessionAliases(sessionId);
+    sessions.projectOf.delete(sessionId);
+    sessions.notifyChanged(projectPathStr);
+  } finally { finishDeletion(); }
+}
+
+/** The transcript record just before a user message: the last record of the previous turn. */
+async function recordBefore(sessionId: string, projectPathStr: string, userUuid: string) {
+  const msgs = await rawHistory(sessionId, projectPathStr);
+  const idx = msgs.findIndex((m) => m.uuid === userUuid);
+  if (idx === -1) throw new HttpError(404, "找不到这条消息（可能还没写入会话文件）");
+  const msg = msgs[idx]!.message as { content?: unknown };
+  const content = msg?.content;
+  const text =
+    typeof content === "string"
+      ? content
+      : Array.isArray(content)
+        ? content.filter((b: { type?: string }) => b?.type === "text").map((b: { text?: string }) => b.text ?? "").join("\n")
+        : "";
+  return { before: msgs[idx - 1]?.uuid, last: msgs[msgs.length - 1]?.uuid, text };
+}
+
+/** Fork into a new independent session. `beforeUuid` = fork from just before that user message; omitted = whole session. */
+export async function forkAt(sessionId: string, projectPathStr: string, beforeUuid?: string): Promise<string> {
+  let upTo: string | undefined;
+  if (beforeUuid) {
+    const r = await recordBefore(sessionId, projectPathStr, beforeUuid);
+    if (!r.before) throw new HttpError(400, "第一条消息之前没有内容可以 fork，请直接新建会话");
+    upTo = r.before;
+  }
+  // The fork is written next to its source (the project, or the worktree the source runs in).
+  const { sessionId: id } = await forkSession(sessionId, { dir: await historyCwd(projectPathStr, sessionId), ...(upTo ? { upToMessageId: upTo } : {}) });
+  sessions.notifyChanged(projectPathStr);
+  return id;
+}
+
+export type RewindMode = "conversation" | "code" | "both";
+
+export async function rewind(sessionId: string, projectPathStr: string, userUuid: string, mode: RewindMode, dryRun: boolean) {
+  const live = await sessions.getOrCreate(sessionId, projectPathStr);
+  const { before, text } = await recordBefore(sessionId, projectPathStr, userUuid);
+  const result: { text: string; rewindId?: string; files?: Awaited<ReturnType<LiveSession["rewindFiles"]>>; newSessionId?: string } = { text };
+  if (mode !== "conversation") result.files = await live.rewindFiles(userUuid, dryRun);
+  if (dryRun || mode === "code") return result;
+  if (before) {
+    result.rewindId = await live.rewindConversation(projectPathStr, before, text);
+  } else {
+    // Rewinding to the very first message: nothing to keep, so continue in a fresh session (the old one stays).
+    result.newSessionId = createDraftSession(projectPathStr);
+    result.rewindId = crypto.randomUUID();
+  }
+  return result;
+}
+
+export function pendingRewindText(sessionId: string): string | undefined {
+  const row = viewRow(sessionId);
+  return row?.rewind_anchor ? (row.rewind_text ?? "") : undefined;
+}
+
+export function pendingRewindDraft(sessionId: string): { rewindText: string | null; rewindId: string | null } {
+  const row = db.prepare("SELECT rewind_anchor, rewind_text, rewind_id FROM session_view WHERE session_id = ?").get(sessionId) as { rewind_anchor: string | null; rewind_text: string | null; rewind_id: string | null } | undefined;
+  return row?.rewind_anchor ? { rewindText: row.rewind_text ?? "", rewindId: row.rewind_id ?? row.rewind_anchor } : { rewindText: null, rewindId: null };
+}
+
+export async function exportSession(sessionId: string, projectPathStr: string) {
+  return (await sessions.getOrCreate(sessionId, projectPathStr)).exportText();
+}
+
+export type OverviewItem = {
+  projectId: string;
+  projectName: string;
+  sessionId: string;
+  title: string;
+  state: SessionState;
+  waitingFor: ("ask" | "plan")[];
+  crons: number;
+  /** Task IDs shown for this session; the overview total dedupes shared project tasks. */
+  cronIds: string[];
+  tasks: number;
+};
+
+/** The "running overview": every session that is busy, waiting for the user, or has scheduled work. */
+export async function overview(): Promise<OverviewItem[]> {
+  const out: OverviewItem[] = [];
+  const managed = new Set((db.prepare("SELECT path FROM projects").all() as { path: string }[]).map((row) => row.path));
+  for (const s of sessions.active()) {
+    const project = sessions.projectOf.get(s.sessionId) ?? s.cwd;
+    if (!managed.has(project)) continue;
+    const projectId = encodeProjectId(project);
+    const snap = s.snapshot();
+    const info = await getSessionInfo(s.sessionId, { dir: s.cwd }).catch(() => undefined);
+    out.push({
+      projectId,
+      projectName: path.basename(project),
+      sessionId: s.sessionId,
+      title: info?.customTitle ?? info?.summary ?? "新会话",
+      state: snap.state,
+      waitingFor: snap.pending.map((p) => p.kind),
+      crons: snap.crons.length,
+      cronIds: snap.crons.map((c) => `${projectId}:${c.id}`),
+      tasks: snap.tasks.filter((t) => t.status === "running").length,
+    });
+  }
+  const rank = (o: OverviewItem) => (o.waitingFor.length || o.state === "requires_action" ? 0 : o.state === "running" ? 1 : 2);
+  return out.sort((a, b) => rank(a) - rank(b));
+}
+
+/** /cd: the session continues in another directory, which becomes (or already is) a project. */
+export async function changeSessionDir(sessionId: string, projectPathStr: string, dir: string) {
+  const target = (await addProject(dir)).path;
+  const live = await sessions.getOrCreate(sessionId, projectPathStr);
+  await live.changeDir(target, () => {
+    db.exec("BEGIN");
+    try {
+      setSessionCwd(sessionId, target);
+      db.prepare("INSERT INTO session_view (session_id, project_path) VALUES (?, ?) ON CONFLICT(session_id) DO UPDATE SET project_path = excluded.project_path").run(sessionId, target);
+      db.prepare("UPDATE scheduled_sessions SET project_path = ? WHERE session_id = ?").run(target, sessionId);
+      db.prepare("UPDATE idecron_schedules SET project_path = ? WHERE session_id = ?").run(target, sessionId);
+      db.exec("COMMIT");
+    } catch (err) {
+      db.exec("ROLLBACK");
+      throw err;
+    }
+    sessions.projectOf.set(sessionId, target);
+  });
+  sessions.notifyChanged(projectPathStr);
+  sessions.notifyChanged(target);
+  return { projectId: encodeProjectId(target) };
+}