@armadra/agent 0.7.4 → 0.7.6

package/dist/checkpoints/shadow-git.d.ts

@@ -16,8 +16,10 @@
 export declare const SHADOW_DIR = "shadow";
 /** cwd 下（不含忽略的）文件数上限，超出本会话降级为 tools。 */
 export declare const SHADOW_MAX_FILES = 20000;
-/** 单次快照耗时上限（毫秒），超出本会话降级为 tools。 */
+/** 单次快照耗时上限（毫秒），连续 `SHADOW_SLOW_STREAK` 次超出本会话降级为 tools。 */
 export declare const SHADOW_MAX_SNAPSHOT_MS = 3000;
+/** 连续这么多次快照超时才降级（首次快照不计）。 */
+export declare const SHADOW_SLOW_STREAK = 2;
 export declare function shadowRoot(dataDir: string): string;
 /** cwd 对应的影子仓库目录。 */
 export declare function shadowRepoDir(dataDir: string, cwd: string): string;
@@ -73,6 +75,8 @@ export declare class ShadowRepo {
     private readonly indexFile;
     private initialized;
     private counted;
+    /** 连续超时的快照数（首次快照不计），到 `SHADOW_SLOW_STREAK` 才降级。 */
+    private slowStreak;
     constructor(dataDir: string, cwd: string, options?: ShadowGitOptions);
     private now;
     private env;

package/dist/checkpoints/shadow-git.js

@@ -23,8 +23,10 @@ import { msg } from "../i18n/index.js";
 export const SHADOW_DIR = "shadow";
 /** cwd 下（不含忽略的）文件数上限，超出本会话降级为 tools。 */
 export const SHADOW_MAX_FILES = 20_000;
-/** 单次快照耗时上限（毫秒），超出本会话降级为 tools。 */
+/** 单次快照耗时上限（毫秒），连续 `SHADOW_SLOW_STREAK` 次超出本会话降级为 tools。 */
 export const SHADOW_MAX_SNAPSHOT_MS = 3_000;
+/** 连续这么多次快照超时才降级（首次快照不计）。 */
+export const SHADOW_SLOW_STREAK = 2;
 /** 单个 git 进程的硬上限，防止卡死。 */
 const GIT_TIMEOUT_MS = 60_000;
 /** 本地配置的版本；改了配置项就加一，旧仓库会补写。 */
@@ -85,6 +87,8 @@ export class ShadowRepo {
     indexFile;
     initialized;
     counted = false;
+    /** 连续超时的快照数（首次快照不计），到 `SHADOW_SLOW_STREAK` 才降级。 */
+    slowStreak = 0;
     constructor(dataDir, cwd, options = {}) {
         this.cwd = resolve(cwd);
         this.dir = shadowRepoDir(dataDir, this.cwd);
@@ -207,6 +211,8 @@ export class ShadowRepo {
             await this.init();
             // 计时不含一次性的建仓与本地配置（十来个 git 子进程，Windows 上可达数秒），只量快照本身
             const started = this.now();
+            // 首次快照要把整个工作区读进索引，天然偏慢，不计入超时
+            const first = !this.counted;
             await this.writeExcludes();
             if (!this.counted) {
                 const out = await this.run([
@@ -233,7 +239,10 @@ export class ShadowRepo {
                 args.push("-p", parent);
             const commit = await this.text(args);
             const elapsed = this.now() - started;
-            if (elapsed > this.maxSnapshotMs) {
+            if (first)
+                return { commit };
+            this.slowStreak = elapsed > this.maxSnapshotMs ? this.slowStreak + 1 : 0;
+            if (this.slowStreak >= SHADOW_SLOW_STREAK) {
                 return {
                     commit,
                     degrade: {

package/dist/cli/bootstrap.js

@@ -76,7 +76,8 @@ export async function bootstrap(argsIn, deps, io) {
         request = { kind: "resume", id };
     }
     const sessionRequest = request;
-    const sessionManager = await step(ExitCode.Session, m().steps.session, () => deps.sessions.open(sessionRequest, { sessionDir: paths.sessionDir, cwd: paths.cwd }));
+    // [#165] 会话替换后跟随当前会话（闭包只经它取，启动会话的 manager 不被常驻）
+    let sessionManager = await step(ExitCode.Session, m().steps.session, () => deps.sessions.open(sessionRequest, { sessionDir: paths.sessionDir, cwd: paths.cwd }));
     let sessionCwd = sessionManager.cwd;
     if (!existsSync(sessionCwd)) {
         const replacement = interactive ? await deps.ui?.askCwd?.(sessionCwd) : undefined;
@@ -281,6 +282,8 @@ export async function bootstrap(argsIn, deps, io) {
             uiBroker: () => uiBroker,
             onSessionReplaced: (next) => {
                 session = next;
+                sessionManager = next.manager ?? sessionManager;
+                assembly.sessionManager = sessionManager;
             },
             sessionStartContext: () => sessionStartContext,
             unattended,
@@ -302,7 +305,7 @@ export async function bootstrap(argsIn, deps, io) {
         if (Object.keys(overrides).length > 0)
             assembly.overrides = overrides;
         session = await step(ExitCode.RuntimeError, m().steps.assembly, () => deps.session.create(assembly));
-        const active = session;
+        const active = session; // 只同步使用：闭包捕获它会让启动会话常驻（#165）
         let disposed;
         shutdown = (reason) => {
             disposed ??= (async () => {
@@ -310,7 +313,7 @@ export async function bootstrap(argsIn, deps, io) {
                 await hooks.run("SessionEnd", { reason }).catch(() => undefined);
                 await disposeHost(host, (e) => warn(m().hostDisposeFailed(String(e))));
                 // 会话被替换过时 dispose 当前那个（旧会话由替换方负责）
-                await (session ?? active).dispose();
+                await session?.dispose();
             })();
             return disposed;
         };
@@ -339,8 +342,13 @@ export async function bootstrap(argsIn, deps, io) {
             providers,
             model,
             thinkingLevel,
-            sessionManager,
-            session: active,
+            // [#165] 跟随当前会话（ACP 关掉启动会话后它可被回收）
+            get sessionManager() {
+                return sessionManager;
+            },
+            get session() {
+                return session;
+            },
             hooks,
             host,
             permission,

package/dist/cli/compose-providers.d.ts

@@ -14,6 +14,7 @@
  *   `originator` 头；OAuth 刷新拿到 `auth.chatgpt` 配置与同一份 env。
  * - 发现缓存（`<dataDir>/models/discovered/<provider>.json`）并入模型表为空的供应商（discovered-cache.ts）；
  *   chatgpt 的缓存 flavor 与当前登录不符时视为过期、不并入。
+ * - max_tokens 上限缓存（`<dataDir>/models/max-tokens-caps.json`，30 天）载回进程内的表并订阅写回（#152）。
  */
 import type { ApiRegistry } from "../ai/apis/api.js";
 import { ProviderRegistry } from "../ai/providers/registry.js";

package/dist/cli/compose-providers.js

@@ -14,10 +14,12 @@
  *   `originator` 头；OAuth 刷新拿到 `auth.chatgpt` 配置与同一份 env。
  * - 发现缓存（`<dataDir>/models/discovered/<provider>.json`）并入模型表为空的供应商（discovered-cache.ts）；
  *   chatgpt 的缓存 flavor 与当前登录不符时视为过期、不并入。
+ * - max_tokens 上限缓存（`<dataDir>/models/max-tokens-caps.json`，30 天）载回进程内的表并订阅写回（#152）。
  */
 import { loadModelsDevIndex } from "../ai/providers/models-dev-cache.js";
 import { ProviderRegistry, discoverLocalModels } from "../ai/providers/registry.js";
 import { mergeDiscoveredModels } from "../ai/providers/discovered-cache.js";
+import { attachMaxTokensCache } from "../ai/providers/max-tokens-cache.js";
 import { lazyIndex } from "../ai/providers/enrich.js";
 import { readOAuthEntry } from "../auth/oauth/token-store.js";
 import { CHATGPT_BASE_URLS, CHATGPT_PROVIDER_ID } from "../auth/chatgpt/presets.js";
@@ -110,6 +112,7 @@ export async function buildProviderRegistry(input, options = {}) {
     }
     // 发现缓存（`ama auth login chatgpt` / `ama models discover chatgpt`）并入模型表为空的供应商
     if (dataDir !== undefined) {
+        attachMaxTokensCache(dataDir);
         const flavor = readOAuthEntry(input.authFile, CHATGPT_PROVIDER_ID)?.flavor;
         mergeDiscoveredModels(registry, dataDir, lazyIndex(() => loadModelsDevIndex(dataDir)), (id) => (id === CHATGPT_PROVIDER_ID ? flavor : undefined));
     }

package/dist/cli/compose-store.d.ts

@@ -6,16 +6,19 @@
  * - `resume{id}` / `fork{id}`：先在本目录、再在全部子目录里按 id 或唯一前缀找文件；找不到 →
  *   `session_not_found`，前缀不唯一 → `invalid_arguments` 并列出候选；
  * - `session-id{id}`：找到则打开，否则以该 id 新建；
- * - `fork{id}`：打开后从叶子复制出新文件，原会话立即关闭（释放锁）。
+ * - `fork{id}`：打开后从叶子复制出新文件，原会话立即关闭（释放锁）；源会话不属于任何 AgentSession，
+ *   它的告警（图片读不回，#183）显式交给 `context.log`。
  */
 import { SessionManager } from "../session/manager.js";
 import type { SessionListItem } from "../session/types.js";
+import type { LogFn } from "./compose-session.js";
 import type { RuntimeDeps, SessionRequest } from "./deps.js";
 /** 按 id / 唯一前缀找会话文件；本 cwd 目录优先。 */
 export declare function findSessionFile(root: string, id: string, cwd?: string): string | undefined;
 export declare function openSession(request: SessionRequest, context: {
     sessionDir: string;
     cwd: string;
+    log?: LogFn | undefined;
 }): SessionManager;
 /** 列会话（最新在前）；子 Agent 会话缺省跳过，`includeSubagents` 时保留（带 `subagent` 标记）。 */
 export declare function listSessions(context: {
@@ -23,4 +26,5 @@ export declare function listSessions(context: {
     cwd?: string;
     includeSubagents?: boolean;
 }): SessionListItem[];
-export declare function createSessionStore(): RuntimeDeps["sessions"];
+/** `log`：`--fork` 源会话的告警出口（通常是会话的 `options.log`）。 */
+export declare function createSessionStore(log?: LogFn): RuntimeDeps["sessions"];

package/dist/cli/compose-store.js

@@ -6,7 +6,8 @@
  * - `resume{id}` / `fork{id}`：先在本目录、再在全部子目录里按 id 或唯一前缀找文件；找不到 →
  *   `session_not_found`，前缀不唯一 → `invalid_arguments` 并列出候选；
  * - `session-id{id}`：找到则打开，否则以该 id 新建；
- * - `fork{id}`：打开后从叶子复制出新文件，原会话立即关闭（释放锁）。
+ * - `fork{id}`：打开后从叶子复制出新文件，原会话立即关闭（释放锁）；源会话不属于任何 AgentSession，
+ *   它的告警（图片读不回，#183）显式交给 `context.log`。
  */
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
@@ -81,7 +82,9 @@ export function openSession(request, context) {
                 : SessionManager.open(file);
         }
         case "fork": {
-            const source = SessionManager.open(requireFile(root, request.id, cwd));
+            const source = SessionManager.open(requireFile(root, request.id, cwd), {
+                warn: (message) => context.log?.("warn", message),
+            });
             try {
                 const leaf = source.leafId();
                 if (leaf === null)
@@ -104,9 +107,10 @@ export function listSessions(context) {
         .filter((item) => context.includeSubagents === true || item.subagent !== true)
         .sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
 }
-export function createSessionStore() {
+/** `log`：`--fork` 源会话的告警出口（通常是会话的 `options.log`）。 */
+export function createSessionStore(log) {
     return {
-        open: (request, context) => openSession(request, context),
+        open: (request, context) => openSession(request, { ...context, log }),
         list: async (context) => listSessions(context),
         show: async (id, context) => {
             const file = requireFile(context.sessionDir, id);

package/dist/cli/compose.js

@@ -40,7 +40,7 @@ import { builtinTools } from "../tools/registry.js";
 import { MEMORY_TOOL, createMemoryTool } from "../memory/tool.js";
 import { takeCodemodeNotice } from "./codemode-notice.js";
 import { buildProviderRegistry } from "./compose-providers.js";
-import { composeSession, emptyComposeState, } from "./compose-session.js";
+import { composeSession, emptyComposeState, stderrLog, } from "./compose-session.js";
 import { createSessionStore } from "./compose-store.js";
 import { defaultSendUser } from "./startup-steps.js";
 import { imageFitOptionsFor } from "../modes/image-input.js";
@@ -211,7 +211,7 @@ export function createRuntimeDeps(options = {}) {
                 return registry;
             },
         },
-        sessions: createSessionStore(),
+        sessions: createSessionStore(options.log ?? stderrLog()),
         tools: { create: (input) => createTools(input, options, state) },
         permissions: {
             create: (input) => new PermissionPipeline({

package/dist/cli/deps.d.ts

@@ -107,7 +107,7 @@ export interface SessionAssembly {
     /**
      * 模式层把当前会话换成另一个（`/new`、`/resume`、`/fork`、RPC `switch_session`）后调用：
      * bootstrap 让 HostApi.session.*、宿主 sendUser、Hook 公共字段与退出时的 dispose 跟随 `next`。
-     * 旧会话由调用方自行 dispose；`Runtime.session` 仍指初始会话。
+     * 旧会话由调用方自行 dispose；`Runtime.session` / `sessionManager` 也随之指向 `next`（#165）。
      */
     onSessionReplaced(next: AgentSession): void;
     /** SessionStart Hook 的 additionalContext（系统提示 hooks 节）；首次装配系统提示时读取。 */

package/dist/config/json-schema.js

@@ -161,6 +161,7 @@ function w5Sections() {
             background: oneOf(SUBAGENT_BACKGROUND_MODES),
             autoBackgroundAfterMs: num(0),
             retainSessions: num(0),
+            forkMaxContextRatio: num(0.05, 0.95),
         }),
         models: object({ aliases: object({ fast: str(), strong: str() }), enabled: strings }),
         fallbackModel: str(),

package/dist/config/key-docs.js

@@ -65,6 +65,7 @@ const IMPLICIT_DEFAULTS = {
         background: "auto",
         autoBackgroundAfterMs: 0,
         retainSessions: 4,
+        forkMaxContextRatio: 0.5,
     },
     reminders: { todo: true, fileChanges: true, contextPressure: true, budget: true },
     todo: { reminder: 10 },

package/dist/config/schema-w5.js

@@ -90,6 +90,7 @@ export function validateConfigW5(c, config) {
         "background",
         "autoBackgroundAfterMs",
         "retainSessions",
+        "forkMaxContextRatio",
     ], (s, p) => {
         c.number(s, "maxConcurrent", p, 1, 64);
         c.number(s, "maxPending", p, 0, 1024);
@@ -97,6 +98,7 @@ export function validateConfigW5(c, config) {
         c.oneOf(s, "background", p, SUBAGENT_BACKGROUND_MODES);
         c.number(s, "autoBackgroundAfterMs", p, 0);
         c.number(s, "retainSessions", p, 0);
+        c.number(s, "forkMaxContextRatio", p, 0.05, 0.95);
     });
     checkSection(c, config, "models", ["aliases", "enabled"], (s, p) => {
         c.stringArray(s, "enabled", p);

package/dist/config/settings-registry.js

@@ -101,6 +101,7 @@ const ROWS = [
     row("subagents.maxConcurrent", "agents", "nextSession", "deny"),
     row("subagents.maxPending", "agents", "nextSession", "deny"),
     row("subagents.retainSessions", "agents", "nextSession", "deny"),
+    row("subagents.forkMaxContextRatio", "agents", "nextSession", "deny"),
     // [W7-B2] 改 task 工具描述（缺省后台 / 前台两种文案），故 prefix
     row("subagents.background", "agents", "restart", "any", { prefix: true }),
     row("subagents.autoBackgroundAfterMs", "agents", "restart", "any"),

package/dist/config/types-w5.d.ts

@@ -79,6 +79,11 @@ export interface SubagentsConfig {
     autoBackgroundAfterMs?: number;
     /** [M-F] 已结束子会话保留在内存的句柄数（LRU），缺省 4；超出的续聊时从会话文件重开。只认用户级。 */
     retainSessions?: number;
+    /**
+     * [#149] fork 回落比例：父上一次请求的输入 token 超过（窗口 − compaction.reserveTokens）× 本值时
+     * fork 回落为 fresh；0.05–0.95，缺省 0.5。只认用户级。
+     */
+    forkMaxContextRatio?: number;
 }
 /** `models.enabled` 的一项：`provider/model[@channel]` 或 `provider/*`。 */
 export declare const MODELS_ENABLED_REF: RegExp;

package/dist/i18n/catalog.d.ts

@@ -534,6 +534,7 @@ declare const en: {
             backgroundStopped: (jobId: string, command: string) => string;
             compactionFailed: (error: string) => string;
             compactionCancelled: string;
+            imageReadBackFailed: (id: string) => string;
         };
         statusLine: {
             usage: string;
@@ -1446,6 +1447,7 @@ declare const en: {
             "subagents.maxPending": string;
             "subagents.retainSessions": string;
             "subagents.defaultModel": string;
+            "subagents.forkMaxContextRatio": string;
             "subagents.background": string;
             "subagents.autoBackgroundAfterMs": string;
             models: string;

package/dist/i18n/messages/config-keys.d.ts

@@ -115,6 +115,7 @@ export declare const en: {
         "subagents.maxPending": string;
         "subagents.retainSessions": string;
         "subagents.defaultModel": string;
+        "subagents.forkMaxContextRatio": string;
         "subagents.background": string;
         "subagents.autoBackgroundAfterMs": string;
         models: string;
@@ -269,6 +270,7 @@ export declare const zh: {
         "subagents.maxPending": string;
         "subagents.retainSessions": string;
         "subagents.defaultModel": string;
+        "subagents.forkMaxContextRatio": string;
         "subagents.background": string;
         "subagents.autoBackgroundAfterMs": string;
         models: string;

package/dist/i18n/messages/config-keys.js

@@ -164,6 +164,7 @@ const keysEn = {
     "subagents.maxPending": "Queue limit; task fails beyond it",
     "subagents.retainSessions": "Finished sub-sessions kept in memory (least recently used first out); others reopen from their session file when continued",
     "subagents.defaultModel": "Default sub-session model provider/model[@channel]",
+    "subagents.forkMaxContextRatio": "Fork sub-agents fall back to fresh when the parent's last request used more than this share of (window − compaction.reserveTokens); 0.05–0.95, default 0.5",
     "subagents.background": "Whether task runs in the background by default: auto = background in the TUI / RPC / ACP and foreground with -p; always / never are fixed. The call argument and the agent type's background: override it; user, project and host level",
     "subagents.autoBackgroundAfterMs": "Move a foreground task to the background after it has run this many milliseconds; 0 disables; user and project level",
     models: "Model aliases and the model picker list; user level only (effective from wave 5 W5-G)",
@@ -292,6 +293,7 @@ const keysZh = {
     "subagents.maxPending": "排队上限，超出时 task 报错",
     "subagents.retainSessions": "内存中保留的已结束子会话数（最久未用的先释放），其余续聊时从会话文件重开",
     "subagents.defaultModel": "子会话缺省模型 provider/model[@channel]",
+    "subagents.forkMaxContextRatio": "fork 子 Agent 的回落比例：父上一次请求超过（窗口 − compaction.reserveTokens）的这一比例时改为 fresh；0.05–0.95，缺省 0.5",
     "subagents.background": "task 缺省是否后台：auto = TUI / RPC / ACP 下后台、-p 下前台；always / never 固定。调用参数与类型定义的 background: 优先；用户、项目、宿主级都认",
     "subagents.autoBackgroundAfterMs": "前台任务运行超过该毫秒数自动转后台；0 关闭；用户、项目级都认",
     models: "模型别名与模型选择器清单；只认用户级（第五波 W5-G 起生效）",

package/dist/i18n/messages/config.d.ts

@@ -115,6 +115,7 @@ export declare const en: {
         "subagents.maxPending": string;
         "subagents.retainSessions": string;
         "subagents.defaultModel": string;
+        "subagents.forkMaxContextRatio": string;
         "subagents.background": string;
         "subagents.autoBackgroundAfterMs": string;
         models: string;
@@ -383,6 +384,7 @@ export declare const zh: {
         "subagents.maxPending": string;
         "subagents.retainSessions": string;
         "subagents.defaultModel": string;
+        "subagents.forkMaxContextRatio": string;
         "subagents.background": string;
         "subagents.autoBackgroundAfterMs": string;
         models: string;

package/dist/i18n/messages/interactive.d.ts

@@ -85,6 +85,7 @@ export declare const en: {
         backgroundStopped: (jobId: string, command: string) => string;
         compactionFailed: (error: string) => string;
         compactionCancelled: string;
+        imageReadBackFailed: (id: string) => string;
     };
     statusLine: {
         usage: string;
@@ -335,6 +336,7 @@ export declare const zh: {
         backgroundStopped: (jobId: string, command: string) => string;
         compactionFailed: (error: string) => string;
         compactionCancelled: string;
+        imageReadBackFailed: (id: string) => string;
     };
     statusLine: {
         usage: string;

package/dist/i18n/messages/interactive.js

@@ -99,6 +99,7 @@ export const en = {
         backgroundStopped: (jobId, command) => `Background command ${jobId} stopped: ${command}`,
         compactionFailed: (error) => `Compaction failed: ${error}`,
         compactionCancelled: "Compaction cancelled",
+        imageReadBackFailed: (id) => `Session image for entry ${id} could not be read back (file changed); it stays empty`,
     },
     statusLine: {
         usage: "Usage: /statusline [full|compact]",
@@ -234,6 +235,7 @@ export const zh = {
         backgroundStopped: (jobId, command) => `后台命令 ${jobId} 已停止：${command}`,
         compactionFailed: (error) => `压缩失败：${error}`,
         compactionCancelled: "压缩已取消",
+        imageReadBackFailed: (id) => `会话文件已改变，条目 ${id} 的图片读不回，保留为空`,
     },
     statusLine: {
         usage: "用法：/statusline [full|compact]",

package/dist/i18n/messages/session.js

@@ -88,7 +88,7 @@ export const en = {
         cwdIsHome: "the working directory is the home directory",
         gitNotFound: "git not found",
         tooManyFiles: (files, max) => `the working directory has ${plural(files, "file")} (limit ${max})`,
-        tooSlow: (seconds, max) => `the snapshot took ${seconds} s (limit ${max} s)`,
+        tooSlow: (seconds, max) => `snapshots took longer than ${max} s twice in a row (latest ${seconds} s)`,
         gitFailed: (command, code, detail) => `git ${command} failed (${code})${detail === "" ? "" : `: ${detail}`}`,
         noShadowCommit: "the checkpoint has no shadow commit",
         shadowCommitMissing: (commit) => `shadow commit ${commit} does not exist`,
@@ -211,7 +211,7 @@ export const zh = {
         cwdIsHome: "工作目录是家目录",
         gitNotFound: "找不到 git",
         tooManyFiles: (files, max) => `工作目录有 ${files} 个文件（上限 ${max}）`,
-        tooSlow: (seconds, max) => `快照用了 ${seconds} 秒（上限 ${max} 秒）`,
+        tooSlow: (seconds, max) => `连续两次快照超过 ${max} 秒（最近一次 ${seconds} 秒）`,
         gitFailed: (command, code, detail) => `git ${command} 失败（${code}）${detail === "" ? "" : `：${detail}`}`,
         noShadowCommit: "检查点没有影子提交",
         shadowCommitMissing: (commit) => `影子提交 ${commit} 不存在`,

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

@@ -19,9 +19,10 @@
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { stopReasonOf } from "../../ai/apis/shared.js";
-import { createSessionAlongside, currentSession, disposeSessionAlongside, setForegroundSession, } from "../../cli/compose-session.js";
+import { createSessionAlongside, currentSession, setForegroundSession, } from "../../cli/compose-session.js";
 import { listSessions } from "../../cli/compose-store.js";
 import { AgentSessionImpl } from "../../agent/session.js";
+import { taskControl } from "../../agents/task-control.js";
 import { RpcError } from "../../drivers/jsonrpc.js";
 import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "../../drivers/acp/types.js";
 import { isPermissionMode } from "../../permissions/modes.js";
@@ -31,7 +32,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, promptWhenIdle, sessionTitle, } from "./acp-sessions.js";
+import { PromptQueue, cancelledResult, disposeQuiet, pageSessions, promptWhenIdle, quiesce, sessionTitle, } from "./acp-sessions.js";
 export const ACP_AGENT_CAPABILITIES = {
     loadSession: true,
     promptCapabilities: { image: true, audio: false, embeddedContext: true },
@@ -157,8 +158,9 @@ export class AcpServer {
                 .abort()
                 .catch(() => undefined);
         await this.queue.settled();
-        for (const session of this.sessions())
-            await session.waitForIdle().catch(() => undefined);
+        for (const s of this.sessions())
+            if (s instanceof AgentSessionImpl)
+                await quiesce(s, taskControl(s.state.sessionId));
         const foreground = this.session();
         for (const entry of this.pool.values())
             entry.unsubscribe();
@@ -167,7 +169,7 @@ export class AcpServer {
                 continue;
             if (!(foreground instanceof AgentSessionImpl))
                 continue;
-            await disposeSessionAlongside(this.runtime, session, foreground).catch(() => undefined);
+            await disposeQuiet(this.runtime, session, foreground).catch(() => undefined);
         }
         this.pool.clear();
         this.standby = undefined;
@@ -311,12 +313,11 @@ export class AcpServer {
             return {};
         this.pool.delete(id);
         this.queue.cancelQueued(id);
-        const running = this.queue.running;
-        if (running?.sessionId === id) {
-            running.cancelRequested = true;
-            await entry.session.abort().catch(() => undefined);
-            await this.queue.settled(id);
-        }
+        // [#167] 通知回合不经队列：不论谁在跑都先安静下来（停后台任务、abort 到空闲）
+        if (this.queue.running?.sessionId === id)
+            this.queue.running.cancelRequested = true;
+        await quiesce(entry.session, taskControl(id));
+        await this.queue.settled(id);
         entry.unsubscribe();
         let fallback = this.session();
         if (fallback === entry.session) {
@@ -330,7 +331,7 @@ export class AcpServer {
             }
         }
         if (fallback instanceof AgentSessionImpl)
-            await disposeSessionAlongside(this.runtime, entry.session, fallback);
+            await disposeQuiet(this.runtime, entry.session, fallback, taskControl(id));
         return {};
     }
     async prompt(params, signal) {
@@ -377,16 +378,17 @@ export class AcpServer {
         setForegroundSession(this.runtime, session);
         if (this.runtime.permission.mode !== entry.mode)
             session.setPermissionMode(entry.mode);
-        const before = session.getStats().tokens;
+        let before = session.getStats().tokens;
         let failure;
         try {
-            await promptWhenIdle(session, job);
+            // [#166] 起点取在真正发起时：等待期间结束的通知回合不计入本次 usage
+            await promptWhenIdle(session, job, () => void (before = session.getStats().tokens));
         }
         catch (error) {
             failure = error;
         }
-        await this.peer.flush();
         const after = session.getStats().tokens;
+        await this.peer.flush();
         const usage = {
             inputTokens: after.input - before.input,
             outputTokens: after.output - before.output,

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

@@ -8,6 +8,8 @@
  */
 import type { ImageBlock } from "../../ai/types.js";
 import type { AgentSessionImpl } from "../../agent/session.js";
+import type { TaskControl } from "../../agents/task-control.js";
+import type { Runtime } from "../../cli/runtime.js";
 import type { AgentMessage, SessionListItem } from "../../session/types.js";
 import { type AcpPromptResult, type AcpListSessionsResult } from "../../drivers/acp/types.js";
 import type { PermissionMode } from "../../permissions/types.js";
@@ -86,4 +88,15 @@ export declare function pageSessions(items: readonly SessionListItem[], cursor:
  * 不用 `streamingBehavior: "followUp"` 入队：`abort()` 不清队列，等待期间的 `session/cancel`
  * 会让这条提示在之后的周期里冒出来。`job.cancelRequested`（cancel / close / 撤回）→ 不再发，直接返回。
  */
-export declare function promptWhenIdle(session: AgentSessionImpl, job: PromptJob): Promise<void>;
+export declare function promptWhenIdle(session: AgentSessionImpl, job: PromptJob, onStart?: () => void): Promise<void>;
+/**
+ * 关会话前把它安静下来（Issue #167）：先停在跑的后台任务（被停止的任务不发完成通知），再反复 abort，
+ * 直到隔一个宏任务仍然空闲——已完成任务排在投递链上的通知会在上一周期结算后的微任务里开新周期，
+ * 一次 abort 不够。超过 `rounds` 轮仍不空闲返回 false。被打断的通知回合与用户 cancel 同样留下中断标记。
+ */
+export declare function quiesce(session: AgentSessionImpl, control: TaskControl | undefined, rounds?: number): Promise<boolean>;
+/**
+ * `disposeSessionAlongside` 的安静版：撞上 busy（SessionEnd Hook 期间又开了通知回合）→ 再 quiesce 重试；
+ * dispose 之后若还有周期（与 dispose 同一时刻开出来的）再 abort 一次。
+ */
+export declare function disposeQuiet(runtime: Runtime, session: AgentSessionImpl, fallback: AgentSessionImpl, control?: TaskControl, retries?: number): Promise<void>;

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

@@ -6,6 +6,7 @@
  * - 同一时刻只跑一个回合，其它会话的 `session/prompt` 进 {@link PromptQueue}（FIFO），不再回 busy；
  * - `session/list`：按 `updatedAt` 降序、`sessionId` 次序分页，cursor 是 `updatedAt|sessionId` 的 base64。
  */
+import { disposeSessionAlongside } from "../../cli/compose-session.js";
 import { RPC_ERRORS, } from "../../drivers/acp/types.js";
 import { RpcError } from "../../drivers/jsonrpc.js";
 import { AmaError } from "../../errors.js";
@@ -164,12 +165,14 @@ export function pageSessions(items, cursor, pageSize = LIST_PAGE_SIZE) {
  * 不用 `streamingBehavior: "followUp"` 入队：`abort()` 不清队列，等待期间的 `session/cancel`
  * 会让这条提示在之后的周期里冒出来。`job.cancelRequested`（cancel / close / 撤回）→ 不再发，直接返回。
  */
-export async function promptWhenIdle(session, job) {
+export async function promptWhenIdle(session, job, onStart) {
     for (;;) {
         // 等周期而不是看 `state.isStreaming`：busy 以周期为准，周期的收尾阶段 isStreaming 已是 false
         await session.waitForIdle();
         if (job.cancelRequested)
             return;
+        // [#166] 每次真正发起前回调（busy 重试时再调，最后一次为准）：usage 的起点不含之前的通知回合
+        onStart?.();
         try {
             await session.prompt(job.text, job.images.length > 0 ? { images: job.images } : {});
             return;
@@ -180,3 +183,43 @@ export async function promptWhenIdle(session, job) {
         }
     }
 }
+const BUSY = Symbol("busy");
+/** 当前没有周期（含收尾阶段）：`waitForIdle()` 已结算即空闲。 */
+async function idleNow(session) {
+    return (await Promise.race([session.waitForIdle(), Promise.resolve(BUSY)])) !== BUSY;
+}
+/**
+ * 关会话前把它安静下来（Issue #167）：先停在跑的后台任务（被停止的任务不发完成通知），再反复 abort，
+ * 直到隔一个宏任务仍然空闲——已完成任务排在投递链上的通知会在上一周期结算后的微任务里开新周期，
+ * 一次 abort 不够。超过 `rounds` 轮仍不空闲返回 false。被打断的通知回合与用户 cancel 同样留下中断标记。
+ */
+export async function quiesce(session, control, rounds = 50) {
+    for (const task of control?.list() ?? [])
+        if (task.status === "running")
+            await control?.stop(task.taskId).catch(() => undefined);
+    for (let i = 0; i < rounds; i++) {
+        await session.abort();
+        await new Promise((resolve) => setImmediate(resolve));
+        if (await idleNow(session))
+            return true;
+    }
+    return false;
+}
+/**
+ * `disposeSessionAlongside` 的安静版：撞上 busy（SessionEnd Hook 期间又开了通知回合）→ 再 quiesce 重试；
+ * dispose 之后若还有周期（与 dispose 同一时刻开出来的）再 abort 一次。
+ */
+export async function disposeQuiet(runtime, session, fallback, control, retries = 3) {
+    for (let i = 0;; i++) {
+        try {
+            await disposeSessionAlongside(runtime, session, fallback);
+            break;
+        }
+        catch (error) {
+            if (i >= retries || !(error instanceof AmaError && error.code === "busy"))
+                throw error;
+            await quiesce(session, control);
+        }
+    }
+    await session.abort();
+}

package/dist/modes/interactive/agent-ui.js

@@ -45,6 +45,8 @@ export function agentCommandHooks(get) {
     };
 }
 const TASK_NOTICE = /^\[task (t\d+)\] ([\s\S]*)$/;
+/** #183：会话图片读不回（`ImageOffload` 的告警）转通知区。 */
+const SESSION_NOTICE = /^cannot read session entry (\S+) back from /;
 export class AgentUi {
     deps;
     plan;
@@ -164,6 +166,11 @@ export class AgentUi {
                 this.deps.notice(level === "warn" ? "warn" : "info", `[${agent} · ${taskId}] ${match[2]}`);
                 return;
             }
+            const image = level === "warn" ? SESSION_NOTICE.exec(message) : null;
+            if (image !== null) {
+                this.deps.notice("warn", msg().interactive.events.imageReadBackFailed(image[1]));
+                return;
+            }
             original?.call(holder, level, message);
         };
         holder.log = routed;