c0de-agent 1.11.0 → 1.13.0

package/dist/tools/index.js

@@ -66,16 +66,34 @@ export function createDefaultRegistry(config = DEFAULT_CONFIG) {
     return reg;
 }
 /**
- * 解析本轮启用的工具名列表（P1-1 修复：config.tools.enabled/disabled 双入口统一生效）。
+ * 解析本轮启用的工具名列表（config.tools.enabled/disabled 双入口统一生效）。
  *
- * - explicit（前端显式选择）非 undefined → 以其为准，但过滤掉 disabled 与未注册名。
- * - 否则 enabled 非空 → enabled ∩ registered；enabled 空 → 全部 registered（空=全部）。
+ * 语义（P1-1 修复「空=全部」安全陷阱 + P2 交集收紧）：
+ * - explicit（前端显式选择）非 undefined → 与 config.tools.enabled 取交集——
+ *   enabled 含 '*' 或未配置时视为无上限（explicit 原样生效）。此前 explicit 完全
+ *   覆盖 enabled：config.tools.enabled=[] 的 fail-closed 语义可被请求级 tools
+ *   静默绕过，设置页「禁用全部」与实际行为矛盾。
+ * - 否则 config.tools.enabled：含 '*'（通配）→ 全部注册工具；
+ *   空数组 → 无工具（fail-closed）；否则 → 显式名单。
  * - 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);
+    const enabled = config.tools?.enabled;
+    const enabledIsWildcard = enabled === undefined || (enabled.length > 0 && enabled.includes('*'));
+    const base = explicit !== undefined
+        ? enabledIsWildcard
+            ? explicit
+            : explicit.filter((n) => enabled.includes(n))
+        : enabledIsWildcard
+            ? all
+            : (enabled ?? []);
     return base.filter((n) => all.includes(n) && !disabled.has(n));
 }
+/**
+ * 依赖「会话绑定项目」的工具：其运行时依赖（如 kanban 的 kanbanStore）由宿主按
+ * session.projectId 注入——无项目会话（CLI print 未注册 cwd 等）调用必失败，
+ * 只会浪费一轮工具调用。会话无 projectId 时从工具集中剔除。
+ */
+export const PROJECT_BOUND_TOOLS = new Set(['kanban']);

package/dist/tools/websearch/index.d.ts

@@ -10,7 +10,11 @@ export declare function resolveProvider(preference: 'auto' | WebSearchProviderId
 export declare function formatForLLM(response: WebSearchResponse): string;
 /** 测试钩子：覆盖默认 fetch（undici ProxyAgent 包装版）。 */
 export declare function setFetchOverride(f: typeof fetch | undefined): void;
-/** 工具入口：解析 provider → search → 返回 WebSearchResponse。 */
+/** 工具入口：解析 provider → search → 返回 WebSearchResponse。
+ *  'auto' 模式带运行时降级链：候选后端按 key 可用性排列（tavily > brave >
+ *  duckduckgo），当前后端因鉴权/限流/服务端/网络错误失败时依次降级——
+ *  此前 auto 只按 key **存在性**选一次，key 失效/过期即整体失败。
+ *  显式指定后端时尊重用户选择，单后端不降级。abort 立即上抛，不沿链继续。 */
 export declare function runWebSearch(input: {
     query: string;
     numResults?: number;

package/dist/tools/websearch/index.js

@@ -1,3 +1,4 @@
+import { decryptSecret } from '../../core/secret.js';
 import { createFetch } from './fetch.js';
 import { braveProvider } from './providers/brave.js';
 import { duckduckgoProvider } from './providers/duckduckgo.js';
@@ -8,11 +9,13 @@ const PROVIDERS = {
     tavily: tavilyProvider,
     brave: braveProvider,
 };
-/** 环境变量名 → config key 字段映射。环境变量优先于 config。 */
+/** 环境变量名 → config key 字段映射。环境变量优先于 config。
+ *  config 值落盘时已加密（enc: 前缀），此处解密后使用（明文兼容透传）。 */
 function resolveKeys(config) {
+    const decrypt = (v) => (v ? decryptSecret(v) : v);
     return {
-        tavily: process.env.TAVILY_API_KEY ?? config.tavilyApiKey,
-        brave: process.env.BRAVE_API_KEY ?? config.braveApiKey,
+        tavily: process.env.TAVILY_API_KEY ?? decrypt(config.tavilyApiKey),
+        brave: process.env.BRAVE_API_KEY ?? decrypt(config.braveApiKey),
     };
 }
 /** 按 preference + key 可用性解析目标 provider。auto 优先级：tavily > brave > duckduckgo。 */
@@ -62,17 +65,53 @@ export function setFetchOverride(f) {
 function currentFetch() {
     return fetchOverride ?? createFetch();
 }
-/** 工具入口：解析 provider → search → 返回 WebSearchResponse。 */
+/** 运行时降级判定：鉴权失效（key 过期/被撤）、限流、服务端错误可换后端重试；
+ *  4xx 参数错误（400 等）换后端无意义；网络层错误（无 status）也降级（该后端连通性
+ *  问题，duckduckgo 兜底）。 */
+function isFallbackable(err) {
+    const status = err?.status;
+    return (typeof status !== 'number' ||
+        status >= 500 ||
+        status === 401 ||
+        status === 403 ||
+        status === 429);
+}
+/** 工具入口：解析 provider → search → 返回 WebSearchResponse。
+ *  'auto' 模式带运行时降级链：候选后端按 key 可用性排列（tavily > brave >
+ *  duckduckgo），当前后端因鉴权/限流/服务端/网络错误失败时依次降级——
+ *  此前 auto 只按 key **存在性**选一次，key 失效/过期即整体失败。
+ *  显式指定后端时尊重用户选择，单后端不降级。abort 立即上抛，不沿链继续。 */
 export async function runWebSearch(input, config, abort) {
     const keys = resolveKeys(config);
-    const provider = resolveProvider(config.provider, keys);
-    return provider.search({
+    const apiKeyFor = (provider) => provider.id === 'tavily' ? keys.tavily : provider.id === 'brave' ? keys.brave : undefined;
+    const search = (provider) => provider.search({
         query: input.query,
         limit: clampNumResults(input.numResults),
         recency: input.recency,
         signal: abort,
-        apiKey: provider.id === 'tavily' ? keys.tavily : provider.id === 'brave' ? keys.brave : undefined,
+        apiKey: apiKeyFor(provider),
         fetchImpl: currentFetch(),
     });
+    if (config.provider === 'auto') {
+        const chain = [tavilyProvider, braveProvider, duckduckgoProvider].filter((p) => p.isAvailable(apiKeyFor(p)));
+        let lastError = null;
+        for (const provider of chain) {
+            try {
+                return await search(provider);
+            }
+            catch (err) {
+                if (abort.aborted)
+                    throw err;
+                if (!isFallbackable(err))
+                    throw err;
+                lastError = err;
+            }
+        }
+        if (lastError instanceof Error)
+            throw lastError;
+        throw new Error(`websearch 无可用后端：${String(lastError)}`);
+    }
+    const provider = resolveProvider(config.provider, keys);
+    return search(provider);
 }
 export { clampNumResults, DEFAULT_NUM_RESULTS };

package/dist/tools/websearch/providers/brave.js

@@ -1,4 +1,4 @@
-import { DEFAULT_NUM_RESULTS } from '../types.js';
+import { DEFAULT_NUM_RESULTS, httpStatusError } from '../types.js';
 const BRAVE_SEARCH_URL = 'https://api.search.brave.com/res/v1/web/search';
 /** 导出供测试：recency → Brave freshness 代码映射。 */
 export function recencyToFreshness(recency) {
@@ -39,7 +39,7 @@ export const braveProvider = {
         });
         if (!response.ok) {
             const text = await response.text().catch(() => response.statusText);
-            throw new Error(`Brave API error (${response.status}): ${text}`);
+            throw httpStatusError(`Brave API error (${response.status}): ${text}`, response.status);
         }
         const data = (await response.json());
         const sources = [];

package/dist/tools/websearch/providers/duckduckgo.js

@@ -1,3 +1,4 @@
+import { httpStatusError } from '../types.js';
 const DUCKDUCKGO_SEARCH_URL = 'https://api.duckduckgo.com/';
 const AGENT_TOKEN = 'c0de-agent';
 function cleanText(value) {
@@ -49,7 +50,7 @@ async function callDuckDuckGoSearch(params) {
     });
     if (!response.ok) {
         const text = await response.text().catch(() => response.statusText);
-        throw new Error(`DuckDuckGo API error (${response.status}): ${text}`);
+        throw httpStatusError(`DuckDuckGo API error (${response.status}): ${text}`, response.status);
     }
     return (await response.json());
 }

package/dist/tools/websearch/providers/tavily.js

@@ -1,4 +1,4 @@
-import { DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS, MIN_NUM_RESULTS } from '../types.js';
+import { DEFAULT_NUM_RESULTS, httpStatusError, MAX_NUM_RESULTS, MIN_NUM_RESULTS } from '../types.js';
 const TAVILY_SEARCH_URL = 'https://api.tavily.com/search';
 function clamp(n) {
     if (n === undefined || Number.isNaN(n))
@@ -62,7 +62,7 @@ async function callTavilySearch(apiKey, params) {
     if (!response.ok) {
         const raw = await response.text().catch(() => response.statusText);
         const msg = getErrorMessage(safeParse(raw)) ?? (raw.trim() || response.statusText);
-        throw new Error(`Tavily API error (${response.status}): ${msg}`);
+        throw httpStatusError(`Tavily API error (${response.status}): ${msg}`, response.status);
     }
     return (await response.json());
 }

package/dist/tools/websearch/types.d.ts

@@ -47,5 +47,9 @@ declare const MAX_NUM_RESULTS = 20;
 declare const MIN_NUM_RESULTS = 1;
 /** clamp 结果数到 [MIN, MAX]；undefined/NaN 回退到 fallback。 */
 declare function clampNumResults(n: number | undefined, fallback?: number): number;
+/** 携带 HTTP 状态码的错误（降级链按 401/403/429/5xx 判定是否换后端重试）。 */
+declare function httpStatusError(message: string, status: number): Error & {
+    status: number;
+};
 export type { Recency, WebSearchParams, WebSearchProvider, WebSearchProviderId, WebSearchResponse, WebSearchSource, };
-export { clampNumResults, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS, MIN_NUM_RESULTS };
+export { clampNumResults, DEFAULT_NUM_RESULTS, httpStatusError, MAX_NUM_RESULTS, MIN_NUM_RESULTS };

package/dist/tools/websearch/types.js

@@ -15,4 +15,10 @@ function clampNumResults(n, fallback = DEFAULT_NUM_RESULTS) {
         return fallback;
     return Math.min(MAX_NUM_RESULTS, Math.max(MIN_NUM_RESULTS, Math.trunc(n)));
 }
-export { clampNumResults, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS, MIN_NUM_RESULTS };
+/** 携带 HTTP 状态码的错误（降级链按 401/403/429/5xx 判定是否换后端重试）。 */
+function httpStatusError(message, status) {
+    const err = new Error(message);
+    err.status = status;
+    return err;
+}
+export { clampNumResults, DEFAULT_NUM_RESULTS, httpStatusError, MAX_NUM_RESULTS, MIN_NUM_RESULTS };

package/dist/update/index.d.ts

@@ -1,10 +1,10 @@
 export type { HandoffServer } from './ipc.js';
-export { createHandoffServer, requestHandoff } from './ipc.js';
+export { confirmHandoff, createHandoffServer, requestHandoff } from './ipc.js';
 export type { UpdateScheduler, UpdateSchedulerOptions } from './scheduler.js';
 export { createUpdateScheduler } from './scheduler.js';
 export type { SerializedEntry, SerializedSession, SessionSnapshot } from './snapshot.js';
 export { orderSessionsByParent, restoreSessions, serializeSessions } from './snapshot.js';
-export type { HotUpdateOptions, HotUpdateResult, SpawnFn } from './updater.js';
-export { cleanupSnapshot, performHotUpdate, performInstall } from './updater.js';
+export type { HotUpdateOptions, HotUpdateResult, InstallMethod, InstallOnlyResult, SpawnFn, } from './updater.js';
+export { cleanupSnapshot, manualInstallCommand, performHandoff, performHotUpdate, performInstall, } from './updater.js';
 export type { UpdateCheckResult } from './version.js';
 export { checkForUpdate, compareSemver, getCurrentVersion } from './version.js';

package/dist/update/index.js

@@ -1,6 +1,6 @@
 // 热更新 + 会话迁移包（spec §18）。
-export { createHandoffServer, requestHandoff } from './ipc.js';
+export { confirmHandoff, createHandoffServer, requestHandoff } from './ipc.js';
 export { createUpdateScheduler } from './scheduler.js';
 export { orderSessionsByParent, restoreSessions, serializeSessions } from './snapshot.js';
-export { cleanupSnapshot, performHotUpdate, performInstall } from './updater.js';
+export { cleanupSnapshot, manualInstallCommand, performHandoff, performHotUpdate, performInstall, } from './updater.js';
 export { checkForUpdate, compareSemver, getCurrentVersion } from './version.js';

package/dist/update/ipc.d.ts

@@ -22,9 +22,14 @@ type HandoffOptions = {
     verify?: (token: string | undefined) => boolean;
     /**
      * 响应发出后退出进程（旧实例完整让渡：主服务与资源已在 onHandoff 中关闭）。
-     * 退出延迟 250ms 保证 HTTP 响应刷出；不设时仅响应不退出（测试用）。
+     * 退出延迟 250ms 保证 HTTP 响应刷出；不设时仅响应不退出（测试用 / 两阶段交接）。
      */
     exitAfterResponse?: boolean;
+    /**
+     * 收到 POST /handoff-confirm 时调用（两阶段交接第二阶段）：
+     * 新实例绑定端口成功后的确认。调用方在此清理定时器并退出进程。
+     */
+    onConfirm?: () => void | Promise<void>;
 };
 /**
  * requestHandoff 抛出的可区分错误（调用方据此分流处理）：
@@ -44,5 +49,11 @@ type HandoffError = Error & {
 declare function createHandoffServer(onHandoff: () => Promise<void>, opts?: HandoffOptions): Promise<HandoffServer>;
 /** 新实例请求旧实例让出端口（graceful shutdown）。失败抛可区分的 HandoffError。 */
 declare function requestHandoff(port: number, host?: string, token?: string): Promise<void>;
+/**
+ * 两阶段交接第二阶段（P3 回滚修复）：新实例绑定端口成功后 POST /handoff-confirm，
+ * 旧实例收到才退出进程。连接失败/旧实例已退出时静默——确认是尽力而为，
+ * 超时兜底由旧实例的复活窗口负责（端口占用状态是最终裁判）。
+ */
+declare function confirmHandoff(port: number, host?: string, token?: string): Promise<void>;
 export type { HandoffError, HandoffOptions, HandoffServer };
-export { createHandoffServer, requestHandoff };
+export { confirmHandoff, createHandoffServer, requestHandoff };

package/dist/update/ipc.js

@@ -18,7 +18,7 @@ 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 (req.method === 'POST' && (req.url === '/handoff' || req.url === '/handoff-confirm')) {
                 const authorized = opts.verify
                     ? opts.verify(req.headers.authorization?.replace(/^Bearer\s+/i, ''))
                     : expected.length > 0
@@ -29,6 +29,24 @@ function createHandoffServer(onHandoff, opts = {}) {
                     res.end(JSON.stringify({ ok: false, error: 'unauthorized' }));
                     return;
                 }
+                if (req.url === '/handoff-confirm') {
+                    // 两阶段交接第二阶段：新实例绑定成功后的确认。响应后由 onConfirm
+                    // 调度退出；不设 onConfirm 时直接退出（与 exitAfterResponse 独立）。
+                    try {
+                        res.writeHead(200, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ ok: true }));
+                        if (opts.onConfirm) {
+                            await opts.onConfirm();
+                        }
+                        else {
+                            setTimeout(() => process.exit(0), 250);
+                        }
+                    }
+                    catch (error) {
+                        console.error('[handoff] confirm handler failed:', error);
+                    }
+                    return;
+                }
                 try {
                     await onHandoff();
                     res.writeHead(200, { 'content-type': 'application/json' });
@@ -87,4 +105,20 @@ async function requestHandoff(port, host = '127.0.0.1', token) {
         throw error;
     }
 }
-export { createHandoffServer, requestHandoff };
+/**
+ * 两阶段交接第二阶段（P3 回滚修复）：新实例绑定端口成功后 POST /handoff-confirm，
+ * 旧实例收到才退出进程。连接失败/旧实例已退出时静默——确认是尽力而为，
+ * 超时兜底由旧实例的复活窗口负责（端口占用状态是最终裁判）。
+ */
+async function confirmHandoff(port, host = '127.0.0.1', token) {
+    try {
+        await fetch(`http://${host}:${port}/handoff-confirm`, {
+            method: 'POST',
+            ...(token ? { headers: { Authorization: `Bearer ${token}` } } : {}),
+        });
+    }
+    catch {
+        // 旧实例已退出或不可达：无确认对象，忽略。
+    }
+}
+export { confirmHandoff, createHandoffServer, requestHandoff };

package/dist/update/scheduler.js

@@ -1,3 +1,4 @@
+import { getCurrentVersion } from './version.js';
 const DEFAULT_INTERVAL_MS = 60 * 60 * 1000;
 const DEFAULT_INITIAL_DELAY_MS = 10_000;
 function createUpdateScheduler(opts) {
@@ -14,8 +15,10 @@ function createUpdateScheduler(opts) {
             r = await opts.checkFn();
         }
         catch {
-            // 异常降级：缓存 hasUpdate:false，但不触发 onUpdate（避免误报）。
-            lastResult = { hasUpdate: false, currentVersion: '0.0.0', latestVersion: '0.0.0' };
+            // 异常降级：缓存 hasUpdate:false + checkError，且保留真实当前版本
+            //（此前写死 '0.0.0'，前端/API 会展示错误版本号）。不触发 onUpdate（避免误报）。
+            const v = getCurrentVersion();
+            lastResult = { hasUpdate: false, currentVersion: v, latestVersion: v, checkError: true };
             return lastResult;
         }
         lastResult = r;

package/dist/update/snapshot.d.ts

@@ -11,6 +11,7 @@ type SerializedSession = {
     worktreePath: string | null;
     source: string | null;
     deletedAt: number | null;
+    deletedBatchId: string | null;
     createdAt: number;
     updatedAt: number;
 };
@@ -25,6 +26,17 @@ type SerializedEntry = {
     tokenCount: number;
     createdAt: number;
 };
+/** 序列化后的终端元信息（热更新后新实例按原 id 重建 shell）。 */
+type SerializedTerminal = {
+    id: string;
+    shell: string;
+    cwd: string;
+    title: string;
+    projectId?: string;
+    /** P3-7：用户勾选「更新后自动重启」的前台命令（如 `npm run dev`）；
+     *  新实例重建 shell 后把该命令写入 stdin 重跑。仅显式勾选才携带。 */
+    command?: string;
+};
 /** 热更新迁移快照（spec §18.2）。 */
 type SessionSnapshot = {
     version: string;
@@ -32,12 +44,15 @@ type SessionSnapshot = {
     entries: SerializedEntry[];
     config: unknown;
     timestamp: number;
+    /** P1：活跃终端元信息——进程无法续命，新实例据此在原位重建 shell（同 id，
+     *  前端持久化布局可无感重连）。旧快照缺省视为无终端。 */
+    terminals?: SerializedTerminal[];
 };
 /** 按 parentId 拓扑序排列 sessions，使父会话先于子会话插入（满足自引用 FK）。 */
 declare function orderSessionsByParent(list: SerializedSession[]): SerializedSession[];
-/** 从 DB 导出所有会话与条目为可序列化快照。 */
-declare function serializeSessions(handle: DB, config?: unknown): Promise<SessionSnapshot>;
+/** 从 DB 导出所有会话与条目为可序列化快照。terminals 为活跃终端元信息（可选）。 */
+declare function serializeSessions(handle: DB, config?: unknown, terminals?: SerializedTerminal[]): Promise<SessionSnapshot>;
 /** 把快照导入 DB（保留原始 id 与时间戳；父会话先插入以满足 FK）。 */
 declare function restoreSessions(handle: DB, snapshot: SessionSnapshot): Promise<void>;
-export type { SerializedEntry, SerializedSession, SessionSnapshot };
+export type { SerializedEntry, SerializedSession, SerializedTerminal, SessionSnapshot };
 export { orderSessionsByParent, restoreSessions, serializeSessions };

package/dist/update/snapshot.js

@@ -19,6 +19,7 @@ function toSerializedSession(row) {
         worktreePath: row.worktreePath,
         source: row.source,
         deletedAt: row.deletedAt ? toDateMs(row.deletedAt) : null,
+        deletedBatchId: row.deletedBatchId ?? null,
         createdAt: toDateMs(row.createdAt),
         updatedAt: toDateMs(row.updatedAt),
     };
@@ -53,8 +54,8 @@ function orderSessionsByParent(list) {
         visit(s);
     return ordered;
 }
-/** 从 DB 导出所有会话与条目为可序列化快照。 */
-async function serializeSessions(handle, config) {
+/** 从 DB 导出所有会话与条目为可序列化快照。terminals 为活跃终端元信息（可选）。 */
+async function serializeSessions(handle, config, terminals) {
     const [sRows, eRows] = await Promise.all([
         handle.db.select().from(sessions),
         handle.db.select().from(sessionEntries),
@@ -65,6 +66,7 @@ async function serializeSessions(handle, config) {
         entries: eRows.map(toSerializedEntry),
         config: config ?? null,
         timestamp: Date.now(),
+        ...(terminals && terminals.length > 0 ? { terminals } : {}),
     };
 }
 /** 把快照导入 DB（保留原始 id 与时间戳；父会话先插入以满足 FK）。 */
@@ -83,6 +85,7 @@ async function restoreSessions(handle, snapshot) {
             worktreePath: s.worktreePath,
             source: s.source,
             deletedAt: s.deletedAt != null ? new Date(s.deletedAt) : null,
+            deletedBatchId: s.deletedBatchId ?? null,
             createdAt: new Date(s.createdAt),
             updatedAt: new Date(s.updatedAt),
         })

package/dist/update/updater.d.ts

@@ -51,6 +51,8 @@ type HotUpdateOptions = {
     handoffPort?: number;
     /** 旧实例主服务端口；新实例 --port 复用（保证接管同一地址）。 */
     port?: number;
+    /** 旧实例绑定地址；新实例 --host 复用（保证接管同一地址）。 */
+    host?: string;
     /** 传给新实例的认证 token（经环境变量 C0DE_AUTH_TOKEN），保证新旧实例握手同 token。 */
     authToken?: string;
     /** 手动安装等待程序文件变更的超时（ms）；默认 10 分钟，超时放弃等待。 */
@@ -75,6 +77,20 @@ type InstallMethod = {
 declare function detectInstallMethod(): InstallMethod;
 /** 手动安装提示命令（unknown 安装方式时返回给前端展示）。 */
 declare function manualInstallCommand(pkg: string): string;
+/**
+ * 分阶段热更新的第二阶段（P0 修复：install 与 pause 解耦）。
+ *
+ * 调用方（/api/update/apply）顺序：
+ *   1. checkNow → hasUpdate
+ *   2. performInstall（仅安装；失败时**尚未暂停任何会话**，直接 409 可操作错误）
+ *   3. 安装成功 → pauseAll（暂停活跃 run 至安全点）
+ *   4. serializeSessions → performHandoff（本函数：写快照 + spawn 新实例）
+ *   5. spawn 失败 → 调用方 resumeAll 回滚暂停的会话
+ *
+ * 对比旧流程（pause → 序列化 → performHotUpdate 内含 install）：install 失败时
+ * 会话已被 pause/forcedAbort 且无回滚路径——更新失败顺带销毁进行中的工作。
+ */
+declare function performHandoff(snapshot: SessionSnapshot, method: InstallMethod, opts?: HotUpdateOptions): Promise<HotUpdateResult>;
 /**
  * 执行热更新（spec §18.1-18.2 + P0-2 修订流程）：
  *   1. 序列化当前会话状态到快照文件
@@ -96,4 +112,4 @@ declare function performInstall(opts?: HotUpdateOptions): Promise<InstallOnlyRes
 /** 清理快照临时目录（热更新完成或放弃后调用）。 */
 declare function cleanupSnapshot(snapshotPath: string): Promise<void>;
 export type { HotUpdateOptions, HotUpdateResult, InstallMethod, InstallOnlyResult, SpawnFn };
-export { cleanupSnapshot, detectInstallMethod, manualInstallCommand, performHotUpdate, performInstall, };
+export { cleanupSnapshot, detectInstallMethod, manualInstallCommand, performHandoff, performHotUpdate, performInstall, };

package/dist/update/updater.js

@@ -170,7 +170,7 @@ function defaultSpawn(_snapshotPath, argv, opts) {
         }
     });
 }
-/** 组装新实例 argv（serve --restore <snapshot> [--port] [--handoff-port]）。 */
+/** 组装新实例 argv（serve --restore <snapshot> [--port] [--host] [--handoff-port]）。 */
 function buildSpawnArgv(snapshotPath, opts) {
     const restoreFlag = opts.restoreFlag ?? '--restore';
     const argv = [
@@ -178,12 +178,55 @@ function buildSpawnArgv(snapshotPath, opts) {
         restoreFlag,
         snapshotPath,
         ...(opts.port !== undefined ? ['--port', String(opts.port)] : []),
+        ...(opts.host ? ['--host', opts.host] : []),
     ];
     if (opts.handoffPort !== undefined) {
         argv.push('--handoff-port', String(opts.handoffPort));
     }
     return argv;
 }
+/**
+ * 把快照写入临时目录（或 opts.snapshotPath），返回实际路径。
+ * 独立成函数供 performHotUpdate（一体流程）与 performHandoff（分阶段流程）共用。
+ */
+async function writeSnapshot(snapshot, opts) {
+    const snapshotPath = opts.snapshotPath ?? join(await mkdtemp(join(tmpdir(), 'c0de-update-')), 'snapshot.json');
+    await writeFile(snapshotPath, JSON.stringify(snapshot), 'utf8');
+    return snapshotPath;
+}
+/** 安装完成后的滚动切换：spawn 新实例（restore 快照 + handoff 端口接管由新实例发起）。 */
+async function spawnAfterInstall(snapshotPath, method, opts) {
+    const spawnNew = opts.spawnNewInstanceFn ?? defaultSpawn;
+    const argv = buildSpawnArgv(snapshotPath, opts);
+    try {
+        await spawnNew(snapshotPath, argv, opts);
+    }
+    catch (error) {
+        return {
+            _tag: 'spawn_failed',
+            error: error instanceof Error ? error.message : String(error),
+            snapshotPath,
+        };
+    }
+    return { _tag: 'success', snapshotPath, installMethod: method.kind };
+}
+/**
+ * 分阶段热更新的第二阶段（P0 修复：install 与 pause 解耦）。
+ *
+ * 调用方（/api/update/apply）顺序：
+ *   1. checkNow → hasUpdate
+ *   2. performInstall（仅安装；失败时**尚未暂停任何会话**，直接 409 可操作错误）
+ *   3. 安装成功 → pauseAll（暂停活跃 run 至安全点）
+ *   4. serializeSessions → performHandoff（本函数：写快照 + spawn 新实例）
+ *   5. spawn 失败 → 调用方 resumeAll 回滚暂停的会话
+ *
+ * 对比旧流程（pause → 序列化 → performHotUpdate 内含 install）：install 失败时
+ * 会话已被 pause/forcedAbort 且无回滚路径——更新失败顺带销毁进行中的工作。
+ */
+async function performHandoff(snapshot, method, opts = {}) {
+    const snapshotPath = await writeSnapshot(snapshot, opts);
+    return spawnAfterInstall(snapshotPath, method, opts);
+}
 /**
  * 执行热更新（spec §18.1-18.2 + P0-2 修订流程）：
  *   1. 序列化当前会话状态到快照文件
@@ -197,9 +240,7 @@ function buildSpawnArgv(snapshotPath, opts) {
  */
 async function performHotUpdate(snapshot, opts = {}) {
     const pkg = opts.packageName ?? DEFAULT_PACKAGE;
-    const dir = await mkdtemp(join(tmpdir(), 'c0de-update-'));
-    const snapshotPath = opts.snapshotPath ?? join(dir, 'snapshot.json');
-    await writeFile(snapshotPath, JSON.stringify(snapshot), 'utf8');
+    const snapshotPath = await writeSnapshot(snapshot, opts);
     // 识别安装方式
     const method = detectInstallMethod();
     // 安装前采集程序文件基线（watch 依赖此判断「变更已发生」）
@@ -246,19 +287,7 @@ async function performHotUpdate(snapshot, opts = {}) {
         }
     }
     // 程序文件已变更（自动安装落盘或用户手动安装完成）→ 滚动切换
-    const spawnNew = opts.spawnNewInstanceFn ?? defaultSpawn;
-    const argv = buildSpawnArgv(snapshotPath, opts);
-    try {
-        await spawnNew(snapshotPath, argv, opts);
-    }
-    catch (error) {
-        return {
-            _tag: 'spawn_failed',
-            error: error instanceof Error ? error.message : String(error),
-            snapshotPath,
-        };
-    }
-    return { _tag: 'success', snapshotPath, installMethod: method.kind };
+    return spawnAfterInstall(snapshotPath, method, opts);
 }
 /**
  * 仅安装新版本（P2-7：无活跃 serve 的 `c0de update --apply`）。
@@ -291,4 +320,4 @@ async function performInstall(opts = {}) {
 async function cleanupSnapshot(snapshotPath) {
     await rm(join(snapshotPath, '..'), { recursive: true, force: true }).catch(() => { });
 }
-export { cleanupSnapshot, detectInstallMethod, manualInstallCommand, performHotUpdate, performInstall, };
+export { cleanupSnapshot, detectInstallMethod, manualInstallCommand, performHandoff, performHotUpdate, performInstall, };

package/dist/update/version.d.ts

@@ -3,6 +3,9 @@ type UpdateCheckResult = {
     currentVersion: string;
     latestVersion: string;
     releaseNotes?: string;
+    /** P3-8：检查本身失败（网络/registry 异常），与「已是最新」区分——
+     *  消费方据此给出「稍后重试」而非误导性的「无更新」。 */
+    checkError?: boolean;
 };
 type CheckOptions = {
     fetchImpl?: typeof fetch;

package/dist/update/version.js

@@ -48,16 +48,22 @@ async function checkForUpdate(opts = {}) {
     };
     try {
         const res = await fetchImpl(`${registry}/${pkg}/latest`);
-        if (!res.ok)
+        if (!res.ok) {
+            // 非 200（404/5xx/限流）→ 检查失败而非无更新
+            result.checkError = true;
             return result;
+        }
         const data = (await res.json());
-        if (!data.version)
+        if (!data.version) {
+            result.checkError = true;
             return result;
+        }
         result.latestVersion = data.version;
         result.hasUpdate = compareSemver(current, data.version) < 0;
     }
     catch {
-        // 离线/网络错误：保守地报告无更新
+        // 离线/网络错误：保守地报告无更新，但标记检查失败供上层区分提示
+        result.checkError = true;
     }
     return result;
 }

package/drizzle/0008_tranquil_lily_hollister.sql

@@ -0,0 +1 @@
+ALTER TABLE "sessions" ADD COLUMN "deleted_batch_id" uuid;

package/drizzle/0010_usage_events_ledger.sql

@@ -0,0 +1,17 @@
+CREATE TABLE "usage_events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"call_id" uuid NOT NULL,
+	"session_id" uuid,
+	"project_id" text,
+	"provider" text NOT NULL,
+	"model" text NOT NULL,
+	"input_tokens" bigint DEFAULT 0 NOT NULL,
+	"output_tokens" bigint DEFAULT 0 NOT NULL,
+	"cache_read" bigint DEFAULT 0,
+	"cost" real,
+	"timestamp" bigint NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "uq_usage_events_call" ON "usage_events" USING btree ("call_id");--> statement-breakpoint
+CREATE INDEX "idx_usage_events_project_ts" ON "usage_events" USING btree ("project_id","timestamp");--> statement-breakpoint
+CREATE INDEX "idx_usage_events_ts" ON "usage_events" USING btree ("timestamp");

package/drizzle/0011_slow_slapstick.sql

@@ -0,0 +1,12 @@
+CREATE TABLE "app_meta" (
+	"key" text PRIMARY KEY NOT NULL,
+	"value" text NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "kanban_boards" DROP CONSTRAINT "kanban_boards_project_id_projects_id_fk";
+--> statement-breakpoint
+ALTER TABLE "kanban_boards" ALTER COLUMN "project_id" DROP NOT NULL;--> statement-breakpoint
+ALTER TABLE "kanban_boards" ADD COLUMN "deleted_at" timestamp with time zone DEFAULT null;--> statement-breakpoint
+ALTER TABLE "kanban_boards" ADD COLUMN "deleted_project_name" text;--> statement-breakpoint
+ALTER TABLE "projects" ADD COLUMN "trusted_at" timestamp with time zone DEFAULT null;--> statement-breakpoint
+ALTER TABLE "kanban_boards" ADD CONSTRAINT "kanban_boards_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE set null ON UPDATE no action;

package/drizzle/0012_chief_timeslip.sql

@@ -0,0 +1 @@
+ALTER TABLE "kanban_boards" ADD COLUMN "purge_pending_at" timestamp with time zone DEFAULT null;

package/drizzle/0013_swift_zeigeist.sql

@@ -0,0 +1 @@
+ALTER TABLE "kanban_boards" ADD COLUMN "deleted_project_worktree" text;

package/drizzle/0014_flimsy_legion.sql

@@ -0,0 +1 @@
+ALTER TABLE "projects" ADD COLUMN "risk_fingerprint" text DEFAULT null;