c0de-agent 1.10.0 → 1.12.0

package/dist/kanban/store.js

@@ -5,6 +5,13 @@ import { DEFAULT_KANBAN_COLUMNS } from '../shared/types/kanban.js';
 const DEFAULT_COLUMN_ID = 'todo';
 /** Position increment — large gap avoids frequent re-indexing on reorder. */
 const POSITION_GAP = 1000;
+/** 列内仍有卡片时禁止删除该列（否则卡片静默不可见）。 */
+class KanbanColumnInUseError extends Error {
+    constructor(columnNames, cardCount) {
+        super(`列 [${columnNames.join(', ')}] 中仍有 ${cardCount} 张卡片，无法删除。` +
+            '请先移动或删除这些卡片。');
+    }
+}
 // ── Row → API mappers ──────────────────────────────────────
 function rowToBoard(row) {
     return {
@@ -140,7 +147,39 @@ function createKanbanStore(handle, projectId) {
             await db.delete(kanbanCards).where(eq(kanbanCards.id, id));
         },
         async updateBoard(patch) {
-            await getOrCreateBoardId();
+            const boardId = await getOrCreateBoardId();
+            // P1-4：删除列前校验该列内是否有卡片；删除标签前把悬空 labelId 从卡片上清掉。
+            if (patch.columns !== undefined) {
+                const cards = await db
+                    .select({ columnId: kanbanCards.columnId })
+                    .from(kanbanCards)
+                    .where(eq(kanbanCards.boardId, boardId));
+                const newColumnIds = new Set(patch.columns.map((c) => c.id));
+                const removedWithCards = new Map();
+                for (const card of cards) {
+                    if (!newColumnIds.has(card.columnId)) {
+                        removedWithCards.set(card.columnId, (removedWithCards.get(card.columnId) ?? 0) + 1);
+                    }
+                }
+                if (removedWithCards.size > 0) {
+                    const total = Array.from(removedWithCards.values()).reduce((a, b) => a + b, 0);
+                    throw new KanbanColumnInUseError(Array.from(removedWithCards.keys()), total);
+                }
+            }
+            if (patch.labels !== undefined) {
+                const labelIds = new Set(patch.labels.map((l) => l.id));
+                const cards = await db
+                    .select({ id: kanbanCards.id, labels: kanbanCards.labels })
+                    .from(kanbanCards)
+                    .where(eq(kanbanCards.boardId, boardId));
+                for (const card of cards) {
+                    const current = (card.labels ?? []);
+                    const kept = current.filter((lid) => labelIds.has(lid));
+                    if (kept.length !== current.length) {
+                        await db.update(kanbanCards).set({ labels: kept }).where(eq(kanbanCards.id, card.id));
+                    }
+                }
+            }
             const [boardRow] = await db
                 .update(kanbanBoards)
                 .set({
@@ -153,6 +192,41 @@ function createKanbanStore(handle, projectId) {
             const row = boardRow;
             return rowToBoard(row);
         },
+        /** 整板替换（导入）：board 配置 + 卡片在单事务内重建；中途失败整体回滚，
+         *  不残留「配置已换、卡片半新半旧」的混合状态。 */
+        async replaceBoard(input) {
+            const boardId = await getOrCreateBoardId();
+            await db.transaction(async (tx) => {
+                await tx.delete(kanbanCards).where(eq(kanbanCards.boardId, boardId));
+                await tx
+                    .update(kanbanBoards)
+                    .set({ columns: input.columns, labels: input.labels, updatedAt: new Date() })
+                    .where(eq(kanbanBoards.id, boardId));
+                if (input.cards.length > 0) {
+                    await tx.insert(kanbanCards).values(input.cards.map((c) => ({
+                        boardId,
+                        title: c.title,
+                        description: c.description ?? null,
+                        columnId: c.columnId,
+                        priority: c.priority,
+                        position: c.position,
+                        labels: c.labels,
+                    })));
+                }
+            });
+            const boardRow = await db
+                .select()
+                .from(kanbanBoards)
+                .where(eq(kanbanBoards.id, boardId))
+                .limit(1);
+            const board = boardRow[0];
+            const cards = await db
+                .select()
+                .from(kanbanCards)
+                .where(eq(kanbanCards.boardId, boardId))
+                .orderBy(asc(kanbanCards.columnId), asc(kanbanCards.position));
+            return { ...rowToBoard(board), cards: cards.map(rowToCard) };
+        },
     };
 }
-export { createKanbanStore };
+export { createKanbanStore, KanbanColumnInUseError };

package/dist/llm/index.d.ts

@@ -8,6 +8,6 @@ export { builtinCapabilities, createRegistry, DEFAULT_MODEL_CAPABILITIES, overri
 export type { Retryable, RetryOptions } from './retry.js';
 export { delay, retryable, withRetry } from './retry.js';
 export type { FallbackChain } from './routing.js';
-export { runWithFallback, shouldFallOver } from './routing.js';
+export { buildFallbackChain, runWithFallback, shouldFallOver } from './routing.js';
 export * from './schema/index.js';
 export { estimateTokens } from './token.js';

package/dist/llm/index.js

@@ -3,6 +3,6 @@ export { buildInternalRequest, chat, chatStream, toInternalMessage, toStreamChun
 export { isContextOverflow, isContextOverflowFailure } from './provider-error.js';
 export { builtinCapabilities, createRegistry, DEFAULT_MODEL_CAPABILITIES, overrideToCapabilities, registerProvider, resolveModelByRole, resolveRoute, setRole, } from './registry.js';
 export { delay, retryable, withRetry } from './retry.js';
-export { runWithFallback, shouldFallOver } from './routing.js';
+export { buildFallbackChain, runWithFallback, shouldFallOver } from './routing.js';
 export * from './schema/index.js';
 export { estimateTokens } from './token.js';

package/dist/llm/provider.js

@@ -135,7 +135,7 @@ const streamTarget = async function* (ctx, request, target, chain) {
         headers: { authorization: `Bearer ${authHeader}`, ...resolved.route.headers() },
         signal: ctx.signal,
         fetchImpl: ctx.fetchImpl,
-    }), { maxRetries: chain.maxRetries, sleep: chain.sleep });
+    }), { maxRetries: chain.maxRetries, sleep: chain.sleep, initialDelayMs: chain.retryDelay });
     let state = initialStepState();
     for await (const frame of sseFraming(stream)) {
         const chunk = parseChunk(resolved.route.id, frame);

package/dist/llm/retry.d.ts

@@ -4,9 +4,10 @@ declare const RETRY_MAX_DELAY_NO_HEADERS = 30000;
 declare const RETRY_MAX_DELAY = 2147483647;
 /**
  * Compute the delay before the next retry attempt (ms).
- * Honors retry-after / retry-after-ms headers when present, else exponential backoff.
+ * Honors retry-after / retry-after-ms headers when present, else exponential backoff
+ * from the given base delay (defaults to RETRY_INITIAL_DELAY).
  */
-declare const delay: (attempt: number, error?: unknown) => number;
+declare const delay: (attempt: number, error?: unknown, initialDelayMs?: number) => number;
 /** A normalized, retryable error descriptor for the session layer. */
 type Retryable = {
     message: string;
@@ -29,6 +30,8 @@ type RetryOptions = {
         delayMs: number;
         error: unknown;
     }) => void;
+    /** Base delay for exponential backoff (default RETRY_INITIAL_DELAY). */
+    initialDelayMs?: number;
 };
 /**
  * Run an async operation with retry. Retries only on retryable LLM errors.

package/dist/llm/retry.js

@@ -17,9 +17,10 @@ const errorHeaders = (error) => {
 const capDelay = (ms) => Math.min(ms, RETRY_MAX_DELAY);
 /**
  * Compute the delay before the next retry attempt (ms).
- * Honors retry-after / retry-after-ms headers when present, else exponential backoff.
+ * Honors retry-after / retry-after-ms headers when present, else exponential backoff
+ * from the given base delay (defaults to RETRY_INITIAL_DELAY).
  */
-const delay = (attempt, error) => {
+const delay = (attempt, error, initialDelayMs = RETRY_INITIAL_DELAY) => {
     const headers = errorHeaders(error);
     if (headers) {
         const retryAfterMs = headers['retry-after-ms'];
@@ -37,9 +38,9 @@ const delay = (attempt, error) => {
             if (!Number.isNaN(parsed) && parsed > 0)
                 return capDelay(Math.ceil(parsed));
         }
-        return capDelay(RETRY_INITIAL_DELAY * RETRY_BACKOFF_FACTOR ** (attempt - 1));
+        return capDelay(initialDelayMs * RETRY_BACKOFF_FACTOR ** (attempt - 1));
     }
-    return capDelay(Math.min(RETRY_INITIAL_DELAY * RETRY_BACKOFF_FACTOR ** (attempt - 1), RETRY_MAX_DELAY_NO_HEADERS));
+    return capDelay(Math.min(initialDelayMs * RETRY_BACKOFF_FACTOR ** (attempt - 1), RETRY_MAX_DELAY_NO_HEADERS));
 };
 /**
  * Decide whether a thrown error is retryable. Returns undefined when not retryable
@@ -74,7 +75,7 @@ const withRetry = async (fn, options) => {
             const fallbackReason = isLLMError(error)
                 ? error.reason
                 : { _tag: 'InvalidRequest', message: '' };
-            const delayMs = Math.min(reasonRetryAfterMs(fallbackReason) ?? delay(attempt, error), canRetry.policy.maxDelay);
+            const delayMs = Math.min(reasonRetryAfterMs(fallbackReason) ?? delay(attempt, error, options.initialDelayMs), canRetry.policy.maxDelay);
             options.onRetry?.({ attempt, delayMs, error });
             await sleep(delayMs);
         }

package/dist/llm/routing.d.ts

@@ -32,5 +32,28 @@ declare const runWithFallback: <T>(registry: Registry, chain: FallbackChain, run
  * errors propagate without trying fallbacks.
  */
 declare const shouldFallOver: (error: unknown) => boolean;
+/** 回退目标所需的最小 provider 信息。 */
+type FallbackSourceProvider = {
+    name?: string;
+    _tag?: string;
+    /** 声明了模型清单的 provider 只对清单内的模型回退；未声明视为不支持（保守）。 */
+    models?: Record<string, unknown>;
+};
+/**
+ * 从 config.fallback 构建回退链（主 chat 循环/压缩/标题等 LLM 调用的接线点）。
+ * - enabled=false → undefined（保持内置默认：3 次重试、无跨 provider 回退）。
+ * - enabled=true → 按配置 maxRetries/retryDelay 重试，并对「声明了同一模型」的
+ *   其他 provider 依次回退。无合格回退目标时 fallbacks 为空——重试参数仍然生效。
+ * 回退只接受声明了该模型的 provider：对未声明的 provider 盲目回退会在其 API 处
+ * 得到 InvalidRequest 并中断整条链（shouldFallOver 不放过非回退错误）。
+ */
+declare function buildFallbackChain(config: {
+    providers: FallbackSourceProvider[];
+    fallback: {
+        enabled: boolean;
+        maxRetries: number;
+        retryDelay: number;
+    };
+}, provider: string, model: string): FallbackChain | undefined;
 export type { FallbackChain };
-export { runWithFallback, shouldFallOver };
+export { buildFallbackChain, runWithFallback, shouldFallOver };

package/dist/llm/routing.js

@@ -20,6 +20,7 @@ const runWithFallback = async (registry, chain, run) => {
             const result = await withRetry(() => run(target.provider, target.model), {
                 maxRetries: chain.maxRetries,
                 sleep: chain.sleep,
+                initialDelayMs: chain.retryDelay,
             });
             return { result, provider: target.provider, model: target.model };
         }
@@ -50,4 +51,31 @@ const shouldFallOver = (error) => {
         return true;
     return false;
 };
-export { runWithFallback, shouldFallOver };
+/**
+ * 从 config.fallback 构建回退链（主 chat 循环/压缩/标题等 LLM 调用的接线点）。
+ * - enabled=false → undefined（保持内置默认：3 次重试、无跨 provider 回退）。
+ * - enabled=true → 按配置 maxRetries/retryDelay 重试，并对「声明了同一模型」的
+ *   其他 provider 依次回退。无合格回退目标时 fallbacks 为空——重试参数仍然生效。
+ * 回退只接受声明了该模型的 provider：对未声明的 provider 盲目回退会在其 API 处
+ * 得到 InvalidRequest 并中断整条链（shouldFallOver 不放过非回退错误）。
+ */
+function buildFallbackChain(config, provider, model) {
+    const fb = config.fallback;
+    if (!fb.enabled)
+        return undefined;
+    const fallbacks = config.providers
+        .filter((p) => {
+        const name = p.name || p._tag;
+        if (!name || name === provider)
+            return false;
+        return p.models !== undefined && model in p.models;
+    })
+        .map((p) => ({ provider: (p.name || p._tag), model }));
+    return {
+        primary: { provider, model },
+        fallbacks,
+        maxRetries: fb.maxRetries,
+        retryDelay: fb.retryDelay,
+    };
+}
+export { buildFallbackChain, runWithFallback, shouldFallOver };

package/dist/project/index.d.ts

@@ -1,4 +1,4 @@
 export type { Project } from './project.js';
-export { fromDirectory, getByDirectory, getProject, listProjects, updateProjectName, } from './project.js';
+export { fromDirectory, getByDirectory, getProject, listProjects, relocateProject, updateProjectName, } from './project.js';
 export type { ResolvedProject } from './resolve.js';
 export { resolveProject } from './resolve.js';

package/dist/project/index.js

@@ -1,2 +1,2 @@
-export { fromDirectory, getByDirectory, getProject, listProjects, updateProjectName, } from './project.js';
+export { fromDirectory, getByDirectory, getProject, listProjects, relocateProject, updateProjectName, } from './project.js';
 export { resolveProject } from './resolve.js';

package/dist/project/project.d.ts

@@ -21,3 +21,17 @@ export declare function listProjects(handle: DB): Promise<Project[]>;
 export declare function getProject(handle: DB, id: string): Promise<Project | null>;
 export declare function getByDirectory(handle: DB, directory: string): Promise<Project | null>;
 export declare function updateProjectName(handle: DB, id: string, name: string): Promise<Project | null>;
+/**
+ * 项目重新定位（A1：目录被移动/重命名后的恢复通道）。
+ *
+ * 项目身份 = sha256(worktree)，目录移动后旧项目记录的 worktree 失效且不可改 id。
+ * 此前唯一恢复路径是「删除项目」：会话打散进孤儿回收站逐条恢复，看板永久丢失。
+ * 本函数在单事务内把项目整体迁移到新目录身份（新 id），保住看板与会话归属：
+ *   1. 以新目录解析出的 id upsert 项目行（沿用旧名称）；
+ *   2. 会话 projectId/worktreePath 迁移到新身份；
+ *   3. 看板 projectId 迁移（目标为新身份，唯一约束无冲突）；
+ *   4. 删除旧项目行。
+ * 同一 id（如 git 仓库根未变、仅路径符号变化）→ 仅更新 worktree，不换身份。
+ * 目标目录已注册为另一项目时抛 TARGET_OCCUPIED（调用方转 409），绝不静默合并。
+ */
+export declare function relocateProject(handle: DB, id: string, directory: string): Promise<Project>;

package/dist/project/project.js

@@ -1,6 +1,6 @@
 import { basename } from 'node:path';
 import { eq } from 'drizzle-orm';
-import { projects, sessions } from '../db/schema.js';
+import { kanbanBoards, projects, sessions } from '../db/schema.js';
 import { resolveProject } from './resolve.js';
 function rowToProject(row) {
     return {
@@ -85,3 +85,79 @@ export async function updateProjectName(handle, id, name) {
         .returning();
     return row ? rowToProject(row) : null;
 }
+/**
+ * 项目重新定位（A1：目录被移动/重命名后的恢复通道）。
+ *
+ * 项目身份 = sha256(worktree)，目录移动后旧项目记录的 worktree 失效且不可改 id。
+ * 此前唯一恢复路径是「删除项目」：会话打散进孤儿回收站逐条恢复，看板永久丢失。
+ * 本函数在单事务内把项目整体迁移到新目录身份（新 id），保住看板与会话归属：
+ *   1. 以新目录解析出的 id upsert 项目行（沿用旧名称）；
+ *   2. 会话 projectId/worktreePath 迁移到新身份；
+ *   3. 看板 projectId 迁移（目标为新身份，唯一约束无冲突）；
+ *   4. 删除旧项目行。
+ * 同一 id（如 git 仓库根未变、仅路径符号变化）→ 仅更新 worktree，不换身份。
+ * 目标目录已注册为另一项目时抛 TARGET_OCCUPIED（调用方转 409），绝不静默合并。
+ */
+export async function relocateProject(handle, id, directory) {
+    const current = await getProject(handle, id);
+    if (!current)
+        throw new Error('PROJECT_NOT_FOUND');
+    const resolved = resolveProject(directory);
+    if (resolved.id === id) {
+        // 身份不变：仅刷新 worktree 与 git 元数据；会话 worktreePath 同步。
+        await handle.db.transaction(async (tx) => {
+            await tx
+                .update(projects)
+                .set({
+                worktree: resolved.worktree,
+                vcs: resolved.vcs,
+                gitRemote: resolved.gitRemote,
+                updatedAt: new Date(),
+            })
+                .where(eq(projects.id, id));
+            await tx
+                .update(sessions)
+                .set({ worktreePath: resolved.worktree })
+                .where(eq(sessions.projectId, id));
+        });
+    }
+    else {
+        const occupied = await getProject(handle, resolved.id);
+        if (occupied) {
+            throw new Error(`TARGET_OCCUPIED: 目标目录已注册为项目「${occupied.name ?? '未命名项目'}」`);
+        }
+        await handle.db.transaction(async (tx) => {
+            await tx
+                .insert(projects)
+                .values({
+                id: resolved.id,
+                worktree: resolved.worktree,
+                vcs: resolved.vcs,
+                name: current.name ?? basename(resolved.worktree),
+                gitRemote: resolved.gitRemote,
+            })
+                .onConflictDoUpdate({
+                target: projects.id,
+                set: {
+                    worktree: resolved.worktree,
+                    vcs: resolved.vcs,
+                    gitRemote: resolved.gitRemote,
+                    updatedAt: new Date(),
+                },
+            });
+            await tx
+                .update(sessions)
+                .set({ projectId: resolved.id, worktreePath: resolved.worktree })
+                .where(eq(sessions.projectId, id));
+            await tx
+                .update(kanbanBoards)
+                .set({ projectId: resolved.id })
+                .where(eq(kanbanBoards.projectId, id));
+            await tx.delete(projects).where(eq(projects.id, id));
+        });
+    }
+    const result = await getProject(handle, resolved.id);
+    if (!result)
+        throw new Error(`Relocate failed for ${directory}`);
+    return result;
+}

package/dist/server/agent-manager.d.ts

@@ -36,11 +36,25 @@ type AgentManager = {
     abort(sessionId: string): boolean;
     pause(sessionId: string): boolean;
     resume(sessionId: string): boolean;
+    /** 暂停全部活跃 run 并等待到达安全点；超时强制中止（热更新前调用）。
+     *  返回 pausedIds：成功暂停的会话 id 列表——调用方在后续步骤（spawn 等）
+     *  失败时必须对其逐个 resume 回滚，避免更新失败连带冻结用户对话。 */
+    pauseAll(timeoutMs?: number): Promise<{
+        paused: number;
+        forcedAbort: number;
+        pausedIds: string[];
+    }>;
     steer(sessionId: string, message: string): boolean;
     /** 查询某 session 的所有子 agent run（恢复/展示用）。 */
     children(parentSessionId: string): ActiveRun[];
     /** 查询所有后台任务（jobId 非空的 run）。 */
     backgroundJobs(): ActiveRun[];
+    /** 列出全部活跃 run（含子 agent）——热更新影响面展示用。 */
+    listActive(): Array<{
+        sessionId: string;
+        agentType?: string;
+        parentSessionId?: string;
+    }>;
     /** 中止所有活跃 run 并清空（dev 热重载重建前调用）。 */
     dispose(): void;
 };

package/dist/server/agent-manager.js

@@ -54,6 +54,37 @@ function createAgentManager() {
             resumeAgent(run.state);
             return true;
         },
+        /**
+         * 请求暂停所有活跃 run，等待其到达安全暂停点（当前原子操作完成后）。
+         * 超时后对仍未暂停的 run 强制 abort（热更新不能无限等待）。
+         * 返回 { paused: 已暂停数, forcedAbort: 超时中止数 }。
+         */
+        async pauseAll(timeoutMs = 30_000) {
+            const active = Array.from(runs.values())
+                .map((slot) => slotRun(slot))
+                .filter((r) => r !== undefined && r.state.status._tag === 'running');
+            for (const run of active) {
+                pauseAgent(run.state);
+            }
+            const deadline = Date.now() + timeoutMs;
+            while (Date.now() < deadline) {
+                const stillRunning = active.filter((r) => r.state.status._tag === 'running');
+                if (stillRunning.length === 0)
+                    break;
+                await new Promise((res) => setTimeout(res, 100));
+            }
+            let forcedAbort = 0;
+            for (const run of active) {
+                if (run.state.status._tag === 'running') {
+                    abortAgent(run.state);
+                    forcedAbort += 1;
+                }
+            }
+            const pausedIds = active
+                .filter((r) => r.state.status._tag === 'paused')
+                .map((r) => r.sessionId);
+            return { paused: active.length - forcedAbort, forcedAbort, pausedIds };
+        },
         steer(sessionId, message) {
             const run = slotRun(runs.get(sessionId));
             if (!run)
@@ -71,6 +102,16 @@ function createAgentManager() {
                 .map((slot) => slotRun(slot))
                 .filter((r) => r?.jobId !== undefined);
         },
+        listActive() {
+            return Array.from(runs.values())
+                .map((slot) => slotRun(slot))
+                .filter((r) => r !== undefined)
+                .map((r) => ({
+                sessionId: r.sessionId,
+                agentType: r.agentType,
+                parentSessionId: r.parentSessionId,
+            }));
+        },
         dispose() {
             // dev 热重载重建前调用：中止所有活跃 run（loop 在 turn/流边界检测 signal
             // → unwind → 调用方 finally 持久化 + unregister），然后清空 Map。

package/dist/server/app.js

@@ -7,6 +7,7 @@ import { createAuthMiddleware } from './middleware/auth.js';
 import { createCORSMiddleware } from './middleware/cors.js';
 import { errorHandler } from './middleware/error.js';
 import { createAgentRoute } from './routes/agent.js';
+import { createAuthRoute } from './routes/auth.js';
 import { createCatalogRoute } from './routes/catalog.js';
 import { createChatRoute } from './routes/chat.js';
 import { createCommandsRoute } from './routes/commands.js';
@@ -32,10 +33,19 @@ function createApp(ctx) {
     // spec §24.2：仅允许本地/可信 origin 跨域读，拒绝外部网页。
     app.use('*', createCORSMiddleware({ allowedOrigins: ctx.config.security.allowedOrigins }));
     // spec §24.2：Bearer token 认证（配置了 token 时生效；/api/health 探活放行）。
-    // token 来源：用户配置 security.token，或启动时自动生成（ctx.authToken）。
-    app.use('/api/*', createAuthMiddleware(ctx.authToken));
+    // P2-16：authManager 存在时按设备 token 校验；认证/配对引导端点公开。
+    app.use('/api/*', createAuthMiddleware(ctx.authToken, {
+        publicPaths: [
+            '/api/health',
+            '/api/auth/register',
+            '/api/auth/pairing/request',
+            '/api/auth/pairing/status',
+        ],
+        ...(ctx.authManager ? { verify: (t) => ctx.authManager?.verify(t) ?? false } : {}),
+    }));
     // 路由
     app.route('/api/health', createHealthRoute());
+    app.route('/api/auth', createAuthRoute(ctx));
     app.route('/api/agents', createAgentRoute(ctx));
     app.route('/api/sessions', createSessionRoute(ctx));
     app.route('/api/projects', createProjectRoute(ctx));

package/dist/server/auth-manager.d.ts

@@ -0,0 +1,85 @@
+type DeviceRecord = {
+    id: string;
+    name: string;
+    tokenHash: string;
+    createdAt: number;
+};
+type PendingPairing = {
+    pairingId: string;
+    deviceName: string;
+    code: string;
+    createdAt: number;
+    status: 'pending' | 'approved' | 'denied';
+    /** 请求来源（尽力而为：x-forwarded-for 首跳，本地回环时为 local）。仅展示 + 软限流，不作身份断言。 */
+    source: string;
+    deviceToken?: string;
+};
+type AuthManagerOptions = {
+    dataDir: string;
+    /** 显式配置的静态 token（security.token / C0DE_AUTH_TOKEN）；非空 → 静态模式。 */
+    staticToken?: string;
+    /** bootstrap token 文件路径（默认 dataDir/auth-token）。 */
+    tokenFilePath?: string;
+    /** 配对码有效期（ms），默认 10 分钟。 */
+    pairingTtlMs?: number;
+    /** 首设备 bootstrap TTL（ms）：>0 时，bootstrap 超过此时长即拒绝首设备注册
+     *  （需重启 serve 重新生成）。0=不限制。用于缩短「URL 泄漏后被抢先注册」的窗口。 */
+    firstDeviceTtlMs?: number;
+    now?: () => number;
+};
+export type AuthManager = {
+    /** 当前 bootstrap token（静态模式下即 staticToken）。 */
+    readonly bootstrap: string | undefined;
+    /** API/WS 请求校验：仅设备 token 有效（静态模式下 staticToken 有效）。 */
+    verify(token: string | undefined): boolean;
+    /** handoff 端点校验：设备 token + 当前 bootstrap（历史 bootstrap 不接受，
+     *  否则已泄漏的旧 URL token 仍可借 handoff 强杀本地服务）。 */
+    verifyHandoff(token: string | undefined): boolean;
+    /** 首次设备注册：校验 bootstrap 后换发设备 token 并轮换 bootstrap。
+     *  无设备时首个凭 bootstrap 的请求即视为首设备（免审批），后续请求需配对审批。
+     *  返回新设备 token；bootstrap 已失效/已注册过 → 返回 null。 */
+    registerFirstDevice(bootstrapToken: string, deviceName: string): Promise<string | null>;
+    /** 发起配对请求（未认证）：返回 { pairingId, code }；静态模式/未启用返回 null。
+     *  source 为请求来源（IP 等，尽力而为），用于审批展示与按来源限流。 */
+    requestPairing(deviceName: string, source?: string): {
+        pairingId: string;
+        code: string;
+    } | null;
+    /** 查询配对状态（未认证）：pending / approved(含 token) / denied / not_found。 */
+    pairingStatus(pairingId: string): {
+        status: 'pending';
+    } | {
+        status: 'approved';
+        deviceToken: string;
+    } | {
+        status: 'denied';
+    } | {
+        status: 'not_found';
+    };
+    /** 列出待审批配对（需已认证设备调用）。 */
+    listPairings(): Array<{
+        pairingId: string;
+        deviceName: string;
+        code: string;
+        createdAt: number;
+        source: string;
+    }>;
+    /** 审批配对（需已认证设备调用）：通过后为请求设备签发 token。 */
+    approvePairing(pairingId: string): boolean;
+    /** 拒绝配对。 */
+    denyPairing(pairingId: string): boolean;
+    /** 列出已授权设备（id/name/createdAt）。 */
+    listDevices(): Array<{
+        id: string;
+        name: string;
+        createdAt: number;
+    }>;
+    /** 撤销某设备：立即从内存移除并落盘；返回是否成功。 */
+    revokeDevice(id: string): boolean;
+    /** 持久化设备注册表到磁盘（fire-and-forget 调用）。 */
+    persist(): void;
+    /** 关闭 devices.json 热重载 watcher（server dispose 时调用）。 */
+    dispose(): void;
+};
+export declare function createAuthManager(opts: AuthManagerOptions): AuthManager;
+export type { DeviceRecord, PendingPairing };