c0de-agent 1.11.0 → 1.12.0

package/dist/session/session.js

@@ -1,5 +1,6 @@
-import { and, eq, gt, inArray, isNull, lt, ne, or } from 'drizzle-orm';
-import { sessions } from '../db/schema.js';
+import { and, eq, gt, ilike, inArray, isNull, lt, ne, notExists, or, sql } from 'drizzle-orm';
+import { alias } from 'drizzle-orm/pg-core';
+import { sessionEntries, sessions } from '../db/schema.js';
 import { generateId } from '../shared/index.js';
 /** Convert a DB row (with Date timestamps) to the shared Session type (with number timestamps). */
 export function rowToSession(row) {
@@ -26,7 +27,9 @@ export function rowToSession(row) {
     };
 }
 /** Create a new root session. */
-async function createSession(handle, title, projectId, agentType, source) {
+async function createSession(handle, title, projectId, agentType, source, 
+/** P1 会话树治理：子 agent 会话挂到父会话（树内嵌套 + 删除级联）。 */
+parentId) {
     const [row] = await handle.db
         .insert(sessions)
         .values({
@@ -34,6 +37,7 @@ async function createSession(handle, title, projectId, agentType, source) {
         projectId: projectId ?? null,
         agentType: agentType ?? null,
         source: source ?? null,
+        parentId: parentId ?? null,
     })
         .returning();
     if (!row)
@@ -58,82 +62,386 @@ async function listAllSessions(handle) {
     const rows = await handle.db.select().from(sessions).where(isNull(sessions.deletedAt));
     return rows.map(rowToSession);
 }
-/** List soft-deleted sessions (回收站). */
-async function listDeletedSessions(handle) {
+/** List soft-deleted sessions (回收站)；projectId 提供时仅列出归属该项目的会话
+ *  （P1-7：回收站此前全库共享，项目 A 的界面能清空项目 B 的删除会话）。 */
+async function listDeletedSessions(handle, projectId) {
     const rows = await handle.db
         .select()
         .from(sessions)
-        .where(gt(sessions.deletedAt, new Date(0)));
+        .where(projectId
+        ? and(gt(sessions.deletedAt, new Date(0)), eq(sessions.projectId, projectId))
+        : gt(sessions.deletedAt, new Date(0)));
+    return rows.map(rowToSession);
+}
+/** 列出未归属任何项目的已软删除会话（孤儿）。删除项目时 FK set null 使会话失去 projectId，
+ *  在任何项目的回收站视图都不可见（F1），需专门的全局视图暴露以便恢复/归巢。 */
+async function listOrphanDeletedSessions(handle) {
+    const rows = await handle.db
+        .select()
+        .from(sessions)
+        .where(and(gt(sessions.deletedAt, new Date(0)), isNull(sessions.projectId)));
     return rows.map(rowToSession);
 }
+/**
+ * 标记回收站条目「已被用户看到」，记录 metadata.trashSeenAt = now（仅首次，不重置）。
+ * 回收站保留期自首次看到起算（见 purgeDeletedSessions）。软删除时会清除旧标记，
+ * 恢复后再次删除须重新看到回收站才重新起算——避免「未重新看到就被过早清空」。
+ * scope.orphan=true 时仅标记未归属项目的孤儿会话（与 listOrphanDeletedSessions 对齐）；
+ * 孤儿标记仅在用户展开「未归属项目」分组时由前端显式调用（POST /deleted/orphans/seen），
+ * 避免打开任意项目回收站连带启动无关孤儿条目的倒计时。
+ */
+async function touchTrashSeen(handle, scope = {}) {
+    const where = scope.orphan
+        ? and(gt(sessions.deletedAt, new Date(0)), isNull(sessions.projectId))
+        : scope.projectId
+            ? and(gt(sessions.deletedAt, new Date(0)), eq(sessions.projectId, scope.projectId))
+            : gt(sessions.deletedAt, new Date(0));
+    const rows = await handle.db
+        .select({ id: sessions.id, metadata: sessions.metadata })
+        .from(sessions)
+        .where(where);
+    const now = Date.now();
+    let touched = 0;
+    for (const row of rows) {
+        const meta = (row.metadata ?? {});
+        // A3：只标记首次看到，不随每次打开重置——否则「剩余天数」虚标，
+        // 经常打开回收站的用户条目永不清理，保留期形同虚设。
+        if (typeof meta.trashSeenAt === 'number')
+            continue;
+        await handle.db
+            .update(sessions)
+            .set({ metadata: { ...meta, trashSeenAt: now } })
+            .where(eq(sessions.id, row.id));
+        touched += 1;
+    }
+    return touched;
+}
 /**
  * 软删除会话（级联其所有 fork 后代）。设置 deletedAt = now；
- * 30 天后由 purgeDeletedSessions 物理清除。
+ * 60 天后由 purgeDeletedSessions 物理清除（到期先标记、宽限 7 天）。
+ * A3：同时清除 trashSeenAt/purgePendingAt——恢复后重删的会话必须重新被
+ * 用户看到才重新起算，宽限期标记不跨删除周期生效。
  * 会话不存在或已在回收站 → 返回 false（调用方按 404 处理）。
  */
 async function softDeleteSession(handle, id) {
     const [row] = await handle.db
-        .select({ id: sessions.id, deletedAt: sessions.deletedAt })
+        .select({ id: sessions.id, deletedAt: sessions.deletedAt, metadata: sessions.metadata })
         .from(sessions)
         .where(eq(sessions.id, id));
     if (!row || row.deletedAt)
         return false;
     const ids = new Set([id]);
+    const metas = new Map([[id, row.metadata]]);
     let frontier = [id];
     while (frontier.length > 0) {
         // 用 parentId 过滤：收集下一层子会话
         const children = await handle.db
-            .select({ id: sessions.id })
+            .select({ id: sessions.id, metadata: sessions.metadata })
             .from(sessions)
             .where(and(isNull(sessions.deletedAt), inArray(sessions.parentId, frontier)));
         frontier = children.map((r) => r.id).filter((cid) => !ids.has(cid));
-        for (const r of children)
+        for (const r of children) {
             ids.add(r.id);
+            metas.set(r.id, r.metadata);
+        }
     }
     const now = new Date();
+    // 同一次删除级联共享同一批次号：恢复时仅还原同批次后代，避免把早先
+    // 被用户单独删除的分支一并复活（删除/恢复级联的语义不对称缺陷）。
+    const batchId = generateId();
     for (const sid of ids) {
-        await handle.db.update(sessions).set({ deletedAt: now }).where(eq(sessions.id, sid));
+        await handle.db
+            .update(sessions)
+            .set({
+            deletedAt: now,
+            deletedBatchId: batchId,
+            metadata: clearTrashMarks((metas.get(sid) ?? {})),
+        })
+            .where(eq(sessions.id, sid));
     }
     return true;
 }
 /**
- * 从回收站恢复会话：默认连带恢复其已软删除的祖先链——
- * 否则恢复的会话因父仍在回收站而游离于会话树之外（P2-1：UI 不可达）。
- * 祖先中未删除的（活跃）节点不需要也不应该被改动。
+ * A3：清除回收站倒计时/宽限期标记（软删除与项目删除共用）。
+ * 恢复后重删的会话须重新被看到才重新起算；宽限期标记不跨删除周期生效。
+ * 无标记时原样返回，避免无谓的 jsonb 覆写。
  */
-async function restoreSession(handle, id) {
+function clearTrashMarks(meta) {
+    if (typeof meta.trashSeenAt !== 'number' && typeof meta.purgePendingAt !== 'number')
+        return meta;
+    const { trashSeenAt: _seen, purgePendingAt: _purge, ...rest } = meta;
+    return rest;
+}
+/**
+ * 把会话归属到指定项目（P1-2 孤儿会话补救）：设置 projectId 与 worktreePath。
+ * 会话不存在返回 false。
+ */
+async function rebindSession(handle, id, project) {
     const [row] = await handle.db.select().from(sessions).where(eq(sessions.id, id));
-    if (!row || !row.deletedAt)
+    if (!row)
         return false;
+    await handle.db
+        .update(sessions)
+        .set({ projectId: project.id, worktreePath: project.worktree })
+        .where(eq(sessions.id, id));
+    return true;
+}
+async function restoreSessionCore(handle, id, opts = {}) {
+    const includeDescendants = opts.includeDescendants !== false;
+    const [row] = await handle.db.select().from(sessions).where(eq(sessions.id, id));
+    if (!row?.deletedAt)
+        return {
+            restored: false,
+            restoredAncestorCount: 0,
+            crossedBatchAncestor: false,
+            leftBehindDescendantCount: 0,
+        };
+    const targetBatch = row.deletedBatchId;
     const ids = new Set([id]);
+    // 后代 BFS：仅还原属于同一删除批次的后代（删除时父+后代共享 deletedBatchId）。
+    // 若只按「已删除」收集，会把早先被用户单独删除的分支一并复活（F2 不对称缺陷）。
+    if (includeDescendants) {
+        let frontier = [id];
+        while (frontier.length > 0) {
+            const children = await handle.db
+                .select({ id: sessions.id })
+                .from(sessions)
+                .where(and(gt(sessions.deletedAt, new Date(0)), inArray(sessions.parentId, frontier), row.deletedBatchId
+                ? eq(sessions.deletedBatchId, row.deletedBatchId)
+                : isNull(sessions.deletedBatchId)));
+            frontier = children.map((r) => r.id).filter((cid) => !ids.has(cid));
+            for (const r of children)
+                ids.add(r.id);
+        }
+    }
+    // A2：统计所有已删后代中未随本次恢复的数量（批次不同 → 滞留回收站）。
+    let leftBehindDescendantCount = 0;
+    if (includeDescendants) {
+        const seen = new Set();
+        let frontier = [id];
+        while (frontier.length > 0) {
+            const children = await handle.db
+                .select({ id: sessions.id })
+                .from(sessions)
+                .where(and(gt(sessions.deletedAt, new Date(0)), inArray(sessions.parentId, frontier)));
+            frontier = [];
+            for (const ch of children) {
+                if (seen.has(ch.id))
+                    continue;
+                seen.add(ch.id);
+                frontier.push(ch.id);
+                if (!ids.has(ch.id))
+                    leftBehindDescendantCount += 1;
+            }
+        }
+    }
+    // 祖先链（仅还原其中已软删除的节点）：为保证恢复节点在会话树可达，
+    // 已删除的祖先无论批次均需一并还原。记录还原的祖先数量与是否跨越删除批次，
+    // 供前端提示「为保持会话树完整，同时还原了 N 个父会话」。
+    let restoredAncestorCount = 0;
+    let crossedBatchAncestor = false;
     let parentId = row.parentId;
     while (parentId) {
         const [parent] = await handle.db.select().from(sessions).where(eq(sessions.id, parentId));
         if (!parent)
             break;
-        if (parent.deletedAt)
+        if (parent.deletedAt && !ids.has(parent.id)) {
             ids.add(parent.id);
+            restoredAncestorCount += 1;
+            if (parent.deletedBatchId !== targetBatch)
+                crossedBatchAncestor = true;
+        }
         parentId = parent.parentId;
     }
     for (const sid of ids) {
-        await handle.db.update(sessions).set({ deletedAt: null }).where(eq(sessions.id, sid));
+        await handle.db
+            .update(sessions)
+            .set({ deletedAt: null, deletedBatchId: null })
+            .where(eq(sessions.id, sid));
     }
-    return true;
+    return {
+        restored: true,
+        restoredAncestorCount,
+        crossedBatchAncestor,
+        leftBehindDescendantCount,
+    };
+}
+async function restoreSession(handle, id, opts = {}) {
+    return (await restoreSessionCore(handle, id, opts)).restored;
 }
 /**
- * 物理清除回收站中超过保留期（默认 30 天）的会话。
- * 子会话先于父会话删除（自引用 FK 要求）。
- * 返回清除数量。启动时与每日定时调用。
+ * P2-4：回收站保留期 60 天（原 30 天），自「用户首次在回收站看到该条目」
+ * （metadata.trashSeenAt）起算，而非删除时间（墙钟）——否则用户删除后长期不开服务、
+ * 重启即被静默物理清除，从未见过任何倒计时。临时会话（CLI print / workflow）保留期
+ * 仍为 30 天，见 purgeTemporarySessions。
+ */
+export const TRASH_RETENTION_MS = 60 * 24 * 60 * 60 * 1000;
+/**
+ * A3：到期标记 → 物理清除的宽限期（默认 7 天）。
+ * 条目到期后先写 metadata.purgePendingAt，UI 显示「即将清除」并可恢复；
+ * 宽限期满才物理清除——杜绝「到期即静默物理清空」的数据丢失死角。
+ */
+export const TRASH_PURGE_GRACE_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * 回收站两阶段清理（启动时与每日定时调用）：
+ * 阶段一：trashSeenAt 超过保留期且未标记 → 标记 purgePendingAt（进入宽限期，可恢复）。
+ * 阶段二：purgePendingAt 早于宽限截止 → 物理清除（子会话先于父，自引用 FK 要求）。
+ * 未被看到过（trashSeenAt 缺失）或恢复后重删、尚未重新看到的会话永不进入任一阶段。
+ */
+async function purgeDeletedSessions(handle, retentionMs = TRASH_RETENTION_MS, graceMs = TRASH_PURGE_GRACE_MS) {
+    const retentionCutoff = Date.now() - retentionMs;
+    const graceCutoff = Date.now() - graceMs;
+    const rows = await handle.db
+        .select({
+        id: sessions.id,
+        parentId: sessions.parentId,
+        deletedAt: sessions.deletedAt,
+        metadata: sessions.metadata,
+    })
+        .from(sessions)
+        .where(gt(sessions.deletedAt, new Date(0)));
+    // —— 阶段一：到期标记（先宽限，不直接清除）——
+    let marked = 0;
+    for (const r of rows) {
+        if (!r.deletedAt)
+            continue;
+        const meta = (r.metadata ?? {});
+        const seen = meta.trashSeenAt;
+        const deletedMs = r.deletedAt.getTime();
+        // 保留期自「首次看到」起算：seen 缺失或早于最近一次删除 → 未重新看到，不标记。
+        if (typeof seen !== 'number' || seen <= deletedMs || seen >= retentionCutoff)
+            continue;
+        if (typeof meta.purgePendingAt === 'number')
+            continue;
+        await handle.db
+            .update(sessions)
+            .set({ metadata: { ...meta, purgePendingAt: Date.now() } })
+            .where(eq(sessions.id, r.id));
+        marked += 1;
+    }
+    // —— 阶段二：宽限期满物理清除 ——
+    const pending = rows.filter((r) => {
+        if (!r.deletedAt)
+            return false;
+        const meta = (r.metadata ?? {});
+        const p = meta.purgePendingAt;
+        return typeof p === 'number' && p < graceCutoff;
+    });
+    let deleted = 0;
+    if (pending.length > 0) {
+        // 拓扑序：无子会话的先删
+        const remaining = new Set(pending.map((r) => r.id));
+        while (remaining.size > 0) {
+            const hasChildParent = new Set(pending.filter((r) => r.parentId && remaining.has(r.parentId)).map((r) => r.parentId));
+            const leaves = pending
+                .filter((r) => remaining.has(r.id) && !hasChildParent.has(r.id))
+                .map((r) => r.id);
+            if (leaves.length === 0) {
+                // 循环引用兜底：强制按 id 逐个删除（自引用环数据异常场景）
+                for (const id of Array.from(remaining)) {
+                    await handle.db.delete(sessions).where(eq(sessions.id, id));
+                    remaining.delete(id);
+                    deleted += 1;
+                }
+                break;
+            }
+            for (const id of leaves) {
+                await handle.db.delete(sessions).where(eq(sessions.id, id));
+                remaining.delete(id);
+                deleted += 1;
+            }
+        }
+    }
+    return { marked, deleted };
+}
+/** C4：空会话 GC 保留期（7 天）。仅覆盖「从未写入任何消息/工具条目」的会话。 */
+const EMPTY_SESSION_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * C4：清理长期空置的 web 会话（无任何条目、无子会话、未删除、创建早于保留期）。
+ * 覆盖「新建会话后未发言」的残留：首条消息失败清理依赖前端 JS 执行，
+ * 崩溃/断电/离线时必然残留空「New Session」行。CLI 临时会话由 purgeTemporarySessions 负责。
  */
-async function purgeDeletedSessions(handle, retentionMs = 30 * 24 * 60 * 60 * 1000) {
+async function purgeEmptySessions(handle, retentionMs = EMPTY_SESSION_RETENTION_MS) {
     const cutoff = new Date(Date.now() - retentionMs);
+    const children = alias(sessions, 'empty_children');
+    const result = await handle.db
+        .delete(sessions)
+        .where(and(lt(sessions.createdAt, cutoff), isNull(sessions.deletedAt), or(isNull(sessions.source), eq(sessions.source, 'web')), notExists(handle.db
+        .select({ one: sql `1` })
+        .from(sessionEntries)
+        .where(eq(sessionEntries.sessionId, sessions.id))), notExists(handle.db
+        .select({ one: sql `1` })
+        .from(children)
+        .where(eq(children.parentId, sessions.id)))))
+        .returning({ id: sessions.id });
+    return result.length;
+}
+/** Update a session's title. */
+async function updateSessionTitle(handle, id, title) {
+    await handle.db.update(sessions).set({ title, updatedAt: new Date() }).where(eq(sessions.id, id));
+}
+/**
+ * 彻底删除某个回收站会话及其全部后代（含未软删除的 fork 后代，防御数据异常）。
+ * 子会话先于父会话删除（自引用 FK RESTRICT 要求）；entries/archives 经 FK cascade 清理。
+ * 返回删除数量。会话不存在或不在回收站 → 返回 0。
+ */
+async function permanentlyDeleteSession(handle, id) {
+    const [row] = await handle.db
+        .select({ id: sessions.id, deletedAt: sessions.deletedAt })
+        .from(sessions)
+        .where(eq(sessions.id, id));
+    if (!row?.deletedAt)
+        return 0;
+    const all = await handle.db
+        .select({ id: sessions.id, parentId: sessions.parentId })
+        .from(sessions);
+    const ids = new Set([id]);
+    let frontier = [id];
+    while (frontier.length > 0) {
+        const children = all
+            .filter((r) => r.parentId && frontier.includes(r.parentId))
+            .map((r) => r.id)
+            .filter((cid) => !ids.has(cid));
+        for (const cid of children)
+            ids.add(cid);
+        frontier = children;
+    }
+    // 拓扑序：无子会话的先删（与 purgeDeletedSessions 同策略）
+    const remaining = new Set(ids);
+    let deleted = 0;
+    while (remaining.size > 0) {
+        const hasChildParent = new Set(Array.from(remaining).filter((rid) => {
+            const r = all.find((x) => x.id === rid);
+            return r?.parentId && remaining.has(r.parentId);
+        }));
+        const leaves = Array.from(remaining).filter((rid) => !hasChildParent.has(rid));
+        if (leaves.length === 0) {
+            for (const rid of Array.from(remaining)) {
+                await handle.db.delete(sessions).where(eq(sessions.id, rid));
+                remaining.delete(rid);
+                deleted += 1;
+            }
+            break;
+        }
+        for (const rid of leaves) {
+            await handle.db.delete(sessions).where(eq(sessions.id, rid));
+            remaining.delete(rid);
+            deleted += 1;
+        }
+    }
+    return deleted;
+}
+/** 清空回收站：物理删除所有已软删除会话（子先于父）。返回删除数量。
+ *  projectId 提供时仅清空该项目（P1-7）。 */
+async function emptyTrash(handle, projectId) {
     const rows = await handle.db
         .select({ id: sessions.id, parentId: sessions.parentId })
         .from(sessions)
-        .where(lt(sessions.deletedAt, cutoff));
+        .where(projectId
+        ? and(gt(sessions.deletedAt, new Date(0)), eq(sessions.projectId, projectId))
+        : gt(sessions.deletedAt, new Date(0)));
     if (rows.length === 0)
         return 0;
-    // 拓扑序：无子会话的先删
     const remaining = new Set(rows.map((r) => r.id));
     let deleted = 0;
     while (remaining.size > 0) {
@@ -142,7 +450,6 @@ async function purgeDeletedSessions(handle, retentionMs = 30 * 24 * 60 * 60 * 10
             .filter((r) => remaining.has(r.id) && !hasChildParent.has(r.id))
             .map((r) => r.id);
         if (leaves.length === 0) {
-            // 循环引用兜底：强制按 id 逐个删除（自引用环数据异常场景）
             for (const id of Array.from(remaining)) {
                 await handle.db.delete(sessions).where(eq(sessions.id, id));
                 remaining.delete(id);
@@ -158,9 +465,78 @@ async function purgeDeletedSessions(handle, retentionMs = 30 * 24 * 60 * 60 * 10
     }
     return deleted;
 }
-/** Update a session's title. */
-async function updateSessionTitle(handle, id, title) {
-    await handle.db.update(sessions).set({ title, updatedAt: new Date() }).where(eq(sessions.id, id));
+/**
+ * 清理过期临时会话（P2 → P1 收紧：仅清理显式标记的临时会话）。
+ * - agentType='print'：CLI 一次性问答（c0de chat，非 --continue）创建的会话。
+ * - agentType='workflow'：工作流运行产生的会话。
+ * 普通 CLI 会话（ACP）与 --continue 续接的会话（续接时已升级）永不清理——
+ * 此前按 source='cli' 全删会把用户显式续接的历史静默物理删除。
+ * 保留期默认 30 天；子条目经 FK cascade 一并删除。
+ * 返回清除数量。启动时与每日定时调用。
+ */
+async function purgeTemporarySessions(handle, retentionMs = 30 * 24 * 60 * 60 * 1000) {
+    const cutoff = new Date(Date.now() - retentionMs);
+    const all = await handle.db
+        .select({
+        id: sessions.id,
+        parentId: sessions.parentId,
+        agentType: sessions.agentType,
+        updatedAt: sessions.updatedAt,
+    })
+        .from(sessions);
+    const roots = all.filter((r) => (r.agentType === 'print' || r.agentType === 'workflow') &&
+        r.updatedAt != null &&
+        r.updatedAt.getTime() < cutoff.getTime());
+    if (roots.length === 0)
+        return 0;
+    // 临时会话可能派发过子 agent（其子会话挂 parentId）。父会话直接删除会撞自引用
+    // FK（RESTRICT），且子会话失去父后成为游离节点——故连同全部后代一起物理清除，
+    // 并按拓扑序「子先于父」删除（与 emptyTrash / purgeDeletedSessions 同一策略）。
+    const childrenOf = new Map();
+    for (const r of all) {
+        if (r.parentId) {
+            const list = childrenOf.get(r.parentId) ?? [];
+            list.push(r.id);
+            childrenOf.set(r.parentId, list);
+        }
+    }
+    const ids = new Set();
+    const collect = (sid) => {
+        if (ids.has(sid))
+            return;
+        ids.add(sid);
+        for (const c of childrenOf.get(sid) ?? [])
+            collect(c);
+    };
+    for (const r of roots)
+        collect(r.id);
+    const remaining = new Set(ids);
+    let deleted = 0;
+    while (remaining.size > 0) {
+        const leaves = Array.from(remaining).filter((sid) => !(childrenOf.get(sid) ?? []).some((c) => remaining.has(c)));
+        if (leaves.length === 0) {
+            // 循环引用兜底：强制逐个删除（数据异常场景）
+            for (const sid of Array.from(remaining)) {
+                await handle.db.delete(sessions).where(eq(sessions.id, sid));
+                remaining.delete(sid);
+                deleted += 1;
+            }
+            break;
+        }
+        for (const sid of leaves) {
+            await handle.db.delete(sessions).where(eq(sessions.id, sid));
+            remaining.delete(sid);
+            deleted += 1;
+        }
+    }
+    return deleted;
+}
+/**
+ * 把临时会话升级为持久会话（--continue 续接时调用）：
+ * 清除 print 标记，30 天临时清理不再触及。
+ */
+async function upgradeTemporarySession(handle, id) {
+    await handle.db.update(sessions).set({ agentType: null }).where(eq(sessions.id, id));
 }
 /** Bump updatedAt to now (used after appending messages). */
 async function touchSession(handle, id) {
@@ -271,4 +647,59 @@ async function listSessionsByProject(handle, projectId) {
         .where(and(eq(sessions.projectId, projectId), isNull(sessions.deletedAt), or(isNull(sessions.source), ne(sessions.source, 'cli'))));
     return rows.map(rowToSession);
 }
-export { createSession, getSession, listAllSessions, listDeletedSessions, listSessions, listSessionsByProject, purgeDeletedSessions, restoreSession, softDeleteSession, touchLastOpened, touchSession, updateSessionLastRun, updateSessionTitle, };
+/**
+ * 跨会话搜索（P2-6）：标题 + 消息内容子串匹配。
+ * 默认仅搜索未软删除的非 CLI 会话（与 Web 会话树一致）；projectId 提供时限定项目。
+ * opts.includeDeleted=true 时搜索回收站（P3：回收站无搜索，删后找内容只能逐行翻）。
+ * 返回 { session, matchedBy: 'title' | 'content' }。
+ */
+async function searchSessions(handle, query, projectId, opts = {}) {
+    const needle = query.trim();
+    if (!needle)
+        return [];
+    const pattern = `%${needle.replace(/[%_\\]/g, '\\$&')}%`;
+    const baseWhere = and(opts.includeDeleted ? gt(sessions.deletedAt, new Date(0)) : isNull(sessions.deletedAt), 
+    // 回收站搜索与回收站列表（listDeletedSessions）一致：不过滤 source。
+    ...(opts.includeDeleted ? [] : [or(isNull(sessions.source), ne(sessions.source, 'cli'))]), ...(projectId ? [eq(sessions.projectId, projectId)] : []));
+    // 标题命中（ILIKE 转义后按字面子串）
+    const byTitle = await handle.db
+        .select()
+        .from(sessions)
+        .where(and(baseWhere, ilike(sessions.title, pattern)));
+    const byContent = await handle.db
+        .selectDistinctOn([sessions.id], {
+        id: sessions.id,
+        title: sessions.title,
+        parentId: sessions.parentId,
+        projectId: sessions.projectId,
+        branchPoint: sessions.branchPoint,
+        metadata: sessions.metadata,
+        agentType: sessions.agentType,
+        worktreePath: sessions.worktreePath,
+        source: sessions.source,
+        deletedAt: sessions.deletedAt,
+        deletedBatchId: sessions.deletedBatchId,
+        createdAt: sessions.createdAt,
+        updatedAt: sessions.updatedAt,
+    })
+        .from(sessionEntries)
+        .innerJoin(sessions, eq(sessionEntries.sessionId, sessions.id))
+        .where(and(baseWhere, eq(sessionEntries.tag, 'message'), sql `${sessionEntries.content}::text ILIKE ${pattern}`))
+        .orderBy(sessions.id, sessions.updatedAt);
+    const result = [];
+    const seen = new Set();
+    for (const row of byTitle) {
+        const s = rowToSession(row);
+        result.push({ session: s, matchedBy: 'title' });
+        seen.add(s.id);
+    }
+    for (const row of byContent) {
+        const s = rowToSession(row);
+        if (!seen.has(s.id)) {
+            result.push({ session: s, matchedBy: 'content' });
+            seen.add(s.id);
+        }
+    }
+    return result;
+}
+export { clearTrashMarks, createSession, emptyTrash, getSession, listAllSessions, listDeletedSessions, listOrphanDeletedSessions, listSessions, listSessionsByProject, permanentlyDeleteSession, purgeDeletedSessions, purgeEmptySessions, purgeTemporarySessions, rebindSession, restoreSession, restoreSessionCore, searchSessions, softDeleteSession, touchLastOpened, touchSession, touchTrashSeen, updateSessionLastRun, updateSessionTitle, upgradeTemporarySession, };

package/dist/session/snapshot.d.ts

@@ -12,6 +12,9 @@ declare function getFileSnapshots(handle: DB, sessionId: string): Promise<FileSn
 declare function getLatestFileSnapshot(handle: DB, sessionId: string, filePath: string): Promise<FileSnapshot | null>;
 /** Quick check: return cached file content if a snapshot exists, else null. */
 declare function checkFileSnapshot(handle: DB, sessionId: string, filePath: string): Promise<string | null>;
-/** 把源会话每个文件的最新快照复制到目标会话（fork 分支用，P1-4）。 */
-declare function copyFileSnapshots(handle: DB, fromSessionId: string, toSessionId: string): Promise<void>;
+/** 把源会话每个文件的最新快照复制到目标会话（fork 分支用，P1-4）。
+ *  C3：beforeMs 提供时只复制创建时间 ≤ 分支点的快照版本——从较早消息点 fork 时，
+ *  分支点之后更新的快照反映的是「未来」文件状态，复制会污染分支上下文；
+ *  无合格版本的文件夹跳过（宁可缺快照由磁盘重读，也不注入错误内容）。 */
+declare function copyFileSnapshots(handle: DB, fromSessionId: string, toSessionId: string, beforeMs?: number): Promise<void>;
 export { checkFileSnapshot, copyFileSnapshots, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot, };

package/dist/session/snapshot.js

@@ -73,14 +73,22 @@ async function checkFileSnapshot(handle, sessionId, filePath) {
     const snapshot = await getLatestFileSnapshot(handle, sessionId, filePath);
     return snapshot?.content ?? null;
 }
-/** 把源会话每个文件的最新快照复制到目标会话（fork 分支用，P1-4）。 */
-async function copyFileSnapshots(handle, fromSessionId, toSessionId) {
+/** 把源会话每个文件的最新快照复制到目标会话（fork 分支用，P1-4）。
+ *  C3：beforeMs 提供时只复制创建时间 ≤ 分支点的快照版本——从较早消息点 fork 时，
+ *  分支点之后更新的快照反映的是「未来」文件状态，复制会污染分支上下文；
+ *  无合格版本的文件夹跳过（宁可缺快照由磁盘重读，也不注入错误内容）。 */
+async function copyFileSnapshots(handle, fromSessionId, toSessionId, beforeMs) {
     const rows = await handle.db
         .select()
         .from(fileSnapshots)
         .where(eq(fileSnapshots.sessionId, fromSessionId));
     const latest = new Map();
     for (const r of rows) {
+        if (beforeMs !== undefined) {
+            const created = r.createdAt instanceof Date ? r.createdAt.getTime() : new Date(r.createdAt).getTime();
+            if (created > beforeMs)
+                continue;
+        }
         const prev = latest.get(r.filePath);
         if (!prev || (r.version ?? 0) > (prev.version ?? 0))
             latest.set(r.filePath, r);

package/dist/session/types.d.ts

@@ -91,10 +91,20 @@ type ArchiveRef = {
     type: 'archive' | 'squash';
     id: string;
 };
+/** 会话级用量汇总（P0 审查：列表视图此前无法回答「会话花了多少 token/钱」）。
+ *  从 metadata.segments 聚合，零额外查询。 */
+type SessionUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    cost: number;
+    calls: number;
+};
 /** A node in the session tree. */
 type SessionTreeNode = {
     session: Session;
     children: SessionTreeNode[];
+    usage: SessionUsage;
 };
 /** A decoded compaction archive row. */
 type CompactionArchive = {
@@ -121,4 +131,4 @@ type FileSnapshot = {
     mtimeMs?: number;
     createdAt: number;
 };
-export type { ArchiveRef, BranchSummaryEntry, CompactionArchive, CompactionConfig, CompactionEntry, CompactionResult, FileSnapshot, HotFile, MessageInput, SessionEntry, SessionTreeNode, SquashConfig, SquashEntry, SteeringEntry, Summarizer, };
+export type { ArchiveRef, BranchSummaryEntry, CompactionArchive, CompactionConfig, CompactionEntry, CompactionResult, FileSnapshot, HotFile, MessageInput, SessionEntry, SessionTreeNode, SessionUsage, SquashConfig, SquashEntry, SteeringEntry, Summarizer, };

package/dist/shared/types/agent.d.ts

@@ -155,6 +155,13 @@ type AgentEvent = {
     toolCallId: string;
     tool: string;
     input: unknown;
+}
+/** P0 双层超时：提示后仍无响应，pending 已兜底自动拒绝（run 继续）——前端须清理弹窗状态。 */
+ | {
+    _tag: 'permission_expired';
+    toolCallId: string;
+    tool: string;
+    input: unknown;
 } | {
     _tag: 'error';
     error: AgentError;
@@ -202,6 +209,10 @@ type AgentEvent = {
             status: string;
         }[];
     }[];
+}
+/** SSE 心跳（服务端防前端 90s 静默看门狗误杀长任务）；前端无 UI 变化，直接忽略。 */
+ | {
+    _tag: 'heartbeat';
 } | {
     _tag: 'done';
 };