c0de-agent 1.11.0 → 1.12.0

package/dist/session/branch.js

@@ -99,8 +99,10 @@ async function forkSession(handle, sessionId, messageIndex) {
                 sourceSessionId: sessionId,
             },
         });
-        // 复制源会话最新文件快照（P1-4：@文件上下文随分支保留）。
-        await copyFileSnapshots(txHandle, sessionId, forked.id);
+        // 复制源会话文件快照（P1-4：@文件上下文随分支保留）。
+        // C3：按分支点时间过滤——分支点之后更新的快照是「未来」状态，不复制。
+        const branchPointMs = typeof target.createdAt === 'number' ? target.createdAt : new Date(target.createdAt).getTime();
+        await copyFileSnapshots(txHandle, sessionId, forked.id, branchPointMs);
         const created = await getSession(txHandle, forked.id);
         if (!created)
             throw new Error('Forked session not found after creation');
@@ -116,6 +118,21 @@ async function getBranches(handle, sessionId) {
         .where(and(eq(sessions.parentId, sessionId), isNull(sessions.deletedAt)));
     return rows.map(rowToSession);
 }
+/** 从会话 metadata.segments 聚合用量（零额外查询——段数据已在行内）。 */
+function sessionUsage(session) {
+    const calls = (session.metadata.segments ?? []).flatMap((s) => s.calls ?? []);
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheRead = 0;
+    let cost = 0;
+    for (const c of calls) {
+        inputTokens += c.usage.input;
+        outputTokens += c.usage.output;
+        cacheRead += c.usage.cacheRead ?? 0;
+        cost += c.cost;
+    }
+    return { inputTokens, outputTokens, cacheRead, cost, calls: calls.length };
+}
 /** Build a full session tree from root sessions down.
  * 每层按 metadata.lastOpenedAt 降序（fallback updatedAt、createdAt）。
  * 排除软删除会话与 CLI 来源会话（Web 树仅展示 web 会话）。
@@ -140,6 +157,7 @@ async function getTree(handle) {
         .map((session) => ({
         session,
         children: build(session.id),
+        usage: sessionUsage(session),
     }));
     return build(null);
 }

package/dist/session/import.d.ts

@@ -0,0 +1,44 @@
+import type { DB } from '../db/client.js';
+/** 导入消息的宽松形状（导出 JSON 反序列化后，字段可能缺失/类型漂移）。 */
+type ImportMessage = {
+    id?: string;
+    role?: string;
+    content?: unknown;
+    tokenCount?: number;
+    createdAt?: number | string;
+};
+/** 导入归档的宽松形状。 */
+type ImportArchive = {
+    id?: string;
+    compactionId?: string;
+    archiveType?: string;
+    originalEntries?: unknown;
+    fileSnapshots?: unknown;
+    summary?: string;
+    tokenCount?: number;
+    searchableText?: string;
+    createdAt?: number | string;
+};
+/**
+ * 导入会话数据（GET /sessions/:id/export 的逆操作）：
+ * 新建根会话（source 'web'），消息与归档**始终生成新 id**（保留 role/content/时间戳）——
+ * 导入副本可重复执行（同库内复制/恢复场景），不与原会话或既往导入冲突。
+ * 说明：导出仅含 tag='message' 的消息——compaction/steering 等特殊条目不随迁，
+ * 导入后会话显示完整原始消息流（上下文重建略长，但不丢内容）。
+ * P0：权限态（permissionMode/alwaysAllow）仅在调用方显式确认后随迁——
+ * metadata 由路由层过滤，未确认时不传入本函数。
+ */
+declare function importSessionData(handle: DB, opts: {
+    title: string;
+    projectId?: string;
+    messages: ImportMessage[];
+    archives: ImportArchive[];
+    /** 随迁的会话 metadata（仅权限态等安全字段，由调用方过滤）。 */
+    metadata?: Record<string, unknown>;
+}): Promise<{
+    sessionId: string;
+    messageCount: number;
+    archiveCount: number;
+}>;
+export type { ImportArchive, ImportMessage };
+export { importSessionData };

package/dist/session/import.js

@@ -0,0 +1,83 @@
+import { eq } from 'drizzle-orm';
+import { compactionArchives, sessionEntries, sessions } from '../db/schema.js';
+import { generateId } from '../shared/index.js';
+import { createSession } from './session.js';
+const VALID_ROLES = new Set([
+    'user',
+    'assistant',
+    'system',
+    'tool',
+]);
+function toDate(value) {
+    if (typeof value === 'number')
+        return new Date(value);
+    if (typeof value === 'string') {
+        const d = new Date(value);
+        if (!Number.isNaN(d.getTime()))
+            return d;
+    }
+    return new Date();
+}
+function sanitizeContent(content) {
+    if (Array.isArray(content)) {
+        // 只保留结构完整的分片；其余丢弃（导入宁少勿坏）
+        return content.filter((p) => p !== null && typeof p === 'object' && typeof p._tag === 'string');
+    }
+    if (typeof content === 'string' && content.length > 0) {
+        return [{ _tag: 'text', text: content }];
+    }
+    return [];
+}
+/**
+ * 导入会话数据（GET /sessions/:id/export 的逆操作）：
+ * 新建根会话（source 'web'），消息与归档**始终生成新 id**（保留 role/content/时间戳）——
+ * 导入副本可重复执行（同库内复制/恢复场景），不与原会话或既往导入冲突。
+ * 说明：导出仅含 tag='message' 的消息——compaction/steering 等特殊条目不随迁，
+ * 导入后会话显示完整原始消息流（上下文重建略长，但不丢内容）。
+ * P0：权限态（permissionMode/alwaysAllow）仅在调用方显式确认后随迁——
+ * metadata 由路由层过滤，未确认时不传入本函数。
+ */
+async function importSessionData(handle, opts) {
+    const session = await createSession(handle, opts.title, opts.projectId, undefined, 'web');
+    return handle.db.transaction(async (tx) => {
+        if (opts.metadata && Object.keys(opts.metadata).length > 0) {
+            await tx.update(sessions).set({ metadata: opts.metadata }).where(eq(sessions.id, session.id));
+        }
+        let messageCount = 0;
+        for (const m of opts.messages) {
+            const role = m.role;
+            if (typeof role !== 'string' || !VALID_ROLES.has(role))
+                continue;
+            await tx.insert(sessionEntries).values({
+                id: generateId(),
+                sessionId: session.id,
+                tag: 'message',
+                role,
+                content: sanitizeContent(m.content),
+                tokenCount: typeof m.tokenCount === 'number' ? m.tokenCount : 0,
+                createdAt: toDate(m.createdAt),
+            });
+            messageCount += 1;
+        }
+        let archiveCount = 0;
+        for (const a of opts.archives) {
+            await tx.insert(compactionArchives).values({
+                id: generateId(),
+                sessionId: session.id,
+                compactionId: typeof a.compactionId === 'string' && a.compactionId.length > 0
+                    ? a.compactionId
+                    : generateId(),
+                archiveType: typeof a.archiveType === 'string' ? a.archiveType : 'compaction',
+                originalEntries: Array.isArray(a.originalEntries) ? a.originalEntries : [],
+                fileSnapshots: Array.isArray(a.fileSnapshots) ? a.fileSnapshots : [],
+                summary: typeof a.summary === 'string' ? a.summary : '',
+                tokenCount: typeof a.tokenCount === 'number' ? a.tokenCount : null,
+                searchableText: typeof a.searchableText === 'string' ? a.searchableText : null,
+                createdAt: toDate(a.createdAt),
+            });
+            archiveCount += 1;
+        }
+        return { sessionId: session.id, messageCount, archiveCount };
+    });
+}
+export { importSessionData };

package/dist/session/index.d.ts

@@ -3,7 +3,7 @@ export { forkSession, getBranches, getTree } from './branch.js';
 export { buildCompactionPrompt, compactSession, extractHotFiles, findSafeCutPoint, } from './compaction.js';
 export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessage, } from './context.js';
 export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, } from './message.js';
-export { createSession, getLLMSegments, getSession, listDeletedSessions, listSessions, migrateLegacyDetails, purgeDeletedSessions, restoreSession, saveLLMSegments, segmentFingerprint, softDeleteSession, touchSession, updateSessionTitle, } from './session.js';
+export { createSession, getLLMSegments, getSession, listDeletedSessions, listSessions, migrateLegacyDetails, purgeDeletedSessions, restoreSession, restoreSessionCore, saveLLMSegments, segmentFingerprint, softDeleteSession, TRASH_RETENTION_MS, touchSession, touchTrashSeen, updateSessionTitle, } from './session.js';
 export { checkFileSnapshot, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot, } from './snapshot.js';
 export { squashRecent } from './squash.js';
 export { estimateMessageTokens, estimateTokens } from './token.js';

package/dist/session/index.js

@@ -4,7 +4,7 @@ export { forkSession, getBranches, getTree } from './branch.js';
 export { buildCompactionPrompt, compactSession, extractHotFiles, findSafeCutPoint, } from './compaction.js';
 export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessage, } from './context.js';
 export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, } from './message.js';
-export { createSession, getLLMSegments, getSession, listDeletedSessions, listSessions, migrateLegacyDetails, purgeDeletedSessions, restoreSession, saveLLMSegments, segmentFingerprint, softDeleteSession, touchSession, updateSessionTitle, } from './session.js';
+export { createSession, getLLMSegments, getSession, listDeletedSessions, listSessions, migrateLegacyDetails, purgeDeletedSessions, restoreSession, restoreSessionCore, saveLLMSegments, segmentFingerprint, softDeleteSession, TRASH_RETENTION_MS, touchSession, touchTrashSeen, updateSessionTitle, } from './session.js';
 export { checkFileSnapshot, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot, } from './snapshot.js';
 export { squashRecent } from './squash.js';
 export { estimateMessageTokens, estimateTokens } from './token.js';

package/dist/session/jobs.d.ts

@@ -0,0 +1,12 @@
+import type { DB } from '../db/client.js';
+/**
+ * 标记崩溃遗留的后台子 agent 任务并通知父会话（P2）。
+ *
+ * background task 在子 session 上写 lastRun.status='running'（subagent.ts），
+ * 完成后置 'completed'。进程崩溃时悬空任务永远停在 'running'，父会话收不到
+ * 完成通知（原实现仅内存 jobId，重启即丢）。启动时调用：
+ *  - 悬空任务 lastRun 置 'completed'（死任务不再显示 interrupted）；
+ *  - 合成一条 state="failed" 通知写入父会话（子 session 已挂 parentId）。
+ * 返回标记数量。
+ */
+export declare function markDeadBackgroundJobs(handle: DB): Promise<number>;

package/dist/session/jobs.js

@@ -0,0 +1,53 @@
+import { and, inArray, isNotNull, sql } from 'drizzle-orm';
+import { sessions } from '../db/schema.js';
+import { appendMessage } from './message.js';
+import { updateSessionLastRun } from './session.js';
+/**
+ * 标记崩溃遗留的后台子 agent 任务并通知父会话（P2）。
+ *
+ * background task 在子 session 上写 lastRun.status='running'（subagent.ts），
+ * 完成后置 'completed'。进程崩溃时悬空任务永远停在 'running'，父会话收不到
+ * 完成通知（原实现仅内存 jobId，重启即丢）。启动时调用：
+ *  - 悬空任务 lastRun 置 'completed'（死任务不再显示 interrupted）；
+ *  - 合成一条 state="failed" 通知写入父会话（子 session 已挂 parentId）。
+ * 返回标记数量。
+ */
+export async function markDeadBackgroundJobs(handle) {
+    const rows = await handle.db
+        .select({
+        id: sessions.id,
+        parentId: sessions.parentId,
+        agentType: sessions.agentType,
+    })
+        .from(sessions)
+        .where(and(isNotNull(sessions.agentType), isNotNull(sessions.parentId), sql `${sessions.metadata}->'lastRun'->>'status' = 'running'`));
+    // 父会话已入回收站的不再注入失败通知（否则向 60 天后将清除的会话写死消息）。
+    const parentIds = Array.from(new Set(rows.map((r) => r.parentId).filter((p) => !!p)));
+    const trashedParents = new Set();
+    if (parentIds.length > 0) {
+        const parents = await handle.db
+            .select({ id: sessions.id, deletedAt: sessions.deletedAt })
+            .from(sessions)
+            .where(inArray(sessions.id, parentIds));
+        for (const p of parents)
+            if (p.deletedAt)
+                trashedParents.add(p.id);
+    }
+    for (const row of rows) {
+        await updateSessionLastRun(handle, row.id, {
+            status: 'completed',
+            agentName: row.agentType ?? undefined,
+            startedAt: Date.now(),
+        });
+        if (row.parentId && !trashedParents.has(row.parentId)) {
+            const synthetic = `<task id="${row.id}" state="failed">\n<task_error>\n后台任务在服务重启前未完成，已标记为失败（可重新派发）\n</task_error>\n</task>`;
+            await appendMessage(handle, row.parentId, {
+                role: 'user',
+                content: [{ _tag: 'text', text: synthetic }],
+            }).catch(() => {
+                // 通知写入失败：任务已标记，父会话可能收不到失败提示——仅记录
+            });
+        }
+    }
+    return rows.length;
+}

package/dist/session/message.d.ts

@@ -9,6 +9,12 @@ declare function getMessages(handle: DB, sessionId: string, opts?: {
     limit?: number;
     offset?: number;
 }): Promise<Message[]>;
+/**
+ * 会话 steering 条目映射为 Message 形态（role='user'，内容为 steering part）。
+ * 时间线渲染与消息合并使用（P0：追加指令持久化后的展示路径）；
+ * 不并入 getMessages——compaction/shake/export 等仅处理真实消息的消费者不受影响。
+ */
+declare function getSteeringAsMessages(handle: DB, sessionId: string): Promise<Message[]>;
 /** Count messages in a session. */
 declare function getMessageCount(handle: DB, sessionId: string): Promise<number>;
 /** Delete all messages after the given 0-based index (keeps 0..index inclusive). */
@@ -19,4 +25,4 @@ declare function getEntries(handle: DB, sessionId: string): Promise<SessionEntry
 declare function deleteEntriesByIds(handle: DB, ids: string[]): Promise<void>;
 /** Low-level: insert a raw entry row (for compaction/squash/branch_summary/steering). */
 declare function insertEntry(handle: DB, values: typeof sessionEntries.$inferInsert): Promise<typeof sessionEntries.$inferSelect>;
-export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, };
+export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, getSteeringAsMessages, insertEntry, };

package/dist/session/message.js

@@ -104,6 +104,26 @@ async function getMessages(handle, sessionId, opts) {
         .offset(opts?.offset ?? 0);
     return rows.map(rowToMessage);
 }
+/**
+ * 会话 steering 条目映射为 Message 形态（role='user'，内容为 steering part）。
+ * 时间线渲染与消息合并使用（P0：追加指令持久化后的展示路径）；
+ * 不并入 getMessages——compaction/shake/export 等仅处理真实消息的消费者不受影响。
+ */
+async function getSteeringAsMessages(handle, sessionId) {
+    const rows = await handle.db
+        .select()
+        .from(sessionEntries)
+        .where(and(eq(sessionEntries.sessionId, sessionId), eq(sessionEntries.tag, 'steering')))
+        .orderBy(asc(sessionEntries.createdAt));
+    return rows.map((row) => ({
+        id: row.id,
+        sessionId: row.sessionId,
+        role: 'user',
+        content: [{ _tag: 'steering', text: row.content.text ?? '' }],
+        tokenCount: row.tokenCount ?? 0,
+        createdAt: toEpochMs(row.createdAt),
+    }));
+}
 /** Count messages in a session. */
 async function getMessageCount(handle, sessionId) {
     const [result] = await handle.db
@@ -142,4 +162,4 @@ async function insertEntry(handle, values) {
         throw new Error('Failed to insert entry');
     return row;
 }
-export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, };
+export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, getSteeringAsMessages, insertEntry, };

package/dist/session/session.d.ts

@@ -2,39 +2,144 @@ import type { DB } from '../db/client.js';
 import { sessions } from '../db/schema.js';
 import type { LLMSegment } from '../shared/types/agent.js';
 import type { ChatTool } from '../shared/types/llm.js';
-import type { LastRun, Session } from '../shared/types/message.js';
+import type { LastRun, Session, SessionMetadata } from '../shared/types/message.js';
 /** Convert a DB row (with Date timestamps) to the shared Session type (with number timestamps). */
 export declare function rowToSession(row: typeof sessions.$inferSelect): Session;
 /** Create a new root session. */
-declare function createSession(handle: DB, title: string, projectId?: string, agentType?: string, source?: 'web' | 'cli'): Promise<Session>;
+declare function createSession(handle: DB, title: string, projectId?: string, agentType?: string, source?: 'web' | 'cli', 
+/** P1 会话树治理：子 agent 会话挂到父会话（树内嵌套 + 删除级联）。 */
+parentId?: string): Promise<Session>;
 /** Get a session by id, or null if not found. */
 declare function getSession(handle: DB, id: string): Promise<Session | null>;
 /** List all active sessions (未软删除、非 CLI 来源；source 为 NULL 的旧数据视为 web). */
 declare function listSessions(handle: DB): Promise<Session[]>;
 /** 列出所有未软删除会话（含 CLI 来源；供 ACP/CLI 等非 Web 消费者使用）。 */
 declare function listAllSessions(handle: DB): Promise<Session[]>;
-/** List soft-deleted sessions (回收站). */
-declare function listDeletedSessions(handle: DB): Promise<Session[]>;
+/** List soft-deleted sessions (回收站)；projectId 提供时仅列出归属该项目的会话
+ *  （P1-7：回收站此前全库共享，项目 A 的界面能清空项目 B 的删除会话）。 */
+declare function listDeletedSessions(handle: DB, projectId?: string): Promise<Session[]>;
+/** 列出未归属任何项目的已软删除会话（孤儿）。删除项目时 FK set null 使会话失去 projectId，
+ *  在任何项目的回收站视图都不可见（F1），需专门的全局视图暴露以便恢复/归巢。 */
+declare function listOrphanDeletedSessions(handle: DB): Promise<Session[]>;
+/**
+ * 标记回收站条目「已被用户看到」，记录 metadata.trashSeenAt = now（仅首次，不重置）。
+ * 回收站保留期自首次看到起算（见 purgeDeletedSessions）。软删除时会清除旧标记，
+ * 恢复后再次删除须重新看到回收站才重新起算——避免「未重新看到就被过早清空」。
+ * scope.orphan=true 时仅标记未归属项目的孤儿会话（与 listOrphanDeletedSessions 对齐）；
+ * 孤儿标记仅在用户展开「未归属项目」分组时由前端显式调用（POST /deleted/orphans/seen），
+ * 避免打开任意项目回收站连带启动无关孤儿条目的倒计时。
+ */
+declare function touchTrashSeen(handle: DB, scope?: {
+    projectId?: string;
+    orphan?: boolean;
+}): Promise<number>;
 /**
  * 软删除会话（级联其所有 fork 后代）。设置 deletedAt = now；
- * 30 天后由 purgeDeletedSessions 物理清除。
+ * 60 天后由 purgeDeletedSessions 物理清除（到期先标记、宽限 7 天）。
+ * A3：同时清除 trashSeenAt/purgePendingAt——恢复后重删的会话必须重新被
+ * 用户看到才重新起算，宽限期标记不跨删除周期生效。
  * 会话不存在或已在回收站 → 返回 false（调用方按 404 处理）。
  */
 declare function softDeleteSession(handle: DB, id: string): Promise<boolean>;
+/**
+ * A3：清除回收站倒计时/宽限期标记（软删除与项目删除共用）。
+ * 恢复后重删的会话须重新被看到才重新起算；宽限期标记不跨删除周期生效。
+ * 无标记时原样返回，避免无谓的 jsonb 覆写。
+ */
+declare function clearTrashMarks(meta: SessionMetadata): SessionMetadata;
+/**
+ * 把会话归属到指定项目（P1-2 孤儿会话补救）：设置 projectId 与 worktreePath。
+ * 会话不存在返回 false。
+ */
+declare function rebindSession(handle: DB, id: string, project: {
+    id: string;
+    worktree: string;
+}): Promise<boolean>;
 /**
  * 从回收站恢复会话：默认连带恢复其已软删除的祖先链——
  * 否则恢复的会话因父仍在回收站而游离于会话树之外（P2-1：UI 不可达）。
  * 祖先中未删除的（活跃）节点不需要也不应该被改动。
+ *
+ * P2 修复：删除级联后代入回收站，恢复同样级联还原目标会话的整棵后代子树——
+ * 否则「删除根会话 → 恢复根会话」后分支仍滞留回收站且无任何提示，保留期后被清。
+ * 兄弟分支（祖先的其他后代）不受影响。
  */
-declare function restoreSession(handle: DB, id: string): Promise<boolean>;
+export type RestoreResult = {
+    restored: boolean;
+    /** 为可达性连带还原的祖先会话数量（不含目标会话与其同批次后代）。 */
+    restoredAncestorCount: number;
+    /** 是否连带还原了与目标非同一次删除批次的祖先（用户早先单独删除的会话）。 */
+    crossedBatchAncestor: boolean;
+    /**
+     * A2：已删除但未随本次恢复的后代数量（删除批次不同——典型场景是项目删除时
+     * 各会话批次断裂）。这些 fork 分支滞留在回收站，必须显式告知用户单独恢复，
+     * 否则会被静默物理清除。
+     */
+    leftBehindDescendantCount: number;
+};
+declare function restoreSessionCore(handle: DB, id: string, opts?: {
+    includeDescendants?: boolean;
+}): Promise<RestoreResult>;
+declare function restoreSession(handle: DB, id: string, opts?: {
+    includeDescendants?: boolean;
+}): Promise<boolean>;
 /**
- * 物理清除回收站中超过保留期（默认 30 天）的会话。
- * 子会话先于父会话删除（自引用 FK 要求）。
- * 返回清除数量。启动时与每日定时调用。
+ * P2-4：回收站保留期 60 天（原 30 天），自「用户首次在回收站看到该条目」
+ * （metadata.trashSeenAt）起算，而非删除时间（墙钟）——否则用户删除后长期不开服务、
+ * 重启即被静默物理清除，从未见过任何倒计时。临时会话（CLI print / workflow）保留期
+ * 仍为 30 天，见 purgeTemporarySessions。
+ */
+export declare const TRASH_RETENTION_MS: number;
+/**
+ * A3：到期标记 → 物理清除的宽限期（默认 7 天）。
+ * 条目到期后先写 metadata.purgePendingAt，UI 显示「即将清除」并可恢复；
+ * 宽限期满才物理清除——杜绝「到期即静默物理清空」的数据丢失死角。
+ */
+export declare const TRASH_PURGE_GRACE_MS: number;
+/** 清除结果：marked = 本次新标记进入宽限期的条目数；deleted = 本次物理清除数。 */
+export type TrashPurgeResult = {
+    marked: number;
+    deleted: number;
+};
+/**
+ * 回收站两阶段清理（启动时与每日定时调用）：
+ * 阶段一：trashSeenAt 超过保留期且未标记 → 标记 purgePendingAt（进入宽限期，可恢复）。
+ * 阶段二：purgePendingAt 早于宽限截止 → 物理清除（子会话先于父，自引用 FK 要求）。
+ * 未被看到过（trashSeenAt 缺失）或恢复后重删、尚未重新看到的会话永不进入任一阶段。
  */
-declare function purgeDeletedSessions(handle: DB, retentionMs?: number): Promise<number>;
+declare function purgeDeletedSessions(handle: DB, retentionMs?: number, graceMs?: number): Promise<TrashPurgeResult>;
+/**
+ * C4：清理长期空置的 web 会话（无任何条目、无子会话、未删除、创建早于保留期）。
+ * 覆盖「新建会话后未发言」的残留：首条消息失败清理依赖前端 JS 执行，
+ * 崩溃/断电/离线时必然残留空「New Session」行。CLI 临时会话由 purgeTemporarySessions 负责。
+ */
+declare function purgeEmptySessions(handle: DB, retentionMs?: number): Promise<number>;
 /** Update a session's title. */
 declare function updateSessionTitle(handle: DB, id: string, title: string): Promise<void>;
+/**
+ * 彻底删除某个回收站会话及其全部后代（含未软删除的 fork 后代，防御数据异常）。
+ * 子会话先于父会话删除（自引用 FK RESTRICT 要求）；entries/archives 经 FK cascade 清理。
+ * 返回删除数量。会话不存在或不在回收站 → 返回 0。
+ */
+declare function permanentlyDeleteSession(handle: DB, id: string): Promise<number>;
+/** 清空回收站：物理删除所有已软删除会话（子先于父）。返回删除数量。
+ *  projectId 提供时仅清空该项目（P1-7）。 */
+declare function emptyTrash(handle: DB, projectId?: string): Promise<number>;
+/**
+ * 清理过期临时会话（P2 → P1 收紧：仅清理显式标记的临时会话）。
+ * - agentType='print'：CLI 一次性问答（c0de chat，非 --continue）创建的会话。
+ * - agentType='workflow'：工作流运行产生的会话。
+ * 普通 CLI 会话（ACP）与 --continue 续接的会话（续接时已升级）永不清理——
+ * 此前按 source='cli' 全删会把用户显式续接的历史静默物理删除。
+ * 保留期默认 30 天；子条目经 FK cascade 一并删除。
+ * 返回清除数量。启动时与每日定时调用。
+ */
+declare function purgeTemporarySessions(handle: DB, retentionMs?: number): Promise<number>;
+/**
+ * 把临时会话升级为持久会话（--continue 续接时调用）：
+ * 清除 print 标记，30 天临时清理不再触及。
+ */
+declare function upgradeTemporarySession(handle: DB, id: string): Promise<void>;
 /** Bump updatedAt to now (used after appending messages). */
 declare function touchSession(handle: DB, id: string): Promise<void>;
 /** 记录会话上次打开时间（用于会话列表按最近打开排序）。 */
@@ -56,4 +161,16 @@ export declare function saveLLMSegments(handle: DB, id: string, segments: LLMSeg
 /** 更新会话 metadata.lastRun（agent run 开始/结束时写入；重启后检测中断用）。 */
 declare function updateSessionLastRun(handle: DB, id: string, lastRun: LastRun): Promise<void>;
 declare function listSessionsByProject(handle: DB, projectId: string): Promise<Session[]>;
-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' }。
+ */
+declare function searchSessions(handle: DB, query: string, projectId?: string, opts?: {
+    includeDeleted?: boolean;
+}): Promise<Array<{
+    session: Session;
+    matchedBy: 'title' | 'content';
+}>>;
+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, };