c0de-agent 1.9.0 → 1.11.0

package/dist/server/server.js

@@ -1,4 +1,5 @@
 // src/server/server.ts
+import { randomBytes } from 'node:crypto';
 import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { connect as tcpConnect } from 'node:net';
 import { homedir } from 'node:os';
@@ -12,10 +13,13 @@ import { createAndPopulateRegistry } from '../core/workflows/index.js';
 import { createDB, migrateDB } from '../db/index.js';
 import { createRegistry, overrideToCapabilities, rebuildRegistry, registerProvider, } from '../llm/registry.js';
 import { initPlugins } from '../plugins/index.js';
+import { purgeDeletedSessions } from '../session/session.js';
 import { createDefaultRegistry, createDefaultURLRegistry } from '../tools/index.js';
 import { checkForUpdate, createHandoffServer, createUpdateScheduler, requestHandoff, restoreSessions, } from '../update/index.js';
 import { createAgentManager } from './agent-manager.js';
 import { createApp } from './app.js';
+import { createAuthManager } from './auth-manager.js';
+import { isAllowedOrigin } from './middleware/cors.js';
 import { createPermissionStore } from './permission/store.js';
 import { PTYManager } from './terminal/pty-manager.js';
 /** 把 config.providers 注册到新建的 LLM registry（修复此前空 registry 的遗漏）。 */
@@ -75,6 +79,59 @@ function resolveDbDir() {
         return envDir;
     return join(resolveGlobalDataRoot(), 'pglite');
 }
+/**
+ * 认证 token 解析（P0 安全修复）：
+ * 1. security.authEnabled 显式为 false → 无认证（用户显式选择）。
+ * 2. 用户配置 security.token → 使用。
+ * 3. 环境变量 C0DE_AUTH_TOKEN（热更新新实例经 updater 传入）→ 采用并落盘。
+ * 4. dataDir 下 auth-token 文件（跨重启/热更新稳定）→ 复用。
+ * 5. 都没有 → 生成随机 token 并写入 auth-token（0600）。
+ */
+function resolveAuthToken(config, dataDir) {
+    if (config.security.authEnabled === false)
+        return undefined;
+    if (config.security.token && config.security.token.length > 0)
+        return config.security.token;
+    const tokenFile = join(dataDir, 'auth-token');
+    const envToken = process.env.C0DE_AUTH_TOKEN;
+    if (envToken) {
+        try {
+            mkdirSync(dataDir, { recursive: true });
+            writeFileSync(tokenFile, envToken, { mode: 0o600 });
+        }
+        catch {
+            // 落盘失败不影响本次运行
+        }
+        return envToken;
+    }
+    try {
+        const existing = readFileSync(tokenFile, 'utf-8').trim();
+        if (existing)
+            return existing;
+    }
+    catch {
+        // 文件不存在，走生成分支
+    }
+    const generated = randomBytes(24).toString('hex');
+    try {
+        mkdirSync(dataDir, { recursive: true });
+        writeFileSync(tokenFile, generated, { mode: 0o600 });
+    }
+    catch {
+        // 落盘失败：本次运行仍可用内存 token
+    }
+    return generated;
+}
+/** 只读 dataDir 下已存在的 auth-token（新实例 handoff 握手用；不生成）。 */
+function readAuthTokenFile(dataDir) {
+    try {
+        const t = readFileSync(join(dataDir, 'auth-token'), 'utf-8').trim();
+        return t || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** 一次性迁移：<cwd>/.c0de/pglite → 全局路径。仅当目标不存在时执行。
  *
  * 多个项目各有 .c0de/pglite 时只迁移第一个遇到的（首次启动即触发）；
@@ -130,6 +187,16 @@ async function buildServerContext(db, opts = {}) {
     // 工作流注册表：三级发现（builtin → global → project），eager 初始化。
     // 此前是惰性 getter 只注册 builtin，导致项目级 .c0de/workflows/*.js 永远不可见。
     const workflowRegistry = await createAndPopulateRegistry(cwd);
+    const dataDir = resolveDbDir();
+    // 先解析/生成 bootstrap token（落盘），再创建 authManager 读取——
+    // 首启时文件由 resolveAuthToken 生成，顺序颠倒会导致 bootstrap 读到空值。
+    const resolvedToken = resolveAuthToken(config, dataDir);
+    const authManager = createAuthManager({
+        dataDir,
+        ...(config.security.token && config.security.token.length > 0
+            ? { staticToken: config.security.token }
+            : {}),
+    });
     const ctx = {
         db,
         config,
@@ -141,6 +208,9 @@ async function buildServerContext(db, opts = {}) {
         agentManager: createAgentManager(),
         permissionStore: createPermissionStore(),
         permissionMode: config.permission.defaultMode,
+        sessionPermissionModes: new Map(),
+        authToken: resolvedToken,
+        authManager: config.security.authEnabled === false ? undefined : authManager,
         // Agent 注册表：内置 4 个默认 agent；项目/用户自定义 agent 可在启动后补充加载。
         agentRegistry: (() => {
             const reg = createAgentRegistry();
@@ -158,30 +228,18 @@ async function buildServerContext(db, opts = {}) {
         cwd,
         ptyManager: new PTYManager(),
     };
-    // spec §18.3 handoff server：旧实例监听随机端口，收到 POST /handoff 时
-    // 序列化当前会话状态 + 优雅关闭，让新实例接管。config.update.enabled=false
-    // 或测试 skipHandoff 时跳过（减少后台资源占用）。
-    let handoffServer;
-    if (config.update.enabled && !opts.skipHandoff) {
-        const createHandoff = opts.createHandoffFn ?? createHandoffServer;
-        handoffServer = await createHandoff(async () => {
-            // 序列化在热更新主链路（performHotUpdate）已完成；handoff 回调只需释放资源。
-            // 这里提前停 scheduler 以避免 close 期间还在跑检查。
-            ctx.updateScheduler.stop();
-        });
-        ctx.handoff = { port: handoffServer.port, server: handoffServer };
-    }
+    // handoff server 不在此创建：它需要持有主 HTTP server 引用以触发完整关停，
+    // 由 startServer 在 serve() 之后创建（dev 模式走 vite，不创建）。
     return {
         ctx,
         dispose: async () => {
             // dev 重建前调用：中止活跃 run + settle pending permission +
-            // 停 scheduler + 关 handoff。**不 close db**（调用方持有）。
+            // 停 scheduler + 关 devices.json watcher。**不 close db**（调用方持有）。
             ctx.agentManager.dispose();
             ctx.permissionStore.dispose();
             ctx.updateScheduler.stop();
             ctx.ptyManager.dispose();
-            if (handoffServer)
-                await handoffServer.close();
+            ctx.authManager?.dispose();
         },
     };
 }
@@ -288,9 +346,26 @@ async function bootstrapServerContext(opts = {}) {
         db = await createDevDb(cwd);
     }
     const { ctx, dispose } = await buildServerContext(db, opts);
+    // 回收站清理：启动时清一次 + 每 24h 清一次（软删除保留 30 天）。
+    // fire-and-forget：清理失败不阻塞服务启动。
+    void purgeDeletedSessions(db).catch(() => { });
+    const purgeTimer = setInterval(() => {
+        void purgeDeletedSessions(db).catch(() => { });
+    }, 24 * 60 * 60 * 1000);
+    purgeTimer.unref();
+    // P2-15：PGLite WAL 周期刷盘（30s），缩短 kill -9 等突然停机时的已提交数据丢失窗口。
+    const syncTimer = db.sync
+        ? setInterval(() => {
+            void db.sync?.().catch(() => { });
+        }, 30_000)
+        : null;
+    syncTimer?.unref();
     return {
         ctx,
         close: async () => {
+            clearInterval(purgeTimer);
+            if (syncTimer)
+                clearInterval(syncTimer);
             await dispose();
             if (ownsDb)
                 await db.close();
@@ -301,13 +376,24 @@ async function bootstrapServerContext(opts = {}) {
  * 请求旧实例 handoff 后轮询端口释放（spec §18.3）。旧实例收到 /handoff 后
  * 优雅退出释放端口；新实例轮询 TCP 连接直到被拒（端口已释放）或超时报错。
  */
-async function requestHandoffWithRetry(port, maxAttempts = 30, delayMs = 100) {
+async function requestHandoffWithRetry(port, token, maxAttempts = 30, delayMs = 100) {
     try {
-        await requestHandoff(port);
+        await requestHandoff(port, '127.0.0.1', token);
     }
-    catch {
-        // 旧实例未启 handoff 端点（update 未启用）；直接尝试绑端口。
-        return;
+    catch (err) {
+        const handoffErr = err;
+        // 连接层失败（ECONNREFUSED 等）：旧实例未启 handoff 端点（update 未启用）；
+        // 直接尝试绑端口。
+        if (handoffErr?.kind === 'connect')
+            return;
+        // HTTP 401：旧实例存在但 auth token 不匹配——立即明确报错退出。若继续
+        // bind 必撞 EADDRINUSE，把真实原因（token 校验失败）误报成端口占用。
+        if (handoffErr?.kind === 'http' && handoffErr.status === 401) {
+            throw new Error(`handoff: 端口 ${port} 上的旧实例拒绝让渡（HTTP 401：auth token 不匹配）。\n` +
+                `新旧实例须共享同一 token（C0DE_AUTH_TOKEN 环境变量或数据目录 auth-token 文件），\n` +
+                `请核对配置后重试。`);
+        }
+        throw err;
     }
     for (let i = 0; i < maxAttempts; i++) {
         const released = await new Promise((resolve) => {
@@ -327,8 +413,10 @@ async function requestHandoffWithRetry(port, maxAttempts = 30, delayMs = 100) {
 async function startServer(opts = {}) {
     const port = opts.port ?? 3000;
     // spec §18.3：新实例从 --handoff-port 拿到旧实例端口，请求优雅退出后绑端口。
+    // 握手 token：updater spawn 时经 C0DE_AUTH_TOKEN 环境变量传入，否则读 auth-token 文件。
     if (opts.handoffPort && !opts.skipHandoff) {
-        await requestHandoffWithRetry(opts.handoffPort);
+        const pendingToken = process.env.C0DE_AUTH_TOKEN ?? readAuthTokenFile(resolveDbDir());
+        await requestHandoffWithRetry(opts.handoffPort, pendingToken);
     }
     const { ctx, close: closeCtx } = await bootstrapServerContext(opts);
     const app = createApp(ctx);
@@ -336,10 +424,10 @@ async function startServer(opts = {}) {
     if (ctx.config.update.enabled)
         ctx.updateScheduler.start();
     const server = serve({ fetch: app.fetch, port });
+    ctx.port = port;
     // WebSocket：终端双向流。Hono v2 无原生 WS，用 ws 包直接挂载到 HTTP server。
     // 匹配 /api/terminal/:id/ws → ptyManager.attachWebSocket
     const wss = new WebSocketServer({ noServer: true });
-    const expectedToken = ctx.config.security.authEnabled ? ctx.config.security.token : undefined;
     server.on('upgrade', (req, socket, head) => {
         const url = new URL(req.url ?? '', `http://${req.headers.host ?? 'localhost'}`);
         const match = url.pathname.match(/^\/api\/terminal\/([^/]+)\/ws$/);
@@ -347,10 +435,22 @@ async function startServer(opts = {}) {
             socket.destroy();
             return;
         }
-        // 认证：token 通过 query 参数传递（浏览器 WS 无法设置 Authorization header）
-        if (expectedToken) {
+        // Origin 校验：浏览器 WS 不受 CORS 约束，必须在服务端显式校验。
+        // 非浏览器客户端（无 Origin 头）放行——token 仍是硬门槛。
+        const origin = req.headers.origin;
+        if (origin && !isAllowedOrigin(origin, ctx.config.security.allowedOrigins)) {
+            socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        // 认证：token 通过 query 参数传递（浏览器 WS 无法设置 Authorization header）。
+        // P2-16：优先 authManager 校验（设备 token）；回退 ctx.authToken 兼容测试上下文。
+        if (ctx.authManager || ctx.authToken) {
             const token = url.searchParams.get('token');
-            if (token !== expectedToken) {
+            const ok = ctx.authManager
+                ? ctx.authManager.verify(token ?? undefined)
+                : token === ctx.authToken;
+            if (!ok) {
                 socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
                 socket.destroy();
                 return;
@@ -370,7 +470,7 @@ async function startServer(opts = {}) {
         });
     });
     let closed = false;
-    const close = async () => {
+    const closeMain = async () => {
         if (closed)
             return;
         closed = true;
@@ -378,6 +478,26 @@ async function startServer(opts = {}) {
         server.close();
         await closeCtx();
     };
-    return { app, port, close };
+    const close = async () => {
+        await closeMain();
+        await handoffServer?.close();
+    };
+    // spec §18.3 handoff server：旧实例收到 POST /handoff 后关闭主服务与资源，
+    // 响应 200，随后退出进程（exitAfterResponse），端口让渡给新实例。
+    // config.update.enabled=false 或 skipHandoff 时跳过。
+    let handoffServer;
+    if (ctx.config.update.enabled && !opts.skipHandoff) {
+        const createHandoff = opts.createHandoffFn ?? createHandoffServer;
+        handoffServer = await createHandoff(closeMain, {
+            // P2-16：token 轮换后新旧实例 bootstrap 可能不同，用 verifyHandoff 接受
+            // 当前/历史 bootstrap 与设备 token；无 authManager 回退字符串比较。
+            ...(ctx.authManager
+                ? { verify: (t) => ctx.authManager?.verifyHandoff(t) ?? false }
+                : { expectedToken: ctx.authToken }),
+            exitAfterResponse: true,
+        });
+        ctx.handoff = { port: handoffServer.port, server: handoffServer };
+    }
+    return { app, port, close, ...(ctx.authToken ? { authToken: ctx.authToken } : {}) };
 }
-export { bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, releaseDevDbLock, resolveDbDir, startServer, syncRegistryFromConfig, };
+export { acquireDevDbLock, bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, releaseDevDbLock, resolveAuthToken, resolveDbDir, startServer, syncRegistryFromConfig, };

package/dist/server/types.d.ts

@@ -8,9 +8,10 @@ import type { Config as SharedConfig } from '../shared/types/config.js';
 import type { URLRegistry } from '../shared/types/tool.js';
 import type { ToolRegistry } from '../tools/types.js';
 import type { HandoffServer, UpdateScheduler } from '../update/index.js';
-import type { PTYManager } from './terminal/pty-manager.js';
 import type { AgentManager } from './agent-manager.js';
+import type { AuthManager } from './auth-manager.js';
 import type { PermissionStore } from './permission/store.js';
+import type { PTYManager } from './terminal/pty-manager.js';
 /** 持有所有服务依赖的不可变上下文（config 字段可变用于 PATCH 更新）。 */
 type ServerContext = {
     db: DB;
@@ -26,8 +27,22 @@ type ServerContext = {
     agentManager: AgentManager;
     /** 全局权限确认 store（单例），独立于 agent run 生命周期。 */
     permissionStore: PermissionStore;
-    /** 全局授权模式（运行时可临时切换）：'default' 逐个确认；'auto' 自动放行 ask 工具（YOLO）。启动时取 config.permission.defaultMode，PUT /api/permissions 临时切换不回写 config。 */
+    /** 默认授权模式（config.permission.defaultMode）。 */
     permissionMode: 'default' | 'auto';
+    /** 会话级授权模式覆盖：Map<sessionId, mode>。会话未覆盖时回退 permissionMode。
+     *  P1-5：auto 是高风险状态，按会话隔离避免一个标签页切换影响全部会话。 */
+    sessionPermissionModes: Map<string, 'default' | 'auto'>;
+    /**
+     * API Bearer token（认证未显式关闭时必存在）。
+     * 用户配置 security.token 优先；否则自动生成并持久化到数据目录 auth-token 文件
+     * （跨重启/热更新稳定，浏览器首访经 ?token= URL 获取后本地保存）。
+     * P2-16：bootstrap token 仅用于首设备注册；注册后轮换，API 请求认设备 token。
+     */
+    authToken?: string;
+    /** 认证管理器（token 轮换 + 设备配对审批，P2-16）。authEnabled=false 或测试上下文为 undefined。 */
+    authManager?: AuthManager;
+    /** 主 HTTP 服务实际绑定端口（startServer 绑定后回填；热更新 spawn 新实例复用）。 */
+    port?: number;
     /** Agent 类型注册表（spec: multi-agent-design）。注入 agent loop 的 runSubAgent。 */
     agentRegistry: AgentRegistry;
     /** 工作流注册表（spec: dynamic-workflow-design）。注入 /workflow slash 命令和 workflowz steering。 */

package/dist/session/archive.d.ts

@@ -1,7 +1,7 @@
 import type { DB } from '../db/client.js';
 import type { ArchiveRef, CompactionArchive, SessionEntry } from './types.js';
 /** Archive original entries before compaction/squash. Returns the archive id. */
-declare function archiveOriginalEntries(handle: DB, sessionId: string, entries: SessionEntry[], archiveType: 'compaction' | 'squash' | 'shake', summary: string, compactionId: string): Promise<string>;
+declare function archiveOriginalEntries(handle: DB, sessionId: string, entries: SessionEntry[], archiveType: 'compaction' | 'squash' | 'shake' | 'clear', summary: string, compactionId: string): Promise<string>;
 /** Get an archive by id. Returns null for invalid or non-existent ids. */
 declare function getArchive(handle: DB, id: string): Promise<CompactionArchive | null>;
 /** Get the original entries stored in an archive. */

package/dist/session/branch.d.ts

@@ -1,11 +1,20 @@
 import type { DB } from '../db/client.js';
 import type { Session, SessionTreeNode } from './types.js';
-/** Fork a session at a message index — copies messages 0..index into a new child session. */
+/**
+ * fork 分支点 messageIndex 越界（评审 NIT：客户端索引过期/分页 bug）。
+ * 与「会话不存在」区分开：消费路由应映射 400 并透出 message，而非 404。
+ */
+declare class BranchPointOutOfRangeError extends Error {
+    constructor(messageIndex: number);
+}
+/** Fork a session at a message index — copies all entries (messages + tool pairs)
+ *  up to and including the branch point message, plus latest file snapshots. */
 declare function forkSession(handle: DB, sessionId: string, messageIndex: number): Promise<Session>;
 /** Get direct child sessions (branches) of a session. */
 declare function getBranches(handle: DB, sessionId: string): Promise<Session[]>;
 /** Build a full session tree from root sessions down.
  * 每层按 metadata.lastOpenedAt 降序（fallback updatedAt、createdAt）。
+ * 排除软删除会话与 CLI 来源会话（Web 树仅展示 web 会话）。
  */
 declare function getTree(handle: DB): Promise<SessionTreeNode[]>;
-export { forkSession, getBranches, getTree };
+export { BranchPointOutOfRangeError, forkSession, getBranches, getTree };

package/dist/session/branch.js

@@ -1,54 +1,130 @@
-import { eq } from 'drizzle-orm';
+import { and, eq, isNull, ne, or } from 'drizzle-orm';
 import { sessions } from '../db/schema.js';
 import { generateId } from '../shared/index.js';
-import { getMessages, insertEntry } from './message.js';
+import { getEntries, insertEntry } from './message.js';
 import { createSession, getSession, rowToSession } from './session.js';
-/** Fork a session at a message index — copies messages 0..index into a new child session. */
+import { copyFileSnapshots } from './snapshot.js';
+/**
+ * fork 分支点 messageIndex 越界（评审 NIT：客户端索引过期/分页 bug）。
+ * 与「会话不存在」区分开：消费路由应映射 400 并透出 message，而非 404。
+ */
+class BranchPointOutOfRangeError extends Error {
+    constructor(messageIndex) {
+        super(`Branch point message index ${messageIndex} out of range`);
+        this.name = 'BranchPointOutOfRangeError';
+    }
+}
+/** 把 SessionEntry 还原为 sessionEntries 原始行（fork 复制用）。 */
+function entryToRow(e, sessionId) {
+    const id = generateId();
+    // Message 无 _tag（共享类型）；其余条目经 _tag 判别。
+    if (!('_tag' in e)) {
+        return {
+            id,
+            sessionId,
+            tag: 'message',
+            role: e.role,
+            content: e.content,
+            tokenCount: e.tokenCount,
+        };
+    }
+    switch (e._tag) {
+        case 'compaction':
+            return {
+                id,
+                sessionId,
+                tag: 'compaction',
+                content: {
+                    summary: e.summary,
+                    originalEntryIds: e.originalEntryIds,
+                    archiveId: e.archiveId,
+                },
+                tokenCount: e.tokenCount,
+            };
+        case 'squash':
+            return {
+                id,
+                sessionId,
+                tag: 'squash',
+                content: {
+                    summary: e.summary,
+                    squashedEntryIds: e.squashedEntryIds,
+                    archiveId: e.archiveId,
+                },
+                tokenCount: e.tokenCount,
+            };
+        case 'branch_summary':
+            return {
+                id,
+                sessionId,
+                tag: 'branch_summary',
+                content: { summary: e.summary, sourceSessionId: e.sourceSessionId },
+            };
+        case 'steering':
+            return { id, sessionId, tag: 'steering', content: { text: e.content } };
+    }
+}
+/** Fork a session at a message index — copies all entries (messages + tool pairs)
+ *  up to and including the branch point message, plus latest file snapshots. */
 async function forkSession(handle, sessionId, messageIndex) {
     const source = await getSession(handle, sessionId);
     if (!source)
         throw new Error(`Session not found: ${sessionId}`);
-    const messages = await getMessages(handle, sessionId);
-    const toCopy = messages.slice(0, messageIndex + 1);
-    const forked = await createSession(handle, `Branch of ${source.title}`, source.projectId ?? undefined);
-    await handle.db
-        .update(sessions)
-        .set({ parentId: sessionId, branchPoint: messageIndex })
-        .where(eq(sessions.id, forked.id));
-    for (const msg of toCopy) {
-        await insertEntry(handle, {
+    const entries = await getEntries(handle, sessionId);
+    const msgEntries = entries.filter((e) => !('_tag' in e));
+    const target = msgEntries[messageIndex];
+    if (!target) {
+        throw new BranchPointOutOfRangeError(messageIndex);
+    }
+    const targetIdx = entries.findIndex((e) => e.id === target.id);
+    const toCopy = entries.slice(0, targetIdx + 1);
+    // 多表写入（sessions insert/update + sessionEntries 复制 + 快照复制）包单个事务：
+    // 中途失败整体回滚，不残留永久可见的半成品分支（同 compactSession/squashRecent 写法）。
+    const updated = await handle.db.transaction(async (tx) => {
+        const txHandle = { db: tx, close: handle.close };
+        const forked = await createSession(txHandle, `Branch of ${source.title}`, source.projectId ?? undefined, undefined, source.source === 'cli' ? 'cli' : 'web');
+        await tx
+            .update(sessions)
+            .set({ parentId: sessionId, branchPoint: messageIndex })
+            .where(eq(sessions.id, forked.id));
+        for (const e of toCopy) {
+            await insertEntry(txHandle, entryToRow(e, forked.id));
+        }
+        await insertEntry(txHandle, {
             id: generateId(),
             sessionId: forked.id,
-            tag: 'message',
-            role: msg.role,
-            content: msg.content,
-            tokenCount: msg.tokenCount,
+            tag: 'branch_summary',
+            content: {
+                summary: `Branched from session ${sessionId} at message ${messageIndex}`,
+                sourceSessionId: sessionId,
+            },
         });
-    }
-    await insertEntry(handle, {
-        id: generateId(),
-        sessionId: forked.id,
-        tag: 'branch_summary',
-        content: {
-            summary: `Branched from session ${sessionId} at message ${messageIndex}`,
-            sourceSessionId: sessionId,
-        },
+        // 复制源会话最新文件快照（P1-4：@文件上下文随分支保留）。
+        await copyFileSnapshots(txHandle, sessionId, forked.id);
+        const created = await getSession(txHandle, forked.id);
+        if (!created)
+            throw new Error('Forked session not found after creation');
+        return created;
     });
-    const updated = await getSession(handle, forked.id);
-    if (!updated)
-        throw new Error('Forked session not found after creation');
     return updated;
 }
 /** Get direct child sessions (branches) of a session. */
 async function getBranches(handle, sessionId) {
-    const rows = await handle.db.select().from(sessions).where(eq(sessions.parentId, sessionId));
+    const rows = await handle.db
+        .select()
+        .from(sessions)
+        .where(and(eq(sessions.parentId, sessionId), isNull(sessions.deletedAt)));
     return rows.map(rowToSession);
 }
 /** Build a full session tree from root sessions down.
  * 每层按 metadata.lastOpenedAt 降序（fallback updatedAt、createdAt）。
+ * 排除软删除会话与 CLI 来源会话（Web 树仅展示 web 会话）。
  */
 async function getTree(handle) {
-    const rows = await handle.db.select().from(sessions);
+    const rows = await handle.db
+        .select()
+        .from(sessions)
+        .where(and(isNull(sessions.deletedAt), or(isNull(sessions.source), ne(sessions.source, 'cli'))));
     const byParent = new Map();
     for (const row of rows) {
         const session = rowToSession(row);
@@ -67,4 +143,4 @@ async function getTree(handle) {
     }));
     return build(null);
 }
-export { forkSession, getBranches, getTree };
+export { BranchPointOutOfRangeError, forkSession, getBranches, getTree };

package/dist/session/compaction.js

@@ -228,6 +228,7 @@ async function compactSession(handle, sessionId, summarizer, config) {
         if (config?.preserveSnapshots !== false) {
             const hotFiles = extractHotFiles(compactMessages);
             for (const file of hotFiles) {
+                // 不传 mtimeMs：由 upsertFileSnapshot 从已有行透传，压缩后热文件不误判过期。
                 const id = await upsertFileSnapshot(txHandle, sessionId, file.path, file.content);
                 fileSnapshotIds.push(id);
             }

package/dist/session/context.d.ts

@@ -8,8 +8,9 @@ declare function messageToChatMessage(msg: Message): ChatMessage;
 declare function entriesToChatMessages(entries: SessionEntry[], snapshots: FileSnapshot[]): ChatMessage[];
 /** Inject file snapshot block after the first message (preserves cache prefix). */
 declare function injectSnapshots(messages: ChatMessage[], snapshots: FileSnapshot[]): ChatMessage[];
-/** Get the full session context: all entries + file snapshots. */
-declare function getSessionContext(handle: DB, sessionId: string): Promise<{
+/** Get the full session context: all entries + file snapshots.
+ *  cwd 提供时刷新过期快照：文件磁盘 mtime 晚于快照记录 → 重读并升版本（P1-5）。 */
+declare function getSessionContext(handle: DB, sessionId: string, cwd?: string): Promise<{
     entries: SessionEntry[];
     snapshots: FileSnapshot[];
 }>;

package/dist/session/context.js

@@ -1,5 +1,7 @@
+import { readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
 import { getEntries } from './message.js';
-import { getFileSnapshots } from './snapshot.js';
+import { getFileSnapshots, upsertFileSnapshot } from './snapshot.js';
 /**
  * Drop tool messages whose id cannot be paired with an assistant tool_call,
  * and inject synthetic tool results for orphan tool_calls (assistant 发出了
@@ -162,12 +164,43 @@ function injectSnapshots(messages, snapshots) {
         return [snapshotMessage];
     return [first, snapshotMessage, ...messages.slice(1)];
 }
-/** Get the full session context: all entries + file snapshots. */
-async function getSessionContext(handle, sessionId) {
+/** Get the full session context: all entries + file snapshots.
+ *  cwd 提供时刷新过期快照：文件磁盘 mtime 晚于快照记录 → 重读并升版本（P1-5）。 */
+async function getSessionContext(handle, sessionId, cwd) {
+    if (cwd)
+        await refreshStaleSnapshots(handle, sessionId, cwd);
     const [entries, snapshots] = await Promise.all([
         getEntries(handle, sessionId),
         getFileSnapshots(handle, sessionId),
     ]);
     return { entries, snapshots };
 }
+/** 比对每个文件最新快照与磁盘 mtime，过期则重读并写入新版本。 */
+async function refreshStaleSnapshots(handle, sessionId, cwd) {
+    const snaps = await getFileSnapshots(handle, sessionId);
+    const latest = new Map();
+    for (const s of snaps) {
+        const prev = latest.get(s.filePath);
+        if (!prev || s.version > prev.version)
+            latest.set(s.filePath, s);
+    }
+    for (const s of latest.values()) {
+        const p = resolve(cwd, s.filePath);
+        // try 只覆盖 fs 错误（stat/readFile）：文件已删除/不可读 → 保留旧快照
+        // （读工具会报错提示模型），跳过该文件继续处理其余快照。
+        const st = await stat(p).catch(() => null);
+        if (!st)
+            continue;
+        // upsertFileSnapshot 落盘时对 mtimeMs 取整（bigint 列），比对侧同样取整，
+        // 避免向下舍入导致"存储值 < 真实值"的永久误判过期。
+        if ((s.mtimeMs ?? 0) >= Math.round(st.mtimeMs))
+            continue;
+        const content = await readFile(p, 'utf-8').catch(() => null);
+        if (content === null)
+            continue;
+        // DB 写入放在 try 之外：upsertFileSnapshot 失败必须向上抛，
+        // 否则过期内容被静默注入上下文（评审 NIT：错误吞没范围过大）。
+        await upsertFileSnapshot(handle, sessionId, s.filePath, content, st.mtimeMs);
+    }
+}
 export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessage };

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, deleteSession, getLLMSegments, getSession, listSessions, migrateLegacyDetails, saveLLMSegments, segmentFingerprint, touchSession, updateSessionTitle, } from './session.js';
+export { createSession, getLLMSegments, getSession, listDeletedSessions, listSessions, migrateLegacyDetails, purgeDeletedSessions, restoreSession, saveLLMSegments, segmentFingerprint, softDeleteSession, touchSession, 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, deleteSession, getLLMSegments, getSession, listSessions, migrateLegacyDetails, saveLLMSegments, segmentFingerprint, touchSession, updateSessionTitle, } from './session.js';
+export { createSession, getLLMSegments, getSession, listDeletedSessions, listSessions, migrateLegacyDetails, purgeDeletedSessions, restoreSession, saveLLMSegments, segmentFingerprint, softDeleteSession, touchSession, updateSessionTitle, } from './session.js';
 export { checkFileSnapshot, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot, } from './snapshot.js';
 export { squashRecent } from './squash.js';
 export { estimateMessageTokens, estimateTokens } from './token.js';