c0de-agent 1.9.0 → 1.11.0

package/dist/core/slash.js

@@ -29,13 +29,12 @@ const helpCommand = {
     execute: async () => {
         const lines = [
             'Available commands:',
-            '  /compact        Manually trigger context compaction',
-            '  /model <name>   Switch the current session model',
-            '  /clear          Clear session messages',
-            '  /help           Show this help',
-            '  /fork [index]   Fork session from a message',
-            '  /config [k][v]  View or set configuration',
-            '  /workflow       Manage and run workflows',
+            '  /compact         Manually trigger context compaction',
+            '  /clear [id] --yes  Clear session messages (default: current session; archives originals)',
+            '  /help            Show this help',
+            '  /fork [id] [index]  Fork session (default: current session, latest message)',
+            '  /config [key] [value]  View or set configuration (dot paths supported)',
+            '  /workflow        Manage and run workflows',
         ];
         return { _tag: 'text', text: lines.join('\n') };
     },
@@ -51,42 +50,90 @@ const compactCommand = {
 };
 const modelCommand = {
     name: 'model',
-    description: 'Switch the current session model',
-    argsHint: '<model-name>',
-    execute: async (args) => {
-        if (!args)
-            return { _tag: 'error', message: 'Usage: /model <model-name>' };
-        return { _tag: 'success', message: `Model set to ${args} (takes effect next turn)` };
+    description: 'Model selection guidance',
+    argsHint: '',
+    execute: async () => {
+        // 诚实化：模型由前端 ModelSelector 决定并随请求 body 传递，服务端不保存会话级模型覆盖。
+        // 此前返回 "Model set to X" 但什么都不生效。
+        return {
+            _tag: 'text',
+            text: '会话模型请在聊天页底部的模型选择器中切换（/model 不再直接生效）。',
+        };
     },
 };
 const clearCommand = {
     name: 'clear',
-    description: 'Clear session messages',
+    description: 'Clear session messages (archives originals first)',
+    argsHint: '[session-id] [--yes]',
     execute: async (args, ctx) => {
-        if (!args)
-            return { _tag: 'error', message: 'Usage: /clear <session-id>' };
-        const { deleteEntriesByIds, getEntries } = await import('../session/message.js');
-        const entries = await getEntries(ctx.deps.db, args);
+        const parts = args.split(/\s+/).filter(Boolean);
+        const yes = parts.includes('--yes');
+        const sessionId = parts.find((p) => p !== '--yes') ?? ctx.sessionId;
+        if (!sessionId) {
+            return { _tag: 'error', message: 'Usage: /clear [session-id] --yes（当前会话可省略 id）' };
+        }
+        if (!yes) {
+            return {
+                _tag: 'error',
+                message: '清空消息不可逆。原始消息将归档保存，确认请执行 /clear --yes（或 /clear <session-id> --yes）。',
+            };
+        }
+        const { getEntries, deleteEntriesByIds } = await import('../session/message.js');
+        const entries = await getEntries(ctx.deps.db, sessionId);
         const ids = entries.map((e) => ('id' in e ? e.id : '')).filter(Boolean);
         if (ids.length > 0) {
+            // 归档原始内容（与 shake 同机制），删除才有后悔路径
+            const { archiveOriginalEntries } = await import('../session/archive.js');
+            const { generateId } = await import('../shared/index.js');
+            await archiveOriginalEntries(ctx.deps.db, sessionId, entries, 'clear', `Cleared ${ids.length} entries`, generateId());
             await deleteEntriesByIds(ctx.deps.db, ids);
         }
-        return { _tag: 'success', message: `Cleared ${ids.length} entries` };
+        return { _tag: 'success', message: `Cleared ${ids.length} entries (archived)` };
     },
 };
 const forkCommand = {
     name: 'fork',
     description: 'Fork session from a message index',
-    argsHint: '<session-id> [message-index]',
+    argsHint: '[session-id] [message-index]',
     execute: async (args, ctx) => {
-        if (!args)
-            return { _tag: 'error', message: 'Usage: /fork <session-id> [message-index]' };
-        const parts = args.split(/\s+/);
-        const sessionId = parts[0] ?? '';
-        const messageIndex = parts[1] !== undefined ? Number.parseInt(parts[1], 10) : 0;
+        const parts = args.split(/\s+/).filter(Boolean);
+        // 默认当前会话；第一个参数若是 session id（非纯数字）则用它。
+        let sessionId = ctx.sessionId;
+        let messageIndex;
+        for (const p of parts) {
+            if (/^\d+$/.test(p)) {
+                messageIndex = Number.parseInt(p, 10);
+            }
+            else if (!sessionId) {
+                sessionId = p;
+            }
+        }
+        if (!sessionId) {
+            return {
+                _tag: 'error',
+                message: 'Usage: /fork [session-id] [message-index]（当前会话可省略 id）',
+            };
+        }
+        // 未指定 index → 默认最新一条消息处分支（与 web fork API 语义一致，不再是 index 0）
+        if (messageIndex === undefined) {
+            const { getMessages } = await import('../session/message.js');
+            const messages = await getMessages(ctx.deps.db, sessionId);
+            if (messages.length === 0) {
+                return { _tag: 'error', message: 'EMPTY_SESSION: 空会话无法分支' };
+            }
+            messageIndex = messages.length - 1;
+        }
         const { forkSession } = await import('../session/branch.js');
-        const forked = await forkSession(ctx.deps.db, sessionId, messageIndex);
-        return { _tag: 'success', message: `Forked to new session: ${forked.id}` };
+        try {
+            const forked = await forkSession(ctx.deps.db, sessionId, messageIndex);
+            return { _tag: 'success', message: `Forked to new session: ${forked.id}` };
+        }
+        catch (error) {
+            return {
+                _tag: 'error',
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
     },
 };
 const configCommand = {
@@ -94,16 +141,31 @@ const configCommand = {
     description: 'View or set configuration',
     argsHint: '[key] [value]',
     execute: async (args, ctx) => {
+        const { getByPath, setPathPatch, coerce } = await import('./config-path.js');
         if (!args) {
             return { _tag: 'text', text: JSON.stringify(ctx.config, null, 2) };
         }
         const parts = args.split(/\s+/);
         const key = parts[0] ?? '';
         if (parts.length === 1) {
-            const value = ctx.config[key];
-            return { _tag: 'text', text: `${key}: ${JSON.stringify(value)}` };
+            try {
+                const value = getByPath(ctx.config, key);
+                return { _tag: 'text', text: `${key}: ${JSON.stringify(value)}` };
+            }
+            catch (error) {
+                return { _tag: 'error', message: error instanceof Error ? error.message : String(error) };
+            }
         }
-        return { _tag: 'success', message: 'Config updates are handled via the config API' };
+        // 点路径写值：与 CLI config set 同语义（project 作用域最小落盘，null=unset）
+        const { applyScopedPatch, loadConfigScopes, saveConfigScoped } = await import('./config.js');
+        const scopes = loadConfigScopes(ctx.cwd);
+        const value = coerce(parts.slice(1).join(' '));
+        const next = applyScopedPatch(scopes.project ?? {}, setPathPatch(key, value));
+        await saveConfigScoped('project', ctx.cwd, next);
+        return {
+            _tag: 'success',
+            message: `${value === null ? 'Unset' : 'Set'} ${key} (scope: project)`,
+        };
     },
 };
 const workflowCommand = {

package/dist/core/title.js

@@ -111,6 +111,21 @@ async function generateSessionTitle(deps, sessionId, firstMessage, chatProvider,
     catch (e) {
         // 标题生成是尽力而为的辅助功能：失败不阻塞主对话流，但记录以便排查。
         console.warn('[title] generateSessionTitle failed:', e instanceof Error ? e.message : String(e));
+        // P2-12：失败时回退到首条消息摘要，避免列表出现大量同名 "New Session"。
+        await fallbackTitleFromMessage(db, sessionId, firstMessage);
     }
 }
+/** 从首条消息生成回退标题：取首个非空行，超长截断（与 cleanTitle 一致）。 */
+async function fallbackTitleFromMessage(db, sessionId, firstMessage) {
+    const firstLine = firstMessage
+        .split('\n')
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    if (!firstLine)
+        return;
+    const title = firstLine.length > TITLE_MAX_LENGTH
+        ? `${firstLine.slice(0, TITLE_MAX_LENGTH - 3)}...`
+        : firstLine;
+    await updateSessionTitle(db, sessionId, title).catch(() => { });
+}
 export { DEFAULT_SESSION_TITLE, generateSessionTitle, isDefaultTitle };

package/dist/core/types.d.ts

@@ -87,6 +87,8 @@ type CommandContext = {
     cwd: string;
     config: Config;
     deps: AgentDependencies;
+    /** 当前会话 id（Web chat 路由注入）：/clear /fork 等命令默认作用于当前会话。 */
+    sessionId?: string;
     workflowRegistry?: import('./workflows/registry.js').WorkflowRegistry;
 };
 /** Declarative subcommand definition for commands like /workflow. */

package/dist/core/workflows/discovery.d.ts

@@ -28,5 +28,5 @@ type SaveResult = {
  * - 返回 { ok, filePath, meta } 或 { ok: false, error }
  */
 declare function saveWorkflow(name: string, source: string, target?: SaveTarget, projectDir?: string): Promise<SaveResult>;
-export { discoverGlobalWorkflows, discoverWorkflows, saveWorkflow };
 export type { SaveResult, SaveTarget };
+export { discoverGlobalWorkflows, discoverWorkflows, saveWorkflow };

package/dist/core/workflows/index.d.ts

@@ -1,7 +1,7 @@
 export { BUILTIN_WORKFLOWS, createBuiltinWorkflows } from './builtins.js';
 export { buildWorkflowContext } from './context.js';
-export { discoverGlobalWorkflows, discoverWorkflows, saveWorkflow } from './discovery.js';
 export type { SaveResult, SaveTarget } from './discovery.js';
+export { discoverGlobalWorkflows, discoverWorkflows, saveWorkflow } from './discovery.js';
 export type { WorkflowRegistry } from './registry.js';
 export { createAndPopulateRegistry, createWorkflowRegistry, reloadRegistry } from './registry.js';
 export { executeWorkflow } from './runtime.js';

package/dist/db/client.d.ts

@@ -5,10 +5,14 @@ import type { DBConfig } from './types.js';
  * Unified database handle.
  * `db` is the Drizzle ORM instance with schema bound.
  * `close()` cleans up the connection.
+ * `sync()` (PGLite only) flushes WAL to filesystem — periodic call 缩短
+ * 突然停机（kill -9）时的数据丢失窗口，是 WAL 之外的额外保险。
  */
 type DB = {
     db: PgliteDatabase<typeof schema>;
     close(): Promise<void>;
+    /** PGLite：syncToFs(false) 全量刷盘；PostgreSQL 模式下为 no-op（服务端自行管理）。 */
+    sync?(): Promise<void>;
 };
 /**
  * Create a database connection.

package/dist/db/client.js

@@ -23,6 +23,11 @@ async function createDB(config) {
             async close() {
                 await client.close();
             },
+            async sync() {
+                // P2-15：主动把 WAL 刷到文件系统（默认非 relaxedDurability 全量 fsync），
+                // 使 kill -9 等非优雅退出时已提交事务不丢。失败吞掉（尽力而为）。
+                await client.syncToFs().catch(() => { });
+            },
         };
     }
     // PostgreSQL mode — cast to PgliteDatabase for a unified interface.

package/dist/db/schema.d.ts

@@ -273,6 +273,40 @@ export declare const sessions: import("drizzle-orm/pg-core").PgTableWithColumns<
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        source: import("drizzle-orm/pg-core").PgColumn<{
+            name: "source";
+            tableName: "sessions";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        deletedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "deleted_at";
+            tableName: "sessions";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         createdAt: import("drizzle-orm/pg-core").PgColumn<{
             name: "created_at";
             tableName: "sessions";
@@ -783,6 +817,23 @@ export declare const fileSnapshots: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        mtimeMs: import("drizzle-orm/pg-core").PgColumn<{
+            name: "mtime_ms";
+            tableName: "file_snapshots";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         createdAt: import("drizzle-orm/pg-core").PgColumn<{
             name: "created_at";
             tableName: "file_snapshots";

package/dist/db/schema.js

@@ -1,5 +1,5 @@
 import { sql } from 'drizzle-orm';
-import { index, integer, jsonb, pgTable, real, text, timestamp, uniqueIndex, uuid, } from 'drizzle-orm/pg-core';
+import { bigint, index, integer, jsonb, pgTable, real, text, timestamp, uniqueIndex, uuid, } from 'drizzle-orm/pg-core';
 /**
  * Projects table — git repos or plain directories tracked for agent workspaces.
  * Identity: sha256(worktree)[:16]（git 仓库用仓库根，普通目录用绝对路径）。gitRemote 仅作
@@ -29,6 +29,10 @@ export const sessions = pgTable('sessions', {
     metadata: jsonb('metadata').notNull().default({}),
     agentType: text('agent_type'),
     worktreePath: text('worktree_path'),
+    /** 会话来源：'web'（Web UI）/ 'cli'（CLI print 模式）；null=旧数据视为 web。 */
+    source: text('source').default(sql `null`),
+    /** 软删除时间戳；null=未删除。回收站保留 30 天后物理清除。 */
+    deletedAt: timestamp('deleted_at', { withTimezone: true }).default(sql `null`),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
 }, (table) => [
@@ -89,6 +93,8 @@ export const fileSnapshots = pgTable('file_snapshots', {
     contentHash: text('content_hash').notNull(),
     tokenCount: integer('token_count').default(0),
     version: integer('version').default(1),
+    /** 快照创建时文件磁盘 mtime（毫秒）。注入前比对，过期自动重读（P1-5）。 */
+    mtimeMs: bigint('mtime_ms', { mode: 'number' }),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
 }, (table) => [
     index('idx_snapshots_session_path').on(table.sessionId, table.filePath),

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

@@ -14,13 +14,33 @@ type ActiveRun = {
 };
 /** Agent run 跟踪器 + 控制操作。 */
 type AgentManager = {
+    /**
+     * 同步原子占位（P0-4 POST /api/chat 并发守卫）：sessionId 无条目时立即占位并返回
+     * true；已有条目（占位或活跃 run）时返回 false。has+set 一气呵成、全程无 await，
+     * 杜绝 check-then-act 竞态——此前守卫用 get 检查、真正注册在 SSE 回调内，中间隔
+     * 多个 await，双发 POST 均通过守卫后后注册覆盖前者（runs.set），且先结束者在
+     * finally unregister 时误删仍在跑的 run，abort/steer/pause 全部失效。
+     * 占位由 register 填充、unregister 释放，二者均幂等。
+     */
+    tryAcquire(sessionId: string): boolean;
+    /** 注册活跃 run；若该 sessionId 已被 tryAcquire 占位则填充该占位。 */
     register(run: ActiveRun): void;
+    /** 取活跃 run；占位期间（register 前）返回 undefined，视为无活跃 run。 */
     get(sessionId: string): ActiveRun | undefined;
+    /** 该 sessionId 是否处于占位状态（tryAcquire 后、register 前）。 */
+    isStarting(sessionId: string): boolean;
+    /** 释放条目（占位或活跃 run）；幂等。 */
     unregister(sessionId: string): void;
+    /** 活跃 run 数（不含占位）。 */
     size(): number;
     abort(sessionId: string): boolean;
     pause(sessionId: string): boolean;
     resume(sessionId: string): boolean;
+    /** 暂停全部活跃 run 并等待到达安全点；超时强制中止（热更新前调用）。 */
+    pauseAll(timeoutMs?: number): Promise<{
+        paused: number;
+        forcedAbort: number;
+    }>;
     steer(sessionId: string, message: string): boolean;
     /** 查询某 session 的所有子 agent run（恢复/展示用）。 */
     children(parentSessionId: string): ActiveRun[];

package/dist/server/agent-manager.js

@@ -1,59 +1,111 @@
 // src/server/agent-manager.ts
 import { abortAgent, injectSteering, pauseAgent, resumeAgent } from '../core/index.js';
+/** 取 slot 内的活跃 run；占位（'starting'）或不存在返回 undefined。 */
+function slotRun(slot) {
+    return slot?.kind === 'run' ? slot.run : undefined;
+}
 function createAgentManager() {
     const runs = new Map();
     return {
+        tryAcquire(sessionId) {
+            if (runs.has(sessionId))
+                return false;
+            runs.set(sessionId, { kind: 'starting' });
+            return true;
+        },
         register(run) {
-            runs.set(run.sessionId, run);
+            runs.set(run.sessionId, { kind: 'run', run });
         },
         get(sessionId) {
-            return runs.get(sessionId);
+            return slotRun(runs.get(sessionId));
+        },
+        isStarting(sessionId) {
+            return runs.get(sessionId)?.kind === 'starting';
         },
         unregister(sessionId) {
             runs.delete(sessionId);
         },
         size() {
-            return runs.size;
+            let n = 0;
+            for (const slot of runs.values()) {
+                if (slot.kind === 'run')
+                    n += 1;
+            }
+            return n;
         },
         abort(sessionId) {
-            const run = runs.get(sessionId);
+            const run = slotRun(runs.get(sessionId));
             if (!run)
                 return false;
             abortAgent(run.state);
             return true;
         },
         pause(sessionId) {
-            const run = runs.get(sessionId);
+            const run = slotRun(runs.get(sessionId));
             if (!run)
                 return false;
             pauseAgent(run.state);
             return true;
         },
         resume(sessionId) {
-            const run = runs.get(sessionId);
+            const run = slotRun(runs.get(sessionId));
             if (!run)
                 return false;
             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;
+                }
+            }
+            return { paused: active.length - forcedAbort, forcedAbort };
+        },
         steer(sessionId, message) {
-            const run = runs.get(sessionId);
+            const run = slotRun(runs.get(sessionId));
             if (!run)
                 return false;
             injectSteering(run.state, message);
             return true;
         },
         children(parentSessionId) {
-            return Array.from(runs.values()).filter((r) => r.parentSessionId === parentSessionId);
+            return Array.from(runs.values())
+                .map((slot) => slotRun(slot))
+                .filter((r) => r?.parentSessionId === parentSessionId);
         },
         backgroundJobs() {
-            return Array.from(runs.values()).filter((r) => r.jobId !== undefined);
+            return Array.from(runs.values())
+                .map((slot) => slotRun(slot))
+                .filter((r) => r?.jobId !== undefined);
         },
         dispose() {
             // dev 热重载重建前调用：中止所有活跃 run（loop 在 turn/流边界检测 signal
             // → unwind → 调用方 finally 持久化 + unregister），然后清空 Map。
-            for (const run of runs.values()) {
-                abortAgent(run.state);
+            for (const slot of runs.values()) {
+                const run = slotRun(slot);
+                if (run)
+                    abortAgent(run.state);
             }
             runs.clear();
         },

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,9 +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 探活放行）。
-    app.use('/api/*', createAuthMiddleware(ctx.config.security.authEnabled ? ctx.config.security.token : undefined));
+    // 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,79 @@
+type DeviceRecord = {
+    id: string;
+    name: string;
+    tokenHash: string;
+    createdAt: number;
+};
+type PendingPairing = {
+    pairingId: string;
+    deviceName: string;
+    code: string;
+    createdAt: number;
+    status: 'pending' | 'approved' | 'denied';
+    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;
+    /** 轮换后仍接受为 handoff 凭据的旧 bootstrap 数量，默认 3。 */
+    handoffTokenRetention?: 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。 */
+    verifyHandoff(token: string | undefined): boolean;
+    /** 首次设备注册：校验 bootstrap 后换发设备 token 并轮换 bootstrap。
+     *  无设备时首个凭 bootstrap 的请求即视为首设备（免审批），后续请求需配对审批。
+     *  返回新设备 token；bootstrap 已失效/已注册过 → 返回 null。 */
+    registerFirstDevice(bootstrapToken: string, deviceName: string): Promise<string | null>;
+    /** 发起配对请求（未认证）：返回 { pairingId, code }；静态模式/未启用返回 null。 */
+    requestPairing(deviceName: 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;
+    }>;
+    /** 审批配对（需已认证设备调用）：通过后为请求设备签发 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 };