Sandyzzx · Oct 7, 2026 · Oct 7, 2026 · Oct 7, 2026 · Oct 7, 2026 · Oct 7, 2026
diff --git a/.gitignore b/.gitignore
@@ -10,13 +10,5 @@ plugins/codex-zcode-bridge/.mcp.local.json
 .env
 .env.*
 !.env.example
-# Current shared-core contracts are versioned; other local research stays local.
-!docs/
-docs/*
-!docs/SHARED_CORE.md
-!docs/ARCHITECTURE.md
-!docs/INTERFACES.md
-!docs/ZCODE_RUNTIME.md
-!docs/PHASE7_LIVE_PROGRESS.md
-!docs/research/
-!docs/research/**
+# Documentation is versioned by default. Scratch material belongs in docs/_draft/.
+docs/_draft/
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,31 @@
+# AGENTS.md
+
+本仓库把 Codex 的任务派发给本机 ZCode 执行。任何 agent 动手前先读这份文件。
+
+## 阅读顺序
+
+1. `docs/README.md` —— 文档路由、状态等级、语言约定。
+2. `docs/PROJECT_STATE.md` —— 当前状态快照：稳定、实验、不支持、调查中。
+3. 按任务类型读权威文档：架构改动读 `docs/ARCHITECTURE.md`，接口改动读 `docs/INTERFACES.md`，宿主接入读 `docs/SHARED_CORE.md`，运行配置读 `docs/ZCODE_RUNTIME.md`。
+4. 需要知道"为什么这样定"时读 `docs/decisions/`。
+5. `docs/archive/` 默认不读，只有调查历史决策时才读。
+
+## 文档等级
+
+每份文档顶部标注四种状态之一：`AUTHORITATIVE` 当前事实或合同、`DECISION` 已批准决策、`RESEARCH` 研究结论、`ARCHIVED` 历史材料。研究结论和归档材料不能当作当前实现使用。
+
+## 硬规则
+
+- 改变 `docs/ARCHITECTURE.md`、`docs/INTERFACES.md`、`docs/SHARED_CORE.md`、`docs/ZCODE_RUNTIME.md` 描述的行为前，先有 `DECISION` 记录。实现不能反向改写合同。
+- 公共 MCP 工具名与 schema、任务状态语义、隐私边界、新增运行时依赖，都属于合同变更。
+- 研究材料放 `docs/research/`，草稿放 `docs/_draft/`（已忽略）。不要把未定稿留在 `docs/` 顶层。
+- 语言：`README.md` 英文，技术文档中文，`docs/README.md` 双语索引。
+- 核心权威文档控制在 10 份以内。单份超过约 15 KB，或同一主题被三个以上独立读者分读，才拆成多份。
+- 写结论时区分"已核实"和"未运行"。不要把 NOT RUN 写成通过，也不要把尝试过的方法写成可行方法。
+- 引用 ZCode 内部结构时标明观测版本，用 Observed 措辞，不要写成官方合同。
+
+## 提交与验证
+
+- 代码改动跑 `npm run typecheck`、`npm test`、`npm run build`、`npm run validate:plugin`，并保证 `git diff --check` 干净。
+- `plugins/codex-zcode-bridge/dist/bridge.mjs` 与 `worker/worker-main.mjs` 是提交物，必须与源码同步；CI 会校验它们没有落后。
+- 不默认提交、推送或发布。发布走 release-please，合并到 `master` 之后由它生成版本 PR。
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -10,6 +10,8 @@ Manager 用进程内 promise 队列以及同一 data root 下的 `.tasks/.manage
 
 未启动 worker 可重拉一次；抢占过的 attempt 不会重复执行。已开始的 worker 不自动重跑。worker 丢失但记录的 ZCode PID 仍存活时保留占用，要求 `zcode_cancel` 验证清理。清理失败的终态任务也保留目录与 slot；续跑被拒绝，再次 cancel 成功后才释放。进程身份依赖 PID；操作系统重用 PID 和自行脱离进程组的后代属于未充分验证的边界。
 
+worker 每 3 秒原子写入一次绑定 attempt 与 PID 的私有 heartbeat，字段含 session、turn、Bridge event 序号和已观测到的 ZCode event 序号。管理器遇到一次负向 PID 探测时，若 heartbeat 不超过 15 秒则暂缓失联判定。ZCode turn 完成后，worker 在清理进程前写入 outcome checkpoint，并在清理成功后更新验证标志；worker 在提交最终 result 之前退出时，管理器可据 checkpoint 恢复报告，清理未验证则保留 `cleanup_failed` 与 workspace 占用。
+
 续跑先复制旧结果到 attempt 归档、准备 continue spec，再提交新 attempt 的 queued 状态。旧 root result 在提交前可恢复，在提交后因 attempt 不匹配不会被视为新结果。即使准备过程崩溃，原终态仍可读取。
 
 审批记录按 attempt 隔离，公开 request ID 也带 attempt。相同 ID 的方法与规范化参数（包括 session 和输入）必须一致，否则拒绝。超时、取消和结束均 abort 待处理 interaction，释放 worker 轮询。

diff --git a/docs/INTERFACES.md b/docs/INTERFACES.md
@@ -10,7 +10,7 @@ TaskPackage 的五个数组必须存在，可为空。workspace 是绝对项目
 
 任务 objective、requirements、路径、验收、测试命令及续跑 feedback 不截断；完整 prompt 超过 60,000 字符会返回 TASK_INVALID。参考 context 与旧结果摘要仍有明确的截断标记，不能把安全约束只放在参考 context。
 
-zcode_events 使用单调 seq cursor、limit 1–200、wait_ms 0–25,000、raw/summary view。summary 合并可见输出时会注明压缩。运行时事件先核对 session、单调 runtime seq 和可用 turn ID；存在历史事件的 session 必须观察新 turn.started 后才接受结束事件。缺少某些身份字段的旧协议仍有兼容路径，真实跨版本行为未全部验证。
+zcode_events 使用单调 seq cursor、limit 1–200、wait_ms 0–25,000、raw/summary view。summary 合并可见输出时会注明压缩。公开事件只包含可见文本、工具名称与状态，以及有限的生命周期 metadata；隐藏 reasoning 和未知 usage metadata 不进入公开事件。订阅前记录 `snapshot.runtime.eventSeq`。live 订阅连续 10 秒没有新事件时，每 5 秒按已观测序号向 `session/events` 补拉一次，重放仍经过同样的 session、单调 runtime seq 和 turn ID 过滤；runtime 明确拒绝该方法时降级为纯 live 订阅，连续 3 次失败后同样降级，两种情况都会发出可见的 `session_event_replay_unavailable` 事件。协议变化不能只靠字符串方法名推断支持。`session/read` 未接入，原生当前状态查询仍为 NOT RUN。运行时事件先核对 session、单调 runtime seq 和可用 turn ID；存在历史事件的 session 必须观察新 turn.started 后才接受结束事件。缺少某些身份字段的旧协议仍有兼容路径，真实跨版本行为未全部验证。
 
 `zcode_feedback` 是独立的 `TaskFeedbackSnapshotV01` v0.1 聚合层，含 `schema_version: "0.1"`，并返回结构化 snapshot 与简洁文本。它不替代 `zcode_events`，也不改变 `TaskResult`、状态接口或已持久化记录。字段来源分为 Bridge task state（task、attempt、status、起止时间和墙钟 duration）、runtime-observed（只接受当前 attempt 规范化 `model_selected`、`model_tool_call`、`tool_status` 事件中的 allowlisted 字段）和 Agent report（仅当前 attempt 出现 `report_ready`、结果 attempt/status 匹配且结果为 `completed` 或 `waiting_for_master` 时，标记 `source: "agent_report"`）。模型不从请求或 catalog 回退；runtime model 缺失时为 `null`。`phase` 与 `progress` 固定为 `null`。activity 使用 Bridge 持久化事件时生成的 observation timestamp，语义固定为 `last_observed`；不表达工具仍在运行。交互状态固定为 `not_observed`，表示 snapshot 未确立可靠的当前交互状态，不表示历史中没有交互或没有待处理请求；原始交互事件仍由 `zcode_events` 提供。该 snapshot 不包含 runtime turn outcome 或 Bridge failure reason 字段，因此文本只显示可由 Bridge status 支持的完成/失败状态，不推断 turn 成功、目标完成或主机验收。Agent 报告中的 summary、文件、tests 与 issues 均不是 Bridge 独立验证结果。
 

diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md
@@ -0,0 +1,48 @@
+# Project State
+
+> Status: AUTHORITATIVE
+> Last updated: 2026-10-07
+> Last verified: 2026-10-07，核对来源见文末。
+
+当前状态快照，回答"现在什么能用、什么不能用"。路线图和优先级不在这里。
+
+## 版本与发布
+
+- 当前发布：`1.2.2`（`package.json`、`plugins/codex-zcode-bridge/plugin.json`）。
+- 发布方式：release-please 监听 `master`，合并后自动开版本 PR；合并版本 PR 才产生 tag 与 GitHub Release。
+- CI：`.github/workflows/ci.yml`，ubuntu 与 windows 两个作业，跑 typecheck、build、test、validate:plugin，并校验生成的 bundle 已随源码提交。
+
+## 稳定
+
+- TaskManager 生命周期：`queued` / `running` / `completed` / `failed` / `cancelled` / `waiting_for_master`，含 attempt 独占、续跑归档、清理验证。
+- MCP 默认工具 13 个，清单见 `INTERFACES.md`。
+- `zcode_events` 的增量事件、cursor 与 raw/summary 视图。
+- `zcode_feedback` 的 `TaskFeedbackSnapshotV01`。
+- 工作区隔离：执行目录由调用宿主准备，Bridge 不创建也不删除 worktree。
+- 模型选择：可按任务覆盖 provider/model，不持久化为工作区默认。
+- 并发：同一 data root 内默认最多 8 个 worker，可用 `ZCODE_BRIDGE_MAX_CONCURRENT_WORKERS` 在 1–8 之间调整。
+
+## 实验
+
+- `zcode_progress_probe`：默认关闭，只有直接调用 `createBridgeServer({ enableExperiments: true })` 才注册。
+- Desktop 索引同步：best effort，事务内校验 schema 与 Bridge owner；尚未写入真实 Desktop 数据库。
+
+## 不支持
+
+- Start Plan 的 headless 认证：app-server 需要桌面渲染器提供的验证码会话，Bridge 不伪造、不绕过。当前 headless 开发路径使用 Coding Plan。见 `research/start-plan-headless-2026-09-27.md`。
+
+## 调查中 / NOT RUN
+
+以下边界没有实跑验证，不能当成已知可用：
+
+- `session/read` 原生当前状态查询：未接入。
+- 真实 ZCode app-server RPC 探针与跨版本兼容：只在记录过的 0.16.9 路径上观测过。
+- 真实 ZCode 权限审批往返：现有回归使用假运行时，未经真实交互验证。
+- 跨 Host 并发 attach/control：研究阶段结论为 NO-GO，除非上游提供 ownership/control 协议。
+- 真实 GUI 关闭时序、UI 响应与取消时延。
+- 真实 Desktop 数据库写入与刷新行为。
+- PID 重用，以及自行脱离进程组的后代进程。
+
+## 核对来源
+
+`package.json`、`src/host/stdio.ts`、`src/mcp/server.ts`、`src/worker/run-task.ts`、`src/adapters/zcode-app-server-adapter.ts`、`docs/ARCHITECTURE.md`、`docs/INTERFACES.md`、GitHub Actions 运行记录。文中标注"未运行"的条目没有被上述来源证实，保持未验证状态。
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,123 @@
+# 文档索引 / Documentation
+
+英文使用者从 [README.md](../README.md) 开始。技术文档为中文。本文是文档路由：先看状态等级，再按读者路径选文档。
+
+English readers start at [README.md](../README.md). This index is bilingual; the technical documents themselves are written in Chinese.
+
+## 状态等级 / Status levels
+
+每份文档顶部标注四种状态之一。这是本仓库最重要的一条约定：没有状态标注的文档不能被当成事实依据。
+
+| 状态 | 含义 | 使用方式 |
+|---|---|---|
+| `AUTHORITATIVE` | 当前事实或合同 | 可以据此开发和判断 |
+| `DECISION` | 已批准的架构决策 | 引用它回答"为什么不那样做" |
+| `RESEARCH` | 研究结论 | 只作参考，不代表当前实现 |
+| `ARCHIVED` | 历史材料 | 默认不读，只用于追溯 |
+
+现状说明：下面的现有文档在本次整理前没有状态标注，状态由本索引统一指定。文档下次被修改时补上顶部标注。
+
+## For Master Agents
+
+按顺序读，不要通读全仓库文档：
+
+1. `docs/PROJECT_STATE.md` —— 当前状态快照（稳定 / 实验 / 不支持 / 调查中）
+2. `docs/ARCHITECTURE.md` —— 系统现在怎么工作
+3. `docs/INTERFACES.md` —— 合同与兼容边界
+4. `docs/decisions/README.md` —— 已批准决策索引
+5. 只在需要证据时读 `docs/research/`
+
+不要默认读 `docs/archive/`。
+
+## For Coding Agents
+
+1. 本任务涉及的合同文档（`INTERFACES.md` / `ZCODE_RUNTIME.md` / `SHARED_CORE.md`）
+2. 对应组件的架构（`ARCHITECTURE.md`）
+3. `AGENTS.md` 里的硬规则
+
+实现不能自行改写合同。需要改合同先提 `DECISION`。
+
+## 索引 / Index
+
+### 权威文档 AUTHORITATIVE
+
+| 文档 | 语言 | 最后更新 | 最后核对 |
+|---|---|---|---|
+| [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 | 未记录 |
+| [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 | 未记录 |
+
+`最后核对` 表示上一次有人把文档内容与代码逐条对照的日期。这一列目前全部为空，说明此前没有这个习惯；新建和修改文档时必须填写，否则该文档只能算"最后更新"，不能算"已验证"。
+
+### 决策 DECISION
+
+| 文档 | 日期 | 说明 |
+|---|---|---|
+| [decisions/README.md](decisions/README.md) | 2026-10-07 | 决策索引 |
+| [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 决策 |
+| [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 | 可靠性修复计划，含未完成项 |
+
+### 研究 RESEARCH
+
+| 文档 | 日期 | 说明 |
+|---|---|---|
+| [research/phase1-codex-zcode-2026-09-26.md](research/phase1-codex-zcode-2026-09-26.md) | 2026-09-26 | Phase 1 参考项目调研与 V0.1 架构建议 |
+| [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 篇文档、实验脚本与证据索引 |
+
+带日期的研究目录可以自带 README 作为该主题的文档地图；逐篇条目写在那份 README 里，不重复列在本索引。
+
+### 归档 ARCHIVED
+
+| 文档 | 日期 | 说明 |
+|---|---|---|
+| [archive/appserver-capability-matrix-2026-09-27.md](archive/appserver-capability-matrix-2026-09-27.md) | 2026-09-27 | app-server 能力普查，已被 2026-10-05 的能力探针取代 |
+| [archive/mvp-v0.3-2026-09-27.md](archive/mvp-v0.3-2026-09-27.md) | 2026-09-27 | MVP 0.3 版本说明 |
+| [archive/mcp-sdk-v2-migration-2026-09-27.md](archive/mcp-sdk-v2-migration-2026-09-27.md) | 2026-09-27 | MCP SDK v2 迁移记录 |
+| [archive/phase7-live-progress.md](archive/phase7-live-progress.md) | 2026-10-03 | Phase 7 兼容说明；有效内容已提炼进 `ARCHITECTURE.md` / `INTERFACES.md` |
+
+### 报告 REPORT
+
+| 文档 | 说明 |
+|---|---|
+| [TASK_FEEDBACK_V01_IMPLEMENTATION_REPORT.md](../TASK_FEEDBACK_V01_IMPLEMENTATION_REPORT.md) | Task Feedback v0.1 的交付报告，一次性材料 |
+
+### 自动生成 Generated
+
+| 文档 | 说明 |
+|---|---|
+| [CHANGELOG.md](../CHANGELOG.md) | 由 release-please 维护，不要手改 |
+
+## 新文档放哪里
+
+| 内容 | 位置 |
+|---|---|
+| 当前事实、合同 | `docs/` 顶层，数量控制在 10 份以内 |
+| 已批准决策 | `docs/decisions/ADR-NNN-<slug>.md` |
+| 研究结论与证据 | `docs/research/<topic>-<YYYY-MM-DD>/` |
+| 一次性交付报告 | `docs/reports/` |
+| 已被取代的材料 | `docs/archive/<phase-or-topic>/` |
+| 未定稿草稿 | `docs/_draft/`（已 gitignore，不进仓库） |
+
+## 仓库外的材料
+
+以下内容有意不放进仓库，追溯时按下表位置查找：
+
+| 位置 | 内容 |
+|---|---|
+| `C:\Users\Sandy\.codex\archived_docs\codex-zcode-bridge\` | 全库审计报告、生命周期可观测性方案、ccteam 对比、整改报告、验收证据 JSON |
+| `<repo>\.tasks\notes\` | 会话期笔记；属于桥接运行数据根，不是版本化文档 |
+
+桥接运行数据根 `.tasks/` 只放任务记录，不要在那里存放研究用的外部仓库克隆。