@armadra/agent 0.8.0 → 0.9.0

package/dist/checkpoints/backend.js

@@ -21,6 +21,8 @@ export function createCheckpointBackendFactory(settings) {
             return undefined;
         let tracker;
         let registered = false;
+        // 登记会话根目录的写入（mkdir → tmp → rename）；snapshot 等它结束，收尾时不会还有文件在落盘
+        let registering = Promise.resolve();
         const warn = (message) => ctx.log("warn", message);
         const get = () => {
             tracker ??= new CheckpointTracker({
@@ -34,7 +36,7 @@ export function createCheckpointBackendFactory(settings) {
             });
             if (!registered && settings.sessionsRoot !== undefined) {
                 registered = true;
-                registerSessionRoot(settings.dataDir, settings.sessionsRoot).catch((error) => ctx.log("debug", msg().session.checkpoints.registerFailed(String(error))));
+                registering = registerSessionRoot(settings.dataDir, settings.sessionsRoot).catch((error) => ctx.log("debug", msg().session.checkpoints.registerFailed(String(error))));
             }
             return tracker;
         };
@@ -79,6 +81,9 @@ export function createCheckpointBackendFactory(settings) {
             hooks,
             snapshot: async (userEntryId) => {
                 try {
+                    // 先让登记写完再记检查点：检查点条目落盘之后请求马上发出，不能再被它拖住
+                    get();
+                    await registering;
                     const shadowCommit = await shadowSnapshot(userEntryId);
                     await get().snapshot(userEntryId, shadowCommit !== undefined ? { shadowCommit } : {});
                 }

package/dist/checkpoints/blobs.d.ts

@@ -1,5 +1,5 @@
 /**
- * 检查点备份存储（docs/rewind-plan.md §1.1）。[RW-A]
+ * 检查点备份存储（docs/history/rewind-plan.md §1.1）。[RW-A]
  *
  * - 位置 `<dataDir>/file-history/blobs/<sha256 前 2 位>/<sha256>`，内容为文件原字节；
  *   先写 `<name>.tmp-<pid>-<序号>` 再 rename，已存在即跳过（内容寻址，同内容只存一份）。

package/dist/checkpoints/blobs.js

@@ -1,5 +1,5 @@
 /**
- * 检查点备份存储（docs/rewind-plan.md §1.1）。[RW-A]
+ * 检查点备份存储（docs/history/rewind-plan.md §1.1）。[RW-A]
  *
  * - 位置 `<dataDir>/file-history/blobs/<sha256 前 2 位>/<sha256>`，内容为文件原字节；
  *   先写 `<name>.tmp-<pid>-<序号>` 再 rename，已存在即跳过（内容寻址，同内容只存一份）。

package/dist/checkpoints/gc.d.ts

@@ -1,5 +1,5 @@
 /**
- * 备份清理（docs/rewind-plan.md §1.4）。[RW-A]
+ * 备份清理（docs/history/rewind-plan.md §1.4）。[RW-A]
  *
  * - 标记：递归扫描会话根目录下全部 `*.jsonl`（含 `.trash/`，trash 里的会话还能找回），凡含
  *   `ama.checkpoint` 的行，取其中所有 64 位十六进制串作为引用。不解析 JSON：损坏或未来格式的行也只会

package/dist/checkpoints/gc.js

@@ -1,5 +1,5 @@
 /**
- * 备份清理（docs/rewind-plan.md §1.4）。[RW-A]
+ * 备份清理（docs/history/rewind-plan.md §1.4）。[RW-A]
  *
  * - 标记：递归扫描会话根目录下全部 `*.jsonl`（含 `.trash/`，trash 里的会话还能找回），凡含
  *   `ama.checkpoint` 的行，取其中所有 64 位十六进制串作为引用。不解析 JSON：损坏或未来格式的行也只会

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

@@ -1,5 +1,5 @@
 /**
- * 读 git HEAD（docs/rewind-plan.md §1.2、D6）。[RW-A]
+ * 读 git HEAD（docs/history/rewind-plan.md §1.2、D6）。[RW-A]
  *
  * 不起 git 进程：从 cwd 向上找 `.git`（目录，或 worktree / 子模块的 `gitdir: <路径>` 文件），读 `HEAD`；
  * 符号引用先查 gitdir 再查 `commondir`（worktree 的分支引用在主仓库），最后查 `packed-refs`。

package/dist/checkpoints/git-head.js

@@ -1,5 +1,5 @@
 /**
- * 读 git HEAD（docs/rewind-plan.md §1.2、D6）。[RW-A]
+ * 读 git HEAD（docs/history/rewind-plan.md §1.2、D6）。[RW-A]
  *
  * 不起 git 进程：从 cwd 向上找 `.git`（目录，或 worktree / 子模块的 `gitdir: <路径>` 文件），读 `HEAD`；
  * 符号引用先查 gitdir 再查 `commondir`（worktree 的分支引用在主仓库），最后查 `packed-refs`。

package/dist/checkpoints/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * 检查点（docs/rewind-plan.md）的对外入口。[RW-A]
+ * 检查点（docs/history/rewind-plan.md）的对外入口。[RW-A]
  *
  * 会话接线（RW-B）用 `createCheckpointBackendFactory` + `resolveCheckpointSettings`；
  * 其余导出给 CLI（GC、占用）与测试。

package/dist/checkpoints/index.js

@@ -1,5 +1,5 @@
 /**
- * 检查点（docs/rewind-plan.md）的对外入口。[RW-A]
+ * 检查点（docs/history/rewind-plan.md）的对外入口。[RW-A]
  *
  * 会话接线（RW-B）用 `createCheckpointBackendFactory` + `resolveCheckpointSettings`；
  * 其余导出给 CLI（GC、占用）与测试。

package/dist/checkpoints/replay.d.ts

@@ -1,5 +1,5 @@
 /**
- * 从会话条目重建检查点（docs/rewind-plan.md §1.2）。[RW-A]
+ * 从会话条目重建检查点（docs/history/rewind-plan.md §1.2）。[RW-A]
  *
  * - 按文件顺序重放全部条目（不限活动分支）里的 `ama.checkpoint` 与 `ama.checkpoint-track`；
  *   track 并入对应 userEntryId 的检查点（检查点里已有该文件时不覆盖）。

package/dist/checkpoints/replay.js

@@ -1,5 +1,5 @@
 /**
- * 从会话条目重建检查点（docs/rewind-plan.md §1.2）。[RW-A]
+ * 从会话条目重建检查点（docs/history/rewind-plan.md §1.2）。[RW-A]
  *
  * - 按文件顺序重放全部条目（不限活动分支）里的 `ama.checkpoint` 与 `ama.checkpoint-track`；
  *   track 并入对应 userEntryId 的检查点（检查点里已有该文件时不覆盖）。

package/dist/checkpoints/restore.d.ts

@@ -1,5 +1,5 @@
 /**
- * 恢复代码（docs/rewind-plan.md §3.2）。[RW-A]
+ * 恢复代码（docs/history/rewind-plan.md §3.2）。[RW-A]
  *
  * 对每个已跟踪文件，取目标检查点里的记录，没有则取该文件最早的记录：
  * 1. 记录 `skipped` → 报告 too_large / not_regular；

package/dist/checkpoints/restore.js

@@ -1,5 +1,5 @@
 /**
- * 恢复代码（docs/rewind-plan.md §3.2）。[RW-A]
+ * 恢复代码（docs/history/rewind-plan.md §3.2）。[RW-A]
  *
  * 对每个已跟踪文件，取目标检查点里的记录，没有则取该文件最早的记录：
  * 1. 记录 `skipped` → 报告 too_large / not_regular；

package/dist/checkpoints/settings.d.ts

@@ -1,5 +1,5 @@
 /**
- * 检查点配置解析（docs/rewind-plan.md §5）。[RW-A]
+ * 检查点配置解析（docs/history/rewind-plan.md §5）。[RW-A]
  *
  * `AMA_CHECKPOINTS`（tools | shadow-git | off）> config `checkpoints.mode` > 缺省 tools；
  * 无效的环境变量值 warn 后忽略。`maxFileBytes` / `keep` 取配置，缺省 5 MiB / 100。

package/dist/checkpoints/settings.js

@@ -1,5 +1,5 @@
 /**
- * 检查点配置解析（docs/rewind-plan.md §5）。[RW-A]
+ * 检查点配置解析（docs/history/rewind-plan.md §5）。[RW-A]
  *
  * `AMA_CHECKPOINTS`（tools | shadow-git | off）> config `checkpoints.mode` > 缺省 tools；
  * 无效的环境变量值 warn 后忽略。`maxFileBytes` / `keep` 取配置，缺省 5 MiB / 100。

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

@@ -1,5 +1,5 @@
 /**
- * 影子 git 仓库（docs/rewind-plan.md §6）。[RW-D]
+ * 影子 git 仓库（docs/history/rewind-plan.md §6）。[RW-D]
  *
  * - 位置 `<dataDir>/file-history/shadow/<sha256(cwd) 前 16>/`，用 `--git-dir` 指向它、`--work-tree` 指向 cwd；
  *   不碰用户仓库的对象、索引与引用。git 以子进程调用（零运行时依赖）。

package/dist/checkpoints/shadow-git.js

@@ -1,5 +1,5 @@
 /**
- * 影子 git 仓库（docs/rewind-plan.md §6）。[RW-D]
+ * 影子 git 仓库（docs/history/rewind-plan.md §6）。[RW-D]
  *
  * - 位置 `<dataDir>/file-history/shadow/<sha256(cwd) 前 16>/`，用 `--git-dir` 指向它、`--work-tree` 指向 cwd；
  *   不碰用户仓库的对象、索引与引用。git 以子进程调用（零运行时依赖）。

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

@@ -1,5 +1,5 @@
 /**
- * 按影子提交恢复代码（docs/rewind-plan.md §6）。[RW-D]
+ * 按影子提交恢复代码（docs/history/rewind-plan.md §6）。[RW-D]
  *
  * 1. 把当前工作区写成树，与目标提交做 `diff-tree`：只处理有差异的文件，被忽略的文件不在两边的树里，不会被碰。
  *    目标里有、当前树里没有但磁盘上还在的文件（现在被忽略了）跳过。

package/dist/checkpoints/shadow-restore.js

@@ -1,5 +1,5 @@
 /**
- * 按影子提交恢复代码（docs/rewind-plan.md §6）。[RW-D]
+ * 按影子提交恢复代码（docs/history/rewind-plan.md §6）。[RW-D]
  *
  * 1. 把当前工作区写成树，与目标提交做 `diff-tree`：只处理有差异的文件，被忽略的文件不在两边的树里，不会被碰。
  *    目标里有、当前树里没有但磁盘上还在的文件（现在被忽略了）跳过。

package/dist/checkpoints/tracker.d.ts

@@ -1,5 +1,5 @@
 /**
- * 检查点运行时状态（docs/rewind-plan.md §1.3、§2）。[RW-A]
+ * 检查点运行时状态（docs/history/rewind-plan.md §1.3、§2）。[RW-A]
  *
  * - `beforeWrite`：文件在任何检查点里都没出现过 → 备份当前内容、追加 `ama.checkpoint-track`、
  *   加入已跟踪；出现过则什么都不做。失败只 warn，不抛（检查点是辅助，不能让编辑失败）。

package/dist/checkpoints/tracker.js

@@ -1,5 +1,5 @@
 /**
- * 检查点运行时状态（docs/rewind-plan.md §1.3、§2）。[RW-A]
+ * 检查点运行时状态（docs/history/rewind-plan.md §1.3、§2）。[RW-A]
  *
  * - `beforeWrite`：文件在任何检查点里都没出现过 → 备份当前内容、追加 `ama.checkpoint-track`、
  *   加入已跟踪；出现过则什么都不做。失败只 warn，不抛（检查点是辅助，不能让编辑失败）。

package/dist/checkpoints/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * 检查点与回滚契约（docs/rewind-plan.md §1、§3）。契约文件，实现归 RW-A（`src/checkpoints/**`）
+ * 检查点与回滚契约（docs/history/rewind-plan.md §1、§3）。契约文件，实现归 RW-A（`src/checkpoints/**`）
  * 与 RW-B（`src/agent/session-rewind.ts`）。
  *
  * - 会话条目两类，均为 `custom`（不进上下文）：`ama.checkpoint`（新回合的用户消息之后）与

package/dist/checkpoints/types.js

@@ -1,5 +1,5 @@
 /**
- * 检查点与回滚契约（docs/rewind-plan.md §1、§3）。契约文件，实现归 RW-A（`src/checkpoints/**`）
+ * 检查点与回滚契约（docs/history/rewind-plan.md §1、§3）。契约文件，实现归 RW-A（`src/checkpoints/**`）
  * 与 RW-B（`src/agent/session-rewind.ts`）。
  *
  * - 会话条目两类，均为 `custom`（不进上下文）：`ama.checkpoint`（新回合的用户消息之后）与

package/dist/cli/args.d.ts

@@ -82,7 +82,7 @@ export interface ParsedArgs {
     prompt?: string;
     /** 原始位置参数。 */
     positionals: string[];
-    /** [W6-C0] `--lang zh|en`：界面语言（`AMA_LANG` 优先，docs/i18n.md）。 */
+    /** [W6-C0] `--lang zh|en`：界面语言（`AMA_LANG` 优先，docs/guides/i18n.md）。 */
     lang?: Locale;
     /** [W6-C0] `--memory` → true、`--no-memory` → false：覆盖 `memory.enabled`（W6-M）。 */
     memory?: boolean;
@@ -102,7 +102,7 @@ export declare class UsageError extends AmaError {
 export { helpText } from "./help-text.js";
 export declare function emptyArgs(): ParsedArgs;
 /**
- * ACP terminal 型认证方法的入口（docs/acp.md「无模型时」）：客户端把方法的 `args` **追加**到配置好的
+ * ACP terminal 型认证方法的入口（docs/reference/acp.md「无模型时」）：客户端把方法的 `args` **追加**到配置好的
  * Agent 启动命令后面（规范原文 append），实际得到 `ama --mode acp … --acp-terminal-auth <id>`。
  * 见到这个标志就不再按启动参数解析，转成对应的 `auth` 子命令；同一条命令里的 `--auth-file`、`--lang` 一并带上。
  */

package/dist/cli/args.js

@@ -312,7 +312,7 @@ function validate(args) {
     }
 }
 /**
- * ACP terminal 型认证方法的入口（docs/acp.md「无模型时」）：客户端把方法的 `args` **追加**到配置好的
+ * ACP terminal 型认证方法的入口（docs/reference/acp.md「无模型时」）：客户端把方法的 `args` **追加**到配置好的
  * Agent 启动命令后面（规范原文 append），实际得到 `ama --mode acp … --acp-terminal-auth <id>`。
  * 见到这个标志就不再按启动参数解析，转成对应的 `auth` 子命令；同一条命令里的 `--auth-file`、`--lang` 一并带上。
  */

package/dist/cli/bootstrap.js

@@ -416,7 +416,7 @@ export async function runCli(argv, deps, io) {
     }
     catch (error) {
         try {
-            // [ACP-A] --mode acp 没有可用模型：认证门照常握手，会话方法重试 bootstrap（docs/acp-plan.md §2.2）
+            // [ACP-A] --mode acp 没有可用模型：认证门照常握手，会话方法重试 bootstrap（docs/history/acp-plan.md §2.2）
             if (acp && error instanceof StartupError && error.exitCode === ExitCode.NoModel)
                 return await (await import("../modes/acp/acp-auth-gate.js")).runAcpAuthGate(args, deps, io, error);
             return reportError(error, io);

package/dist/cli/choice-prompt.d.ts

@@ -5,7 +5,7 @@
  *   Esc / Ctrl+C / stdin 结束 = 取消；
  * - 结束后把列表收成一行「? 问题 答案」，恢复 raw 状态与光标，暂停 stdin；进程意外退出时也恢复；
  * - 颜色与字形按环境：`NO_COLOR` / 非 TTY 输出无色，`AMA_ASCII` / 区域设置决定 ASCII 字形（字形表见
- *   docs/tui-design.md §2.2）；
+ *   docs/design/tui-design.md §2.2）；
  * - 输入不是可开 raw 的 TTY（管道、CI）时 {@link confirmContinue} 回落为原来的文本 `[y/N]` 问答。
  */
 export interface ChoiceInput {

package/dist/cli/choice-prompt.js

@@ -5,7 +5,7 @@
  *   Esc / Ctrl+C / stdin 结束 = 取消；
  * - 结束后把列表收成一行「? 问题 答案」，恢复 raw 状态与光标，暂停 stdin；进程意外退出时也恢复；
  * - 颜色与字形按环境：`NO_COLOR` / 非 TTY 输出无色，`AMA_ASCII` / 区域设置决定 ASCII 字形（字形表见
- *   docs/tui-design.md §2.2）；
+ *   docs/design/tui-design.md §2.2）；
  * - 输入不是可开 raw 的 TTY（管道、CI）时 {@link confirmContinue} 回落为原来的文本 `[y/N]` 问答。
  */
 import { createInterface } from "node:readline/promises";

package/dist/cli/codemode-notice.d.ts

@@ -1,6 +1,6 @@
 /**
  * codemode 缺省关闭的一次性提示（设计 §5.5「默认开放」）：`default` 预设跟随预设时只在沙箱 strict
- * （Node ≥ 25，或有可用的操作系统沙箱，docs/sandbox.md）开 codemode；否则缺省关闭，启动时提示一次
+ * （Node ≥ 25，或有可用的操作系统沙箱，docs/guides/sandbox.md）开 codemode；否则缺省关闭，启动时提示一次
  * 怎么显式开启。
  *
  * - 只在「跟随预设」且预设是 `default`、运行时不是 strict 时提示；显式写了 `codemode.mode`（含 off）

package/dist/cli/codemode-notice.js

@@ -1,6 +1,6 @@
 /**
  * codemode 缺省关闭的一次性提示（设计 §5.5「默认开放」）：`default` 预设跟随预设时只在沙箱 strict
- * （Node ≥ 25，或有可用的操作系统沙箱，docs/sandbox.md）开 codemode；否则缺省关闭，启动时提示一次
+ * （Node ≥ 25，或有可用的操作系统沙箱，docs/guides/sandbox.md）开 codemode；否则缺省关闭，启动时提示一次
  * 怎么显式开启。
  *
  * - 只在「跟随预设」且预设是 `default`、运行时不是 strict 时提示；显式写了 `codemode.mode`（含 off）

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

@@ -1,5 +1,5 @@
 /**
- * 子 Agent 的组装（docs/wave5-plan.md §7.1、§7.4，D22–D24）。[W5-G]
+ * 子 Agent 的组装（docs/history/wave5-plan.md §7.1、§7.4，D22–D24）。[W5-G]
  *
  * 由 compose-extensions.ts 的一行接入：每次装配会话时发现定义文件（`--agent-dir` / profile
  * `agentDirs` → config `agents.dirs` → 用户级 → 项目级（需信任）），建类型目录并绑到 task 工具

package/dist/cli/compose-agents.js

@@ -1,5 +1,5 @@
 /**
- * 子 Agent 的组装（docs/wave5-plan.md §7.1、§7.4，D22–D24）。[W5-G]
+ * 子 Agent 的组装（docs/history/wave5-plan.md §7.1、§7.4，D22–D24）。[W5-G]
  *
  * 由 compose-extensions.ts 的一行接入：每次装配会话时发现定义文件（`--agent-dir` / profile
  * `agentDirs` → config `agents.dirs` → 用户级 → 项目级（需信任）），建类型目录并绑到 task 工具

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

@@ -1,5 +1,5 @@
 /**
- * 会话扩展的组装表（docs/wave5-plan.md §10.1，D30）。[W5-C0]
+ * 会话扩展的组装表（docs/history/wave5-plan.md §10.1，D30）。[W5-C0]
  *
  * 唯一允许多个批次各加一行的文件：每个批次在 `composeExtensions` 的数组里追加**一行**自己的工厂，
  * 实现放在各自文件（`src/agent/session-<名>.ts` 等）。表顺序即调用顺序：

package/dist/cli/compose-extensions.js

@@ -1,5 +1,5 @@
 /**
- * 会话扩展的组装表（docs/wave5-plan.md §10.1，D30）。[W5-C0]
+ * 会话扩展的组装表（docs/history/wave5-plan.md §10.1，D30）。[W5-C0]
  *
  * 唯一允许多个批次各加一行的文件：每个批次在 `composeExtensions` 的数组里追加**一行**自己的工厂，
  * 实现放在各自文件（`src/agent/session-<名>.ts` 等）。表顺序即调用顺序：

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

@@ -1,5 +1,5 @@
 /**
- * 记忆的组装（docs/wave6-plan.md §3、D8、D9、D11、D12）。[W6-M]
+ * 记忆的组装（docs/history/wave6-plan.md §3、D8、D9、D11、D12）。[W6-M]
  *
  * - 开关：独立终端看合并后的 `memory.enabled`（用户级 / profile.config；项目级只能设 false；`--memory` /
  *   `--no-memory`；`AMA_MEMORY=0|1` 经 bootstrap 并入命令行覆盖，命令行优先）。缺省关闭：不建运行期、不读盘、

package/dist/cli/compose-memory.js

@@ -1,5 +1,5 @@
 /**
- * 记忆的组装（docs/wave6-plan.md §3、D8、D9、D11、D12）。[W6-M]
+ * 记忆的组装（docs/history/wave6-plan.md §3、D8、D9、D11、D12）。[W6-M]
  *
  * - 开关：独立终端看合并后的 `memory.enabled`（用户级 / profile.config；项目级只能设 false；`--memory` /
  *   `--no-memory`；`AMA_MEMORY=0|1` 经 bootstrap 并入命令行覆盖，命令行优先）。缺省关闭：不建运行期、不读盘、

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

@@ -9,7 +9,7 @@
  * - SDK 追加的供应商（`ProviderData[]`）折成 `config.providers` 条目，走同一条合并路径。
  * - 零配置（设计 §10.0）：没有 `defaultModel`、也没有任何需要 key 的供应商配了 key 时，探测本地
  *   ollama / lmstudio（短超时），把枚举到的模型加进注册表，供 `pickDefaultModel` 选用。
- * - [W6-O] ChatGPT 登录（docs/wave6-plan.md D14）：`chatgpt` 的缺省渠道按 auth.json 条目的 flavor 定（用户写了
+ * - [W6-O] ChatGPT 登录（docs/history/wave6-plan.md D14）：`chatgpt` 的缺省渠道按 auth.json 条目的 flavor 定（用户写了
  *   `defaultChannel` 时不动）；`AMA_CHATGPT_BASE_URL` 改该渠道地址；`auth.chatgpt.originator` 改 codex 渠道的
  *   `originator` 头；OAuth 刷新拿到 `auth.chatgpt` 配置与同一份 env。
  * - 发现缓存（`<dataDir>/models/discovered/<provider>.json`）并入模型表为空的供应商（discovered-cache.ts）；

package/dist/cli/compose-providers.js

@@ -9,7 +9,7 @@
  * - SDK 追加的供应商（`ProviderData[]`）折成 `config.providers` 条目，走同一条合并路径。
  * - 零配置（设计 §10.0）：没有 `defaultModel`、也没有任何需要 key 的供应商配了 key 时，探测本地
  *   ollama / lmstudio（短超时），把枚举到的模型加进注册表，供 `pickDefaultModel` 选用。
- * - [W6-O] ChatGPT 登录（docs/wave6-plan.md D14）：`chatgpt` 的缺省渠道按 auth.json 条目的 flavor 定（用户写了
+ * - [W6-O] ChatGPT 登录（docs/history/wave6-plan.md D14）：`chatgpt` 的缺省渠道按 auth.json 条目的 flavor 定（用户写了
  *   `defaultChannel` 时不动）；`AMA_CHATGPT_BASE_URL` 改该渠道地址；`auth.chatgpt.originator` 改 codex 渠道的
  *   `originator` 头；OAuth 刷新拿到 `auth.chatgpt` 配置与同一份 env。
  * - 发现缓存（`<dataDir>/models/discovered/<provider>.json`）并入模型表为空的供应商（discovered-cache.ts）；

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

@@ -1,5 +1,5 @@
 /**
- * 模型请求的流中空闲超时（docs/model-efficiency-plan.md D18）。[ME-C]
+ * 模型请求的流中空闲超时（docs/history/model-efficiency-plan.md D18）。[ME-C]
  *
  * 等响应头仍由 `request.idleTimeoutMs` / `AMA_IDLE_TIMEOUT_MS`（compose-session.ts `idleTimeoutFrom`）
  * 决定；流开始后两块数据之间的上限读 `AMA_STREAM_IDLE_TIMEOUT_MS` > config

package/dist/cli/compose-request.js

@@ -1,5 +1,5 @@
 /**
- * 模型请求的流中空闲超时（docs/model-efficiency-plan.md D18）。[ME-C]
+ * 模型请求的流中空闲超时（docs/history/model-efficiency-plan.md D18）。[ME-C]
  *
  * 等响应头仍由 `request.idleTimeoutMs` / `AMA_IDLE_TIMEOUT_MS`（compose-session.ts `idleTimeoutFrom`）
  * 决定；流开始后两块数据之间的上限读 `AMA_STREAM_IDLE_TIMEOUT_MS` > config

package/dist/cli/from-prompt.d.ts

@@ -1,5 +1,5 @@
 /**
- * `--from <会话 id>[#编号]`：用旧会话里的一条用户消息作为新提示（docs/sessions.md「复用」）。[W4-D]
+ * `--from <会话 id>[#编号]`：用旧会话里的一条用户消息作为新提示（docs/guides/sessions.md「复用」）。[W4-D]
  *
  * - 文本：那条消息的文本；命令行另有位置参数时接在后面（空一行）；
  * - 图片：`-p` 时把图片块写进临时目录、追加到 `--image`（沿用 print 模式的图片校验：模型不收图片 →

package/dist/cli/from-prompt.js

@@ -1,5 +1,5 @@
 /**
- * `--from <会话 id>[#编号]`：用旧会话里的一条用户消息作为新提示（docs/sessions.md「复用」）。[W4-D]
+ * `--from <会话 id>[#编号]`：用旧会话里的一条用户消息作为新提示（docs/guides/sessions.md「复用」）。[W4-D]
  *
  * - 文本：那条消息的文本；命令行另有位置参数时接在后面（空一行）；
  * - 图片：`-p` 时把图片块写进临时目录、追加到 `--image`（沿用 print 模式的图片校验：模型不收图片 →

package/dist/cli/main.d.ts

@@ -15,7 +15,7 @@
  * - 签名 `main(argv): Promise<number>` 与「直接执行才自动运行」判定保持不变：
  *   src/bundle.ts 显式调用 `main()`。
  * - [W6-C0] 界面语言在解析参数后、任何输出前定一次：`AMA_LANG` > `--lang` > 用户级 `ui.language` >
- *   `LC_ALL` / `LC_MESSAGES` / `LANG`（docs/i18n.md）；profile / 项目级的 `ui.language` 由 bootstrap 合并后补定。
+ *   `LC_ALL` / `LC_MESSAGES` / `LANG`（docs/guides/i18n.md）；profile / 项目级的 `ui.language` 由 bootstrap 合并后补定。
  */
 import type { CliIo, RuntimeDeps, StdinKind } from "./deps.js";
 import { type LanguageSetting } from "../i18n/index.js";

package/dist/cli/main.js

@@ -15,7 +15,7 @@
  * - 签名 `main(argv): Promise<number>` 与「直接执行才自动运行」判定保持不变：
  *   src/bundle.ts 显式调用 `main()`。
  * - [W6-C0] 界面语言在解析参数后、任何输出前定一次：`AMA_LANG` > `--lang` > 用户级 `ui.language` >
- *   `LC_ALL` / `LC_MESSAGES` / `LANG`（docs/i18n.md）；profile / 项目级的 `ui.language` 由 bootstrap 合并后补定。
+ *   `LC_ALL` / `LC_MESSAGES` / `LANG`（docs/guides/i18n.md）；profile / 项目级的 `ui.language` 由 bootstrap 合并后补定。
  */
 import { fstatSync, readFileSync, realpathSync } from "node:fs";
 import { join } from "node:path";

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

@@ -1,6 +1,6 @@
 /**
  * `ama auth set|list|remove <provider>`（设计 §3.5、§16.2 B5 验收）。[B5]
- * `ama auth login|logout|status chatgpt`（docs/wave6-plan.md §4.2）。[W6-O] 实现在 auth/chatgpt/cli.ts。
+ * `ama auth login|logout|status chatgpt`（docs/history/wave6-plan.md §4.2）。[W6-O] 实现在 auth/chatgpt/cli.ts。
  *
  * - set：key 从 stdin 读取（TTY 下不回显），不经命令行参数，避免进 shell 历史；写 auth.json 0600。
  *   [ACP-A] 不给 provider 且 stdin 是 TTY 时先用方向键选内置的需 key 供应商（ACP 终端登录方法

package/dist/cli/subcommands/auth.js

@@ -1,6 +1,6 @@
 /**
  * `ama auth set|list|remove <provider>`（设计 §3.5、§16.2 B5 验收）。[B5]
- * `ama auth login|logout|status chatgpt`（docs/wave6-plan.md §4.2）。[W6-O] 实现在 auth/chatgpt/cli.ts。
+ * `ama auth login|logout|status chatgpt`（docs/history/wave6-plan.md §4.2）。[W6-O] 实现在 auth/chatgpt/cli.ts。
  *
  * - set：key 从 stdin 读取（TTY 下不回显），不经命令行参数，避免进 shell 历史；写 auth.json 0600。
  *   [ACP-A] 不给 provider 且 stdin 是 TTY 时先用方向键选内置的需 key 供应商（ACP 终端登录方法

package/dist/cli/subcommands/config-set.d.ts

@@ -1,5 +1,5 @@
 /**
- * `ama config get | set | unset | list` (docs/wave6-plan.md §6.4, D24-D26). [W6-S]
+ * `ama config get | set | unset | list` (docs/history/wave6-plan.md §6.4, D24-D26). [W6-S]
  *
  * Thin layer over config/edit.ts (the `/config` panel uses the same core):
  * - `get <key> [--json]`: effective value, source layer and apply tier;

package/dist/cli/subcommands/config-set.js

@@ -1,5 +1,5 @@
 /**
- * `ama config get | set | unset | list` (docs/wave6-plan.md §6.4, D24-D26). [W6-S]
+ * `ama config get | set | unset | list` (docs/history/wave6-plan.md §6.4, D24-D26). [W6-S]
  *
  * Thin layer over config/edit.ts (the `/config` panel uses the same core):
  * - `get <key> [--json]`: effective value, source layer and apply tier;

package/dist/cli/subcommands/doctor.js

@@ -231,7 +231,7 @@ function proxySection(report, io) {
     for (const line of describeProxy(inspectProxy(io.env)))
         report.item(line);
 }
-/** 检查点备份占用（docs/rewind-plan.md §1.4）。 */
+/** 检查点备份占用（docs/history/rewind-plan.md §1.4）。 */
 async function fileHistoryLine(report, dataDir) {
     try {
         const usage = await blobUsage(dataDir);

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

@@ -1,5 +1,5 @@
 /**
- * `ama init [--force]`（docs/providers.md「配置目录」）：建配置目录与缺省文件，逐个报告状态。
+ * `ama init [--force]`（docs/guides/providers.md「配置目录」）：建配置目录与缺省文件，逐个报告状态。
  */
 import type { CliIo } from "../deps.js";
 export declare function initUsage(): string;

package/dist/cli/subcommands/init.js

@@ -1,5 +1,5 @@
 /**
- * `ama init [--force]`（docs/providers.md「配置目录」）：建配置目录与缺省文件，逐个报告状态。
+ * `ama init [--force]`（docs/guides/providers.md「配置目录」）：建配置目录与缺省文件，逐个报告状态。
  */
 import { describeInit, initConfigDir, initNextSteps } from "../../config/init.js";
 import { resolveConfigDir } from "../../config/paths.js";

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

@@ -1,5 +1,5 @@
 /**
- * `ama memory list|show|edit|rm|path|enable|disable`（docs/wave6-plan.md §3.5）。[W6-M]
+ * `ama memory list|show|edit|rm|path|enable|disable`（docs/history/wave6-plan.md §3.5）。[W6-M]
  *
  * - 作用域按用户级配置（`memory.scopes`，缺省 user + project）；项目作用域以 cwd 定位，需项目已受信任
  *   （trust.json 记录），否则跳过并提示。`memory.enabled` 为 false 时照样能看、能改（条目保留但不使用）。

package/dist/cli/subcommands/memory.js

@@ -1,5 +1,5 @@
 /**
- * `ama memory list|show|edit|rm|path|enable|disable`（docs/wave6-plan.md §3.5）。[W6-M]
+ * `ama memory list|show|edit|rm|path|enable|disable`（docs/history/wave6-plan.md §3.5）。[W6-M]
  *
  * - 作用域按用户级配置（`memory.scopes`，缺省 user + project）；项目作用域以 cwd 定位，需项目已受信任
  *   （trust.json 记录），否则跳过并提示。`memory.enabled` 为 false 时照样能看、能改（条目保留但不使用）。

package/dist/cli/subcommands/models.js

@@ -87,7 +87,7 @@ async function check(io, registry, ref) {
 }
 /**
  * `ama models refresh [--provider <id>[,<id>…]]`：显式联网拉 models.dev，按内置快照的清单裁剪，
- * 写用户级覆盖 `<dataDir>/models-dev.json`（docs/providers.md「模型元数据」）。启动与其它命令不联网。
+ * 写用户级覆盖 `<dataDir>/models-dev.json`（docs/guides/providers.md「模型元数据」）。启动与其它命令不联网。
  */
 const REFRESH_ACTION = {
     usage: "ama models refresh [--provider <id>[,<id>…]]",

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

@@ -1,5 +1,5 @@
 /**
- * `ama providers list|channels|remove`（docs/providers.md「一键接入」）：供应商 → 渠道 → 模型数与 key 来源
+ * `ama providers list|channels|remove`（docs/guides/providers.md「一键接入」）：供应商 → 渠道 → 模型数与 key 来源
  * （从不显示 key）；remove 删配置条目（先备份）与 auth.json 里该供应商及其渠道的 key。
  */
 import { type Ctx } from "./providers.js";

package/dist/cli/subcommands/providers-list.js

@@ -1,5 +1,5 @@
 /**
- * `ama providers list|channels|remove`（docs/providers.md「一键接入」）：供应商 → 渠道 → 模型数与 key 来源
+ * `ama providers list|channels|remove`（docs/guides/providers.md「一键接入」）：供应商 → 渠道 → 模型数与 key 来源
  * （从不显示 key）；remove 删配置条目（先备份）与 auth.json 里该供应商及其渠道的 key。
  */
 import { apiShortName } from "../../ai/providers/channels.js";

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

@@ -1,5 +1,5 @@
 /**
- * `ama providers add|refresh` 的纯计算部分（docs/providers.md「一键接入」）：候选渠道、模型列表的
+ * `ama providers add|refresh` 的纯计算部分（docs/guides/providers.md「一键接入」）：候选渠道、模型列表的
  * 协议提示、探测结果 → 模型渠道、渠道收敛、追加式合并进配置、表格。
  *
  * 不读写文件、不联网（`fetchModelList` 除外，它只是一次 GET）；命令流程在 providers.ts。

package/dist/cli/subcommands/providers-plan.js

@@ -1,5 +1,5 @@
 /**
- * `ama providers add|refresh` 的纯计算部分（docs/providers.md「一键接入」）：候选渠道、模型列表的
+ * `ama providers add|refresh` 的纯计算部分（docs/guides/providers.md「一键接入」）：候选渠道、模型列表的
  * 协议提示、探测结果 → 模型渠道、渠道收敛、追加式合并进配置、表格。
  *
  * 不读写文件、不联网（`fetchModelList` 除外，它只是一次 GET）；命令流程在 providers.ts。

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

@@ -1,5 +1,5 @@
 /**
- * `ama providers add|list|channels|remove|refresh`（docs/providers.md「一键接入」「渠道」）。
+ * `ama providers add|list|channels|remove|refresh`（docs/guides/providers.md「一键接入」「渠道」）。
  *
  * - add：只给 baseUrl 与 key，列出中转的模型（`GET /models`）、用 models.dev 补元数据、可选逐渠道
  *   探测，把渠道与模型追加进用户级 config.json（先备份）；key 从 stdin 读（不回显）存 auth.json，

package/dist/cli/subcommands/providers.js

@@ -1,5 +1,5 @@
 /**
- * `ama providers add|list|channels|remove|refresh`（docs/providers.md「一键接入」「渠道」）。
+ * `ama providers add|list|channels|remove|refresh`（docs/guides/providers.md「一键接入」「渠道」）。
  *
  * - add：只给 baseUrl 与 key，列出中转的模型（`GET /models`）、用 models.dev 补元数据、可选逐渠道
  *   探测，把渠道与模型追加进用户级 config.json（先备份）；key 从 stdin 读（不回显）存 auth.json，

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

@@ -3,7 +3,7 @@
  *
  * - `--format md|json|jsonl`（缺省 md）；`--branch leaf|all`（缺省 leaf = 当前分支）；
  * - `--output <文件>`：写文件（0600，已存在则覆盖），否则写 stdout；
- * - 导出内容先脱敏（session/redact.ts），格式说明见 docs/sessions.md「导出」。
+ * - 导出内容先脱敏（session/redact.ts），格式说明见 docs/guides/sessions.md「导出」。
  */
 import type { CliIo } from "../deps.js";
 export declare function sessionsExportUsage(): string;

package/dist/cli/subcommands/sessions-export.js

@@ -3,7 +3,7 @@
  *
  * - `--format md|json|jsonl`（缺省 md）；`--branch leaf|all`（缺省 leaf = 当前分支）；
  * - `--output <文件>`：写文件（0600，已存在则覆盖），否则写 stdout；
- * - 导出内容先脱敏（session/redact.ts），格式说明见 docs/sessions.md「导出」。
+ * - 导出内容先脱敏（session/redact.ts），格式说明见 docs/guides/sessions.md「导出」。
  */
 import { writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";

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

@@ -1,5 +1,5 @@
 /**
- * `ama sessions trace <id|文件>`：会话轨迹导出（docs/wave6-plan.md §2.5、D7）。[W6-T2]
+ * `ama sessions trace <id|文件>`：会话轨迹导出（docs/history/wave6-plan.md §2.5、D7）。[W6-T2]
  *
  * - 缺省 / `--html [文件]` / `--format html`：自包含 HTML（`trace/html.ts`）；`--json` / `--format json`：与 RPC
  *   `get_trace` 同形的 JSON（全部回合、已加载子会话、`previews` 只含本会话节点；`--no-content` 时没有）。

package/dist/cli/subcommands/sessions-trace.js

@@ -1,5 +1,5 @@
 /**
- * `ama sessions trace <id|文件>`：会话轨迹导出（docs/wave6-plan.md §2.5、D7）。[W6-T2]
+ * `ama sessions trace <id|文件>`：会话轨迹导出（docs/history/wave6-plan.md §2.5、D7）。[W6-T2]
  *
  * - 缺省 / `--html [文件]` / `--format html`：自包含 HTML（`trace/html.ts`）；`--json` / `--format json`：与 RPC
  *   `get_trace` 同形的 JSON（全部回合、已加载子会话、`previews` 只含本会话节点；`--no-content` 时没有）。