@tea-agent/loop-agent 0.26.2 → 0.26.4

package/skills/loop-agent/references/orchestrator-and-interventions.md

@@ -15,7 +15,7 @@ main session 是 decision-maker 与 scheduler，**不是** implementer。稀缺
 ## 默认执行模型
 
 | Actor | 主角色 | 避免 |
-|---|---|---|
+| --- | --- | --- |
 | Main session (Operator Assist) | Objective、contract、**CLI 编排**、DAG review、routing、failure triage（doctor/reconcile）、approve/reject/resume、shell verify、handoff | 成为 coder；绕过 CLI 写业务树；失败后直接 Edit |
 | Agent DAG runner | 可恢复 multi-node orchestration、write policy、run artifacts | 不更新 DAG/source 的 ad-hoc replanning |
 | Cursor one-shot prompt | 显式有界诊断/介入；非默认 | 当 DAG executor、自动写入、无 path scope 宽写、失败默认恢复 |
@@ -48,7 +48,7 @@ sidecar intervention 是一次性 Pi 或 Cursor prompt，用于 unblock 主 work
 典型 routing：
 
 | 情况 | 使用 |
-|---|---|
+| --- | --- |
 | 需 quick root-cause analysis、plan critique、log 解读 | one-shot Pi prompt，read-only |
 | 需 codebase-indexed multi-file 诊断或 bounded patch | one-shot Cursor prompt |
 | 需确定性 evidence | shell command / shell DAG node |
@@ -94,14 +94,20 @@ P5 验证：future agent 可从 practice report + completed node artifacts 继
 main session 编排；不是默认 implementer。in-flight run 期间：
 
 | Action | 何时 | 记录位置 |
-|--------|------|----------|
+| -------- | ------ | ---------- |
 | Inspect status / node artifacts | 始终允许 | progress 或 sidecar output 中的 notes |
 | Sidecar read-only Pi/Cursor prompt | 诊断、plan critique、log 解读 | resume 前的 findings |
-| Surgical patch | small、obvious、可 verify；无 active `writeSet` 冲突 | `ai_workspace/loop-agent/reports/` 或 exec plan，含 scope + verification |
-| DAG/source repair | topology、writeSet 或 prompt contract 错误 | 编辑平台临时目录中的 DAG 或 plan；re-validate；rerun |
+| Surgical patch | **不适用于** exclusive writer（如 `implement-pi` / `repair-pi`）active 期间的工作区写；仅当无 active exclusive writer、变更极窄且可 verify 的治理元数据时才可考虑 | `ai_workspace/loop-agent/reports/` 或 exec plan，含 scope + verification |
+| DAG/source repair | topology、writeSet 或 prompt contract 错误；writer 非 active 时修正元数据 | 编辑平台临时目录中的 DAG 或 plan；re-validate；rerun |
 | Approve/reject/resume | Decision Gate `pause-on-human` | 仅 CLI artifacts |
 | Post-DAG closeout | promotion、report、plan archive、indexes | `promote-run`、`closeout task`、`ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress`、exec-plan indexes — 非 root `artifacts/`，除非 explicit narrow writeSet |
 
+**Live-run 纪律（与目标项目 AGENTS managed block 同口径）**：
+
+- Operator 须持续监控 run，直到 controller 报告 run 已结束（节点/流程终态如 `FINISHED`、`FAILED` 或 `partial_failed`），或 Decision Gate **需要 approve**；不要在节点仍运行时假定完成。
+- 判活须组合 runner heartbeat、session events 与 `dag doctor` liveness/provider meaningful progress；Runner heartbeat 只证明 lease，alone ≠ progress。
+- exclusive writer 运行期间：主会话与其他 writer **不得并发修改工作区**，以免 write-guard 错误归因；只读 status/doctor/report/observe/console 与 approve/reject/resume CLI 仍允许。
+
 **Verdict 与 Decision Gate 提醒**（authoring guidance，非 runtime 变更）：
 
 - `shell.verdictGate` 后的 review/supervisor node：首条非空行须精确为 `VERDICT: pass` 或 `VERDICT: request-revision`（P2/P4）。
@@ -117,7 +123,7 @@ main session 编排；不是默认 implementer。in-flight run 期间：
 1. 变更不触及业务功能逻辑；通常是 task source、DAG JSON typo、doc index、或删除 scratch。
 2. 原因已知；不需要 broad system understanding。
 3. 不改变 product requirement 语义、architecture、public API、data model 或 cross-platform contract。
-4. 不与 active DAG exclusive `writeSet` 冲突。
+4. 不与 active DAG exclusive `writeSet` 冲突；且 exclusive writer 运行期间**一律禁止**主会话/其他 writer 并发改工作区（不仅是路径重叠判断），以免 write-guard 错误归因。
 5. 可立即 shell verify。
 6. 记录 scope + verification；且**下一步仍是 CLI re-validate / rerun**，不是「主会话继续实现」。
 
@@ -134,6 +140,7 @@ main session 编排；不是默认 implementer。in-flight run 期间：
 - 手工按计划实现功能或修测试失败。
 - 改 API/contract 语义或 refactor 子系统。
 - 编辑 in-flight exclusive DAG node 拥有的实现文件。
+- exclusive writer active 时主会话或其他 writer 并发修改工作区（即使自认无 writeSet 冲突）。
 - 用 `cursor-prompt` / 宿主 Write 代替 `implement-pi` / `repair-pi`。
 
 失败默认序列（替代旧 surgical-patch 心智）：