@tea-agent/loop-agent 0.16.21 → 0.16.23

package/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### 修复
 
+- Backend-test 唯一 JSON object 提取器在扫描裸对象前会等长忽略完整 Markdown 行内代码中的对象形状示例（如 `{error:{code,message,type}}`）；唯一真实 envelope 可正常物化，多个真实 JSON、fence 外额外对象与未闭合对象继续 fail-closed。
+
 - Backend-test 节点 10 `backend-test-semantic-gate-shell` 不再用 Markdown `first-verdict-line` 读取 raw Pi 输出；改为同一 `semantic-initial` pipeline 按 task id 只读 `contracts/backend-test-semantic-review.json`，仅 `verdict=pass` 放行 pytest，`request-revision`/缺失/malformed 清晰 fail-closed；节点 09 仍只负责 materialize+trace，15 节点与单次 pytest 不变。
 - 公开 Case Manifest schema（`docs/templates/backend-test-case-manifest.schema.json`）对齐 materializer dual-scope coverage：`coverageSummary` 在 `additionalProperties:false` 下 required 并声明 `global`/`inScope`（`total`/`covered`/`gapped`/`ratio`）与 `crossDomainGapCount`；回归测试以无依赖轻量 contract 锁定 schema↔canonical 一致性；不改 materializer/15 节点。
 - Backend-test Case Manifest materializer 将模型顶层 `coverageSummary` 视为非权威：secret 扫描后剥离，再 strict parse 其余字段，并始终 `computeCaseManifestCoverageSummary` 写入 canonical summary；my-webapp 自定义/部分 summary 不再导致 invalid-output；prompt 禁止模型输出 coverageSummary；15 节点与单次 pytest 不变。
@@ -35,6 +37,18 @@
 - Pi SDK 执行长推理或大段结构化输出时不再把高频流式增量事件无界累积到内存；同一响应在多个生命周期事件中重复出现的 Token 用量只统计一次，避免 `Invalid string length` 和成本数据虚高。
 - 后端测试复合执行节点继续保持 clean environment、失败分类和 fail-closed outcome，并为唯一 JUnit/initial Result、canonical Result、traceability 与 Observe 投影保留结构化运行证据。
 
+## [0.16.23] - 2026-07-21
+
+### 修复
+
+- DAG runner 在归档到 `completed/` 前停止 heartbeat 并排空 state 写队列。避免 terminal 节点全 FINISHED 后仍因 completed-facts write guard 拒绝写 `state.json` 导致 `run-dag` 非零退出、Worker 记 `run-error`/Task Pool `Blocked`。
+
+## [0.16.22] - 2026-07-21
+
+### 修复
+
+- Git checkpoint `allowed_paths` 审计与 shell write-guard 对齐：忽略 `.playwright-cli/**` 等 ephemeral tool cache。frontend-test 浏览器用例与 `frontend-test-result` 已绿时，不再因 playwright-cli 会话落盘导致 promote/closeout `record-error`。
+
 ## [0.16.21] - 2026-07-21
 
 ### 修复

package/dist/commands/init.js

@@ -679,6 +679,21 @@ function buildManagedAgentsBlock(input) {
         "- Shell 验证是完成依据；模型建议不能替代命令证据。",
         "- 保留无关的用户改动，不要回退自己没有做的修改。",
         "- 委托模型写入前，必须把写入边界写成结构化 `task.json.allowedPaths` / `task.json.forbiddenPaths`，再审查生成 DAG 的 writer `writeSet`；不要只依赖 `source/执行约束.md` 的自然语言约束。",
+        "- 本仓库对 openCode 等主会话的定位是 **Compatibility / Operator Assist**：主会话编排 `loop-agent` / `agent-worker` CLI 与只读诊断，**不是**默认实现 agent。",
+        "",
+        "### 主会话硬约束（Compatibility / Operator Assist）",
+        "",
+        "主会话（含 openCode、Cursor Chat、其他宿主 agent）必须遵守以下硬约束；skills 与本文件是纪律文档，**不能**替代 `task.json` / DAG `writeSet` / runtime 执法。",
+        "",
+        "| 类别 | 规则 |",
+        "|---|---|",
+        "| **角色** | 主会话 = **operator-only**，不是 implementer。 |",
+        "| **允许** | 调用已发布 `loop-agent` / `agent-worker` CLI；只读 `status` / `dag status` / `dag doctor` / `dag report` / `inspect` / `agent-worker observe`；准备或修正任务源 `source/*` 与 `task.json` 边界；记录 human gate；跑 shell 验证与 handoff。 |",
+        "| **禁止** | 绕过 `loop-agent` / `agent-worker` CLI，用宿主 Edit/Write/ApplyPatch 等直接改业务实现；在 CLI/DAG 失败后「救火改文件」；用聊天自述代替 shell 验证完成声明。 |",
+        "| **失败时只允许** | `loop-agent dag doctor` / `dag report` / `dag reconcile-run`（及适用的 `agent-worker task reconcile` / `pool mark-failed`）；记 human gate；修正 **任务源 / task.json / DAG 包** 后 re-validate 并 **经 CLI 重跑**。 |",
+        "| **实现写入** | 业务代码与功能修复 **只** 经受治理 DAG writer（`implement-pi` / `repair-pi` 等）通过 `dag run-task` / `run-dag`（或 worker 子进程调用的同一路径）完成。 |",
+        "",
+        "**永远不要**：`loop-agent` / `agent-worker` 失败 ⇒ 主会话直接改仓库实现。",
         "",
         "### 自然语言入口路由",
         "",
@@ -778,7 +793,9 @@ function buildManagedAgentsBlock(input) {
         "",
         "### DAG 诊断与收口",
         "",
-        "执行后优先使用 `loop-agent dag report --run-id <run-id> --markdown` 读取 run facts；失败或 paused run 使用 `loop-agent dag doctor --run-id <run-id> --markdown` 诊断。失败 DAG run 不应写成成功 closeout，应使用 `loop-agent dag closeout-draft --run-id <run-id>` 生成 failure handoff，保留 what failed、evidence、classification、recommended follow-up、safe retry conditions 和 human decision needed。",
+        "执行后优先使用 `loop-agent dag report --run-id <run-id> --markdown` 读取 run facts；失败或 paused run 使用 `loop-agent dag doctor --run-id <run-id> --markdown` 诊断。需要生命周期对齐时用 `loop-agent dag reconcile-run --run-id <run-id>`（先只读检查，显式 action 才写入）。失败 DAG run 不应写成成功 closeout，应使用 `loop-agent dag closeout-draft --run-id <run-id>` 生成 failure handoff，保留 what failed、evidence、classification、recommended follow-up、safe retry conditions 和 human decision needed。",
+        "",
+        "失败恢复默认序列：doctor/report → classify → reconcile 或 replan → CLI 重跑 → shell verify。**禁止**把主会话直接 Edit 业务代码当作恢复手段。",
         "",
         "### 运行态与 Skills",
         "",

package/dist/worker/delivery/git-transaction.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { z } from "zod";
 import { getTaskPoolRoot } from "../pool/run-store.js";
 import { assertSafeRuntimeId } from "../follow-up/paths.js";
+import { isEphemeralToolCachePath } from "../../executors/shell-write-guard.js";
 import { expandAllowedPathsForWorkflow } from "../materialize/harness-task-materializer.js";
 import { resolveWorkflow } from "../task-spec/workflow-routing.js";
 const execFileAsync = promisify(execFile);
@@ -280,6 +281,10 @@ function auditChangedPathsReport(changes, taskSpec) {
     const allowedPaths = expandAllowedPathsForWorkflow(resolveWorkflow(taskSpec).workflow, taskSpec.constraints.allowed_paths);
     const violations = [];
     for (const changed of changes) {
+        // Match shell write-guard: tool caches are not product evidence and must not
+        // fail checkpoint after a green frontend-test browser run.
+        if (isEphemeralToolCachePath(changed))
+            continue;
         if (/(^|\/)(\.env(?:\.|$)|[^/]*\.(?:pem|key|p12|pfx))$/i.test(changed))
             violations.push(`changed path may contain sensitive material: ${changed}`);
         else if (taskSpec.constraints.forbidden_paths.some((glob) => matchesGlob(changed, glob)))

package/dist/workflows/dag/backend-test-contract-envelope.js

@@ -6,6 +6,44 @@
  * Semantic review / classification materializers reuse the same scanner.
  */
 const JSON_FENCE_RE = /```json\s*\r?\n([\s\S]*?)\r?\n```/gi;
+/**
+ * Mask complete Markdown inline-code spans without changing source offsets.
+ * Object-shaped examples inside backticks are prose, not JSON candidates.
+ * Unclosed delimiters stay visible so malformed output cannot hide conflicts.
+ */
+function maskMarkdownInlineCode(text) {
+    const chars = text.split("");
+    for (let index = 0; index < text.length;) {
+        if (text[index] !== "`") {
+            index += 1;
+            continue;
+        }
+        let delimiterLength = 1;
+        while (text[index + delimiterLength] === "`")
+            delimiterLength += 1;
+        if (delimiterLength >= 3) {
+            index += delimiterLength;
+            continue;
+        }
+        const delimiter = "`".repeat(delimiterLength);
+        let close = text.indexOf(delimiter, index + delimiterLength);
+        while (close >= 0 &&
+            (text[close - 1] === "`" || text[close + delimiterLength] === "`")) {
+            close = text.indexOf(delimiter, close + delimiterLength);
+        }
+        if (close < 0) {
+            index += delimiterLength;
+            continue;
+        }
+        const end = close + delimiterLength;
+        for (let cursor = index; cursor < end; cursor += 1) {
+            if (chars[cursor] !== "\n" && chars[cursor] !== "\r")
+                chars[cursor] = " ";
+        }
+        index = end;
+    }
+    return chars.join("");
+}
 function isPlainObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -121,7 +159,7 @@ function findUniqueJsonObjectText(text) {
     if (fences.length === 1) {
         const fence = fences[0];
         const outsideScans = [trimmed.slice(0, fence.start), trimmed.slice(fence.end)]
-            .map((fragment) => scanBalancedObjectSpans(fragment));
+            .map((fragment) => scanBalancedObjectSpans(maskMarkdownInlineCode(fragment)));
         if (outsideScans.some((scan) => scan.unclosedObject)) {
             throw new Error("backend-test unique JSON object: unclosed JSON object outside fenced json block");
         }
@@ -131,7 +169,7 @@ function findUniqueJsonObjectText(text) {
         }
         return fence.body;
     }
-    const scan = scanBalancedObjectSpans(trimmed);
+    const scan = scanBalancedObjectSpans(maskMarkdownInlineCode(trimmed));
     if (scan.unclosedObject) {
         throw new Error("backend-test unique JSON object: unclosed JSON object; expected one unique balanced object");
     }

package/dist/workflows/dag/runner.js

@@ -469,6 +469,11 @@ async function executeDagCheckpoint(input) {
             }
             break;
         }
+        // Stop heartbeats before terminal archive. A late heartbeat writing
+        // state.json under completed/ trips the completed-facts write guard and
+        // makes run-dag exit non-zero after every node already finished.
+        clearInterval(heartbeatTimer);
+        await stateWriteQueue;
         state.finishedAt = new Date().toISOString();
         const runDirBeforeTransfer = runDir;
         await writeBudgetLedgerArtifacts(runDir, state.budgetLedger);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.16.21",
+  "version": "0.16.23",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/agent-worker/SKILL.md

@@ -10,10 +10,17 @@ references:
 
 当工作起点是 Feature Packet、TaskSpec、Task Pool、Worker batch 或 versioned self-hosting release train 时使用本 skill。它负责在单次 loop-agent DAG run 之外选择并监督工作。
 
+## Compatibility / Operator Assist
+
+- 主会话对本 skill 的定位是 **outer-loop operator**，不是实现 agent。
+- **允许**：`agent-worker` / `loop-agent` CLI；只读 `pool doctor`、`observe`、status/report；冻结 controller identity；选择 Ready 工作与 recovery 命令。
+- **禁止**：绕过 CLI 直接 Edit 业务实现；Worker/DAG 失败后主会话「救火改文件」。
+- **失败时只允许**：保留 evidence → `task retry` / `task reconcile` / `pool mark-failed` / human gate → 再经 CLI 重跑；实现写入仍只经 published `loop-agent` DAG。
+
 ## Route the Work
 
 - 用 `agent-worker` 做 Feature validation 与 lifecycle 决策、Ready-task 选择、batch 推进、controller identity freeze、candidate takeover canary，以及失败 Worker run 的恢复。
-- 对单个有界 DAG task、DAG diagnostics、node implementation，或 DAG runtime/kernel 修复，直接用 `loop-agent`。
+- 对单个有界 DAG task、DAG diagnostics、node implementation，或 DAG runtime/kernel 修复，用 `loop-agent` CLI（仍禁止主会话直接写实现）。
 - 不要让 DAG leaf node 递归启动 `agent-worker`；Worker 是 outer loop，不是另一个 node executor。
 
 ## Boundaries
@@ -23,14 +30,15 @@ references:
 - Controller identity 冻结驱动 batch 的 published package；loop-agent skill snapshot 则单独冻结注入单次 DAG run 的 instructions。
 - 本 skill 不复制 command catalog。精确 flags 见 CLI help 与同级 `../loop-agent/references/command-reference.md`。
 - 不要把本 skill 加入默认 DAG role skills；仅对 outer-loop operator 工作显式路由。
+- 主会话 skills 文本**不能**替代 writeSet / controller identity 执法。
 
 ## Operator Flow
 
 1. 校验 Feature Packet 与 TaskSpecs，再从 Task Pool facts 选择 Ready 工作，而不是从 chat state。Task Pool 身份是 `{ featureId, taskId }`，不是裸 taskId。
 2. 在写入前解析并冻结目标 published controller；在 batch、task 与 run evidence 中保留 controller identity。
-3. 将仓库写入委托给受治理的 loop-agent DAG nodes，并审查其 task boundaries 与 write sets。
+3. 将仓库**实现写入**委托给受治理的 loop-agent DAG nodes（子进程 CLI），并审查 task boundaries 与 write sets；主会话不手写实现。
 4. 自举时保持 published version N 固定，由它维护 candidate N+1，再通过 deterministic isolated canary 证明 candidate takeover。
-5. 失败时先保留原始 run record、evidence 与 failure handoff，再重试或创建后续工作。
+5. 失败时先保留原始 run record、evidence 与 failure handoff，再 CLI 重试或创建后续工作——**禁止**主会话直接改业务树收尾。
 6. Failed task 重试使用 `agent-worker task retry <task-id> --feature-id <feature-id> --repo <repo> --reason <reason>`；跨 Feature 同名时禁止省略 `--feature-id`。
 7. 升级或发现 legacy state 时先 `pool doctor`，再用 `pool migrate-state`（默认 dry-run；apply 需 `--owner` + `--reason`）。Observe 保持只读。
 

package/skills/agent-worker/references/agent-worker-operator.md

@@ -2,11 +2,24 @@
 
 `agent-worker` 是 Feature Packet、TaskSpec、Task Pool 与 self-hosting release-train 操作的 outer-loop adapter。它不是 DAG executor。
 
+## Compatibility / Operator Assist
+
+主会话使用本 reference 时是 **operator**，不是 implementer：
+
+| 允许 | 禁止 |
+|---|---|
+| `agent-worker` / `loop-agent` CLI | 宿主 Edit/Write 直接改业务实现 |
+| 只读 doctor / observe / report / status | Worker 或 DAG 失败后「救火改文件」 |
+| 冻结 controller identity、选 Ready、retry/reconcile | 跳过 published controller 手写实现收尾 |
+| human gate 记录 | 用聊天完成声明代替 shell / harness 证据 |
+
+实现写入只通过 Worker spawn 的已发布 `loop-agent` DAG。skills 不能替代 writeSet 或 controller identity。
+
 ## Routing Boundary
 
-当工作单元是 Feature lifecycle、一组 TaskSpecs、Ready queue、Worker batch 或 candidate takeover 时，选 `agent-worker`。当工作单元是单次受治理 DAG run、node implementation、DAG diagnosis 或 DAG runtime repair 时，选 `loop-agent`。
+当工作单元是 Feature lifecycle、一组 TaskSpecs、Ready queue、Worker batch 或 candidate takeover 时，选 `agent-worker`。当工作单元是单次受治理 DAG run、node implementation、DAG diagnosis 或 DAG runtime repair 时，选 `loop-agent` CLI。
 
-Leaf DAG nodes 不得递归启动 `agent-worker`。Worker 负责 DAG 之外的 selection 与 lifecycle state；loop-agent 负责 DAG 内的 execution facts。
+Leaf DAG nodes 不得递归启动 `agent-worker`。Worker 负责 DAG 之外的 selection 与 lifecycle state；loop-agent 负责 DAG 内的 execution facts。主会话不得绕过二者直接实现。
 
 ## Responsibilities
 
@@ -21,9 +34,9 @@ Leaf DAG nodes 不得递归启动 `agent-worker`。Worker 负责 DAG 之外的 s
 1. 阅读 Feature Packet，校验其 TaskSpecs 与 dependency graph。
 2. 从持久化的 Task Pool state 推导下一步动作；不要从 chat history 重建 lifecycle state。canonical state 键是 `{ featureId, taskId }`（路径 `.harness/task-pool/states/<featureId>/<taskId>.json`）。
 3. 对可写 batch 只冻结一次 controller，并将其 identity 传播到下游 evidence。
-4. 将每个选中的 TaskSpec 委托给 loop-agent，使用其结构化的 allowed / forbidden paths。
+4. 将每个选中的 TaskSpec **经 CLI** 委托给 loop-agent，使用其结构化的 allowed / forbidden paths；主会话不代替 writer。
 5. 根据 canonical run facts 刷新 Feature review、reports 与 Task Pool state。
-6. 重试 Failed task：
+6. 重试 Failed task（CLI only；禁止主会话手改实现）：
 
    ```text
    agent-worker task retry <task-id> --feature-id <feature-id> --repo <repo> --reason <reason>
@@ -54,6 +67,7 @@ Leaf DAG nodes 不得递归启动 `agent-worker`。Worker 负责 DAG 之外的 s
 - 不要在此实现 node scheduling、write-set enforcement 或 model prompts。
 - 不要在本 skill 中维护一份独立的精确 CLI flags 列表；以 CLI help 与 `../../loop-agent/references/command-reference.md` 为准。
 - 不要把本 skill 路由为 DAG nodes 的默认 role skill。
+- 不要把主会话定位成 Worker/DAG 失败后的实现后备通道。
 
 ## Candidate Canary Boundary
 

package/skills/loop-agent/SKILL.md

@@ -23,12 +23,16 @@ Shared loop-agent harness workflow 规则见 `references/harness-policy.md`。Re
 
 ## 默认立场
 
-- 主入口是 **Agent DAG**。
-- 主会话负责编排、审 writeSet、复核验证与 handoff。
-- DAG `pi` executor 是唯一受治理 Agent runtime：默认用于 read-only planning / review / diagnosis；当节点声明 `toolProfile: "write"` 时用于 bounded implementation / repair；Pi 模型矩阵保持 LOW=`gpt-5.3-codex-spark`、MED=`glm-5.2`、HIGH=`gpt-5.5`。
-- `pi-prompt` 与 `cursor-prompt` 都是一次性 full-capability helper；用作 sidecar 时必须在 prompt 和 tool/model 参数里显式收窄。
-- Cursor 仅是显式、手工触发的 `cursor-prompt` one-shot sidecar，不是受治理 DAG/Loop writer；受治理写入固定为 `implement-pi` / `repair-pi`，必须给出 allowed / forbidden paths 与 writeSet。
-- Shell verification 是事实源；任何完成声明都必须有本轮命令输出。
+- 主入口是 **Agent DAG**（经已发布 `loop-agent` / 可选 `agent-worker` CLI）。
+- 本 skill 对 openCode 等宿主的定位是 **Compatibility / Operator Assist**，不是「主会话实现业务代码」。
+- **主会话 = operator-only**：编排 CLI、审 writeSet、只读 status/doctor/report/observe、记 human gate、跑 shell 验证与 handoff。
+- **严禁**主会话绕过 `loop-agent` / `agent-worker` CLI，用宿主 Edit/Write/ApplyPatch 等直接改业务实现，或在 CLI 失败后「救火改文件」。
+- **允许（主会话）**：调用 `loop-agent` / `agent-worker`；只读查 `status` / `dag status` / `dag doctor` / `dag report` / `inspect` / Observe；维护任务源 `source/*` 与结构化 `task.json` 边界（通过 CLI 或显式任务准备步骤，而非替代 DAG writer）。
+- **禁止（主会话）**：直接实现功能/修 bug 业务代码；把 sidecar 当默认 writer；用聊天自述代替 shell 验证。
+- **失败时只允许**：`dag doctor` / `dag report` / `dag reconcile-run`（及 worker 侧 reconcile）、记 human gate、按边界重跑或 replan；不得改走主会话直接写实现。
+- DAG `pi` executor 是唯一受治理 Agent runtime：默认 read-only planning / review / diagnosis；`toolProfile: "write"` 时为 bounded implementation / repair。Pi 模型矩阵 LOW=`gpt-5.3-codex-spark`、MED=`glm-5.2`、HIGH=`gpt-5.5`。
+- `pi-prompt` 与 `cursor-prompt` 是一次性 helper；sidecar 须在 prompt/tool 参数中收窄。Cursor 仅显式手工 `cursor-prompt`，不是 DAG/Loop writer。
+- Shell verification 是事实源；完成声明必须有本轮命令输出。
 - 长期结论写回 `ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress/` 或 `./skill/`。
 
 ## 唯一推荐执行路径
@@ -68,21 +72,15 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
 
 ## Bounded Write Execution
 
-需要写代码时，默认使用 DAG `pi` executor 的 write tool profile（`implement-pi` / `repair-pi`）。Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证，并在执行后由主会话独立运行 shell verification。
+需要写业务代码时，**只**通过 DAG `pi` writer（`implement-pi` / `repair-pi`）经 `loop-agent run-dag` / `dag run-task --execute` 等 CLI 路径执行。主会话不得自行 Edit 实现文件「代替」writer。
 
-`cursor-prompt` 仅作人工 one-shot sidecar intervention，不进入 Loop auto-execute / Delegate auto-run / DAG writer 选择。细节见 `ai_workspace/loop-agent/cursor-prompt-sidecar.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
+Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证；执行后由主会话**独立跑 shell 验证**（仍经终端/CLI，不手改代码冒充通过）。
 
-Pi writer prompt（以及可选 sidecar prompt）都必须包含：
+`cursor-prompt` 仅作人工 one-shot sidecar intervention，不进入 Loop auto-execute / Delegate auto-run / DAG writer 选择。细节见 `ai_workspace/loop-agent/cursor-prompt-sidecar.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
 
-- task id
-- exact objective
-- allowed paths
-- forbidden paths
-- hard constraints
-- expected verification
-- instruction to preserve unrelated files
+Pi writer / 可选 sidecar prompt 都必须包含：task id、exact objective、allowed/forbidden paths、hard constraints、expected verification、preserve unrelated files。
 
-bounded writer 完成后，主会话必须独立复核；命令清单见 `references/verification-and-failure-handling.md` 的独立复核章节。
+bounded writer 完成后，主会话只做独立复核；命令清单见 `references/verification-and-failure-handling.md`。
 
 ## 进阶主题路由
 
@@ -121,12 +119,13 @@ bounded writer 完成后，主会话必须独立复核；命令清单见 `refere
 1. One task = one bounded work chunk.
 2. Source materials are mandatory: `source/需求.md` and `source/执行约束.md`. Prefer immutable originals under `source/references/` via `import-prd` or Worker `source_docs`; treat `需求.md` as a derived contract.
 3. Agent DAG is the implementation workflow. Review must three-way check references + derived source + implementation when originals exist.
-4. DAG `pi` executor stays read-only unless the node sets `toolProfile: "write"`; `pi-prompt` / `cursor-prompt` are full-capability one-shot helpers and must be bounded per call.
-5. Pi writer nodes must be bounded by explicit allowed / forbidden paths and writeSet; Cursor remains `cursor-prompt` sidecar only.
-6. Completed DAG and one-shot run facts are read-only.
-7. Do not write root `artifacts/` from read-only DAG or sidecar steps.
-8. Do not keep hidden workflow state in chat only; write durable conclusions to repo artifacts.
-9. Verify before completion.
+4. **Compatibility / Operator Assist**：主会话不得绕过 `loop-agent` / `agent-worker` CLI 直接实现或「救火」改业务代码；失败只走 doctor / reconcile / human gate / 重跑。
+5. DAG `pi` executor stays read-only unless the node sets `toolProfile: "write"`; `pi-prompt` / `cursor-prompt` are full-capability one-shot helpers and must be bounded per call.
+6. Pi writer nodes must be bounded by explicit allowed / forbidden paths and writeSet; Cursor remains `cursor-prompt` sidecar only.
+7. Completed DAG and one-shot run facts are read-only.
+8. Do not write root `artifacts/` from read-only DAG or sidecar steps.
+9. Do not keep hidden workflow state in chat only; write durable conclusions to repo artifacts.
+10. Verify before completion.
 
 ## References
 

package/skills/loop-agent/references/harness-policy.md

@@ -7,7 +7,8 @@
 - **Agent DAG** 是 medium/large、multi-file、architecture-sensitive、public-contract、CI/script 或 harness-runtime 工作的默认 implementation workflow。
 - 历史顺序式 `run analyze|plan|spec|implement|verify|auto|loop|continue` workflow 已移除。不要将其作为 fallback path 呈现。
 - **Long-running `loop`** 是 Agent DAG 之上的 outer state/evidence layer。它记录 rounds、context compression、signals、canonical refs；不得替代 complex work 的 DAG writeSet review、Decision Gate 或 shell verification。
-- **Main session** 负责 orchestrate：选一个 work chunk、准备 source materials、review DAG/writeSet、monitor failures、跑 final verification、hand off。
+- **Main session（Compatibility / Operator Assist）** 只 orchestrate：选 work chunk、准备 source materials、调用已发布 `loop-agent` / `agent-worker` CLI、review DAG/writeSet、monitor failures、跑 final shell verification、hand off。**不是**默认 implementer。
+- **严禁**主会话绕过 CLI，用宿主编辑工具直接改业务实现，或在 DAG/worker 失败后「救火改文件」。skills 是纪律文档，**不是**写入边界执法手段；执法靠 `task.json` 路径、DAG `writeSet` 与 runtime。
 - **Executors** 实现 bounded work：Pi 是唯一受治理 Agent runtime（read-only planning/review/diagnosis，以及 `toolProfile: "write"` 的 bounded implementation/repair）；shell 产出 deterministic verification facts；`cursor-prompt` 仅是 one-shot sidecar。
 - **Shell verification 是 completion fact source**。LLM review 或 advisory output 不能替代 command exit codes 与 archived evidence。
 
@@ -15,24 +16,30 @@
 
 | Tier | Default purpose | Commands |
 |---|---|---|
-| Primary | Normal autonomous implementation | `new-task` -> `dag run-task --profile auto` -> `dag validate --strict-models --strict-governance` -> `run-dag` |
-| Operator | Diagnose, recover, close out, inspect facts | `status`, `instructions`, `dag status`, `dag doctor`, `dag report`, `dag closeout-draft`, `dag reconcile-tasks`, `dag final-verification`, `inspect`, `doctor`, `spine audit`, `knowledge curate`, `docs audit`, `handoff check`, `loop-benchmark` |
-| Compatibility | Legacy task metadata and feature-study helpers | `goal`, `reference`, `study` |
-| Escape hatch | Isolated delegation, one-shot diagnosis or bounded repair | `delegate`, `worktree`, `harvest`, `pi-prompt`, `cursor-prompt` |
-| Experimental | Long-running outer task state | `loop init|status|run|record-round|add-signal|closeout` |
+| Primary | Normal autonomous implementation（经 CLI） | `new-task` -> `dag run-task --profile auto` -> `dag validate --strict-models --strict-governance` -> `run-dag` |
+| Operator | Diagnose, recover, close out, inspect facts | `status`, `instructions`, `dag status`, `dag doctor`, `dag report`, `dag reconcile-run`, `dag closeout-draft`, `dag reconcile-tasks`, `dag final-verification`, `inspect`, `doctor`, `spine audit`, `knowledge curate`, `docs audit`, `handoff check`, `loop-benchmark`；Observe：`agent-worker observe serve\|snapshot` |
+| Compatibility (CLI helpers) | Legacy task metadata and feature-study helpers | `goal`, `reference`, `study` |
+| Escape hatch | Isolated delegation, one-shot diagnosis or **显式** bounded repair | `delegate`, `worktree`, `harvest`, `pi-prompt`, `cursor-prompt`（不得作失败默认恢复） |
+| Experimental | Long-running outer task state | `loop init\|status\|run\|record-round\|add-signal\|closeout` |
 
-Prompt templates、README snippets、task instructions 应优先呈现 Primary + Operator。Compatibility 与 escape-hatch commands 仍可用，但须携带其 downgrade/fallback 含义。
+**主会话角色名 Compatibility / Operator Assist** 与上表「Compatibility (CLI helpers)」不同：前者描述宿主 agent 的权限边界，后者是遗留 CLI 命令分层。
+
+Prompt templates、README snippets、task instructions 应优先呈现 Primary + Operator。Escape-hatch 仍可用，但须携带 downgrade 含义，且**不得**写成「CLI 失败后主会话直接改代码」。
 
 ## Entry selection decision tree
 
 ```text
 Is this only status, diagnosis, recovery, or closeout?
-  yes -> Operator commands.
+  yes -> Operator CLI only (`status` / `dag doctor` / `dag report` / `reconcile` / Observe / human gate).
+         Never recover by main-session Edit of business implementation.
   no  -> Does it need recoverable, reviewable, verifiable implementation state?
-           no  -> Use read-only pi-prompt for analysis, or a tiny main-session surgical patch only if obvious and immediately verifiable.
-           yes -> Agent DAG.
+           no  -> Read-only pi-prompt / inspect only. Do not main-session implement.
+           yes -> Agent DAG via loop-agent CLI (or agent-worker outer loop that spawns loop-agent).
 ```
 
+失败恢复允许集（主会话）：`dag doctor`、`dag report`、`dag reconcile-run`、worker `task reconcile` / `pool mark-failed`（若适用）、记录 human gate、修正 **source/task.json/DAG 包** 后 re-validate/重跑。
+**禁止**：宿主直接改 `src/**` 等业务实现以绕过失败节点。
+
 在以下任一 signal 适用时用 Agent DAG 而非 broad one-shot execution：
 
 - loop-agent runtime, DAG schema, run facts, promotion/closeout, scripts/CI, public contract, or shared protocol is touched.
@@ -254,8 +261,8 @@ Verification 应从 target repo verification matrix 选择。Cross-repo document
 每个 task handoff 应回答：
 
 1. What changed and why。
-2. 用了哪条 workflow path：DAG、sidecar 或 main-session surgical patch。
-3. 若从 DAG downgrade，explicit reason 与 evidence。
+2. 用了哪条 workflow path：DAG（经 CLI）、operator 元数据维护、或显式 sidecar（须说明非默认）。
+3. 若曾考虑绕过 CLI / 主会话直接写实现，必须写明 **未采用** 及改走的 doctor/reconcile/重跑路径；禁止把「主会话救火写码」写成合法 path。
 4. Executors used 及其 boundaries。
 5. Verification commands run 与 results。
 6. DAG / one-shot / loop refs（如有）。

package/skills/loop-agent/references/hybrid-dag.md

@@ -29,7 +29,7 @@
 |-------|-------|----------|
 | **Primary / Level 3** | `dag run-task --profile auto` / `dag init-hybrid`（已实现） | 从 task `source/` 自动生成 hybrid DAG；`--profile auto` 路由 standard / review-gated / supervised template；无 profile `run-task` 默认为 standard-compatible generate+validate only |
 | **Primary / Level 2** | `run-dag --dag <path>` | 跨 Pi + shell + static executor 执行 Agent DAG orchestration |
-历史顺序式 `run analyze|plan|implement|verify|auto|loop|continue` 已移除。trivial one-line 修正时，记录的 main-session surgical patch 仍可能比建 DAG 更省，但它不是第二套 workflow runtime。
+历史顺序式 `run analyze|plan|implement|verify|auto|loop|continue` 已移除。主会话是 Operator Assist：业务实现走 Agent DAG CLI。极窄的文档/DAG JSON/task-source 元数据修正不是第二套 workflow runtime，也**不得**在 CLI 失败后变成「主会话直接改实现」。
 
 **心智模型**：`run-dag` 是 loop-agent 内自编的 Agent DAG orchestration；受治理 Agent leaf executor 只有 Pi。`cursor-prompt` 是独立 sidecar，不是 DAG node executor。不要把 Cursor 重新引入 hybrid schema / `executorModels` / writer 选择。
 
@@ -87,11 +87,11 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 
 可复用 template：`docs/templates/agent-dag.base.json`（model 生成 DAG 的首选 base template）、`docs/templates/agent-dag.schema.json`（JSON Schema）、`docs/templates/agent-dag.supervised-implementation.json`（supervised implementation：writeSet audit、soft/hard verify、process supervisor、repair、review verdict gate）、`docs/templates/backend-test-dag.json`（后端测试专用模板）、`docs/templates/frontend-test-dag.json`（FE-test RAG：Markdown case manifest、串行 Playwright CLI case 子节点与逐 case 证据）、`docs/templates/agent-dag-process-supervisor.prompt.md`、`docs/templates/agent-dag-review-verdict.prompt.md`、`docs/templates/agent-dag-authority-surface-audit.prompt.md`（可选 authority surface verifier；authority signal 或显式 enablement 匹配时由 `dag init-hybrid` 插入）、`examples/hybrid-loop-agent-dag.json`、`docs/templates/hybrid-dag.json`。
 
-### Supervised implementation flow（减少 main-session intervention）
+### Supervised implementation flow（减少 operator 中途介入）
 
-长时 implementation 曾迫使 main session 中途 re-verify、re-review 或 surgical-patch 时，用 `ai_workspace/loop-agent/templates/agent-dag.supervised-implementation.json`。
+长时 implementation 若曾迫使 operator 中途 re-verify、re-review 或（错误地）主会话救火写码，改用 `ai_workspace/loop-agent/templates/agent-dag.supervised-implementation.json`，把修复留在 DAG CLI 内。
 
-**此前 main session 介入原因**：linear hybrid DAG 缺少 in-run writeSet coverage audit；旧 supervised write-set gate 在初审返回 `request-revision` 或遗漏 `VERDICT:` 时也会直接 `partial_failed`，需要人工新建下一轮 run。此外还缺少 supervision 前归档的 soft verification、read-only process supervisor（`executor: pi`，`role: supervisor` — 非新 executor）、bounded repair exclusive writer、确定性 hard-verify shell fact，以及 fail-closed review verdict gate（除非 whitelist `VERDICT:` 行存在）。
+**此前主会话/operator 介入原因**：linear hybrid DAG 缺少 in-run writeSet coverage audit；旧 supervised write-set gate 在初审返回 `request-revision` 或遗漏 `VERDICT:` 时也会直接 `partial_failed`，需要新建下一轮 run。此外还缺少 supervision 前归档的 soft verification、read-only process supervisor（`executor: pi`，`role: supervisor` — 非新 executor）、bounded repair exclusive writer、确定性 hard-verify shell fact，以及 fail-closed review verdict gate（除非 whitelist `VERDICT:` 行存在）。
 
 **Supervised topology**（执行前替换所有 `REPLACE/WITH/...` placeholder）：
 
@@ -105,7 +105,7 @@ contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
   → review-pi → review-verdict-recovery-pi → review-gate-shell → decision-pi → closeout-pi
 ```
 
-| Stage | 减少 main-session 工作的方式 |
+| Stage | 减少 operator 中途介入的方式 |
 |-------|------------------------------|
 | `write-set-audit-pi` | implement 前捕获 missing/overlapping writeSet owner；第一条非空行必须是 canonical verdict |
 | `write-set-audit-format-repair-pi` / `final-write-set-audit-format-repair-pi` | 初审和终审各有一次只读格式恢复；只补 canonical verdict/结构并保留 findings，结论不明确时返回 `request-revision`，不得从一般正文猜 pass |
@@ -157,11 +157,11 @@ loop-agent dag run-task <task-id> --init-only --cwd <repo-root>
 - **不要**把 `.harness/dag-runs/` 内容 commit 到 git。
 - canonical per-run DAG 历史是 `.harness/dag-runs/completed/<run-id>/run.json` 及该 run 目录的 `state.json`、`executor.jsonl`、node artifacts；新建 run directory 使用 `YYYYMMDD-<slug>`。
 - root `artifacts/修改记录.md` 与 `artifacts/验证结果.md` 是 legacy current-work / explicit-write 摘要。不是 per-run 不可变历史，也不是新工作流默认交付路径。
-- Agent DAG read-only node 不得写 root `artifacts/`；若须更新 root artifacts，用显式 `exclusive` write node 或记录了理由、验证与迁移计划的 main-session surgical patch。
+- Agent DAG read-only node 不得写 root `artifacts/`；若须更新 root artifacts，用显式 `exclusive` write node（经 CLI），不要用主会话直接写实现或 root artifacts 代替节点。
 - DAG Cursor 节点交付物必须写入 `.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/`；`./artifacts/**` 是错误落点。
 - 长期结论须迁入 `ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/reports/` 或 `ai_workspace/loop-agent/progress/`。从 completed run evidence 汇总 task artifacts 时用 `promote-run <task-id> --run-id <run-id>`；再用 `closeout task <task-id>` 生成 progress。二者 deterministic，且不 mutate completed run facts。
 
-**DAG author 的 artifact-boundary 提醒**：大量 *讨论* root `artifacts/**` 的 task 仍遵守同一 write guard — read-only node 仅在 node output 返回发现；exclusive node 保持 `artifacts/**` 在 `forbiddenPaths`，除非 concrete path 在 `writeSet`。不要在 declared writeSet 外 instruct implementer 写 `artifacts/修改记录.md` 或 `artifacts/验证结果.md`（P3 boundary-risk practice）。scout 在链接 skill reference 中发现 stale wording 时，把那些 path 纳入 implementer writeSet，或接受记录的 main-session patch（P2 教训：`hybrid-dag.md` 被 scout 发现但 initial writeSet 遗漏）。
+**DAG author 的 artifact-boundary 提醒**：大量 *讨论* root `artifacts/**` 的 task 仍遵守同一 write guard — read-only node 仅在 node output 返回发现；exclusive node 保持 `artifacts/**` 在 `forbiddenPaths`，除非 concrete path 在 `writeSet`。不要在 declared writeSet 外 instruct implementer 写 `artifacts/修改记录.md` 或 `artifacts/验证结果.md`（P3 boundary-risk practice）。scout 在链接 skill reference 中发现 stale wording 时，把那些 path 纳入 implementer writeSet 并在 DAG 内写入（P2 教训：`hybrid-dag.md` 被 scout 发现但 initial writeSet 遗漏）；不要依赖 post-DAG 主会话大段补写。
 
 ### Decision Gate（M3–M5 runtime）
 
@@ -238,7 +238,7 @@ review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-sum
 | 7 | Completed facts | `.harness/dag-runs/completed/**` 仅可读 evidence — 归档后永不 mutate 历史 run 目录、`run.json`、`state.json` 或 `artifacts/**` |
 | 8 | Verdict gate | review/supervisor 应以 `VERDICT: pass` 或 `VERDICT: request-revision` 开头以利阅读；用 current-run `<fromNodeId>.json`（`$HARNESS_DAG_RUN_DIR`）上 `shell.verdictGate` block，exact-match `accept[]`；默认 `lineMode=first-non-empty`，supervised template 用 `first-verdict-line` 容忍 preamble 或第一条 normalized `VERDICT:` 前的常见整行 Markdown emphasis |
 | 9 | Decision Gate | 恰好 emit 一个 `DECISION_ENVELOPE_JSON` block；`audit.runId` 须绑定 **当前** run id；禁止 `decision: accept`、发明 schema、extra root key；填 `audit.nodeId` / `audit.model` |
-| 10 | writeSet planning | scout 应列出链接的 `./skill/references/**` 为 **writeSet expansion candidates**（P2：遗漏链接 skill ref 迫使 main-session patch） |
+| 10 | writeSet planning | scout 应列出链接的 `./skill/references/**` 为 **writeSet expansion candidates**（P2：遗漏链接 skill ref 会导致无法在 DAG 内收敛，禁止事后主会话大段补写） |
 | 11 | Evidence summary | `evidence-summary-shell` / leading `EVIDENCE:` 行是 **practice convention**，非 runtime executor、schema field 或 parser |
 | 12 | Featureization | 除非 repeated real-run failure 证明 checklist guidance 不够，勿加 runtime/schema/validator/CLI/executor feature |
 | 13 | writeSet / writer backend | `exclusive` node 用 narrow、disjoint path；无 `**`；固定用 Pi write profile |

package/skills/loop-agent/references/multi-worktree.md

@@ -12,7 +12,7 @@
 
 - 有 ≥ 2 个可独立推进的 task id，且希望在不同 worktree 中并发运行
 - 或希望主 repo 保持干净供审阅，而 leaf executor 在 worktree 内跑 `implement`/`verify`
-- 单一顺序 task 可跳过 — 直接 Agent DAG 或 main-session surgical patch 足够
+- 单一顺序 task 可跳过 multi-worktree — 用 Agent DAG CLI 即可；不要用主会话直接实现代替 DAG
 
 ### 核心命令
 

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

@@ -4,24 +4,24 @@
 
 ## 核心立场
 
-**Agent DAG 优先，main session 编排，executor 实现，shell 验证。**
+**Agent DAG 优先，main session = Compatibility / Operator Assist，executor 经 CLI 实现，shell 验证。**
 
 `harness.json.workflowPolicy` 的 repo 级 policy 将 Agent DAG 作为 autonomous 与 harness-governed work 的 implementation workflow。历史顺序式 `run ...` workflow 已移除。
 
-main session 是 decision-maker 与 scheduler，不是默认 implementer。其稀缺 context 应留给 objective 对齐、DAG review、failure triage、executor 选择、verification review 与 handoff。长时 implementation 应委派给 Pi-only Agent DAG node、shell verification 或 worktree delegate；Cursor 仅作为显式 one-shot sidecar。
+main session 是 decision-maker 与 scheduler，**不是** implementer。稀缺 context 只用于 objective 对齐、调用 `loop-agent` / `agent-worker`、DAG/writeSet review、failure triage、verification review 与 handoff。长时 implementation 必须委派给 Pi-only Agent DAG node（经 CLI）、shell verification 或 worktree `delegate`；Cursor 仅显式 one-shot sidecar。
 
-这不是绝对禁止 edit。main-session 手动 edit 仅允许作为有 verification 与 artifact 记录的 bounded surgical patch。
+**严禁**主会话绕过 CLI 直接改业务实现，或在 DAG/worker 失败后「救火改文件」。宿主 Edit/Write 不是受治理恢复路径。
 
 ## 默认执行模型
 
 | Actor | 主角色 | 避免 |
 |---|---|---|
-| Main session | Objective、contract、DAG review、routing、failure triage、approve/reject/resume、handoff | 成为长时 coder |
-| Agent DAG runner | 可恢复 multi-node orchestration、rank-parallel execution、write policy、run artifacts | 不更新 DAG/source 的 ad-hoc replanning |
-| Cursor one-shot prompt | 有界诊断、人工介入的小修复或 executor 调试 | 作为 DAG executor、自动写入路径或无 path scope 的宽写入 |
-| Pi executor / prompt | Fast reasoning、read-only scouting、planning、review、decision-envelope advice | 充当 hidden state source |
-| Shell executor | 确定性事实：tests、lint、typecheck、build、governance checks | 智能 repair |
-| Human gate | Product、architecture、risk、permission 决策 | 常规 implementation debugging |
+| 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 宽写、失败默认恢复 |
+| Pi executor / prompt | DAG 内 scouting/planning/review/write profile；sidecar 只读诊断 | 充当 hidden state；主会话假装自己是 Pi writer |
+| Shell executor | 确定性验证事实 | 智能 repair |
+| Human gate | Product、architecture、risk、permission | 常规 implementation debugging |
 
 ## 入口选择
 
@@ -29,9 +29,9 @@ main session 是 decision-maker 与 scheduler，不是默认 implementer。其
 
 **supervised Agent DAG** 用于 `governanceProfile=supervised`，或工作触及 loop-agent runtime、scripts/CI、schema/public contract、多个 exclusive writer、repair flow 或 high-cost path。
 
-**one-shot Pi / Cursor prompt** 仅作受控 sidecar intervention，不是 workflow state source。
+**one-shot Pi / Cursor prompt** 仅作受控 sidecar intervention，不是 workflow state source，也不是 CLI 失败后的默认出口。
 
-**main-session surgical patch** 仅用于 small、obvious、low-risk 的修正，且 delegation 开销会占主导。
+**main-session 直接写业务实现：默认禁止。** 仅治理/脚手架层面的极窄修正见下文「允许的 operator 写入」；功能实现、bugfix、多文件逻辑变更必须走 DAG CLI。
 
 ## Sidecar intervention 协议
 
@@ -70,11 +70,11 @@ Agent DAG read-only node **不得**写 root `artifacts/`。
 - Agent DAG node 发现属于 node output 与 runner-owned artifacts，位于 `.harness/dag-runs/<state>/<run-id>/<node-id>/`；Cursor 节点的 `修改记录.md` / `验证结果.md` 位于 `.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/`。
 - 不要把 root `artifacts/` 当作所有 DAG node 的共享 state 交集；`.harness/dag-runs/<run-id>/` 才是 DAG state 交集。
 - `./artifacts/**` 不是 DAG artifact 位置；出现该目录通常表示 Cursor prompt 没有收到 DAG-owned artifact dir。
-- 若必须更新 root `artifacts/`，用显式 write-capable node 或 narrow scope、verification、recorded rationale 与后续迁移计划的 main-session surgical patch。
+- 若必须更新 root `artifacts/`，用显式 write-capable DAG node；不要用主会话「顺手写 root artifacts」代替节点。
 
-**Linked skill-reference writeSet candidates**：DAG task 变更 workflow 语义（artifact boundary、verdict gate、evidence summary、intervention policy）时，scout node 应提议 `./skill/references/**` 下链接文件为 **writeSet expansion candidates**，而非仅 primary docs。P2 表明 implementer writeSet 遗漏 `hybrid-dag.md` 时，虽 scout 已发现 drift，仍须 post-DAG main-session patch。
+**Linked skill-reference writeSet candidates**：DAG task 变更 workflow 语义时，scout 应提议 `./skill/references/**` 为 **writeSet expansion candidates**，并在下一轮 DAG 中写入，而不是 post-DAG 由主会话大段补写 skill。
 
-**Bounded main-session patch 须记录**：DAG run 中或之后任何可接受的 surgical patch（scope、变更文件、verification、rationale）应写入 `ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress/` 或 active exec plan — 不可静默应用且无 audit trail。
+**允许的 operator 写入必须记录**：若发生下文极窄 operator 文件维护，须在 `ai_workspace/loop-agent/reports/`、`progress/` 或 exec plan 留下 scope + verification — 不可静默、不可当作实现完成。
 
 **勿把 root `artifacts/**` 当 read-only DAG handoff**（P3/P5）：即使 task 文本、scout 或 supervisor 讨论 `artifacts/修改记录.md` / `artifacts/验证结果.md`，read-only DAG node 只能在 node output 返回发现。root `artifacts/` 是 legacy / explicit-write 摘要区，不是 in-flight DAG node 的共享 scratchpad，也不是新工作流默认 handoff。post-DAG 持久 handoff 用 `ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress/`、exec-plan 索引与 `.harness/dag-runs/completed/<run-id>/` node artifacts。
 
@@ -110,55 +110,54 @@ main session 编排；不是默认 implementer。in-flight run 期间：
 
 完整 authoring checklist：`ai_workspace/loop-agent/agent-dag-runner.md` §「Agent DAG authoring checklist」与 `hybrid-dag.md` § Authoring checklist。
 
-## Main-session surgical patch policy
+## 允许的 operator 写入（极窄；默认仍走 CLI）
 
-仅当以下**全部**成立时允许：
+主会话**默认零业务写权限**。下列**全部**成立时，才允许维护**治理/任务元数据**（不是产品功能实现）：
 
-1. 变更 small 且 obvious，通常 1–3 个文件。
+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 node 的 `writeSet` 或其他 executor 声明职责冲突。
-5. 可用 targeted command 立即 verify。
-6. patch 摘要与 verification 结果记录在 artifacts/progress/report。
+3. 不改变 product requirement 语义、architecture、public API、data model 或 cross-platform contract。
+4. 不与 active DAG exclusive `writeSet` 冲突。
+5. 可立即 shell verify。
+6. 记录 scope + verification；且**下一步仍是 CLI re-validate / rerun**，不是「主会话继续实现」。
 
 好例子：
 
-- validation 指出后修正 DAG JSON path 或 schema typo。
+- 修 DAG JSON path / schema typo 后 `dag validate` + `run-dag`。
 - 修正 doc index link 或 typo。
-- revert 明显 out-of-scope 的生成 scratch file。
-- LSP 或 typecheck 指向确切 issue 时修单个 import/path 错误。
+- 删除明显 out-of-scope 的生成 scratch。
+- 补全 `source/执行约束.md` 中的 allowedPaths 列表后 regenerate DAG。
 
-坏例子：
+坏例子（**一律禁止**）：
 
-- 手工按 task `artifacts/实现计划.md` 或根 `artifacts/` 实现功能（应走 DAG plan/implement 节点或 exec-plan）。
-- 不委派就修大量 test failure。
-- 改 API/contract 语义。
-- refactor 子系统。
-- 编辑 in-flight exclusive DAG node 拥有的文件。
+- CLI/DAG 失败后主会话直接改 `src/**`「救火」。
+- 手工按计划实现功能或修测试失败。
+- 改 API/contract 语义或 refactor 子系统。
+- 编辑 in-flight exclusive DAG node 拥有的实现文件。
+- 用 `cursor-prompt` / 宿主 Write 代替 `implement-pi` / `repair-pi`。
 
-最小协议：
+失败默认序列（替代旧 surgical-patch 心智）：
 
 ```text
-1. 标记 intervention / 必要时 pause。
-2. 检查 status 与 dirty files。
-3. 声明 reason 与 scope。
-4. 做最小 edit。
-5. 跑 targeted verification。
-6. 记录 patch 摘要与 verification evidence。
-7. Resume DAG / rerun failed node / restart verify。
+1. dag doctor / dag report / status
+2. 分类失败；需要时 reconcile-run 或 human gate
+3. 仅当 source/DAG 包错误时最小修正元数据
+4. dag validate → run-dag / worker 重试
+5. shell verification
+6. 记录 evidence；禁止主会话实现收尾
 ```
 
 ## 失败状态机
 
 ```text
-Run DAG workflow
-  -> success: verify -> handoff
-  -> node/step failure: diagnose
-       -> transient/tool issue: one-shot sidecar 或 retry -> verify -> resume
-       -> bounded implementation issue: Cursor/Pi fix -> verify -> resume
-       -> DAG design/source issue: stop -> edit DAG/source -> validate/spec -> rerun
-       -> requirement/architecture issue: Decision Gate 或 human approval -> resume/reject
-  -> verification failure: bounded fix loop 或 replan，永不宣称完成
+Run DAG workflow (via loop-agent / agent-worker CLI)
+  -> success: shell verify -> handoff
+  -> node/step failure: diagnose with doctor/report
+       -> transient/tool issue: CLI retry or explicit read-only sidecar advice -> verify -> resume
+       -> bounded implementation issue: DAG repair-pi / re-run writer via CLI（禁止主会话 Edit 实现）
+       -> DAG design/source issue: stop -> fix DAG/source metadata -> validate -> rerun
+       -> requirement/architecture issue: Decision Gate / human approval -> resume/reject
+  -> verification failure: CLI bounded repair loop 或 replan；永不主会话手改冒充完成
 ```
 
 ## 记录要求

package/skills/loop-agent/references/task-workflow.md

@@ -17,7 +17,7 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
 
 当目标仓库是 loop-agent 本仓库时，`loop-agent` 命令必须来自 npm 上已发布的安装包。首次安装或有意升级可用 `@tea-agent/loop-agent@latest`，但一次自举任务启动后不要中途升级控制器，并记录 `npm list -g @tea-agent/loop-agent --depth=0` 显示的实际版本。不要用当前工作区的 `npm link` 或 `npm run dev` 控制会改动 CLI、DAG runtime、executor、package metadata 或 build output 的任务；源码开发和 focused debugging 才使用 `npm run dev -- <args>`。
 
-低风险的一行修正文档或配置时，可以由 main session 做 surgical patch，但仍必须记录 scope 并运行对应验证命令。
+主会话默认是 **Compatibility / Operator Assist**：实现工作必须走上方 DAG CLI。低风险的文档/index/task-source 元数据修正仅作 operator 维护，须记录 scope、跑验证，且**不得**扩展为业务实现或 CLI 失败后的救火写码；见 `orchestrator-and-interventions.md`。
 
 ## Source Materials
 

package/skills/loop-agent/references/verification-and-failure-handling.md

@@ -105,7 +105,7 @@ product-line taxonomy 的事实源是 `ai_workspace/loop-agent/design/state-and-
 
 ### Cursor bounded write 后的独立复核
 
-Cursor bounded execution 完成后，主会话必须独立执行：
+显式 `cursor-prompt` sidecar（非默认路径）完成后，主会话必须**独立跑验证命令**，不得用手改代码「补成绿色」：
 
 ```bash
 git status --short
@@ -119,15 +119,22 @@ loop-agent docs audit
 loop-agent handoff check <task-id>
 ```
 
-Cursor 自己报告的完成不算 verification fact；以上命令的 exit code 与输出才是完成声明的证据。
+Cursor / 主会话自述完成不算 verification fact；以上命令的 exit code 与输出才是完成声明的证据。
 
-### 失败处理
+### 失败处理（Compatibility / Operator Assist）
 
-child agent 失败时：
+主会话定位为 operator，**不是**失败后的实现后备通道。
 
-- **业务/测试失败**：让 child agent 在同一 task bounds 内修复
-- **Workflow runtime 失败**（如 `loop-agent` runtime 问题、部分 artifact 生成、输出聚合 crash）：保持 task contract，但允许 main agent 或 child agent 在同一 scoped implementation 内手动完成，仍跑 `verify`
-- **意外残留**（tmp 文件、探索性 mock、scratch 输出）：handoff 前删除
+| 失败类型 | 主会话允许 | 主会话禁止 |
+|---|---|---|
+| 业务/测试失败 | 在同一 bounds 内 **重跑** DAG writer / repair 节点；`dag doctor` / `dag report` | 直接 Edit 业务实现「先修好再说」 |
+| Workflow / runtime 失败 | `dag doctor`、`dag reconcile-run`、记 human gate、升级/重装已发布 controller 后 **新 run**；必要时修 **task source / DAG JSON** 再 validate | 主会话手动完成 scoped implementation 以绕过 CLI |
+| Write guard / path 冲突 | 收紧 `allowedPaths`/`writeSet` 后 regenerate/revalidate | 扩大权限后由主会话直接写 |
+| 需求/架构不清 | Decision Gate / human approval | 边猜边改业务代码 |
+| 意外残留（tmp/scratch） | handoff 前删除 scratch；记录在 report | 把清理当成「顺便重构实现」 |
+
+**默认恢复序列**：diagnose（doctor/report）→ classify → reconcile 或 replan → CLI 重跑 → shell verify。
+**永远不要**：`loop-agent` / `agent-worker` 失败 ⇒ 主会话直接改仓库实现。
 
 ### Closeout 规则
 workflow/runtime/ai_workspace/loop-agent/skill 变更结束时：