c0de-agent 1.10.0 → 1.12.0

package/dist/server/routes/update.js

@@ -1,23 +1,64 @@
 import { Hono } from 'hono';
-import { getCurrentVersion, performHotUpdate, serializeSessions } from '../../update/index.js';
+import { getSession } from '../../session/session.js';
+import { getCurrentVersion, manualInstallCommand, performHandoff, performInstall, serializeSessions, } from '../../update/index.js';
 import { apiError } from '../middleware/error.js';
 /**
  * GET /api/update — 返回后台调度器缓存的版本检查结果（spec §18.1）。
  * 路由本身不触发 npm registry 请求；调度器周期性 checkNow 写入缓存，
  * 路由读缓存（避免每个前端轮询都打外网）。
  *
- * POST /api/update/apply — 手动触发热更新（spec §18.2）：
- *   序列化当前会话 → performHotUpdate（npm install -g + spawn 新实例 + handoffPort）。
- *   旧实例通过 handoff 端点优雅退出，新实例 restore 快照并接管端口。
- *   响应立即返回（不阻塞 spawn），实际接管由 handoff IPC 异步完成。
- *   dev（vite）模式无 handoff server，返回 409——热更新仅在独立 serve 进程可用。
+ * POST /api/update/apply — 手动触发热更新（spec §18.2），P0 修复后顺序：
+ *   1. checkNow 确认有更新；
+ *   2. performInstall（仅安装新版本）——失败时**尚未暂停任何会话**，
+ *      直接返回可操作错误（409 + 手动更新命令），用户工作零损失；
+ *   3. 安装成功 → pauseAll 暂停活跃 run 至安全点（原子操作完成）；
+ *   4. serializeSessions → performHandoff（写快照 + spawn 新实例）；
+ *   5. spawn 失败 → resumeAll 回滚暂停的会话，返回明确错误。
+ *
+ * 旧实例通过 handoff 端点优雅退出，新实例 restore 快照并接管端口。
+ * 响应立即返回（不阻塞 spawn），实际接管由 handoff IPC 异步完成。
+ * dev（vite）模式无 handoff server，返回 409——热更新仅在独立 serve 进程可用。
  */
 function createUpdateRoute(ctx) {
     const app = new Hono();
-    app.get('/', (c) => {
+    app.get('/', async (c) => {
+        // 热更新影响面（P2-11）：apply 前由前端确认框逐项展示受影响对象。
+        // 顶层 run（主 agent）+ 终端数；子 agent 归父会话，不重复列出。
+        const active = ctx.agentManager.listActive();
+        const topRuns = active.filter((r) => !r.parentSessionId);
+        const runs = [];
+        for (const r of topRuns) {
+            let title = r.sessionId.slice(0, 8);
+            try {
+                const session = await getSession(ctx.db, r.sessionId);
+                if (session)
+                    title = session.title;
+            }
+            catch {
+                // 会话查询失败：回退 id 前缀展示
+            }
+            runs.push({
+                sessionId: r.sessionId,
+                title,
+                ...(r.agentType ? { agentType: r.agentType } : {}),
+            });
+        }
+        const impact = { runs, terminalCount: ctx.ptyManager.list().length };
+        // P2-8：update.enabled=false 时无 handoff server，apply 必然 409。
+        // 不再触发 checkNow，也不返回 hasUpdate，避免横幅出现一个点了必失败的应用按钮。
+        if (ctx.config.update.enabled === false) {
+            const v = getCurrentVersion();
+            return c.json({
+                hasUpdate: false,
+                disabled: true,
+                currentVersion: v,
+                latestVersion: v,
+                impact,
+            });
+        }
         const cached = ctx.updateScheduler.getLastResult();
         if (cached)
-            return c.json(cached);
+            return c.json({ ...cached, impact });
         // 无缓存（首次启动延迟未到）：同步触发一次，避免前端首屏空。
         // 不 await——保持 GET 语义非阻塞；前端下次轮询拿到结果。
         void ctx.updateScheduler.checkNow();
@@ -26,6 +67,7 @@ function createUpdateRoute(ctx) {
             hasUpdate: false,
             currentVersion: v,
             latestVersion: v,
+            impact,
         });
     });
     app.post('/apply', async (c) => {
@@ -36,20 +78,60 @@ function createUpdateRoute(ctx) {
         if (!result.hasUpdate) {
             return apiError(c, 409, 'NO_UPDATE', '已是最新版本，无需热更新');
         }
+        // P0 修复：install 先行。失败（网络/权限/unknown 安装方式）时未触碰任何
+        // 会话状态，直接返回可操作错误——旧流程先 pause 后 install，失败时
+        // 已暂停/强杀的会话无回滚路径。
+        const install = await performInstall({});
+        if (install._tag === 'install_failed') {
+            return apiError(c, 409, 'INSTALL_FAILED', install.error, {
+                command: manualInstallCommand('c0de-agent'),
+            });
+        }
+        if (install._tag === 'manual_install_required') {
+            return apiError(c, 409, 'MANUAL_UPDATE_REQUIRED', install.error, {
+                command: install.command,
+            });
+        }
+        const method = { kind: install.installMethod };
+        // 安装已成功 → 暂停所有活跃 run，等其到达安全暂停点（原子操作完成）。
+        // 注意：暂停不是「可恢复快照」——新实例只有 DB 状态、无内存 agent run，
+        // 进行中的对话会以 interrupted 呈现，用户重发上一条消息即可继续（幂等
+        // 检查跳过重复 append）。工具副作用不回滚。
+        const pauseTimeoutMs = ctx.config.update.pauseTimeoutMs ?? 30_000;
+        const pauseResult = await ctx.agentManager.pauseAll(pauseTimeoutMs);
         const snapshot = await serializeSessions(ctx.db, ctx.config);
-        const r = await performHotUpdate(snapshot, {
+        const r = await performHandoff(snapshot, method, {
             handoffPort: ctx.handoff.port,
             port: ctx.port,
-            authToken: ctx.authToken,
+            // P2-16：传当前 bootstrap（轮换后 ctx.authToken 可能已过期）；
+            // 旧实例 handoff 端点经 verifyHandoff 接受当前/历史 bootstrap 与设备 token。
+            authToken: ctx.authManager?.bootstrap ?? ctx.authToken,
         });
-        if (r._tag === 'success') {
-            return c.json({
-                ok: true,
-                snapshotPath: r.snapshotPath,
-                latestVersion: result.latestVersion,
+        if (r._tag !== 'success') {
+            // P0 回滚：spawn 失败（含程序文件未就绪等）→ 恢复被暂停的会话。
+            // forcedAbort 的无法恢复（已中止），但这是超时兜底，属可接受损失。
+            for (const id of pauseResult.pausedIds) {
+                ctx.agentManager.resume(id);
+            }
+            if (r._tag === 'manual_install_required') {
+                return apiError(c, 409, 'MANUAL_UPDATE_REQUIRED', r.error, {
+                    command: r.command,
+                    snapshotPath: r.snapshotPath,
+                    resumedSessions: pauseResult.pausedIds.length,
+                });
+            }
+            return apiError(c, 500, 'HOT_UPDATE_FAILED', `${r._tag}: ${r.error}`, {
+                resumedSessions: pauseResult.pausedIds.length,
             });
         }
-        return apiError(c, 500, 'HOT_UPDATE_FAILED', `${r._tag}: ${'error' in r ? r.error : 'unknown'}`);
+        return c.json({
+            ok: true,
+            snapshotPath: r.snapshotPath,
+            latestVersion: result.latestVersion,
+            installMethod: r.installMethod,
+            pausedSessions: pauseResult.paused,
+            forcedAbort: pauseResult.forcedAbort,
+        });
     });
     return app;
 }

package/dist/server/server.d.ts

@@ -1,8 +1,8 @@
 import type { Hono } from 'hono';
 import type { DB } from '../db/client.js';
-import type { Registry } from '../llm/registry.js';
 import type { Config } from '../shared/types/config.js';
 import { checkForUpdate, createHandoffServer } from '../update/index.js';
+import { buildRegistryFromConfig, syncRegistryFromConfig } from './registry-config.js';
 import type { ServerContext } from './types.js';
 type StartServerOptions = {
     port?: number;
@@ -31,15 +31,6 @@ type BootstrappedServer = {
     ctx: ServerContext;
     close(): Promise<void>;
 };
-/** 把 config.providers 注册到新建的 LLM registry（修复此前空 registry 的遗漏）。 */
-declare function buildRegistryFromConfig(config: Config): Registry;
-/**
- * config 变更后原子地同步 registry：在隔离的 next registry 上重建全部路由，
- * 完成后一次性替换 registry 内部 table 引用。运行中的 resolveRoute 任何时刻
- * 看到的都是完整的旧表或完整的新表，不会读到「已清空但未注册完」的半状态，
- * 因此不会把本可用的 provider 误判为 NoRoute。ServerContext 立即生效，无需重启。
- */
-declare function syncRegistryFromConfig(registry: Registry, config: Config): void;
 /** 解析 PGLite 持久化数据目录：优先 C0DE_DB_DIR，否则全局数据根下 pglite 子目录。
  *
  * 历史上数据库放在 <cwd>/.c0de/pglite（项目级），但项目 DB schema 通过 projectId
@@ -50,8 +41,9 @@ declare function resolveDbDir(): string;
  * 1. security.authEnabled 显式为 false → 无认证（用户显式选择）。
  * 2. 用户配置 security.token → 使用。
  * 3. 环境变量 C0DE_AUTH_TOKEN（热更新新实例经 updater 传入）→ 采用并落盘。
- * 4. dataDir 下 auth-token 文件（跨重启/热更新稳定）→ 复用。
- * 5. 都没有 → 生成随机 token 并写入 auth-token（0600）。
+ * 4. 已有已注册设备 → 复用 auth-token 文件（跨重启稳定；设备 token 存 devices.json）。
+ * 5. 无已注册设备（首设备待注册态）→ 每次 serve 都重新生成 bootstrap，刷新
+ *    firstDeviceTtlMs 窗口。此前「复用旧文件」会让过期 bootstrap 无法通过重启恢复。
  */
 declare function resolveAuthToken(config: Config, dataDir: string): string | undefined;
 /**

package/dist/server/server.js

@@ -1,6 +1,6 @@
 // src/server/server.ts
-import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { randomBytes } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { connect as tcpConnect } from 'node:net';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -8,56 +8,20 @@ import { serve } from '@hono/node-server';
 import { WebSocketServer } from 'ws';
 import { BUILTIN_AGENTS, createAgentRegistry } from '../core/agents/index.js';
 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, rebuildRegistry, registerProvider, } from '../llm/registry.js';
 import { initPlugins } from '../plugins/index.js';
+import { markDeadBackgroundJobs } from '../session/jobs.js';
+import { purgeDeletedSessions, purgeEmptySessions, purgeTemporarySessions, TRASH_PURGE_GRACE_MS, TRASH_RETENTION_MS, } from '../session/session.js';
 import { createDefaultRegistry, createDefaultURLRegistry } from '../tools/index.js';
-import { checkForUpdate, createHandoffServer, createUpdateScheduler, requestHandoff, restoreSessions, } from '../update/index.js';
+import { checkForUpdate, confirmHandoff, createHandoffServer, createUpdateScheduler, requestHandoff, restoreSessions, } from '../update/index.js';
 import { createAgentManager } from './agent-manager.js';
 import { createApp } from './app.js';
+import { createAuthManager } from './auth-manager.js';
 import { isAllowedOrigin } from './middleware/cors.js';
 import { createPermissionStore } from './permission/store.js';
+import { buildRegistryFromConfig, syncRegistryFromConfig } from './registry-config.js';
 import { PTYManager } from './terminal/pty-manager.js';
-/** 把 config.providers 注册到新建的 LLM registry（修复此前空 registry 的遗漏）。 */
-function buildRegistryFromConfig(config) {
-    const registry = createRegistry();
-    for (const p of config.providers) {
-        registerProviderFromConfig(registry, p);
-    }
-    return registry;
-}
-function registerProviderFromConfig(registry, p) {
-    // 兼容 config.json 中以 _tag 标识 provider 的格式（name 缺失时回退到 _tag）
-    const name = p.name || p._tag;
-    if (!name || !p.baseURL)
-        return;
-    // baseURL 已含 /v1 时用 /chat/completions，避免 /v1/v1 双重前缀
-    const path = p.baseURL.replace(/\/+$/, '').endsWith('/v1') ? '/chat/completions' : undefined;
-    registerProvider(registry, {
-        name,
-        baseURL: p.baseURL,
-        apiKey: p.apiKey ? decryptSecret(p.apiKey) : p.apiKey,
-        ...(path ? { path } : {}),
-        // 传递用户配置的 per-model capabilities（contextWindow 等），
-        // 否则 resolveRoute 回退到 DEFAULT_MODEL_CAPABILITIES，可能导致预算过小。
-        ...(p.models ? { models: overrideToCapabilities(p.models) } : {}),
-    });
-}
-/**
- * config 变更后原子地同步 registry：在隔离的 next registry 上重建全部路由，
- * 完成后一次性替换 registry 内部 table 引用。运行中的 resolveRoute 任何时刻
- * 看到的都是完整的旧表或完整的新表，不会读到「已清空但未注册完」的半状态，
- * 因此不会把本可用的 provider 误判为 NoRoute。ServerContext 立即生效，无需重启。
- */
-function syncRegistryFromConfig(registry, config) {
-    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/) 同约定——
  * 数据库等运行时数据放全局，项目 .c0de/ 只留配置和扩展。 */
@@ -82,8 +46,9 @@ function resolveDbDir() {
  * 1. security.authEnabled 显式为 false → 无认证（用户显式选择）。
  * 2. 用户配置 security.token → 使用。
  * 3. 环境变量 C0DE_AUTH_TOKEN（热更新新实例经 updater 传入）→ 采用并落盘。
- * 4. dataDir 下 auth-token 文件（跨重启/热更新稳定）→ 复用。
- * 5. 都没有 → 生成随机 token 并写入 auth-token（0600）。
+ * 4. 已有已注册设备 → 复用 auth-token 文件（跨重启稳定；设备 token 存 devices.json）。
+ * 5. 无已注册设备（首设备待注册态）→ 每次 serve 都重新生成 bootstrap，刷新
+ *    firstDeviceTtlMs 窗口。此前「复用旧文件」会让过期 bootstrap 无法通过重启恢复。
  */
 function resolveAuthToken(config, dataDir) {
     if (config.security.authEnabled === false)
@@ -102,13 +67,16 @@ function resolveAuthToken(config, dataDir) {
         }
         return envToken;
     }
-    try {
-        const existing = readFileSync(tokenFile, 'utf-8').trim();
-        if (existing)
-            return existing;
-    }
-    catch {
-        // 文件不存在，走生成分支
+    // 已有设备 → 复用 auth-token 文件，保持跨重启稳定（已授权设备经 devices.json 认 token）。
+    if (hasRegisteredDevices(dataDir)) {
+        try {
+            const existing = readFileSync(tokenFile, 'utf-8').trim();
+            if (existing)
+                return existing;
+        }
+        catch {
+            // 文件不存在，走生成分支
+        }
     }
     const generated = randomBytes(24).toString('hex');
     try {
@@ -120,6 +88,19 @@ function resolveAuthToken(config, dataDir) {
     }
     return generated;
 }
+/** dataDir 下是否存在已授权设备（devices.json 非空）。 */
+function hasRegisteredDevices(dataDir) {
+    try {
+        const path = join(dataDir, 'devices.json');
+        if (!existsSync(path))
+            return false;
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        return Array.isArray(parsed.devices) && parsed.devices.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
 /** 只读 dataDir 下已存在的 auth-token（新实例 handoff 握手用；不生成）。 */
 function readAuthTokenFile(dataDir) {
     try {
@@ -185,6 +166,19 @@ async function buildServerContext(db, opts = {}) {
     // 工作流注册表：三级发现（builtin → global → project），eager 初始化。
     // 此前是惰性 getter 只注册 builtin，导致项目级 .c0de/workflows/*.js 永远不可见。
     const workflowRegistry = await createAndPopulateRegistry(cwd);
+    const dataDir = resolveDbDir();
+    // 先解析/生成 bootstrap token（落盘），再创建 authManager 读取——
+    // 首启时文件由 resolveAuthToken 生成，顺序颠倒会导致 bootstrap 读到空值。
+    const resolvedToken = resolveAuthToken(config, dataDir);
+    const authManager = createAuthManager({
+        dataDir,
+        ...(config.security.token && config.security.token.length > 0
+            ? { staticToken: config.security.token }
+            : {}),
+        ...(config.security.firstDeviceTtlMs !== undefined
+            ? { firstDeviceTtlMs: config.security.firstDeviceTtlMs }
+            : {}),
+    });
     const ctx = {
         db,
         config,
@@ -196,7 +190,10 @@ async function buildServerContext(db, opts = {}) {
         agentManager: createAgentManager(),
         permissionStore: createPermissionStore(),
         permissionMode: config.permission.defaultMode,
-        authToken: resolveAuthToken(config, resolveDbDir()),
+        sessionPermissionModes: new Map(),
+        sessionAlwaysAllow: new Map(),
+        authToken: resolvedToken,
+        authManager: config.security.authEnabled === false ? undefined : authManager,
         // Agent 注册表：内置 4 个默认 agent；项目/用户自定义 agent 可在启动后补充加载。
         agentRegistry: (() => {
             const reg = createAgentRegistry();
@@ -220,11 +217,12 @@ async function buildServerContext(db, opts = {}) {
         ctx,
         dispose: async () => {
             // dev 重建前调用：中止活跃 run + settle pending permission +
-            // 停 scheduler。**不 close db**（调用方持有）。
+            // 停 scheduler + 关 devices.json watcher。**不 close db**（调用方持有）。
             ctx.agentManager.dispose();
             ctx.permissionStore.dispose();
             ctx.updateScheduler.stop();
             ctx.ptyManager.dispose();
+            ctx.authManager?.dispose();
         },
     };
 }
@@ -331,12 +329,60 @@ async function bootstrapServerContext(opts = {}) {
         db = await createDevDb(cwd);
     }
     const { ctx, dispose } = await buildServerContext(db, opts);
+    // P2-4 + A3：回收站两阶段清理——启动时清一次 + 每 24h 清一次。
+    // 阶段一标记到期条目进入宽限期（UI 可见可恢复），阶段二物理清除宽限期满的条目。
+    // fire-and-forget：清理失败不阻塞服务启动；结果落日志可查。
+    const runTrashPurge = () => {
+        void purgeDeletedSessions(db)
+            .then(({ marked, deleted }) => {
+            if (marked > 0) {
+                console.log(`[server] 回收站清理：${marked} 个会话已到期，进入 ${TRASH_PURGE_GRACE_MS / (24 * 60 * 60 * 1000)} 天宽限期（期间可恢复）`);
+            }
+            if (deleted > 0) {
+                console.log(`[server] 回收站清理：已物理清除 ${deleted} 个超过宽限期的会话（保留期 ${TRASH_RETENTION_MS / (24 * 60 * 60 * 1000)} 天）`);
+            }
+        })
+            .catch(() => { });
+    };
+    runTrashPurge();
+    const purgeTimer = setInterval(() => {
+        runTrashPurge();
+        // P2：CLI print / 工作流临时会话同样每日清理（30 天保留）
+        void purgeTemporarySessions(db).catch(() => { });
+        // C4：长期空置的 web 空会话每日清理（7 天保留）
+        void purgeEmptySessions(db).catch(() => { });
+    }, 24 * 60 * 60 * 1000);
+    purgeTimer.unref();
+    // P2：启动时同步清一次临时会话（每日定时之外的兜底）
+    void purgeTemporarySessions(db).catch(() => { });
+    // C4：启动时同步清一次空会话（兜底）
+    void purgeEmptySessions(db).catch(() => { });
+    // P2：标记崩溃遗留的后台子 agent 任务（lastRun=running 的 subagent 会话）
+    // 并给父会话注入失败通知。fire-and-forget：失败不阻塞启动。
+    void markDeadBackgroundJobs(db).catch(() => { });
+    // P2-15：PGLite WAL 周期刷盘（30s），缩短 kill -9 等突然停机时的已提交数据丢失窗口。
+    const syncTimer = db.sync
+        ? setInterval(() => {
+            void db.sync?.().catch(() => { });
+        }, 30_000)
+        : null;
+    syncTimer?.unref();
     return {
         ctx,
         close: async () => {
+            clearInterval(purgeTimer);
+            if (syncTimer)
+                clearInterval(syncTimer);
             await dispose();
-            if (ownsDb)
+            if (ownsDb) {
                 await db.close();
+                // P0 修复：优雅关闭（含热更新 handoff）时显式释放 .dev.lock。
+                // 旧流程依赖新实例的 stale-PID 检测清理锁文件，而旧进程在 handoff
+                // 响应后延迟 250ms 才退出——新实例若在该窗口内做锁检查（PID 仍存活）
+                // 会抛「Database is locked」崩溃，且旧实例已退出，双输。显式释放后
+                // 锁文件在进程存活期就已移除，新实例直接重建锁，无竞态窗口。
+                releaseDevDbLock(resolveDbDir());
+            }
         },
     };
 }
@@ -378,25 +424,15 @@ async function requestHandoffWithRetry(port, token, maxAttempts = 30, delayMs =
     }
     throw new Error(`handoff: old instance on port ${port} did not release after ${maxAttempts} attempts`);
 }
-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) {
-        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);
-    // config.update.enabled 时启动后台调度器。
-    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.authToken;
+/**
+ * 两阶段 handoff 的确认窗口（P3 回滚修复）：旧实例响应 POST /handoff 后不退出，
+ * 等待新实例绑定端口成功后 POST /handoff-confirm 再退。窗口内未收到确认
+ * （新实例启动失败）→ 旧实例原地复活重新接管端口，用户工作零损失。
+ * 窗口需覆盖新实例 bootstrap（DB 迁移/快照恢复）耗时，取 60s 留裕量。
+ */
+const HANDOFF_CONFIRM_WINDOW_MS = 60_000;
+/** 组装终端 WebSocket upgrade 处理器（bringUp 与复活共用）。 */
+function attachTerminalUpgrade(ctx, wss, server) {
     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$/);
@@ -412,10 +448,14 @@ async function startServer(opts = {}) {
             socket.destroy();
             return;
         }
-        // 认证：token 通过 query 参数传递（浏览器 WS 无法设置 Authorization header）
-        if (expectedToken) {
+        // 认证：token 通过 query 参数传递（浏览器 WS 无法设置 Authorization header）。
+        // P2-16：优先 authManager 校验（设备 token）；回退 ctx.authToken 兼容测试上下文。
+        if (ctx.authManager || ctx.authToken) {
             const token = url.searchParams.get('token');
-            if (token !== expectedToken) {
+            const ok = ctx.authManager
+                ? ctx.authManager.verify(token ?? undefined)
+                : token === ctx.authToken;
+            if (!ok) {
                 socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
                 socket.destroy();
                 return;
@@ -434,31 +474,126 @@ async function startServer(opts = {}) {
             }
         });
     });
-    let closed = false;
-    const closeMain = async () => {
-        if (closed)
-            return;
-        closed = true;
-        wss.close();
-        server.close();
-        await closeCtx();
+}
+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) {
+        const pendingToken = process.env.C0DE_AUTH_TOKEN ?? readAuthTokenFile(resolveDbDir());
+        await requestHandoffWithRetry(opts.handoffPort, pendingToken);
+    }
+    // 两阶段 handoff 状态（旧实例视角）：确认窗口定时器与复活互斥锁。
+    let confirmTimer = null;
+    let reviving = false;
+    let handoffServer;
+    let currentClose = null;
+    // RunningServer 暴露的稳定句柄（复活后更新；app/authToken 每次 bringUp 重建）。
+    let currentApp = null;
+    let currentAuthToken;
+    const clearConfirmTimer = () => {
+        if (confirmTimer) {
+            clearTimeout(confirmTimer);
+            confirmTimer = null;
+        }
+    };
+    /**
+     * 组装完整服务栈（bootstrap → app → 调度器 → 绑定端口 → WS → handoff server）。
+     * 首次启动与超时复活共用。复活时新实例可能已绑定端口：serve() 抛 EADDRINUSE
+     * 说明新实例实际上已接管（确认请求丢失），旧实例退出即可。
+     */
+    const bringUp = async () => {
+        const { ctx, close: closeCtx } = await bootstrapServerContext(opts);
+        const app = createApp(ctx);
+        // config.update.enabled 时启动后台调度器。
+        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。
+        const wss = new WebSocketServer({ noServer: true });
+        attachTerminalUpgrade(ctx, wss, server);
+        let closed = false;
+        const closeMain = async () => {
+            if (closed)
+                return;
+            closed = true;
+            wss.close();
+            server.close();
+            await closeCtx();
+        };
+        const close = async () => {
+            clearConfirmTimer();
+            await closeMain();
+            await handoffServer?.close();
+        };
+        currentClose = close;
+        currentApp = app;
+        currentAuthToken = ctx.authToken;
+        // spec §18.3 handoff server：旧实例收到 POST /handoff 后关闭主服务与资源，
+        // 响应 200。两阶段交接：不再立即退出——等待新实例 POST /handoff-confirm
+        // （onConfirm）确认接管；窗口超时未确认则 revive 原地复活。
+        // config.update.enabled=false 或 skipHandoff 时跳过。
+        if (ctx.config.update.enabled && !opts.skipHandoff) {
+            const createHandoff = opts.createHandoffFn ?? createHandoffServer;
+            handoffServer = await createHandoff(closeMain, {
+                // P2-16：token 轮换后新旧实例 bootstrap 可能不同，用 verifyHandoff 接受
+                // 当前/历史 bootstrap 与设备 token；无 authManager 回退字符串比较。
+                ...(ctx.authManager
+                    ? { verify: (t) => ctx.authManager?.verifyHandoff(t) ?? false }
+                    : { expectedToken: ctx.authToken }),
+                exitAfterResponse: false,
+                onConfirm: () => {
+                    // 新实例确认已接管端口 → 旧实例退出（延迟保证确认响应刷出）。
+                    clearConfirmTimer();
+                    setTimeout(() => process.exit(0), 250);
+                },
+            });
+            ctx.handoff = { port: handoffServer.port, server: handoffServer };
+            // 确认窗口：新实例启动失败时旧实例复活（保留进程句柄，定时器不可 unref）。
+            confirmTimer = setTimeout(() => {
+                void (async () => {
+                    if (reviving)
+                        return;
+                    reviving = true;
+                    try {
+                        await bringUp();
+                        console.warn('[handoff] 新实例未确认接管，旧实例已复活并重新接管端口');
+                    }
+                    catch (err) {
+                        if (err.code === 'EADDRINUSE') {
+                            // 新实例已绑定端口（确认请求丢失）→ 它已接管，旧实例正常退出。
+                            console.warn('[handoff] 端口已被新实例接管，旧实例退出');
+                            process.exit(0);
+                        }
+                        console.error('[handoff] 旧实例复活失败，退出：', err);
+                        process.exit(1);
+                    }
+                    finally {
+                        reviving = false;
+                    }
+                })();
+            }, HANDOFF_CONFIRM_WINDOW_MS);
+        }
+        // 两阶段交接第二阶段：新实例绑定成功后确认旧实例可退出。
+        // 旧实例（无 handoffPort）跳过；确认失败静默（窗口超时兜底）。
+        if (opts.handoffPort) {
+            const confirmToken = process.env.C0DE_AUTH_TOKEN ?? readAuthTokenFile(resolveDbDir());
+            void confirmHandoff(opts.handoffPort, '127.0.0.1', confirmToken);
+        }
     };
-    const close = async () => {
-        await closeMain();
-        await handoffServer?.close();
+    await bringUp();
+    if (!currentApp)
+        throw new Error('server failed to start: app not built');
+    return {
+        app: currentApp,
+        port,
+        close: async () => {
+            await currentClose?.();
+        },
+        ...(currentAuthToken ? { authToken: currentAuthToken } : {}),
     };
-    // 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 } : {}) };
 }
+// P1-1：buildRegistryFromConfig/syncRegistryFromConfig 实现移入 registry-config.ts，
+// 此处 re-export 保留 server.ts 历史导出兼容（测试/CLI 引用）。
 export { acquireDevDbLock, bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, releaseDevDbLock, resolveAuthToken, resolveDbDir, startServer, syncRegistryFromConfig, };