@jslee124/forge 0.3.1 → 0.3.3

package/resources/docs/zh-CN/ARCHITECTURE.md

@@ -80,7 +80,7 @@ User -> CLI -> Agent Runtime
 
 CLI 负责命令和配置解析、持久化交互 session、多行编辑、斜杠补全、`@` 文件引用、workspace 选择、流式事件和 diff 渲染、敏感操作审批、通过 `AbortSignal` 转发取消，以及选择退出码。它不包含 agent loop 或工具实现；Commander 负责进程命令，Ink 只负责交互 presentation。文件 mention 只携带 workspace-relative path，不绕过 `read_file`、workspace 校验、policy 或 trace。
 
-每个交互 prompt 开始新的有界 run 和审批实例；下一 prompt 只携带已完成的 user/assistant text。session 可以跨重启恢复，但 tool continuation 和审批只属于产生它们的 run。
+每个交互 prompt 开始新的有界 run 和审批实例；下一 prompt 携带已完成的 canonical user、assistant、tool-call 与严格配对的 tool-result block。session schema v3 可以跨重启恢复这些 provider-neutral 历史，但未闭合调用、tool continuation 和审批只属于产生它们的 run。
 
 ### Agent runtime
 

package/resources/docs/zh-CN/CLI_UI.md

@@ -50,6 +50,14 @@ editing
 - 补全菜单打开时上下移动选项；菜单关闭时未来可用于 prompt history，但不是 Milestone 4.6 要求。
 - Shift+Tab 在当前模型支持的 thinking-effort 等级间循环。
 
+## Context 压力与控制
+
+输入区 footer 使用两行：第一行常驻 model/effort 与预计 context indicator，第二行保留现有键盘快捷键。Indicator 使用 `○`、`◔`、`◑`、`◕` 或 `●`，同时显示百分比和语义文字；估算值带 `~`，响应式渲染会先隐藏 label，再隐藏数字或圆环。
+
+`/context` 会打开使用同一 pressure snapshot 的键盘控制面板，展示 instruction、tool schema、active history、draft/image 估算、effective reserve、checkpoint 来源、阈值、strategy 和上次压缩。按 `p` 预览、`c` 立即压缩一次、`a` 只为当前进程启用自动压缩、`s` 明确保存为用户默认，Escape 关闭。`warn` 模式第一次越过阈值时会提供 compact once、session auto 或 dismiss，不会抢占正在运行的任务或审批输入。
+
+默认仍是 `warn`。自动压缩依据 projected pressure，而不是消息数量；取消、无效 projection 或低回收收益会让 auto 暂停。规范 transcript 始终无损保留。
+
 ## 斜杠命令补全
 
 当 `/` 是首个非空白字符时打开命令列表，后续字符按命令名过滤。同一个 registry 同时驱动补全和 `/help`，避免两处漂移。当前包括 `/help`、`/new`、`/clear`、`/context`、`/compact`、`/plugins`、`/login`、`/logout`、`/model`、`/delete-model`、`/effort`、`/resume` 和 `/exit`。
@@ -89,10 +97,12 @@ editing
 
 文件写入审批前必须在独立面板展示精确变更：操作和路径（create/modify/delete）、文件摘要和行数、带新旧行号的 unified diff、带 `+/-` 的新增/删除行、清晰的 file/hunk header、已知文件类型的语法高亮，以及触达安全显示限制时的截断说明。
 
-审批不能只依赖颜色；`--no-color`、无色终端和色觉差异都必须保留 `+/-`、header 和行号。超过安全审查限制的 diff 不可审批，不能把未展示的部分默认为已审查。控制项要说明范围：首次 workspace 写入的审批只覆盖本次 run 的后续 workspace 写入，进程命令仍需单独审批。
+审批不能只依赖颜色；`--no-color`、无色终端和色觉差异都必须保留 `+/-`、header 和行号。超过安全审查限制的 diff 不可审批。`1` 仅允许一次，`2` 允许当前内存 session 中准确展示的 scope，`3` 打开可选拒绝 feedback；高风险 action 不提供 session 选项。`/permissions` 展示 profile、scope ID、use count 和 revoke；grant 会在 `/new`、`/resume` 和进程退出时消失。
 
 网络工具审批使用专用面板，展示注册工具名和将发送到外部的有界 URL 或搜索词；plugin secret 和任意 input object 不渲染为预览。
 
+Update checker 也位于 Ink tree 内。启动后的结果可以增加 current/latest banner，但不会产生 transcript 文本或抢走 editor、stream、approval input。宽终端显示 release-notes destination 与 restart 说明；窄终端仍保留版本、`forge update`、restart 和 `/update-dismiss`。
+
 ## 登录面板
 
 浏览器登录是独立面板，不是 transcript 文本。Codex auth surface 以带独立地址字段的结构化 `login` event 报告 URL，因此 UI 不需要从文本块重新解析。

package/resources/docs/zh-CN/CONFIGURATION.md

@@ -99,6 +99,8 @@ built-in defaults
 
 Forge 没有实现 `full-access` profile。获批子进程也没有 OS sandbox，详见安全模型。
 
+Permission grant 不是配置。编号 session 选项只在当前进程保存 host 规范化 scope；项目配置、instruction、Skill、checkpoint、tool result 和 plugin hook 都不能持久化或扩大它。`/permissions` 可以查看并撤销当前内存 grant。
+
 ### Trace 与 plugins
 
 | 字段 | 默认值 | 说明 |
@@ -117,8 +119,11 @@ Forge 没有实现 `full-access` profile。获批子进程也没有 OS sandbox
 | `context.bufferTokens` | `8192` | 1–2,000,000 | 项目可以增加 safety buffer。 |
 | `context.recentTailTokens` | `12000` | 0–2,000,000 | 项目可以减少原样保留的近期历史预算。 |
 | `context.summaryTargetTokens` | `1200` | 64–2,000,000 | 项目可以减少 checkpoint target。 |
+| `context.activationThreshold` | `0.78` | 0.5–0.95 | 项目只能降低压力阈值，不能提高。 |
+| `context.minimumReclaimTokens` | `8000` | 0–2,000,000 | 项目只能降低 no-progress token 下限，不能提高。 |
+| `context.minimumReclaimRatio` | `0.2` | 0–0.9 | 项目只能降低 no-progress 比率，不能提高。 |
 
-`warn` 会测量并报告压力，但不自动生成 checkpoint；`compact` 允许在实现的预算规则需要时自动生成 checkpoint。`/compact` 始终可作为显式交互操作。无论哪种模式，规范 session transcript 都会独立保留。详见上下文管理。
+`warn` 会测量预计下一次请求的压力，并在越过 activation threshold 时给出非阻塞 TUI 控制；`compact` 允许按压力生成 checkpoint。`/context` 可以只为当前进程启用自动压缩，也可以在用户明确选择后把 `compact` 保存到用户配置；session-only 状态不会恢复。`/compact` 在所有模式下仍可显式使用。规范 session transcript 始终独立保留。详见上下文管理。
 
 ## 安全的项目配置
 

package/resources/docs/zh-CN/CONTEXT_MANAGEMENT.md

@@ -4,10 +4,12 @@ English · 中文目录
 
 ## 状态
 
-Roadmap Milestone 10 已实现。默认模式仍是 `warn`；自动生成 checkpoint 在 provider 质量 gate 发布前保持 opt-in。当前 checkpoint 使用确定性、脱敏的 extractive summarizer，因此默认测试和手动 `/compact` 不会产生付费模型调用。它在所有可用历史消息之间分配有界空间，移除类似 authority 的审批声明，并把验证文字标记为历史信息。
+Roadmap Milestone 10 与 Milestone 13.0-13.5 已实现。默认模式仍是 `warn`；自动生成 checkpoint 在 provider 质量 gate 发布前保持 opt-in。TUI 现在会预计完整的下一次请求输入、常驻显示分段压力 indicator，并通过 `/context` 提供仅当前 session 或明确持久化的自动模式。当前 checkpoint 使用确定性、脱敏的 extractive summarizer，因此默认测试和手动 `/compact` 不会产生付费模型调用。它在所有可用历史消息之间分配有界空间，移除类似 authority 的审批声明，并把验证文字标记为历史信息。
 
 Checkpoint schema 和 adapter capability contract 支持 provider-native opaque state；但当前 OpenAI AI SDK 和 DeepSeek adapter 因 transport 尚未提供安全的 compact-item round trip，声明 native compaction 不支持。
 
+初始 activation threshold 是 `0.78`。Input capacity 只扣除一次 `max(output reserve, safety buffer)`。压缩被取消、输出无效，或回收量小于 8,000 token 与 projected input 20% 两者的较大值时，auto mode 会暂停。Stable-prefix 与 cache observation 只把 hash metadata 写入 trace；provider 没有报告的 cache usage 保持 unavailable。
+
 ## 为什么要做
 
 Forge 已经区分项目指令、完成对话、当前 user request 和 provider continuation，也限制指令文件、工具输出、模型步骤、工具调用和持久化 session 大小。但长 session 的 token window 仍可能在 provider 边界失败：每次 native request 都会重新发送完成的 user/assistant turn，run 内的 assistant tool call 和 tool result 也会累积到 continuation。
@@ -146,7 +148,7 @@ remaining history budget
 
 ## Conversation compaction
 
-选择算法优先保留 mandatory instructions、current request、required protocol state 和最近的完整 turn；只选择更旧、已完成的消息进入 checkpoint。应先清理可安全移除的旧 tool output，再压缩更大范围。要保持 user/assistant 配对，不能截断半个 tool-call 事务。
+选择算法优先保留 mandatory instructions、current request、required protocol state 和最近的完整 turn；session schema v3 的 structured `history` 与 checkpoint v2 按闭合 user/assistant/tool exchange 选择和 hash。只选择更旧、已完成的消息进入 checkpoint，不能拆开 tool-call/result 或保留 orphan result。
 
 Checkpoint 至少包含 schema version、源消息区间、source/tail hash、生成时间、summary text、summary token estimate、redaction/provenance 和 strategy。它是派生数据，可被 hash 不匹配或验证失败的检查丢弃；规范 transcript 始终保留。
 

package/resources/docs/zh-CN/GETTING_STARTED.md

@@ -19,9 +19,9 @@ English · 中文文档目录
 - Git
 - 以下任意一种模型访问方式：DeepSeek API key、OpenAI API key、已配置的 OpenAI-compatible endpoint，或通过 Codex CLI 使用 ChatGPT 账号
 
-Forge 的开发 workspace 继续保持 private。release 自动化会生成唯一的公共 CLI package `@jslee124/forge`，内部 packages 和插件 SDK 仍保持私有。在首次 npm release 可见前，请从源码运行或全局链接当前 checkout。
+Forge 的开发 workspace 继续保持 private。release 自动化会生成唯一的公共 CLI package `@jslee124/forge`，内部 packages 和插件 SDK 仍保持私有。普通用户应安装已发布的 CLI；参与 Forge 开发时再从源码运行或全局链接当前 checkout。
 
-对于已经发布的构建：
+安装当前稳定版本：
 
 ```bash
 npm install --global @jslee124/forge
@@ -38,7 +38,7 @@ pnpm build
 pnpm forge --version
 ```
 
-最后一条命令会构建 workspace；当前源码 release 应输出 `0.3.1`。它不会联系模型 provider。
+最后一条命令会构建 workspace；当前源码 release 应输出 `0.3.3`。它不会联系模型 provider。
 
 开发期间可以一直使用 `pnpm forge`。如果希望直接输入 `forge`：
 
@@ -180,7 +180,7 @@ pnpm forge resume --last
 pnpm forge inspect <run-id>
 ```
 
-Session 保存已经完成的 user/assistant turns；run 是一次带独立 ID 和 JSONL event trace 的有界 agent-loop 执行。Resume 只恢复已完成对话文本，不恢复旧审批、待执行 tool call、子进程或 provider continuation state。详见会话与 trace。
+Session 保存规范 conversation context；run 是一次带独立 ID 和 JSONL event trace 的有界 agent-loop 执行。交互式 Resume 会重放可用的历史模型与工具事件，但不会重新激活旧审批、待执行 tool call、子进程或 provider continuation state。详见会话与 trace。
 
 ## 下一步
 

package/resources/docs/zh-CN/PLUGINS.md

@@ -4,7 +4,7 @@
 
 English · 中文目录
 
-Forge 0.3.1 不依赖插件。插件是可选的进程内 JavaScript module，可以注册模型调用工具和显式本地命令、贡献指令、观察不可变 run event，或让策略更严格。实现中的类型、schema 和 host 才是最终合约：types.ts、schema.ts、host.ts。
+Forge 0.3.3 不依赖插件。插件是可选的进程内 JavaScript module，可以注册模型调用工具和显式本地命令、贡献指令、观察不可变 run event，或让策略更严格。实现中的类型、schema 和 host 才是最终合约：types.ts、schema.ts、host.ts。
 
 ## 快速开始
 
@@ -277,7 +277,7 @@ conversation、把 child 保存为可独立 resume 的 session、在专用 TUI p
 
 加载插件会执行拥有 Forge 进程完整权限的本地代码；它可以直接 import Node、读任意文件、启动进程或联网。Forge 只在支持的 API 边界执行：trust 前不 import 项目 entry；校验 manifest/API/capability/name/schema；model 调用的 plugin tool 走 core policy/approval；model/network/process/相关 write 需确认；policy hook 只能更严格；prompt/Skill 有界且带来源；observer input clone/freeze/脱敏。
 
-这些保证不隔离恶意 trusted entry，强隔离需要受限进程或 OS sandbox。Forge 0.3.1 没有插件安装器、依赖解析器、registry、hot reload、TypeScript entry 编译、custom interactive UI、provider registration、隔离进程或可强制执行的 filesystem/network capability；plugin command 只通过 `forge plugins run` 执行，不自动成为交互 slash command。
+这些保证不隔离恶意 trusted entry，强隔离需要受限进程或 OS sandbox。Forge 0.3.3 没有插件安装器、依赖解析器、registry、hot reload、TypeScript entry 编译、custom interactive UI、provider registration、隔离进程或可强制执行的 filesystem/network capability；plugin command 只通过 `forge plugins run` 执行，不自动成为交互 slash command。
 
 ## Skills 与产品文档属于资源
 

package/resources/docs/zh-CN/PRODUCT.md

@@ -75,7 +75,7 @@ Forge 可以使用成熟库消除偶然复杂度，但核心运行时概念必
 
 ## v0.1 成功标准
 
-详细 gate 见 v0.1 验收与评测。一次完整仓库任务至少要：读取多个相关文件、进行定向修改、运行自动验证、证明失败恢复、在成功或限制后停止、拒绝 workspace 外文件操作、生成与真实行为一致的 trace 和总结。
+详细 gate 见历史 v0.1 验收与评测。一次完整仓库任务至少要：读取多个相关文件、进行定向修改、运行自动验证、证明失败恢复、在成功或限制后停止、拒绝 workspace 外文件操作、生成与真实行为一致的 trace 和总结。
 
 ## v0.1 不在范围内
 

package/resources/docs/zh-CN/RELEASING.md

@@ -22,17 +22,18 @@ registry。
 
 ## 准备 release
 
-从干净 checkout 开始，并选择 SemVer：
+从干净 checkout 开始，并选择 SemVer。下面以 `0.3.1` 为例，实际执行时替换为
+准备发布的版本：
 
 ```bash
-pnpm version:set 0.3.0
+pnpm version:set 0.3.1
 pnpm install --frozen-lockfile
 pnpm check
 pnpm check:docs
 pnpm test
 pnpm eval:deterministic
 pnpm package:verify
-pnpm release:verify-tag v0.3.0
+pnpm release:verify-tag v0.3.1
 ```
 
 `package:verify` 会构建公共产物、检查 tarball、在全新临时 prefix 中禁用
@@ -42,33 +43,32 @@ API version，并验证 `forge --version`、`forge --help` 和 `forge config val
 打 tag 前必须检查 pack 内容和 release notes。API key、auth 文件、本地
 trace、`.env` 以及未经脱敏审核的 evaluation artifact 都不能发布。
 
-## 首次发布到 npm
+## npm 一次性初始化（已完成）
 
-npm 账号或组织必须拥有 `@jslee124` scope，并启用 2FA。npm package 存在后
-才能配置 trusted publisher，因此先用经过审核的预发布版本（例如
-`0.3.0-bootstrap.0`）和非稳定 dist-tag 创建 package，再把仓库中的
-`publish.yml` 配置为 GitHub Actions trusted publisher。bootstrap 版本不要
-放入 `latest`。
+npm 首次发布已在 v0.3.0 完成。维护者拥有 `@jslee124` scope，
+`.github/workflows/publish.yml` 已注册为该 package 的 GitHub Actions trusted
+publisher。一次性 bootstrap 使用 `0.3.0-bootstrap.0` 和 `bootstrap` dist-tag；
+现在 `latest` 已指向稳定版本 `0.3.0`。后续 release 不要重复 bootstrap 流程。
 
-trusted publishing 配置完成后，稳定版本只由 tag workflow 发布。它使用
-OIDC，不保存长期 npm token，并在所有 release gate 通过后发布生成 package。
+稳定版本必须只由 tag workflow 发布。它使用 OIDC，不保存长期 npm token，并在
+所有 release gate 通过后发布生成 package。如果未来更换 trusted publisher
+配置，应在创建 tag 前同时检查 npm package 设置和 workflow identity。
 
 ## 发布稳定版本
 
 提交版本、release notes 和构建输入，然后创建不可移动的 annotated tag：
 
 ```bash
-git tag -a v0.3.0 -m "Forge v0.3.0"
-git push origin v0.3.0
+git tag -a v0.3.1 -m "Forge v0.3.1"
+git push origin v0.3.1
 ```
 
 `Publish npm package` workflow 会先确认 Git tag、根版本、私有 workspace
-版本、runtime 版本和生成 npm package 完全一致，然后运行
-`npm publish --access public`。
+版本、runtime 版本和生成 npm package 完全一致，然后使用显式 dist-tag 发布。
+稳定语义版本路由到 `latest`；带 prerelease component 的版本路由到 `next`。
 
-预发布版本才使用 `npm publish --tag next`。不要移动已经发布的 Git tag，
-也不要复用 npm 版本。错误 release 应通过新的 patch 版本修复，并保留旧版本
-供用户回滚。
+不要移动已经发布的 Git tag，也不要复用 npm 版本。错误 release 应通过新的
+patch 版本修复，并保留旧版本供用户回滚。
 
 ## 用户更新
 
@@ -77,10 +77,7 @@ git push origin v0.3.0
 ```bash
 forge update check
 forge update
-forge update 0.3.1
+forge update 0.3.3
 ```
 
-交互启动最多每 24 小时在后台刷新一次提示性 npm 检查，并在后续启动显示缓存
-结果；绝不会因为启动而安装更新。设置 `FORGE_DISABLE_UPDATE_CHECK=1` 可以关闭
-启动检查。显式更新命令会先把 npm metadata 解析为精确 SemVer，再执行禁用
-lifecycle scripts 的全局 npm 安装。
+交互启动在 Ink 内发布 cached、refreshing、available、current、failed 或 disabled 状态，并最多每 24 小时刷新一次 npm metadata；晚到结果不会进入对话历史。启动永不安装更新，`/update-dismiss` 只 dismiss 当前版本。`FORGE_DISABLE_UPDATE_CHECK=1` 可关闭启动检查。显式命令仍可重复，会先解析精确 SemVer；只有识别 npm/pnpm 全局安装来源后才用 argument array 与 `--ignore-scripts` 安装，未知来源只报告版本和 release notes。成功后仍需 restart。

package/resources/docs/zh-CN/SECURITY.md

@@ -51,6 +51,10 @@ v0.1 之后再考虑。未来的显式高级模式必须有清晰警告和用户
 
 ## 进程边界
 
+交互审批采用结构化选择：`1` 仅允许一次，`2` 只在当前内存 session 中保存界面准确展示的 scope，`3` 拒绝并可附带有界 feedback。Command scope 绑定精确 program/argument array、canonical workspace/cwd 和 timeout ceiling；workspace write、network tool/destination 与 delegated-model 使用同样由 host 规范化的字段。`/permissions` 展示 use count 并可撤销。
+
+Grant 不序列化也不随 resume 恢复。参数、cwd、destination、workspace 或超时上限变化都会重新提示；destructive、credential-sensitive、install、publish 与广泛外部副作用命令不可复用。Plugin policy hook 只能保持或收紧 `deny > confirm > allow`，不能创建或扩大 grant。
+
 v0.1 `run_command` 接受 program 和 args 数组，以 Node.js `spawn`、`shell: false` 启动。pipeline、重定向、命令替换和复合 shell 语法不接受。默认 profile 下每条命令都需确认，审批提示至少显示精确 program、逐项引用的参数、工作目录、超时和相关环境变化。
 
 工作目录在 workspace 内不代表进程不能读写外部。没有 OS sandbox，Forge 不能声称获批子进程具有文件系统或网络隔离；`shell: false` 只防止 Forge 自己解析 shell 表达式。
@@ -81,7 +85,7 @@ Child 继承有效 policy/approval，只获得声明的非 subagent 工具，共
 
 模型实际返回的 reasoning/thinking 默认对用户可见，必须标记为 provider 提供；不能声称访问 provider 没有返回的 reasoning。reasoning 可能含仓库敏感信息，trace 和导出使用同一脱敏策略。
 
-恢复 session 只恢复完成的对话，不恢复可执行 authority；每次恢复创建新策略实例，不恢复旧审批、待调用工具、子进程或 provider continuation，并重新加载当前配置和项目指令。session snapshot 和 trace 在 `FORGE_HOME` 外仓库存储，但仍可能含仓库文本、diff、命令和模型输出，是本地敏感数据。
+恢复 session 会恢复完成的 canonical 对话，包括闭合的 tool-call/result 对，但不恢复可执行 authority；历史工具输出只是 untrusted context，不是当前验证。每次恢复创建新策略实例，不恢复旧审批、待调用工具、子进程或 provider continuation，并重新加载当前配置和项目指令。session snapshot 和 trace 在 `FORGE_HOME` 外仓库存储，但仍可能含仓库文本、diff、命令和模型输出，是本地敏感数据。
 
 ## Credential 处理
 

package/resources/docs/zh-CN/SESSIONS.md

@@ -4,11 +4,12 @@ English · 中文目录
 
 ## 目标
 
-Forge 持久化足够的可信 metadata 和已完成对话历史，使交互式聊天可以在进程退出后继续。它不会尝试重放进行中的工具调用。
+Forge 持久化足够的可信 metadata、已完成对话历史和有界的未完成运行结果，使交互式聊天可以在进程退出后继续。它不会尝试重放进行中的工具调用。
 
 ```text
 Session
-|-- 已完成的 user/assistant 轮次
+|-- canonical user/assistant/tool-call/tool-result 历史
+|-- 有界的 failed/denied/cancelled run 结果
 |-- 已完成 assistant 轮次的 provider reasoning summary
 |-- 可选的派生 context checkpoint
 |-- workspace 与 working-directory metadata
@@ -28,9 +29,11 @@ $FORGE_HOME/
     `-- <run-id>.jsonl
 ```
 
-Session snapshot 使用 `schemaVersion: 2`，读取时迁移 v1；trace envelope 使用 `schemaVersion: 1`。文件只能写入解析后的 Forge home。snapshot 原子替换，活跃 run 的 trace 追加写入。
+Session snapshot 使用 `schemaVersion: 3`，读取时迁移 v1/v2；v3 保存 provider-neutral content block 与 fidelity 标记。trace envelope 使用 `schemaVersion: 1`。文件只能写入解析后的 Forge home。snapshot 原子替换，活跃 run 的 trace 追加写入。
 
-每个 session 保存 session ID、创建和更新时间、规范 workspace root、工作目录、已完成对话、provider 暴露的 reasoning 文本、run ID 顺序，以及可选的带来源和 hash 的 checkpoint。每行 trace 包含 run ID、可选 session ID、序号、时间戳和一个结构化 `RunEvent`。Subagent trace envelope 还包含 `parentRunId` 和 `subagentName`，parent trace 则通过完成的 delegation tool result 反向关联 child run。
+最终脱敏并序列化为 JSON 后，持久 session snapshot 的上限为 4 MiB。Forge 在保存与加载时使用同一 byte limit。超限保存会在原子替换前失败，因此之前可恢复的 snapshot 会保留。由于 canonical history 有意保持无损，checkpoint 也不会删除它，当前 retention 策略是在接近上限时开启新 session；若旧 JSON 不再需要出现在 resume 列表中，可将它归档到活动 `sessions/` 目录之外。
+
+每个 session 保存 session ID、创建和更新时间、规范 workspace root、工作目录、已完成对话、未完成运行的原始用户请求和有界无授权语义结果、provider 暴露的 reasoning 文本、run ID 顺序，以及可选的带来源和 hash 的 checkpoint。已完成但遇到工具失败的运行也会保留有界工具结果。每行 trace 包含 run ID、可选 session ID、序号、时间戳和一个结构化 `RunEvent`。Subagent trace envelope 还包含 `parentRunId` 和 `subagentName`，parent trace 则通过完成的 delegation tool result 反向关联 child run。
 
 ## 恢复行为
 
@@ -41,14 +44,18 @@ forge resume --last
 
 交互式 `/resume` 只展示当前规范 workspace 的有界 session 列表。恢复规则如下：
 
-1. 只恢复已完成的 user/assistant 轮次和 provider 实际提供的 reasoning，且仅用于展示。
+当所有关联 trace 均可用时，交互式 transcript 会按照原运行使用的同一组有序 `RunEvent` 重建，恢复 reasoning summary、中间模型文本、工具 Proposed、审批决定、Completed 和 Failed 记录，而不是把供模型续聊使用的有界摘要显示成 assistant 正文。
+
+1. 恢复已完成的 user/assistant/tool 轮次，包括严格配对的 tool call 与模型实际看到的 result/failure；failed、denied、cancelled 和 limit-reached 运行恢复原始请求及有界结果摘要。
 2. 新 prompt 总是以新的 run ID 开始新的有界运行。
 3. 重新加载当前配置和 `AGENTS.md` 指令。
-4. 每次恢复都创建新的审批状态。
-5. 不恢复 provider continuation、部分完成的工具调用或子进程。
+4. 每次恢复都创建新的审批状态，并在加载历史前清除内存 session grant。
+5. 不恢复 provider continuation、部分完成的工具调用或子进程；闭合的历史工具交换会成为模型可见上下文，但只是 untrusted historical observation，新运行仍须重新检查 workspace 并重新取得审批。
 6. 其他 workspace 的 session 会被拒绝。
 7. 缺失或无效 snapshot 在发起模型请求前以可操作的配置错误结束。
 8. 有效 checkpoint 恢复同一个有界 active view；过期 checkpoint 被忽略，不改变规范 transcript。
+9. 旧 snapshot 的文本总是无损迁移；只有当所有关联 run trace 均可读、完整且现有规范消息能与重建结果严格按顺序匹配时，才 all-or-nothing 补回结构化工具历史。
+10. 任一关联 trace 缺失或无效时，Forge 使用 structured canonical fallback，不展示误导性的残缺时间线；tool call/result 仍可见且 final answer 不重复。
 
 因此，Forge 恢复的是 conversation context，而不是 authority 或 executable state。保存的 reasoning 仅用于展示，不会加入模型历史；Forge 只保存 provider 实际发出的 summary，不会声称拥有隐藏 chain of thought。
 
@@ -60,9 +67,9 @@ forge resume --last
 
 ## 脱敏与安全
 
-持久化前会脱敏配置的 credential 值和已识别的 secret 字段；特别是 `DEEPSEEK_API_KEY` 绝不能出现在 snapshot 或 trace 中。Trace 仍可能包含仓库内容、diff、命令、模型文本和 provider reasoning，因此 `sessions/` 与 `runs/` 属于本地敏感数据，不应提交到仓库。
+持久化前会脱敏配置的 credential 值和已识别的 secret 字段。有界运行摘要不保存工具输出、文件正文、命令参数或原始错误消息，只保留安全的工具标识、文件路径或命令程序名以及错误码；特别是 `DEEPSEEK_API_KEY` 绝不能出现在 snapshot 或 trace 中。Trace 仍可能包含仓库内容、diff、命令、模型文本和 provider reasoning，因此 `sessions/` 与 `runs/` 属于本地敏感数据，不应提交到仓库。
 
-恢复不会削弱安全模型：旧审批不恢复；旧 permission profile 不是授权；项目文件不能通过 workspace 工具修改 `FORGE_HOME` 下的 session metadata；列出或 inspect session 是只读操作且不会调用模型。
+恢复不会削弱安全模型：旧审批不恢复；`/permissions` scope/use count 不写入 snapshot 或 checkpoint；旧 permission profile 不是授权；项目文件不能通过 workspace 工具修改 `FORGE_HOME` 下的 session metadata；列出或 inspect session 是只读操作且不会调用模型。
 
 ## 延后行为
 

package/resources/docs/zh-CN/TROUBLESHOOTING.md

@@ -110,6 +110,12 @@ pnpm forge auth login openai --method device-code
 
 当 stdin/stderr 不是 TTY 时，one-shot native run 没有审批通道，需要确认的操作会 fail closed。这是预期行为。请改在终端运行、把任务缩小为只读，或使用专门的自动化/评测审批通道。不要把切换 profile 当成 OS isolation；两种 profile 都不会 sandbox 获批进程。
 
+交互 Forge Engine 中，`1` 只允许一次，`2` 仅保存界面展示的 session scope；用 `/permissions` 查看和撤销。参数、cwd、network destination、workspace、超过 ceiling 的 timeout 或 install/publish/destructive 高风险命令会正确重新提示。按 `3` 后可输入 guidance 再回车，把 denial result 返回当前 run，但不会授予 authority。
+
+## 显示更新但 `forge update` 不安装
+
+Forge 只在识别 npm/pnpm 全局安装来源时执行安装。未知或复制的 executable 只报告精确版本与 release-notes URL，不猜测包管理器；请使用最初的 installer。显式安装成功后需要 restart。`FORGE_DISABLE_UPDATE_CHECK=1` 只关闭启动检查，`forge update check` 仍是显式且权威的查询。
+
 ## 项目 plugin 被发现但显示 skipped
 
 Forge 会从规范 workspace root 的 `.forge/plugins/` 发现项目 plugin，但在信任前不会 import。检查代码后使用 `/plugins` 面板，或：
@@ -159,7 +165,7 @@ Session 与 workspace 绑定。请在同一个规范仓库中启动：
 pnpm forge resume --last
 ```
 
-Snapshot 位于 `$FORGE_HOME/sessions`。修改 `FORGE_HOME`、移动 checkout、删除或损坏 JSON 都会影响结果。Resume 只恢复 completed turns，不能继续中断的 stream 或待处理 tool call。
+Snapshot 位于 `$FORGE_HOME/sessions`。修改 `FORGE_HOME`、移动 checkout、删除或损坏 JSON 都会影响结果。Resume 会恢复 completed turns，以及 failed、denied、cancelled、limit-reached 运行的有界结果，但不能继续中断的 stream 或待处理 tool call；新运行会重新检查当前状态。
 
 ## 终端输入或渲染异常
 

package/resources/skills/forge-plugin-creator/references/plugin-api.md

@@ -1,6 +1,6 @@
 # Forge plugin API reference
 
-This reference is version-matched to Forge 0.3.1 and plugin API version `"1"`.
+This reference is version-matched to Forge 0.3.3 and plugin API version `"1"`.
 The runtime schema and types remain authoritative when they are present.
 
 ## Manifest