Sandyzzx · Oct 7, 2026 · Oct 7, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -14,6 +14,17 @@
 
 每份文档顶部标注四种状态之一：`AUTHORITATIVE` 当前事实或合同、`DECISION` 已批准决策、`RESEARCH` 研究结论、`ARCHIVED` 历史材料。研究结论和归档材料不能当作当前实现使用。
 
+权威文档的顶部至少包含：
+
+```markdown
+> Status: AUTHORITATIVE
+> Last updated: YYYY-MM-DD
+> Last verified: YYYY-MM-DD（核对了哪几条；只核对了一部分就写明范围）
+> Verified against: <commit SHA>
+```
+
+`Last updated` 和 `Last verified` 是两件事：改过不等于核对过。`Verified against` 记录核对时代码停在哪个提交，指码已经前进很多时应当重新核对。索引汇总在 `docs/README.md`，但不能代替文档自身的标注。
+
 ## 硬规则
 
 - 改变 `docs/ARCHITECTURE.md`、`docs/INTERFACES.md`、`docs/SHARED_CORE.md`、`docs/ZCODE_RUNTIME.md` 描述的行为前，先有 `DECISION` 记录。实现不能反向改写合同。

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -1,7 +1,42 @@
 # 当前架构
 
+> Status: AUTHORITATIVE
+> Last updated: 2026-10-07
+> Last verified: 2026-10-07（本轮核对 heartbeat 周期与 15 秒宽限、结果 checkpoint、事件补拉与降级；其余条款沿用此前记录，未逐条复核）
+> Verified against: ed2d402
+
 本文件描述当前代码，不是历史阶段的冻结设计。公共类型见 `src/interfaces.ts`，MCP schema 见 `src/mcp/schemas.ts`；共享边界见 [SHARED_CORE.md](SHARED_CORE.md)。
 
+## 总览
+
+```text
+Codex 宿主
+   │ MCP（stdio）
+Bridge MCP server（src/mcp）
+   │
+TaskManager（src/manager）
+   ├─ TaskStore（src/store）        任务证据持久化
+   ├─ 调度队列与 worker 启动
+   └─ 事件与 feedback 聚合
+   │
+ZCodeAppServerAdapter（src/adapters）
+   │
+ZCode app-server（zcode.cjs app-server --stdio）
+```
+
+| 组件 | 负责 | 不负责 |
+|---|---|---|
+| MCP server | 对外契约面：工具名、输入 schema、输出结构 | 任务状态判定 |
+| TaskManager | 生命周期所有者：排队、调度、attempt 边界、终态、续跑、清理 | ZCode 协议细节 |
+| TaskStore | 任务证据持久化：status、result、events、attempt 元数据 | 业务判断 |
+| Worker | 单 attempt 的执行进程，一次进入、不重跑 | 调度决策 |
+| AppServerAdapter | ZCode 协议边界：session、事件、交互、清理 | 宿主策略 |
+| 调用宿主 | 准备执行目录、决定是否接收改动 | 任务调度 |
+
+合同级定义见 [INTERFACES.md](INTERFACES.md)。
+
+## 运行细节
+
 `src/mcp/main.ts` 仅为 Codex 入口；`src/host/stdio.ts` 组合宿主 profile、运行配置、TaskStore、DirectWorkspaceProvider、BridgeTaskManager 和 MCP server。启动不创建 ZCode session；坏的 Bridge 配置会明确阻止启动。doctor 对坏配置返回 error。
 
 Manager 用进程内 promise 队列以及同一 data root 下的 `.tasks/.manager.lock` 序列化调度。锁记录 owner PID，活 owner 不因时间超限被驱逐；死 owner 由串行 reclaim guard 回收。未完成 owner 发布的异常锁明确报错。不同 data root 不共享调度锁，需要调用宿主避免向重叠目录提交冲突任务。PID 重用的跨进程身份强化尚未验证。

diff --git a/docs/INTERFACES.md b/docs/INTERFACES.md
@@ -1,5 +1,10 @@
 # 当前接口与兼容边界
 
+> Status: AUTHORITATIVE
+> Last updated: 2026-10-07
+> Last verified: 2026-10-07（本轮核对事件补拉与降级、`session/read` 未接入、默认工具数 13；其余条款沿用此前记录，未逐条复核）
+> Verified against: ed2d402
+
 准确类型与 schema 以 `src/interfaces.ts` 和 `src/mcp/schemas.ts` 为准。核心公共入口见 [SHARED_CORE.md](SHARED_CORE.md)。历史源码注释中的 V0.1/FROZEN 是沿革说明，不代表当前新增功能已经冻结。
 
 默认 MCP 工具：`zcode_task`、`zcode_status`、`zcode_feedback`、`zcode_result`、`zcode_continue`、`zcode_cancel`、`zcode_events`、`zcode_interaction_reply`、`zcode_doctor`、`zcode_model_catalog`、`zcode_default_model`、`zcode_set_default_model`、`zcode_clear_default_model`。实验 progress probe 需显式启用。
@@ -19,3 +24,5 @@ zcode_interaction_reply 必须引用当前 attempt 的 interaction_requested.req
 稳定错误包括 TASK_INVALID、TASK_ALREADY_EXISTS、TASK_ID_CONFLICT、CONTINUE_OPERATION_CONFLICT、BRIDGE_BUSY、REQUEST_QUEUE_TIMEOUT、TASK_NOT_FOUND、TASK_NOT_FINISHED、TASK_STATE、CANCEL_FAILED，以及 runtime/provider、timeout、invalid_agent_report 等执行错误。相同 task_id 与相同任务内容会重放首次回执；不同内容返回 TASK_ID_CONFLICT。超时后使用原 task_id 查询或重试，不要换 ID。续作可传 operation_id；相同 ID 与相同反馈会重放回执，不同反馈返回 CONTINUE_OPERATION_CONFLICT。cleanup_failed 表示运行时清理未验证，任务保持目录占用；再次 zcode_cancel 尝试清理后保留原执行结果。
 
 公开进度 usage 仅保留数值 token/cost 字段，隐藏推理、未知 metadata 和原始 RPC error 不转发。审批需要的工具输入、任务 prompt、可见回答、私有本地日志仍属于可能含敏感内容的任务证据，使用者须按本地数据策略管理。
+
+控制面、权威状态与补充观察的边界见 [decisions/ADR-004](decisions/ADR-004-separate-control-state-and-observation.md)：ZCode 本地 metadata、rollout 与日志可以进入补充观察，但不得单独决定任务状态、状态迁移或恢复结论；Desktop `tasks-index.sqlite` 是登记过的 best-effort 集成例外。
diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md
@@ -6,6 +6,8 @@
 
 当前状态快照，回答"现在什么能用、什么不能用"。路线图和优先级不在这里。
 
+控制面、权威 Bridge 状态与补充观察的边界见 [decisions/ADR-004](decisions/ADR-004-separate-control-state-and-observation.md)：本地材料可以观察，但不能单独驱动任务状态、状态迁移与恢复结论。
+
 ## 版本与发布
 
 - 当前发布：`1.2.2`（`package.json`、`plugins/codex-zcode-bridge/plugin.json`）。

diff --git a/docs/README.md b/docs/README.md
@@ -1,5 +1,8 @@
 # 文档索引 / Documentation
 
+> Status: AUTHORITATIVE（仅指本索引）
+> Last updated: 2026-10-07
+
 英文使用者从 [README.md](../README.md) 开始。技术文档为中文。本文是文档路由：先看状态等级，再按读者路径选文档。
 
 English readers start at [README.md](../README.md). This index is bilingual; the technical documents themselves are written in Chinese.
@@ -15,7 +18,7 @@ English readers start at [README.md](../README.md). This index is bilingual; the
 | `RESEARCH` | 研究结论 | 只作参考，不代表当前实现 |
 | `ARCHIVED` | 历史材料 | 默认不读，只用于追溯 |
 
-现状说明：下面的现有文档在本次整理前没有状态标注，状态由本索引统一指定。文档下次被修改时补上顶部标注。
+每份文档必须在顶部自带标注；本索引只做汇总，不能代替标注。跳过本索引直接打开某份权威文档时，也应能从文件顶部看到状态与核对情况。
 
 ## For Master Agents
 
@@ -46,15 +49,15 @@ English readers start at [README.md](../README.md). This index is bilingual; the
 | [README.md](../README.md) | en | 2026-10-05 | 未记录 |
 | [README.zh-CN.md](../README.zh-CN.md) | zh | 2026-10-03 | 未记录 |
 | [PROJECT_STATE.md](PROJECT_STATE.md) | zh | 2026-10-07 | 2026-10-07 |
-| [ARCHITECTURE.md](ARCHITECTURE.md) | zh | 2026-10-03 | 未记录 |
-| [INTERFACES.md](INTERFACES.md) | zh | 2026-10-06 | 未记录 |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | zh | 2026-10-07 | 2026-10-07（部分） |
+| [INTERFACES.md](INTERFACES.md) | zh | 2026-10-07 | 2026-10-07（部分） |
 | [SHARED_CORE.md](SHARED_CORE.md) | zh | 2026-10-06 | 未记录 |
 | [ZCODE_RUNTIME.md](ZCODE_RUNTIME.md) | zh | 2026-10-03 | 未记录 |
 | [plugins/codex-zcode-bridge/README.md](../plugins/codex-zcode-bridge/README.md) | zh | 2026-10-03 | 未记录 |
 | [plugins/codex-zcode-bridge/SECURITY.md](../plugins/codex-zcode-bridge/SECURITY.md) | zh + en | 2026-10-03 | 未记录 |
 | [plugins/codex-zcode-bridge/skills/zcode-bridge/SKILL.md](../plugins/codex-zcode-bridge/skills/zcode-bridge/SKILL.md) | zh | 2026-10-06 | 未记录 |
 
-`最后核对` 表示上一次有人把文档内容与代码逐条对照的日期。这一列目前全部为空，说明此前没有这个习惯；新建和修改文档时必须填写，否则该文档只能算"最后更新"，不能算"已验证"。
+`最后核对` 表示上一次有人把文档内容与代码逐条对照的日期，`（部分）` 表示只核对了其中一部分条款，具体范围写在文档顶部的 `Last verified` 行。`未记录` 不等于内容有问题，只表示还没有人做过这次核对。新建和修改文档时必须填写，否则该文档只能算"最后更新"，不能算"已验证"。
 
 ### 决策 DECISION
 
@@ -64,7 +67,7 @@ English readers start at [README.md](../README.md). This index is bilingual; the
 | [ADR-001](decisions/ADR-001-appserver-as-production-execution-path.md) | 2026-10-07 | Accepted：生产执行路径使用 app-server |
 | [ADR-002](decisions/ADR-002-manager-owns-task-lifecycle.md) | 2026-10-07 | Accepted：Manager 独占生命周期，worker 通过 attempt claim 入场 |
 | [ADR-003](decisions/ADR-003-execution-directory-prepared-by-host.md) | 2026-10-07 | Accepted：执行目录由调用宿主准备 |
-| [ADR-004](decisions/ADR-004-observation-is-not-control.md) | 2026-10-07 | Proposed：本地材料只作观察面，待 Master 决策 |
+| [ADR-004](decisions/ADR-004-separate-control-state-and-observation.md) | 2026-10-07 | Accepted：分离运行时控制、权威状态与补充观察 |
 | [decisions/roadmap-decisions-2026-09-27.md](decisions/roadmap-decisions-2026-09-27.md) | 2026-09-27 | 路线图与决策讨论 |
 | [decisions/reliability-repair-plan-v2-2026-10-03.md](decisions/reliability-repair-plan-v2-2026-10-03.md) | 2026-10-03 | 可靠性修复计划，含未完成项 |
 
@@ -76,6 +79,7 @@ English readers start at [README.md](../README.md). This index is bilingual; the
 | [research/desktop-task-refresh-2026-09-28.md](research/desktop-task-refresh-2026-09-28.md) | 2026-09-28 | ZCode Desktop 任务列表刷新机制 |
 | [research/start-plan-headless-2026-09-27.md](research/start-plan-headless-2026-09-27.md) | 2026-09-27 | Start Plan headless 认证阻塞与 Coding Plan 回归 |
 | [research/native-cli-vs-appserver-2026-10-05/README.md](research/native-cli-vs-appserver-2026-10-05/README.md) | 2026-10-05 | Native CLI vs app-server 研究：结论、6 篇文档、实验脚本与证据索引 |
+| [research/task-feedback-v0-1-2026-10-05/README.md](research/task-feedback-v0-1-2026-10-05/README.md) | 2026-10-05 | Task Feedback v0.1 的输入：app-server 事件能力探针与两份建议 |
 
 带日期的研究目录可以自带 README 作为该主题的文档地图；逐篇条目写在那份 README 里，不重复列在本索引。
 
@@ -92,7 +96,7 @@ English readers start at [README.md](../README.md). This index is bilingual; the
 
 | 文档 | 说明 |
 |---|---|
-| [TASK_FEEDBACK_V01_IMPLEMENTATION_REPORT.md](../TASK_FEEDBACK_V01_IMPLEMENTATION_REPORT.md) | Task Feedback v0.1 的交付报告，一次性材料 |
+| [reports/task-feedback-v0-1-implementation-2026-10-06.md](reports/task-feedback-v0-1-implementation-2026-10-06.md) | Task Feedback v0.1 的交付报告，一次性材料 |
 
 ### 自动生成 Generated
 

diff --git a/docs/SHARED_CORE.md b/docs/SHARED_CORE.md
@@ -1,5 +1,9 @@
 # 共享核心与宿主适配
 
+> Status: AUTHORITATIVE
+> Last updated: 2026-10-06
+> Last verified: 未逐条核对
+
 Codex 与 dsh 连接同一个 ZCode 执行端，因此任务调度、存储、续跑、取消、结果归一化、ZCode 协议和 Desktop 索引属于共享核心。`src/adapters/` 适配 ZCode，不是调用宿主。
 
 公共入口是 `codex-zcode-bridge/core`（源码 `src/core.ts`）。入口没有启动副作用，提供类型声明，并导出 `buildTaskFeedbackSnapshotV01` 与 `renderTaskFeedback`。`npm run build:core` 构建核心；当前仓库仍为 private，未发布独立 npm 包。可在本地构建后用 `npm pack` 生成版本化制品供 fork 锁定；发布渠道和独立核心版本策略尚未确定。

diff --git a/docs/ZCODE_RUNTIME.md b/docs/ZCODE_RUNTIME.md
@@ -1,5 +1,9 @@
 # ZCode 运行配置边界
 
+> Status: AUTHORITATIVE
+> Last updated: 2026-10-03
+> Last verified: 未逐条核对
+
 当前生产路径是 `node zcode.cjs app-server --stdio`，不是历史 CLI `--prompt --json`。解析入口为 `NodeRuntimeResolver`，配置项与用户设置方法见仓库 README。
 
 Bridge 只读取官方 builtin/personal provider 配置，不复制、不改写内容，也不将环境或凭据写入任务 metadata。personal 配置的 `config.providerConfigRules.providerRules` 必须为非空数组或对象；已知空 stub 被拒绝。结构验证不能证明 provider 可用或账号有权限。

diff --git a/docs/decisions/ADR-004-observation-is-not-control.md b/docs/decisions/ADR-004-observation-is-not-control.md