c0de-agent 1.11.0 → 1.13.0

package/dist/session/snapshot.d.ts

@@ -12,6 +12,9 @@ declare function getFileSnapshots(handle: DB, sessionId: string): Promise<FileSn
 declare function getLatestFileSnapshot(handle: DB, sessionId: string, filePath: string): Promise<FileSnapshot | null>;
 /** Quick check: return cached file content if a snapshot exists, else null. */
 declare function checkFileSnapshot(handle: DB, sessionId: string, filePath: string): Promise<string | null>;
-/** 把源会话每个文件的最新快照复制到目标会话（fork 分支用，P1-4）。 */
-declare function copyFileSnapshots(handle: DB, fromSessionId: string, toSessionId: string): Promise<void>;
+/** 把源会话每个文件的最新快照复制到目标会话（fork 分支用，P1-4）。
+ *  C3：beforeMs 提供时只复制创建时间 ≤ 分支点的快照版本——从较早消息点 fork 时，
+ *  分支点之后更新的快照反映的是「未来」文件状态，复制会污染分支上下文；
+ *  无合格版本的文件夹跳过（宁可缺快照由磁盘重读，也不注入错误内容）。 */
+declare function copyFileSnapshots(handle: DB, fromSessionId: string, toSessionId: string, beforeMs?: number): Promise<void>;
 export { checkFileSnapshot, copyFileSnapshots, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot, };

package/dist/session/snapshot.js

@@ -73,14 +73,22 @@ async function checkFileSnapshot(handle, sessionId, filePath) {
     const snapshot = await getLatestFileSnapshot(handle, sessionId, filePath);
     return snapshot?.content ?? null;
 }
-/** 把源会话每个文件的最新快照复制到目标会话（fork 分支用，P1-4）。 */
-async function copyFileSnapshots(handle, fromSessionId, toSessionId) {
+/** 把源会话每个文件的最新快照复制到目标会话（fork 分支用，P1-4）。
+ *  C3：beforeMs 提供时只复制创建时间 ≤ 分支点的快照版本——从较早消息点 fork 时，
+ *  分支点之后更新的快照反映的是「未来」文件状态，复制会污染分支上下文；
+ *  无合格版本的文件夹跳过（宁可缺快照由磁盘重读，也不注入错误内容）。 */
+async function copyFileSnapshots(handle, fromSessionId, toSessionId, beforeMs) {
     const rows = await handle.db
         .select()
         .from(fileSnapshots)
         .where(eq(fileSnapshots.sessionId, fromSessionId));
     const latest = new Map();
     for (const r of rows) {
+        if (beforeMs !== undefined) {
+            const created = r.createdAt instanceof Date ? r.createdAt.getTime() : new Date(r.createdAt).getTime();
+            if (created > beforeMs)
+                continue;
+        }
         const prev = latest.get(r.filePath);
         if (!prev || (r.version ?? 0) > (prev.version ?? 0))
             latest.set(r.filePath, r);

package/dist/session/types.d.ts

@@ -91,10 +91,22 @@ type ArchiveRef = {
     type: 'archive' | 'squash';
     id: string;
 };
+/** 会话级用量汇总（P0 审查：列表视图此前无法回答「会话花了多少 token/钱」）。
+ *  从 metadata.segments 聚合，零额外查询。 */
+type SessionUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    cost: number;
+    /** 价格未知（cost=null）的调用数：成本按 $0 计入，UI 需提示低估。 */
+    unknownCostCalls: number;
+    calls: number;
+};
 /** A node in the session tree. */
 type SessionTreeNode = {
     session: Session;
     children: SessionTreeNode[];
+    usage: SessionUsage;
 };
 /** A decoded compaction archive row. */
 type CompactionArchive = {
@@ -121,4 +133,4 @@ type FileSnapshot = {
     mtimeMs?: number;
     createdAt: number;
 };
-export type { ArchiveRef, BranchSummaryEntry, CompactionArchive, CompactionConfig, CompactionEntry, CompactionResult, FileSnapshot, HotFile, MessageInput, SessionEntry, SessionTreeNode, SquashConfig, SquashEntry, SteeringEntry, Summarizer, };
+export type { ArchiveRef, BranchSummaryEntry, CompactionArchive, CompactionConfig, CompactionEntry, CompactionResult, FileSnapshot, HotFile, MessageInput, SessionEntry, SessionTreeNode, SessionUsage, SquashConfig, SquashEntry, SteeringEntry, Summarizer, };

package/dist/session/usage.d.ts

@@ -0,0 +1,62 @@
+import type { DB } from '../db/client.js';
+import type { UsageConfig } from '../shared/types/config.js';
+/**
+ * 把 sessions.metadata.segments 中全部调用补齐进 usage_events（幂等）。
+ * 覆盖：升级前历史数据、fork 复制的 segments（display 用途）、导入会话携带的
+ * segments。callId 冲突（已入账）静默跳过。
+ * 返回本次新增行数。
+ */
+export declare function backfillUsageEvents(handle: DB): Promise<number>;
+/** 当月用量汇总（金额 + token），预算护栏判定用。
+ *  cost：已发生成本——价格未知（cost=null）的调用按 $0 计入，故金额口径对自建
+ *  网关/未登记模型会系统性低估；tokens：input+output+cacheRead tokens 之和，
+ *  与价格无关，作为价格独立的兜底口径（缓存读取也按用量计费，须计入）。
+ *  unknownCostCalls：当月价格未知的调用数——金额预算轴据此识别「口径低估」，
+ *  无 token 预算兜底时并入护栏告警文案（P2-2：预算静默失效不再无提示）。
+ */
+export declare function monthUsage(handle: DB, opts: {
+    projectId?: string | null;
+    sinceMs: number;
+}): Promise<{
+    cost: number;
+    tokens: number;
+    unknownCostCalls: number;
+}>;
+/** 当月累计用量（本月 1 日 00:00 本地时区起算）。
+ *  已知限制：跨时区/换机时「本月」边界随本地时区漂移，成本护栏阈值随之平移——
+ *  本地单机（服务端与用户同机）场景无影响。 */
+export declare function currentMonthUsage(handle: DB, projectId?: string | null, now?: Date): Promise<{
+    cost: number;
+    tokens: number;
+    unknownCostCalls: number;
+}>;
+/** 预算护栏判定结果：parts 为超支描述片段，action 为实际超支轴中最严格的动作
+ *  （'abort' > 'pause'；'warn' 不阻断、不会进入本判定）。
+ *  warnings：非阻断的告警片段（P2-2）——金额轴启用但当月存在价格未知调用且
+ *  无 token 预算兜底时，「金额口径低估」不再静默；消费方并入暂停/中止文案。 */
+export type BudgetOverage = {
+    parts: string[];
+    action: 'pause' | 'abort';
+    warnings: string[];
+};
+/** 预算护栏判定：金额（USD）+ token 双口径，返回超支描述 + 阻断动作（空 parts =
+ *  无需阻断——可能超支但动作仅 warn）。
+ *  金额口径受 budgetAction 控制；token 口径受 tokenBudgetAction 控制（缺省回退
+ *  budgetAction，向后兼容）。warn 动作只走前端徽标/面板告警，不进本判定。
+ *  供 Web loop 暂停/中止、CLI 拒绝、子 agent 提前中止共用。
+ *  项目口径仅在 projectId 可归属时检查（未归属会话只受全局口径兜底）。
+ *  token 口径独立于价格，兜底自建网关/未登记模型（cost 恒 $0）的场景。
+ *  P1：金额/token 两轴动作各自求值，多轴同时超支取更严格者（abort > pause），
+ *  不再被单一布尔预算标志坍缩降级。 */
+export declare function budgetOverageParts(handle: DB, usage: UsageConfig, projectId: string | null | undefined, now?: Date): Promise<BudgetOverage>;
+/** 本地时区的 YYYY-MM 月份键（与 usage 聚合、前端徽标同口径）。 */
+export declare function localMonthKey(ts: number): string;
+/** 一次性 backfill 标记键（app_meta）。 */
+export declare const USAGE_BACKFILL_MARKER = "usage_backfill_v1";
+/**
+ * P3-8：backfill 只在「升级后的首次启动」执行一次，之后跳过——
+ * backfill 的真实消费者只有升级前遗留 segments（fork 复制的 segments 经 callId
+ * 唯一约束去重本就是 no-op；导入会话的 segments 已剥离 call id 不产生账本行），
+ * 每次启动全表扫描是纯浪费。标记写入与 backfill 同事务，失败不落标记可重试。
+ */
+export declare function backfillUsageEventsOnce(handle: DB): Promise<number>;

package/dist/session/usage.js

@@ -0,0 +1,194 @@
+// src/session/usage.ts
+// 成本账本工具：usage_events 的 backfill 与月度成本查询。
+//
+// usage_events（append-only，与 session 生命周期解耦）是成本聚合的权威数据源。
+// 会话物理清除（回收站到期/彻底删除/临时会话清理）不触及它——成本是账本。
+// 写路径在 loop manageSegment（每个 LLM 调用落一行）；本模块负责两条辅助路径：
+//  1. backfillUsageEvents：把 sessions.metadata.segments 中已有调用补齐进账本
+//     （升级前产生的历史数据 + fork 复制的 segments + 导入的会话）。
+//     幂等：callId 唯一约束 + onConflictDoNothing，可安全重复执行。
+//  2. budgetOverageParts：预算暂停/拒绝（usage.budgetAction='pause'）用的当月
+//     金额 + token 双口径超支判定（token 兜底价格未知的自建网关/未登记模型）。
+import { and, eq, gte } from 'drizzle-orm';
+import { appMeta, sessions, usageEvents } from '../db/schema.js';
+/**
+ * 把 sessions.metadata.segments 中全部调用补齐进 usage_events（幂等）。
+ * 覆盖：升级前历史数据、fork 复制的 segments（display 用途）、导入会话携带的
+ * segments。callId 冲突（已入账）静默跳过。
+ * 返回本次新增行数。
+ */
+export async function backfillUsageEvents(handle) {
+    const rows = await handle.db
+        .select({ id: sessions.id, projectId: sessions.projectId, metadata: sessions.metadata })
+        .from(sessions);
+    let added = 0;
+    for (const row of rows) {
+        const meta = (row.metadata ?? {});
+        for (const seg of meta.segments ?? []) {
+            if (typeof seg.provider !== 'string' || typeof seg.model !== 'string')
+                continue;
+            for (const call of seg.calls ?? []) {
+                if (typeof call.id !== 'string' || call.id.length === 0)
+                    continue;
+                const ts = typeof call.timestamp === 'number' && call.timestamp > 0 ? call.timestamp : 0;
+                if (ts === 0)
+                    continue;
+                const input = typeof call.usage?.input === 'number' ? call.usage.input : 0;
+                const output = typeof call.usage?.output === 'number' ? call.usage.output : 0;
+                const cacheRead = typeof call.usage?.cacheRead === 'number' ? call.usage.cacheRead : 0;
+                const cost = typeof call.cost === 'number' ? call.cost : null;
+                const result = await handle.db
+                    .insert(usageEvents)
+                    .values({
+                    callId: call.id,
+                    sessionId: row.id,
+                    projectId: row.projectId,
+                    provider: seg.provider,
+                    model: seg.model,
+                    inputTokens: input,
+                    outputTokens: output,
+                    cacheRead,
+                    cost,
+                    timestamp: ts,
+                })
+                    .onConflictDoNothing();
+                if (result.rowCount && result.rowCount > 0)
+                    added += result.rowCount;
+            }
+        }
+    }
+    return added;
+}
+/** 当月用量汇总（金额 + token），预算护栏判定用。
+ *  cost：已发生成本——价格未知（cost=null）的调用按 $0 计入，故金额口径对自建
+ *  网关/未登记模型会系统性低估；tokens：input+output+cacheRead tokens 之和，
+ *  与价格无关，作为价格独立的兜底口径（缓存读取也按用量计费，须计入）。
+ *  unknownCostCalls：当月价格未知的调用数——金额预算轴据此识别「口径低估」，
+ *  无 token 预算兜底时并入护栏告警文案（P2-2：预算静默失效不再无提示）。
+ */
+export async function monthUsage(handle, opts) {
+    const conds = [gte(usageEvents.timestamp, opts.sinceMs)];
+    if (opts.projectId)
+        conds.push(eq(usageEvents.projectId, opts.projectId));
+    const rows = await handle.db
+        .select({
+        cost: usageEvents.cost,
+        inputTokens: usageEvents.inputTokens,
+        outputTokens: usageEvents.outputTokens,
+        cacheRead: usageEvents.cacheRead,
+    })
+        .from(usageEvents)
+        .where(and(...conds));
+    let cost = 0;
+    let tokens = 0;
+    let unknownCostCalls = 0;
+    for (const r of rows) {
+        if (typeof r.cost === 'number')
+            cost += r.cost;
+        else
+            unknownCostCalls += 1;
+        tokens += r.inputTokens + r.outputTokens + (r.cacheRead ?? 0);
+    }
+    return { cost, tokens, unknownCostCalls };
+}
+/** 当月累计用量（本月 1 日 00:00 本地时区起算）。
+ *  已知限制：跨时区/换机时「本月」边界随本地时区漂移，成本护栏阈值随之平移——
+ *  本地单机（服务端与用户同机）场景无影响。 */
+export async function currentMonthUsage(handle, projectId, now = new Date()) {
+    const monthStart = new Date(now.getFullYear(), now.getMonth(), 1).getTime();
+    return monthUsage(handle, { projectId, sinceMs: monthStart });
+}
+/** 预算护栏判定：金额（USD）+ token 双口径，返回超支描述 + 阻断动作（空 parts =
+ *  无需阻断——可能超支但动作仅 warn）。
+ *  金额口径受 budgetAction 控制；token 口径受 tokenBudgetAction 控制（缺省回退
+ *  budgetAction，向后兼容）。warn 动作只走前端徽标/面板告警，不进本判定。
+ *  供 Web loop 暂停/中止、CLI 拒绝、子 agent 提前中止共用。
+ *  项目口径仅在 projectId 可归属时检查（未归属会话只受全局口径兜底）。
+ *  token 口径独立于价格，兜底自建网关/未登记模型（cost 恒 $0）的场景。
+ *  P1：金额/token 两轴动作各自求值，多轴同时超支取更严格者（abort > pause），
+ *  不再被单一布尔预算标志坍缩降级。 */
+export async function budgetOverageParts(handle, usage, projectId, now = new Date()) {
+    const projectBudgetUsd = usage.monthlyBudgetUsd ?? 0;
+    const globalBudgetUsd = usage.globalMonthlyBudgetUsd ?? 0;
+    const projectTokenBudget = usage.monthlyTokenBudget ?? 0;
+    const globalTokenBudget = usage.globalMonthlyTokenBudget ?? 0;
+    const amountAction = usage.budgetAction ?? 'warn';
+    const tokenAction = usage.tokenBudgetAction ?? amountAction;
+    // P0-3：'pause' 与 'abort' 都是阻断动作（均需 loop 放行前检查）；'warn' 不阻断。
+    const amountBlocks = amountAction === 'pause' || amountAction === 'abort';
+    const tokenBlocks = tokenAction === 'pause' || tokenAction === 'abort';
+    const projectScoped = projectId != null && (projectBudgetUsd > 0 || projectTokenBudget > 0);
+    const globalScoped = globalBudgetUsd > 0 || globalTokenBudget > 0;
+    if (!projectScoped && !globalScoped)
+        return { parts: [], action: 'pause', warnings: [] };
+    const [project, global] = await Promise.all([
+        projectScoped ? currentMonthUsage(handle, projectId, now) : Promise.resolve(null),
+        globalScoped ? currentMonthUsage(handle, undefined, now) : Promise.resolve(null),
+    ]);
+    // P2-2：金额轴阻断启用但价格未知调用无 token 兜底 → 「金额口径低估」告警。
+    // 仅当对应范围未设置 token 预算（token 兜底缺失）且当月确有 cost=null 调用时
+    // 追加——warnings 不触发阻断，只并入暂停/中止文案让用户知道护栏口径不可靠。
+    const warnings = [];
+    const amountAxisActive = amountBlocks && (globalBudgetUsd > 0 || (projectBudgetUsd > 0 && projectId != null));
+    if (amountAxisActive) {
+        const globalUnknown = global?.unknownCostCalls ?? 0;
+        if (globalBudgetUsd > 0 && globalTokenBudget <= 0 && globalUnknown > 0) {
+            warnings.push(`金额口径低估：本月有 ${globalUnknown} 次调用价格未知（按 $0 计入），且未设置全局 token 预算兜底`);
+        }
+        const projectUnknown = project?.unknownCostCalls ?? 0;
+        if (projectBudgetUsd > 0 &&
+            projectTokenBudget <= 0 &&
+            projectId != null &&
+            projectUnknown > 0) {
+            warnings.push(`金额口径低估：本项目有 ${projectUnknown} 次调用价格未知（按 $0 计入），且未设置项目 token 预算兜底`);
+        }
+    }
+    const parts = [];
+    // 实际超支轴中的最严格阻断动作：任一超支轴动作 === 'abort' 即整体 abort，否则 pause。
+    let action = 'pause';
+    if (amountBlocks && globalBudgetUsd > 0 && global && global.cost > globalBudgetUsd) {
+        parts.push(`全局预算 $${globalBudgetUsd.toFixed(2)}：本月全部项目已 $${global.cost.toFixed(2)}`);
+        if (amountAction === 'abort')
+            action = 'abort';
+    }
+    if (amountBlocks && projectBudgetUsd > 0 && project && project.cost > projectBudgetUsd) {
+        parts.push(`项目预算 $${projectBudgetUsd.toFixed(2)}：本项目已 $${project.cost.toFixed(2)}`);
+        if (amountAction === 'abort')
+            action = 'abort';
+    }
+    if (tokenBlocks && globalTokenBudget > 0 && global && global.tokens > globalTokenBudget) {
+        parts.push(`全局 token 预算 ${globalTokenBudget.toLocaleString()}：本月已 ${global.tokens.toLocaleString()} tokens`);
+        if (tokenAction === 'abort')
+            action = 'abort';
+    }
+    if (tokenBlocks && projectTokenBudget > 0 && project && project.tokens > projectTokenBudget) {
+        parts.push(`项目 token 预算 ${projectTokenBudget.toLocaleString()}：本项目已 ${project.tokens.toLocaleString()} tokens`);
+        if (tokenAction === 'abort')
+            action = 'abort';
+    }
+    return { parts, action, warnings };
+}
+/** 本地时区的 YYYY-MM 月份键（与 usage 聚合、前端徽标同口径）。 */
+export function localMonthKey(ts) {
+    const d = new Date(ts);
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+}
+/** 一次性 backfill 标记键（app_meta）。 */
+export const USAGE_BACKFILL_MARKER = 'usage_backfill_v1';
+/**
+ * P3-8：backfill 只在「升级后的首次启动」执行一次，之后跳过——
+ * backfill 的真实消费者只有升级前遗留 segments（fork 复制的 segments 经 callId
+ * 唯一约束去重本就是 no-op；导入会话的 segments 已剥离 call id 不产生账本行），
+ * 每次启动全表扫描是纯浪费。标记写入与 backfill 同事务，失败不落标记可重试。
+ */
+export async function backfillUsageEventsOnce(handle) {
+    const [marker] = await handle.db
+        .select()
+        .from(appMeta)
+        .where(eq(appMeta.key, USAGE_BACKFILL_MARKER));
+    if (marker)
+        return 0;
+    const added = await backfillUsageEvents(handle);
+    await handle.db.insert(appMeta).values({ key: USAGE_BACKFILL_MARKER, value: String(Date.now()) });
+    return added;
+}

package/dist/shared/types/agent.d.ts

@@ -84,7 +84,9 @@ type LLMCall = {
         firstToken: number;
         total: number;
     };
-    cost: number;
+    /** 估算成本（USD）。null = 价格未知（provider 未注册或模型无价目），
+     *  聚合时按 $0 计入并单独计数，UI 显式提示——不再静默记 0 造成预算漏报。 */
+    cost: number | null;
     thinking?: string;
     /** 模型回复文本（替代完整 responseChunks；前端只用文本拼接）。 */
     responseText: string;
@@ -149,12 +151,23 @@ type AgentEvent = {
     tool: string;
     input: unknown;
 }
-/** P1-6：权限确认超时（5 分钟）被自动拒绝时通知前端，提供「重新询问」入口。 */
+/** P1-6：权限确认超时（5 分钟）被自动拒绝时通知前端，提供「重新询问」入口。
+ *  timeoutAction 告知兜底动作（pause=拒绝后暂停 run / deny=拒绝后继续），前端据此渲染文案。 */
  | {
     _tag: 'permission_timeout';
     toolCallId: string;
     tool: string;
     input: unknown;
+    timeoutAction: 'pause' | 'deny';
+}
+/** P0 双层超时：提示后仍无响应，pending 已兜底自动拒绝——前端须清理弹窗状态。
+ *  timeoutAction='pause' 时后端同时暂停 run（status_change(paused) 事件随后到达）。 */
+ | {
+    _tag: 'permission_expired';
+    toolCallId: string;
+    tool: string;
+    input: unknown;
+    timeoutAction: 'pause' | 'deny';
 } | {
     _tag: 'error';
     error: AgentError;
@@ -162,6 +175,13 @@ type AgentEvent = {
 /** 通知前端：本轮 LLM 调用详情已持久化，应刷新调用详情面板。轻量通知，不带 payload。 */
  | {
     _tag: 'llm_detail';
+}
+/** 工作流执行进度（/workflow run 的 onProgress → SSE progress 事件）：
+ *  前端以横幅展示当前阶段，不再对长工作流黑盒等待。 */
+ | {
+    _tag: 'progress';
+    message: string;
+    detail?: unknown;
 } | {
     _tag: 'subagent_start';
     childId: string;
@@ -202,6 +222,10 @@ type AgentEvent = {
             status: string;
         }[];
     }[];
+}
+/** SSE 心跳（服务端防前端 90s 静默看门狗误杀长任务）；前端无 UI 变化，直接忽略。 */
+ | {
+    _tag: 'heartbeat';
 } | {
     _tag: 'done';
 };
@@ -237,6 +261,9 @@ type AgentState = {
         provider: string;
         model: string;
     };
+    /** P3 成本护栏：本 run 已因预算超支暂停过一次。恢复后不再重复暂停
+     *  （用户点「恢复」即知情同意继续，反复暂停是骚扰而非护栏）。 */
+    budgetPauseTriggered?: boolean;
     /**
      * 压缩死锁标记：自动压缩成功后仍超阈值（如 keepRecentTokens 本身已超限）时置真，
      * 暂停后续自动压缩以防每轮重复触发（无限循环）。收到新用户消息（agentLoop 重入）时重置。

package/dist/shared/types/config.d.ts

@@ -46,15 +46,30 @@ type WebSearchConfig = {
 };
 /** 多 agent 配置（spec: multi-agent-design §4.12）。 */
 type AgentsConfig = {
-    /** agent markdown 目录（相对项目根），默认 '.c0de/agents'。 */
-    dir: string;
     /** 并行子 agent 数上限，默认 3。 */
     subagentConcurrency: number;
 };
 /** 权限配置：控制工具执行授权的默认行为。 */
 type PermissionConfig = {
-    /** 启动时的默认授权模式：'default' 逐个确认（默认）；'auto' 自动放行 ask 工具（YOLO 自动授权）。 */
+    /**
+     * 启动时的默认授权模式：
+     * - 'default'（默认）：只读工具自动放行；写/执行工具需确认。Web 为交互弹窗；
+     *   CLI 非交互（`c0de chat` 未加 -y）下写/执行工具直接拒绝并提示加 -y 或改 auto。
+     *   （`c0de acp` 恒为 full-auto，由编辑器侧自行控制执行授权，不受本项影响。）
+     * - 'auto'：全部工具自动放行（YOLO）。克隆仓库前务必先审查其 .c0de/config.json。
+     */
     defaultMode: 'default' | 'auto';
+    /**
+     * 权限确认超时（提示后 25 分钟宽限期满）兜底拒绝后的动作：
+     * - 'pause'（默认）：拒绝该工具并暂停 run，用户回来点「恢复」继续——
+     *   避免 default 模式下 agent 在用户缺席时继续自主执行后续工具；
+     * - 'deny'：拒绝该工具，run 继续执行（旧行为，会话绝不挂起）。
+     */
+    timeoutAction?: 'pause' | 'deny';
+    /** 首层确认超时（毫秒）——超过仅提示、pending 保持；默认 5 分钟。 */
+    timeoutMs?: number;
+    /** 首层超时后到兜底自动拒绝的宽限期（毫秒）；默认 25 分钟。 */
+    expireGraceMs?: number;
 };
 /** 自动升级配置（spec §18）。控制后台 npm registry 检查与无感知热更新行为。 */
 type UpdateConfig = {
@@ -81,6 +96,50 @@ type SecurityConfig = {
     token?: string;
     /** 额外允许的 CORS origin（本地回环始终允许；局域网/远程访问需显式添加）。 */
     allowedOrigins: string[];
+    /** 首设备 bootstrap token 有效期（毫秒）。bootstrap 自生成（auth-token 文件
+     *  mtime）起超过此时长即拒绝首设备注册。未设置时默认 5 分钟（auth-manager 内置）；
+     * 无已注册设备时每次 serve 都会重新生成 bootstrap，故重启即可恢复注册。
+     *  用于共享主机等 URL 可能泄漏的场景，缩短「先到先得」竞态窗口。 */
+    firstDeviceTtlMs?: number;
+};
+/** 用量与成本统计配置。 */
+type UsageConfig = {
+    /** 月度成本预算（USD，按配置价目估算）。0 = 不限制。
+     *  项目口径：当前项目聚合成本超过预算时告警/暂停。
+     *  当前月成本超过预算时，设置页「用量」面板给出醒目告警。 */
+    monthlyBudgetUsd: number;
+    /**
+     * 全局月度成本预算（USD，所有项目 + 未归属调用聚合）。0 = 不限制。
+     *  P1-3：与项目预算并存，任一超支即触发 budgetAction——
+     *  未归属项目/未配置项目预算的花费至少受全局预算兜底。
+     *  仅 global 作用域生效：项目作用域写入会被剥离并忽略（作用域收敛）。 */
+    globalMonthlyBudgetUsd?: number;
+    /**
+     * 月度 token 预算（input + output + cacheRead tokens 之和），0 = 不限制。
+     *  P0：价格独立护栏——自建网关/未登记模型的 cost 恒 $0，金额护栏拦不住，
+     *  token 护栏按 token 量兜底（缓存读取亦按用量计费，故纳入口径）。
+     *  动作由 tokenBudgetAction 决定（缺省回退 budgetAction，向后兼容）。 */
+    monthlyTokenBudget?: number;
+    /**
+     * 全局月度 token 预算（所有项目 + 未归属调用聚合），0 = 不限制。
+     *  与 monthlyTokenBudget 并存，任一超支即按 tokenBudgetAction 触发。
+     *  仅 global 作用域生效（与 globalMonthlyBudgetUsd 同口径）。 */
+    globalMonthlyTokenBudget?: number;
+    /**
+     * 超支动作（P3 成本护栏），作用于**金额**预算：
+     * - 'warn'（默认）：仅告警（顶栏徽标/用量面板），agent 继续执行；
+     * - 'pause'：新一轮 LLM 请求前发现当月成本超预算 → 暂停 run（等同权限超时
+     *   暂停机制），用户点「恢复」后本 run 不再因预算重复暂停（用户已知情）；
+     * - 'abort'：新一轮 LLM 请求前发现超预算 → 中止 run（硬封顶，无「恢复」按钮，
+     *   需重新发送消息/调高预算后重试），适合需要「撞线即硬停、不可在界面原地放行」的场景。
+     */
+    budgetAction?: 'warn' | 'pause' | 'abort';
+    /**
+     * token 预算的超支动作，独立于金额预算（P：token 是兜底口径，用户可能希望
+     * 「金额超支暂停、token 超支只告警」或反之）。缺省回退 budgetAction。
+     * 语义同 budgetAction：'pause'/'abort' 硬性暂停/中止，'warn' 仅徽标/面板告警。
+     */
+    tokenBudgetAction?: 'warn' | 'pause' | 'abort';
 };
 /** Global application configuration. */
 type Config = {
@@ -120,7 +179,7 @@ type Config = {
     agents: AgentsConfig;
     permission: PermissionConfig;
     update: UpdateConfig;
+    usage: UsageConfig;
     theme: 'light' | 'dark' | 'system';
-    locale: string;
 };
-export type { AgentsConfig, CompactionConfig, Config, MCPServerConfig, PermissionConfig, SecurityConfig, ToolMetricsConfig, UpdateConfig, WebSearchConfig, };
+export type { AgentsConfig, CompactionConfig, Config, MCPServerConfig, PermissionConfig, SecurityConfig, ToolMetricsConfig, UpdateConfig, UsageConfig, WebSearchConfig, };

package/dist/shared/types/kanban.d.ts

@@ -30,10 +30,10 @@ type KanbanCard = {
     createdAt: string;
     updatedAt: string;
 };
-/** A kanban board (one per project). */
+/** A kanban board (one per project). P2-5：回收站（软删除）看板 projectId 为 null。 */
 type KanbanBoard = {
     id: string;
-    projectId: string;
+    projectId: string | null;
     columns: KanbanColumnDef[];
     labels: KanbanLabelDef[];
     createdAt: string;
@@ -51,6 +51,8 @@ declare const KANBAN_LABEL_COLORS: readonly string[];
  *  implementation, mirroring the todoState pattern). */
 interface KanbanStore {
     getBoard(): Promise<KanbanBoardWithCards>;
+    /** 只读获取板（不懒创建）：纯读路径（导出等）用，无板返回 null。 */
+    peekBoard(): Promise<KanbanBoardWithCards | null>;
     addCard(input: {
         title: string;
         description?: string | null;
@@ -70,6 +72,19 @@ interface KanbanStore {
         columns?: KanbanColumnDef[];
         labels?: KanbanLabelDef[];
     }): Promise<KanbanBoard>;
+    /** 导入/替换整板：列与标签配置 + 全部卡片原子替换（导入数据的落点）。 */
+    replaceBoard(input: {
+        columns: KanbanColumnDef[];
+        labels: KanbanLabelDef[];
+        cards: Array<{
+            title: string;
+            description?: string | null;
+            columnId: string;
+            priority: KanbanPriority;
+            position: number;
+            labels: string[];
+        }>;
+    }): Promise<KanbanBoardWithCards>;
 }
 export type { KanbanBoard, KanbanBoardWithCards, KanbanCard, KanbanColumnDef, KanbanLabelDef, KanbanPriority, KanbanStore, };
 export { DEFAULT_KANBAN_COLUMNS, KANBAN_LABEL_COLORS };

package/dist/shared/types/message.d.ts

@@ -48,12 +48,35 @@ type SessionMetadata = {
     mainThreadId?: string;
     squashCount?: number;
     fileSnapshots?: string[];
+    /** 工作流运行会话对应的 /workflow 名称（创建时写入；中断恢复指引展示用）。 */
+    workflowName?: string;
     /** 本会话分段增量 LLM 调用记录，用于调用详情面板展示。 */
     segments?: LLMSegment[];
     /** 上次 agent run 状态；status='running' 且进程无活跃 run → 被中断。 */
     lastRun?: LastRun;
+    /** M3：中断 run 的半截轮次区间起点——最后一条含文本 user 消息的条目 id。
+     *  区间 (since, until] 内的条目属「未完成轮次」：构建上下文时剔除、时间线置灰。
+     *  与 unfinishedUntilEntryId 成对使用；条目被 /clear、压缩归档后区间自然失效（no-op）。 */
+    unfinishedSinceEntryId?: string;
+    /** M3：中断轮次区间终点——标记时数据库中最后一条条目的 id（含）。 */
+    unfinishedUntilEntryId?: string;
     /** 上次打开时间戳（ms），用于会话列表按最近打开排序。 */
     lastOpenedAt?: number;
+    /** P2：会话级授权模式覆盖（'auto'/'default'），跨重启持久化。 */
+    permissionMode?: 'auto' | 'default';
+    /** 回收站条目首次被用户看到的时间戳（ms）。回收站保留期自此起算，而非删除时间——
+     *  避免「删除后长期不开服务，重启即被静默物理清除、从未见过倒计时」的墙钟缺陷。
+     *  只标记一次（touchTrashSeen 不重置），保证倒计时稳定可预期。 */
+    trashSeenAt?: number;
+    /** 回收站条目已到期、进入物理清除宽限期的时间戳（ms）。
+     *  到期先标记，宽限期（默认 7 天）内可在 UI 恢复；期满后由 purgeDeletedSessions 物理清除。 */
+    purgePendingAt?: number;
+    /**
+     * P2-3：最近一次预算超支暂停的原因（loop 暂停时写入）。热更新/重启后 run 重建，
+     * 内存 budgetPauseTriggered 标记丢失——新 run 启动时消费此字段还原标记，
+     * 避免用户已确认继续后又被同一超支原因二次暂停。消费即删除（单次语义）。
+     */
+    budgetPauseReason?: string;
 };
 /** A conversation session (may have a parent for branching). */
 type Session = {

package/dist/tools/builtin/kanban.js

@@ -31,6 +31,17 @@ function formatBoardSummary(board, errors = []) {
         if (cards.length === 0)
             lines.push('  (empty)');
     }
+    // P1 修复：历史幽灵卡片（列 id 不在当前列配置，旧版本脏数据）单独列出并附
+    // 完整 id——否则对 agent 完全不可见（且 Total 与列之和恒对不上），无法清理。
+    const colIds = new Set(board.columns.map((c) => c.id));
+    const orphans = board.cards.filter((c) => !colIds.has(c.columnId));
+    if (orphans.length > 0) {
+        lines.push(`## 未归属列 (${orphans.length})`);
+        for (const card of orphans) {
+            lines.push(`  [${card.id}] "${card.title}"（引用已不存在的列 "${card.columnId}"，` +
+                `可 delete 清理或 move 到现有列）`);
+        }
+    }
     const total = board.cards.length;
     lines.push(`\nTotal: ${total} card(s).`);
     if (total === 0)
@@ -84,12 +95,12 @@ export const kanbanTool = {
     name: 'kanban',
     description: `Manage the project's shared kanban task board. 5 operations:
 - view: list all columns and cards (read-only)
-- add: create a new task card (title required; optional description, columnId defaults to todo, priority defaults to medium, labels)
+- add: create a new task card (title required; optional description, columnId defaults to the board's first column, priority defaults to medium, labels)
 - update: edit a card's title/description/priority/labels (id required)
 - move: move a card to a different column or reorder (id + columnId required; optional position)
 - delete: remove a card (id required)
 
-The board is shared across all sessions and agents in the same project — use it to coordinate work, track tasks visible to the user, and break down complex projects. Column ids are: todo, in_progress, in_review, done, cancelled (customizable by the user via the board config UI).`,
+The board is shared across all sessions and agents in the same project — use it to coordinate work, track tasks visible to the user, and break down complex projects. Column ids are user-configurable: do NOT guess them — run \`view\` first to discover the current columns, then reuse those exact ids. Adding/moving to an unknown column id fails with the list of valid ids.`,
     parameters: kanbanParameters,
     permission: 'auto',
     execute: async (input, ctx) => {

package/dist/tools/index.d.ts

@@ -34,10 +34,21 @@ import type { ToolRegistry } from './types.js';
  */
 export declare function createDefaultRegistry(config?: Config): ToolRegistry;
 /**
- * 解析本轮启用的工具名列表（P1-1 修复：config.tools.enabled/disabled 双入口统一生效）。
+ * 解析本轮启用的工具名列表（config.tools.enabled/disabled 双入口统一生效）。
  *
- * - explicit（前端显式选择）非 undefined → 以其为准，但过滤掉 disabled 与未注册名。
- * - 否则 enabled 非空 → enabled ∩ registered；enabled 空 → 全部 registered（空=全部）。
+ * 语义（P1-1 修复「空=全部」安全陷阱 + P2 交集收紧）：
+ * - explicit（前端显式选择）非 undefined → 与 config.tools.enabled 取交集——
+ *   enabled 含 '*' 或未配置时视为无上限（explicit 原样生效）。此前 explicit 完全
+ *   覆盖 enabled：config.tools.enabled=[] 的 fail-closed 语义可被请求级 tools
+ *   静默绕过，设置页「禁用全部」与实际行为矛盾。
+ * - 否则 config.tools.enabled：含 '*'（通配）→ 全部注册工具；
+ *   空数组 → 无工具（fail-closed）；否则 → 显式名单。
  * - disabled 恒过滤（registry 已排除，此处兜底）。
  */
 export declare function resolveEnabledToolNames(registry: ToolRegistry, config: Pick<Config, 'tools'>, explicit?: string[]): string[];
+/**
+ * 依赖「会话绑定项目」的工具：其运行时依赖（如 kanban 的 kanbanStore）由宿主按
+ * session.projectId 注入——无项目会话（CLI print 未注册 cwd 等）调用必失败，
+ * 只会浪费一轮工具调用。会话无 projectId 时从工具集中剔除。
+ */
+export declare const PROJECT_BOUND_TOOLS: ReadonlySet<string>;