c0de-agent 1.11.0 → 1.13.0

package/dist/server/server.d.ts

@@ -1,11 +1,14 @@
 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;
+    /** 绑定地址（默认 127.0.0.1，仅本机可达）。显式配置非回环地址（0.0.0.0/局域网 IP）
+     *  时服务对网络可达，安全仅靠 token + allowedOrigins 保证——serve 命令会打印醒目警告。 */
+    host?: string;
     cwd?: string;
     /** 注入已有 DB（测试用）。 */
     db?: DB;
@@ -31,15 +34,9 @@ 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;
+/** serve 默认端口：避开 node 生态常用端口（3000/4000/5173/8000/8080…），
+ * 降低与其他本地服务撞端口的概率。显式 --port 始终优先。 */
+export declare const DEFAULT_SERVE_PORT = 7310;
 /** 解析 PGLite 持久化数据目录：优先 C0DE_DB_DIR，否则全局数据根下 pglite 子目录。
  *
  * 历史上数据库放在 <cwd>/.c0de/pglite（项目级），但项目 DB schema 通过 projectId
@@ -50,8 +47,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;
 /**
@@ -79,10 +77,15 @@ declare function buildServerContext(db: DB, opts?: StartServerOptions): Promise<
 declare function acquireDevDbLock(dataDir: string): void;
 /** Release the dev DB lock (best-effort, stale-detection covers missed calls). */
 declare function releaseDevDbLock(dataDir: string): void;
+/** 读取运行中 serve 的端口（CLI 锁冲突引导用）。文件缺失/损坏 → null。 */
+declare function readServeInfo(dataDir: string): {
+    pid: number;
+    port: number;
+} | null;
 /** dev 专用：创建 + migrate PGLite，跨热重载复用（单写者，只建一次）。 */
 declare function createDevDb(cwd: string): Promise<DB>;
 /** 初始化 DB + 配置 + 注册表，返回 ServerContext + 清理函数（dev 与独立后端共用）。 */
 declare function bootstrapServerContext(opts?: StartServerOptions): Promise<BootstrappedServer>;
 declare function startServer(opts?: StartServerOptions): Promise<RunningServer>;
 export type { BootstrappedServer, RunningServer, StartServerOptions };
-export { acquireDevDbLock, bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, releaseDevDbLock, resolveAuthToken, resolveDbDir, startServer, syncRegistryFromConfig, };
+export { acquireDevDbLock, bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, readServeInfo, releaseDevDbLock, resolveAuthToken, resolveDbDir, startServer, syncRegistryFromConfig, };

package/dist/server/server.js

@@ -7,59 +7,28 @@ import { dirname, join } from 'node:path';
 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 { loadConfig, loadConfigScopes } from '../core/config.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 { purgeDeletedKanbanBoards } from '../kanban/index.js';
 import { initPlugins } from '../plugins/index.js';
-import { purgeDeletedSessions } from '../session/session.js';
+import { getByDirectory } from '../project/index.js';
+import { projectTrustCurrent } from '../project/trust.js';
+import { markDeadBackgroundJobs } from '../session/jobs.js';
+import { purgeDeletedSessions, purgeEmptySessions, purgeTemporarySessions, TRASH_PURGE_GRACE_MS, TRASH_RETENTION_MS, } from '../session/session.js';
+import { backfillUsageEventsOnce } from '../session/usage.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);
-        }
-    });
-}
+/** serve 默认端口：避开 node 生态常用端口（3000/4000/5173/8000/8080…），
+ * 降低与其他本地服务撞端口的概率。显式 --port 始终优先。 */
+export const DEFAULT_SERVE_PORT = 7310;
 /** 全局数据根目录：XDG_DATA_HOME 优先，否则 ~/.local/share/c0de。
  * 与 opencode (~/.local/share/opencode/)、oh-my-pi (~/.omp/agent/) 同约定——
  * 数据库等运行时数据放全局，项目 .c0de/ 只留配置和扩展。 */
@@ -84,8 +53,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)
@@ -104,13 +74,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 {
@@ -122,6 +95,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 {
@@ -170,23 +156,51 @@ function migrateLegacyPglite(cwd, targetDir) {
  */
 async function buildServerContext(db, opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
+    // P1：快照携带的终端元信息——新实例原位重建 shell（同 id）。提前解析出来，
+    // ptyManager 创建后立即恢复；旧快照无 terminals 字段时为空。
+    let restoredTerminals = [];
     if (opts.restoreFrom) {
         const snapshot = JSON.parse(readFileSync(opts.restoreFrom, 'utf8'));
         await restoreSessions(db, snapshot);
+        restoredTerminals = Array.isArray(snapshot.terminals)
+            ? snapshot.terminals.filter((t) => !!t &&
+                typeof t.id === 'string' &&
+                typeof t.shell === 'string' &&
+                typeof t.cwd === 'string')
+            : [];
     }
     const config = await loadConfig(cwd);
     const toolRegistry = createDefaultRegistry(config);
     const llmRegistry = buildRegistryFromConfig(config);
     const urlRegistry = createDefaultURLRegistry();
+    // P0-2：项目插件只在项目被显式信任后加载（fail-closed）——克隆仓库自带的
+    // .c0de/plugins 不会在首次 serve 时静默执行；c0de trust / Web 信任后重启生效。
+    // 未注册项目（首次 serve、尚无项目记录）视为未信任。
+    // P0（代码面）：已信任但指纹漂移（git pull 改了插件代码/MCP 参数/风险键）→
+    // 同样不加载——与聊天门禁同口径，杜绝「先重启、后门禁」窗口里执行漂移代码。
+    let projectTrusted = false;
+    try {
+        const p = await getByDirectory(db, cwd);
+        if (p?.trustedAt != null) {
+            projectTrusted = projectTrustCurrent(loadConfigScopes(cwd).project, p.trustedAt, p.riskFingerprint, cwd);
+        }
+    }
+    catch {
+        // 信任状态查询失败 → 保持未信任（宁可少加载插件）
+    }
     const { pluginRegistry, hookRunner } = await initPlugins({
         cwd,
         config,
         toolRegistry,
         llmRegistry,
+        projectTrusted,
     });
     // 工作流注册表：三级发现（builtin → global → project），eager 初始化。
     // 此前是惰性 getter 只注册 builtin，导致项目级 .c0de/workflows/*.js 永远不可见。
-    const workflowRegistry = await createAndPopulateRegistry(cwd);
+    // P0 信任边界：项目级工作流与 .c0de/plugins 同为仓库自带任意代码执行面，
+    // 仅在 serve 目录项目当前可信任（projectTrusted）时 dynamic import——与上方
+    // 插件加载同口径，杜绝「克隆即执行」。
+    const workflowRegistry = await createAndPopulateRegistry(cwd, { projectTrusted });
     const dataDir = resolveDbDir();
     // 先解析/生成 bootstrap token（落盘），再创建 authManager 读取——
     // 首启时文件由 resolveAuthToken 生成，顺序颠倒会导致 bootstrap 读到空值。
@@ -196,7 +210,38 @@ async function buildServerContext(db, opts = {}) {
         ...(config.security.token && config.security.token.length > 0
             ? { staticToken: config.security.token }
             : {}),
+        ...(config.security.firstDeviceTtlMs !== undefined
+            ? { firstDeviceTtlMs: config.security.firstDeviceTtlMs }
+            : {}),
     });
+    const ptyManager = new PTYManager();
+    // P1：热更新恢复——按快照元信息原位重建终端 shell（同 id，前端布局无感重连）。
+    // 进程内状态（运行中的 dev server 等）无法续命，但用户在熟悉的布局里得到新 shell，
+    // 且 cwd/title/shell 保持一致。恢复失败（极端环境）不阻塞启动。
+    for (const t of restoredTerminals) {
+        try {
+            ptyManager.create({
+                id: t.id,
+                shell: t.shell,
+                cwd: t.cwd,
+                title: t.title || undefined,
+                ...(t.projectId ? { projectId: t.projectId } : {}),
+            });
+            // P3-7：用户勾选的「更新后自动重启」——重建 shell 后把前台命令写入 stdin 重跑
+            // （如 `npm run dev`）。写入由 PTY 缓冲，shell 初始化完成后即执行；失败不阻塞启动。
+            if (typeof t.command === 'string' && t.command.length > 0) {
+                try {
+                    ptyManager.write(t.id, `${t.command}\n`);
+                }
+                catch (err) {
+                    console.warn(`[server] 终端命令重跑失败（${t.id}）：${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        catch (err) {
+            console.warn(`[server] 终端恢复失败（${t.id}）：${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     const ctx = {
         db,
         config,
@@ -206,9 +251,21 @@ async function buildServerContext(db, opts = {}) {
         hookRunner,
         pluginRegistry,
         agentManager: createAgentManager(),
-        permissionStore: createPermissionStore(),
+        // P3：权限双层超时可配置（config.permission.timeoutMs/expireGraceMs）；
+        // 缺省回退 store 内置默认（5 分钟 + 25 分钟）。
+        permissionStore: createPermissionStore({
+            ...(config.permission.timeoutMs !== undefined && config.permission.timeoutMs > 0
+                ? { timeoutMs: config.permission.timeoutMs }
+                : {}),
+            ...(config.permission.expireGraceMs !== undefined && config.permission.expireGraceMs > 0
+                ? { expireGraceMs: config.permission.expireGraceMs }
+                : {}),
+        }),
         permissionMode: config.permission.defaultMode,
         sessionPermissionModes: new Map(),
+        sessionAlwaysAllow: new Map(),
+        workflowBusyBySession: new Map(),
+        workflowBusyByScope: new Map(),
         authToken: resolvedToken,
         authManager: config.security.authEnabled === false ? undefined : authManager,
         // Agent 注册表：内置 4 个默认 agent；项目/用户自定义 agent 可在启动后补充加载。
@@ -226,7 +283,7 @@ async function buildServerContext(db, opts = {}) {
             initialDelayMs: config.update.initialDelayMs,
         }),
         cwd,
-        ptyManager: new PTYManager(),
+        ptyManager,
     };
     // handoff server 不在此创建：它需要持有主 HTTP server 引用以触发完整关停，
     // 由 startServer 在 serve() 之后创建（dev 模式走 vite，不创建）。
@@ -302,6 +359,49 @@ function releaseDevDbLock(dataDir) {
         /* best-effort */
     }
 }
+const SERVE_INFO_FILE = 'serve-info.json';
+/** serve 运行信息落盘（port + pid）：CLI 在锁冲突（serve 占用持久库）时读取，
+ *  引导用户直接打开 Web 界面继续对话，而不是给出无从下手的报错。不落 token。 */
+function writeServeInfo(dataDir, port) {
+    try {
+        if (!existsSync(dataDir))
+            mkdirSync(dataDir, { recursive: true });
+        writeFileSync(join(dataDir, SERVE_INFO_FILE), JSON.stringify({ pid: process.pid, port, startedAt: Date.now() }), 'utf8');
+    }
+    catch {
+        /* best-effort：仅影响 CLI 引导文案，不影响服务本身 */
+    }
+}
+/** 关闭时清除本进程写入的 serve 信息（pid 匹配才删，防止误删热更新新实例的信息）。 */
+function removeServeInfo(dataDir) {
+    try {
+        const path = join(dataDir, SERVE_INFO_FILE);
+        if (!existsSync(path))
+            return;
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (parsed.pid === process.pid)
+            unlinkSync(path);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** 读取运行中 serve 的端口（CLI 锁冲突引导用）。文件缺失/损坏 → null。 */
+function readServeInfo(dataDir) {
+    try {
+        const path = join(dataDir, SERVE_INFO_FILE);
+        if (!existsSync(path))
+            return null;
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (typeof parsed.pid === 'number' && typeof parsed.port === 'number') {
+            return { pid: parsed.pid, port: parsed.port };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 /** dev 专用：创建 + migrate PGLite，跨热重载复用（单写者，只建一次）。 */
 async function createDevDb(cwd) {
     const dataDir = resolveDbDir();
@@ -346,13 +446,60 @@ async function bootstrapServerContext(opts = {}) {
         db = await createDevDb(cwd);
     }
     const { ctx, dispose } = await buildServerContext(db, opts);
-    // 回收站清理：启动时清一次 + 每 24h 清一次（软删除保留 30 天）。
-    // fire-and-forget：清理失败不阻塞服务启动。
-    void purgeDeletedSessions(db).catch(() => { });
+    // P2 成本账本 backfill：升级后首次启动把遗留 segments 补齐进 usage_events
+    // （幂等，callId 唯一约束去重；app_meta 标记保证只执行一次——导入会话的
+    // segments 已剥离 call id，不产生账本行）。fire-and-forget。
+    void backfillUsageEventsOnce(db)
+        .then((added) => {
+        if (added > 0)
+            console.log(`[server] 成本账本补齐：新增 ${added} 条历史调用记录`);
+    })
+        .catch((err) => {
+        console.warn(`[server] 成本账本补齐失败：${err instanceof Error ? err.message : String(err)}`);
+    });
+    // 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(() => { });
+        // P2-5：回收站看板两阶段清理（与会话回收站同策略：到期先标记宽限，期满再物理清除，
+        // 杜绝「到期即静默清空」）。
+        void purgeDeletedKanbanBoards(db, TRASH_RETENTION_MS, TRASH_PURGE_GRACE_MS)
+            .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} 个超过宽限期的看板`);
+            }
+        })
+            .catch(() => { });
+    };
+    runTrashPurge();
     const purgeTimer = setInterval(() => {
-        void purgeDeletedSessions(db).catch(() => { });
+        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(() => {
@@ -367,8 +514,15 @@ async function bootstrapServerContext(opts = {}) {
             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());
+            }
         },
     };
 }
@@ -410,24 +564,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 });
+/**
+ * 两阶段 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$/);
@@ -469,35 +614,147 @@ 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 ?? DEFAULT_SERVE_PORT;
+    // 默认仅绑定回环地址（安全默认：本地工具不应默认暴露局域网/公网）。
+    // 需要容器/远程访问时显式 --host 0.0.0.0（serve 命令会打印非回环警告）。
+    const host = opts.host ?? '127.0.0.1';
+    // 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;
+        }
     };
-    const close = async () => {
-        await closeMain();
-        await handoffServer?.close();
+    /**
+     * 组装完整服务栈（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, hostname: host });
+        ctx.port = port;
+        ctx.host = host;
+        writeServeInfo(resolveDbDir(), 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();
+            removeServeInfo(resolveDbDir());
+            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;
+            // P0 修复：确认窗口必须在「收到 POST /handoff（交接开始）」时才启动，
+            // 而非 bringUp 时无条件启动——否则任何运行超过 HANDOFF_CONFIRM_WINDOW_MS
+            // 的普通实例都会在窗口超时后误判「新实例未确认」，重新 bringUp 时第二
+            // listen 触发 EADDRINUSE（unhandled 'error'）崩溃。窗口从交接实际发生起算。
+            const armConfirmWindow = () => {
+                clearConfirmTimer();
+                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);
+            };
+            handoffServer = await createHandoff(async () => {
+                await closeMain();
+                armConfirmWindow();
+            }, {
+                // 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 };
+        }
+        // 两阶段交接第二阶段：新实例绑定成功后确认旧实例可退出。
+        // 旧实例（无 handoffPort）跳过；确认失败静默（窗口超时兜底）。
+        if (opts.handoffPort) {
+            const confirmToken = process.env.C0DE_AUTH_TOKEN ?? readAuthTokenFile(resolveDbDir());
+            void confirmHandoff(opts.handoffPort, '127.0.0.1', confirmToken);
+        }
+    };
+    await bringUp();
+    if (!currentApp)
+        throw new Error('server failed to start: app not built');
+    return {
+        app: currentApp,
+        port,
+        close: async () => {
+            await currentClose?.();
+        },
+        // P：仅「首设备待注册」时回传 bootstrap 供 serve 命令拼 ?token= 注册 URL。
+        // 已有已注册设备时 auth-token 文件里是注册后被轮换的旧值——带进 URL 会让新浏览器
+        // 误点「注册链接」却得到 BOOTSTRAP_CONSUMED 引导配对（横幅文案误导）。此时不携带，
+        // serve 打印无 token 的 URL，新浏览器自然走配对流程。
+        ...(currentAuthToken && !hasRegisteredDevices(resolveDbDir())
+            ? { 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, {
-            // P2-16：token 轮换后新旧实例 bootstrap 可能不同，用 verifyHandoff 接受
-            // 当前/历史 bootstrap 与设备 token；无 authManager 回退字符串比较。
-            ...(ctx.authManager
-                ? { verify: (t) => ctx.authManager?.verifyHandoff(t) ?? false }
-                : { expectedToken: ctx.authToken }),
-            exitAfterResponse: true,
-        });
-        ctx.handoff = { port: handoffServer.port, server: handoffServer };
-    }
-    return { app, port, close, ...(ctx.authToken ? { authToken: ctx.authToken } : {}) };
 }
-export { acquireDevDbLock, bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, releaseDevDbLock, resolveAuthToken, resolveDbDir, startServer, syncRegistryFromConfig, };
+// P1-1：buildRegistryFromConfig/syncRegistryFromConfig 实现移入 registry-config.ts，
+// 此处 re-export 保留 server.ts 历史导出兼容（测试/CLI 引用）。
+export { acquireDevDbLock, bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, readServeInfo, releaseDevDbLock, resolveAuthToken, resolveDbDir, startServer, syncRegistryFromConfig, };