minimal-agent 0.10.0 → 0.12.0

package/src/context/sessionPath.ts

@@ -0,0 +1,206 @@
+/**
+ * ============================================================
+ *  src/context/sessionPath.ts —— 按目录隔离的会话文件路径
+ * ------------------------------------------------------------
+ *  做的事：
+ *    新会话使用 Workspace Index 的稳定 workspaceId，写入
+ *    ~/.minimal-agent/sessions/workspace-<id>--<sessionId>.json。
+ *    因此外接盘挂载名、盘符或 symlink 表达变化时仍指向同一份历史。
+ *
+ *  旧命名规则（路径索引时代，仍用于兼容迁移）：
+ *    <sanitized-path>-<6-hex-hash>--<sessionId>.json
+ *      sanitized：路径归一化后只保留 [a-z0-9-]，最长 80 字符
+ *      hash    ：原始路径 sha1 前 6 位，防 sanitize 后碰撞
+ *      sessionId：v2 多 session 支持；默认 'default'
+ *
+ *    resolveSessionFile() 会验证当前路径及 Workspace Index 中的历史别名，
+ *    首次打开旧文件时复制到稳定文件名；旧文件保留作为恢复依据。
+ *
+ *  迁移：
+ *    旧版 ~/.minimal-agent/last-context.json 启动时一次性 rename 到
+ *    当前 cwd 对应的会话文件。失败静默——丢迁移好过崩进程。
+ * ============================================================
+ */
+
+import { createHash } from 'node:crypto';
+import { constants, readFileSync, realpathSync } from 'node:fs';
+import { chmod, copyFile, mkdir, rename, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { agentStateDir } from './agentHome.js';
+
+const DEFAULT_SESSION_ID = 'default';
+const SESSION_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/;
+
+interface IndexedWorkspaceIdentity {
+  id: string;
+  canonicalPath: string;
+  displayPath?: string;
+  pathAliases?: string[];
+}
+
+function comparablePath(path: string): string {
+  try { return realpathSync(resolve(path)).replace(/\\/g, '/').toLowerCase(); }
+  catch { return resolve(path).replace(/\\/g, '/').toLowerCase(); }
+}
+
+function mountStablePath(path: string): string {
+  return comparablePath(path).replace(/^\/volumes\/([^/]+?) \d+(\/|$)/, '/volumes/$1$2');
+}
+
+function indexedWorkspaceFor(cwd: string): IndexedWorkspaceIdentity | null {
+  try {
+    const parsed = JSON.parse(readFileSync(join(agentStateDir(), 'workspace-index.json'), 'utf8')) as {
+      workspaces?: IndexedWorkspaceIdentity[];
+    };
+    const target = comparablePath(cwd);
+    const mountTarget = mountStablePath(cwd);
+    return parsed.workspaces?.find((workspace) => [
+      workspace.canonicalPath,
+      workspace.displayPath,
+      ...(workspace.pathAliases ?? []),
+    ].some((path) => typeof path === 'string'
+      && (comparablePath(path) === target || mountStablePath(path) === mountTarget))) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function stableSessionFileFor(workspaceId: string, sessionId: string): string {
+  const safeWorkspaceId = workspaceId.replace(/[^a-zA-Z0-9._-]/g, '');
+  if (!safeWorkspaceId) throw new Error('workspace id 无效');
+  return join(agentStateDir(), 'sessions', `workspace-${safeWorkspaceId}--${validateSessionId(sessionId)}.json`);
+}
+
+/** 仅用于旧历史识别和迁移；新调用应使用 sessionFileFor。 */
+export function legacyPathSessionFileFor(cwd: string, sessionId: string = DEFAULT_SESSION_ID): string {
+  const safeSessionId = validateSessionId(sessionId);
+  const normalized = resolve(cwd).replace(/\\/g, '/').toLowerCase();
+  const sanitized = normalized
+    .replace(/:/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+  const hash = createHash('sha1').update(normalized).digest('hex').slice(0, 6);
+  return join(agentStateDir(), 'sessions', `${sanitized}-${hash}--${safeSessionId}.json`);
+}
+
+export function validateSessionId(sessionId: string): string {
+  const value = sessionId.trim();
+  if (!SESSION_ID_RE.test(value) || value === '.' || value === '..' || value.includes('..')) {
+    throw new Error('session id 只能包含字母、数字、点、下划线和短横线，且长度不超过 80');
+  }
+  return value;
+}
+
+/**
+ * 把 cwd + sessionId 编码成会话文件绝对路径。
+ *
+ * @param cwd 工作目录
+ * @param sessionId 多 session 支持的 id；缺省 'default'
+ *
+ * 注意：'default' 调用走新格式 `<base>--default.json`。如果磁盘上只有
+ * 旧格式 `<base>.json`（v1 历史文件），需要用 resolveSessionFile()
+ * 拿到实际存在的路径用于 load。
+ */
+export function sessionFileFor(
+  cwd: string,
+  sessionId: string = DEFAULT_SESSION_ID,
+): string {
+  const safeSessionId = validateSessionId(sessionId);
+  const workspace = indexedWorkspaceFor(cwd);
+  return workspace
+    ? stableSessionFileFor(workspace.id, safeSessionId)
+    : legacyPathSessionFileFor(cwd, safeSessionId);
+}
+
+/** 旧格式（v1，不带 `--<id>` 后缀）—— 仅 'default' session 可能存在 */
+function legacySessionFileFor(cwd: string): string {
+  const normalized = resolve(cwd).replace(/\\/g, '/').toLowerCase();
+  const sanitized = normalized
+    .replace(/:/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+  const hash = createHash('sha1').update(normalized).digest('hex').slice(0, 6);
+  return join(
+    agentStateDir(),
+    'sessions',
+    `${sanitized}-${hash}.json`,
+  );
+}
+
+/**
+ * 解析 cwd + sessionId 对应的实际存在的会话文件路径。
+ *
+ *  - 新格式（带 `--<id>`）存在 → 返回新路径
+ *  - 仅 sessionId='default' 且新路径不存在但旧路径（不带 `--`）存在 → 返回旧路径
+ *  - 都不存在 → 返回新路径（让调用方按新格式 create）
+ */
+export async function resolveSessionFile(
+  cwd: string,
+  sessionId: string = DEFAULT_SESSION_ID,
+): Promise<string> {
+  const fresh = sessionFileFor(cwd, sessionId);
+  try {
+    await stat(fresh);
+    return fresh;
+  } catch {
+    // 新路径不存在
+  }
+  const workspace = indexedWorkspaceFor(cwd);
+  const aliases = workspace
+    ? [cwd, workspace.canonicalPath, workspace.displayPath, ...(workspace.pathAliases ?? [])]
+    : [cwd];
+  const candidates = [...new Set(aliases.filter((value): value is string => typeof value === 'string'))]
+    .flatMap((path) => [
+      legacyPathSessionFileFor(path, sessionId),
+      ...(sessionId === DEFAULT_SESSION_ID ? [legacySessionFileFor(path)] : []),
+    ]);
+  for (const legacy of candidates) {
+    try {
+      await stat(legacy);
+    } catch {
+      continue;
+    }
+    if (legacy !== fresh && workspace) {
+      try {
+        await mkdir(dirname(fresh), { recursive: true });
+        await copyFile(legacy, fresh, constants.COPYFILE_EXCL).catch(async (error) => {
+          if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        });
+        await chmod(fresh, 0o600).catch(() => {});
+        return fresh;
+      } catch {
+        // Migration is an optimization. The verified legacy history remains
+        // authoritative when the stable destination cannot be written.
+        return legacy;
+      }
+    }
+    return legacy;
+  }
+  return fresh;
+}
+
+/**
+ * 一次性把旧版 ~/.minimal-agent/last-context.json 迁到当前 cwd 对应的
+ * 会话文件。
+ *
+ * 静默策略：
+ *  - 旧文件不存在 → 直接返回
+ *  - rename 失败（目标已存在 / 权限等）→ 忽略，旧文件原位等下次启动
+ */
+export async function migrateLegacyContext(cwd: string): Promise<void> {
+  const legacy = join(agentStateDir(), 'last-context.json');
+  try {
+    await stat(legacy);
+  } catch {
+    return;
+  }
+  const target = sessionFileFor(cwd);
+  try {
+    await mkdir(dirname(target), { recursive: true });
+    await rename(legacy, target);
+  } catch {
+    // 静默
+  }
+}

package/src/context/sessionRegistry.js

@@ -273,7 +273,7 @@ export async function listSessionSummaries(cwd) {
         if (!ids.includes(session.id))
             ids.push(session.id);
     }
-    return Promise.all(ids.map(async (id) => {
+    return (await Promise.all(ids.map(async (id) => {
         const existing = group[id] ?? indexedById.get(id);
         let modified = existing?.updatedAt ?? Date.now();
         try {
@@ -288,7 +288,13 @@ export async function listSessionSummaries(cwd) {
                 createdAt: modified,
                 updatedAt: modified,
             };
-    }));
+    }))).sort((a, b) => {
+        if (a.id === 'default')
+            return -1;
+        if (b.id === 'default')
+            return 1;
+        return b.updatedAt - a.updatedAt;
+    });
 }
 async function createSessionUnlocked(cwd, options) {
     const id = validateSessionId(options.id ?? randomUUID());

package/src/context/sessionRegistry.ts

@@ -0,0 +1,414 @@
+/**
+ * ============================================================
+ *  src/context/sessionRegistry.ts —— 同 cwd 多 session 注册表
+ * ------------------------------------------------------------
+ *  做的事：
+ *    一个工作目录下可以有多个并行 session（id = 任意字符串），
+ *    每次只激活一个。active 信息存 ~/.minimal-agent/active-sessions.json，
+ *    键是 cwd 的 sha1[:12]，值是当前激活的 session id 字符串。
+ *
+ *  文件路径：
+ *    <MINIMAL_AGENT_HOME ?? ~>/.minimal-agent/active-sessions.json
+ *    <MINIMAL_AGENT_HOME ?? ~>/.minimal-agent/sessions/<cwd-hash>--<id>.json
+ *      （新格式；旧格式 <cwd-hash>.json 视作 id='default' 兼容）
+ *
+ *  抉择：
+ *    - active 文件 atomic write（写 .tmp + rename）—— 防止跨进程并发写时部分写入
+ *    - sessionId 为字符串，'default' 是约定的默认值（无 active 时返回它）
+ *    - listSessions 同时扫新旧格式，保证迁移期不丢
+ * ============================================================
+ */
+
+import { createHash, randomUUID } from 'node:crypto';
+import { basename } from 'node:path';
+import { copyFile, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveSessionFile, sessionFileFor, validateSessionId } from './sessionPath.js';
+import { workspaceIndexService } from './workspaceIndex.js';
+export { validateSessionId } from './sessionPath.js';
+
+/** 解析根目录，支持 MINIMAL_AGENT_HOME 测试覆盖 */
+function agentHome(): string {
+  return process.env.MINIMAL_AGENT_HOME ?? homedir();
+}
+
+function agentDir(): string {
+  return join(agentHome(), '.minimal-agent');
+}
+
+function activeFilePath(): string {
+  return join(agentDir(), 'active-sessions.json');
+}
+
+function sessionsDirPath(): string {
+  return join(agentDir(), 'sessions');
+}
+
+function cwdHash(cwd: string): string {
+  return createHash('sha1').update(cwd).digest('hex').slice(0, 12);
+}
+
+interface ActiveMap {
+  [cwdHash: string]: string;
+}
+
+export interface SessionSummary {
+  id: string;
+  title: string;
+  createdAt: number;
+  updatedAt: number;
+  lastMessagePreview?: string;
+  /** Session 级模型绑定；缺省时回退到全局基座模型。 */
+  modelId?: string;
+}
+
+interface SessionMetadataFile {
+  [cwdHash: string]: Record<string, SessionSummary>;
+}
+
+function metadataFilePath(): string {
+  return join(agentDir(), 'session-metadata.json');
+}
+
+async function loadMetadata(): Promise<SessionMetadataFile> {
+  try {
+    const value = JSON.parse(await readFile(metadataFilePath(), 'utf8')) as unknown;
+    return value && typeof value === 'object' && !Array.isArray(value) ? value as SessionMetadataFile : {};
+  } catch {
+    return {};
+  }
+}
+
+async function saveMetadata(value: SessionMetadataFile): Promise<void> {
+  await mkdir(agentDir(), { recursive: true });
+  const target = metadataFilePath();
+  const tmp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, JSON.stringify(value, null, 2), { encoding: 'utf8', mode: 0o600 });
+    await rename(tmp, target);
+  } finally {
+    await unlink(tmp).catch(() => {});
+  }
+}
+
+async function loadActiveMap(): Promise<ActiveMap> {
+  try {
+    const raw = await readFile(activeFilePath(), 'utf8');
+    const data = JSON.parse(raw);
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+      return data as ActiveMap;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+async function saveActiveMap(map: ActiveMap): Promise<void> {
+  await mkdir(agentDir(), { recursive: true });
+  const target = activeFilePath();
+  const tmp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, JSON.stringify(map), { encoding: 'utf8', mode: 0o600 });
+    await rename(tmp, target);
+  } finally {
+    await unlink(tmp).catch(() => {});
+  }
+}
+
+/**
+ * 同进程内的串行互斥队列（`session-metadata.json` / `active-sessions.json` 都是全局
+ * 单文件，按 cwdHash 分组——两个并发调用方 load→改→save 会互相覆盖丢更新）。
+ * 照抄 `plugins/cron-runner/src/store.ts` 的 `enqueueMutation` 模式。
+ *
+ * 同进程先排队，队首操作再取得跨进程目录锁。CLI、Desktop Runtime 与 Cron 可以同时
+ * 使用同一个 MINIMAL_AGENT_HOME；仅靠 rename 只能避免半写文件，不能避免两个进程
+ * load→改→save 时后写覆盖先写。目录创建在各平台都是原子的，适合做短临界区互斥。
+ *
+ * 下面所有导出的可变函数（setActiveSession/createSession/updateSessionMetadata/
+ * copySession/deleteSession）都必须整体包一层 enqueueMutation；内部若需要调用
+ * 另一个可变操作的逻辑，必须调用其 *Unlocked 版本而不是导出版本——否则内层调用会
+ * 排到同一队列的外层调用之后，外层等内层、内层等外层排到自己，死锁。
+ */
+let mutationQueue: Promise<void> = Promise.resolve();
+const LOCK_STALE_MS = 120_000;
+const LOCK_WAIT_MS = 15_000;
+
+function lockDirPath(): string {
+  return join(agentDir(), 'session-registry.lock');
+}
+
+function processIsAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+async function acquireRegistryLock(): Promise<() => Promise<void>> {
+  const lockDir = lockDirPath();
+  const ownerFile = join(lockDir, 'owner.json');
+  const startedAt = Date.now();
+  await mkdir(agentDir(), { recursive: true, mode: 0o700 });
+  while (true) {
+    try {
+      await mkdir(lockDir, { mode: 0o700 });
+      await writeFile(ownerFile, JSON.stringify({ pid: process.pid, createdAt: Date.now() }), {
+        encoding: 'utf8',
+        mode: 0o600,
+      });
+      return async () => { await rm(lockDir, { recursive: true, force: true }); };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      let stale = false;
+      try {
+        const [ownerRaw, info] = await Promise.all([readFile(ownerFile, 'utf8'), stat(lockDir)]);
+        const owner = JSON.parse(ownerRaw) as { pid?: number; createdAt?: number };
+        stale = typeof owner.pid === 'number'
+          ? !processIsAlive(owner.pid)
+          : Date.now() - info.mtimeMs > LOCK_STALE_MS;
+      } catch {
+        try {
+          stale = Date.now() - (await stat(lockDir)).mtimeMs > LOCK_STALE_MS;
+        } catch {
+          continue;
+        }
+      }
+      if (stale) {
+        await rm(lockDir, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() - startedAt > LOCK_WAIT_MS) {
+        throw new Error('等待 Session 注册表锁超时，请确认没有异常残留的 minimal-agent 进程');
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+}
+
+function enqueueMutation<T>(mutate: () => Promise<T>): Promise<T> {
+  const run = async (): Promise<T> => {
+    const release = await acquireRegistryLock();
+    try {
+      return await mutate();
+    } finally {
+      await release();
+    }
+  };
+  const operation = mutationQueue.then(run, run);
+  mutationQueue = operation.then(() => undefined, () => undefined);
+  return operation;
+}
+
+/**
+ * 获取当前 cwd 的激活 session id。
+ * 无记录 → 返回 'default'。
+ */
+export async function getActiveSession(cwd: string): Promise<string> {
+  const workspace = await workspaceIndexService.findByPath(cwd).catch(() => null);
+  if (workspace?.activeSessionId) {
+    try { return validateSessionId(workspace.activeSessionId); } catch { /* fall through */ }
+  }
+  const map = await loadActiveMap();
+  try { return validateSessionId(map[cwdHash(cwd)] ?? 'default'); }
+  catch { return 'default'; }
+}
+
+async function setActiveSessionUnlocked(cwd: string, sessionId: string): Promise<void> {
+  const id = validateSessionId(sessionId);
+  const map = await loadActiveMap();
+  map[cwdHash(cwd)] = id;
+  await saveActiveMap(map);
+  // 索引是自愈便利层：权威存储（active-sessions.json）已落盘，索引写失败
+  // （锁超时/磁盘错误）绝不能反过来打断会话切换——尽力而为，下次 reconcile 自愈。
+  await workspaceIndexService.setActive(cwd, id).catch(async () => {
+    await workspaceIndexService.recordPendingMutation({ type: 'active', path: cwd, sessionId: id }).catch(() => {});
+  });
+}
+
+/**
+ * 设置当前 cwd 的激活 session id。
+ *
+ * 写入策略：先写 <target>.tmp，再原子 rename 到 target；
+ * 即使被中断也只会留临时文件，不破坏 target。
+ */
+export async function setActiveSession(
+  cwd: string,
+  sessionId: string,
+): Promise<void> {
+  return enqueueMutation(() => setActiveSessionUnlocked(cwd, sessionId));
+}
+
+/**
+ * 列出当前 cwd 下所有真实存在的 session id。
+ *
+ * 扫描规则：
+ *  - 新格式 `<hash>--<id>.json` → 提取 id
+ *  - 旧格式 `<hash>.json` → 视作 'default'
+ *  - default 只有存在历史文件或元数据时才返回；CLI 的隐式 default 写入兼容不变
+ */
+export async function listSessions(cwd: string): Promise<string[]> {
+  const dir = sessionsDirPath();
+  const defaultName = basename(sessionFileFor(cwd, 'default'));
+  const prefix = defaultName.slice(0, -'default.json'.length);
+  let names: string[] = [];
+  try { names = await readdir(dir); } catch { /* a new workspace has no files yet */ }
+  const ids = names
+    .filter((name) => name.startsWith(prefix) && name.endsWith('.json') && !name.endsWith('.tmp.json'))
+    .map((name) => name.slice(prefix.length, -'.json'.length))
+    .filter((id) => {
+      try { validateSessionId(id); return true; } catch { return false; }
+    });
+  const metadata = await loadMetadata();
+  ids.push(...Object.keys(metadata[cwdHash(cwd)] ?? {}).filter((id) => !ids.includes(id)));
+  if (!ids.includes('default')) {
+    try {
+      await stat(await resolveSessionFile(cwd, 'default'));
+      ids.push('default');
+    } catch {
+      // A missing implicit default is not a visible conversation.
+    }
+  }
+  const unique = [...new Set(ids.filter((id) => id !== 'default'))].sort();
+  return ids.includes('default') ? ['default', ...unique] : unique;
+}
+
+export async function listSessionSummaries(cwd: string): Promise<SessionSummary[]> {
+  const ids = await listSessions(cwd);
+  const metadata = await loadMetadata();
+  const group = metadata[cwdHash(cwd)] ?? {};
+  const indexed = await workspaceIndexService.findByPath(cwd).catch(() => null);
+  const indexedById = new Map((indexed?.sessions ?? []).map((session) => [session.id, session]));
+  for (const session of indexed?.sessions ?? []) {
+    if (!ids.includes(session.id)) ids.push(session.id);
+  }
+  return (await Promise.all(ids.map(async (id) => {
+    const existing = group[id] ?? indexedById.get(id);
+    let modified = existing?.updatedAt ?? Date.now();
+    try { modified = (await stat(await resolveSessionFile(cwd, id))).mtimeMs; } catch { /* metadata-only draft */ }
+    return existing
+      ? { ...existing, updatedAt: Math.max(existing.updatedAt, modified) }
+      : {
+          id,
+          title: id === 'default' ? '默认会话' : id,
+          createdAt: modified,
+          updatedAt: modified,
+        };
+  }))).sort((a, b) => {
+    if (a.id === 'default') return -1;
+    if (b.id === 'default') return 1;
+    return b.updatedAt - a.updatedAt;
+  });
+}
+
+async function createSessionUnlocked(
+  cwd: string,
+  options: { id?: string; title?: string; modelId?: string },
+): Promise<SessionSummary> {
+  const id = validateSessionId(options.id ?? randomUUID());
+  const metadata = await loadMetadata();
+  const hash = cwdHash(cwd);
+  const group = metadata[hash] ?? {};
+  if (group[id] || (await listSessions(cwd)).includes(id)) throw new Error(`session 已存在: ${id}`);
+  const now = Date.now();
+  const summary = {
+    id,
+    title: options.title?.trim() || '新会话',
+    createdAt: now,
+    updatedAt: now,
+    ...(options.modelId?.trim() ? { modelId: options.modelId.trim() } : {}),
+  };
+  metadata[hash] = { ...group, [id]: summary };
+  await saveMetadata(metadata);
+  // 权威元数据已落盘；索引只是便利层，失败不阻断建会话（见 setActiveSessionUnlocked）。
+  await workspaceIndexService.touchSession(cwd, summary).catch(async () => {
+    await workspaceIndexService.recordPendingMutation({ type: 'touch', path: cwd, session: summary }).catch(() => {});
+  });
+  return summary;
+}
+
+export async function createSession(
+  cwd: string,
+  options: { id?: string; title?: string; modelId?: string } = {},
+): Promise<SessionSummary> {
+  return enqueueMutation(() => createSessionUnlocked(cwd, options));
+}
+
+async function updateSessionMetadataUnlocked(
+  cwd: string,
+  sessionId: string,
+  patch: { title?: string; lastMessagePreview?: string; modelId?: string | null },
+): Promise<SessionSummary> {
+  const id = validateSessionId(sessionId);
+  const metadata = await loadMetadata();
+  const hash = cwdHash(cwd);
+  const group = metadata[hash] ?? {};
+  const now = Date.now();
+  const previous = group[id] ?? { id, title: id === 'default' ? '默认会话' : id, createdAt: now, updatedAt: now };
+  const next = {
+    ...previous,
+    ...(patch.title !== undefined ? { title: patch.title.trim() || previous.title } : {}),
+    ...(patch.lastMessagePreview !== undefined ? { lastMessagePreview: patch.lastMessagePreview.slice(0, 240) } : {}),
+    ...(patch.modelId === null ? { modelId: undefined } : patch.modelId !== undefined ? { modelId: patch.modelId.trim() } : {}),
+    updatedAt: now,
+  };
+  metadata[hash] = { ...group, [id]: next };
+  await saveMetadata(metadata);
+  // 权威元数据已落盘；索引只是便利层，失败不阻断元数据更新。
+  await workspaceIndexService.touchSession(cwd, next).catch(async () => {
+    await workspaceIndexService.recordPendingMutation({ type: 'touch', path: cwd, session: next }).catch(() => {});
+  });
+  return next;
+}
+
+export async function updateSessionMetadata(
+  cwd: string,
+  sessionId: string,
+  patch: { title?: string; lastMessagePreview?: string; modelId?: string | null },
+): Promise<SessionSummary> {
+  return enqueueMutation(() => updateSessionMetadataUnlocked(cwd, sessionId, patch));
+}
+
+export async function copySession(cwd: string, sourceSessionId: string, title?: string): Promise<SessionSummary> {
+  return enqueueMutation(async () => {
+    const sourceId = validateSessionId(sourceSessionId);
+    const source = (await listSessionSummaries(cwd)).find((session) => session.id === sourceId);
+    const target = await createSessionUnlocked(cwd, { title: title ?? '会话副本', ...(source?.modelId ? { modelId: source.modelId } : {}) });
+    try {
+      await mkdir(sessionsDirPath(), { recursive: true });
+      await copyFile(await resolveSessionFile(cwd, sourceId), sessionFileFor(cwd, target.id));
+    } catch {
+      // An empty source session is still valid; its metadata is the useful clone.
+    }
+    return target;
+  });
+}
+
+export async function deleteSession(cwd: string, sessionId: string): Promise<void> {
+  return enqueueMutation(async () => {
+    const id = validateSessionId(sessionId);
+    if (id === 'default') throw new Error('默认会话不能删除，可以归档后清空');
+    await unlink(await resolveSessionFile(cwd, id)).catch(() => {});
+    const metadata = await loadMetadata();
+    const hash = cwdHash(cwd);
+    if (metadata[hash]) {
+      delete metadata[hash][id];
+      await saveMetadata(metadata);
+    }
+    // 权威元数据已删除；索引只是便利层，失败不阻断删会话。
+    await workspaceIndexService.removeSession(cwd, id).catch(async () => {
+      await workspaceIndexService.recordPendingMutation({ type: 'remove-session', path: cwd, sessionId: id }).catch(() => {});
+    });
+    // 注意：这里故意直接读 loadActiveMap + 调 *Unlocked，不调导出的
+    // getActiveSession/setActiveSession——同一个已在队列里的 mutation
+    // 不能再排一次同一队列，否则自己等自己，死锁。
+    const activeMap = await loadActiveMap();
+    if ((activeMap[cwdHash(cwd)] ?? 'default') === id) {
+      await setActiveSessionUnlocked(cwd, 'default');
+    }
+  });
+}