@armadra/agent 0.4.0 → 0.5.0

package/dist/cli/subcommands/sessions.js

@@ -5,13 +5,17 @@
  * - list [--all]：缺省只列当前目录的会话；`--all` 列全部。
  * - show <id>：头信息 + 条目类型统计 + 首条提示 + 用户消息编号（`--from <id>#<编号>` 复用）。
  * - search / export：见 sessions-search.ts、sessions-export.ts（只读扫描，不经会话存储）。
- * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）。
+ * - prune [--older-than <天>] [--dry-run]：缺省 30 天，移到 trash（不删除）；之后清理检查点备份
+ *   （未被任何会话引用且超过 1 天的 blob，docs/rewind-plan.md §1.4）与超过 7 天的剪贴板图片
+ *   （`<数据目录>/clipboard/`，W5-I），`--dry-run` 时只报告。
  */
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
+import { formatBytes, gcBlobs } from "../../checkpoints/gc.js";
 import { expandHome, resolveDataDir } from "../../config/paths.js";
 import { parseSubArgs, UsageError } from "../args.js";
 import { ExitCode } from "../exit-codes.js";
 import { numberUserMessages } from "../../session/reuse.js";
+import { gcClipboardImages } from "../../tools/clipboard-image.js";
 import { runSessionsExport } from "./sessions-export.js";
 import { runSessionsSearch } from "./sessions-search.js";
 export const SESSIONS_USAGE = `用法：ama sessions list [--all] [--session-dir <目录>]
@@ -109,12 +113,42 @@ export async function runSessions(argv, io, deps) {
             for (const file of moved)
                 io.stdout(`${dryRun ? "将移到 trash" : "已移到 trash"}：${file}\n`);
             io.stdout(`${moved.length} 个会话${dryRun ? "（演练，未改动）" : ""}\n`);
+            await pruneFileHistory(io, sessionDir, dryRun);
+            await pruneClipboard(io, dryRun);
             return ExitCode.Ok;
         }
         default:
             throw new UsageError(`未知的 sessions 子命令：${action}`);
     }
 }
+/** 检查点备份 GC：扫描本次的会话目录、缺省会话目录与登记过的目录。失败只提示，不影响 prune。 */
+async function pruneFileHistory(io, sessionDir, dryRun) {
+    const dataDir = resolveDataDir({ env: io.env });
+    try {
+        const result = await gcBlobs({
+            dataDir,
+            sessionRoots: [sessionDir, join(dataDir, "sessions")],
+            dryRun,
+        });
+        if (result.removed.length === 0)
+            return;
+        io.stdout(`file-history：${dryRun ? "将清除" : "已清除"} ${result.removed.length} 个未引用的备份（${formatBytes(result.removedBytes)}）\n`);
+    }
+    catch (error) {
+        io.stderr(`ama: file-history 清理跳过（${error instanceof Error ? error.message : String(error)}）\n`);
+    }
+}
+/** [W5-I] `<数据目录>/clipboard/` 超过 7 天的剪贴板图片。失败只提示。 */
+async function pruneClipboard(io, dryRun) {
+    try {
+        const removed = await gcClipboardImages(resolveDataDir({ env: io.env }), { dryRun });
+        if (removed.length > 0)
+            io.stdout(`clipboard：${dryRun ? "将清除" : "已清除"} ${removed.length} 个超过 7 天的剪贴板图片\n`);
+    }
+    catch (error) {
+        io.stderr(`ama: clipboard 清理跳过（${error instanceof Error ? error.message : String(error)}）\n`);
+    }
+}
 function notWired(io, what) {
     io.stderr(`ama: ${what} 尚未装配（会话存储由集成批次注入）\n`);
     return ExitCode.RuntimeError;

package/dist/codemode/capability.d.ts

@@ -1,14 +1,19 @@
 /**
- * 沙箱能力探测（设计 §5.5 沙箱第 4 条）。[B10]
+ * 沙箱能力探测（设计 §5.5 沙箱第 4 条；docs/sandbox.md「探测与降级」）。[B10][S2]
  *
  * Node 的权限模型（`--permission`）在 Node ≥ 25 同时拒绝网络；Node 22 / 24 只管文件、子进程、
- * worker 与 addon，不管网络——脚本若逃出 `vm` 就能联网。所以：
- * - Node ≥ 25 → `strict`；
- * - Node 22 / 24 → 仍可用，但工具描述与状态栏标注「网络未隔离」；`codemode.requireStrict: true`
- *   时直接禁用 codemode 工具并 warning（`codemodeAvailability`）。
+ * worker 与 addon，不管网络——脚本若逃出 `vm` 就能联网。子进程另外经操作系统沙箱（macOS
+ * sandbox-exec、Linux bwrap / unshare，src/sandbox）启动时，网络由内核拒绝。所以：
+ * - Node ≥ 25 → `strict`（OS 沙箱可用时叠加，纵深防御）；
+ * - Node 22 / 24 + 可用的 OS 沙箱 → `strict`（子进程必须经 OS 沙箱启动）；
+ * - Node 22 / 24 且没有 OS 沙箱 → 仍可用，但工具描述与状态栏标注「网络未隔离」；
+ *   `codemode.requireStrict: true` 时直接禁用 codemode 工具并 warning（`codemodeAvailability`）。
  *
- * 状态栏由 B7 直接调用 `detectSandboxCapability()` 判断（不经宿主 status）。
+ * 能力在进程内只探测一次（OS 沙箱探针有缓存），同一环境下描述与权限类字节稳定。状态栏直接调用
+ * `detectSandboxCapability()`（不经宿主 status）；组装根先用 `configureOsSandbox` 记下 `sandbox.enabled`。
  */
+import type { SandboxConfig } from "../config/types.js";
+import { type OsSandboxStatus } from "../sandbox/detect.js";
 export interface SandboxCapability {
     /** 权限模型同时隔离文件、子进程与网络。 */
     strict: boolean;
@@ -18,12 +23,24 @@ export interface SandboxCapability {
     reason: string;
     /** 运行时支持的权限开关：Node ≥ 22.13 / 23.5 为 `--permission`，更早为 `--experimental-permission`。 */
     permissionFlag: "--permission" | "--experimental-permission";
+    /** 操作系统沙箱（`kind: none` 表示没有）；codemode 子进程经它启动。 */
+    os: OsSandboxStatus;
 }
 export declare const NETWORK_NOT_ISOLATED = "network not isolated";
 export declare function parseNodeMajor(version: string): number;
 /** `--permission` 在 Node 22.13 / 23.5 之后才是稳定名字；之前只有 `--experimental-permission`。 */
 export declare function permissionFlagFor(allowedFlags?: ReadonlySet<string>): SandboxCapability["permissionFlag"];
-export declare function detectSandboxCapability(nodeVersion?: string, allowedFlags?: ReadonlySet<string>): SandboxCapability;
+/**
+ * 运行时的沙箱能力。`os` 缺省：不传 `nodeVersion` 时用进程内缓存的探测结果（`osSandboxStatus()`）；
+ * 传了假设的 Node 版本（测试、展示）时不探测，按没有 OS 沙箱算，需要时显式传入。
+ */
+export declare function detectSandboxCapability(nodeVersion?: string, allowedFlags?: ReadonlySet<string>, os?: OsSandboxStatus): SandboxCapability;
+/** 按配置的 `sandbox.enabled`（缺省 auto）得到运行时能力。 */
+export declare function sandboxCapabilityFor(config: {
+    sandbox?: SandboxConfig;
+}): SandboxCapability;
+/** strict 是否依赖 OS 沙箱（Node 22 / 24）：此时子进程必须经 OS 沙箱启动，包装不了就报错。 */
+export declare function strictNeedsOsSandbox(capability: Pick<SandboxCapability, "strict" | "nodeMajor">): boolean;
 export type CodemodeAvailability = {
     available: true;
     capability: SandboxCapability;

package/dist/codemode/capability.js

@@ -1,14 +1,18 @@
 /**
- * 沙箱能力探测（设计 §5.5 沙箱第 4 条）。[B10]
+ * 沙箱能力探测（设计 §5.5 沙箱第 4 条；docs/sandbox.md「探测与降级」）。[B10][S2]
  *
  * Node 的权限模型（`--permission`）在 Node ≥ 25 同时拒绝网络；Node 22 / 24 只管文件、子进程、
- * worker 与 addon，不管网络——脚本若逃出 `vm` 就能联网。所以：
- * - Node ≥ 25 → `strict`；
- * - Node 22 / 24 → 仍可用，但工具描述与状态栏标注「网络未隔离」；`codemode.requireStrict: true`
- *   时直接禁用 codemode 工具并 warning（`codemodeAvailability`）。
+ * worker 与 addon，不管网络——脚本若逃出 `vm` 就能联网。子进程另外经操作系统沙箱（macOS
+ * sandbox-exec、Linux bwrap / unshare，src/sandbox）启动时，网络由内核拒绝。所以：
+ * - Node ≥ 25 → `strict`（OS 沙箱可用时叠加，纵深防御）；
+ * - Node 22 / 24 + 可用的 OS 沙箱 → `strict`（子进程必须经 OS 沙箱启动）；
+ * - Node 22 / 24 且没有 OS 沙箱 → 仍可用，但工具描述与状态栏标注「网络未隔离」；
+ *   `codemode.requireStrict: true` 时直接禁用 codemode 工具并 warning（`codemodeAvailability`）。
  *
- * 状态栏由 B7 直接调用 `detectSandboxCapability()` 判断（不经宿主 status）。
+ * 能力在进程内只探测一次（OS 沙箱探针有缓存），同一环境下描述与权限类字节稳定。状态栏直接调用
+ * `detectSandboxCapability()`（不经宿主 status）；组装根先用 `configureOsSandbox` 记下 `sandbox.enabled`。
  */
+import { NO_OS_SANDBOX, osSandboxStatus } from "../sandbox/detect.js";
 export const NETWORK_NOT_ISOLATED = "network not isolated";
 export function parseNodeMajor(version) {
     const major = Number.parseInt(version.replace(/^v/, "").split(".")[0] ?? "", 10);
@@ -18,8 +22,13 @@ export function parseNodeMajor(version) {
 export function permissionFlagFor(allowedFlags = process.allowedNodeEnvironmentFlags) {
     return allowedFlags.has("--permission") ? "--permission" : "--experimental-permission";
 }
-export function detectSandboxCapability(nodeVersion = process.versions.node, allowedFlags) {
-    const nodeMajor = parseNodeMajor(nodeVersion);
+/**
+ * 运行时的沙箱能力。`os` 缺省：不传 `nodeVersion` 时用进程内缓存的探测结果（`osSandboxStatus()`）；
+ * 传了假设的 Node 版本（测试、展示）时不探测，按没有 OS 沙箱算，需要时显式传入。
+ */
+export function detectSandboxCapability(nodeVersion, allowedFlags, os) {
+    const osStatus = os ?? (nodeVersion === undefined ? osSandboxStatus() : NO_OS_SANDBOX);
+    const nodeMajor = parseNodeMajor(nodeVersion ?? process.versions.node);
     const permissionFlag = permissionFlagFor(allowedFlags);
     if (nodeMajor >= 25) {
         return {
@@ -27,6 +36,16 @@ export function detectSandboxCapability(nodeVersion = process.versions.node, all
             nodeMajor,
             reason: `Node ${nodeMajor}: the permission model blocks file access, child processes and network`,
             permissionFlag,
+            os: osStatus,
+        };
+    }
+    if (osStatus.isolatesNetwork) {
+        return {
+            strict: true,
+            nodeMajor,
+            reason: `Node ${nodeMajor}: the OS sandbox (${osStatus.kind}) blocks network; the permission model blocks file access and child processes`,
+            permissionFlag,
+            os: osStatus,
         };
     }
     return {
@@ -34,8 +53,17 @@ export function detectSandboxCapability(nodeVersion = process.versions.node, all
         nodeMajor,
         reason: `Node ${nodeMajor}: ${NETWORK_NOT_ISOLATED} (the permission model blocks file access and child processes only)`,
         permissionFlag,
+        os: osStatus,
     };
 }
+/** 按配置的 `sandbox.enabled`（缺省 auto）得到运行时能力。 */
+export function sandboxCapabilityFor(config) {
+    return detectSandboxCapability(undefined, undefined, osSandboxStatus(config.sandbox?.enabled ?? "auto"));
+}
+/** strict 是否依赖 OS 沙箱（Node 22 / 24）：此时子进程必须经 OS 沙箱启动，包装不了就报错。 */
+export function strictNeedsOsSandbox(capability) {
+    return capability.strict && capability.nodeMajor < 25;
+}
 /** `requireStrict` 且运行时不是 strict → 禁用并给出 warning；非 strict 但允许 → 可用并提示。 */
 export function codemodeAvailability(requireStrict, capability = detectSandboxCapability()) {
     if (capability.strict)
@@ -44,12 +72,12 @@ export function codemodeAvailability(requireStrict, capability = detectSandboxCa
         return {
             available: false,
             capability,
-            warning: `codemode 已禁用：Node ${capability.nodeMajor} 的权限模型不隔离网络（codemode.requireStrict 为 true；Node ≥ 25 才隔离）`,
+            warning: `codemode 已禁用：Node ${capability.nodeMajor} 的权限模型不隔离网络，也没有可用的操作系统沙箱（${capability.os.detail}；codemode.requireStrict 为 true；Node ≥ 25 或 macOS sandbox-exec / Linux bwrap 可隔离）`,
         };
     }
     return {
         available: true,
         capability,
-        warning: `codemode：Node ${capability.nodeMajor} 下网络未隔离（Node ≥ 25 才隔离；要求隔离可设 codemode.requireStrict）`,
+        warning: `codemode：Node ${capability.nodeMajor} 下网络未隔离（没有可用的操作系统沙箱：${capability.os.detail}；要求隔离可设 codemode.requireStrict）`,
     };
 }

package/dist/codemode/host-side.d.ts

@@ -12,7 +12,13 @@
  *   （完整门禁）；名字是 `codemode` 直接拒绝。脚本结束时 abort 仍在跑的调用。
  * - 超时：父进程计时，到点杀子进程树（POSIX 进程组 / Windows taskkill）；外层 abort：先发
  *   `abort`，宽限后杀树。
+ * - OS 沙箱（docs/sandbox.md）：有可用的 sandbox-exec / bwrap / unshare 时，整条命令行经它启动，拒绝
+ *   网络与一切写入（`CODEMODE_OS_POLICY`；子进程本来就没有写权限）。Node 22 / 24 的 strict 依赖这一层
+ *   （`requireOsSandbox`），包装不了就报错，不裸跑；Node ≥ 25 是叠加的纵深防御。
  */
+import { type OsSandboxStatus } from "../sandbox/detect.js";
+import type { OsSandboxPolicy } from "../sandbox/profile.js";
+import { type WrappedCommand } from "../sandbox/wrap.js";
 import { type SandboxCapability } from "./capability.js";
 import { type ScriptOptions, type StoreSnapshot, type ToolDecl } from "./protocol.js";
 /** 父进程累积的输出上限（字符）；超出后丢弃中段（给模型的再按 max_output_tokens 截）。 */
@@ -23,6 +29,10 @@ export declare const ABORT_GRACE_MS = 500;
 export declare function resolveSandboxEntry(moduleUrl?: string): string | undefined;
 /** 子进程参数（不含可执行文件）。 */
 export declare function sandboxArgs(entry: string, capability?: Pick<SandboxCapability, "permissionFlag">): string[];
+/** codemode 子进程的 OS 沙箱策略：拒绝网络，任何位置都不可写。 */
+export declare const CODEMODE_OS_POLICY: OsSandboxPolicy;
+/** 完整命令行：`<node> <sandboxArgs>`，有 OS 沙箱时再经它包装。 */
+export declare function sandboxCommand(nodePath: string, args: readonly string[], os: Pick<OsSandboxStatus, "kind" | "path">): WrappedCommand;
 /** 子进程环境：空；Electron 下以 Node 方式运行同一可执行文件；Windows 保留 SystemRoot。 */
 export declare function sandboxEnv(versions?: NodeJS.ProcessVersions, platform?: NodeJS.Platform, parentEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export interface SandboxRunRequest {
@@ -39,6 +49,10 @@ export interface SandboxRunRequest {
     /** 缺省 process.execPath。 */
     nodePath?: string;
     capability?: Pick<SandboxCapability, "permissionFlag">;
+    /** 缺省 osSandboxStatus()（进程内缓存的探测结果）。 */
+    os?: Pick<OsSandboxStatus, "kind" | "path">;
+    /** true：必须经 OS 沙箱启动（Node 22 / 24 的 strict 依赖它），包装不了直接失败。 */
+    requireOsSandbox?: boolean;
 }
 export interface SandboxRunResult {
     ok: boolean;

package/dist/codemode/host-side.js

@@ -12,11 +12,16 @@
  *   （完整门禁）；名字是 `codemode` 直接拒绝。脚本结束时 abort 仍在跑的调用。
  * - 超时：父进程计时，到点杀子进程树（POSIX 进程组 / Windows taskkill）；外层 abort：先发
  *   `abort`，宽限后杀树。
+ * - OS 沙箱（docs/sandbox.md）：有可用的 sandbox-exec / bwrap / unshare 时，整条命令行经它启动，拒绝
+ *   网络与一切写入（`CODEMODE_OS_POLICY`；子进程本来就没有写权限）。Node 22 / 24 的 strict 依赖这一层
+ *   （`requireOsSandbox`），包装不了就报错，不裸跑；Node ≥ 25 是叠加的纵深防御。
  */
 import { spawn } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { osSandboxStatus } from "../sandbox/detect.js";
+import { wrapCommand } from "../sandbox/wrap.js";
 import { killProcessTree, trackProcessGroup, untrackProcessGroup } from "../tools/process-tree.js";
 import { detectSandboxCapability } from "./capability.js";
 import { LineSplitter, SANDBOX_MAIN_FLAG, decodeChildLine, encodeLine, } from "./protocol.js";
@@ -49,6 +54,15 @@ export function sandboxArgs(entry, capability = detectSandboxCapability()) {
         SANDBOX_MAIN_FLAG,
     ];
 }
+/** codemode 子进程的 OS 沙箱策略：拒绝网络，任何位置都不可写。 */
+export const CODEMODE_OS_POLICY = Object.freeze({
+    network: "deny",
+    writable: Object.freeze([]),
+});
+/** 完整命令行：`<node> <sandboxArgs>`，有 OS 沙箱时再经它包装。 */
+export function sandboxCommand(nodePath, args, os) {
+    return wrapCommand(os, nodePath, args, CODEMODE_OS_POLICY);
+}
 /** 子进程环境：空；Electron 下以 Node 方式运行同一可执行文件；Windows 保留 SystemRoot。 */
 export function sandboxEnv(versions = process.versions, platform = process.platform, parentEnv = process.env) {
     const env = {};
@@ -82,8 +96,17 @@ export async function runSandbox(request) {
     if (request.signal.aborted) {
         return { ...base, ok: false, error: "Script aborted", aborted: true, elapsedMs: 0 };
     }
+    const command = sandboxCommand(request.nodePath ?? process.execPath, sandboxArgs(entry, request.capability), request.os ?? osSandboxStatus());
+    if (request.requireOsSandbox === true && !command.networkDenied) {
+        return {
+            ...base,
+            ok: false,
+            error: "codemode sandbox requires an OS sandbox to isolate network, but none is available",
+            elapsedMs: 0,
+        };
+    }
     const isWindows = process.platform === "win32";
-    const child = spawn(request.nodePath ?? process.execPath, sandboxArgs(entry, request.capability), {
+    const child = spawn(command.command, command.args, {
         env: sandboxEnv(),
         stdio: ["pipe", "pipe", "pipe"],
         detached: !isWindows,

package/dist/codemode/tool.d.ts

@@ -88,7 +88,7 @@ export declare const CODEMODE_ONLY_GUIDELINE = "read, edit, write, bash and the
 export declare function createCodemodeTool(options: CodemodeToolOptions): ToolDefinition<CodemodeInput>;
 /** 组装根用：从 ToolFactoryContext 的形状取所需（避免 codemode → cli 的依赖）。 */
 export interface CodemodeFactoryContext {
-    config: Pick<AmaConfig, "tools" | "codemode">;
+    config: Pick<AmaConfig, "tools" | "codemode" | "sandbox">;
     registry: {
         list(): readonly string[];
         get(name: string): ToolDefinition | undefined;

package/dist/codemode/tool.js

@@ -20,7 +20,7 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { codemodeCallableFilter, resolveCodemodeMode } from "../tools/presets.js";
-import { codemodeAvailability, detectSandboxCapability, } from "./capability.js";
+import { codemodeAvailability, detectSandboxCapability, sandboxCapabilityFor, strictNeedsOsSandbox, } from "./capability.js";
 import { BASH_RESULT_DECLARATION, DEFAULT_INLINE_BUDGET, buildDeclarationBlock, toolDeclaration, } from "./declarations.js";
 import { runSandbox } from "./host-side.js";
 import { parseOptionsLine } from "./protocol.js";
@@ -189,8 +189,8 @@ export function createCodemodeTool(options) {
             },
             required: ["script"],
         },
-        // 网络隔离（Node ≥ 25）时脚本只能经 tools.* 做事，每次内层调用各自过权限：codemode 本身按 read
-        // 类（default 模式免审批）；不隔离网络时脚本逃出 vm 就能联网，仍按 execute。
+        // 网络隔离（Node ≥ 25，或 OS 沙箱）时脚本只能经 tools.* 做事，每次内层调用各自过权限：codemode
+        // 本身按 read 类（default 模式免审批）；不隔离网络时脚本逃出 vm 就能联网，仍按 execute。
         permission: capability.strict ? "read" : "execute",
         executionMode: "sequential",
         promptSnippet: options.exclusive === true
@@ -218,6 +218,8 @@ export function createCodemodeTool(options) {
                 tools,
                 store: readStore(ctx.session),
                 signal: ctx.signal,
+                os: capability.os,
+                requireOsSandbox: strictNeedsOsSandbox(capability),
                 ...(options.entry !== undefined ? { entry: options.entry } : {}),
                 ...(options.nodePath !== undefined ? { nodePath: options.nodePath } : {}),
                 callTool: async (name, args, signal) => {
@@ -280,7 +282,7 @@ export function createCodemodeTool(options) {
  */
 export function codemodeToolFactory(overrides = {}) {
     return (ctx) => {
-        const capability = overrides.capability ?? detectSandboxCapability();
+        const capability = overrides.capability ?? sandboxCapabilityFor(ctx.config);
         const mode = resolveCodemodeMode(ctx.config, capability.strict).mode;
         if (mode === "off")
             return undefined;

package/dist/compaction/breaker.d.ts

@@ -1,31 +1,47 @@
 /**
- * 压缩熔断（设计 §9「熔断」）。[B2]
+ * 压缩熔断（设计 §9「熔断」，wave5 §8.2 C5）。[B2][W5-H1]
  *
  * - 无 `contextWindow` 或配置关闭 → 自动压缩关闭（手动 /compact 仍可用）。
- * - 同一 run 内档二（摘要）≤ 1 次（`startRun()` 重置计数）。
- * - 连续两次摘要失败 → 跳闸，关闭自动压缩直到 `reset()`（例如用户手动压缩成功）。
+ * - 不再限制「每 run 档二 ≤ 1 次」（单提示长任务需要多次摘要）；改为两种跳闸：
+ *   - 连续 3 次摘要失败；
+ *   - 快速回填：连续 3 次摘要都在上一次摘要后不到 3 回合就又需要摘要（压缩不动、越压越满）。
+ *   跳闸后关闭自动压缩直到 `reset()`（例如用户手动压缩成功）。
+ * - 固定前缀（system + 工具表）已超过预算：摘要无济于事，直接告警、不再尝试（`prefix_overflow`，
+ *   由调用方每次检查时更新）。
+ * - 「nothing to compact」不计失败（调用方不调 `recordSummary`）。
  * - 溢出恢复：压缩后估算仍 > 0.8 × window → 不重试。
  */
-export declare const MAX_SUMMARIES_PER_RUN = 1;
-export declare const MAX_CONSECUTIVE_FAILURES = 2;
+export declare const MAX_CONSECUTIVE_FAILURES = 3;
+/** 上一次摘要后不到这么多回合又需要摘要，记一次快速回填。 */
+export declare const RAPID_REFILL_TURNS = 3;
+export declare const MAX_RAPID_REFILLS = 3;
 export declare const RETRY_AFTER_COMPACTION_RATIO = 0.8;
-export type BreakerBlockReason = "disabled" | "no_window" | "tripped" | "run_limit";
+export type BreakerBlockReason = "disabled" | "no_window" | "tripped" | "rapid_refill" | "prefix_overflow";
 export declare class CompactionBreaker {
-    private summariesThisRun;
     private consecutiveFailures;
+    private rapidRefills;
+    private turn;
+    private lastSummaryTurn;
+    private prefixOverflow;
     private enabled;
     private contextWindow;
     constructor(enabled: boolean, contextWindow: number | undefined);
     configure(enabled: boolean, contextWindow: number | undefined): void;
+    /** 连续失败或快速回填跳闸（溢出恢复也不再尝试）。 */
     get tripped(): boolean;
-    /** 自动压缩整体是否开启（不看本 run 计数）。 */
+    /** 自动压缩整体是否开启。 */
     get autoEnabled(): boolean;
+    /** 新 run 开始（会话在 agent_start 时调用）；不再重置任何计数，保留以兼容调用点。 */
     startRun(): void;
+    /** 每次请求前的阈值检查调用一次：回合计数（快速回填按它判断）。 */
+    tick(): void;
+    /** 固定前缀是否已超预算（调用方每次准备摘要前更新）。 */
+    setPrefixOverflow(overflow: boolean): void;
     /** 自动档二能否执行；不能则给出原因。 */
     blockReason(): BreakerBlockReason | undefined;
     canSummarize(): boolean;
     recordSummary(success: boolean): void;
-    /** 手动压缩成功等场景：清零失败计数。 */
+    /** 手动压缩成功等场景：清零全部计数。 */
     reset(): void;
     /** 溢出恢复后是否值得重试。 */
     shouldRetryAfterCompaction(tokensAfter: number): boolean;

package/dist/compaction/breaker.js

@@ -1,17 +1,27 @@
 /**
- * 压缩熔断（设计 §9「熔断」）。[B2]
+ * 压缩熔断（设计 §9「熔断」，wave5 §8.2 C5）。[B2][W5-H1]
  *
  * - 无 `contextWindow` 或配置关闭 → 自动压缩关闭（手动 /compact 仍可用）。
- * - 同一 run 内档二（摘要）≤ 1 次（`startRun()` 重置计数）。
- * - 连续两次摘要失败 → 跳闸，关闭自动压缩直到 `reset()`（例如用户手动压缩成功）。
+ * - 不再限制「每 run 档二 ≤ 1 次」（单提示长任务需要多次摘要）；改为两种跳闸：
+ *   - 连续 3 次摘要失败；
+ *   - 快速回填：连续 3 次摘要都在上一次摘要后不到 3 回合就又需要摘要（压缩不动、越压越满）。
+ *   跳闸后关闭自动压缩直到 `reset()`（例如用户手动压缩成功）。
+ * - 固定前缀（system + 工具表）已超过预算：摘要无济于事，直接告警、不再尝试（`prefix_overflow`，
+ *   由调用方每次检查时更新）。
+ * - 「nothing to compact」不计失败（调用方不调 `recordSummary`）。
  * - 溢出恢复：压缩后估算仍 > 0.8 × window → 不重试。
  */
-export const MAX_SUMMARIES_PER_RUN = 1;
-export const MAX_CONSECUTIVE_FAILURES = 2;
+export const MAX_CONSECUTIVE_FAILURES = 3;
+/** 上一次摘要后不到这么多回合又需要摘要，记一次快速回填。 */
+export const RAPID_REFILL_TURNS = 3;
+export const MAX_RAPID_REFILLS = 3;
 export const RETRY_AFTER_COMPACTION_RATIO = 0.8;
 export class CompactionBreaker {
-    summariesThisRun = 0;
     consecutiveFailures = 0;
+    rapidRefills = 0;
+    turn = 0;
+    lastSummaryTurn;
+    prefixOverflow = false;
     enabled;
     contextWindow;
     constructor(enabled, contextWindow) {
@@ -22,15 +32,23 @@ export class CompactionBreaker {
         this.enabled = enabled;
         this.contextWindow = contextWindow;
     }
+    /** 连续失败或快速回填跳闸（溢出恢复也不再尝试）。 */
     get tripped() {
-        return this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES;
+        return (this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES || this.rapidRefills >= MAX_RAPID_REFILLS);
     }
-    /** 自动压缩整体是否开启（不看本 run 计数）。 */
+    /** 自动压缩整体是否开启。 */
     get autoEnabled() {
         return this.enabled && this.contextWindow !== undefined && !this.tripped;
     }
-    startRun() {
-        this.summariesThisRun = 0;
+    /** 新 run 开始（会话在 agent_start 时调用）；不再重置任何计数，保留以兼容调用点。 */
+    startRun() { }
+    /** 每次请求前的阈值检查调用一次：回合计数（快速回填按它判断）。 */
+    tick() {
+        this.turn++;
+    }
+    /** 固定前缀是否已超预算（调用方每次准备摘要前更新）。 */
+    setPrefixOverflow(overflow) {
+        this.prefixOverflow = overflow;
     }
     /** 自动档二能否执行；不能则给出原因。 */
     blockReason() {
@@ -38,23 +56,35 @@ export class CompactionBreaker {
             return "disabled";
         if (this.contextWindow === undefined)
             return "no_window";
-        if (this.tripped)
+        if (this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES)
             return "tripped";
-        if (this.summariesThisRun >= MAX_SUMMARIES_PER_RUN)
-            return "run_limit";
+        if (this.rapidRefills >= MAX_RAPID_REFILLS)
+            return "rapid_refill";
+        if (this.prefixOverflow)
+            return "prefix_overflow";
         return undefined;
     }
     canSummarize() {
         return this.blockReason() === undefined;
     }
     recordSummary(success) {
-        this.summariesThisRun++;
-        this.consecutiveFailures = success ? 0 : this.consecutiveFailures + 1;
+        if (!success) {
+            this.consecutiveFailures++;
+            return;
+        }
+        this.consecutiveFailures = 0;
+        const last = this.lastSummaryTurn;
+        if (last !== undefined && this.turn - last < RAPID_REFILL_TURNS)
+            this.rapidRefills++;
+        else
+            this.rapidRefills = 0;
+        this.lastSummaryTurn = this.turn;
     }
-    /** 手动压缩成功等场景：清零失败计数。 */
+    /** 手动压缩成功等场景：清零全部计数。 */
     reset() {
         this.consecutiveFailures = 0;
-        this.summariesThisRun = 0;
+        this.rapidRefills = 0;
+        this.lastSummaryTurn = undefined;
     }
     /** 溢出恢复后是否值得重试。 */
     shouldRetryAfterCompaction(tokensAfter) {

package/dist/compaction/estimate.d.ts

@@ -2,15 +2,23 @@
  * 上下文 token 估算（设计 §9「估算」）。[B2]
  *
  * `contextTokens` = 最后一条非 error / aborted 助手消息的 `totalTokens`（缺则
- * `input + output + cacheRead + cacheWrite`，**含 output**）+ 其后消息的估算（字符 / 4，图片 1 600）。
+ * `input + output + cacheRead + cacheWrite`，**含 output**）+ 其后消息的估算（图片 1 600）。
  * 若该 usage 之后活动分支上出现过 `context_edit` 或 `compaction`，usage 不再可信，按投影全量重估。
+ *
+ * [W5-H1] 文本估算按脚本区分（wave5 D28 / C10）：CJK 统一表意文字（含扩展区与兼容区）、假名、
+ * 谚文、CJK 符号与全角形式每字 1 token，其余字符合计 / 4 向上取整。「字符 / 4」对中文低估 3–4 倍，
+ * 中文会话会晚触发直至溢出；所有阈值（档一、档二、保留区）都用这个口径。
  */
-import type { Usage } from "../ai/types.js";
+import type { ContentBlock, Usage } from "../ai/types.js";
 import type { ContextItem } from "../session/projection.js";
 import type { AgentMessage, SessionEntry } from "../session/types.js";
 export declare const IMAGE_TOKENS = 1600;
+/** 文本的 token 估算：CJK / 假名 / 谚文每字 1，其余字符 / 4（向上取整）。 */
+export declare function estimateTextTokens(text: string): number;
 export declare function calculateContextTokens(usage: Usage): number;
-/** 单条消息的估算（字符 / 4 向上取整，图片每张 1 600）。 */
+/** 内容的估算（文本按脚本，图片每张 1 600）。 */
+export declare function estimateContentTokens(content: string | readonly ContentBlock[]): number;
+/** 单条消息的估算（文本按脚本区分，图片每张 1 600）。 */
 export declare function estimateMessageTokens(message: AgentMessage): number;
 export declare function estimateMessagesTokens(messages: readonly AgentMessage[]): number;
 export interface ContextEstimate {