@tea-agent/loop-agent 0.35.0 → 0.35.1-beta.0

package/AGENTS.md

@@ -1,108 +1,108 @@
-<!-- CODEGRAPH_START -->
-## CodeGraph
-
-如果仓库根目录存在 `.codegraph/`，在理解或定位代码前优先使用 CodeGraph，再考虑 rg/fd 或手动读文件。
-<!-- CODEGRAPH_END -->
-
-# AGENTS.md
-
-本仓库采用“人类掌舵，智能体执行”的工程方式。目标不是一次性写完所有代码，而是在一个可持续演进、可交接、可验证的系统里做小步增量。
-
-`AGENTS.md` 是地图，不是百科。顶层只保留开工协议、会话协议与文档导航；长期知识、方法论、决策、计划、报告和模板应进入 `docs/`。
-
-## 默认立场
-
-- 仓库是记录系统：决策、契约、计划、测试、报告优先落到仓库，而不是停留在聊天里。
-- 一次只推进一个清晰工作块；主会话按 Orient → Select → Contract → Implement → Verify → Handoff 治理，runtime 真实流程以 `src/workflows/` 为准。
-- 先验证基线，再叠加改动；完成定义必须可验证，不能靠删测试、降标准或模糊描述制造“完成”。
-- Do not consider backward compatibility. Ignore legacy code/libraries.
-- 搜索先于实现；受治理 Agent runtime 只有 Pi（`implement-pi` / `repair-pi`）；`cursor-prompt` 仅为显式手工 one-shot sidecar。
-- DAG 标准路径：Contract → Scout → Plan → Implement → Verify → Closeout/Handoff。
-- 机器校验契约真源：`docs/init-surface.manifest.json`、`docs/architecture/runtime-boundaries.md`、`src/cli/command-definitions.ts`、`skills/loop-agent/`、`scripts/check-*.sh`；本文件只指路。
-- 本仓库既是源项目也是 init 默认模板；新增能力必须判断 npm 内置 vs `loop-agent init` 投影。
-- 委托写入前必须结构化 `task.json.allowedPaths` / `forbiddenPaths`，并审查 DAG writer `writeSet`。
-- Shell 搜索优先 `rg`，按名找文件优先 `fd`；脚本用 Git Bash / 兼容 Bash。
-- 用 loop-agent 迭代本仓库时，控制器必须来自已发布 npm 包（记录实际版本）；启动后不要中途升级；不要用工作区 `npm link` / `npm run dev` 控制可能改 CLI/runtime/package 的任务。
-- 反复出现的约束固化为文档、脚本、检查、测试或模板；禁止占位实现（除非 contract 标明脚手架）。
-- 非微小实现：`exec-plan` 不能替代 Agent DAG；除非用户要求 one-shot 或计划记录 escape hatch，否则改实现前完成 `task advance`（PRD + 结构化路径边界）、writeSet gate 审查与 `task advance --approve-gate`。
-- **实现默认 DAG，主会话不直接改代码**：只要是实现/修复/行为或展示语义变更（含 observe 文案映射、runtime status、schema、executor、CLI 等），主会话只做 Orient / 建 task / dry-run / validate / writeSet 审查 / 执行与监视 DAG，**不得**自己改 `src/**`、`test/**` 等交付面。仅当用户**明确授权**主会话直接处理（例如「直接改」「主会话改」「one-shot」「不用 DAG」）时，才允许主会话写入；授权后仍须记录边界、allowedPaths 与验证证据。纯答疑、读代码、查状态、提交/推送已有 diff、或用户点名的文档微调（如本文件规则）不在此限。
-- 不要自行引入外部 SDD/spec-first 等强制平行治理树；以本文件与 `docs/` 为准（ADR 0006）。
-
-## 开始顺序
-
-改文件前必须先完成：
-
-1. `pwd` → 读 `README.md`、`harness.json`、`docs/README.md`；有 `CONTEXT.md` 则读术语表。
-2. 实现类工作继续读：`docs/governance/development-principles.md`、`docs/governance/feature-workflow.md`、`docs/governance/verification-matrix.md`。
-3. 涉及命令/executor/init/skills/发布包/治理检查时继续读：`docs/architecture/runtime-boundaries.md`、`docs/runtime/loop-agent-harness.md`。
-4. 涉及测试纪律/验证声明/调试时继续读：`docs/governance/harness-methodology-*.md`。
-5. 查看最近提交、相关 plan/progress/report；`git status --short --branch`；跑最小基线验证。
-6. 后端/接口/pytest → `taskKind: "backend-test"`（不是 `--profile`）；知识回写 `knowledge-sync`；图谱开荒 `knowledge-graph-bootstrap`。`--profile` 仅 `auto|minimal|standard|reviewed|supervised`。
-7. 看板/observe → `agent-worker console`（默认 repo=当前目录、port=8790；listen 成功后默认打开系统浏览器，`--no-open` 禁止）（`/inspect/` 只读）；`observe serve` 已下线（`OBSERVE_SERVE_REMOVED` + exit 2）；`observe snapshot` 仍可用。
-8. 分支合并 → 先读 `docs/operations/branch-merge-guideline.md`。
-
-## 会话协议
-
-1. Orient → 2. Select（一块）→ 3. Contract → 4. Implement → 5. Verify → 6. Converge Docs → 7. Handoff。
-
-这不是 DAG 节点序列。实现默认 Agent DAG；主 agent 拆任务、写 contract、结构化路径、审查 DAG/writeSet/profile/shell verification，**不自行 implement**。主会话 one-shot 仅在用户明确授权时可用，并记录边界与验证证据；「看起来很小」或「只是展示文案」不构成授权——若改动触及 runtime/status/映射语义，仍走 DAG。
-
-启动 loop-agent DAG 流程后，主 agent 应自主推进到整个流程结束，不要中途请求无谓的人工确认（如“要我现在执行 DAG 吗？”）。只要 dry-run / validate / writeSet 审查通过就应直接执行并跑完全部 ranks；遇到真问题（契约不一致、writeSet 越界、verify 失败且超出 maxFixLoops、用户明显未授权的高风险动作）才停。即便 profile 是 supervised/reviewed，也不默认在 review-gate 主动停下等人——控制器会在需要人工 approve 时自行提示，主 agent 的职责是推动流程跑完。
-
-DAG 执行期间主 agent 必须持续轮询监视直到 run 结束（FINISHED / FAILED / 需要 approve），不能轮询一次就停下等用户；轮询间隔应合理（避免频繁唤醒浪费 token，也不得住一个节点上赌一次就走）。判活必须用可靠方式：看 `state.json` 的 `runner.heartbeatAt` 是否持续刷新 + `session-events.jsonl` 是否在增长 + `dag doctor` 的 `liveness` 字段，不要只用 `tasklist /FI "PID eq X"` 这类过滤语法在 Git Bash 下会误报 DEAD，从而错判一个正常工作的 run 为 orphaned。遇到疑似 stall 先按 `docs/runtime/agent-dag-runner.md` 查 `lastMeaningfulProgressAt` / provider 活动，有真实进展就继续等，绝不盲目 supersede。持续监视过程中，主 agent 可在合适节点（例如 rank/节点状态变化、进入 verify/closeout、出现 stall 嫌疑或需要 approve 时）向用户做简短进度汇报（当前节点、状态、是否有风险），避免长时间静默；汇报是告知，不是请求确认，不得因此停下流程。
-
-DAG 执行期间，主 agent 不得修改 writeSet 外的任何工作区文件（包括 AGENTS.md、docs、根配置等）。bounded writer 节点的 write guard 用「节点运行期间的工作区 diff」作为越界证据，不区分改动来自 pi 还是主会话——主会话在 pi 节点跑的时候改了 writeSet 外文件，会让 write guard 把账算到 pi 头上、判节点 ERROR、下游 cascade skip。需要改文档/约束时，要么在 DAG 启动前改完，要么等 run 结束后改；务必与 DAG 写入节点在时间上互斥。排查任务路由问题时优先用 `resolveTaskDagTemplateSelection` / `classifyTaskDemand` 等纯函数探针或 `--output` 指定临时路径，不要反复 `dag execute --dry-run` / 无必要的 lifecycle 探测。dry-run 不执行节点；若确需预演，检查命令返回的 `.harness/dag-runs/dry-run/<runId>/` `runDir`，它不进入 active overview，也不能作为 `dag resume` 目标。优先用纯函数探针或 `task status`。
-
-## 项目地图
-
-- `CONTEXT.md`：术语表
-- `src/`：运行时；`test/`：Vitest；`bin/loop-agent.js`：CLI
-- `skills/`：源仓库/npm 内置 skills；目标项目只生成 `.agents/skills/`
-- `.harness/`：运行态（tasks/dag-runs/runs 等；init 会 gitignore 运行事实，保留 prompts 与占位）
-- `docs/`：治理；`website/`：用户文档站；`scripts/`：检查与 CI
-
-## 工作规则（增量约束）
-
-- 保留无关用户改动；优先沿用现有 helper/目录边界。
-- 长期决策写入 `docs/`；面向用户变更更新 `CHANGELOG.md`（结果导向中文）。
-- init/投影变更必须同步目标项目生成物与 package assets；init evolution 按 `docs/init-surface.manifest.json` 分级。
-- CLI/skill entry/runtime boundary/发布包变更同步 catalog、脚本与测试。
-- 明确的前端页面/UI/组件/交互实现需求必须设置 `taskKind: "frontend-implementation"`（不是 `--profile`），不得保留默认 `standard`；浏览器/UI 自动化测试继续使用 `taskKind: "frontend-test"`。
-- 没有新鲜验证证据时不声明完成；新债写入 plan/progress/report。
-
-## 验证
-
-权威源：`docs/governance/verification-matrix.md`。
-
-默认节奏：编辑中只跑矩阵「最低验证」（typecheck + 定向 Vitest）；`git commit` 的 `pre-commit` 只做 `check-repo`；`git push` 的 `pre-push` 经 `node scripts/pre-push-verify.mjs` 在 receipt 命中时复用、miss 时跑 full `bash scripts/ci.sh`（全量 typecheck + `npm test`）。每个 clone 安装一次 hooks：`bash scripts/install-git-hooks.sh`。
-
-连续 source→target 交付遵循**单一最终树全量验证**：同一 Git tree、相同环境与命令合同在 receipt TTL 内只选一个本地 full authority（有效 receipt / target pre-push / 可选 `npm run verify:tree`），不按分支名策略化，也不机械双跑 full CI。细节见 verification-matrix 与 branch-merge-guideline。
-
-常用：
-
-```bash
-# 编辑中
-npm run typecheck
-npx vitest run <相关测试路径>
-
-# 可选：提前验证当前 clean HEAD 并写 receipt（随后同 tree push 可复用）
-npm run verify:tree
-
-# push / 交付前（或依赖 pre-push；receipt miss 时安全回退 full）
-bash scripts/ci.sh
-npm run build
-node bin/loop-agent.js --help
-```
-
-文档站变更：`npm run docs:build`。init / architecture / skill entry / pack 定向验证见 verification-matrix。
-
-## 交接
-
-记录：改了什么、为什么、验证命令与结果、契约/文档/测试影响、剩余风险、后续工作。
-
-## 禁止事项
-
-- 未读相关文档就大改；一次混合无关重构/新功能/文档大迁移。
-- 把对话约束当长期知识；缺验证宣称完成；假设系统没有某能力（先搜索）。
-- stub/假数据通路替代交付；把本机绝对路径写入仓库级 AGENTS/README/模板/发布包。
-- 只更新本仓库体验而遗漏目标项目 init 体验。
+<!-- CODEGRAPH_START -->
+## CodeGraph
+
+如果仓库根目录存在 `.codegraph/`，在理解或定位代码前优先使用 CodeGraph，再考虑 rg/fd 或手动读文件。
+<!-- CODEGRAPH_END -->
+
+# AGENTS.md
+
+本仓库采用“人类掌舵，智能体执行”的工程方式。目标不是一次性写完所有代码，而是在一个可持续演进、可交接、可验证的系统里做小步增量。
+
+`AGENTS.md` 是地图，不是百科。顶层只保留开工协议、会话协议与文档导航；长期知识、方法论、决策、计划、报告和模板应进入 `docs/`。
+
+## 默认立场
+
+- 仓库是记录系统：决策、契约、计划、测试、报告优先落到仓库，而不是停留在聊天里。
+- 一次只推进一个清晰工作块；主会话按 Orient → Select → Contract → Implement → Verify → Handoff 治理，runtime 真实流程以 `src/workflows/` 为准。
+- 先验证基线，再叠加改动；完成定义必须可验证，不能靠删测试、降标准或模糊描述制造“完成”。
+- Do not consider backward compatibility. Ignore legacy code/libraries.
+- 搜索先于实现；受治理 Agent runtime 只有 Pi（`implement-pi` / `repair-pi`）；`cursor-prompt` 仅为显式手工 one-shot sidecar。
+- DAG 标准路径：Contract → Scout → Plan → Implement → Verify → Closeout/Handoff。
+- 机器校验契约真源：`docs/init-surface.manifest.json`、`docs/architecture/runtime-boundaries.md`、`src/cli/command-definitions.ts`、`skills/loop-agent/`、`scripts/check-*.sh`；本文件只指路。
+- 本仓库既是源项目也是 init 默认模板；新增能力必须判断 npm 内置 vs `loop-agent init` 投影。
+- 委托写入前必须结构化 `task.json.allowedPaths` / `forbiddenPaths`，并审查 DAG writer `writeSet`。
+- Shell 搜索优先 `rg`，按名找文件优先 `fd`；脚本用 Git Bash / 兼容 Bash。
+- 用 loop-agent 迭代本仓库时，控制器必须来自已发布 npm 包（记录实际版本）；启动后不要中途升级；不要用工作区 `npm link` / `npm run dev` 控制可能改 CLI/runtime/package 的任务。
+- 反复出现的约束固化为文档、脚本、检查、测试或模板；禁止占位实现（除非 contract 标明脚手架）。
+- 非微小实现：`exec-plan` 不能替代 Agent DAG；除非用户要求 one-shot 或计划记录 escape hatch，否则改实现前完成 `task advance`（PRD + 结构化路径边界）、writeSet gate 审查与 `task advance --approve-gate`。
+- **实现默认 DAG，主会话不直接改代码**：只要是实现/修复/行为或展示语义变更（含 observe 文案映射、runtime status、schema、executor、CLI 等），主会话只做 Orient / 建 task / dry-run / validate / writeSet 审查 / 执行与监视 DAG，**不得**自己改 `src/**`、`test/**` 等交付面。仅当用户**明确授权**主会话直接处理（例如「直接改」「主会话改」「one-shot」「不用 DAG」）时，才允许主会话写入；授权后仍须记录边界、allowedPaths 与验证证据。纯答疑、读代码、查状态、提交/推送已有 diff、或用户点名的文档微调（如本文件规则）不在此限。
+- 不要自行引入外部 SDD/spec-first 等强制平行治理树；以本文件与 `docs/` 为准（ADR 0006）。
+
+## 开始顺序
+
+改文件前必须先完成：
+
+1. `pwd` → 读 `README.md`、`harness.json`、`docs/README.md`；有 `CONTEXT.md` 则读术语表。
+2. 实现类工作继续读：`docs/governance/development-principles.md`、`docs/governance/feature-workflow.md`、`docs/governance/verification-matrix.md`。
+3. 涉及命令/executor/init/skills/发布包/治理检查时继续读：`docs/architecture/runtime-boundaries.md`、`docs/runtime/loop-agent-harness.md`。
+4. 涉及测试纪律/验证声明/调试时继续读：`docs/governance/harness-methodology-*.md`。
+5. 查看最近提交、相关 plan/progress/report；`git status --short --branch`；跑最小基线验证。
+6. 后端/接口/pytest → `taskKind: "backend-test"`（不是 `--profile`）；知识回写 `knowledge-sync`；图谱开荒 `knowledge-graph-bootstrap`。`--profile` 仅 `auto|minimal|standard|reviewed|supervised`。
+7. 看板/observe → `agent-worker console`（默认 repo=当前目录、port=8790；listen 成功后默认打开系统浏览器，`--no-open` 禁止）（`/inspect/` 只读）；`observe serve` 已下线（`OBSERVE_SERVE_REMOVED` + exit 2）；`observe snapshot` 仍可用。
+8. 分支合并 → 先读 `docs/operations/branch-merge-guideline.md`。
+
+## 会话协议
+
+1. Orient → 2. Select（一块）→ 3. Contract → 4. Implement → 5. Verify → 6. Converge Docs → 7. Handoff。
+
+这不是 DAG 节点序列。实现默认 Agent DAG；主 agent 拆任务、写 contract、结构化路径、审查 DAG/writeSet/profile/shell verification，**不自行 implement**。主会话 one-shot 仅在用户明确授权时可用，并记录边界与验证证据；「看起来很小」或「只是展示文案」不构成授权——若改动触及 runtime/status/映射语义，仍走 DAG。
+
+启动 loop-agent DAG 流程后，主 agent 应自主推进到整个流程结束，不要中途请求无谓的人工确认（如“要我现在执行 DAG 吗？”）。只要 dry-run / validate / writeSet 审查通过就应直接执行并跑完全部 ranks；遇到真问题（契约不一致、writeSet 越界、verify 失败且超出 maxFixLoops、用户明显未授权的高风险动作）才停。即便 profile 是 supervised/reviewed，也不默认在 review-gate 主动停下等人——控制器会在需要人工 approve 时自行提示，主 agent 的职责是推动流程跑完。
+
+DAG 执行期间主 agent 必须持续轮询监视直到 run 结束（FINISHED / FAILED / 需要 approve），不能轮询一次就停下等用户；轮询间隔应合理（避免频繁唤醒浪费 token，也不得住一个节点上赌一次就走）。判活必须用可靠方式：看 `state.json` 的 `runner.heartbeatAt` 是否持续刷新 + `session-events.jsonl` 是否在增长 + `dag doctor` 的 `liveness` 字段，不要只用 `tasklist /FI "PID eq X"` 这类过滤语法在 Git Bash 下会误报 DEAD，从而错判一个正常工作的 run 为 orphaned。遇到疑似 stall 先按 `docs/runtime/agent-dag-runner.md` 查 `lastMeaningfulProgressAt` / provider 活动，有真实进展就继续等，绝不盲目 supersede。持续监视过程中，主 agent 可在合适节点（例如 rank/节点状态变化、进入 verify/closeout、出现 stall 嫌疑或需要 approve 时）向用户做简短进度汇报（当前节点、状态、是否有风险），避免长时间静默；汇报是告知，不是请求确认，不得因此停下流程。
+
+DAG 执行期间，主 agent 不得修改 writeSet 外的任何工作区文件（包括 AGENTS.md、docs、根配置等）。bounded writer 节点的 write guard 用「节点运行期间的工作区 diff」作为越界证据，不区分改动来自 pi 还是主会话——主会话在 pi 节点跑的时候改了 writeSet 外文件，会让 write guard 把账算到 pi 头上、判节点 ERROR、下游 cascade skip。需要改文档/约束时，要么在 DAG 启动前改完，要么等 run 结束后改；务必与 DAG 写入节点在时间上互斥。排查任务路由问题时优先用 `resolveTaskDagTemplateSelection` / `classifyTaskDemand` 等纯函数探针或 `--output` 指定临时路径，不要反复 `dag execute --dry-run` / 无必要的 lifecycle 探测。dry-run 不执行节点；若确需预演，检查命令返回的 `.harness/dag-runs/dry-run/<runId>/` `runDir`，它不进入 active overview，也不能作为 `dag resume` 目标。优先用纯函数探针或 `task status`。
+
+## 项目地图
+
+- `CONTEXT.md`：术语表
+- `src/`：运行时；`test/`：Vitest；`bin/loop-agent.js`：CLI
+- `skills/`：源仓库/npm 内置 skills；目标项目只生成 `.agents/skills/`
+- `.harness/`：运行态（tasks/dag-runs/runs 等；init 会 gitignore 运行事实，保留 prompts 与占位）
+- `docs/`：治理；`website/`：用户文档站；`scripts/`：检查与 CI
+
+## 工作规则（增量约束）
+
+- 保留无关用户改动；优先沿用现有 helper/目录边界。
+- 长期决策写入 `docs/`；面向用户变更更新 `CHANGELOG.md`（结果导向中文）。
+- init/投影变更必须同步目标项目生成物与 package assets；init evolution 按 `docs/init-surface.manifest.json` 分级。
+- CLI/skill entry/runtime boundary/发布包变更同步 catalog、脚本与测试。
+- 明确的前端页面/UI/组件/交互实现需求必须设置 `taskKind: "frontend-implementation"`（不是 `--profile`），不得保留默认 `standard`；浏览器/UI 自动化测试继续使用 `taskKind: "frontend-test"`。
+- 没有新鲜验证证据时不声明完成；新债写入 plan/progress/report。
+
+## 验证
+
+权威源：`docs/governance/verification-matrix.md`。
+
+默认节奏：编辑中只跑矩阵「最低验证」（typecheck + 定向 Vitest）；`git commit` 的 `pre-commit` 只做 `check-repo`；`git push` 的 `pre-push` 经 `node scripts/pre-push-verify.mjs` 在 receipt 命中时复用、miss 时跑 full `bash scripts/ci.sh`（全量 typecheck + `npm test`）。每个 clone 安装一次 hooks：`bash scripts/install-git-hooks.sh`。
+
+连续 source→target 交付遵循**单一最终树全量验证**：同一 Git tree、相同环境与命令合同在 receipt TTL 内只选一个本地 full authority（有效 receipt / target pre-push / 可选 `npm run verify:tree`），不按分支名策略化，也不机械双跑 full CI。细节见 verification-matrix 与 branch-merge-guideline。
+
+常用：
+
+```bash
+# 编辑中
+npm run typecheck
+npx vitest run <相关测试路径>
+
+# 可选：提前验证当前 clean HEAD 并写 receipt（随后同 tree push 可复用）
+npm run verify:tree
+
+# push / 交付前（或依赖 pre-push；receipt miss 时安全回退 full）
+bash scripts/ci.sh
+npm run build
+node bin/loop-agent.js --help
+```
+
+文档站变更：`npm run docs:build`。init / architecture / skill entry / pack 定向验证见 verification-matrix。
+
+## 交接
+
+记录：改了什么、为什么、验证命令与结果、契约/文档/测试影响、剩余风险、后续工作。
+
+## 禁止事项
+
+- 未读相关文档就大改；一次混合无关重构/新功能/文档大迁移。
+- 把对话约束当长期知识；缺验证宣称完成；假设系统没有某能力（先搜索）。
+- stub/假数据通路替代交付；把本机绝对路径写入仓库级 AGENTS/README/模板/发布包。
+- 只更新本仓库体验而遗漏目标项目 init 体验。

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## [Unreleased]
 
+## [0.35.1-beta.0] - 2026-08-14
+
+### 重点更新
+
+- Operator Chat 新增长跑 DAG 自主监督能力，通过只读 `operationWait`、canonical heartbeat 与有界退避持续监控后台 operation 至真实终态
+- `task advance --approve-gate --json` 新增 stderr 周期进度，同时保证 stdout 保持单一最终 JSON
+- `loop-agent init` 收敛 managed `.gitignore` 与运行态目录迁移评估，并保留项目自有 Pi routing
+- Operator Chat `/` 命令面板升级为响应式 3/2/1 列卡片网格，补齐参数命令、动态目录与键盘/IME 行为
+
+### 新增
+
+- Operator Chat 长跑 DAG 监督 P0-P2：新增只读、model-callable、无需 Human Gate 的 `operationWait` action/tool（复用 operation event store 的 `listFrom`/`subscribe`，订阅先于复查防竞态；已有事件/终态/needs-reconcile 立即返回，首个新事件立即 settle，超时返回 `timedOut:true` 摘要而非命令失败，NOT_FOUND/EVENT_CURSOR_EXPIRED 确定性错误；所有路径单次 settle 并清理 timer/listener）。
+- Console operation runner 将 sibling CLI 的 `LoopAgentClient` heartbeat 投影为 canonical `kind: "heartbeat"` operation event（含 `at`、`elapsedMs` 与 operation/action/run/task 安全摘要）；写入失败不终止 sibling CLI/DAG 执行，不改变 DAG runner lease heartbeat 频率。
+
+### 改进
+
+- `task advance --approve-gate --json` 运行 DAG 时周期进度只写 stderr（`--quiet` 可关闭），stdout 保持单个 `OperatorCommandResultV1` JSON；新增 `--progress-interval-ms`（下限 1000ms，与 `dag execute` 同语义）与 `--quiet` 参数；observer 仅在 approve 且非 dry-run 时创建，所有终态/异常路径 `finally` dispose，不留 timer。
+- Operator Chat 长跑监督合同统一为 60 → 90 → 120 → 180 秒退避（状态变化后重置 60 秒，疑似 stall 用 30–60 秒复查）；base prompt 与 managed init `AGENTS.md` 模板明确：长跑 DAG 必须经 `prepareDagExecution → runDag → operationId` 由 Console operation 后台持有，禁止前台 Bash 直接 `task advance --approve-gate`、禁止管道 `tail`/`head`、禁止模型自行拼接 `nohup`/`Start-Process`/`start`。
+
+### Init / Upgrade
+
+- `loop-agent init` 的 managed `.gitignore` block 收敛为四条目录级规则（`.harness/`、`.agents/`、`.task-pool/`、`.worktrees/`）：删除旧细粒度规则与反向放行；`scripts/` 与 `ai_workspace/loop-agent/` 保持可提交。旧格式 block 仍由 `check-update` 确定性报告 `refresh-managed-block`，`update --apply-safe` / `upgrade` 应用后收敛，block 外用户规则原样保留。
+- full init 不再生成 `.harness/**/.gitkeep` 占位文件（目录照常创建）。
+- `init upgrade` 在 managed block 收敛后生成只读 gitignore 迁移评估（`.harness/init-upgrades/<run-id>/gitignore-migration.json`）：inventory 已跟踪的 `.harness/**` 与 `.agents/**`，建议 index-only 的 `git rm -r --cached --ignore-unmatch` 命令（只改 index、保留工作区文件）；`.agents` 已跟踪内容触发审查暂停，非 Git 仓库 / git 查询失败 / 存在 staged 条目时 fail closed，controller 不自动修改 Git index。
+
+### Operator Chat
+
+- Operator Chat 斜杠命令面板完成 UI-12 响应式卡片网格：Operator / Pi Web / Extensions / Prompts / Skills 分组按现有 `comfortable / compact / narrow` 容器模式渲染 3 / 2 / 1 列，卡片仅显示真实命令名与最多两行描述；面板头部固定、候选区独立滚动、分组标题 sticky，长命令不会撑宽页面。键盘支持四方向几何导航与最小滚动，hover、`aria-selected`、`aria-activedescendant` 保持同源；IME composition 与结束后 100ms 保护阻止误导航/误接受，完整描述通过 `aria-describedby` 关联。补足 1/2/3 列、跨分组和 shuffled globalIndex 回归测试，并以真实浏览器验证三档列数、无横向溢出及 Operator/extension/prompt/skill 补全路径。
+- 修复 Operator Chat 命令面板缺口：`/name` 与 `/compact` 参数走本地重命名/压缩路径，palette Enter/Tab 对参数命令进入可编辑前缀，动态 Extension/Skill/Prompt 冲突按优先级保留最高来源，动态目录 fail-soft 时保留本地命令并展示可重试 warning；会话标题 tooltip 水平夹紧视口，单条 Markdown 渲染失败仅该消息降级为纯文本。
+
 ## [0.35.0] - 2026-08-13
 
 ### 重点更新

package/README.md

@@ -1,165 +1,165 @@
-# loop-agent
-
-`loop-agent` 是面向 AI coding agent 的仓库级任务运行时与治理工具。它把研发任务组织为可审查、可执行、可恢复、可验证的 Agent DAG，并将任务源、写入边界、运行事实和完成证据保存在仓库中。
-
-发布包提供两个 CLI：
-
-| CLI | 职责 |
-| --- | --- |
-| `loop-agent` | 单仓库任务、Agent DAG、验证、恢复与治理 |
-| `agent-worker` | 可选的 Feature、TaskSpec、Task Pool 与 Observe 外层编排 |
-
-受治理的 Agent writer 只有 Pi；`cursor-prompt` 仅用于显式手工 one-shot，不进入 DAG 或 Loop 自动写入路径。
-
-## 适合解决什么问题
-
-- 把模糊的 coding 请求转成有任务源、边界和验收标准的执行过程。
-- 在 Contract → Scout → Plan → Implement → Verify → Closeout 节点间保留可审查证据。
-- 用 `allowedPaths`、`forbiddenPaths` 和 DAG `writeSet` 限制模型写入。
-- 在中断、失败或跨会话后，从 `.harness/` 中恢复真实状态。
-- 用 shell verification 而不是模型自述判断任务是否完成。
-- 可选地通过 `agent-worker` 编排 Feature、Ready Queue、QA、交付与只读 Observe 看板。
-
-## 5 分钟开始
-
-### 安装
-
-```bash
-npm install -g @tea-agent/loop-agent@latest
-loop-agent --version
-```
-
-### 初始化当前项目
-
-```bash
-loop-agent init instructions --repo-root .
-loop-agent init --repo-root . --profile full --merge
-loop-agent init doctor --repo-root .
-loop-agent inspect --repo-root .
-```
-
-初始化会保留已有用户内容，并补充 `AGENTS.md`、`harness.json`、`ai_workspace/loop-agent/`、`.agents/skills/`、`.harness/` 和验证脚本等治理入口。
-
-控制器升级后，旧项目可能仍使用过期的 repo-local skills、模板、managed blocks 和治理说明。普通安全仓库命令结束时会自动检测目标项目是否需要对齐：非 TTY 只向 stderr 输出提示且不写入目标；TTY 且无 human decisions、无活跃 DAG/Worker 时，可经明确 `y/yes` 同意后应用 deterministic safe actions；也可手动运行统一入口：
-
-```bash
-loop-agent init reconcile --repo-root .
-```
-
-`init reconcile` 在 surface 缺失、存在 human decisions、存在活跃 DAG/Worker 或无法确认 Worker 状态时零写入，并返回 `needs-baseline`、`needs-human-decision` 或 `blocked-active-runtime`；其余情况复用 `init update --apply-safe` 的安全动作并复查返回 `clean`、`needs-model-merge` 或 `needs-safe-update`。
-
-写入型自然语言请求「`loop-agent初始化更新`」或「`loop-agent 初始化更新`」必须进入可恢复的统一闭环，而不是只做检查：
-
-```bash
-loop-agent init upgrade --repo-root . --json
-# controller 返回单文件 merge task 后：
-loop-agent init upgrade --repo-root . --run-id <run-id> --continue --json
-```
-
-它在 `.harness/init-upgrades/<run-id>/` 保存身份、扫描、动作收据、合并任务、验证与报告；`--status` / `--report` 只读。默认管理项目 `.opencode/plugins/`、`.pi/extensions/` 和 `.pi/settings.json`，不会默认写 `~/.pi/agent/settings.json`。旧项目首次执行后需 reload 宿主会话，以加载更新后的 AGENTS、skills 与 recovery 产物。明确「检查初始化更新」「只检查，不要修改」仍只运行 `init check-update`。
-
-完整说明见[初始化目标项目](website/docs/quick-start/init-target-project.md)。
-
-### 运行第一个任务
-
-初始化后，在已初始化的目标项目中你可以直接对宿主 agent 说「**loop-agent 帮我完成 XXX 需求**」（或「帮我实现 / 帮我修复 / 帮我开发 XXX」「使用 loop-agent 完成 XXX」「按 loop-agent 流程处理 XXX」），初始化写入的 `AGENTS.md` 与 `.agents/skills/loop-agent/` 会把这类通用需求表达确定性地路由进 Agent DAG，**无需**追加额外的 `cli` 关键词。主会话只负责编排与验证，业务实现由受治理 DAG writer 完成。
-
-```bash
-# 标准单任务路径：唯一 mutation 入口 task advance + 可选只读 task status
-loop-agent task advance example-task "实现一个有明确验收标准的小功能" \
-  --prd path/to/prd.md \
-  --allowed-path "src/**" \
-  --forbidden-path ".harness/**" \
-  --verify "<label>:<command>" \
-  --json
-
-# 审查返回的 writeSet / gate.digest 后，同一命令批准并长跑到稳定终态
-loop-agent task advance example-task \
-  --approve-gate "write-set-review:<digest>" \
-  --json
-
-# 可选只读查询（不 refresh、不 mutation）
-loop-agent task status example-task --json
-```
-
-`--verify` 命令应取项目 `AGENTS.md` / `docs/governance/verification-matrix.md` 登记的验证命令（不要假定 `npm run typecheck` 存在）；`--verify` 可选，省略时自动从 package.json scripts 或既有 managed `task.json.verifyCommands` 推导建议。
-
-首次 `task advance` 会 create/import PRD/派生 managed contract/生成并 strict validate DAG，然后停在 writeSet gate；未批准不会启动业务 writer。详细步骤见[第一次运行](website/docs/quick-start/first-run.md)和 [Agent DAG 工作流](website/docs/guides/agent-dag.md)。
-
-## 查看执行状态
-
-```bash
-loop-agent task status example-task --json
-# advanced forensic（非标准主路径）
-loop-agent dag report --run-id <run-id>
-```
-
-### Official 本地操作面（CLI + 统一 Operator Console）
-
-| 入口 | 命令 | 角色 |
-| --- | --- | --- |
-| 受治理 CLI | `loop-agent …` / `agent-worker …` | 权威写入与诊断 |
-| Loop Operator Console | `agent-worker console` | Official 本地控制面（默认 repo=当前目录、`127.0.0.1:8790`，含 Operate 与 Inspect） |
-| Inspect（只读） | `agent-worker console` → `/inspect/`；`observe snapshot` | 统一 Console 内只读检视；`observe serve` 已下线（REMOVED / exit 2） |
-
-```bash
-# 终端 A：Console（任务/运行操作面；canonical mutation 只经 sibling loop-agent）
-agent-worker console                              # 默认 repo=当前目录、port=8790；本地图形环境默认打开浏览器
-agent-worker console --no-open                    # 只启动服务，不打开浏览器
-agent-worker console doctor --repo .
-
-```
-
-访问 Console <http://127.0.0.1:8790/>；**Operator Chat Official** 是 Console 内的主引导交互。构建时设置 `VITE_OPERATOR_CHAT_DEFAULT_LANDING=chat` 可将 Chat 作为默认 landing；flag 未开启时仍默认进入 Tasks，旧 Task Ops tab 始终保留。顶部「检视」以及 `/inspect/` 提供只读 Dashboard、DAG、时间线与 artifacts；`loop-agent …` / `agent-worker …` CLI direct path 仍是受治理 fallback。当前状态为 **code ready, dogfood pending/unmet**，不宣称已替代 openCode 或其他外部主会话。
-
-## 核心边界
-
-- `.harness/` 保存任务、DAG run、one-shot run、可选 Task Pool 与 `init-upgrades/` 可恢复升级运行事实。
-- `ai_workspace/loop-agent/` 保存目标项目的长期治理资料。
-- `.agents/skills/` 保存目标项目可审计的 repo-local skills。
-- `agent-worker` 通过已发布的 `loop-agent` 子进程执行 DAG，不维护第二套 runtime kernel。
-- 当前不内置远程 Task Pool、云 Worker 集群、自动 push、自动创建或合并 PR、生产凭据管理。
-
-架构说明见[系统全景](docs/architecture/system-overview.md)和 [runtime 边界](docs/architecture/runtime-boundaries.md)。
-
-## 文档导航
-
-### 使用者
-
-- [安装](website/docs/quick-start/installation.md)
-- [初始化目标项目](website/docs/quick-start/init-target-project.md)
-- [第一次运行](website/docs/quick-start/first-run.md)
-- [功能导览](website/docs/overview/feature-map.md)
-- [CLI 参考](website/docs/reference/cli.md)
-- [Observe 看板](website/docs/guides/observe-ui.md)
-
-### 维护者与 Agent
-
-- [`AGENTS.md`](AGENTS.md)：开工协议与工作规则
-- [`docs/README.md`](docs/README.md)：治理文档总索引
-- [`docs/governance/`](docs/governance/README.md)：工程原则、工作流与验证方法
-- [`docs/runtime/`](docs/runtime/README.md)：DAG 运行、恢复与 runtime 手册
-- [`docs/operations/`](docs/operations/README.md)：本地环境、合并与协作操作
-- [`docs/governance/feature-workflow.md`](docs/governance/feature-workflow.md)：会话治理与 runtime workflow
-- [`docs/governance/verification-matrix.md`](docs/governance/verification-matrix.md)：验证命令选择
-- [`docs/architecture/`](docs/architecture/README.md)：架构、事实与演进边界
-- [`CHANGELOG.md`](CHANGELOG.md)：版本变化与 breaking changes
-
-## 本仓库开发
-
-开始修改前先阅读 `AGENTS.md`。常用验证：
-
-```bash
-npm install
-npm run typecheck
-npm test
-npm run build
-bash scripts/check-repo.sh
-```
-
-完整门禁和特定环境排障分别见：
-
-- [`docs/governance/verification-matrix.md`](docs/governance/verification-matrix.md)
-- [`docs/operations/local-development-environment.md`](docs/operations/local-development-environment.md)
-
-发布和初始化 surface 变更还应运行 `npm pack --dry-run` 与 `bash scripts/check-init-surface.sh`。
+# loop-agent
+
+`loop-agent` 是面向 AI coding agent 的仓库级任务运行时与治理工具。它把研发任务组织为可审查、可执行、可恢复、可验证的 Agent DAG，并将任务源、写入边界、运行事实和完成证据保存在仓库中。
+
+发布包提供两个 CLI：
+
+| CLI | 职责 |
+| --- | --- |
+| `loop-agent` | 单仓库任务、Agent DAG、验证、恢复与治理 |
+| `agent-worker` | 可选的 Feature、TaskSpec、Task Pool 与 Observe 外层编排 |
+
+受治理的 Agent writer 只有 Pi；`cursor-prompt` 仅用于显式手工 one-shot，不进入 DAG 或 Loop 自动写入路径。
+
+## 适合解决什么问题
+
+- 把模糊的 coding 请求转成有任务源、边界和验收标准的执行过程。
+- 在 Contract → Scout → Plan → Implement → Verify → Closeout 节点间保留可审查证据。
+- 用 `allowedPaths`、`forbiddenPaths` 和 DAG `writeSet` 限制模型写入。
+- 在中断、失败或跨会话后，从 `.harness/` 中恢复真实状态。
+- 用 shell verification 而不是模型自述判断任务是否完成。
+- 可选地通过 `agent-worker` 编排 Feature、Ready Queue、QA、交付与只读 Observe 看板。
+
+## 5 分钟开始
+
+### 安装
+
+```bash
+npm install -g @tea-agent/loop-agent@latest
+loop-agent --version
+```
+
+### 初始化当前项目
+
+```bash
+loop-agent init instructions --repo-root .
+loop-agent init --repo-root . --profile full --merge
+loop-agent init doctor --repo-root .
+loop-agent inspect --repo-root .
+```
+
+初始化会保留已有用户内容，并补充 `AGENTS.md`、`harness.json`、`ai_workspace/loop-agent/`、`.agents/skills/`、`.harness/` 和验证脚本等治理入口。
+
+控制器升级后，旧项目可能仍使用过期的 repo-local skills、模板、managed blocks 和治理说明。普通安全仓库命令结束时会自动检测目标项目是否需要对齐：非 TTY 只向 stderr 输出提示且不写入目标；TTY 且无 human decisions、无活跃 DAG/Worker 时，可经明确 `y/yes` 同意后应用 deterministic safe actions；也可手动运行统一入口：
+
+```bash
+loop-agent init reconcile --repo-root .
+```
+
+`init reconcile` 在 surface 缺失、存在 human decisions、存在活跃 DAG/Worker 或无法确认 Worker 状态时零写入，并返回 `needs-baseline`、`needs-human-decision` 或 `blocked-active-runtime`；其余情况复用 `init update --apply-safe` 的安全动作并复查返回 `clean`、`needs-model-merge` 或 `needs-safe-update`。
+
+写入型自然语言请求「`loop-agent初始化更新`」或「`loop-agent 初始化更新`」必须进入可恢复的统一闭环，而不是只做检查：
+
+```bash
+loop-agent init upgrade --repo-root . --json
+# controller 返回单文件 merge task 后：
+loop-agent init upgrade --repo-root . --run-id <run-id> --continue --json
+```
+
+它在 `.harness/init-upgrades/<run-id>/` 保存身份、扫描、动作收据、合并任务、验证与报告；`--status` / `--report` 只读。默认管理项目 `.opencode/plugins/`、`.pi/extensions/` 和 `.pi/settings.json`，不会默认写 `~/.pi/agent/settings.json`。旧项目首次执行后需 reload 宿主会话，以加载更新后的 AGENTS、skills 与 recovery 产物。明确「检查初始化更新」「只检查，不要修改」仍只运行 `init check-update`。
+
+完整说明见[初始化目标项目](website/docs/quick-start/init-target-project.md)。
+
+### 运行第一个任务
+
+初始化后，在已初始化的目标项目中你可以直接对宿主 agent 说「**loop-agent 帮我完成 XXX 需求**」（或「帮我实现 / 帮我修复 / 帮我开发 XXX」「使用 loop-agent 完成 XXX」「按 loop-agent 流程处理 XXX」），初始化写入的 `AGENTS.md` 与 `.agents/skills/loop-agent/` 会把这类通用需求表达确定性地路由进 Agent DAG，**无需**追加额外的 `cli` 关键词。主会话只负责编排与验证，业务实现由受治理 DAG writer 完成。
+
+```bash
+# 标准单任务路径：唯一 mutation 入口 task advance + 可选只读 task status
+loop-agent task advance example-task "实现一个有明确验收标准的小功能" \
+  --prd path/to/prd.md \
+  --allowed-path "src/**" \
+  --forbidden-path ".harness/**" \
+  --verify "<label>:<command>" \
+  --json
+
+# 审查返回的 writeSet / gate.digest 后，同一命令批准并长跑到稳定终态
+loop-agent task advance example-task \
+  --approve-gate "write-set-review:<digest>" \
+  --json
+
+# 可选只读查询（不 refresh、不 mutation）
+loop-agent task status example-task --json
+```
+
+`--verify` 命令应取项目 `AGENTS.md` / `docs/governance/verification-matrix.md` 登记的验证命令（不要假定 `npm run typecheck` 存在）；`--verify` 可选，省略时自动从 package.json scripts 或既有 managed `task.json.verifyCommands` 推导建议。
+
+首次 `task advance` 会 create/import PRD/派生 managed contract/生成并 strict validate DAG，然后停在 writeSet gate；未批准不会启动业务 writer。详细步骤见[第一次运行](website/docs/quick-start/first-run.md)和 [Agent DAG 工作流](website/docs/guides/agent-dag.md)。
+
+## 查看执行状态
+
+```bash
+loop-agent task status example-task --json
+# advanced forensic（非标准主路径）
+loop-agent dag report --run-id <run-id>
+```
+
+### Official 本地操作面（CLI + 统一 Operator Console）
+
+| 入口 | 命令 | 角色 |
+| --- | --- | --- |
+| 受治理 CLI | `loop-agent …` / `agent-worker …` | 权威写入与诊断 |
+| Loop Operator Console | `agent-worker console` | Official 本地控制面（默认 repo=当前目录、`127.0.0.1:8790`，含 Operate 与 Inspect） |
+| Inspect（只读） | `agent-worker console` → `/inspect/`；`observe snapshot` | 统一 Console 内只读检视；`observe serve` 已下线（REMOVED / exit 2） |
+
+```bash
+# 终端 A：Console（任务/运行操作面；canonical mutation 只经 sibling loop-agent）
+agent-worker console                              # 默认 repo=当前目录、port=8790；本地图形环境默认打开浏览器
+agent-worker console --no-open                    # 只启动服务，不打开浏览器
+agent-worker console doctor --repo .
+
+```
+
+访问 Console <http://127.0.0.1:8790/>；**Operator Chat Official** 是 Console 内的主引导交互。构建时设置 `VITE_OPERATOR_CHAT_DEFAULT_LANDING=chat` 可将 Chat 作为默认 landing；flag 未开启时仍默认进入 Tasks，旧 Task Ops tab 始终保留。顶部「检视」以及 `/inspect/` 提供只读 Dashboard、DAG、时间线与 artifacts；`loop-agent …` / `agent-worker …` CLI direct path 仍是受治理 fallback。当前状态为 **code ready, dogfood pending/unmet**，不宣称已替代 openCode 或其他外部主会话。
+
+## 核心边界
+
+- `.harness/` 保存任务、DAG run、one-shot run、可选 Task Pool 与 `init-upgrades/` 可恢复升级运行事实。
+- `ai_workspace/loop-agent/` 保存目标项目的长期治理资料。
+- `.agents/skills/` 保存目标项目可审计的 repo-local skills。
+- `agent-worker` 通过已发布的 `loop-agent` 子进程执行 DAG，不维护第二套 runtime kernel。
+- 当前不内置远程 Task Pool、云 Worker 集群、自动 push、自动创建或合并 PR、生产凭据管理。
+
+架构说明见[系统全景](docs/architecture/system-overview.md)和 [runtime 边界](docs/architecture/runtime-boundaries.md)。
+
+## 文档导航
+
+### 使用者
+
+- [安装](website/docs/quick-start/installation.md)
+- [初始化目标项目](website/docs/quick-start/init-target-project.md)
+- [第一次运行](website/docs/quick-start/first-run.md)
+- [功能导览](website/docs/overview/feature-map.md)
+- [CLI 参考](website/docs/reference/cli.md)
+- [Observe 看板](website/docs/guides/observe-ui.md)
+
+### 维护者与 Agent
+
+- [`AGENTS.md`](AGENTS.md)：开工协议与工作规则
+- [`docs/README.md`](docs/README.md)：治理文档总索引
+- [`docs/governance/`](docs/governance/README.md)：工程原则、工作流与验证方法
+- [`docs/runtime/`](docs/runtime/README.md)：DAG 运行、恢复与 runtime 手册
+- [`docs/operations/`](docs/operations/README.md)：本地环境、合并与协作操作
+- [`docs/governance/feature-workflow.md`](docs/governance/feature-workflow.md)：会话治理与 runtime workflow
+- [`docs/governance/verification-matrix.md`](docs/governance/verification-matrix.md)：验证命令选择
+- [`docs/architecture/`](docs/architecture/README.md)：架构、事实与演进边界
+- [`CHANGELOG.md`](CHANGELOG.md)：版本变化与 breaking changes
+
+## 本仓库开发
+
+开始修改前先阅读 `AGENTS.md`。常用验证：
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+bash scripts/check-repo.sh
+```
+
+完整门禁和特定环境排障分别见：
+
+- [`docs/governance/verification-matrix.md`](docs/governance/verification-matrix.md)
+- [`docs/operations/local-development-environment.md`](docs/operations/local-development-environment.md)
+
+发布和初始化 surface 变更还应运行 `npm pack --dry-run` 与 `bash scripts/check-init-surface.sh`。