create-windy 0.6.12 → 0.6.14

package/template/docs/operations/agent-session-troubleshooting.md

@@ -0,0 +1,196 @@
+# Agent Session 重复故障速查
+
+## 页面显示 Session 不可用
+
+先确认 Server 使用 PostgreSQL，而不是非生产内存模式；再确认 Migration 0058、0059 已应用、
+`AI_ARTIFACT_ENCRYPTION_SECRET` 与写入时一致，以及当前用户具备 Feature、Permission、License。
+不要临时改成内存 Session。首次 fresh-deploy 验收应在部署前清空旧开发 Docker 容器及数据卷，并从
+空库顺序应用 AH-1 的 0058—0060；启用 AH-2 Workflow 的同一 0.6.14 基线还要继续应用结构性
+`0061_agent_workflow.sql`。运行中排障不得清表重建。
+
+## 旧开发期 Agent 聊天记录无法读取
+
+这是本版本的明确边界。AH-1 Session/Context/Memory 与 AH-2 Workflow 是 fresh-deploy baseline，
+不提供旧开发期 Agent 聊天历史、Event Log、Memory 或 Workflow 投影兼容。0061 是 Workflow
+结构性 Migration，不是历史清理 Migration；仓库也不提供旧 Agent 数据迁移、回填或清理脚本。
+验收从已清空旧开发容器和数据卷的空库开始；不得删除或迁移正式 Run 审计、Client Agent Session、
+Artifact、审批、上传或业务数据来“修复”此现象。
+
+## 重启后 Session 消失或 head 不连续
+
+检查 `agent_sessions.head_sequence` 与同 Session 的最大 Event sequence。若不一致，停止该 Session
+写入并保留数据库快照；不要手工补 Event、改 sequence 或更新 Migration 历史。确认应用连接的是
+同一 PostgreSQL 实例，并检查事务失败日志。
+
+## Checkpoint 或 Fork 返回冲突
+
+刷新 Session 详情，使用最新 `headSequence` 重新发起。Checkpoint 必须锚定当前 head，Fork 必须
+引用该父 Session 已提交的 Checkpoint。冲突是 CAS 保护，不应通过覆盖 head 绕过。
+
+## Replay 看起来没有重新执行 Tool
+
+这是预期行为。replay 固定为 `recorded-only`。确需重做写 Tool 时必须走显式再执行入口，重新取得
+当前授权、必要审批、幂等键与 command receipt；不得把 replay/fork 改成隐式副作用执行。
+
+若 replay 统一返回 503 或日志出现读取 `segment.session`，检查路由是否仍把 replay segment 当成
+内嵌 Session。正确实现按 `segment.sessionId` 读取真实 Session 投影后返回；不存在或越权仍使用
+稳定不可访问响应，不能伪造快照。
+
+## 普通 Agent 权限可以写入长期 Session
+
+识别信号是同一请求只具备业务 Operation 的执行权，却能通过 `/agent/runs` 的 `sessionId` 追加
+Turn。绑定长期 Session 是额外治理写入，必须在 Run 启动时重新检查 `system.agent-session`
+Feature、License 和 `system.agent-session.manage`。不要把普通 Agent 执行权复用为 Session 写权；
+未传 `sessionId` 的 Run 才保持原行为。
+
+## 切换案件后列表仍出现旧 Session
+
+详情返回 404、但列表仍暴露旧 Session ID、状态或血缘，说明列表只按 Actor 过滤。列表和详情必须
+共同使用 Actor + 当前 Scope digest；不要依赖前端缓存过滤，也不要把 Session ID 当成无敏感性。
+
+## 已撤权或删除的数据仍出现在检索中
+
+先查 `agent_source_invalidation_deliveries` 对应 Search/Embedding Delivery 的 status、attempt count、
+Lease 和 error code，再确认目标 Adapter 与 Worker 已装配。不要仅清浏览器缓存。修复目标后让原
+Delivery 重试，不能新建无因果关系的“补偿删除”掩盖原队列。
+
+无论索引是否收敛，业务读取都应由权威对象 Guard 立即拒绝。若仍能读取，按授权绕过事故处理，
+优先检查对象授权 Port、source version/sequence 和 authorization generation，而不是先修 UI。
+
+## 删除一个 Memory 后同源投影全部消失
+
+检查删除路径是否错误发布 `source-deleted`。单个 Memory 删除只是 projection 自身删除，不得触发
+同源 Context、Memory、Search 或 Embedding 清除；`source-deleted` 只能由权威来源生命周期发布。
+若已经误发，先保留 Outbox 与审计证据，停止消费者，再按权威来源当前状态重建受影响投影。
+
+## 不同模块的同名来源互相失效
+
+信号包括相同 kind/ID 的不同模块发生唯一键冲突，或其中一个删除后另一个也被标记失效。检查
+Context/Memory source、Outbox 唯一键、stale 判定和匹配是否都保留 moduleKey，并确认 0059 已
+应用。空、未知或未注册 Module Key 必须 fail closed，不能猜测归属。
+
+## Run 启动冲突后 Turn 永久开放
+
+若时间线只有 `turn.started` 而没有 `run.linked` 或 Turn 终态，检查两步 CAS 冲突是否被吞掉。正确
+路径应重读同一幂等坐标并重试补链；Run 启动失败则关闭开放 Step/Turn，补偿失败必须连同原错误
+上抛。不要手工修改 head sequence 或补写无因果 Event。
+
+## Context 来源显示 invalid 或 attempt 没有 Context Version
+
+`invalid` 表示来源已撤权、删除、归档、过期、被取代或当前授权不可用。不要把它改回 valid；应从
+权威来源重新构建新的 Context Version。若 attempt 完全没有版本，检查生产 Composition Root、
+`AGENT_CONTEXT_HOST_URL`、内部 Token、ContextVersion 路由和 Provider/模型循环 Adapter。每次
+attempt 必须先 prepare 来源，在 DLP/Provider governance 后、Provider 调用前 commit 最终消息与
+请求 digest；该写入失败必须阻止 attempt，不能事后补记录冒充实际输入。若所有 Context/Memory
+读取都稳定 503，通常是来源定义已存在但权威 Adapter 未装配；未支持来源应继续 fail closed，
+而不是绕过 Guard。
+
+## 有表无 Memory
+
+识别信号是 `agent_memory_projections` 已存在 active 行，或五类表结构已创建，但新的长期 Session
+attempt 仍只包含当前 user prompt/`turn.started`，没有带来源的 Session Summary、历史结果或可用
+Memory。先检查生产 Composition Root 是否同时实例化五类 Memory Projector append 入口与
+Retriever，再核对终态 Run、Session 摘要、用户确认和模块核验路径是否实际调用 append。Retriever
+必须在每次 attempt 重新执行 Actor、Scope、Feature、License、TTL、复核状态和逐来源对象授权；
+缺少 module-authoritative Adapter 的业务 Memory 应稳定拒绝，不能为了让表中数据“可见”而绕过。
+业务模块入口应来自 `ModuleRequestContext.sessionMemory`，而不是直接拿 Repository；若 SSE 客户端
+断开后缺最终结果，检查下一次 prepare 是否对未关闭 `run.linked` 执行终态复核与幂等补投。
+
+## Turn 已关闭但结果 Memory 或 Receipt 缺失
+
+这是终态崩溃窗信号。先核对 `agent_session_run_projection_receipts`、对应 `run.linked`、Remote terminal
+sequence 和两个确定性 Memory ID。正确顺序是幂等投影、写 Receipt、再关闭 Turn；Reconciler 必须
+扫描 closed-but-unprojected 并补齐，不能因已见 `turn.completed` 就跳过。结果 digest 或 sequence
+冲突时保留证据并 fail closed，禁止手工伪造 Receipt。单项 Memory 是用户可删除投影，Receipt 不应
+将其复活。
+
+## Case Memory 混入其它案件
+
+检查业务 Operation 是否显式提供当前 `caseId`，以及 Retriever 是否仍把
+`derived_from_session_id` 当案件坐标。Session 血缘只表示派生来源，不能证明当前案件或跨案授权。
+缺少明确案件坐标时 Case Memory Candidate 与 Verified Fact Reference 必须 fail closed；即使有
+`caseId`，仍要由所属模块的权威对象 Adapter 复核，不能批量混合其它案件候选。
+
+再核对 Run binding、`turn.started.currentCaseId`、`agent_context_versions.current_case_id` 与
+`agent_memory_projections.current_case_id`。四处必须是同一规范化值；相同幂等键若出现不同值应直接
+冲突。历史恢复 SQL 只能匹配相同坐标；无案件坐标不能读取案件版本。V1 没有跨案 grant，不得以
+Session ID、前端选择或模块自报参数代替。
+
+## Working Context 长期不失效
+
+识别信号是 Working Context 没有 `expires_at`、超过 24 小时仍 active，或过期后 Context/Search/
+Embedding 仍可命中。所有自动 Working Context 必须具有 Run/Turn 生命周期和最长 24 小时 TTL；
+检查过期 Scheduler、条件更新和 `source-expired` 五路 Delivery。不要延长 TTL 来掩盖 Worker 未装配，
+也不要把完整用户文本或 assistant 输出永久晋升为 Session Summary。
+
+若投影已过期但消费它的 Context 或派生 Memory 仍 active，检查 Context/Memory source 表是否同时
+保存该 Memory 的直接 `memoryId` 坐标与底层来源链。只保存底层业务来源会使 TTL 事件无法命中直接
+消费者。Memory-to-Memory 来源允许递归复核，但环、超过 32 层或累计坐标超限必须拒绝。
+
+## Oxfmt 报告找不到 node 或 bun
+
+不要重复执行同一失败命令。该工作区的 `node_modules/.bin/oxfmt` 使用 `#!/usr/bin/env node`，而非交互
+Session 的 PATH 可能没有 Node/Bun。先用 `command -v` 定位运行时；Bun 位于默认用户目录时，可执行
+`~/.bun/bin/bun node_modules/oxfmt/bin/oxfmt --write <files>`。运行时路径不存在则停止，
+记录未格式化文件并交给具备仓库运行时的集中验证，不要安装另一套依赖或反复触发同一错误。
+
+## 业务来源状态变化但没有失效 Outbox
+
+检查业务模块是否通过 Host 绑定的 `ModuleRequestContext.sourceInvalidation` 在来源事务中发布，并确认
+权威 Adapter 已注册。调用方若能自报 Module Key、Actor 或 Scope，说明绕过了 Producer seam；应
+立即停止该入口。deleted、expired、superseded 与 authorization-revoked 都必须有领域事件坐标和
+稳定幂等 ID，缺少 Producer 或事务 append 时 fail closed，不能事后造无因果补偿。
+
+## SSE 读取要求 manage 或终态写入只检查 read
+
+这是读写授权混淆。纯 `/agent/runs/:runId/events` 只需要既有 Run read 权限和持久 binding 读取校验，
+不应要求 `system.agent-session.manage`。result projection、cancel、attach 以及任何会追加长期 Session
+事实的路径，必须重新执行 Session Feature、License、manage Guard，并核对客户端 `sessionId` 与
+持久 Run binding。不要为了修终态旁路而阻断只读 SSE。
+
+## Context 早于 DLP
+
+识别信号包括：治理拒绝后仍有 active Context Version；持久消息含已被 DLP 删除的内容；记录的
+digest 无法从最终 Provider request 复算；或日志显示 Provider 调用早于 Context commit。停止相关
+长期 Session attempt，保留版本、Provider receipt 和审计证据。正确顺序是 prepare 候选来源，完成
+DLP 与 Provider policy，随后在 Provider 看到输入前 commit 最终消息、来源关系和 request digest；
+commit 失败或治理拒绝都不产生 active 版本。不要修改旧版本 digest 追平请求，应重新创建新 attempt。
+
+## 终态权限旁路
+
+识别信号是用户不能启动绑定 Session 的 Run，却能通过 result、cancel 或 attach 路径追加
+`turn.completed`、`run.cancelled`、Artifact 或其它长期事实；另一信号是请求提供任意 `sessionId`
+即可写入。每个终态路径都必须重新检查 `system.agent-session` Feature、License 和
+`system.agent-session.manage`，并比较客户端 `sessionId` 与持久 `run.linked` 绑定。两者不一致时
+拒绝写 Session；未绑定长期 Session 的普通 Run 保持原有终态行为。
+
+## 幂等跨 Session
+
+识别信号是两个 Session/Turn 用相同 Actor、Operation、key 和 input 启动后得到同一 Run ID，或
+第二个 Session 的 `run.linked` 指向已属于第一个 Session 的 Run。幂等坐标必须包含长期
+Session/Turn（或等价绑定 digest），持久绑定还要保证一 Run 只能属于一个 Session。修复后不得把
+旧 Run 重新挂到新 Session；保留原绑定，并为新 Session 创建独立 Run 或返回明确绑定冲突。
+
+## Session 归档后派生投影仍保持 active
+
+检查归档 Outbox 的 scope 是否为 `session-derived`。若只发布 `sourceKind=session`，而消费者按业务
+来源类型匹配，Context/Memory 不会收敛。归档应按 Session ID 失效该 Session 的派生投影；它不是
+任意业务来源的 `source-deleted`，不能扩散到其它 Session 或权威对象。
+
+若 session-scope 投影已失效，但同一 Session 派生的 user/case Memory 仍 active，说明消费者把
+Memory 使用 scope 当成派生关系。检查每个投影的 `derived_from_session_id` 与
+`derived_through_sequence`，并按前者匹配归档失效；不能只筛 `scope_kind=session`。恢复时从仍有效
+的权威来源重新投影，不能手工把遗留 user/case 行改成 session scope。
+
+该模式也称为“archive 仅按 scope”：归档消费者错误地按投影使用范围判断派生关系。
+
+## Memory 候选被当成业务事实
+
+立即停止下游使用。Case Memory Candidate 只能是 pending 或 rejected；模型摘要不能自动升级为
+业务事实。正确做法是由业务模块核验并生成新的 Verified Fact Reference，保留权威 resource、
+version 与 digest，不能原地修改候选类型或跨案合并。
+
+## payload 无法解密
+
+核对部署 Secret、恢复时间点和数据库来源。不得尝试用新 Secret 覆盖旧密文，也不要把明文导出
+到日志排障。保留样本、digest 与备份，在隔离环境确认是 Secret 漂移、密文损坏还是错误数据库。

package/template/docs/operations/agent-workflow-recovery.md

@@ -0,0 +1,74 @@
+# Agent Workflow 运维与恢复速查
+
+## Model Pricing readiness
+
+Model Node 在任何 Provider 调用前都会核对当前 `modelAttempts`、剩余 Token 与成本预算，并要求服务端冻结的价格目录覆盖实际 deployment/model。运维通过 `WINDY_AGENT_WORKFLOW_MODEL_PRICING_JSON` 提供 `version`、`currency` 与 `prices[]`；当前唯一支持的 `currency` 是精确大写 `USD`，其它币种在 Composition 阶段直接拒绝。每项包含 `deploymentKey`、`model`、`inputMicrosPerMillion`、`outputMicrosPerMillion`。允许用 `model: "*"` 表示该 deployment 的受控默认价格，但更精确的模型项优先。
+
+未配置时 `GET /api/agent/workflows/readiness` 返回 `MODEL_PRICING_UNAVAILABLE`，Model Node 不会调用 Provider。非法 JSON 或非法金额会在 Runtime composition 时 fail fast。价格变更会产生新的 catalog digest 并进入 Node execution evidence；发布前必须按 Provider 或采购合同核实，不能把示例 `0` 当作真实价格。
+
+Rubric 与安全评测使用平台固定的受治理 Tool 角色 Key：`agent.workflow.evaluation.rubric` 与 `agent.workflow.evaluation.safety`，不接受评测请求指定 Tool。业务 Module 只需在 Manifest 注册对应 Tool、Schema、Feature、Permission、Audit Action 与真实 Handler；生产 Composition 会从已完成双向契约校验的 `GovernedToolRegistry` definitions 解析并注入，不需要再次修改平台接线。两项 Tool 必须声明审批和幂等；缺少注册、Handler、Schema 或审计事实时不注入角色，评测保持 `unavailable`，平台不提供降级 Handler 或伪造结果。
+
+## Workspace 与委派授权 readiness
+
+子 Agent 的 Workspace 必须由 project-owned Server Composition 通过 `agentWorkflowWorkspacePolicies` 注册权威 Policy。Policy 需要返回自身管理的稳定 `workspaceId`、Scope 关系与 digest；Runtime 提供的 `workspaceGrantId` 只是幂等请求坐标，不能被当作 Workspace 事实。没有注册、Workspace 已撤销或 Scope 子集无法证明时，Subagent Node 在创建 child Session/Run 前 fail closed。
+
+冻结 grant 会进入 child Run authorization snapshot。此后每次 Tool 调用都重新读取 Delegation、Workspace Policy、当前 Actor/Feature/Permission/License、Tool allowlist、Scope proof 与 active Budget reservation；任何撤权或 coordinate 漂移都会被 Tool Host 拒绝，不能只靠创建时 digest 放行。
+
+## 并行与 deadline
+
+Scheduler 先用 Run/Node CAS 持久 claim 多个 ready Node，再并发调用 Adapter；只有 Node/Event 收敛写入由本进程 mutation queue 串行化。全局 admission 以最新快照中的 `running + waiting` 对比 `Run.budget.maxParallelism`，跨 worker 仍依靠 Run 行锁与 event sequence CAS 防止超配。批次退出或请求中断后由 Durable Job continuation 用原 Node/command/fence 恢复。
+
+Node deadline 始终取 Node 与 Run deadline 的较早值。超时先协调既有外部执行和 usage，再持久化 Node `timed-out`；随后通过取消链终结 sibling、Side Effect 和 Budget reservation，并收敛 Run `timed-out`，不会借用 retry/skip/fallback failure policy。Condition 未选分支不参与 Join；`join:any` 会取消 loser 独占分支的全部活跃后代，并保留 winner/shared 路径。
+
+## 先确认事实
+
+排查顺序固定为 Workflow Run → Node Run → side-effect command → canonical Event → Adapter receipt →
+ArtifactRef。不要从 Web 图、日志文本或子 Agent 最终回答反推业务事实。主站状态与数据库不一致时，
+以 PostgreSQL 的 version、event sequence、command status 和 receipt 为准。
+
+## 重复故障速查
+
+| 现象                              | 核对                                                              | 安全处置                                                       |
+| --------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------- |
+| Run 长期 `running`                | deadline、cancellation、活跃 Node、head sequence                  | 只对合法非终态执行 Recovery；不要直接改状态                    |
+| Node 重启后重复调用外部系统       | prepared/committed command、idempotency key、Adapter receipt      | 先 reconcile 同一 command；禁止创建新 key 盲重试               |
+| condition 后继不明确              | Node result receipt 的 `selectedBranch`、digest、terminal Event   | receipt 缺失则 fail closed；不得重新让模型选择                 |
+| 子 Agent 权限拒绝                 | Release required guards、父级 ceiling、当前 Host、Scope/Workspace | 修复真实授权或发布新 Release；不得从请求中删除 required guards |
+| Budget 显示还有余量但不能继续     | reservation、Provider usage measurement status                    | unknown 不是零；补真实计量或终止，不手工放宽                   |
+| Approval/Job 已完成但 Node 仍等待 | command external receipt、Work Item/Job 当前事实                  | 用原 command coordinate reconcile 后原子提交 Node 终态         |
+| Artifact 无法打开                 | ArtifactRef source/hash/retention、当前对象授权                   | 每次重新授权并签短期 token；不得持久化旧下载 URL               |
+| Evaluation unavailable            | 两臂 Release、Run、Provider、metrics source、rubric evidence      | 保留 unavailable 与 reason；不得创建假 Run 或填零              |
+| Web 图与节点列表不同              | API Run projection、浏览器缓存、Graph adapter                     | 先刷新 canonical 投影；图坐标不是 Runtime 事实                 |
+
+## 取消与恢复
+
+取消先持久化 Run cancellation request，再传播到未终结 Node、子 Agent 和可取消 Adapter。迟到的
+Provider、Tool 或 Job 响应只能用于协调既有 command，不能把已取消 Run 改成完成。不能取消的
+外部副作用保留 receipt 和审计，由领域补偿流程处理；Workflow Runtime 不伪造回滚。
+
+Recovery 必须在一个受控入口执行：读取最新 Run/Node/version/sequence，重新取得当前 Actor、
+Feature、Permission、License、Scope 与对象授权，核对冻结 policy digest，串行化预留父级剩余
+Budget，然后协调 side-effect command。授权收窄、Release 漂移、unknown usage、receipt 冲突或
+非法状态转换都应终止恢复并记录安全错误码。
+
+## Fresh deploy 与保留
+
+本次基线只支持清空旧开发 Docker 容器及数据卷后的空数据库首次部署。按 migration 顺序执行到
+0061；0061 只有 DDL，不包含旧 Agent 会话、聊天、logs 的清理、搬迁或兼容 DML。部署后检查所有
+Run 下游外键不是 cascade。生产留存或删除必须另行形成受治理策略，不能直接删除 Run 抹掉历史。
+
+## 真实验收清单
+
+- 空 PostgreSQL 顺序执行到 0061，并验证重复执行的 migration tracker 语义；
+- 在进程退出故障点分别覆盖外部副作用提交前、提交后 receipt 前、Node 终态前和后继提交前；
+- 覆盖并发 Recovery/CAS、取消与迟到响应、deadline、retry/backoff/skip/fail-run；
+- 覆盖真实并发 branch、全局 `maxParallelism`、Condition 非参与分支和嵌套 `join:any` loser 取消；
+- 覆盖父级剩余 Budget 并发预留、unknown token/cost fail closed、子 Agent 授权收窄；
+- 用真实 Workspace Registry 验证 child Session/Run 与每次 Tool 调用撤权后的 fail-closed；
+- 覆盖 Approval Work Item、Durable Job、write Tool 和 Subagent 四类 command reconciliation；
+- 使用真实 Provider 和相同冻结坐标执行单/多 Agent 双臂评测，保存每 arm 原始可复核 evidence；
+- 验证 Artifact 每次打开重新授权，过期 token 不进入 Event、receipt 或业务表；
+- 验证主站只读图、语义节点列表和对象授权，且没有在线编辑入口。
+
+普通代码静态检查、单元测试、build 或空数据库 fixture 都不能替代上述真实环境证据。正式合并候选
+运行 `bun run test:merge`，只有冻结发布候选才运行 `bun run release:verify`。

package/template/docs/operations/incremental-delivery.md

@@ -176,7 +176,7 @@ resource fork 或 Finder metadata。路径组件以 `._` 开头时直接拒绝
 ## 构建与旧项目升级
 
 `packages/delivery`、本说明和 `delivery:remote` 脚本自 `create-windy@0.6.7` 起进入受管
-Starter；当前公开版为 `0.6.9`，最低支持基线 `0.6.6` 可通过连续 recipe 事务升级，现有
+Starter；当前 registry 公开版为 `0.6.12`，最低支持基线 `0.6.6` 可通过连续 recipe 事务升级，现有
 project-owned 发布脚本不会被覆盖。正式构建先准备一个完整 release 目录，其中
 `images.tar` 必须是 OCI image layout（含 `oci-layout`、`index.json` 和
 `blobs/sha256/*`），再运行：

package/template/docs/platform/agent-production-store.md

@@ -0,0 +1,82 @@
+# Agent 生产 Store、不可变 Release 与评估追踪
+
+## 目标与边界
+
+Agent Runtime 的 PostgreSQL Store 是多副本生产默认实现。它只保存 Run
+执行事实、加密后的调用/事件/结果、Release 快照和评估结果，不保存业务会话、消息、
+标题、案件范围或归档策略。业务事实仍由业务模块持久化。
+
+SQLite Store 只用于单副本本地开发和确定性验证；未配置
+`AGENT_DATABASE_URL` 且配置了 `AGENT_RUN_STORE_PATH` 时才启用。生产部署不得用
+共享文件系统模拟多副本 SQLite。
+
+## 状态与反馈闭环
+
+同一个 `Idempotency-Key` 只能对应同一请求指纹。Run 的 canonical event 使用
+`run_id + sequence` 唯一键，读取接口按 cursor 重放；终态后追加、完成和取消都是
+幂等操作。事件或输出超过上限时，Store 写入唯一的 `run.failed`，避免运行态无限
+增长。
+
+每个工作副本领取 30 秒租约，并每 10 秒续租。租约丢失会中止当前执行，保留加密
+调用快照供其他副本接管；恢复轮询使用行锁和 `skip locked` 防止重复领取。终态数据
+按 TTL 清理，运行中数据不会被 TTL 清理。
+
+## 不可变 Release 与回滚
+
+每次 Run 固定以下坐标：
+
+- Operation 与模块版本；
+- Workflow、Prompt 和模型 Route 版本；
+- Tool/输出 Schema 摘要；
+- Manifest 摘要。
+
+这些坐标生成稳定的 `releaseId`。同一 `releaseId` 只能对应同一快照，冲突时
+fail closed，不能原地修改。业务模块通过
+`ModuleAiOperationHandlerRegistration.release` 显式声明 Workflow、Prompt 和
+Route 版本；未声明时使用模块版本。
+
+回滚不是修改历史 Release，而是重新部署此前的模块/注册版本。旧 Release 仍保留，
+新 Run 会固定到回滚后的旧坐标，历史 Run、评估和审计关联不会被改写。
+
+## 评估、用量、Attempt、审计和 Trace
+
+`POST /api/agent/evaluations` 仅接受内部 Token，可按 Release、评估集 Key 和评估集
+版本幂等记录指标；同一坐标提交不同结果会拒绝。`usage.reported` 作为加密 canonical
+event 保存。Provider attempt 审计以 `runId + attempt` 唯一保存，并可通过 Run 关联
+Release、usage 和平台 Audit。
+
+平台将请求关联值哈希为 128 位 Trace ID。Agent Runtime 用它建立 OTel 父 Trace，
+Span 只包含 Run ID、Operation Key、Release ID 和终态，不写 Prompt、业务输入、
+模型输出、Tool 参数、Actor 或 Secret。配置
+`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 后启用 OTLP/HTTP 导出，认证头由
+`OTEL_EXPORTER_OTLP_HEADERS` 注入。
+
+## 运维配置
+
+生产 Agent profile 必须配置：
+
+```dotenv
+AGENT_DATABASE_URL=postgresql://...
+AGENT_RUN_ENCRYPTION_SECRET=至少32字节随机值
+AGENT_SERVER_INTERNAL_TOKEN=随机内部令牌
+```
+
+可选配置：
+
+```dotenv
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://collector.example/v1/traces
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20...
+```
+
+加密密钥缺失或不足 32 字节时 Runtime 拒绝启动。数据库迁移必须先于 Agent Server
+启动。Provider attempt 的独立审计 Store 仍按
+`AI_PROVIDER_AUDIT_RETENTION_DAYS` 执行留存；不可把它与业务日志混用。
+
+## 故障与恢复
+
+- PostgreSQL 不可用：启动 fail closed；运行中的副本停止续租，不继续产生副作用。
+- 副本退出：租约过期后由其他副本恢复加密调用，不创建新 Run。
+- OTLP 不可用：BatchSpanProcessor 按 OTel 导出策略处理，不向业务响应暴露 Collector
+  细节；Run Store 与平台 Audit 仍是业务审计事实。
+- Release 快照冲突、评估结果漂移或幂等键漂移：稳定拒绝，要求修正发布输入。
+- 超过容量、事件数或输出大小：写入或返回有界失败，不允许无界降级。

package/template/docs/platform/agent-run-reattachment.md

@@ -0,0 +1,52 @@
+# Agent Run 安全恢复
+
+## 目标
+
+业务应用可以在刷新、断网或页面重开后，使用 Operation Key、Run ID 和最后消费的
+事件游标继续读取同一个 Agent Run。恢复不会新建 Run，也不会让浏览器持有内部
+Execution Grant。
+
+## 所有权边界
+
+- 业务层持久化会话、消息、Run ID 与最后确认的事件游标。
+- 平台层持久化 Run 与 Actor、Operation、授权范围及不可变 Release 的绑定。
+- Agent Runtime 持久化执行事实、事件、结果和工具调用事实。
+- 浏览器只持有业务标识，不读取或保存平台内部 Token。
+
+平台数据库不可用时只启用进程内绑定仓储，供本地开发使用；生产环境必须配置
+PostgreSQL，才能在服务重启和多副本切换后安全恢复。
+
+## 恢复协议
+
+客户端调用 `attach(operation, runId, { cursor, signal })`，也可使用语义相同的
+`resume`。平台先验证游标，再返回当前状态、事件入口和可选终态事件。事件流从
+游标之后继续，客户端按 sequence 去重。
+
+每次 attach、events、result 与 cancel 都重新检查：
+
+1. 当前 Actor 与 Run 绑定的 Actor 完全一致；
+2. Operation 与创建 Run 时一致，且当前 Release 仍可用；
+3. 当前 Feature、Permission 与 License 仍允许访问；
+4. 当前数据范围快照与创建 Run 时一致；
+5. 绑定未超过保留期。
+
+未知 Run、Actor 不匹配、Operation 不匹配、范围变化、权限收回和绑定过期统一
+返回 `404 RUN_CONFLICT`，避免通过错误差异探测 Run 是否存在。
+
+## Tool Host 与重启
+
+平台使用内部密钥为 Actor、Operation 和幂等键派生确定性 Execution Grant，
+数据库只保存 Token Hash。Agent Runtime 可在平台重启后继续使用原 Grant；
+Tool Host 通过 Hash 找回绑定，并再次解析当前 Actor 与所有 Guard。
+
+绑定保存创建时的最小授权快照和 Release ID。若 Operation、Tool Schema、网络
+策略或 Release 已变化，旧 Run 的新工具调用会 fail closed。Tool handler 仍以
+`toolCallId` 作为业务写入幂等键，因此恢复不会扩大重复写入窗口。
+
+## 保留与运维
+
+绑定默认保留七天，过期记录在签发新 Run 时清理。该表不保存 Prompt、输入、
+输出、业务消息或 Artifact 内容，不扩大业务数据留存范围。
+
+`AGENT_SERVER_INTERNAL_TOKEN` 同时是平台与 Agent Runtime 的内部认证根密钥，
+必须至少 32 字节，只能通过服务端环境变量注入，禁止下发到 Web。

package/template/docs/platform/agent-runtime-observability.md

@@ -81,9 +81,10 @@ opaque handle。报表与列表读取写入关键审计 `agent.runtime.report.re
 读取当前范围内的模型组合。详情中每个 Attempt 同时保留 `sequence`、`deploymentKey`、
 `requestedModel` 与可为空的 `reportedModel`，不会把实际回报伪装成请求值。
 
-ADK Web 的 canonical bridge 仍以专用调试服务身份调用平台，但报表归属使用
-`toModuleActor(context.actor)` 后的真实数据用户，使开发调试用量进入正确的业务范围，
-而不是泄露或冒充普通登录会话。
+主站 Runtime Report 与业务会话投影始终使用当前登录身份。Server 以
+`toModuleActor(context.actor)` 形成受限模块 Actor，并按当前范围过滤 Run；不存在专用
+调试服务身份或第二种 Token。这样开发调试用量进入正确业务范围，同时不会泄露内部 Actor
+ID 或冒充其它登录会话。
 
 ## Agent Server 内部接口与指标