@armadra/agent 0.7.3 → 0.7.4

package/dist/modes/acp/acp-server.js

@@ -31,7 +31,7 @@ import { AcpEventMapper, permissionModes, toolKind, toolLocations, toolTitle, }
 import { msg } from "../../i18n/index.js";
 import { CONFIG_IDS, applyConfigOption, availableCommands, buildConfigOptions, prepareConfigOptions, } from "./acp-config.js";
 import { clientCapabilitiesOf } from "./acp-connection.js";
-import { PromptQueue, cancelledResult, pageSessions, sessionTitle, } from "./acp-sessions.js";
+import { PromptQueue, cancelledResult, pageSessions, promptWhenIdle, sessionTitle, } from "./acp-sessions.js";
 export const ACP_AGENT_CAPABILITIES = {
     loadSession: true,
     promptCapabilities: { image: true, audio: false, embeddedContext: true },
@@ -336,6 +336,7 @@ export class AcpServer {
     async prompt(params, signal) {
         const entry = this.entryOf(params);
         const { text, images } = promptOf(params["prompt"]);
+        let onAbort;
         const result = new Promise((resolve, reject) => {
             const job = {
                 sessionId: entry.id,
@@ -347,13 +348,22 @@ export class AcpServer {
             };
             // 客户端以 $/cancel_request 撤回：等价 session/cancel，答复由对等端改成 -32800。
             // 连接关闭（stdin 结束）也会 abort 这个 signal——那时不算撤回，已开始的运行照常跑完。
-            signal?.addEventListener("abort", () => {
+            onAbort = () => {
                 if (this.peer.isOpen)
                     this.cancelJob(job);
-            }, { once: true });
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
             this.queue.push(job);
         });
-        const answer = await result;
+        let answer;
+        try {
+            answer = await result;
+        }
+        finally {
+            // 有监听的组合信号（AbortSignal.any）被运行时强持有：不摘掉，job → 会话随之常驻（D2 L1）
+            if (onAbort !== undefined)
+                signal?.removeEventListener("abort", onAbort);
+        }
         if (signal?.aborted === true && this.peer.isOpen)
             throw new RpcError(RPC_ERRORS.requestCancelled, "session/prompt: request cancelled");
         return answer;
@@ -370,7 +380,7 @@ export class AcpServer {
         const before = session.getStats().tokens;
         let failure;
         try {
-            await session.prompt(job.text, job.images.length > 0 ? { images: job.images } : {});
+            await promptWhenIdle(session, job);
         }
         catch (error) {
             failure = error;

package/dist/modes/acp/acp-sessions.d.ts

@@ -78,3 +78,12 @@ export declare function decodeCursor(cursor: unknown): {
 };
 /** 一页会话（`cursor` 缺省从头）。 */
 export declare function pageSessions(items: readonly SessionListItem[], cursor: unknown, pageSize?: number): AcpListSessionsResult;
+/**
+ * 跑一个出队的提示（docs/memory-plan.md D4、§2.2，Issue #139）。[M-A]
+ *
+ * 后台子 Agent 的完成通知以 `followUp` 在会话空闲时开回合，不经 {@link PromptQueue}；那一回合在跑时
+ * 直接 `prompt` 会报 busy。这里先等它结束；与通知器竞速输了（等到空闲后它抢先开了回合）再等一轮。
+ * 不用 `streamingBehavior: "followUp"` 入队：`abort()` 不清队列，等待期间的 `session/cancel`
+ * 会让这条提示在之后的周期里冒出来。`job.cancelRequested`（cancel / close / 撤回）→ 不再发，直接返回。
+ */
+export declare function promptWhenIdle(session: AgentSessionImpl, job: PromptJob): Promise<void>;

package/dist/modes/acp/acp-sessions.js

@@ -8,6 +8,7 @@
  */
 import { RPC_ERRORS, } from "../../drivers/acp/types.js";
 import { RpcError } from "../../drivers/jsonrpc.js";
+import { AmaError } from "../../errors.js";
 import { msg } from "../../i18n/index.js";
 /** `session/list` 每页条数。 */
 export const LIST_PAGE_SIZE = 50;
@@ -155,3 +156,27 @@ export function pageSessions(items, cursor, pageSize = LIST_PAGE_SIZE) {
         ? { sessions, nextCursor: encodeCursor(last.updatedAt, last.sessionId) }
         : { sessions };
 }
+/**
+ * 跑一个出队的提示（docs/memory-plan.md D4、§2.2，Issue #139）。[M-A]
+ *
+ * 后台子 Agent 的完成通知以 `followUp` 在会话空闲时开回合，不经 {@link PromptQueue}；那一回合在跑时
+ * 直接 `prompt` 会报 busy。这里先等它结束；与通知器竞速输了（等到空闲后它抢先开了回合）再等一轮。
+ * 不用 `streamingBehavior: "followUp"` 入队：`abort()` 不清队列，等待期间的 `session/cancel`
+ * 会让这条提示在之后的周期里冒出来。`job.cancelRequested`（cancel / close / 撤回）→ 不再发，直接返回。
+ */
+export async function promptWhenIdle(session, job) {
+    for (;;) {
+        // 等周期而不是看 `state.isStreaming`：busy 以周期为准，周期的收尾阶段 isStreaming 已是 false
+        await session.waitForIdle();
+        if (job.cancelRequested)
+            return;
+        try {
+            await session.prompt(job.text, job.images.length > 0 ? { images: job.images } : {});
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof AmaError && error.code === "busy"))
+                throw error;
+        }
+    }
+}

package/dist/modes/context-report.js

@@ -10,7 +10,7 @@
  * 统计只读：取活动分支的投影（与 `getStats().contextTokens` 同一口径），不改请求体、不写条目。
  */
 import { AgentSessionImpl } from "../agent/session.js";
-import { DEFAULT_COMPACTION_SETTINGS, pendingPrefixMessage } from "../agent/session-compaction.js";
+import { DEFAULT_COMPACTION_SETTINGS, effectiveWindow, pendingPrefixMessage, } from "../agent/session-compaction.js";
 import { breakdownMessages, largestToolResults, } from "../compaction/breakdown.js";
 import { estimateContextTokens, estimateProjectedTokens, } from "../compaction/estimate.js";
 import { prunePolicy } from "../compaction/prune-tier.js";
@@ -48,7 +48,8 @@ export function contextSnapshot(session) {
         estimate = { ...estimate, tokens: stats.contextTokens };
     const window = stats.contextWindow;
     const reserve = compaction.reserveTokens ?? DEFAULT_COMPACTION_SETTINGS.reserveTokens;
-    const budget = window === undefined ? undefined : Math.max(0, window - reserve);
+    const soft = effectiveWindow(window, compaction);
+    const budget = soft === undefined ? undefined : Math.max(0, soft - reserve);
     const percent = window === undefined || window <= 0
         ? undefined
         : Math.min(100, Math.round((estimate.tokens / window) * 1000) / 10);

package/dist/modes/print/json-event.d.ts

@@ -4,13 +4,24 @@
  * - `message_update` 变成纯增量：去掉累计消息与 `partial`，附最新 `usage`；`done / error`
  *   保留最终 `message`。`tool_execution_end` 去掉 `result.fileChange`（[ACP-C0] 改前 / 改后全文只给
  *   ACP 映射用，不上 RPC / stream-json 线）。其余 `SessionEvent` 原样。
+ * - [M-G] `compact`（RPC 客户端声明 `compact_events`，docs/memory-plan.md D9）：`compactEvent()` 去掉
+ *   重复的大正文——`turn_end.toolResults[]` 每项只留 `{ toolCallId, toolName, isError, timestamp,
+ *   contentOmitted }`；`message_start` 与 `entry_appended`（`message` 条目）里的 toolResult / 带图片的 user
+ *   消息 `content` 换成 `""` 并加 `contentOmitted: true`。`message_end` 与 `tool_execution_end` 保持全量。
+ *   `stream-json` 不传 compact，输出不变。
  * - `toJsonLine()`：一行 JSON；Error 序列化为 `{ name, message }`，bigint 转字符串，
  *   U+2028 / U+2029 转义（部分 JSONL 客户端会把它们当换行）；图片 base64 不截断。
  */
 import type { SessionEvent } from "../../agent/types.js";
 import type { AssistantEvent } from "../../ai/types.js";
 import type { RpcEvent, WireAssistantEvent } from "../../rpc.js";
+export interface WireOptions {
+    /** [M-G] 客户端声明了 `compact_events`。 */
+    compact?: boolean;
+}
 export declare function toWireAssistantEvent(event: AssistantEvent): WireAssistantEvent;
-export declare function toWireEvent(event: SessionEvent): RpcEvent;
+/** [M-G] 精简事件：只改 turn_end / message_start / entry_appended，其余（含 message_end）原样。 */
+export declare function compactEvent(event: SessionEvent): SessionEvent;
+export declare function toWireEvent(input: SessionEvent, options?: WireOptions): RpcEvent;
 /** 一行 JSON（不含换行符）。 */
 export declare function toJsonLine(value: unknown): string;

package/dist/modes/print/json-event.js

@@ -4,6 +4,11 @@
  * - `message_update` 变成纯增量：去掉累计消息与 `partial`，附最新 `usage`；`done / error`
  *   保留最终 `message`。`tool_execution_end` 去掉 `result.fileChange`（[ACP-C0] 改前 / 改后全文只给
  *   ACP 映射用，不上 RPC / stream-json 线）。其余 `SessionEvent` 原样。
+ * - [M-G] `compact`（RPC 客户端声明 `compact_events`，docs/memory-plan.md D9）：`compactEvent()` 去掉
+ *   重复的大正文——`turn_end.toolResults[]` 每项只留 `{ toolCallId, toolName, isError, timestamp,
+ *   contentOmitted }`；`message_start` 与 `entry_appended`（`message` 条目）里的 toolResult / 带图片的 user
+ *   消息 `content` 换成 `""` 并加 `contentOmitted: true`。`message_end` 与 `tool_execution_end` 保持全量。
+ *   `stream-json` 不传 compact，输出不变。
  * - `toJsonLine()`：一行 JSON；Error 序列化为 `{ name, message }`，bigint 转字符串，
  *   U+2028 / U+2029 转义（部分 JSONL 客户端会把它们当换行）；图片 base64 不截断。
  */
@@ -13,7 +18,49 @@ export function toWireAssistantEvent(event) {
     const { partial: _partial, ...rest } = event;
     return rest;
 }
-export function toWireEvent(event) {
+/** toolResult 与带图片的 user 消息：正文换成 `""` 并标 `contentOmitted`；其它消息原样。 */
+function omitContent(message) {
+    const omit = message.role === "toolResult" ||
+        (message.role === "user" &&
+            Array.isArray(message.content) &&
+            message.content.some((block) => block.type === "image"));
+    return omit ? { ...message, content: "", contentOmitted: true } : message;
+}
+/** [M-G] 精简事件：只改 turn_end / message_start / entry_appended，其余（含 message_end）原样。 */
+export function compactEvent(event) {
+    switch (event.type) {
+        case "turn_end":
+            if (event.toolResults.length === 0)
+                return event;
+            return {
+                ...event,
+                // 线上形状（docs/rpc.md）不是完整的 ToolResultMessage：正文与 details 都不带
+                toolResults: event.toolResults.map(({ toolCallId, toolName, isError, timestamp }) => ({
+                    toolCallId,
+                    toolName,
+                    isError,
+                    timestamp,
+                    contentOmitted: true,
+                })),
+            };
+        case "message_start": {
+            const message = omitContent(event.message);
+            return message === event.message ? event : { ...event, message };
+        }
+        case "entry_appended": {
+            if (event.entry.type !== "message")
+                return event;
+            const message = omitContent(event.entry.message);
+            return message === event.entry.message
+                ? event
+                : { ...event, entry: { ...event.entry, message } };
+        }
+        default:
+            return event;
+    }
+}
+export function toWireEvent(input, options = {}) {
+    const event = options.compact === true ? compactEvent(input) : input;
     if (event.type === "tool_execution_end" && event.result.fileChange !== undefined) {
         const { fileChange: _fileChange, ...result } = event.result;
         return { ...event, result };

package/dist/modes/rpc/rpc-mode.d.ts

@@ -6,6 +6,7 @@
  * - 审批：客户端 `set_client_capabilities{capabilities:["approvals"]}` 之后才挂 UI broker；
  *   之前的 ask 无人作答 → deny。`permission_request` 带 `timeoutMs`，超时由会话 deny 并发
  *   `permission_resolved`。
+ * - [M-G] 声明 `compact_events` 之后的事件经 `toWireEvent(event, { compact: true })` 精简（json-event.ts）。
  * - 宿主 `ui.notify` → `{type:"notification", level, message}` 一行（stderr 同时一份）。
  * - stdin 关闭：撤下审批（之后的 ask 无人作答 → deny）、等在途命令与已开始的运行结束、
  *   应答写完 → 退出 0（会话由 runCli dispose）。`printf '{…prompt…}' | ama --mode rpc` 因此能拿到

package/dist/modes/rpc/rpc-mode.js

@@ -6,6 +6,7 @@
  * - 审批：客户端 `set_client_capabilities{capabilities:["approvals"]}` 之后才挂 UI broker；
  *   之前的 ask 无人作答 → deny。`permission_request` 带 `timeoutMs`，超时由会话 deny 并发
  *   `permission_resolved`。
+ * - [M-G] 声明 `compact_events` 之后的事件经 `toWireEvent(event, { compact: true })` 精简（json-event.ts）。
  * - 宿主 `ui.notify` → `{type:"notification", level, message}` 一行（stderr 同时一份）。
  * - stdin 关闭：撤下审批（之后的 ask 无人作答 → deny）、等在途命令与已开始的运行结束、
  *   应答写完 → 退出 0（会话由 runCli dispose）。`printf '{…prompt…}' | ama --mode rpc` 因此能拿到
@@ -24,7 +25,13 @@ import { cachedAgentInfos } from "../../agents/external.js";
 import { RpcApprovals, handlers } from "./commands.js";
 import { createLineReader, writeChunked } from "./jsonl.js";
 import { msg } from "../../i18n/index.js";
-export const RPC_CAPABILITIES = ["approvals", "images", "hooks", "plans"];
+export const RPC_CAPABILITIES = [
+    "approvals",
+    "images",
+    "hooks",
+    "plans",
+    "compact_events",
+];
 export async function runRpcMode(runtime, context, options = {}) {
     const stdin = options.stdin ?? process.stdin;
     const stdout = options.stdout ?? process.stdout;
@@ -34,7 +41,7 @@ export async function runRpcMode(runtime, context, options = {}) {
         writing = writing.then(() => writeChunked(stdout, line)).catch(() => undefined);
         return writing;
     };
-    const subscribe = (s) => s.subscribe((event) => void write(toWireEvent(event)));
+    const subscribe = (s) => s.subscribe((event) => void write(toWireEvent(event, { compact: ctx.capabilities.has("compact_events") })));
     let session = currentSession(runtime);
     let unsubscribe = subscribe(session);
     const approvals = new RpcApprovals();

package/dist/modes/session-report.d.ts

@@ -72,5 +72,5 @@ export declare function subscriptionRows(session: AgentSession, now?: number): K
 export declare function renderRows(rows: readonly KeyValueRow[], indent?: string): string[];
 export declare function describeCache(session: AgentSession, now?: number): string;
 export declare function describeSession(session: AgentSession, now?: number): string;
-/** `/cache fingerprint`：最近一次真实请求的前缀指纹（system / tools 哈希与模型）。 */
+/** `/cache fingerprint`：最近一次真实请求的前缀指纹（system / tools 哈希与模型；[ME-B] 再逐节列哈希）。 */
 export declare function describeFingerprint(session: AgentSession): string;

package/dist/modes/session-report.js

@@ -80,11 +80,13 @@ export function missReasonText(miss) {
         case "model_changed":
             return m.missModel;
         case "prefix_changed":
-            return miss.detail === "tools"
-                ? m.missTools
-                : miss.detail === "system"
-                    ? m.missSystem
-                    : m.missPrefix;
+            if (miss.detail === "tools")
+                return m.missTools;
+            if (miss.detail === "system")
+                return m.missSystem;
+            if (miss.detail?.startsWith("system:") === true)
+                return m.missSystemSections(miss.detail.slice("system:".length).replaceAll(",", ", "));
+            return m.missPrefix;
         case "evicted":
             return m.missEvicted;
     }
@@ -325,7 +327,7 @@ export function describeSession(session, now = Date.now()) {
         ...(external.length > 0 ? [m.externalTitle, ...renderRows(external, "  ")] : []),
     ].join("\n");
 }
-/** `/cache fingerprint`：最近一次真实请求的前缀指纹（system / tools 哈希与模型）。 */
+/** `/cache fingerprint`：最近一次真实请求的前缀指纹（system / tools 哈希与模型；[ME-B] 再逐节列哈希）。 */
 export function describeFingerprint(session) {
     const m = msg().report.session;
     if (!(session instanceof AgentSessionImpl))
@@ -338,6 +340,10 @@ export function describeFingerprint(session) {
         m.fingerprintTitle,
         ...renderRows([
             { key: "system", value: f.system },
+            ...Object.entries(f.sections ?? {}).map(([name, hash]) => ({
+                key: `  ${name}`,
+                value: hash,
+            })),
             { key: "tools", value: f.tools },
             { key: "model", value: f.model },
         ], "  "),

package/dist/rpc.d.ts

@@ -33,8 +33,11 @@ import type { TracePreview } from "./trace/preview.js";
 import type { Trace, TraceSubagentNode } from "./trace/types.js";
 export type { SessionEvent } from "./agent/types.js";
 export declare const RPC_PROTOCOL_VERSION: 1;
-/** `plans`（W5-C0）：客户端声明后计划审批交给客户端（`plan_proposed` → `plan_response`）。 */
-export type RpcCapability = "approvals" | "images" | "hooks" | "plans";
+/**
+ * `plans`（W5-C0）：客户端声明后计划审批交给客户端（`plan_proposed` → `plan_response`）。
+ * `compact_events`（M-G）：客户端声明后 turn_end / message_start / entry_appended 不重复带工具结果与图片正文。
+ */
+export type RpcCapability = "approvals" | "images" | "hooks" | "plans" | "compact_events";
 export interface RpcHello {
     type: "hello";
     protocolVersion: typeof RPC_PROTOCOL_VERSION;

package/dist/session/line-reader.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 会话文件的字节级按行读取（docs/memory-plan.md D6、§2.4）。[M-C0] 实现与单测；调用方由 [M-C] 接入
+ * （`store.ts readSessionLines`、`scan.ts forEachLine`、`list.ts`）。
+ *
+ * - fd + 一块复用的缓冲（缺省 64 KiB）顺序 `readSync`，以 `indexOf(0x0a)` 切行；跨块的残片挪到缓冲
+ *   开头续读，一行比缓冲还长时缓冲翻倍——每行不再分配，不生成全文字符串，也不 split 出整个数组；
+ * - 回调拿到的 `line` 不含 `\n` 与行尾的一个 `\r`，**只在回调期间有效**（可能是复用块的视图），
+ *   需要保留时自行拷贝或解码；空行照样回调（是否跳过由调用方决定）；
+ * - `index` 是物理行号（0 起，含空行）；`byteOffset` 是该行首字节在文件中的偏移（修复半行时
+ *   直接 `truncateSync(file, byteOffset)`）；`last` 为 true 表示这是**没有以 `\n` 结尾**的末行；
+ *   文件以 `\n` 结尾时不会多回调一个空的末行；
+ * - 回调返回 `false` 立即停止读盘并关闭 fd。
+ */
+/** 缺省块大小。 */
+export declare const LINE_CHUNK_BYTES: number;
+export interface LineVisit {
+    (line: Buffer, index: number, last: boolean, byteOffset: number): boolean | void;
+}
+/** 逐行访问 `file`（同步）；打不开时抛 `fs` 的原始错误。 */
+export declare function forEachLineSync(file: string, visit: LineVisit, chunkBytes?: number): void;
+/**
+ * ama 写的行：不解析、只解码行首就取出 type（与消息的 role），口径同 `scan.ts lineType`；
+ * 不是这种形状（或行首不足以判断 role）时 undefined，调用方退回 `JSON.parse`。
+ */
+export declare function lineTypeOf(line: Buffer): {
+    type: string;
+    role?: string;
+} | undefined;

package/dist/session/line-reader.js

@@ -0,0 +1,82 @@
+/**
+ * 会话文件的字节级按行读取（docs/memory-plan.md D6、§2.4）。[M-C0] 实现与单测；调用方由 [M-C] 接入
+ * （`store.ts readSessionLines`、`scan.ts forEachLine`、`list.ts`）。
+ *
+ * - fd + 一块复用的缓冲（缺省 64 KiB）顺序 `readSync`，以 `indexOf(0x0a)` 切行；跨块的残片挪到缓冲
+ *   开头续读，一行比缓冲还长时缓冲翻倍——每行不再分配，不生成全文字符串，也不 split 出整个数组；
+ * - 回调拿到的 `line` 不含 `\n` 与行尾的一个 `\r`，**只在回调期间有效**（可能是复用块的视图），
+ *   需要保留时自行拷贝或解码；空行照样回调（是否跳过由调用方决定）；
+ * - `index` 是物理行号（0 起，含空行）；`byteOffset` 是该行首字节在文件中的偏移（修复半行时
+ *   直接 `truncateSync(file, byteOffset)`）；`last` 为 true 表示这是**没有以 `\n` 结尾**的末行；
+ *   文件以 `\n` 结尾时不会多回调一个空的末行；
+ * - 回调返回 `false` 立即停止读盘并关闭 fd。
+ */
+import { closeSync, openSync, readSync } from "node:fs";
+import { lineType } from "./scan.js";
+/** 缺省块大小。 */
+export const LINE_CHUNK_BYTES = 64 * 1024;
+const LF = 0x0a;
+const CR = 0x0d;
+function stripCr(line) {
+    return line.length > 0 && line[line.length - 1] === CR ? line.subarray(0, -1) : line;
+}
+/** 逐行访问 `file`（同步）；打不开时抛 `fs` 的原始错误。 */
+export function forEachLineSync(file, visit, chunkBytes = LINE_CHUNK_BYTES) {
+    const fd = openSync(file, "r");
+    try {
+        // 一块复用的缓冲：未成行的残片挪到开头再续读；一行比缓冲还长时才翻倍（之后沿用）
+        let buf = Buffer.allocUnsafe(Math.max(1, Math.floor(chunkBytes)));
+        let start = 0; // 未成行数据在 buf 中的起点
+        let end = 0; // 有效数据的终点
+        let index = 0;
+        let lineStart = 0; // `start` 处对应的文件偏移
+        let position = 0;
+        for (;;) {
+            if (start > 0) {
+                buf.copyWithin(0, start, end);
+                end -= start;
+                start = 0;
+            }
+            if (end === buf.length) {
+                const grown = Buffer.allocUnsafe(buf.length * 2);
+                buf.copy(grown, 0, 0, end);
+                buf = grown;
+            }
+            const scanFrom = end; // 残片里已确认没有 \n
+            const read = readSync(fd, buf, end, buf.length - end, position);
+            if (read === 0)
+                break;
+            position += read;
+            end += read;
+            const view = buf.subarray(0, end);
+            for (let nl = view.indexOf(LF, scanFrom); nl >= 0; nl = view.indexOf(LF, start)) {
+                const line = view.subarray(start, nl);
+                const offset = lineStart;
+                lineStart += nl + 1 - start;
+                start = nl + 1;
+                if (visit(stripCr(line), index++, false, offset) === false)
+                    return;
+            }
+        }
+        if (end > start)
+            visit(stripCr(buf.subarray(start, end)), index, true, lineStart);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** 只解码这么多字节来判断行类型（`{"type":"message","message":{"role":"toolResult"` 约 48 字节）。 */
+const TYPE_HEAD_BYTES = 96;
+/**
+ * ama 写的行：不解析、只解码行首就取出 type（与消息的 role），口径同 `scan.ts lineType`；
+ * 不是这种形状（或行首不足以判断 role）时 undefined，调用方退回 `JSON.parse`。
+ */
+export function lineTypeOf(line) {
+    if (line.length <= TYPE_HEAD_BYTES)
+        return lineType(line.toString("utf8"));
+    const found = lineType(line.subarray(0, TYPE_HEAD_BYTES).toString("utf8"));
+    // role 可能被截断：宁可让调用方完整解析，也不给出与 `lineType` 不同的答案
+    if (found?.type === "message" && found.role === undefined)
+        return undefined;
+    return found;
+}

package/dist/session/list.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 会话列表（`SessionManager.list` 的实现）。[M-C] 按块逐行读（docs/memory-plan.md D6、§2.4）：
+ * 只解析头、第一条条目、`leaf` / `session_info` 行、要取 `firstPrompt` 的那一条 user 消息与末行；
+ * 其余 ama 写的行只看行首的 type / role（`lineTypeOf`），不生成全文字符串、不留条目对象。
+ *
+ * 口径与「`migrateSessionLines(readSessionLines(file).lines)` 再统计」一致：空行跳过、末尾半行忽略、
+ * 头必须是 `type: "session"` / `version === SESSION_FORMAT_VERSION` / id 与 cwd 为字符串、`leaf` 行不算
+ * 条目、重复的头与解析失败的中间行让整个文件跳过。差别只有一处：不解析的 ama 行不再逐条检查
+ * `id`（ama 写入的条目总有 id）；行尾不是 `}` 的（写到一半又被追加的坏行）仍会退回完整解析。
+ * 不经 `migrateSessionLines`——格式升到 v2 时要同时改这里（R6，见 migrate.ts）。
+ */
+import { type SessionListItem } from "./types.js";
+/** 只读列出目录下的会话（最新在前）；损坏的文件跳过。 */
+export declare function listSessionItems(dir: string): SessionListItem[];

package/dist/session/list.js

@@ -0,0 +1,150 @@
+/**
+ * 会话列表（`SessionManager.list` 的实现）。[M-C] 按块逐行读（docs/memory-plan.md D6、§2.4）：
+ * 只解析头、第一条条目、`leaf` / `session_info` 行、要取 `firstPrompt` 的那一条 user 消息与末行；
+ * 其余 ama 写的行只看行首的 type / role（`lineTypeOf`），不生成全文字符串、不留条目对象。
+ *
+ * 口径与「`migrateSessionLines(readSessionLines(file).lines)` 再统计」一致：空行跳过、末尾半行忽略、
+ * 头必须是 `type: "session"` / `version === SESSION_FORMAT_VERSION` / id 与 cwd 为字符串、`leaf` 行不算
+ * 条目、重复的头与解析失败的中间行让整个文件跳过。差别只有一处：不解析的 ama 行不再逐条检查
+ * `id`（ama 写入的条目总有 id）；行尾不是 `}` 的（写到一半又被追加的坏行）仍会退回完整解析。
+ * 不经 `migrateSessionLines`——格式升到 v2 时要同时改这里（R6，见 migrate.ts）。
+ */
+import { statSync } from "node:fs";
+import { forEachLineSync, lineTypeOf } from "./line-reader.js";
+import { isBlankLine, isSubagentSession, listSessionFiles } from "./store.js";
+import { SESSION_FORMAT_VERSION } from "./types.js";
+class SkipFile extends Error {
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function endsWithBrace(line) {
+    for (let i = line.length - 1; i >= 0; i--) {
+        const byte = line[i];
+        if (byte === 0x20 || (byte >= 0x09 && byte <= 0x0d))
+            continue;
+        return byte === 0x7d;
+    }
+    return false;
+}
+function promptText(content) {
+    if (typeof content === "string")
+        return content;
+    return content
+        .map((block) => (block.type === "text" ? block.text : ""))
+        .join("");
+}
+/** 统计一条已解析的行（头之后）；不合 v1 规则时抛 SkipFile。 */
+function tallyParsed(tally, line) {
+    if (isObject(line) && line["type"] === "leaf") {
+        const id = line["id"];
+        if (id !== null && typeof id !== "string")
+            throw new SkipFile();
+        return;
+    }
+    if (!isObject(line) || typeof line["id"] !== "string" || typeof line["type"] !== "string") {
+        throw new SkipFile();
+    }
+    if (line["type"] === "session")
+        throw new SkipFile();
+    if (!tally.hasFirst) {
+        tally.hasFirst = true;
+        tally.first = line;
+    }
+    if (line["type"] === "session_info" && line["name"] !== undefined) {
+        tally.name = line["name"];
+    }
+    if (line["type"] !== "message")
+        return;
+    const message = line["message"];
+    if (message.role === "system")
+        return;
+    tally.messageCount++;
+    if (tally.firstPrompt === undefined && message.role === "user") {
+        tally.firstPrompt = promptText(message.content);
+    }
+}
+function parseHeader(line) {
+    if (!isObject(line) || line["type"] !== "session")
+        throw new SkipFile();
+    if (line["version"] !== SESSION_FORMAT_VERSION)
+        throw new SkipFile();
+    if (typeof line["id"] !== "string" || typeof line["cwd"] !== "string")
+        throw new SkipFile();
+    return line;
+}
+/** 不解析就能统计的 ama 行：已过第一条条目、类型确定、行尾完整，且不需要读出内容。 */
+function tallyByType(tally, line, firstPromptTaken) {
+    if (!tally.hasFirst || !endsWithBrace(line))
+        return false;
+    const kind = lineTypeOf(line);
+    if (kind === undefined)
+        return false;
+    if (kind.type === "leaf" || kind.type === "session_info" || kind.type === "session")
+        return false;
+    if (kind.type !== "message")
+        return true;
+    if (kind.role === undefined)
+        return false;
+    if (kind.role === "system")
+        return true;
+    if (kind.role === "user" && !firstPromptTaken)
+        return false;
+    tally.messageCount++;
+    return true;
+}
+function tallyFile(file) {
+    const tally = { hasFirst: false, messageCount: 0 };
+    forEachLineSync(file, (buf, _index, last) => {
+        if (isBlankLine(buf))
+            return;
+        if (tally.header !== undefined && !last) {
+            if (tallyByType(tally, buf, tally.firstPrompt !== undefined))
+                return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(buf.toString("utf8"));
+        }
+        catch {
+            if (last)
+                return false; // 末尾半行：与 readSessionLines 一样忽略
+            throw new SkipFile();
+        }
+        if (tally.header === undefined)
+            tally.header = parseHeader(parsed);
+        else
+            tallyParsed(tally, parsed);
+    });
+    return tally;
+}
+/** 只读列出目录下的会话（最新在前）；损坏的文件跳过。 */
+export function listSessionItems(dir) {
+    const items = [];
+    for (const file of listSessionFiles(dir)) {
+        try {
+            const { header, first, name, firstPrompt, messageCount } = tallyFile(file);
+            if (header === undefined)
+                continue;
+            const item = {
+                id: header.id,
+                file,
+                cwd: header.cwd,
+                createdAt: header.timestamp,
+                modifiedAt: statSync(file).mtime.toISOString(),
+                messageCount,
+            };
+            if (name !== undefined)
+                item.name = name;
+            if (isSubagentSession(header, first))
+                item.subagent = true;
+            if (firstPrompt !== undefined)
+                item.firstPrompt = firstPrompt.slice(0, 200);
+            items.push(item);
+        }
+        catch {
+            // 损坏 / 不可读：列表里跳过（sessions show 会给出具体错误）
+        }
+    }
+    return items;
+}

package/dist/session/manager.d.ts

@@ -7,8 +7,9 @@
  * - `open(file)`：读文件（修复末尾半行）、校验版本、加锁；叶子 = 文件中最后一条条目，
  *   若其后还有 `leaf` 行（`/tree` 换叶子落盘，第三波 A7）则取最后一条 leaf 行。
  * - `setLeaf(id)`：已落盘时追加一行 `leaf{id, timestamp}`；延迟会话在 `flush()` 时补写。
- * - `fork(entryId)`：复制 root → entryId 的分支到新文件（头的 parentSession 指回本文件），
- *   不复制 leaf 行。
+ * - `fork(entryId, { head })`：复制 root → entryId 的分支到新文件（头的 parentSession 指回本文件），
+ *   不复制 leaf 行；给了 `head` 时它成为新根条目，复制的首条重挂到它下面（fork 子会话的 ama.task）；
+ *   `cwd` 缺省同本会话（[ME-A] 隔离的 fork 子会话传 worktree）。
  * - `close()`：释放锁；之后的 append 抛错。
  */
 import type { SessionEntry, SessionEntryInput, SessionHeader, SessionListItem, SessionManagerApi, SessionTreeNode } from "./types.js";
@@ -59,7 +60,10 @@ export declare class SessionManager implements SessionManagerApi {
     getTree(): SessionTreeNode[];
     name(): string | undefined;
     setName(name: string): void;
-    fork(entryId: string): SessionManager;
+    fork(entryId: string, forkOptions?: {
+        head?: SessionEntryInput;
+        cwd?: string;
+    }): SessionManager;
     /** 延迟会话：建文件、写头与缓存条目、加锁。返回文件路径（内存会话为 undefined）。幂等。 */
     flush(): string | undefined;
     isPersisted(): boolean;