c0de-agent 1.9.0 → 1.10.0

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, };

package/dist/session/snapshot.js

@@ -13,10 +13,15 @@ function rowToSnapshot(row) {
         tokenCount: row.tokenCount ?? 0,
         version: row.version ?? 1,
         createdAt,
+        ...(row.mtimeMs != null ? { mtimeMs: Number(row.mtimeMs) } : {}),
     };
 }
-/** Create or update a file snapshot. Always creates a new version. Returns the snapshot id. */
-async function upsertFileSnapshot(handle, sessionId, filePath, content) {
+/** Create or update a file snapshot. Always creates a new version. Returns the snapshot id.
+ *  未传 mtimeMs 时从同文件已有最新行透传（而非置空）：compaction/squash 等从
+ *  工具结果重建快照的调用点拿不到磁盘 mtime，透传旧值可避免每次压缩后热文件
+ *  被误判过期而多一轮冗余重读（自愈无害但浪费；旧值 ≤ 内容实际新鲜度，
+ *  绝不会掩盖磁盘真实变更）。 */
+async function upsertFileSnapshot(handle, sessionId, filePath, content, mtimeMs) {
     const contentHash = createHash('sha256').update(content).digest('hex');
     const tokenCount = estimateTokens(content);
     const [existing] = await handle.db
@@ -26,9 +31,20 @@ async function upsertFileSnapshot(handle, sessionId, filePath, content) {
         .orderBy(desc(fileSnapshots.version))
         .limit(1);
     const version = (existing?.version ?? 0) + 1;
+    // mtimeMs 是浮点（stat 返回微秒精度），bigint 列不接受小数；取整存储。
+    // 调用方未显式提供时继承已有行的 mtimeMs（见函数头注释）。
+    const effectiveMtimeMs = mtimeMs ?? (existing?.mtimeMs != null ? Number(existing.mtimeMs) : null);
     const [row] = await handle.db
         .insert(fileSnapshots)
-        .values({ sessionId, filePath, content, contentHash, tokenCount, version })
+        .values({
+        sessionId,
+        filePath,
+        content,
+        contentHash,
+        tokenCount,
+        version,
+        ...(effectiveMtimeMs != null ? { mtimeMs: Math.round(effectiveMtimeMs) } : {}),
+    })
         .returning();
     if (!row)
         throw new Error('Failed to insert file snapshot');
@@ -57,4 +73,29 @@ async function checkFileSnapshot(handle, sessionId, filePath) {
     const snapshot = await getLatestFileSnapshot(handle, sessionId, filePath);
     return snapshot?.content ?? null;
 }
-export { checkFileSnapshot, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot };
+/** 把源会话每个文件的最新快照复制到目标会话（fork 分支用，P1-4）。 */
+async function copyFileSnapshots(handle, fromSessionId, toSessionId) {
+    const rows = await handle.db
+        .select()
+        .from(fileSnapshots)
+        .where(eq(fileSnapshots.sessionId, fromSessionId));
+    const latest = new Map();
+    for (const r of rows) {
+        const prev = latest.get(r.filePath);
+        if (!prev || (r.version ?? 0) > (prev.version ?? 0))
+            latest.set(r.filePath, r);
+    }
+    for (const r of latest.values()) {
+        await handle.db.insert(fileSnapshots).values({
+            sessionId: toSessionId,
+            entryId: r.entryId,
+            filePath: r.filePath,
+            content: r.content,
+            contentHash: r.contentHash,
+            tokenCount: r.tokenCount,
+            version: r.version,
+            mtimeMs: r.mtimeMs,
+        });
+    }
+}
+export { checkFileSnapshot, copyFileSnapshots, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot, };

package/dist/session/squash.js

@@ -62,6 +62,7 @@ ${history}`;
         if (cfg.preserveFileSnapshots) {
             const hotFiles = extractHotFiles(toSquash);
             for (const file of hotFiles) {
+                // 不传 mtimeMs：由 upsertFileSnapshot 从已有行透传，压缩后热文件不误判过期。
                 const id = await upsertFileSnapshot(txHandle, sessionId, file.path, file.content);
                 fileSnapshotIds.push(id);
             }

package/dist/session/types.d.ts

@@ -117,6 +117,8 @@ type FileSnapshot = {
     contentHash: string;
     tokenCount: number;
     version: number;
+    /** 快照创建时文件磁盘 mtime（毫秒）；旧行无此字段（迁移前写入） */
+    mtimeMs?: number;
     createdAt: number;
 };
 export type { ArchiveRef, BranchSummaryEntry, CompactionArchive, CompactionConfig, CompactionEntry, CompactionResult, FileSnapshot, HotFile, MessageInput, SessionEntry, SessionTreeNode, SquashConfig, SquashEntry, SteeringEntry, Summarizer, };

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

@@ -64,16 +64,17 @@ type UpdateConfig = {
     intervalMs: number;
     /** 启动后首次检查的延迟（毫秒），默认 10 秒。 */
     initialDelayMs: number;
-    /** 发现新版本后自动应用（无感知），false 则仅前端提示手动确认（默认 false）。 */
-    autoApply: boolean;
 };
-/** Server security configuration (spec §24.2). */
+/** Server security configuration (spec §24.2)。 */
 type SecurityConfig = {
-    /** 启用 Bearer token 认证（远程访问场景）。本地开发默认关闭。 */
+    /**
+     * 是否启用 Bearer token 认证（默认 true）。
+     * 关闭为显式选择（可信网络/无人值守场景），会取消一切 API 鉴权。
+     */
     authEnabled: boolean;
-    /** Bearer token；authEnabled 为 true 时必填。 */
+    /** Bearer token；未提供时服务端自动生成并持久化到全局数据目录（跨重启/热更新稳定）。 */
     token?: string;
-    /** 额外允许的 CORS origin（本地回环始终允许）。 */
+    /** 额外允许的 CORS origin（本地回环始终允许；局域网/远程访问需显式添加）。 */
     allowedOrigins: string[];
 };
 /** Global application configuration. */

package/dist/shared/utils/path.d.ts

@@ -5,11 +5,10 @@
  * - `resolve(root, requestPath)` 解析后，若结果不在 root 子树内则返回 null。
  * - 判定逻辑：`relative(root, resolved)` 以 `..` 开头即越界；
  *   再用 `resolve(root, rel) === resolved` 兜底，防止相对段恰好名为 root 的边角情况。
+ * - symlink 防逃逸（P2-5）：root 与目标（或其最近已存在祖先）经 realpath 解析后，
+ *   目标必须仍落在 root 实路径内；否则返回 null。
  *
  * 返回解析后的绝对路径；越界返回 null。
- *
- * 注意：本函数基于 `relative`，不解析符号链接（symlink）。若 root 内存在指向
- * root 外的符号链接，本函数无法阻止经由该链接的逃逸——symlink 逃逸不在本次范围内。
  */
 declare function safeResolve(root: string, requestPath: string): string | null;
 export { safeResolve };

package/dist/shared/utils/path.js

@@ -1,4 +1,5 @@
-import { relative, resolve } from 'node:path';
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, relative, resolve, sep } from 'node:path';
 /**
  * 安全路径解析：确保 requestPath 解析后落在 root 内，防止路径穿越
  * （如 `../etc/passwd`、绝对路径 `/etc/passwd`）。
@@ -6,11 +7,10 @@ import { relative, resolve } from 'node:path';
  * - `resolve(root, requestPath)` 解析后，若结果不在 root 子树内则返回 null。
  * - 判定逻辑：`relative(root, resolved)` 以 `..` 开头即越界；
  *   再用 `resolve(root, rel) === resolved` 兜底，防止相对段恰好名为 root 的边角情况。
+ * - symlink 防逃逸（P2-5）：root 与目标（或其最近已存在祖先）经 realpath 解析后，
+ *   目标必须仍落在 root 实路径内；否则返回 null。
  *
  * 返回解析后的绝对路径；越界返回 null。
- *
- * 注意：本函数基于 `relative`，不解析符号链接（symlink）。若 root 内存在指向
- * root 外的符号链接，本函数无法阻止经由该链接的逃逸——symlink 逃逸不在本次范围内。
  */
 function safeResolve(root, requestPath) {
     const resolved = resolve(root, requestPath);
@@ -18,6 +18,22 @@ function safeResolve(root, requestPath) {
     if (rel.startsWith('..') || resolve(root, rel) !== resolved) {
         return null;
     }
+    try {
+        const rootReal = realpathSync(root);
+        let probe = resolved;
+        while (!existsSync(probe)) {
+            const parent = dirname(probe);
+            if (parent === probe)
+                break;
+            probe = parent;
+        }
+        const probeReal = realpathSync(probe);
+        if (probeReal !== rootReal && !probeReal.startsWith(rootReal + sep))
+            return null;
+    }
+    catch {
+        // realpath 失败（root 不存在等）：保持原有 relative 判定结果
+    }
     return resolved;
 }
 export { safeResolve };

package/dist/tools/builtin/todo.js

@@ -421,16 +421,17 @@ export function getLatestTodoPhasesFromMessages(messages) {
             continue;
         for (let j = msg.content.length - 1; j >= 0; j--) {
             const part = msg.content[j];
-            if (!part || part._tag !== 'tool_result')
+            if (part?._tag !== 'tool_result')
                 continue;
             if (part.tool !== 'todo')
                 continue;
             const output = part.output;
-            if (!output || output._tag !== 'success')
+            if (output?._tag !== 'success')
                 continue;
             const metadata = output.metadata;
-            if (metadata && Array.isArray(metadata.phases)) {
-                return clonePhases(metadata.phases);
+            const phases = metadata?.phases;
+            if (Array.isArray(phases)) {
+                return clonePhases(phases);
             }
         }
     }

package/dist/tools/index.d.ts

@@ -6,11 +6,11 @@ export { dapTools } from './builtin/dap.js';
 export { editTool } from './builtin/edit.js';
 export { globTool, globToRegex } from './builtin/glob.js';
 export { grepTool } from './builtin/grep.js';
+export { kanbanTool } from './builtin/kanban.js';
 export { readTool } from './builtin/read.js';
 export { createDefaultURLRegistry, createFileResolver, createSkillResolver, } from './builtin/resolvers.js';
-export { kanbanTool } from './builtin/kanban.js';
-export { todoTool } from './builtin/todo.js';
 export type { TodoInput, TodoItem, TodoPhase, TodoStatus } from './builtin/todo.js';
+export { todoTool } from './builtin/todo.js';
 export { writeTool } from './builtin/write.js';
 export { yieldTool } from './builtin/yield.js';
 export { executeTool } from './executor.js';
@@ -23,10 +23,21 @@ export { formatForLLM, resolveProvider, runWebSearch } from './websearch/index.j
 export type { WebSearchProvider, WebSearchProviderId, WebSearchResponse, WebSearchSource, } from './websearch/types.js';
 export { createWebSearchTool } from './websearch/websearch.js';
 import type { Config } from '../shared/types/config.js';
+import type { ToolRegistry } from './types.js';
 /**
  * Create a registry pre-loaded with all builtin tools:
  * read, write, edit, glob, grep, bash, task, websearch, and the debug_* set.
  *
+ * config.tools.disabled 中的工具**不注册**——registry 层过滤保证两个入口
+ * （CLI print / Web chat / /api/tools 列表）统一生效，禁用的工具对 agent 完全不可见。
  * @param config 可选配置；websearch 工具按 config.websearch 构造。省略时用 DEFAULT_CONFIG。
  */
-export declare function createDefaultRegistry(config?: Config): import("./types.js").ToolRegistry;
+export declare function createDefaultRegistry(config?: Config): ToolRegistry;
+/**
+ * 解析本轮启用的工具名列表（P1-1 修复：config.tools.enabled/disabled 双入口统一生效）。
+ *
+ * - explicit（前端显式选择）非 undefined → 以其为准，但过滤掉 disabled 与未注册名。
+ * - 否则 enabled 非空 → enabled ∩ registered；enabled 空 → 全部 registered（空=全部）。
+ * - disabled 恒过滤（registry 已排除，此处兜底）。
+ */
+export declare function resolveEnabledToolNames(registry: ToolRegistry, config: Pick<Config, 'tools'>, explicit?: string[]): string[];

package/dist/tools/index.js

@@ -4,10 +4,10 @@ export { dapTools } from './builtin/dap.js';
 export { editTool } from './builtin/edit.js';
 export { globTool, globToRegex } from './builtin/glob.js';
 export { grepTool } from './builtin/grep.js';
+export { kanbanTool } from './builtin/kanban.js';
 export { readTool } from './builtin/read.js';
 // ── Builtin tools ───────────────────────────────────────────
 export { createDefaultURLRegistry, createFileResolver, createSkillResolver, } from './builtin/resolvers.js';
-export { kanbanTool } from './builtin/kanban.js';
 export { todoTool } from './builtin/todo.js';
 export { writeTool } from './builtin/write.js';
 export { yieldTool } from './builtin/yield.js';
@@ -33,28 +33,50 @@ import { taskTool } from './builtin/task.js';
 import { todoTool } from './builtin/todo.js';
 import { writeTool } from './builtin/write.js';
 import { yieldTool } from './builtin/yield.js';
-import { createToolRegistry, registerTool } from './registry.js';
+import { createToolRegistry, listTools, registerTool } from './registry.js';
 import { createWebSearchTool } from './websearch/websearch.js';
 /**
  * Create a registry pre-loaded with all builtin tools:
  * read, write, edit, glob, grep, bash, task, websearch, and the debug_* set.
  *
+ * config.tools.disabled 中的工具**不注册**——registry 层过滤保证两个入口
+ * （CLI print / Web chat / /api/tools 列表）统一生效，禁用的工具对 agent 完全不可见。
  * @param config 可选配置；websearch 工具按 config.websearch 构造。省略时用 DEFAULT_CONFIG。
  */
 export function createDefaultRegistry(config = DEFAULT_CONFIG) {
     const reg = createToolRegistry();
-    registerTool(reg, readTool);
-    registerTool(reg, writeTool);
-    registerTool(reg, editTool);
-    registerTool(reg, globTool);
-    registerTool(reg, grepTool);
-    registerTool(reg, bashTool);
-    registerTool(reg, kanbanTool);
-    registerTool(reg, taskTool);
-    registerTool(reg, todoTool);
-    registerTool(reg, yieldTool);
-    registerTool(reg, createWebSearchTool(config.websearch));
+    const disabled = new Set(config.tools?.disabled ?? []);
+    const register = (tool) => {
+        if (!disabled.has(tool.name))
+            registerTool(reg, tool);
+    };
+    register(readTool);
+    register(writeTool);
+    register(editTool);
+    register(globTool);
+    register(grepTool);
+    register(bashTool);
+    register(kanbanTool);
+    register(taskTool);
+    register(todoTool);
+    register(yieldTool);
+    register(createWebSearchTool(config.websearch));
     for (const tool of dapTools)
-        registerTool(reg, tool);
+        register(tool);
     return reg;
 }
+/**
+ * 解析本轮启用的工具名列表（P1-1 修复：config.tools.enabled/disabled 双入口统一生效）。
+ *
+ * - explicit（前端显式选择）非 undefined → 以其为准，但过滤掉 disabled 与未注册名。
+ * - 否则 enabled 非空 → enabled ∩ registered；enabled 空 → 全部 registered（空=全部）。
+ * - disabled 恒过滤（registry 已排除，此处兜底）。
+ */
+export function resolveEnabledToolNames(registry, config, explicit) {
+    const all = listTools(registry).map((t) => t.name);
+    const disabled = new Set(config.tools?.disabled ?? []);
+    const base = explicit ?? (config.tools?.enabled && config.tools.enabled.length > 0
+        ? config.tools.enabled
+        : all);
+    return base.filter((n) => all.includes(n) && !disabled.has(n));
+}

package/dist/update/index.d.ts

@@ -7,4 +7,4 @@ export { orderSessionsByParent, restoreSessions, serializeSessions } from './sna
 export type { HotUpdateOptions, HotUpdateResult, SpawnFn } from './updater.js';
 export { cleanupSnapshot, performHotUpdate } from './updater.js';
 export type { UpdateCheckResult } from './version.js';
-export { checkForUpdate, compareSemver } from './version.js';
+export { checkForUpdate, compareSemver, getCurrentVersion } from './version.js';

package/dist/update/index.js

@@ -3,4 +3,4 @@ export { createHandoffServer, requestHandoff } from './ipc.js';
 export { createUpdateScheduler } from './scheduler.js';
 export { orderSessionsByParent, restoreSessions, serializeSessions } from './snapshot.js';
 export { cleanupSnapshot, performHotUpdate } from './updater.js';
-export { checkForUpdate, compareSemver } from './version.js';
+export { checkForUpdate, compareSemver, getCurrentVersion } from './version.js';

package/dist/update/ipc.d.ts

@@ -7,9 +7,36 @@ type HandoffServer = {
     port: number;
     close: () => Promise<void>;
 };
-/** 旧实例启动时创建 handoff 端点。收到 POST /handoff 即触发 onHandoff（序列化 + 退出）。 */
-declare function createHandoffServer(onHandoff: () => Promise<void>): Promise<HandoffServer>;
-/** 新实例请求旧实例让出端口（graceful shutdown）。失败抛错。 */
-declare function requestHandoff(port: number, host?: string): Promise<void>;
-export type { HandoffServer };
+type HandoffOptions = {
+    /**
+     * 期望的 Bearer token。设置后 /handoff 必须携带匹配的 Authorization 头，
+     * 否则 401——防止任意本地进程用 POST /handoff 杀掉服务。
+     * 旧实例与新实例读同一 auth-token 文件（或同一 config token），天然匹配。
+     */
+    expectedToken?: string;
+    /**
+     * 响应发出后退出进程（旧实例完整让渡：主服务与资源已在 onHandoff 中关闭）。
+     * 退出延迟 250ms 保证 HTTP 响应刷出；不设时仅响应不退出（测试用）。
+     */
+    exitAfterResponse?: boolean;
+};
+/**
+ * requestHandoff 抛出的可区分错误（调用方据此分流处理）：
+ * - kind='connect'：连接层失败（ECONNREFUSED 等）——旧实例未启 handoff 端点，
+ *   调用方应直接尝试绑端口；
+ * - kind='http'：收到 HTTP 响应但非 2xx（status 为状态码）——如 401 token
+ *   不匹配、500 onHandoff 失败，旧实例存在但拒绝/未能让渡。
+ */
+type HandoffError = Error & {
+    kind: 'connect' | 'http';
+    status?: number;
+};
+/**
+ * 旧实例启动时创建 handoff 端点。收到 POST /handoff 即触发 onHandoff
+ * （关闭主服务与资源），响应 200；exitAfterResponse 时随后退出进程。
+ */
+declare function createHandoffServer(onHandoff: () => Promise<void>, opts?: HandoffOptions): Promise<HandoffServer>;
+/** 新实例请求旧实例让出端口（graceful shutdown）。失败抛可区分的 HandoffError。 */
+declare function requestHandoff(port: number, host?: string, token?: string): Promise<void>;
+export type { HandoffError, HandoffOptions, HandoffServer };
 export { createHandoffServer, requestHandoff };

package/dist/update/ipc.js

@@ -1,17 +1,45 @@
+import { timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
-/** 旧实例启动时创建 handoff 端点。收到 POST /handoff 即触发 onHandoff（序列化 + 退出）。 */
-function createHandoffServer(onHandoff) {
+/**
+ * 恒时比较 Authorization 头与期望值：字符串直接比较可被时序攻击逐字符探测。
+ * 长度不等直接 false——timingSafeEqual 要求等长 buffer，先比较长度本身
+ * 不泄露内容信息。
+ */
+function authHeaderMatches(actual, expected) {
+    if (typeof actual !== 'string' || actual.length !== expected.length)
+        return false;
+    return timingSafeEqual(Buffer.from(actual), Buffer.from(expected));
+}
+/**
+ * 旧实例启动时创建 handoff 端点。收到 POST /handoff 即触发 onHandoff
+ * （关闭主服务与资源），响应 200；exitAfterResponse 时随后退出进程。
+ */
+function createHandoffServer(onHandoff, opts = {}) {
     return new Promise((resolve, reject) => {
+        const expected = opts.expectedToken && opts.expectedToken.length > 0
+            ? `Bearer ${opts.expectedToken}`
+            : '';
         const handler = async (req, res) => {
             if (req.method === 'POST' && req.url === '/handoff') {
+                if (expected && !authHeaderMatches(req.headers.authorization, expected)) {
+                    res.writeHead(401, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: 'unauthorized' }));
+                    return;
+                }
                 try {
                     await onHandoff();
                     res.writeHead(200, { 'content-type': 'application/json' });
                     res.end(JSON.stringify({ ok: true }));
+                    // 仅 200 才调度退出：500 时 exit(0) 会掩盖让渡失败——保留进程供
+                    // 诊断/重试，由下方错误日志暴露 onHandoff 失败原因。
+                    if (opts.exitAfterResponse) {
+                        setTimeout(() => process.exit(0), 250);
+                    }
                 }
                 catch (error) {
                     res.writeHead(500, { 'content-type': 'application/json' });
                     res.end(JSON.stringify({ ok: false, error: String(error) }));
+                    console.error('[handoff] onHandoff failed, keeping process alive:', error);
                 }
                 return;
             }
@@ -32,10 +60,28 @@ function createHandoffServer(onHandoff) {
         });
     });
 }
-/** 新实例请求旧实例让出端口（graceful shutdown）。失败抛错。 */
-async function requestHandoff(port, host = '127.0.0.1') {
-    const res = await fetch(`http://${host}:${port}/handoff`, { method: 'POST' });
-    if (!res.ok)
-        throw new Error(`handoff failed: HTTP ${res.status}`);
+/** 新实例请求旧实例让出端口（graceful shutdown）。失败抛可区分的 HandoffError。 */
+async function requestHandoff(port, host = '127.0.0.1', token) {
+    let res;
+    try {
+        res = await fetch(`http://${host}:${port}/handoff`, {
+            method: 'POST',
+            ...(token ? { headers: { Authorization: `Bearer ${token}` } } : {}),
+        });
+    }
+    catch (err) {
+        // 连接层失败（ECONNREFUSED 等）：旧实例无 handoff 端点。抛 kind='connect'
+        // 让调用方（requestHandoffWithRetry）区分处理——直接尝试绑端口。
+        const error = new Error(`handoff connect failed: ${err instanceof Error ? err.message : String(err)}`);
+        error.kind = 'connect';
+        throw error;
+    }
+    if (!res.ok) {
+        // 收到 HTTP 响应但非 2xx（如 401 token 不匹配、500 onHandoff 失败）。
+        const error = new Error(`handoff failed: HTTP ${res.status}`);
+        error.kind = 'http';
+        error.status = res.status;
+        throw error;
+    }
 }
 export { createHandoffServer, requestHandoff };

package/dist/update/updater.d.ts

@@ -16,8 +16,9 @@ type HotUpdateResult = {
  * 启动新实例的函数签名。
  * @param snapshotPath 快照文件路径（旧实例已写入）
  * @param argv          传给新进程的完整参数（含 restore flag + 可选 handoff flag）
+ * @param opts          热更新选项（authToken 等经环境变量传递给新实例）
  */
-type SpawnFn = (snapshotPath: string, argv: string[]) => Promise<void>;
+type SpawnFn = (snapshotPath: string, argv: string[], opts?: HotUpdateOptions) => Promise<void>;
 type HotUpdateOptions = {
     /** 自更新安装函数；默认 `npm install -g <pkg>`。 */
     installFn?: (pkg: string) => Promise<void>;
@@ -30,6 +31,10 @@ type HotUpdateOptions = {
     restoreFlag?: string;
     /** 旧实例 handoff 端口；提供时新实例启动后请求旧实例 graceful shutdown。 */
     handoffPort?: number;
+    /** 旧实例主服务端口；新实例 --port 复用（保证接管同一地址）。 */
+    port?: number;
+    /** 传给新实例的认证 token（经环境变量 C0DE_AUTH_TOKEN），保证新旧实例握手同 token。 */
+    authToken?: string;
 };
 /**
  * 执行热更新（spec §18.1-18.2 流程）：
@@ -38,8 +43,7 @@ type HotUpdateOptions = {
  *   3. detached 启动新版本实例，传入快照路径（新实例 restore + 端口接管）
  *
  * 注：旧实例的 graceful shutdown / 端口让渡由新实例启动后通过 IPC 协调
- * （见 ipc.ts），本函数只负责"序列化 + 安装 + 接力"。若提供 handoffPort，
- * argv 会带上 --handoff-port，新实例据此 requestHandoff 通知旧实例退出。
+ * （见 ipc.ts），本函数只负责"序列化 + 安装 + 接力"。
  */
 declare function performHotUpdate(snapshot: SessionSnapshot, opts?: HotUpdateOptions): Promise<HotUpdateResult>;
 /** 清理快照临时目录（热更新完成或放弃后调用）。 */

package/dist/update/updater.js

@@ -16,13 +16,17 @@ function defaultInstall(pkg) {
         });
     });
 }
-/** 默认启动新实例：detached spawn，argv 全部透传给新进程。 */
-function defaultSpawn(_snapshotPath, argv) {
+/** 默认启动新实例：detached spawn CLI bin，argv = serve <restore> <handoff>。
+ * 必须以 `serve` 子命令开头（CLI dispatch 按首参选命令）；
+ * --port 复用旧实例端口，--handoff-port 让新实例启动后请求旧实例退出。
+ * 认证 token 经环境变量传递（不落 argv，避免 ps 泄漏）。 */
+function defaultSpawn(_snapshotPath, argv, opts) {
     return new Promise((resolve, reject) => {
         try {
             const child = spawn(process.argv0, [process.argv[1] ?? '', ...argv], {
                 detached: true,
                 stdio: 'ignore',
+                ...(opts?.authToken ? { env: { ...process.env, C0DE_AUTH_TOKEN: opts.authToken } } : {}),
             });
             child.unref();
             resolve();
@@ -39,8 +43,7 @@ function defaultSpawn(_snapshotPath, argv) {
  *   3. detached 启动新版本实例，传入快照路径（新实例 restore + 端口接管）
  *
  * 注：旧实例的 graceful shutdown / 端口让渡由新实例启动后通过 IPC 协调
- * （见 ipc.ts），本函数只负责"序列化 + 安装 + 接力"。若提供 handoffPort，
- * argv 会带上 --handoff-port，新实例据此 requestHandoff 通知旧实例退出。
+ * （见 ipc.ts），本函数只负责"序列化 + 安装 + 接力"。
  */
 async function performHotUpdate(snapshot, opts = {}) {
     const pkg = opts.packageName ?? DEFAULT_PACKAGE;
@@ -59,13 +62,18 @@ async function performHotUpdate(snapshot, opts = {}) {
         };
     }
     const restoreFlag = opts.restoreFlag ?? '--restore';
-    const argv = [restoreFlag, snapshotPath];
+    const argv = [
+        'serve',
+        restoreFlag,
+        snapshotPath,
+        ...(opts.port !== undefined ? ['--port', String(opts.port)] : []),
+    ];
     if (opts.handoffPort !== undefined) {
         argv.push('--handoff-port', String(opts.handoffPort));
     }
     const spawnNew = opts.spawnNewInstanceFn ?? defaultSpawn;
     try {
-        await spawnNew(snapshotPath, argv);
+        await spawnNew(snapshotPath, argv, opts);
     }
     catch (error) {
         return {

package/dist/update/version.d.ts

@@ -10,9 +10,14 @@ type CheckOptions = {
     currentVersion?: string;
     registryUrl?: string;
 };
+/**
+ * 读取当前安装版本（package.json 的 version 字段）。
+ * src/dev 与 dist 两种布局下 `../../package.json` 都指向包根；读取失败回退常量。
+ */
+declare function getCurrentVersion(): string;
 /** 语义化版本比较：a < b → -1，a == b → 0，a > b → 1。忽略前导 v 和 prerelease。 */
 declare function compareSemver(a: string, b: string): number;
 /** 查询 npm registry 判断是否有新版本。网络/解析失败时返回 hasUpdate:false，绝不抛错。 */
 declare function checkForUpdate(opts?: CheckOptions): Promise<UpdateCheckResult>;
 export type { CheckOptions, UpdateCheckResult };
-export { checkForUpdate, compareSemver };
+export { checkForUpdate, compareSemver, getCurrentVersion };