c0de-agent 1.11.0 → 1.13.0

package/dist/server/terminal/pty-manager.d.ts

@@ -21,6 +21,8 @@ export interface CreatePTYOptions {
     shell?: string;
     /** 所属项目 id。 */
     projectId?: string;
+    /** 指定 PTY id（热更新快照恢复时沿用原 id，前端布局无感重连）。 */
+    id?: string;
 }
 /**
  * 检测当前平台默认 shell。
@@ -32,6 +34,16 @@ export interface CreatePTYOptions {
  * /etc/passwd（getpwuid），是用户真实登录 shell 的可靠来源。
  */
 export declare function detectShell(): string;
+/** 把 argv 拼回可安全经 shell 重放的命令行（导出便于单测安全转义）。 */
+export declare function argvToCommand(argv: string[]): string;
+/**
+ * 尽力捕获 shell 当前前台命令（Linux 专有，最佳努力）——热更新后可选自动重跑。
+ * 读取 /proc/<shellPid>/task/<shellPid>/children：
+ *   - 恰好 1 个直接子进程 → 返回其 cmdline（如 `npm run dev`）。
+ *   - 0 个 / 多个（后台任务、管道、子 shell）→ 返回 null（不猜，回退默认不重跑）。
+ * 非 Linux 平台或任何读取异常 → null（能力不可用，优雅降级）。
+ */
+export declare function captureForegroundCommand(shellPid: number): string | null;
 /**
  * PTY 生命周期管理器。
  *

package/dist/server/terminal/pty-manager.js

@@ -1,6 +1,6 @@
 // src/server/terminal/pty-manager.ts
 import { randomUUID } from 'node:crypto';
-import { mkdirSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir, userInfo } from 'node:os';
 import { basename, join } from 'node:path';
 import { spawn } from 'node-pty';
@@ -86,6 +86,10 @@ export function detectShell() {
 }
 const DEFAULT_COLS = 80;
 const DEFAULT_ROWS = 24;
+/** P3-13：cols/rows 上限钳制——路由层只查 Number.isFinite，负值/超大值直接进
+ *  spawn 可能打爆 node-pty 缓冲区或 UI 布局。 */
+const MAX_COLS = 1000;
+const MAX_ROWS = 500;
 const MAX_TITLE_LEN = 100;
 /** scrollback 环形缓冲最大字节数（约 50KB）。 */
 const SCROLLBACK_MAX = 50_000;
@@ -93,6 +97,41 @@ function truncateTitle(title) {
     const clean = title.replace(/[\r\n]/g, ' ').trim();
     return clean.length > MAX_TITLE_LEN ? `${clean.slice(0, MAX_TITLE_LEN)}…` : clean;
 }
+/** POSIX 单引号转义：仅安全字符（字母数字与常见路径/别名符号）原样，否则单引号包裹。 */
+function shellQuote(arg) {
+    if (/^[A-Za-z0-9_./:,+@%=-]+$/.test(arg))
+        return arg;
+    return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+/** 把 argv 拼回可安全经 shell 重放的命令行（导出便于单测安全转义）。 */
+export function argvToCommand(argv) {
+    return argv.map(shellQuote).join(' ');
+}
+/**
+ * 尽力捕获 shell 当前前台命令（Linux 专有，最佳努力）——热更新后可选自动重跑。
+ * 读取 /proc/<shellPid>/task/<shellPid>/children：
+ *   - 恰好 1 个直接子进程 → 返回其 cmdline（如 `npm run dev`）。
+ *   - 0 个 / 多个（后台任务、管道、子 shell）→ 返回 null（不猜，回退默认不重跑）。
+ * 非 Linux 平台或任何读取异常 → null（能力不可用，优雅降级）。
+ */
+export function captureForegroundCommand(shellPid) {
+    if (process.platform !== 'linux')
+        return null;
+    try {
+        const childrenRaw = readFileSync(`/proc/${shellPid}/task/${shellPid}/children`, 'utf8');
+        const children = childrenRaw.trim().split(/\s+/).filter(Boolean).map(Number);
+        if (children.length !== 1)
+            return null;
+        const cmdline = readFileSync(`/proc/${children[0]}/cmdline`, 'utf8');
+        const argv = cmdline.split('\0').filter((s) => s.length > 0);
+        if (argv.length === 0)
+            return null;
+        return argvToCommand(argv);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * PTY 生命周期管理器。
  *
@@ -104,9 +143,15 @@ export class PTYManager {
     entries = new Map();
     /** 创建新 PTY 会话。 */
     create(opts) {
-        const id = `pty_${randomUUID()}`;
-        const cols = opts.cols ?? DEFAULT_COLS;
-        const rows = opts.rows ?? DEFAULT_ROWS;
+        const id = opts.id ?? `pty_${randomUUID()}`;
+        // 指定 id 已存在（重复 restore 快照）→ 返回既有条目，避免泄漏/覆盖进程。
+        const existing = this.entries.get(id);
+        if (existing)
+            return existing.info;
+        // P3-13：钳制到 [1, MAX]——负值/超大值不进入 spawn。
+        const clampDim = (v, dflt, max) => Math.min(max, Math.max(1, Number.isFinite(v) ? v : dflt));
+        const cols = clampDim(opts.cols, DEFAULT_COLS, MAX_COLS);
+        const rows = clampDim(opts.rows, DEFAULT_ROWS, MAX_ROWS);
         const shell = opts.shell ?? detectShell();
         const integration = setupShellIntegration(shell);
         const pty = spawn(shell, integration.spawnArgs, {
@@ -158,6 +203,14 @@ export class PTYManager {
                     ws.close(1000, 'pty exited');
                 }
             }
+            // P3-12 修复：自然退出同样清理 shell 注入脚本/目录（bash --init-file、
+            // zsh ZDOTDIR 临时文件）——此前仅 kill() 清理，自然退出残留 /tmp。
+            try {
+                entry.integrationCleanup?.();
+            }
+            catch {
+                // 清理失败不影响退出流程
+            }
             this.entries.delete(id);
         });
         this.entries.set(id, entry);
@@ -175,9 +228,12 @@ export class PTYManager {
         const entry = this.entries.get(id);
         if (!entry)
             throw new Error(`PTY not found: ${id}`);
-        entry.pty.resize(Math.max(1, cols), Math.max(1, rows));
-        entry.info.cols = cols;
-        entry.info.rows = rows;
+        // P3-13：与 create 同口径钳制
+        const c = Math.min(MAX_COLS, Math.max(1, cols));
+        const r = Math.min(MAX_ROWS, Math.max(1, rows));
+        entry.pty.resize(c, r);
+        entry.info.cols = c;
+        entry.info.rows = r;
     }
     /** 更新 PTY 标题。 */
     setTitle(id, title) {

package/dist/server/types.d.ts

@@ -32,6 +32,9 @@ type ServerContext = {
     /** 会话级授权模式覆盖：Map<sessionId, mode>。会话未覆盖时回退 permissionMode。
      *  P1-5：auto 是高风险状态，按会话隔离避免一个标签页切换影响全部会话。 */
     sessionPermissionModes: Map<string, 'default' | 'auto'>;
+    /** 会话级「始终允许」工具白名单：Map<sessionId, string[]>。持久化于
+     *  session.metadata.alwaysAllow；checker 经 getter 实时读取（run 中可追加）。 */
+    sessionAlwaysAllow: Map<string, string[]>;
     /**
      * API Bearer token（认证未显式关闭时必存在）。
      * 用户配置 security.token 优先；否则自动生成并持久化到数据目录 auth-token 文件
@@ -43,10 +46,23 @@ type ServerContext = {
     authManager?: AuthManager;
     /** 主 HTTP 服务实际绑定端口（startServer 绑定后回填；热更新 spawn 新实例复用）。 */
     port?: number;
+    /** 主 HTTP 服务绑定地址（startServer 回填；热更新 spawn 新实例须复用同一地址）。 */
+    host?: string;
+    /** P1-1：项目级 LLM 注册表缓存 Map<projectId, Registry>——按项目合并配置
+     *  （global + 项目 .c0de/config.json 的 providers）构建，会话聊天按所属项目
+     *  解析路由。项目配置 PATCH 后失效重建。 */
+    projectRegistries?: Map<string, Registry>;
     /** Agent 类型注册表（spec: multi-agent-design）。注入 agent loop 的 runSubAgent。 */
     agentRegistry: AgentRegistry;
     /** 工作流注册表（spec: dynamic-workflow-design）。注入 /workflow slash 命令和 workflowz steering。 */
     workflowRegistry?: import('../core/workflows/registry.js').WorkflowRegistry;
+    /** 工作流运行占用：发起会话 id → 工作流会话 id（/workflow run 通道）。
+     *  发起会话在其工作流运行期间视为占用——主 run 与再次 /workflow run 均 409；
+     *  abort/pause/resume 控制端点据此路由到实际的工作流 run。 */
+    workflowBusyBySession: Map<string, string>;
+    /** 工作流运行占用：执行作用域键 → 工作流会话 id。键为 `project:<projectId>`
+     *  或 `dir:<cwd>`（REST 无 projectId 时）。同一项目/目录不允许并发工作流执行。 */
+    workflowBusyByScope: Map<string, string>;
     /** 后台版本检查调度器（spec §18.1）；/api/update 读取其缓存结果。 */
     updateScheduler: UpdateScheduler;
     /** Handoff HTTP 端点（spec §18.3）；热更新时新实例 POST /handoff 触发优雅退出。 undefined 表示未启用。 */

package/dist/session/archive.d.ts

@@ -8,8 +8,10 @@ declare function getArchive(handle: DB, id: string): Promise<CompactionArchive |
 declare function getArchiveOriginalEntries(handle: DB, archiveId: string): Promise<SessionEntry[]>;
 /** Search archives by keyword (case-insensitive substring on searchable text). */
 declare function searchArchives(handle: DB, sessionId: string, query: string): Promise<CompactionArchive[]>;
+/** List archives for a session（按创建时间倒序）。可选 query 走搜索过滤。 */
+declare function listArchives(handle: DB, sessionId: string, query?: string): Promise<CompactionArchive[]>;
 /** Parse a `@[archive:<id>]` or `@[squash:<n>]` reference from text. Returns null if none. */
 declare function parseArchiveReference(text: string): ArchiveRef | null;
 /** Resolve an archive reference to displayable text. */
 declare function resolveArchiveReference(handle: DB, sessionId: string, ref: ArchiveRef): Promise<string | null>;
-export { archiveOriginalEntries, getArchive, getArchiveOriginalEntries, parseArchiveReference, resolveArchiveReference, searchArchives, };
+export { archiveOriginalEntries, getArchive, getArchiveOriginalEntries, listArchives, parseArchiveReference, resolveArchiveReference, searchArchives, };

package/dist/session/archive.js

@@ -98,6 +98,18 @@ async function searchArchives(handle, sessionId, query) {
         .orderBy(desc(compactionArchives.createdAt));
     return rows.map(rowToArchive);
 }
+/** List archives for a session（按创建时间倒序）。可选 query 走搜索过滤。 */
+async function listArchives(handle, sessionId, query) {
+    if (query && query.trim().length > 0) {
+        return searchArchives(handle, sessionId, query.trim());
+    }
+    const rows = await handle.db
+        .select()
+        .from(compactionArchives)
+        .where(eq(compactionArchives.sessionId, sessionId))
+        .orderBy(desc(compactionArchives.createdAt));
+    return rows.map(rowToArchive);
+}
 /** Parse a `@[archive:<id>]` or `@[squash:<n>]` reference from text. Returns null if none. */
 function parseArchiveReference(text) {
     const archiveId = text.match(/@\[archive:([^\]]+)\]/)?.[1];
@@ -126,4 +138,4 @@ async function resolveArchiveReference(handle, sessionId, ref) {
         return null;
     return `[Referenced Squash #${index + 1}]\n${row.summary}`;
 }
-export { archiveOriginalEntries, getArchive, getArchiveOriginalEntries, parseArchiveReference, resolveArchiveReference, searchArchives, };
+export { archiveOriginalEntries, getArchive, getArchiveOriginalEntries, listArchives, parseArchiveReference, resolveArchiveReference, searchArchives, };

package/dist/session/branch.d.ts

@@ -14,7 +14,8 @@ declare function forkSession(handle: DB, sessionId: string, messageIndex: number
 declare function getBranches(handle: DB, sessionId: string): Promise<Session[]>;
 /** Build a full session tree from root sessions down.
  * 每层按 metadata.lastOpenedAt 降序（fallback updatedAt、createdAt）。
- * 排除软删除会话与 CLI 来源会话（Web 树仅展示 web 会话）。
+ * 排除软删除会话与临时 CLI 会话（print/workflow）；持久化 CLI 会话（--continue 续接）
+ * 与 Web 会话同树可见（CLI/Web 同库不同视图 → 同库同视图）。
  */
 declare function getTree(handle: DB): Promise<SessionTreeNode[]>;
 export { BranchPointOutOfRangeError, forkSession, getBranches, getTree };

package/dist/session/branch.js

@@ -1,8 +1,8 @@
-import { and, eq, isNull, ne, or } from 'drizzle-orm';
-import { sessions } from '../db/schema.js';
+import { and, eq, isNull, lte } from 'drizzle-orm';
+import { compactionArchives, sessions } from '../db/schema.js';
 import { generateId } from '../shared/index.js';
 import { getEntries, insertEntry } from './message.js';
-import { createSession, getSession, rowToSession } from './session.js';
+import { createSession, getSession, rowToSession, webVisibleSessionCondition } from './session.js';
 import { copyFileSnapshots } from './snapshot.js';
 /**
  * fork 分支点 messageIndex 越界（评审 NIT：客户端索引过期/分页 bug）。
@@ -82,13 +82,72 @@ async function forkSession(handle, sessionId, messageIndex) {
     // 中途失败整体回滚，不残留永久可见的半成品分支（同 compactSession/squashRecent 写法）。
     const updated = await handle.db.transaction(async (tx) => {
         const txHandle = { db: tx, close: handle.close };
-        const forked = await createSession(txHandle, `Branch of ${source.title}`, source.projectId ?? undefined, undefined, source.source === 'cli' ? 'cli' : 'web');
+        const branchPointMs = typeof target.createdAt === 'number' ? target.createdAt : new Date(target.createdAt).getTime();
+        const forked = await createSession(txHandle, `Branch of ${source.title}`, source.projectId ?? undefined, undefined, source.source === 'cli' ? 'cli' : 'web', undefined, source.worktreePath ?? undefined);
         await tx
             .update(sessions)
             .set({ parentId: sessionId, branchPoint: messageIndex })
             .where(eq(sessions.id, forked.id));
+        // P2：复制分支点之前的归档（compaction/squash/shake/clear 原始内容）——
+        // 此前 fork 后归档面板为空、时间线压缩条目引用悬空 archiveId。
+        // 新归档换新 id，并重映射复制条目中的 archiveId 引用。
+        const sourceArchives = await tx
+            .select()
+            .from(compactionArchives)
+            .where(and(eq(compactionArchives.sessionId, sessionId), lte(compactionArchives.createdAt, new Date(branchPointMs))));
+        const archiveIdMap = new Map();
+        for (const a of sourceArchives) {
+            const newId = generateId();
+            archiveIdMap.set(a.id, newId);
+            await tx.insert(compactionArchives).values({
+                id: newId,
+                sessionId: forked.id,
+                compactionId: a.compactionId,
+                archiveType: a.archiveType,
+                originalEntries: a.originalEntries,
+                fileSnapshots: a.fileSnapshots,
+                summary: a.summary,
+                tokenCount: a.tokenCount,
+                searchableText: a.searchableText,
+                createdAt: a.createdAt,
+            });
+        }
+        // P2：继承分支点之前的用量 segments（徽标/会话信息面板显示继承成本；
+        // calls 按时间过滤，分支点之后的调用不属于本分支）。usage_events 账本不受影响——
+        // fork 不产生新调用，backfill 经 callId 唯一约束去重，无重复记账。
+        const inheritedSegments = (source.metadata.segments ?? [])
+            .map((seg) => ({
+            ...seg,
+            calls: seg.calls.filter((c) => c.timestamp <= branchPointMs),
+        }))
+            .filter((seg) => seg.calls.length > 0);
+        // fork 继承权限态（permissionMode/alwaysAllow）。fork 语义是「完整上下文副本」，
+        // 此前不复制权限态会使分支静默回退 default 模式、白名单丢失、用户重遇权限疲劳。
+        // 同机同用户 fork 继承 auto/白名单安全（与跨机器 import 的「默认剥离」相反——
+        // import 面向陌生来源，fork 面向本人上下文）。
+        const srcMeta = source.metadata;
+        const forkedMeta = {};
+        if (inheritedSegments.length > 0)
+            forkedMeta.segments = inheritedSegments;
+        if (srcMeta.permissionMode === 'auto' || srcMeta.permissionMode === 'default') {
+            forkedMeta.permissionMode = srcMeta.permissionMode;
+        }
+        if (Array.isArray(srcMeta.alwaysAllow)) {
+            forkedMeta.alwaysAllow = srcMeta.alwaysAllow.filter((x) => typeof x === 'string');
+        }
+        if (Object.keys(forkedMeta).length > 0) {
+            await tx.update(sessions).set({ metadata: forkedMeta }).where(eq(sessions.id, forked.id));
+        }
         for (const e of toCopy) {
-            await insertEntry(txHandle, entryToRow(e, forked.id));
+            const row = entryToRow(e, forked.id);
+            // 归档 id 重映射：compaction/squash 条目引用新复制的归档
+            if (row.tag === 'compaction' || row.tag === 'squash') {
+                const content = row.content;
+                if (typeof content.archiveId === 'string' && archiveIdMap.has(content.archiveId)) {
+                    row.content = { ...content, archiveId: archiveIdMap.get(content.archiveId) };
+                }
+            }
+            await insertEntry(txHandle, row);
         }
         await insertEntry(txHandle, {
             id: generateId(),
@@ -99,8 +158,9 @@ async function forkSession(handle, sessionId, messageIndex) {
                 sourceSessionId: sessionId,
             },
         });
-        // 复制源会话最新文件快照（P1-4：@文件上下文随分支保留）。
-        await copyFileSnapshots(txHandle, sessionId, forked.id);
+        // 复制源会话文件快照（P1-4：@文件上下文随分支保留）。
+        // C3：按分支点时间过滤——分支点之后更新的快照是「未来」状态，不复制。
+        await copyFileSnapshots(txHandle, sessionId, forked.id, branchPointMs);
         const created = await getSession(txHandle, forked.id);
         if (!created)
             throw new Error('Forked session not found after creation');
@@ -116,15 +176,37 @@ async function getBranches(handle, sessionId) {
         .where(and(eq(sessions.parentId, sessionId), isNull(sessions.deletedAt)));
     return rows.map(rowToSession);
 }
+/** 从会话 metadata.segments 聚合用量（零额外查询——段数据已在行内）。 */
+function sessionUsage(session) {
+    const calls = (session.metadata.segments ?? []).flatMap((s) => s.calls ?? []);
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheRead = 0;
+    let cost = 0;
+    let unknownCostCalls = 0;
+    for (const c of calls) {
+        inputTokens += c.usage.input;
+        outputTokens += c.usage.output;
+        cacheRead += c.usage.cacheRead ?? 0;
+        if (c.cost == null) {
+            unknownCostCalls += 1;
+        }
+        else {
+            cost += c.cost;
+        }
+    }
+    return { inputTokens, outputTokens, cacheRead, cost, unknownCostCalls, calls: calls.length };
+}
 /** Build a full session tree from root sessions down.
  * 每层按 metadata.lastOpenedAt 降序（fallback updatedAt、createdAt）。
- * 排除软删除会话与 CLI 来源会话（Web 树仅展示 web 会话）。
+ * 排除软删除会话与临时 CLI 会话（print/workflow）；持久化 CLI 会话（--continue 续接）
+ * 与 Web 会话同树可见（CLI/Web 同库不同视图 → 同库同视图）。
  */
 async function getTree(handle) {
     const rows = await handle.db
         .select()
         .from(sessions)
-        .where(and(isNull(sessions.deletedAt), or(isNull(sessions.source), ne(sessions.source, 'cli'))));
+        .where(and(isNull(sessions.deletedAt), webVisibleSessionCondition()));
     const byParent = new Map();
     for (const row of rows) {
         const session = rowToSession(row);
@@ -140,6 +222,7 @@ async function getTree(handle) {
         .map((session) => ({
         session,
         children: build(session.id),
+        usage: sessionUsage(session),
     }));
     return build(null);
 }

package/dist/session/context.js

@@ -1,5 +1,7 @@
 import { readFile, stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { eq } from 'drizzle-orm';
+import { sessions } from '../db/schema.js';
 import { getEntries } from './message.js';
 import { getFileSnapshots, upsertFileSnapshot } from './snapshot.js';
 /**
@@ -164,16 +166,40 @@ function injectSnapshots(messages, snapshots) {
         return [snapshotMessage];
     return [first, snapshotMessage, ...messages.slice(1)];
 }
+/**
+ * M3：剔除「未完成轮次」条目——metadata 记录的 (since, until] 区间（中断 run
+ * 的半截回复/工具结果）不进入 LLM 上下文，避免模型基于自己未跑完的半截成果
+ * 产生「我已改过了」的错位叙事。区间外条目原样保留。
+ * 两端点都必须存在于当前条目序列：端点因 /clear、压缩归档而消失时区间失效
+ * （整体不剔除）——绝不能把区间后新产生的正常轮次误伤。
+ */
+function excludeUnfinishedTurn(entries, sinceId, untilId) {
+    if (!sinceId || !untilId)
+        return entries;
+    const sinceIdx = entries.findIndex((e) => e.id === sinceId);
+    const untilIdx = entries.findIndex((e) => e.id === untilId);
+    if (sinceIdx < 0 || untilIdx <= sinceIdx)
+        return entries;
+    return entries.filter((_, i) => i <= sinceIdx || i > untilIdx);
+}
 /** Get the full session context: all entries + file snapshots.
  *  cwd 提供时刷新过期快照：文件磁盘 mtime 晚于快照记录 → 重读并升版本（P1-5）。 */
 async function getSessionContext(handle, sessionId, cwd) {
     if (cwd)
         await refreshStaleSnapshots(handle, sessionId, cwd);
-    const [entries, snapshots] = await Promise.all([
+    const [metaRows, entries, snapshots] = await Promise.all([
+        handle.db
+            .select({ metadata: sessions.metadata })
+            .from(sessions)
+            .where(eq(sessions.id, sessionId)),
         getEntries(handle, sessionId),
         getFileSnapshots(handle, sessionId),
     ]);
-    return { entries, snapshots };
+    const meta = (metaRows[0]?.metadata ?? {});
+    return {
+        entries: excludeUnfinishedTurn(entries, meta.unfinishedSinceEntryId, meta.unfinishedUntilEntryId),
+        snapshots,
+    };
 }
 /** 比对每个文件最新快照与磁盘 mtime，过期则重读并写入新版本。 */
 async function refreshStaleSnapshots(handle, sessionId, cwd) {

package/dist/session/import.d.ts

@@ -0,0 +1,44 @@
+import type { DB } from '../db/client.js';
+/** 导入消息的宽松形状（导出 JSON 反序列化后，字段可能缺失/类型漂移）。 */
+type ImportMessage = {
+    id?: string;
+    role?: string;
+    content?: unknown;
+    tokenCount?: number;
+    createdAt?: number | string;
+};
+/** 导入归档的宽松形状。 */
+type ImportArchive = {
+    id?: string;
+    compactionId?: string;
+    archiveType?: string;
+    originalEntries?: unknown;
+    fileSnapshots?: unknown;
+    summary?: string;
+    tokenCount?: number;
+    searchableText?: string;
+    createdAt?: number | string;
+};
+/**
+ * 导入会话数据（GET /sessions/:id/export 的逆操作）：
+ * 新建根会话（source 'web'），消息与归档**始终生成新 id**（保留 role/content/时间戳）——
+ * 导入副本可重复执行（同库内复制/恢复场景），不与原会话或既往导入冲突。
+ * 说明：导出仅含 tag='message' 的消息——compaction/steering 等特殊条目不随迁，
+ * 导入后会话显示完整原始消息流（上下文重建略长，但不丢内容）。
+ * P0：权限态（permissionMode/alwaysAllow）仅在调用方显式确认后随迁——
+ * metadata 由路由层过滤，未确认时不传入本函数。
+ */
+declare function importSessionData(handle: DB, opts: {
+    title: string;
+    projectId?: string;
+    messages: ImportMessage[];
+    archives: ImportArchive[];
+    /** 随迁的会话 metadata（仅权限态等安全字段，由调用方过滤）。 */
+    metadata?: Record<string, unknown>;
+}): Promise<{
+    sessionId: string;
+    messageCount: number;
+    archiveCount: number;
+}>;
+export type { ImportArchive, ImportMessage };
+export { importSessionData };

package/dist/session/import.js

@@ -0,0 +1,83 @@
+import { eq } from 'drizzle-orm';
+import { compactionArchives, sessionEntries, sessions } from '../db/schema.js';
+import { generateId } from '../shared/index.js';
+import { createSession } from './session.js';
+const VALID_ROLES = new Set([
+    'user',
+    'assistant',
+    'system',
+    'tool',
+]);
+function toDate(value) {
+    if (typeof value === 'number')
+        return new Date(value);
+    if (typeof value === 'string') {
+        const d = new Date(value);
+        if (!Number.isNaN(d.getTime()))
+            return d;
+    }
+    return new Date();
+}
+function sanitizeContent(content) {
+    if (Array.isArray(content)) {
+        // 只保留结构完整的分片；其余丢弃（导入宁少勿坏）
+        return content.filter((p) => p !== null && typeof p === 'object' && typeof p._tag === 'string');
+    }
+    if (typeof content === 'string' && content.length > 0) {
+        return [{ _tag: 'text', text: content }];
+    }
+    return [];
+}
+/**
+ * 导入会话数据（GET /sessions/:id/export 的逆操作）：
+ * 新建根会话（source 'web'），消息与归档**始终生成新 id**（保留 role/content/时间戳）——
+ * 导入副本可重复执行（同库内复制/恢复场景），不与原会话或既往导入冲突。
+ * 说明：导出仅含 tag='message' 的消息——compaction/steering 等特殊条目不随迁，
+ * 导入后会话显示完整原始消息流（上下文重建略长，但不丢内容）。
+ * P0：权限态（permissionMode/alwaysAllow）仅在调用方显式确认后随迁——
+ * metadata 由路由层过滤，未确认时不传入本函数。
+ */
+async function importSessionData(handle, opts) {
+    const session = await createSession(handle, opts.title, opts.projectId, undefined, 'web');
+    return handle.db.transaction(async (tx) => {
+        if (opts.metadata && Object.keys(opts.metadata).length > 0) {
+            await tx.update(sessions).set({ metadata: opts.metadata }).where(eq(sessions.id, session.id));
+        }
+        let messageCount = 0;
+        for (const m of opts.messages) {
+            const role = m.role;
+            if (typeof role !== 'string' || !VALID_ROLES.has(role))
+                continue;
+            await tx.insert(sessionEntries).values({
+                id: generateId(),
+                sessionId: session.id,
+                tag: 'message',
+                role,
+                content: sanitizeContent(m.content),
+                tokenCount: typeof m.tokenCount === 'number' ? m.tokenCount : 0,
+                createdAt: toDate(m.createdAt),
+            });
+            messageCount += 1;
+        }
+        let archiveCount = 0;
+        for (const a of opts.archives) {
+            await tx.insert(compactionArchives).values({
+                id: generateId(),
+                sessionId: session.id,
+                compactionId: typeof a.compactionId === 'string' && a.compactionId.length > 0
+                    ? a.compactionId
+                    : generateId(),
+                archiveType: typeof a.archiveType === 'string' ? a.archiveType : 'compaction',
+                originalEntries: Array.isArray(a.originalEntries) ? a.originalEntries : [],
+                fileSnapshots: Array.isArray(a.fileSnapshots) ? a.fileSnapshots : [],
+                summary: typeof a.summary === 'string' ? a.summary : '',
+                tokenCount: typeof a.tokenCount === 'number' ? a.tokenCount : null,
+                searchableText: typeof a.searchableText === 'string' ? a.searchableText : null,
+                createdAt: toDate(a.createdAt),
+            });
+            archiveCount += 1;
+        }
+        return { sessionId: session.id, messageCount, archiveCount };
+    });
+}
+export { importSessionData };

package/dist/session/index.d.ts

@@ -3,7 +3,7 @@ export { forkSession, getBranches, getTree } from './branch.js';
 export { buildCompactionPrompt, compactSession, extractHotFiles, findSafeCutPoint, } from './compaction.js';
 export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessage, } from './context.js';
 export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, } from './message.js';
-export { createSession, getLLMSegments, getSession, listDeletedSessions, listSessions, migrateLegacyDetails, purgeDeletedSessions, restoreSession, saveLLMSegments, segmentFingerprint, softDeleteSession, touchSession, updateSessionTitle, } from './session.js';
+export { consumeBudgetPauseMarker, createSession, emptyTrash, getLLMSegments, getSession, listDeletedSessions, listSessions, markBudgetPause, migrateLegacyDetails, permanentlyDeleteSession, purgeDeletedSessions, restoreSession, restoreSessionCore, saveLLMSegments, segmentFingerprint, softDeleteSession, TRASH_RETENTION_MS, touchSession, touchTrashSeen, updateSessionTitle, } from './session.js';
 export { checkFileSnapshot, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot, } from './snapshot.js';
 export { squashRecent } from './squash.js';
 export { estimateMessageTokens, estimateTokens } from './token.js';

package/dist/session/index.js

@@ -4,7 +4,7 @@ export { forkSession, getBranches, getTree } from './branch.js';
 export { buildCompactionPrompt, compactSession, extractHotFiles, findSafeCutPoint, } from './compaction.js';
 export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessage, } from './context.js';
 export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, } from './message.js';
-export { createSession, getLLMSegments, getSession, listDeletedSessions, listSessions, migrateLegacyDetails, purgeDeletedSessions, restoreSession, saveLLMSegments, segmentFingerprint, softDeleteSession, touchSession, updateSessionTitle, } from './session.js';
+export { consumeBudgetPauseMarker, createSession, emptyTrash, getLLMSegments, getSession, listDeletedSessions, listSessions, markBudgetPause, migrateLegacyDetails, permanentlyDeleteSession, purgeDeletedSessions, restoreSession, restoreSessionCore, saveLLMSegments, segmentFingerprint, softDeleteSession, TRASH_RETENTION_MS, touchSession, touchTrashSeen, updateSessionTitle, } from './session.js';
 export { checkFileSnapshot, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot, } from './snapshot.js';
 export { squashRecent } from './squash.js';
 export { estimateMessageTokens, estimateTokens } from './token.js';

package/dist/session/jobs.d.ts

@@ -0,0 +1,12 @@
+import type { DB } from '../db/client.js';
+/**
+ * 标记崩溃遗留的后台子 agent 任务并通知父会话（P2）。
+ *
+ * background task 在子 session 上写 lastRun.status='running'（subagent.ts），
+ * 完成后置 'completed'。进程崩溃时悬空任务永远停在 'running'，父会话收不到
+ * 完成通知（原实现仅内存 jobId，重启即丢）。启动时调用：
+ *  - 悬空任务 lastRun 置 'completed'（死任务不再显示 interrupted）；
+ *  - 合成一条 state="failed" 通知写入父会话（子 session 已挂 parentId）。
+ * 返回标记数量。
+ */
+export declare function markDeadBackgroundJobs(handle: DB): Promise<number>;

package/dist/session/jobs.js

@@ -0,0 +1,53 @@
+import { and, inArray, isNotNull, sql } from 'drizzle-orm';
+import { sessions } from '../db/schema.js';
+import { appendMessage } from './message.js';
+import { updateSessionLastRun } from './session.js';
+/**
+ * 标记崩溃遗留的后台子 agent 任务并通知父会话（P2）。
+ *
+ * background task 在子 session 上写 lastRun.status='running'（subagent.ts），
+ * 完成后置 'completed'。进程崩溃时悬空任务永远停在 'running'，父会话收不到
+ * 完成通知（原实现仅内存 jobId，重启即丢）。启动时调用：
+ *  - 悬空任务 lastRun 置 'completed'（死任务不再显示 interrupted）；
+ *  - 合成一条 state="failed" 通知写入父会话（子 session 已挂 parentId）。
+ * 返回标记数量。
+ */
+export async function markDeadBackgroundJobs(handle) {
+    const rows = await handle.db
+        .select({
+        id: sessions.id,
+        parentId: sessions.parentId,
+        agentType: sessions.agentType,
+    })
+        .from(sessions)
+        .where(and(isNotNull(sessions.agentType), isNotNull(sessions.parentId), sql `${sessions.metadata}->'lastRun'->>'status' = 'running'`));
+    // 父会话已入回收站的不再注入失败通知（否则向 60 天后将清除的会话写死消息）。
+    const parentIds = Array.from(new Set(rows.map((r) => r.parentId).filter((p) => !!p)));
+    const trashedParents = new Set();
+    if (parentIds.length > 0) {
+        const parents = await handle.db
+            .select({ id: sessions.id, deletedAt: sessions.deletedAt })
+            .from(sessions)
+            .where(inArray(sessions.id, parentIds));
+        for (const p of parents)
+            if (p.deletedAt)
+                trashedParents.add(p.id);
+    }
+    for (const row of rows) {
+        await updateSessionLastRun(handle, row.id, {
+            status: 'completed',
+            agentName: row.agentType ?? undefined,
+            startedAt: Date.now(),
+        });
+        if (row.parentId && !trashedParents.has(row.parentId)) {
+            const synthetic = `<task id="${row.id}" state="failed">\n<task_error>\n后台任务在服务重启前未完成，已标记为失败（可重新派发）\n</task_error>\n</task>`;
+            await appendMessage(handle, row.parentId, {
+                role: 'user',
+                content: [{ _tag: 'text', text: synthetic }],
+            }).catch(() => {
+                // 通知写入失败：任务已标记，父会话可能收不到失败提示——仅记录
+            });
+        }
+    }
+    return rows.length;
+}