@armadra/agent 0.7.5 → 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/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/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/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;

package/dist/session/manager.d.ts

@@ -37,7 +37,7 @@ export declare class SessionManager implements SessionManagerApi {
     private closed;
     private readonly now;
     private readonly images;
-    private readonly warn;
+    private warn;
     /** 已知的会话文件字节数（新行的行首偏移）。 */
     private fileBytes;
     private constructor();
@@ -65,6 +65,8 @@ export declare class SessionManager implements SessionManagerApi {
     private syncImages;
     /** 原文条目（已卸载的从文件回读一份副本）。 */
     private original;
+    /** 接上（或换掉）告警出口（图片读不回等）；`open()` 期间缓冲的告警随即按序冲出（#183）。 */
+    setWarn(warn: (message: string) => void): void;
     /** 已卸载图片的条目数（测试与诊断用）。 */
     offloadedCount(): number;
     private leafLine;

package/dist/session/manager.js

@@ -182,6 +182,11 @@ export class SessionManager {
             return entry;
         return this.images.original(this.storage.file, entry);
     }
+    /** 接上（或换掉）告警出口（图片读不回等）；`open()` 期间缓冲的告警随即按序冲出（#183）。 */
+    setWarn(warn) {
+        this.warn = warn;
+        this.images.setWarn(warn);
+    }
     /** 已卸载图片的条目数（测试与诊断用）。 */
     offloadedCount() {
         return this.images.size;

package/dist/session/offload.d.ts

@@ -10,7 +10,8 @@
  *   `content` 换新数组，image 块换成 `data: ""` 的占位；
  * - 回读：按行位置 `readSync` 一行、`JSON.parse`，校验 id 与内容块数，图片经 `internImage` 驻留后
  *   **就地**放回占位所在的数组（之前拿到同一消息对象的调用方随之看到原图）；读不回（文件被外部改写）时
- *   保留 `""` 并告警，不再重试；
+ *   保留 `""` 并告警，不再重试；告警通道可后接（`setWarn`）：接上之前的告警先缓冲（最多
+ *   `PENDING_WARNINGS` 条，其余折叠成一条计数），接上时按序冲出（#183）；
  * - `original(entry)`：给 `getEntries` / `fork` 的原文副本，不改内存状态。
  */
 import type { SessionEntry } from "./types.js";
@@ -25,12 +26,18 @@ export declare function hasImages(entry: SessionEntry): boolean;
 export declare function readLineAt(file: string, locator: LineLocator): unknown;
 /** 文件里全部 `context_edit` 的目标 id（只解析 context_edit 行；读不了时为空集）。 */
 export declare function editTargets(file: string): Set<string>;
+/** 告警通道接上之前最多缓冲的条数；超出的只计数，冲出时折叠成一条。 */
+export declare const PENDING_WARNINGS = 16;
 export declare class ImageOffload {
-    private readonly warn;
     /** 含图 message 条目的行位置（只有已落盘的条目才有）。 */
     private readonly locators;
     private readonly offloaded;
+    private warn;
+    private readonly pending;
+    private dropped;
     constructor(warn?: (message: string) => void);
+    /** 接上（或换掉）告警通道；之前缓冲的告警按序冲出。 */
+    setWarn(warn: (message: string) => void): void;
     /** 记下条目的行位置；不含图片的条目忽略。 */
     track(entry: SessionEntry, locator: LineLocator): void;
     /** 读文件时逐行调用：记下行位置；`strip` 时就地换成占位（刚解析的对象，别处没有引用）。 */
@@ -48,4 +55,5 @@ export declare class ImageOffload {
     sync(file: string, branch: readonly SessionEntry[], index: ReadonlyMap<string, SessionEntry>): void;
     /** 从文件读回条目（新对象）；不成功时告警、忘掉行位置并返回 undefined。 */
     private read;
+    private report;
 }

package/dist/session/offload.js

@@ -10,7 +10,8 @@
  *   `content` 换新数组，image 块换成 `data: ""` 的占位；
  * - 回读：按行位置 `readSync` 一行、`JSON.parse`，校验 id 与内容块数，图片经 `internImage` 驻留后
  *   **就地**放回占位所在的数组（之前拿到同一消息对象的调用方随之看到原图）；读不回（文件被外部改写）时
- *   保留 `""` 并告警，不再重试；
+ *   保留 `""` 并告警，不再重试；告警通道可后接（`setWarn`）：接上之前的告警先缓冲（最多
+ *   `PENDING_WARNINGS` 条，其余折叠成一条计数），接上时按序冲出（#183）；
  * - `original(entry)`：给 `getEntries` / `fork` 的原文副本，不改内存状态。
  */
 import { closeSync, openSync, readSync } from "node:fs";
@@ -74,14 +75,28 @@ export function editTargets(file) {
     return targets;
 }
 const placeholder = (block) => ({ ...block, data: "" });
+/** 告警通道接上之前最多缓冲的条数；超出的只计数，冲出时折叠成一条。 */
+export const PENDING_WARNINGS = 16;
 export class ImageOffload {
-    warn;
     /** 含图 message 条目的行位置（只有已落盘的条目才有）。 */
     locators = new Map();
     offloaded = new Set();
-    constructor(warn = () => { }) {
+    warn;
+    pending = [];
+    dropped = 0;
+    constructor(warn) {
         this.warn = warn;
     }
+    /** 接上（或换掉）告警通道；之前缓冲的告警按序冲出。 */
+    setWarn(warn) {
+        this.warn = warn;
+        const pending = this.pending.splice(0);
+        if (this.dropped > 0)
+            pending.push(`and ${this.dropped} more session entries could not be read back`);
+        this.dropped = 0;
+        for (const message of pending)
+            warn(message);
+    }
     /** 记下条目的行位置；不含图片的条目忽略。 */
     track(entry, locator) {
         if (hasImages(entry))
@@ -188,8 +203,16 @@ export class ImageOffload {
         catch (error) {
             this.locators.delete(entry.id);
             this.offloaded.delete(entry.id);
-            this.warn(`cannot read session entry ${entry.id} back from ${file}: ${String(error)}`);
+            this.report(`cannot read session entry ${entry.id} back from ${file}: ${String(error)}`);
             return undefined;
         }
     }
+    report(message) {
+        if (this.warn !== undefined)
+            this.warn(message);
+        else if (this.pending.length < PENDING_WARNINGS)
+            this.pending.push(message);
+        else
+            this.dropped++;
+    }
 }

package/dist/tools/background-jobs.d.ts

@@ -5,14 +5,14 @@
  *   这里只拿到 ChildProcess；stdout / stderr 直接写进 `outputPath`（文件描述符交给子进程，ama 退出也不
  *   会因管道断开而 SIGPIPE）。POSIX 自成进程组并登记（进程退出时同步 SIGKILL 残留组）。
  * - `wait(id, timeoutMs)`：等到退出或超时；`stop(id)`：杀整棵树（SIGTERM → 宽限 → SIGKILL）；
- *   `output(id)`：读输出文件尾部（2000 行 / 50 KB）。
+ *   `output(id, options?)`：读输出文件尾部（缺省 2000 行 / 50 KB，调用方可传字节上限）。
  * - 生命周期事件经 `onChange` 发出（started / exited / stopped）；`takeExited()` 取走尚未通知的已退出
  *   任务（提醒通道 reminders.ts 据此告诉模型「后台命令 jobId 已退出（码 N）」）。
  * - 按会话 id 登记（`jobsForSession`）；`disposeSessionJobs` 在会话 dispose 时回收进程树。
  */
 import type { ChildProcess } from "node:child_process";
 import { type ProcessDeps } from "./process-tree.js";
-import { type TruncateResult } from "./truncate.js";
+import { type TruncateOptions, type TruncateResult } from "./truncate.js";
 export type JobStatus = "running" | "exited" | "stopped";
 export interface Job {
     id: string;
@@ -49,8 +49,8 @@ export declare class BackgroundJobs {
     /** 等到退出或超时（`signal` 可提前结束等待，不杀进程）。 */
     wait(id: string, timeoutMs: number, signal?: AbortSignal): Promise<Job | undefined>;
     stop(id: string): Promise<Job | undefined>;
-    /** 输出文件尾部（2000 行 / 50 KB）。 */
-    output(id: string): (TruncateResult & {
+    /** 输出文件尾部（缺省 2000 行 / 50 KB；调用方可传字节上限，#155）。 */
+    output(id: string, options?: TruncateOptions): (TruncateResult & {
         job: Job;
     }) | undefined;
     /** 取走已退出、尚未通知的任务（提醒通道用；wait 已看到退出的也算已知）。 */

package/dist/tools/background-jobs.js

@@ -5,7 +5,7 @@
  *   这里只拿到 ChildProcess；stdout / stderr 直接写进 `outputPath`（文件描述符交给子进程，ama 退出也不
  *   会因管道断开而 SIGPIPE）。POSIX 自成进程组并登记（进程退出时同步 SIGKILL 残留组）。
  * - `wait(id, timeoutMs)`：等到退出或超时；`stop(id)`：杀整棵树（SIGTERM → 宽限 → SIGKILL）；
- *   `output(id)`：读输出文件尾部（2000 行 / 50 KB）。
+ *   `output(id, options?)`：读输出文件尾部（缺省 2000 行 / 50 KB，调用方可传字节上限）。
  * - 生命周期事件经 `onChange` 发出（started / exited / stopped）；`takeExited()` 取走尚未通知的已退出
  *   任务（提醒通道 reminders.ts 据此告诉模型「后台命令 jobId 已退出（码 N）」）。
  * - 按会话 id 登记（`jobsForSession`）；`disposeSessionJobs` 在会话 dispose 时回收进程树。
@@ -119,8 +119,8 @@ export class BackgroundJobs {
         await entry.done;
         return entry.job;
     }
-    /** 输出文件尾部（2000 行 / 50 KB）。 */
-    output(id) {
+    /** 输出文件尾部（缺省 2000 行 / 50 KB；调用方可传字节上限，#155）。 */
+    output(id, options = {}) {
         const entry = this.entries.get(id);
         if (entry === undefined)
             return undefined;
@@ -132,7 +132,7 @@ export class BackgroundJobs {
         catch {
             // 输出文件被删：按空输出
         }
-        return { ...truncateTail(text), job: entry.job };
+        return { ...truncateTail(text, options), job: entry.job };
     }
     /** 取走已退出、尚未通知的任务（提醒通道用；wait 已看到退出的也算已知）。 */
     takeExited() {

package/dist/tools/bash.d.ts

@@ -9,7 +9,8 @@
  * - 注入 `AMA_*` 环境变量（shell.ts）。shell 退出后不等仍占着管道的后台进程。
  * - [W5-H2] 后台命令（§8.3 H6，不加新工具）：`{ command, background: true }` 立即返回
  *   `{ jobId, outputPath, pid }`；`{ job, action: "wait" | "output" | "stop" }` 查询 / 结束
- *   （background-jobs.ts，按会话登记，会话 dispose 时回收进程树；退出经提醒通道通知）。
+ *   （background-jobs.ts，按会话登记，会话 dispose 时回收进程树；退出经提醒通道通知）。查询输出同样按
+ *   会话结果上限尾截断（#155）。
  * - **进程只在 `spawnShell` 里创建**（前台与后台共用）。[S2] `sandbox.bash: auto` 且有能限制写入的
  *   OS 沙箱时在这一处包一层（src/sandbox/bash.ts）；`sandbox: false` 不包装（权限管线照常审批）。
  *   失败输出像是被沙箱拒绝时末尾追加一行说明。

package/dist/tools/bash.js

@@ -9,7 +9,8 @@
  * - 注入 `AMA_*` 环境变量（shell.ts）。shell 退出后不等仍占着管道的后台进程。
  * - [W5-H2] 后台命令（§8.3 H6，不加新工具）：`{ command, background: true }` 立即返回
  *   `{ jobId, outputPath, pid }`；`{ job, action: "wait" | "output" | "stop" }` 查询 / 结束
- *   （background-jobs.ts，按会话登记，会话 dispose 时回收进程树；退出经提醒通道通知）。
+ *   （background-jobs.ts，按会话登记，会话 dispose 时回收进程树；退出经提醒通道通知）。查询输出同样按
+ *   会话结果上限尾截断（#155）。
  * - **进程只在 `spawnShell` 里创建**（前台与后台共用）。[S2] `sandbox.bash: auto` 且有能限制写入的
  *   OS 沙箱时在这一处包一层（src/sandbox/bash.ts）；`sandbox: false` 不包装（权限管线照常审批）。
  *   失败输出像是被沙箱拒绝时末尾追加一行说明。
@@ -304,7 +305,7 @@ async function jobAction(input, ctx, options) {
     }
     if (action === "stop") {
         const job = (await jobs.stop(id));
-        const out = jobs.output(id);
+        const out = jobs.output(id, { maxBytes: toolOutputBytes(ctx.maxResultChars) });
         const text = out?.content ?? "";
         return {
             content: `${text === "" ? "(no output)" : text}\n\n${jobStatusLine(job)}`,
@@ -317,7 +318,7 @@ async function jobAction(input, ctx, options) {
             return fail(`timeoutMs must be between 1 and ${MAX_BASH_TIMEOUT_MS}`);
         await jobs.wait(id, waitMs, ctx.signal);
     }
-    const out = jobs.output(id);
+    const out = jobs.output(id, { maxBytes: toolOutputBytes(ctx.maxResultChars) });
     if (out === undefined)
         return fail(`Unknown background job ${id}`);
     const job = out.job;

package/dist/tools/task-ctl.js

@@ -12,6 +12,7 @@
  */
 import { capTaskText, formatTokens, waitDetachedText } from "../agents/result.js";
 import { taskControl } from "../agents/task-control.js";
+import { nestedTaskRejection } from "./task.js";
 export const TASK_CTL_TOOL = "task_ctl";
 export const DEFAULT_WAIT_MS = 30_000;
 export const MAX_WAIT_MS = 600_000;
@@ -66,7 +67,7 @@ export function createTaskCtlTool() {
         annotations: { pollable: true },
         async execute(input, ctx) {
             if (ctx.depth >= 1)
-                return fail("task_ctl is not available inside a sub-agent.");
+                return fail(nestedTaskRejection(ctx, "task_ctl", "task_ctl is not available inside a sub-agent."));
             const control = taskControl(ctx.sessionId);
             if (input.action === "list") {
                 const tasks = control?.list() ?? ctx.tasks?.list() ?? [];