c0de-agent 1.8.0 → 1.10.0

package/dist/server/server.d.ts

@@ -23,6 +23,8 @@ type StartServerOptions = {
 type RunningServer = {
     app: Hono;
     port: number;
+    /** 认证 token（authEnabled=false 时为 undefined）；serve 命令据此打印带 token 的 URL。 */
+    authToken?: string;
     close(): Promise<void>;
 };
 type BootstrappedServer = {
@@ -32,8 +34,10 @@ type BootstrappedServer = {
 /** 把 config.providers 注册到新建的 LLM registry（修复此前空 registry 的遗漏）。 */
 declare function buildRegistryFromConfig(config: Config): Registry;
 /**
- * config 变更后原地同步 registry（清空旧路由 + 重新注册），
- * 使运行中的 ServerContext 立即生效，无需重启。
+ * config 变更后原子地同步 registry：在隔离的 next registry 上重建全部路由，
+ * 完成后一次性替换 registry 内部 table 引用。运行中的 resolveRoute 任何时刻
+ * 看到的都是完整的旧表或完整的新表，不会读到「已清空但未注册完」的半状态，
+ * 因此不会把本可用的 provider 误判为 NoRoute。ServerContext 立即生效，无需重启。
  */
 declare function syncRegistryFromConfig(registry: Registry, config: Config): void;
 /** 解析 PGLite 持久化数据目录：优先 C0DE_DB_DIR，否则全局数据根下 pglite 子目录。
@@ -41,6 +45,15 @@ declare function syncRegistryFromConfig(registry: Registry, config: Config): voi
  * 历史上数据库放在 <cwd>/.c0de/pglite（项目级），但项目 DB schema 通过 projectId
  * 区分项目，设计本意是全局共享单库。旧路径已在 migrateLegacyPglite 中自动迁移。 */
 declare function resolveDbDir(): string;
+/**
+ * 认证 token 解析（P0 安全修复）：
+ * 1. security.authEnabled 显式为 false → 无认证（用户显式选择）。
+ * 2. 用户配置 security.token → 使用。
+ * 3. 环境变量 C0DE_AUTH_TOKEN（热更新新实例经 updater 传入）→ 采用并落盘。
+ * 4. dataDir 下 auth-token 文件（跨重启/热更新稳定）→ 复用。
+ * 5. 都没有 → 生成随机 token 并写入 auth-token（0600）。
+ */
+declare function resolveAuthToken(config: Config, dataDir: string): string | undefined;
 /**
  * 围绕已有 DB handle 组装 ServerContext（不建/不关闭 DB）。
  *
@@ -52,6 +65,18 @@ declare function buildServerContext(db: DB, opts?: StartServerOptions): Promise<
     ctx: ServerContext;
     dispose: () => Promise<void>;
 }>;
+/**
+ * Cross-process guard for PGLite dataDir.
+ *
+ * PGLite is single-writer WASM Postgres — two processes on the same dataDir
+ * always abort (`RuntimeError: Aborted()`). This lock prevents silent
+ * corruption when multiple dev servers (e.g. different ports) target the
+ * same project.
+ *
+ * - Live PID in lock → throw clear error instead of cryptic WASM abort.
+ * - Dead PID in lock → stale: remove `.dev.lock` + `postmaster.pid`, proceed.
+ */
+declare function acquireDevDbLock(dataDir: string): void;
 /** Release the dev DB lock (best-effort, stale-detection covers missed calls). */
 declare function releaseDevDbLock(dataDir: string): void;
 /** dev 专用：创建 + migrate PGLite，跨热重载复用（单写者，只建一次）。 */
@@ -60,4 +85,4 @@ declare function createDevDb(cwd: string): Promise<DB>;
 declare function bootstrapServerContext(opts?: StartServerOptions): Promise<BootstrappedServer>;
 declare function startServer(opts?: StartServerOptions): Promise<RunningServer>;
 export type { BootstrappedServer, RunningServer, StartServerOptions };
-export { bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, releaseDevDbLock, resolveDbDir, startServer, syncRegistryFromConfig, };
+export { acquireDevDbLock, bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, releaseDevDbLock, resolveAuthToken, resolveDbDir, startServer, syncRegistryFromConfig, };

package/dist/server/server.js

@@ -1,5 +1,6 @@
 // src/server/server.ts
-import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { randomBytes } from 'node:crypto';
 import { connect as tcpConnect } from 'node:net';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -10,12 +11,13 @@ import { loadConfig } from '../core/config.js';
 import { decryptSecret } from '../core/secret.js';
 import { createAndPopulateRegistry } from '../core/workflows/index.js';
 import { createDB, migrateDB } from '../db/index.js';
-import { createRegistry, overrideToCapabilities, registerProvider, } from '../llm/registry.js';
+import { createRegistry, overrideToCapabilities, rebuildRegistry, registerProvider, } from '../llm/registry.js';
 import { initPlugins } from '../plugins/index.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 { isAllowedOrigin } from './middleware/cors.js';
 import { createPermissionStore } from './permission/store.js';
 import { PTYManager } from './terminal/pty-manager.js';
 /** 把 config.providers 注册到新建的 LLM registry（修复此前空 registry 的遗漏）。 */
@@ -44,15 +46,17 @@ function registerProviderFromConfig(registry, p) {
     });
 }
 /**
- * config 变更后原地同步 registry（清空旧路由 + 重新注册），
- * 使运行中的 ServerContext 立即生效，无需重启。
+ * config 变更后原子地同步 registry：在隔离的 next registry 上重建全部路由，
+ * 完成后一次性替换 registry 内部 table 引用。运行中的 resolveRoute 任何时刻
+ * 看到的都是完整的旧表或完整的新表，不会读到「已清空但未注册完」的半状态，
+ * 因此不会把本可用的 provider 误判为 NoRoute。ServerContext 立即生效，无需重启。
  */
 function syncRegistryFromConfig(registry, config) {
-    registry.routes.clear();
-    registry.roles.clear();
-    for (const p of config.providers) {
-        registerProviderFromConfig(registry, p);
-    }
+    rebuildRegistry(registry, (next) => {
+        for (const p of config.providers) {
+            registerProviderFromConfig(next, p);
+        }
+    });
 }
 /** 全局数据根目录：XDG_DATA_HOME 优先，否则 ~/.local/share/c0de。
  * 与 opencode (~/.local/share/opencode/)、oh-my-pi (~/.omp/agent/) 同约定——
@@ -73,6 +77,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 时只迁移第一个遇到的（首次启动即触发）；
@@ -139,6 +196,7 @@ async function buildServerContext(db, opts = {}) {
         agentManager: createAgentManager(),
         permissionStore: createPermissionStore(),
         permissionMode: config.permission.defaultMode,
+        authToken: resolveAuthToken(config, resolveDbDir()),
         // Agent 注册表：内置 4 个默认 agent；项目/用户自定义 agent 可在启动后补充加载。
         agentRegistry: (() => {
             const reg = createAgentRegistry();
@@ -156,30 +214,17 @@ 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。**不 close db**（调用方持有）。
             ctx.agentManager.dispose();
             ctx.permissionStore.dispose();
             ctx.updateScheduler.stop();
             ctx.ptyManager.dispose();
-            if (handoffServer)
-                await handoffServer.close();
         },
     };
 }
@@ -221,11 +266,15 @@ function acquireDevDbLock(dataDir) {
         try {
             unlinkSync(lockPath);
         }
-        catch { /* best-effort */ }
+        catch {
+            /* best-effort */
+        }
         try {
             unlinkSync(join(dataDir, 'postmaster.pid'));
         }
-        catch { /* best-effort */ }
+        catch {
+            /* best-effort */
+        }
     }
     writeFileSync(lockPath, String(process.pid));
 }
@@ -234,7 +283,9 @@ function releaseDevDbLock(dataDir) {
     try {
         unlinkSync(join(dataDir, DEV_LOCK_FILE));
     }
-    catch { /* best-effort */ }
+    catch {
+        /* best-effort */
+    }
 }
 /** dev 专用：创建 + migrate PGLite，跨热重载复用（单写者，只建一次）。 */
 async function createDevDb(cwd) {
@@ -293,13 +344,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) => {
@@ -319,8 +381,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);
@@ -328,10 +392,11 @@ 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;
+    const expectedToken = ctx.authToken;
     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$/);
@@ -339,6 +404,14 @@ async function startServer(opts = {}) {
             socket.destroy();
             return;
         }
+        // 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）
         if (expectedToken) {
             const token = url.searchParams.get('token');
@@ -362,7 +435,7 @@ async function startServer(opts = {}) {
         });
     });
     let closed = false;
-    const close = async () => {
+    const closeMain = async () => {
         if (closed)
             return;
         closed = true;
@@ -370,6 +443,22 @@ 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, {
+            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,9 @@ 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 { PermissionStore } from './permission/store.js';
+import type { PTYManager } from './terminal/pty-manager.js';
 /** 持有所有服务依赖的不可变上下文（config 字段可变用于 PATCH 更新）。 */
 type ServerContext = {
     db: DB;
@@ -28,6 +28,14 @@ type ServerContext = {
     permissionStore: PermissionStore;
     /** 全局授权模式（运行时可临时切换）：'default' 逐个确认；'auto' 自动放行 ask 工具（YOLO）。启动时取 config.permission.defaultMode，PUT /api/permissions 临时切换不回写 config。 */
     permissionMode: 'default' | 'auto';
+    /**
+     * API Bearer token（认证未显式关闭时必存在）。
+     * 用户配置 security.token 优先；否则自动生成并持久化到数据目录 auth-token 文件
+     * （跨重启/热更新稳定，浏览器首访经 ?token= URL 获取后本地保存）。
+     */
+    authToken?: string;
+    /** 主 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/branch.d.ts

@@ -1,6 +1,14 @@
 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[]>;
@@ -8,4 +16,4 @@ declare function getBranches(handle: DB, sessionId: string): Promise<Session[]>;
  * 每层按 metadata.lastOpenedAt 降序（fallback updatedAt、createdAt）。
  */
 declare function getTree(handle: DB): Promise<SessionTreeNode[]>;
-export { forkSession, getBranches, getTree };
+export { BranchPointOutOfRangeError, forkSession, getBranches, getTree };

package/dist/session/branch.js

@@ -1,42 +1,111 @@
 import { eq } from 'drizzle-orm';
-import { sessions } from '../db/schema.js';
+import { sessionEntries, 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);
+        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. */
@@ -67,4 +136,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/snapshot.d.ts

@@ -1,11 +1,17 @@
 import type { DB } from '../db/client.js';
 import type { FileSnapshot } from './types.js';
-/** Create or update a file snapshot. Always creates a new version. Returns the snapshot id. */
-declare function upsertFileSnapshot(handle: DB, sessionId: string, filePath: string, content: string): Promise<string>;
+/** Create or update a file snapshot. Always creates a new version. Returns the snapshot id.
+ *  未传 mtimeMs 时从同文件已有最新行透传（而非置空）：compaction/squash 等从
+ *  工具结果重建快照的调用点拿不到磁盘 mtime，透传旧值可避免每次压缩后热文件
+ *  被误判过期而多一轮冗余重读（自愈无害但浪费；旧值 ≤ 内容实际新鲜度，
+ *  绝不会掩盖磁盘真实变更）。 */
+declare function upsertFileSnapshot(handle: DB, sessionId: string, filePath: string, content: string, mtimeMs?: number): Promise<string>;
 /** Get all snapshots for a session. */
 declare function getFileSnapshots(handle: DB, sessionId: string): Promise<FileSnapshot[]>;
 /** Get the latest snapshot for a specific file, or null. */
 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>;
-export { checkFileSnapshot, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot };
+/** 把源会话每个文件的最新快照复制到目标会话（fork 分支用，P1-4）。 */
+declare function copyFileSnapshots(handle: DB, fromSessionId: string, toSessionId: string): Promise<void>;
+export { checkFileSnapshot, copyFileSnapshots, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot, };