c0de-agent 1.9.0 → 1.10.0

package/dist/server/routes/config.js

@@ -1,5 +1,5 @@
 import { Hono } from 'hono';
-import { mergeConfig, saveConfig } from '../../core/config.js';
+import { loadConfigScopes, mergeConfig, mergeRaw, saveConfigScoped } from '../../core/config.js';
 import { encryptSecret, isEncryptedSecret } from '../../core/secret.js';
 import { syncRegistryFromConfig } from '../server.js';
 function createConfigRoute(ctx) {
@@ -14,10 +14,14 @@ function createConfigRoute(ctx) {
         if (Array.isArray(patch.providers)) {
             patch.providers = patch.providers.map((p) => p.apiKey && !isEncryptedSecret(p.apiKey) ? { ...p, apiKey: encryptSecret(p.apiKey) } : p);
         }
-        ctx.config = mergeConfig(ctx.config, patch);
+        // 按作用域最小落盘：patch 只合并进项目作用域原始文件，
+        // 不把合并结果（含默认值/global 配置）整体序列化进项目文件。
+        const scopes = loadConfigScopes(ctx.cwd);
+        const nextProject = mergeRaw(scopes.project ?? {}, patch);
+        ctx.config = mergeConfig(scopes.global, nextProject);
         // providers 变更后原地同步 registry，使运行中的连接立即生效
         syncRegistryFromConfig(ctx.llmRegistry, ctx.config);
-        await saveConfig(ctx.config, 'project', ctx.cwd).catch(() => {
+        await saveConfigScoped('project', ctx.cwd, nextProject).catch(() => {
             // 保存失败不影响内存配置
         });
         return c.json(ctx.config);

package/dist/server/routes/session.js

@@ -2,7 +2,7 @@ import { Hono } from 'hono';
 import { createSummarizer, runCompaction } from '../../core/compact.js';
 import { fromDirectory } from '../../project/index.js';
 import { archiveOriginalEntries } from '../../session/archive.js';
-import { forkSession, getBranches, getTree } from '../../session/branch.js';
+import { BranchPointOutOfRangeError, forkSession, getBranches, getTree, } from '../../session/branch.js';
 import { deleteEntriesByIds, getMessages, insertEntry } from '../../session/message.js';
 import { createSession, deleteSession, getLLMSegments, getSession, listSessions, listSessionsByProject, touchLastOpened, } from '../../session/session.js';
 import { applyShakeRegions, collectShakeRegions, DEFAULT_SHAKE_CONFIG, toRegionViews, } from '../../session/shake.js';
@@ -63,7 +63,11 @@ function createSessionRoute(ctx) {
             const forked = await forkSession(ctx.db, id, messageIndex);
             return c.json(forked, 201);
         }
-        catch {
+        catch (error) {
+            // 分支点越界是客户端索引/分页 bug → 400 并透出明确语义；归 404 会误导排查
+            if (error instanceof BranchPointOutOfRangeError) {
+                return apiError(c, 400, 'BRANCH_POINT_OUT_OF_RANGE', error.message);
+            }
             return apiError(c, 404, 'NOT_FOUND', 'Session not found');
         }
     });

package/dist/server/routes/terminal.js

@@ -1,6 +1,9 @@
 // src/server/routes/terminal.ts
+import { isAbsolute } from 'node:path';
 import { Hono } from 'hono';
 import { apiError } from '../middleware/error.js';
+/** 允许的 shell 白名单（P2-6：拒绝路径分隔符与任意二进制）。 */
+const ALLOWED_SHELLS = new Set(['bash', 'zsh', 'fish', 'sh']);
 /** 创建终端路由（REST 部分；WebSocket 升级在 server.ts 中处理）。 */
 function createTerminalRoute(ctx) {
     const app = new Hono();
@@ -18,6 +21,15 @@ function createTerminalRoute(ctx) {
         const title = typeof body.title === 'string' ? body.title : undefined;
         const shell = typeof body.shell === 'string' && body.shell.length > 0 ? body.shell : undefined;
         const projectId = typeof body.projectId === 'string' && body.projectId.length > 0 ? body.projectId : undefined;
+        // 入参校验（P2-6）：shell 白名单；cwd 必须为绝对路径。
+        if (shell !== undefined) {
+            if (shell.includes('/') || shell.includes('\\') || !ALLOWED_SHELLS.has(shell)) {
+                return apiError(c, 400, 'INVALID_SHELL', `shell 必须是 ${[...ALLOWED_SHELLS].join('/')} 之一`);
+            }
+        }
+        if (typeof cwd === 'string' && cwd.length > 0 && !isAbsolute(cwd)) {
+            return apiError(c, 400, 'INVALID_CWD', 'cwd 必须是绝对路径');
+        }
         try {
             const info = mgr.create({ cwd, cols, rows, title, shell, projectId });
             return c.json(info, 201);

package/dist/server/routes/update.d.ts

@@ -9,6 +9,7 @@ import type { ServerContext } from '../types.js';
  *   序列化当前会话 → performHotUpdate（npm install -g + spawn 新实例 + handoffPort）。
  *   旧实例通过 handoff 端点优雅退出，新实例 restore 快照并接管端口。
  *   响应立即返回（不阻塞 spawn），实际接管由 handoff IPC 异步完成。
+ *   dev（vite）模式无 handoff server，返回 409——热更新仅在独立 serve 进程可用。
  */
 declare function createUpdateRoute(ctx: ServerContext): Hono;
 export { createUpdateRoute };

package/dist/server/routes/update.js

@@ -1,5 +1,5 @@
 import { Hono } from 'hono';
-import { performHotUpdate, serializeSessions } from '../../update/index.js';
+import { getCurrentVersion, performHotUpdate, serializeSessions } from '../../update/index.js';
 import { apiError } from '../middleware/error.js';
 /**
  * GET /api/update — 返回后台调度器缓存的版本检查结果（spec §18.1）。
@@ -10,6 +10,7 @@ import { apiError } from '../middleware/error.js';
  *   序列化当前会话 → performHotUpdate（npm install -g + spawn 新实例 + handoffPort）。
  *   旧实例通过 handoff 端点优雅退出，新实例 restore 快照并接管端口。
  *   响应立即返回（不阻塞 spawn），实际接管由 handoff IPC 异步完成。
+ *   dev（vite）模式无 handoff server，返回 409——热更新仅在独立 serve 进程可用。
  */
 function createUpdateRoute(ctx) {
     const app = new Hono();
@@ -20,20 +21,26 @@ function createUpdateRoute(ctx) {
         // 无缓存（首次启动延迟未到）：同步触发一次，避免前端首屏空。
         // 不 await——保持 GET 语义非阻塞；前端下次轮询拿到结果。
         void ctx.updateScheduler.checkNow();
+        const v = getCurrentVersion();
         return c.json({
             hasUpdate: false,
-            currentVersion: '0.0.0',
-            latestVersion: '0.0.0',
+            currentVersion: v,
+            latestVersion: v,
         });
     });
     app.post('/apply', async (c) => {
+        if (!ctx.handoff) {
+            return apiError(c, 409, 'HOT_UPDATE_UNAVAILABLE', '热更新仅在独立 serve 进程可用（dev 模式请手动更新）');
+        }
         const result = await ctx.updateScheduler.checkNow();
         if (!result.hasUpdate) {
             return apiError(c, 409, 'NO_UPDATE', '已是最新版本，无需热更新');
         }
         const snapshot = await serializeSessions(ctx.db, ctx.config);
         const r = await performHotUpdate(snapshot, {
-            handoffPort: ctx.handoff?.port,
+            handoffPort: ctx.handoff.port,
+            port: ctx.port,
+            authToken: ctx.authToken,
         });
         if (r._tag === 'success') {
             return c.json({

package/dist/server/routes/workflows.js

@@ -2,9 +2,9 @@ import { unlink } from 'node:fs/promises';
 import { Hono } from 'hono';
 import { streamSSE } from 'hono/streaming';
 import { createAgent } from '../../core/agent.js';
-import { executeWorkflow } from '../../core/workflows/runtime.js';
-import { reloadRegistry } from '../../core/workflows/registry.js';
 import { discoverWorkflows, saveWorkflow } from '../../core/workflows/discovery.js';
+import { reloadRegistry } from '../../core/workflows/registry.js';
+import { executeWorkflow } from '../../core/workflows/runtime.js';
 import { getProject } from '../../project/project.js';
 import { createSession } from '../../session/session.js';
 import { autoAllowChecker } from '../../tools/permission.js';

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 = {
@@ -43,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）。
  *
@@ -54,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，跨热重载复用（单写者，只建一次）。 */
@@ -62,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 { randomBytes } from 'node:crypto';
 import { connect as tcpConnect } from 'node:net';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -16,6 +17,7 @@ import { createDefaultRegistry, createDefaultURLRegistry } from '../tools/index.
 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 的遗漏）。 */
@@ -75,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 时只迁移第一个遇到的（首次启动即触发）；
@@ -141,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();
@@ -158,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();
         },
     };
 }
@@ -301,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) => {
@@ -327,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);
@@ -336,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$/);
@@ -347,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');
@@ -370,7 +435,7 @@ async function startServer(opts = {}) {
         });
     });
     let closed = false;
-    const close = async () => {
+    const closeMain = async () => {
         if (closed)
             return;
         closed = true;
@@ -378,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[];
 }>;