@armadra/agent 0.4.0 → 0.5.1

package/dist/cli/subcommands/models-cache-probe.js

@@ -7,12 +7,12 @@
  * （字段缺失或恒 0）；其余（读到一点、只有写入）→ `inconclusive`（粒度或 TTL 问题）。
  *
  * 计费动作：执行前打印预估（两次 × `--tokens` × 目录输入价，无价 `$?`）；非 TTY 必须 `--yes`
- * （否则退出 2），TTY 下问一次 y/N。`--json` 时预估写 stderr，stdout 只有一个结果对象。
+ * （否则退出 2），TTY 下方向键选一次「继续 / 取消」（choice-prompt.ts）。`--json` 时预估写 stderr，stdout 只有一个结果对象。
  * 协议层不保留原始响应，「usage 字段」列的是该协议解析时读取的字段名。
  */
-import { createInterface } from "node:readline/promises";
 import { priceTokens } from "../../ai/cost.js";
 import { UsageError } from "../args.js";
+import { confirmContinue } from "../choice-prompt.js";
 import { ExitCode } from "../exit-codes.js";
 export const PROBE_DEFAULT_TOKENS = 2048;
 export const PROBE_DEFAULT_GAP_MS = 3000;
@@ -78,15 +78,6 @@ function intOption(ctx, name, fallback, min) {
         throw new UsageError(`--${name} 应为不小于 ${min} 的整数`);
     return value;
 }
-async function confirm() {
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
-    try {
-        return /^y(es)?$/i.test((await rl.question("继续？[y/N] ")).trim());
-    }
-    finally {
-        rl.close();
-    }
-}
 function sampleLine(index, s) {
     const field = s.cacheReported === undefined ? "?" : s.cacheReported ? "有" : "无";
     return `#${index}  input ${s.input} · cacheRead ${s.cacheRead} · cacheWrite ${s.cacheWrite} · 缓存字段 ${field}`;
@@ -122,7 +113,7 @@ async function run(ctx) {
             io.stderr("ama: cache-probe 会发两次计费请求，非交互环境需加 --yes\n");
             return ExitCode.Usage;
         }
-        if (!(await confirm())) {
+        if (!(await confirmContinue({ env: io.env }))) {
             io.stderr("ama: 已取消\n");
             return ExitCode.Ok;
         }

package/dist/cli/subcommands/models-discover.js

@@ -20,7 +20,7 @@
 import { authHeaders, mergeHeaders } from "../../ai/http.js";
 import { discoverLocalModels, materializeModel } from "../../ai/providers/registry.js";
 import { withCustomDefaults } from "../../ai/providers/catalog.js";
-import { describeRefresh, refreshModelsDev } from "../../ai/providers/models-dev-cache.js";
+import { describeModelsDev, loadModelsDevIndex } from "../../ai/providers/models-dev-cache.js";
 import { matchLabel, modelsDevFields } from "../../ai/providers/models-dev.js";
 import { existsSync } from "node:fs";
 import { loadConfigFile } from "../../config/load.js";
@@ -173,15 +173,14 @@ async function run(ctx) {
     }
     const configured = new Map(provider.models.map((m) => [m.id, m]));
     io.stdout(`${provider.id}：发现 ${found.length} 个模型（${modelsUrl(provider)}）\n`);
-    const md = await refreshModelsDev({ dataDir: ctx.level.dataDir, env: io.env });
-    io.stdout(`${describeRefresh(md)}\n`);
-    if (md.warning !== undefined)
-        io.stderr(`ama: 警告：${md.warning}\n`);
+    // models.dev 只读本地（快照 ⊕ `ama models refresh` 的覆盖），不联网。
+    const mdIndex = loadModelsDevIndex(ctx.level.dataDir);
+    io.stdout(`${describeModelsDev(ctx.level.dataDir)}\n`);
     const noTools = new Set();
     const unmatched = new Set();
     for (const model of found) {
         const known = configured.get(model.id);
-        const match = md.index?.match(model.id);
+        const match = mdIndex.match(model.id);
         const fields = match !== undefined ? modelsDevFields(match.model) : undefined;
         if (fields?.toolCall === false)
             noTools.add(model.id);

package/dist/cli/subcommands/models.d.ts

@@ -7,6 +7,8 @@
  * [W3-C0] 子命令分派改为动作表 `MODELS_ACTIONS`（第三波 §1.11 / §2.3）：新动作（C2 的
  * `cache-probe`、B12 的 `discover`）各写在自己的文件里，这里只加一行表项；用法文本、
  * 选项表与必填位置参数都从表里来。
+ *
+ * [W5-M1] `refresh`：models.dev 显式刷新（`refresh-catalog` 保留为别名）。
  */
 import type { ProviderRegistryApi } from "../../ai/types.js";
 import type { CliIo, RuntimeDeps } from "../deps.js";

package/dist/cli/subcommands/models.js

@@ -7,9 +7,12 @@
  * [W3-C0] 子命令分派改为动作表 `MODELS_ACTIONS`（第三波 §1.11 / §2.3）：新动作（C2 的
  * `cache-probe`、B12 的 `discover`）各写在自己的文件里，这里只加一行表项；用法文本、
  * 选项表与必填位置参数都从表里来。
+ *
+ * [W5-M1] `refresh`：models.dev 显式刷新（`refresh-catalog` 保留为别名）。
  */
 import { formatModelRef, modelRefOf } from "../../ai/providers/channels.js";
 import { describeRefresh, modelsDevCachePath, refreshModelsDev, } from "../../ai/providers/models-dev-cache.js";
+import { snapshotMeta } from "../../ai/providers/models-dev-snapshot.js";
 import { parseSubArgs, UsageError } from "../args.js";
 import { ExitCode } from "../exit-codes.js";
 import { buildRegistry, loadUserLevel } from "./context.js";
@@ -78,6 +81,34 @@ async function check(io, registry, ref) {
     io.stdout(`${shown} 可用（${model.api}，${ms} ms，stopReason ${message.stopReason}）\n`);
     return ExitCode.Ok;
 }
+/**
+ * `ama models refresh [--provider <id>[,<id>…]]`：显式联网拉 models.dev，按内置快照的清单裁剪，
+ * 写用户级覆盖 `<dataDir>/models-dev.json`（docs/providers.md「模型元数据」）。启动与其它命令不联网。
+ */
+const REFRESH_ACTION = {
+    usage: "ama models refresh [--provider <id>[,<id>…]]",
+    valueOptions: ["provider"],
+    run: async (ctx) => {
+        const only = ctx.values.get("provider");
+        const providers = only
+            ?.split(",")
+            .map((p) => p.trim())
+            .filter(Boolean);
+        ctx.io.stdout(`内置快照：${snapshotMeta().fetchedAt}；正在拉取 models.dev…\n`);
+        const result = await refreshModelsDev({
+            dataDir: ctx.level.dataDir,
+            env: ctx.io.env,
+            ...(providers !== undefined && providers.length > 0 ? { providers } : {}),
+        });
+        if (result.warning !== undefined)
+            ctx.io.stderr(`ama: ${result.warning}\n`);
+        ctx.io.stdout(`${describeRefresh(result)}\n`);
+        if (result.status === "failed")
+            return ExitCode.RuntimeError;
+        ctx.io.stdout(`已写入 ${modelsDevCachePath(ctx.level.dataDir)}\n`);
+        return ExitCode.Ok;
+    },
+};
 /** 动作表：键是子命令名，顺序即用法文本顺序。 */
 export const MODELS_ACTIONS = Object.freeze({
     list: {
@@ -92,20 +123,8 @@ export const MODELS_ACTIONS = Object.freeze({
     },
     discover: DISCOVER_ACTION,
     "cache-probe": CACHE_PROBE_ACTION,
-    "refresh-catalog": {
-        usage: "ama models refresh-catalog",
-        run: async (ctx) => {
-            const result = await refreshModelsDev({
-                dataDir: ctx.level.dataDir,
-                env: ctx.io.env,
-                force: true,
-            });
-            ctx.io.stdout(`${describeRefresh(result)}\n${modelsDevCachePath(ctx.level.dataDir)}\n`);
-            if (result.warning !== undefined)
-                ctx.io.stderr(`ama: 警告：${result.warning}\n`);
-            return result.status === "unavailable" ? ExitCode.RuntimeError : ExitCode.Ok;
-        },
-    },
+    refresh: REFRESH_ACTION,
+    "refresh-catalog": { ...REFRESH_ACTION, usage: "ama models refresh-catalog（refresh 的旧名）" },
 });
 export const MODELS_USAGE = `用法：${Object.values(MODELS_ACTIONS)
     .map((a) => a.usage)

package/dist/cli/subcommands/providers.d.ts

@@ -8,7 +8,7 @@
  * - list / channels：供应商 → 渠道 → 模型数与 key 来源（从不显示 key）。remove：删配置与 auth.json 条目。
  *
  * 计费：`--probe` 每模型每渠道一次最小请求（并发执行，见到首个流事件即判可用并断开，见
- * probe-runner.ts）；执行前打印预估，TTY 问 y/N，非 TTY 必须 `--yes`。
+ * probe-runner.ts）；执行前打印预估，TTY 下方向键选「继续 / 取消」（choice-prompt.ts，y / n 直选），非 TTY 必须 `--yes`。
  */
 import type { AmaConfig } from "../../config/types.js";
 import type { CliIo, RuntimeDeps } from "../deps.js";

package/dist/cli/subcommands/providers.js

@@ -8,17 +8,17 @@
  * - list / channels：供应商 → 渠道 → 模型数与 key 来源（从不显示 key）。remove：删配置与 auth.json 条目。
  *
  * 计费：`--probe` 每模型每渠道一次最小请求（并发执行，见到首个流事件即判可用并断开，见
- * probe-runner.ts）；执行前打印预估，TTY 问 y/N，非 TTY 必须 `--yes`。
+ * probe-runner.ts）；执行前打印预估，TTY 下方向键选「继续 / 取消」（choice-prompt.ts，y / n 直选），非 TTY 必须 `--yes`。
  */
 import { existsSync } from "node:fs";
-import { createInterface } from "node:readline/promises";
-import { describeRefresh, refreshModelsDev } from "../../ai/providers/models-dev-cache.js";
+import { describeModelsDev, loadModelsDevIndex } from "../../ai/providers/models-dev-cache.js";
 import { modelsDevFields } from "../../ai/providers/models-dev.js";
 import { PROVIDER_ID_PATTERN, setAuthKey } from "../../config/auth-file.js";
 import { loadConfigFile } from "../../config/load.js";
 import { CONFIG_FILE_VERSION } from "../../config/types.js";
 import { writeConfigFile } from "../../config/write.js";
 import { parseSubArgs, UsageError } from "../args.js";
+import { confirmContinue } from "../choice-prompt.js";
 import { pickByPrice } from "../default-model.js";
 import { ExitCode } from "../exit-codes.js";
 import { extractKey } from "./auth.js";
@@ -76,13 +76,7 @@ export function userConfig(level) {
 }
 async function confirm(io, question) {
     io.stderr(question);
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
-    try {
-        return /^y(es)?$/i.test((await rl.question("继续？[y/N] ")).trim());
-    }
-    finally {
-        rl.close();
-    }
+    return confirmContinue({ env: io.env });
 }
 /** --yes / TTY 确认；非 TTY 且没有 --yes 返回 false 并提示（调用方退出 2）。 */
 async function approved(ctx, what) {
@@ -260,17 +254,16 @@ async function add(ctx, id, refresh) {
         return ExitCode.RuntimeError;
     }
     io.stdout(`${id}：发现 ${listed.length} 个模型（${target.url}）\n`);
-    const md = await refreshModelsDev({ dataDir: level.dataDir, env: io.env, force: refresh });
-    io.stdout(`${describeRefresh(md)}\n`);
-    if (md.warning !== undefined)
-        io.stderr(`ama: 警告：${md.warning}\n`);
+    // models.dev 只读本地（快照 ⊕ `ama models refresh` 的覆盖），不联网。
+    const mdIndex = loadModelsDevIndex(level.dataDir);
+    io.stdout(`${describeModelsDev(level.dataDir)}\n`);
     io.stdout(`候选渠道：${candidates.map((c) => `${c.name}（${c.api} ${c.baseUrl}）`).join(" · ")}\n`);
     const existingIds = new Set((existing?.models ?? []).map((m) => m.id));
     const result = await plan(ctx, {
         id,
         candidates,
         listed,
-        index: md.index,
+        index: mdIndex,
         existingIds,
         apiKey: key.apiKey,
         registry,

package/dist/cli/subcommands/sessions.d.ts

@@ -5,7 +5,9 @@
  * - 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 type { CliIo, RuntimeDeps } from "../deps.js";
 export declare const SESSIONS_USAGE = "\u7528\u6CD5\uFF1Aama sessions list [--all] [--session-dir <\u76EE\u5F55>]\n      ama sessions show <id> [--session-dir <\u76EE\u5F55>]\n      ama sessions prune [--older-than <\u5929>] [--dry-run] [--all] [--session-dir <\u76EE\u5F55>]\n      ama sessions search <\u5173\u952E\u8BCD|/\u6B63\u5219/> [--all] [--role user|assistant|tool] [--since 7d] [--limit N]\n      ama sessions export <id> [--format md|json|jsonl] [--output <\u6587\u4EF6>] [--branch leaf|all]\n";

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;