c0de-agent 1.13.0 → 1.14.0

package/dist/session/archive.js

@@ -1,7 +1,7 @@
 import { and, desc, eq, ilike } from 'drizzle-orm';
 import { compactionArchives } from '../db/schema.js';
 import { generateId } from '../shared/index.js';
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+import { isUuid } from '../shared/utils/string.js';
 function toEpochMs(value) {
     if (value instanceof Date)
         return value.getTime();
@@ -42,9 +42,9 @@ function entryToSearchableText(entry) {
             case 'steering':
                 return part.text;
             case 'tool_call':
-                return `${part.tool}: ${JSON.stringify(part.input)}`;
+                return `${part.tool}: ${JSON.stringify(part.input ?? {})}`;
             case 'tool_result':
-                return JSON.stringify(part.output);
+                return JSON.stringify(part.output ?? {});
             default:
                 return '';
         }
@@ -71,7 +71,7 @@ async function archiveOriginalEntries(handle, sessionId, entries, archiveType, s
 /** Get an archive by id. Returns null for invalid or non-existent ids. */
 async function getArchive(handle, id) {
     // PGLite rejects non-UUID strings at query time; validate first.
-    if (!UUID_RE.test(id))
+    if (!isUuid(id))
         return null;
     const [row] = await handle.db
         .select()

package/dist/session/branch.d.ts

@@ -1,4 +1,5 @@
 import type { DB } from '../db/client.js';
+import type { HookRunner } from '../plugins/types.js';
 import type { Session, SessionTreeNode } from './types.js';
 /**
  * fork 分支点 messageIndex 越界（评审 NIT：客户端索引过期/分页 bug）。
@@ -9,13 +10,21 @@ declare class BranchPointOutOfRangeError extends Error {
 }
 /** Fork a session at a message index — copies all entries (messages + tool pairs)
  *  up to and including the branch point message, plus latest file snapshots. */
-declare function forkSession(handle: DB, sessionId: string, messageIndex: number): Promise<Session>;
+declare function forkSession(handle: DB, sessionId: string, messageIndex: number, hooks?: HookRunner): Promise<Session>;
 /** Get direct child sessions (branches) of a session. */
 declare function getBranches(handle: DB, sessionId: string): Promise<Session[]>;
 /** Build a full session tree from root sessions down.
  * 每层按 metadata.lastOpenedAt 降序（fallback updatedAt、createdAt）。
  * 排除软删除会话与临时 CLI 会话（print/workflow）；持久化 CLI 会话（--continue 续接）
  * 与 Web 会话同树可见（CLI/Web 同库不同视图 → 同库同视图）。
+ *
+ * 环防护 + 可见性兜底（P1）：parentId 成环数据（a↔b 互指/自引用，快照恢复会
+ * 保留环、手改 DB 亦可产生）的成员不可从任何根到达——根 = parentId 为 null，
+ * 环上成员父指针都在环内，不存在指向环外的边。朴素构建会让它们从会话树
+ * **静默消失**（列表看不到、无法打开、无法删除）。visited 保证每个会话恰好
+ * 出现一次（环在重复处断开），构建根后把未出现的成员按同一排序作为根补挂。
+ * 正常森林不受影响。与 restoreSessionCore 祖先链 / purgeDeletedSessions /
+ * recycleTree 的环守卫同口径。
  */
 declare function getTree(handle: DB): Promise<SessionTreeNode[]>;
 export { BranchPointOutOfRangeError, forkSession, getBranches, getTree };

package/dist/session/branch.js

@@ -14,9 +14,12 @@ class BranchPointOutOfRangeError extends Error {
         this.name = 'BranchPointOutOfRangeError';
     }
 }
-/** 把 SessionEntry 还原为 sessionEntries 原始行（fork 复制用）。 */
+/** 把 SessionEntry 还原为 sessionEntries 原始行（fork 复制用）。
+ *  createdAt 原样保留：丢弃它会让复制出的条目全部拿到事务 now()（同一毫秒），
+ *  分支会话内时间戳并列——顺序退化为物理行序，时间线显示也全部变成 fork 时刻。 */
 function entryToRow(e, sessionId) {
     const id = generateId();
+    const createdAt = new Date(e.createdAt);
     // Message 无 _tag（共享类型）；其余条目经 _tag 判别。
     if (!('_tag' in e)) {
         return {
@@ -26,6 +29,7 @@ function entryToRow(e, sessionId) {
             role: e.role,
             content: e.content,
             tokenCount: e.tokenCount,
+            createdAt,
         };
     }
     switch (e._tag) {
@@ -40,6 +44,7 @@ function entryToRow(e, sessionId) {
                     archiveId: e.archiveId,
                 },
                 tokenCount: e.tokenCount,
+                createdAt,
             };
         case 'squash':
             return {
@@ -52,6 +57,7 @@ function entryToRow(e, sessionId) {
                     archiveId: e.archiveId,
                 },
                 tokenCount: e.tokenCount,
+                createdAt,
             };
         case 'branch_summary':
             return {
@@ -59,14 +65,15 @@ function entryToRow(e, sessionId) {
                 sessionId,
                 tag: 'branch_summary',
                 content: { summary: e.summary, sourceSessionId: e.sourceSessionId },
+                createdAt,
             };
         case 'steering':
-            return { id, sessionId, tag: 'steering', content: { text: e.content } };
+            return { id, sessionId, tag: 'steering', content: { text: e.content }, createdAt };
     }
 }
 /** Fork a session at a message index — copies all entries (messages + tool pairs)
  *  up to and including the branch point message, plus latest file snapshots. */
-async function forkSession(handle, sessionId, messageIndex) {
+async function forkSession(handle, sessionId, messageIndex, hooks) {
     const source = await getSession(handle, sessionId);
     if (!source)
         throw new Error(`Session not found: ${sessionId}`);
@@ -166,6 +173,15 @@ async function forkSession(handle, sessionId, messageIndex) {
             throw new Error('Forked session not found after creation');
         return created;
     });
+    if (hooks) {
+        try {
+            // 事务提交后再广播（hook 处理器不做 DB 写回调，避免事务内嵌套 IO）
+            await hooks.fireHooks('session:fork', { source, fork: updated });
+        }
+        catch {
+            // 广播失败不阻断分支返回
+        }
+    }
     return updated;
 }
 /** Get direct child sessions (branches) of a session. */
@@ -201,6 +217,14 @@ function sessionUsage(session) {
  * 每层按 metadata.lastOpenedAt 降序（fallback updatedAt、createdAt）。
  * 排除软删除会话与临时 CLI 会话（print/workflow）；持久化 CLI 会话（--continue 续接）
  * 与 Web 会话同树可见（CLI/Web 同库不同视图 → 同库同视图）。
+ *
+ * 环防护 + 可见性兜底（P1）：parentId 成环数据（a↔b 互指/自引用，快照恢复会
+ * 保留环、手改 DB 亦可产生）的成员不可从任何根到达——根 = parentId 为 null，
+ * 环上成员父指针都在环内，不存在指向环外的边。朴素构建会让它们从会话树
+ * **静默消失**（列表看不到、无法打开、无法删除）。visited 保证每个会话恰好
+ * 出现一次（环在重复处断开），构建根后把未出现的成员按同一排序作为根补挂。
+ * 正常森林不受影响。与 restoreSessionCore 祖先链 / purgeDeletedSessions /
+ * recycleTree 的环守卫同口径。
  */
 async function getTree(handle) {
     const rows = await handle.db
@@ -208,22 +232,43 @@ async function getTree(handle) {
         .from(sessions)
         .where(and(isNull(sessions.deletedAt), webVisibleSessionCondition()));
     const byParent = new Map();
+    const all = [];
     for (const row of rows) {
         const session = rowToSession(row);
+        all.push(session);
         const list = byParent.get(session.parentId) ?? [];
         list.push(session);
         byParent.set(session.parentId, list);
     }
     // 排序键：lastOpenedAt > updatedAt > createdAt（均为 epoch ms）
     const sortKey = (s) => s.metadata.lastOpenedAt ?? s.updatedAt ?? s.createdAt ?? 0;
+    const visited = new Set();
     const build = (parentId) => (byParent.get(parentId) ?? [])
         .slice()
         .sort((a, b) => sortKey(b) - sortKey(a))
-        .map((session) => ({
-        session,
-        children: build(session.id),
-        usage: sessionUsage(session),
-    }));
-    return build(null);
+        .flatMap((session) => {
+        if (visited.has(session.id))
+            return [];
+        visited.add(session.id);
+        return [
+            {
+                session,
+                children: build(session.id),
+                usage: sessionUsage(session),
+            },
+        ];
+    });
+    const roots = build(null);
+    // 环成员（不可从根到达）：作为根补挂，环在重复处断开、节点不丢失。
+    // 前一个孤儿根的子树可能已把后续成员纳入（a↔b 环），visited 复查去重。
+    for (const orphan of all
+        .filter((s) => !visited.has(s.id))
+        .sort((a, b) => sortKey(b) - sortKey(a))) {
+        if (visited.has(orphan.id))
+            continue;
+        visited.add(orphan.id);
+        roots.push({ session: orphan, children: build(orphan.id), usage: sessionUsage(orphan) });
+    }
+    return roots;
 }
 export { BranchPointOutOfRangeError, forkSession, getBranches, getTree };

package/dist/session/compaction.d.ts

@@ -9,6 +9,11 @@ import type { CompactionConfig, CompactionResult, HotFile, Summarizer } from './
 declare function findSafeCutPoint(messages: Message[], preferredCut: number): number;
 /** Extract frequently-accessed files (read ≥ 2 times) from message history. */
 declare function extractHotFiles(messages: Message[]): HotFile[];
+/** 工具输出在压缩 prompt 中保留的最大字符数（参考 opencode）。 */
+export declare const TOOL_OUTPUT_MAX_CHARS = 2000;
+/** 截断超长字符串：head 60% + "[truncated]" + tail 40%，而非硬切。
+ *  切点经 headChars/tailChars 内收，绝不产出孤立代理码元。 */
+export declare function truncateToolOutput(s: string): string;
 /**
  * Build the LLM summarization prompt for a set of messages.
  *

package/dist/session/compaction.js

@@ -1,6 +1,7 @@
 import { generateId } from '../shared/index.js';
+import { headChars, tailChars } from '../shared/utils/string.js';
 import { archiveOriginalEntries } from './archive.js';
-import { deleteEntriesByIds, getEntries, getMessages, insertEntry } from './message.js';
+import { deleteEntriesByIds, getEntries, getMessages, insertEntry, summaryEntryTimestamp, } from './message.js';
 import { upsertFileSnapshot } from './snapshot.js';
 import { estimateMessageTokens, estimateTokens } from './token.js';
 /**
@@ -52,14 +53,19 @@ function extractHotFiles(messages) {
     return hot.sort((a, b) => b.accessCount - a.accessCount).slice(0, 10);
 }
 /** 工具输出在压缩 prompt 中保留的最大字符数（参考 opencode）。 */
-const TOOL_OUTPUT_MAX_CHARS = 2000;
-/** 截断超长字符串：head 60% + "[truncated]" + tail 40%，而非硬切。 */
-function truncateToolOutput(s) {
+export const TOOL_OUTPUT_MAX_CHARS = 2000;
+/** 截断标记本身计入 TOOL_OUTPUT_MAX_CHARS 预算（此前 head+tail 吃满 2000 后
+ *  追加 11 字符标记，输出 2011 超出上限）。 */
+const TOOL_OUTPUT_MARKER = '[truncated]';
+/** 截断超长字符串：head 60% + "[truncated]" + tail 40%，而非硬切。
+ *  切点经 headChars/tailChars 内收，绝不产出孤立代理码元。 */
+export function truncateToolOutput(s) {
     if (s.length <= TOOL_OUTPUT_MAX_CHARS)
         return s;
-    const head = Math.floor(TOOL_OUTPUT_MAX_CHARS * 0.6);
-    const tail = TOOL_OUTPUT_MAX_CHARS - head;
-    return `${s.slice(0, head)}[truncated]${s.slice(-tail)}`;
+    const budget = TOOL_OUTPUT_MAX_CHARS - TOOL_OUTPUT_MARKER.length;
+    const head = Math.floor(budget * 0.6);
+    const tail = budget - head;
+    return `${headChars(s, head)}${TOOL_OUTPUT_MARKER}${tailChars(s, tail)}`;
 }
 /** 序列化单个 content part：text/thinking 保持原样，tool 输出超长时截断。 */
 function serializePart(p) {
@@ -244,9 +250,8 @@ async function compactSession(handle, sessionId, summarizer, config) {
                 archiveId,
             },
             tokenCount: estimateTokens(summary),
-            // Position the summary at the first compacted message's timestamp so it
-            // sorts BEFORE the kept recent messages under createdAt-ascending order.
-            createdAt: compactMessages[0] ? new Date(compactMessages[0].createdAt) : new Date(),
+            // 定位在首个被压缩消息处（并列时间戳时再早 1ms），保证摘要排在保留尾部之前。
+            createdAt: summaryEntryTimestamp(compactMessages[0], keepMessages[0]),
         });
         return { archiveId, fileSnapshotIds };
     });

package/dist/session/context.d.ts

@@ -2,8 +2,12 @@ import type { DB } from '../db/client.js';
 import type { ChatMessage } from '../shared/types/llm.js';
 import type { Message } from '../shared/types/message.js';
 import type { FileSnapshot, SessionEntry } from './types.js';
-/** Convert a stored Message to a protocol-level ChatMessage for the LLM. */
-declare function messageToChatMessage(msg: Message): ChatMessage;
+/** Convert a stored Message to protocol-level ChatMessage(s) for the LLM.
+ *  多结果 tool 消息（同一条消息含多条 tool_result）展开为多条 tool 消息——
+ *  此前只取首个 result，其余结果的反馈永远到不了模型（模型会盲目重试
+ *  已完成/已失败的并行工具）。OpenAI 协议一条 tool 消息只能携带一个
+ *  tool_call_id，故展开是唯一正确映射。 */
+declare function messageToChatMessages(msg: Message): ChatMessage[];
 /** Convert all session entries (messages + special) to ChatMessage[] for the LLM. */
 declare function entriesToChatMessages(entries: SessionEntry[], snapshots: FileSnapshot[]): ChatMessage[];
 /** Inject file snapshot block after the first message (preserves cache prefix). */
@@ -14,4 +18,4 @@ declare function getSessionContext(handle: DB, sessionId: string, cwd?: string):
     entries: SessionEntry[];
     snapshots: FileSnapshot[];
 }>;
-export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessage };
+export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessages };

package/dist/session/context.js

@@ -74,8 +74,12 @@ function sanitizeToolPairs(messages) {
     }
     return result;
 }
-/** Convert a stored Message to a protocol-level ChatMessage for the LLM. */
-function messageToChatMessage(msg) {
+/** Convert a stored Message to protocol-level ChatMessage(s) for the LLM.
+ *  多结果 tool 消息（同一条消息含多条 tool_result）展开为多条 tool 消息——
+ *  此前只取首个 result，其余结果的反馈永远到不了模型（模型会盲目重试
+ *  已完成/已失败的并行工具）。OpenAI 协议一条 tool 消息只能携带一个
+ *  tool_call_id，故展开是唯一正确映射。 */
+function messageToChatMessages(msg) {
     const textParts = msg.content
         .filter((p) => p._tag === 'text' || p._tag === 'thinking')
         .map((p) => (p._tag === 'thinking' ? `<think>${p.text}</think>` : p.text))
@@ -85,8 +89,25 @@ function messageToChatMessage(msg) {
         .map((p) => ({
         id: p.id,
         name: p.tool,
-        arguments: JSON.stringify(p.input),
+        // 缺 input 的 tool_call（import 透传的漂移分片）：JSON.stringify(undefined)
+        // 返回 undefined，arguments 字段缺失的调用在协议适配层行为未定义——
+        // 保守序列化为空对象。
+        arguments: JSON.stringify(p.input ?? {}),
     }));
+    if (msg.role === 'tool') {
+        const toolResults = msg.content.filter((p) => p._tag === 'tool_result');
+        if (toolResults.length === 0) {
+            // 空 tool 消息：无 toolCallId，sanitizeToolPairs 会丢弃（同旧行为）
+            return [{ role: 'tool', content: textParts || '' }];
+        }
+        return toolResults.map((p) => ({
+            role: 'tool',
+            toolCallId: p.id,
+            // 缺 output 的 tool_result：JSON.stringify(undefined) 返回 undefined，
+            // content 字段缺失的 tool 消息在协议适配层行为未定义——保守序列化为空对象。
+            content: JSON.stringify(p.output === undefined ? {} : p.output),
+        }));
+    }
     const toolResultPart = msg.content.find((p) => p._tag === 'tool_result');
     const imageParts = msg.content.filter((p) => p._tag === 'image');
     // 含图片：构建多模态 content 数组（text 在前，image 在后）
@@ -102,28 +123,33 @@ function messageToChatMessage(msg) {
         const multimodal = { role: msg.role, content: parts };
         if (toolCalls.length > 0)
             multimodal.toolCalls = toolCalls;
-        return multimodal;
+        return [multimodal];
     }
     // 无图片：保持原纯字符串逻辑（零回归）
     const chat = {
         role: msg.role,
-        content: textParts || (toolResultPart ? JSON.stringify(toolResultPart.output) : ''),
+        content: textParts ||
+            (toolResultPart
+                ? JSON.stringify(toolResultPart.output === undefined ? {} : toolResultPart.output)
+                : ''),
     };
     if (toolCalls.length > 0) {
         chat.toolCalls = toolCalls;
     }
     if (toolResultPart && toolResultPart._tag === 'tool_result') {
         chat.toolCallId = toolResultPart.id;
-        chat.content = JSON.stringify(toolResultPart.output);
+        // 缺 output 的 tool_result：JSON.stringify(undefined) 返回 undefined，
+        // content 字段缺失的 tool 消息在协议适配层行为未定义——保守序列化为空对象。
+        chat.content = JSON.stringify(toolResultPart.output === undefined ? {} : toolResultPart.output);
     }
-    return chat;
+    return [chat];
 }
 /** Convert all session entries (messages + special) to ChatMessage[] for the LLM. */
 function entriesToChatMessages(entries, snapshots) {
     const messages = [];
     for (const entry of entries) {
         if (!('_tag' in entry)) {
-            messages.push(messageToChatMessage(entry));
+            messages.push(...messageToChatMessages(entry));
             continue;
         }
         switch (entry._tag) {
@@ -229,4 +255,4 @@ async function refreshStaleSnapshots(handle, sessionId, cwd) {
         await upsertFileSnapshot(handle, sessionId, s.filePath, content, st.mtimeMs);
     }
 }
-export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessage };
+export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessages };

package/dist/session/import.js

@@ -9,8 +9,11 @@ const VALID_ROLES = new Set([
     'tool',
 ]);
 function toDate(value) {
-    if (typeof value === 'number')
-        return new Date(value);
+    if (typeof value === 'number') {
+        // 非有限数值（JSON 1e999 → Infinity）会产出 Invalid Date，时间戳序列化
+        // 直接击穿插入事务（整单 500）。与字符串分支同口径：无法解析回退当前时间。
+        return Number.isFinite(value) ? new Date(value) : new Date();
+    }
     if (typeof value === 'string') {
         const d = new Date(value);
         if (!Number.isNaN(d.getTime()))
@@ -18,10 +21,45 @@ function toDate(value) {
     }
     return new Date();
 }
+/**
+ * 按 MessageContent 判别字段的形状校验每个分片。
+ * 此前只校验 `_tag` 是字符串：`{_tag:'text', text:123}` 等类型违规分片原样入库，
+ * 后续续聊在 estimateTokens(123) 处 TypeError（历史会话每次对话都 500），
+ * 且 token/protocol 层被迫对缺字段形状逐个打补丁。导入是未受信 JSON 的唯一
+ * 入库入口——在此收敛：结构违规的分片整体丢弃（宁少勿坏）。
+ */
+function isWellFormedPart(p) {
+    switch (p._tag) {
+        case 'text':
+        case 'thinking':
+        case 'steering':
+            return typeof p.text === 'string';
+        case 'tool_call':
+            return (typeof p.id === 'string' &&
+                typeof p.tool === 'string' &&
+                (p.input === undefined ||
+                    (typeof p.input === 'object' && p.input !== null && !Array.isArray(p.input))));
+        case 'tool_result':
+            return (typeof p.id === 'string' &&
+                typeof p.tool === 'string' &&
+                typeof p.output === 'object' &&
+                p.output !== null &&
+                !Array.isArray(p.output));
+        case 'image':
+            return typeof p.mediaType === 'string' && typeof p.data === 'string';
+        default:
+            // 未知分片类型：丢弃（宁少勿坏）
+            return false;
+    }
+}
 function sanitizeContent(content) {
     if (Array.isArray(content)) {
         // 只保留结构完整的分片；其余丢弃（导入宁少勿坏）
-        return content.filter((p) => p !== null && typeof p === 'object' && typeof p._tag === 'string');
+        return content.filter((p) => p !== null &&
+            typeof p === 'object' &&
+            !Array.isArray(p) &&
+            typeof p._tag === 'string' &&
+            isWellFormedPart(p));
     }
     if (typeof content === 'string' && content.length > 0) {
         return [{ _tag: 'text', text: content }];
@@ -44,18 +82,26 @@ async function importSessionData(handle, opts) {
             await tx.update(sessions).set({ metadata: opts.metadata }).where(eq(sessions.id, session.id));
         }
         let messageCount = 0;
+        let lastTs = 0;
         for (const m of opts.messages) {
             const role = m.role;
             if (typeof role !== 'string' || !VALID_ROLES.has(role))
                 continue;
+            // 时间戳严格递增（保持数组顺序）：载荷缺时间戳时 toDate 回退 now()，
+            // 整批消息会落在同一毫秒——并列时间戳让会话内顺序退化为物理行序，
+            // 任何删除+重插都会打乱消息顺序。
+            const createdAt = new Date(Math.max(toDate(m.createdAt).getTime(), lastTs + 1));
+            lastTs = createdAt.getTime();
             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),
+                // tokenCount 是 integer 列：非有限数值（JSON 1e999 → Infinity）会击穿
+                // 插入事务（整单 500）；非法值收敛为 0（未知）。
+                tokenCount: typeof m.tokenCount === 'number' && Number.isFinite(m.tokenCount) ? m.tokenCount : 0,
+                createdAt,
             });
             messageCount += 1;
         }
@@ -71,7 +117,8 @@ async function importSessionData(handle, opts) {
                 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,
+                // integer 列：与消息 tokenCount 同口径拒绝非有限数值（JSON 1e999）。
+                tokenCount: typeof a.tokenCount === 'number' && Number.isFinite(a.tokenCount) ? a.tokenCount : null,
                 searchableText: typeof a.searchableText === 'string' ? a.searchableText : null,
                 createdAt: toDate(a.createdAt),
             });

package/dist/session/index.d.ts

@@ -1,8 +1,8 @@
 export { archiveOriginalEntries, getArchive, getArchiveOriginalEntries, parseArchiveReference, resolveArchiveReference, searchArchives, } from './archive.js';
 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 { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessages, } from './context.js';
+export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, summaryEntryTimestamp, updateEntryContent, } from './message.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';

package/dist/session/index.js

@@ -2,8 +2,8 @@
 export { archiveOriginalEntries, getArchive, getArchiveOriginalEntries, parseArchiveReference, resolveArchiveReference, searchArchives, } from './archive.js';
 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 { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessages, } from './context.js';
+export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, summaryEntryTimestamp, updateEntryContent, } from './message.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';

package/dist/session/message.d.ts

@@ -1,7 +1,11 @@
 import type { DB } from '../db/client.js';
 import { sessionEntries } from '../db/schema.js';
-import type { Message } from '../shared/types/message.js';
+import type { Message, MessageContent } from '../shared/types/message.js';
 import type { MessageInput, SessionEntry } from './types.js';
+/** 摘要条目（compaction/squash）的时间戳：定位在首个被压缩消息处。
+ *  并列时间戳（fork 复制、跨机导入的历史数据）下必须再早 1ms——否则摘要落到
+ *  保留尾部之后，压缩语义反转（模型先看近期消息、再看「已压缩的历史」）。 */
+declare function summaryEntryTimestamp(firstCompacted?: Message, firstKept?: Message): Date;
 /** Append a message to a session. Returns the stored Message with generated id/timestamp. */
 declare function appendMessage(handle: DB, sessionId: string, input: MessageInput): Promise<Message>;
 /** Get messages for a session (tag='message' only), ordered chronologically. */
@@ -23,6 +27,11 @@ declare function deleteMessagesAfter(handle: DB, sessionId: string, messageIndex
 declare function getEntries(handle: DB, sessionId: string): Promise<SessionEntry[]>;
 /** Low-level: delete entries by id. */
 declare function deleteEntriesByIds(handle: DB, ids: string[]): Promise<void>;
-/** Low-level: insert a raw entry row (for compaction/squash/branch_summary/steering). */
+/** Low-level: insert a raw entry row (for compaction/squash/branch_summary/steering).
+ *  未显式给 createdAt 时取会话内单调递增时间戳（追加语义：排在全部已有条目之后）。 */
 declare function insertEntry(handle: DB, values: typeof sessionEntries.$inferInsert): Promise<typeof sessionEntries.$inferSelect>;
-export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, getSteeringAsMessages, insertEntry, };
+/** 就地改写条目内容（shake 替换区域用）。
+ *  刻意不走「删除 + 重插」：重插的行落到物理末尾，并列时间戳的会话里会把
+ *  被改写消息挪到时间线最后——内容替换不应改变条目位置。 */
+declare function updateEntryContent(handle: DB, id: string, content: MessageContent[], tokenCount: number): Promise<void>;
+export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, getSteeringAsMessages, insertEntry, summaryEntryTimestamp, updateEntryContent, };

package/dist/session/message.js

@@ -1,4 +1,4 @@
-import { and, asc, count, eq, inArray } from 'drizzle-orm';
+import { and, asc, count, eq, inArray, max } from 'drizzle-orm';
 import { sessionEntries } from '../db/schema.js';
 import { generateId } from '../shared/index.js';
 import { touchSession } from './session.js';
@@ -74,6 +74,32 @@ function rowToEntry(row) {
             return rowToMessage(row);
     }
 }
+/** 会话内单调递增的条目时间戳（逻辑时钟）。
+ *
+ *  createdAt 是会话内唯一的顺序判定键（getMessages/getEntries/压缩摘要定位/
+ * 工具对相邻性都按它排序），因此必须**严格递增**——并列时间戳会让顺序退化成
+ * 物理行序，任何「删除+重插」都会把条目挪到时间线末尾。
+ * 会话内已有条目的时间戳可能晚于当前时刻（跨机导入、时钟偏移、快照恢复），
+ * 此时直接用 now() 会让新条目排到已有条目之前，故取 max(now, 会话内最大 + 1ms)。 */
+async function nextEntryTimestamp(handle, sessionId) {
+    const [row] = await handle.db
+        .select({ latest: max(sessionEntries.createdAt) })
+        .from(sessionEntries)
+        .where(eq(sessionEntries.sessionId, sessionId));
+    const latestMs = row?.latest ? toEpochMs(row.latest) : 0;
+    return new Date(Math.max(Date.now(), latestMs + 1));
+}
+/** 摘要条目（compaction/squash）的时间戳：定位在首个被压缩消息处。
+ *  并列时间戳（fork 复制、跨机导入的历史数据）下必须再早 1ms——否则摘要落到
+ *  保留尾部之后，压缩语义反转（模型先看近期消息、再看「已压缩的历史」）。 */
+function summaryEntryTimestamp(firstCompacted, firstKept) {
+    if (!firstCompacted)
+        return new Date();
+    const base = firstCompacted.createdAt;
+    if (firstKept === undefined || firstKept.createdAt > base)
+        return new Date(base);
+    return new Date(firstKept.createdAt - 1);
+}
 /** Append a message to a session. Returns the stored Message with generated id/timestamp. */
 async function appendMessage(handle, sessionId, input) {
     const tokenCount = input.tokenCount ?? estimateMessageTokens(input.content);
@@ -86,6 +112,7 @@ async function appendMessage(handle, sessionId, input) {
         role: input.role,
         content: input.content,
         tokenCount,
+        createdAt: await nextEntryTimestamp(handle, sessionId),
     })
         .returning();
     await touchSession(handle, sessionId);
@@ -155,11 +182,24 @@ async function deleteEntriesByIds(handle, ids) {
         return;
     await handle.db.delete(sessionEntries).where(inArray(sessionEntries.id, ids));
 }
-/** Low-level: insert a raw entry row (for compaction/squash/branch_summary/steering). */
+/** Low-level: insert a raw entry row (for compaction/squash/branch_summary/steering).
+ *  未显式给 createdAt 时取会话内单调递增时间戳（追加语义：排在全部已有条目之后）。 */
 async function insertEntry(handle, values) {
-    const [row] = await handle.db.insert(sessionEntries).values(values).returning();
+    const rowValues = values.createdAt === undefined
+        ? { ...values, createdAt: await nextEntryTimestamp(handle, values.sessionId) }
+        : values;
+    const [row] = await handle.db.insert(sessionEntries).values(rowValues).returning();
     if (!row)
         throw new Error('Failed to insert entry');
     return row;
 }
-export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, getSteeringAsMessages, insertEntry, };
+/** 就地改写条目内容（shake 替换区域用）。
+ *  刻意不走「删除 + 重插」：重插的行落到物理末尾，并列时间戳的会话里会把
+ *  被改写消息挪到时间线最后——内容替换不应改变条目位置。 */
+async function updateEntryContent(handle, id, content, tokenCount) {
+    await handle.db
+        .update(sessionEntries)
+        .set({ content, tokenCount })
+        .where(eq(sessionEntries.id, id));
+}
+export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, getSteeringAsMessages, insertEntry, summaryEntryTimestamp, updateEntryContent, };

package/dist/session/session.d.ts

@@ -1,5 +1,6 @@
 import type { DB } from '../db/client.js';
 import { sessions } from '../db/schema.js';
+import type { HookRunner } from '../plugins/types.js';
 import type { LLMSegment } from '../shared/types/agent.js';
 import type { ChatTool } from '../shared/types/llm.js';
 import type { LastRun, Session, SessionMetadata } from '../shared/types/message.js';
@@ -12,7 +13,9 @@ parentId?: string,
 /** 会话工作目录（CLI 会话必填：Web 打开时 agent 工具在该目录执行，而非 serve cwd）。 */
 worktreePath?: string, 
 /** 初始 metadata（如工作流运行会话记录 workflowName，供中断恢复指引展示）。 */
-metadata?: Record<string, unknown>): Promise<Session>;
+metadata?: Record<string, unknown>, 
+/** 插件 hook runner：创建成功后广播 session:create（可选，纯广播不阻断）。 */
+hooks?: HookRunner): Promise<Session>;
 /**
  * Web 会话树可见性条件：web 会话（source 为 null/web）或「持久的 CLI 会话」。
  * 一次性 CLI print 会话与 CLI 来源的 workflow 会话是临时数据，隐藏；
@@ -118,7 +121,8 @@ export declare const TRASH_ABSOLUTE_MAX_MS: number;
  * 宽限期满才物理清除——杜绝「到期即静默物理清空」的数据丢失死角。
  */
 export declare const TRASH_PURGE_GRACE_MS: number;
-/** 清除结果：marked = 本次新标记进入宽限期的条目数；deleted = 本次物理清除数。 */
+/** 清除结果：marked = 本次新标记进入宽限期的条目数；deleted = 本次物理清除行数
+ *  （含随父行一并清除的后代——跨项目/未到期的子行无法在父行删除后幸存）。 */
 export type TrashPurgeResult = {
     marked: number;
     deleted: number;
@@ -127,7 +131,8 @@ export type TrashPurgeResult = {
  * 回收站两阶段清理（启动时与每日定时调用）：
  * 阶段一：进入保留期截止（首次看到 + 60 天）或绝对上限（删除 + 365 天，无论是否
  *   被看到）且未标记 → 标记 purgePendingAt（进入宽限期，可恢复）。
- * 阶段二：purgePendingAt 早于宽限截止 → 物理清除（子会话先于父，自引用 FK 要求）。
+ * 阶段二：purgePendingAt 早于宽限截止 → 物理清除（子会话先于父，自引用 FK 要求；
+ *   删除闭包含全部后代，未到期的子行随父行一并清除）。
  * 恢复后重删、尚未重新看到的会话按「首次看到 + 60 天」计（绝对上限兜底仍生效）。
  */
 declare function purgeDeletedSessions(handle: DB, retentionMs?: number, graceMs?: number): Promise<TrashPurgeResult>;
@@ -151,8 +156,9 @@ declare function purgeEmptySession(handle: DB, id: string): Promise<boolean>;
  * 返回删除数量。会话不存在或不在回收站 → 返回 0。
  */
 declare function permanentlyDeleteSession(handle: DB, id: string): Promise<number>;
-/** 清空回收站：物理删除所有已软删除会话（子先于父）。返回删除数量。
- *  projectId 提供时仅清空该项目（P1-7）。 */
+/** 清空回收站：物理删除所有已软删除会话（子先于父，连同其全部后代）。
+ *  projectId 提供时仅以该项目条目为根（P1-7）——后代闭包仍含其他项目的子行
+ *  （它们引用被删父行，必须同批删除）。返回删除数量。 */
 declare function emptyTrash(handle: DB, projectId?: string): Promise<number>;
 /**
  * 清理过期临时会话（P2 → P1 收紧：仅处理显式标记的临时会话）。