@tea-agent/loop-agent 0.5.0 → 0.7.0

package/skills/loop-agent/references/long-running-loop.md

@@ -1,59 +1,59 @@
-# Long-Running Loop 详细规则
-
-需要跨多轮记录目标、压缩记忆、round facts 引用，或使用 `loop init|status|run|record-round|add-signal|closeout` 时使用本文。`loop` 是 experimental outer workflow state：它不替代 Agent DAG，也不等同于已移除的顺序式 `run loop`。共享 policy 摘要见 `harness-policy.md` 的 "Long-running loop policy" 一节。
-
-## 最小入口
-
-```bash
-loop-agent loop init <task-id>
-loop-agent loop status <task-id>
-loop-agent loop run <task-id> --action shell-verify --command "bash scripts/check-repo.sh"
-loop-agent loop run <task-id> --action pi-review
-loop-agent loop run <task-id> --action cursor-fix --model composer-2.5
-loop-agent loop run <task-id> --action dag
-loop-agent loop run <task-id> --action dag --execute
-loop-agent loop run <task-id> --auto --max-rounds 3
-loop-agent loop run <task-id> --auto --max-rounds 3 --allow-cursor-fix
-loop-agent loop add-signal <task-id> --type human_followup --message "review this boundary before closeout"
-loop-agent loop closeout <task-id>
-loop-agent loop record-round <task-id> \
-  --action manual \
-  --result "summary" \
-  --lesson "what to carry forward" \
-  --next "next bounded action" \
-  --decision continue \
-  --ref ".harness/runs/completed/<run-id>/result.json"
-```
-
-## 状态源与记忆规则
-
-- `loop/objective.md` 与 `loop/context.md` 是运行态投影；exec plan / task source 仍是需求状态源。
-- `rounds.jsonl` 只引用 canonical facts，不复制完整 executor 日志。
-- `context.md` 每轮重写为压缩记忆，不无限 append。
-- `events.jsonl` 只用于 observability，覆盖 loop_start、round_start、action_start、action_finish、context_rewrite、decision、loop_finish；不要把 events 当状态源。
-
-## Action 规则
-
-- `loop run --action shell-verify` 是 deterministic action；命令 exit code 决定 verification result，输出摘要写入 `loop/verification/round-N.json`。
-- `loop run --action pi-review` 必须保持 read-only；工具 allowlist 固定为 `read,grep,find,ls`，输出必须包含 `findingSummary`、`failureCategory`、`nextHypothesis`、`recommendedAction`、`fixScope`、`rootCause`，其中 `recommendedAction` 只能是 `implement_fix|replan|pause|done`。
-- `loop run --action cursor-fix` 必须读取 task `allowedPaths` / `forbiddenPaths`，拒绝空 allowedPaths 或 allowed/forbidden overlap；对 `complexity=medium|large` 的任务，还必须已有 loop `dag` round 证据，或在 `task.json.dagFallbackReason` 中写明 DAG runtime fallback 原因。调用现有 Cursor bounded executor，并把 one-shot evidence 归档到 `.harness/runs/completed|failed/`。
-- `cursor-fix` 只表示 bounded write round 已执行；它不会把 loop 标记 complete，下一步必须进入 `shell-verify` 或 review。
-- `loop run --action dag` 默认是 review mode：调用 `dag run-task <task-id> --profile auto --strict-models` 生成 DAG，再用 `dag validate --strict-models --strict-governance` 校验，并记录 review packet。
-- `loop run --action dag --execute` 才会调用 `run-dag`，随后读取 `dag report --json` 作为 round result；paused DAG 会让 loop 进入 `paused`。
-
-## Auto mode 与写入边界
-
-- `loop run --auto --max-rounds N` 使用 deterministic policy 选择下一轮 action；默认只会自动选择 shell-verify、pi-review、dag review 或 policy pause/block，不自动触发 Cursor 写入。
-- 自动 `cursor-fix` 必须显式 opt-in：`task.json.loopAutoWritePolicy="enabled"`，或 `loopAutoWritePolicy="approval-required"` 加 pending approval signal / `--allow-cursor-fix`。即使 opt-in，也必须通过 `allowedPaths`/`forbiddenPaths`/DAG evidence guard；guard 失败会 pause，不会绕过写入边界。
-- auto mode 遇到同类 failure streak 达阈值会 blocked，避免无限重试。
-
-## Signals
-
-- `loop add-signal` 写入 durable `signals.jsonl`，支持 `human_followup|approval|scope_changed|review_feedback`；urgent/scope_changed 会 pause，review feedback / human follow-up 先走 read-only Pi review，approval 触发下一轮 DAG review packet。
-- Signals 不直接覆盖 `objective.md`；DAG decision envelope / approve / reject / resume 仍由 DAG action 机制管理，loop 只记录 refs。
-
-## Closeout
-
-- `loop closeout` 从 loop state、objective/context、rounds 和 signals 派生 `loop/closeout.md` draft；draft 会标出 workflow path（`dag` / `explicit-fallback` / `missing-dag-evidence` / `micro-or-small`）与 fallback reason。
-- 非 complete 状态必须标 partial/paused/blocked，不能修改 completed facts；medium/large loop 若缺少 DAG round 且没有 `dagFallbackReason`，必须把缺失 DAG 证据列为 remaining risk。
-- 完成声明仍必须由 shell verification、review verdict 和 success criteria coverage 证明。
+# Long-Running Loop 详细规则
+
+需要跨多轮记录目标、压缩记忆、round facts 引用，或使用 `loop init|status|run|record-round|add-signal|closeout` 时使用本文。`loop` 是 experimental outer workflow state：它不替代 Agent DAG，也不等同于已移除的顺序式 `run loop`。共享 policy 摘要见 `harness-policy.md` 的 "Long-running loop policy" 一节。
+
+## 最小入口
+
+```bash
+loop-agent loop init <task-id>
+loop-agent loop status <task-id>
+loop-agent loop run <task-id> --action shell-verify --command "bash scripts/check-repo.sh"
+loop-agent loop run <task-id> --action pi-review
+loop-agent loop run <task-id> --action cursor-fix --model composer-2.5
+loop-agent loop run <task-id> --action dag
+loop-agent loop run <task-id> --action dag --execute
+loop-agent loop run <task-id> --auto --max-rounds 3
+loop-agent loop run <task-id> --auto --max-rounds 3 --allow-cursor-fix
+loop-agent loop add-signal <task-id> --type human_followup --message "review this boundary before closeout"
+loop-agent loop closeout <task-id>
+loop-agent loop record-round <task-id> \
+  --action manual \
+  --result "summary" \
+  --lesson "what to carry forward" \
+  --next "next bounded action" \
+  --decision continue \
+  --ref ".harness/runs/completed/<run-id>/result.json"
+```
+
+## 状态源与记忆规则
+
+- `loop/objective.md` 与 `loop/context.md` 是运行态投影；exec plan / task source 仍是需求状态源。
+- `rounds.jsonl` 只引用 canonical facts，不复制完整 executor 日志。
+- `context.md` 每轮重写为压缩记忆，不无限 append。
+- `events.jsonl` 只用于 observability，覆盖 loop_start、round_start、action_start、action_finish、context_rewrite、decision、loop_finish；不要把 events 当状态源。
+
+## Action 规则
+
+- `loop run --action shell-verify` 是 deterministic action；命令 exit code 决定 verification result，输出摘要写入 `loop/verification/round-N.json`。
+- `loop run --action pi-review` 必须保持 read-only；工具 allowlist 固定为 `read,grep,find,ls`，输出必须包含 `findingSummary`、`failureCategory`、`nextHypothesis`、`recommendedAction`、`fixScope`、`rootCause`，其中 `recommendedAction` 只能是 `implement_fix|replan|pause|done`。
+- `loop run --action cursor-fix` 必须读取 task `allowedPaths` / `forbiddenPaths`，拒绝空 allowedPaths 或 allowed/forbidden overlap；对 `complexity=medium|large` 的任务，还必须已有 loop `dag` round 证据，或在 `task.json.dagFallbackReason` 中写明 DAG runtime fallback 原因。调用现有 Cursor bounded executor，并把 one-shot evidence 归档到 `.harness/runs/completed|failed/`。
+- `cursor-fix` 只表示 bounded write round 已执行；它不会把 loop 标记 complete，下一步必须进入 `shell-verify` 或 review。
+- `loop run --action dag` 默认是 review mode：调用 `dag run-task <task-id> --profile auto --strict-models` 生成 DAG，再用 `dag validate --strict-models --strict-governance` 校验，并记录 review packet。
+- `loop run --action dag --execute` 才会调用 `run-dag`，随后读取 `dag report --json` 作为 round result；paused DAG 会让 loop 进入 `paused`。
+
+## Auto mode 与写入边界
+
+- `loop run --auto --max-rounds N` 使用 deterministic policy 选择下一轮 action；默认只会自动选择 shell-verify、pi-review、dag review 或 policy pause/block，不自动触发 Cursor 写入。
+- 自动 `cursor-fix` 必须显式 opt-in：`task.json.loopAutoWritePolicy="enabled"`，或 `loopAutoWritePolicy="approval-required"` 加 pending approval signal / `--allow-cursor-fix`。即使 opt-in，也必须通过 `allowedPaths`/`forbiddenPaths`/DAG evidence guard；guard 失败会 pause，不会绕过写入边界。
+- auto mode 遇到同类 failure streak 达阈值会 blocked，避免无限重试。
+
+## Signals
+
+- `loop add-signal` 写入 durable `signals.jsonl`，支持 `human_followup|approval|scope_changed|review_feedback`；urgent/scope_changed 会 pause，review feedback / human follow-up 先走 read-only Pi review，approval 触发下一轮 DAG review packet。
+- Signals 不直接覆盖 `objective.md`；DAG decision envelope / approve / reject / resume 仍由 DAG action 机制管理，loop 只记录 refs。
+
+## Closeout
+
+- `loop closeout` 从 loop state、objective/context、rounds 和 signals 派生 `loop/closeout.md` draft；draft 会标出 workflow path（`dag` / `explicit-fallback` / `missing-dag-evidence` / `micro-or-small`）与 fallback reason。
+- 非 complete 状态必须标 partial/paused/blocked，不能修改 completed facts；medium/large loop 若缺少 DAG round 且没有 `dagFallbackReason`，必须把缺失 DAG 证据列为 remaining risk。
+- 完成声明仍必须由 shell verification、review verdict 和 success criteria coverage 证明。

package/skills/loop-agent/references/model-routing.md

@@ -1,36 +1,36 @@
-# 模型配置与路由
-
-查看或修改 loop-agent model 默认值、Agent DAG `executorModels` 或 Pi model/provider 设置时使用本文。
-
-## 模型配置
-
-模型设置来自 repo `harness.json`。历史 `models.<step>` 只作为旧 task metadata 兼容读取；新 DAG work 不从这里路由模型。
-
-示例模型记录：
-
-```json
-{
-  "provider": "wizard-local",
-  "model": "gpt-5.3-codex-spark"
-}
-```
-
-Agent DAG node 的模型来自 DAG JSON 中的 `executorModels`，并由 `dag validate --strict-models` 检查 canonical matrix 漂移。若变更模型配置，须同步更新 `harness.json`、相关测试、repo docs 与本 skill。
-
-`pi-prompt` 是独立 one-shot helper，不使用 `harness.json.models` 或 DAG `executorModels`。当前默认是 `wizard-local/glm-5.2`；高复杂度 one-shot 显式传 `--model gpt-5.5`。Agent DAG `pi` executor 的 canonical matrix 保持；读写 profile 共用同一矩阵：
-
-```json
-{
-  "LOW": "gpt-5.3-codex-spark",
-  "MED": "glm-5.2",
-  "HIGH": "gpt-5.5"
-}
-```
-
-始终信任当前 repo config，而非硬编码示例：
-```bash
-loop-agent inspect
-```
-并在输出中核对 `models` 与 Agent DAG 文档中的 `executorModels` 约定。
-
-Pi SDK runtime reuse 仍为 **default-off**（`CODE_AGENT_PI_REUSE_RUNTIME` 未设/`off`/未知）。opt-in 须显式 `auto-run`；`CODE_AGENT_PI_BACKEND=cli-only` 绕过 reuse。无 live call 的确定性 M2/M3 decision 摘要用 `pi-reuse-benchmark`（见 `command-reference.md`）。
+# 模型配置与路由
+
+查看或修改 loop-agent model 默认值、Agent DAG `executorModels` 或 Pi model/provider 设置时使用本文。
+
+## 模型配置
+
+模型设置来自 repo `harness.json`。历史 `models.<step>` 只作为旧 task metadata 兼容读取；新 DAG work 不从这里路由模型。
+
+示例模型记录：
+
+```json
+{
+  "provider": "wizard-local",
+  "model": "gpt-5.3-codex-spark"
+}
+```
+
+Agent DAG node 的模型来自 DAG JSON 中的 `executorModels`，并由 `dag validate --strict-models` 检查 canonical matrix 漂移。若变更模型配置，须同步更新 `harness.json`、相关测试、repo docs 与本 skill。
+
+`pi-prompt` 是独立 one-shot helper，不使用 `harness.json.models` 或 DAG `executorModels`。当前默认是 `wizard-local/glm-5.2`；高复杂度 one-shot 显式传 `--model gpt-5.5`。Agent DAG `pi` executor 的 canonical matrix 保持；读写 profile 共用同一矩阵：
+
+```json
+{
+  "LOW": "gpt-5.3-codex-spark",
+  "MED": "glm-5.2",
+  "HIGH": "gpt-5.5"
+}
+```
+
+始终信任当前 repo config，而非硬编码示例：
+```bash
+loop-agent inspect
+```
+并在输出中核对 `models` 与 Agent DAG 文档中的 `executorModels` 约定。
+
+Pi SDK runtime reuse 仍为 **default-off**（`CODE_AGENT_PI_REUSE_RUNTIME` 未设/`off`/未知）。opt-in 须显式 `auto-run`；`CODE_AGENT_PI_BACKEND=cli-only` 绕过 reuse。无 live call 的确定性 M2/M3 decision 摘要用 `pi-reuse-benchmark`（见 `command-reference.md`）。

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

@@ -1,54 +1,54 @@
-# Multi-Worktree 并行模式
-
-同时驱动两个及以上独立 loop-agent task、委派到 isolated worktree、或 harvest 已完成工作时使用本文。
-
-## Multi-Worktree 并行模式
-
-需要**同时推进两个及以上独立 loop-agent task** 时，用 multi-worktree mode 隔离编辑与测试。
-
-> **Historical（已移除）**：`subagent list|start|attach|stop|wait|wakeup`、`dashboard` 与 `delegate --supervised` 已随 tmux 白盒 lifecycle 移除。并行观察请用各 task 的 `status`、worktree 内 `logs/`，或 Agent DAG `dag status` / `dag report`。
-
-### 何时启用
-
-- 有 ≥ 2 个可独立推进的 task id，且希望在不同 worktree 中并发运行
-- 或希望主 repo 保持干净供审阅，而 leaf executor 在 worktree 内跑 `implement`/`verify`
-- 单一顺序 task 可跳过 — 直接 Agent DAG 或 main-session surgical patch 足够
-
-### 核心命令
-
-```bash
-loop-agent delegate <task-id> [--executor pi|cursor] [--base <branch>] [--branch <name>] [--no-symlink] [--auto-run] [--no-auto-run]
-loop-agent harvest <task-id> [--squash] [--no-archive] [--keep-worktree]
-loop-agent worktree list
-```
-
-`delegate` 是一步原子操作：校验 `task.json` + `source/需求.md` + `source/执行约束.md` → 在 branch `task/<task-id>` 上创建 `git worktree .worktrees/<task-id>` → 同步 `source/` 与 `task.json` 到 worktree → 相对 symlink `./node_modules` → cursor 默认 in-process SDK direct；Pi `--auto-run` 已移除并会提示 DAG 路径。
-
-`harvest` 是对称 closeout：仅当 `task.status === "completed"` 才运行，然后 merge（默认 `--no-ff`，或 `--squash`），将 `artifacts/`、`logs/`、`.workflow_state.json` 归档回主 repo，移除 worktree + branch。
-
-### 主窗口职责（勿与 executor 重叠）
-
-1. delegate 前与用户 refine `需求.md` / `执行约束.md`
-2. `delegate` 返回后**不要**碰 `plan` 或 `implement` — 让 worktree 内 executor 跑
-3. 用 `status <task-id>` 与 worktree 内 `logs/workflow.log`、`logs/executor.jsonl` 观察进度
-4. task 报告 verify-passed 后，用 `git -C .worktrees/<task-id> log -p main..` 审 diff，再跑 `harvest`
-5. task 失败则**不要** harvest — 进入 worktree 排障并重跑 verify
-
-### 生命周期概览
-
-```
-delegate → executor 跑 spec/implement/verify → completed → harvest → archive + cleanup
-                                          ↘ failed   → worktree 内排障（不 harvest）
-```
-
-### 失败处理
-
-- `delegate` fail-fast：任何 source/conflict 错误在创建 worktree 前 abort
-- `harvest` 拒绝 failed/active task；merge conflict 时打印 conflict 文件（手动解决后重跑）
-- `worktree list` 只读；从任意窗口运行都不影响 in-flight delegate
-
-### 与 Agent DAG 的关系
-
-Agent DAG 是默认 autonomous path；`delegate`/`harvest` 是 cursor-direct 的 worktree escape hatch。多 task 并行时，每个 task 独立 `delegate`，完成后分别 `harvest`。
-
-详见 `docs/cursor-executor-usage.md` 与 `docs/loop-agent-harness.md`。
+# Multi-Worktree 并行模式
+
+同时驱动两个及以上独立 loop-agent task、委派到 isolated worktree、或 harvest 已完成工作时使用本文。
+
+## Multi-Worktree 并行模式
+
+需要**同时推进两个及以上独立 loop-agent task** 时，用 multi-worktree mode 隔离编辑与测试。
+
+> **Historical（已移除）**：`subagent list|start|attach|stop|wait|wakeup`、`dashboard` 与 `delegate --supervised` 已随 tmux 白盒 lifecycle 移除。并行观察请用各 task 的 `status`、worktree 内 `logs/`，或 Agent DAG `dag status` / `dag report`。
+
+### 何时启用
+
+- 有 ≥ 2 个可独立推进的 task id，且希望在不同 worktree 中并发运行
+- 或希望主 repo 保持干净供审阅，而 leaf executor 在 worktree 内跑 `implement`/`verify`
+- 单一顺序 task 可跳过 — 直接 Agent DAG 或 main-session surgical patch 足够
+
+### 核心命令
+
+```bash
+loop-agent delegate <task-id> [--executor pi|cursor] [--base <branch>] [--branch <name>] [--no-symlink] [--auto-run] [--no-auto-run]
+loop-agent harvest <task-id> [--squash] [--no-archive] [--keep-worktree]
+loop-agent worktree list
+```
+
+`delegate` 是一步原子操作：校验 `task.json` + `source/需求.md` + `source/执行约束.md` → 在 branch `task/<task-id>` 上创建 `git worktree .worktrees/<task-id>` → 同步 `source/` 与 `task.json` 到 worktree → 相对 symlink `./node_modules` → cursor 默认 in-process SDK direct；Pi `--auto-run` 已移除并会提示 DAG 路径。
+
+`harvest` 是对称 closeout：仅当 `task.status === "completed"` 才运行，然后 merge（默认 `--no-ff`，或 `--squash`），将 `artifacts/`、`logs/`、`.workflow_state.json` 归档回主 repo，移除 worktree + branch。
+
+### 主窗口职责（勿与 executor 重叠）
+
+1. delegate 前与用户 refine `需求.md` / `执行约束.md`
+2. `delegate` 返回后**不要**碰 `plan` 或 `implement` — 让 worktree 内 executor 跑
+3. 用 `status <task-id>` 与 worktree 内 `logs/workflow.log`、`logs/executor.jsonl` 观察进度
+4. task 报告 verify-passed 后，用 `git -C .worktrees/<task-id> log -p main..` 审 diff，再跑 `harvest`
+5. task 失败则**不要** harvest — 进入 worktree 排障并重跑 verify
+
+### 生命周期概览
+
+```
+delegate → executor 跑 spec/implement/verify → completed → harvest → archive + cleanup
+                                          ↘ failed   → worktree 内排障（不 harvest）
+```
+
+### 失败处理
+
+- `delegate` fail-fast：任何 source/conflict 错误在创建 worktree 前 abort
+- `harvest` 拒绝 failed/active task；merge conflict 时打印 conflict 文件（手动解决后重跑）
+- `worktree list` 只读；从任意窗口运行都不影响 in-flight delegate
+
+### 与 Agent DAG 的关系
+
+Agent DAG 是默认 autonomous path；`delegate`/`harvest` 是 cursor-direct 的 worktree escape hatch。多 task 并行时，每个 task 独立 `delegate`，完成后分别 `harvest`。
+
+详见 `docs/cursor-executor-usage.md` 与 `docs/loop-agent-harness.md`。

package/skills/loop-agent/references/one-shot-runs.md

@@ -1,85 +1,85 @@
-# One-shot Run Evidence（`.harness/runs/`）
-
-当你使用 `cursor-prompt`、Pi `cursor` tool、`promote-run`，或在治理检查中看到 `.harness/runs/active` warning 时，读本文。
-
-## 目录职责
-
-`.harness/runs/` 保存一次性工具调用的运行证据。它不是 task 状态源，也不是 Agent DAG run 目录。
-
-```text
-.harness/runs/active/<run-id>/      # 正在执行或异常残留的 one-shot tool run
-.harness/runs/completed/<run-id>/   # 成功完成的 one-shot run evidence
-.harness/runs/failed/<run-id>/      # 失败的 one-shot run evidence
-```
-
-每个 run directory 通常包含：
-
-```text
-run.md
-meta.json
-artifacts/
-```
-
-`run.md` 是人类可读摘要；`meta.json` 是机器可读 run metadata；`artifacts/` 是该次 one-shot 的交付物目录。
-
-## 什么时候创建
-
-会创建 `.harness/runs/` 的常见入口：
-
-- `loop-agent cursor-prompt ...`
-- Pi `cursor` tool / loop-agent cursor tool 的 one-shot Cursor 调用
-- 内部 two-phase one-shot logging：先 `createActiveCursorRun()`，再 `finalizeCursorRunLog()`
-
-创建条件：
-
-- 调用的 `cwd` 必须是含 `.harness/` 的 harness repo。
-- `cursor-prompt` 会先创建 `.harness/runs/active/<run-id>/`，再把结果归档。
-- 成功时整个目录移动到 `.harness/runs/completed/<run-id>/`。
-- 失败、timeout 或 cancel 时整个目录移动到 `.harness/runs/failed/<run-id>/`。
-
-当前 `pi-prompt` 不创建 `.harness/runs/`。它是 one-shot helper，但不维护 run evidence、task state、verification 或 handoff artifact。
-
-## 与 task / DAG 的关系
-
-| 目录 | 含义 | 是否代表 task 完成 |
-|---|---|---|
-| `.harness/tasks/<task-id>/` | task 运行态状态源 | 是 task 状态源 |
-| `.harness/runs/<state>/<run-id>/` | one-shot tool run evidence | 否，只是一次执行证据 |
-| `.harness/dag-runs/<state>/<run-id>/` | Agent DAG run facts | 否，只是 DAG run facts |
-
-completed one-shot evidence 若要进入 task artifacts，使用：
-
-```bash
-loop-agent promote-run <task-id> --run-id <run-id>
-loop-agent closeout task <task-id>
-```
-
-`promote-run` 只读 `.harness/runs/completed/**`，生成或更新 task `artifacts/修改记录.md` / `artifacts/验证结果.md`，不修改 completed run facts。
-
-## Active 目录清理
-
-`.harness/runs/active/` 只应存在 live one-shot run。治理检查发现 active 内容时会 warning：
-
-```text
-[HARNESS RUNTIME WARNING] .harness/runs/active contains runtime entries
-```
-
-处理规则：
-
-- 如果确有 one-shot 正在执行，可以保留；必要时用 `HARNESS_ALLOW_ACTIVE_TOOL_RUNS=1` 跑治理检查。
-- 如果是已完成、失败或中断残留，应移动到 `completed/` / `failed/`，或在确认无价值后删除。
-- 如果是 `.DS_Store` 等系统垃圾文件，直接删除；它不是合法 run evidence。
-- 不要把 active 残留当作 task 完成证据。
-
-严格检查可用：
-
-```bash
-HARNESS_STRICT_ACTIVE_TOOL_RUNS=1 bash scripts/check-harness-runtime-clean.sh
-```
-
-## 不要做什么
-
-- 不要提交 `.harness/runs/**` 运行态内容。
-- 不要手动改写 `.harness/runs/completed/**` 或 `.harness/runs/failed/**` 事实。
-- 不要把 `.harness/runs/active/**` 当作长期记录。
-- 不要把 one-shot evidence 直接等同于 task artifacts；需要汇总时用 `promote-run`。
+# One-shot Run Evidence（`.harness/runs/`）
+
+当你使用 `cursor-prompt`、Pi `cursor` tool、`promote-run`，或在治理检查中看到 `.harness/runs/active` warning 时，读本文。
+
+## 目录职责
+
+`.harness/runs/` 保存一次性工具调用的运行证据。它不是 task 状态源，也不是 Agent DAG run 目录。
+
+```text
+.harness/runs/active/<run-id>/      # 正在执行或异常残留的 one-shot tool run
+.harness/runs/completed/<run-id>/   # 成功完成的 one-shot run evidence
+.harness/runs/failed/<run-id>/      # 失败的 one-shot run evidence
+```
+
+每个 run directory 通常包含：
+
+```text
+run.md
+meta.json
+artifacts/
+```
+
+`run.md` 是人类可读摘要；`meta.json` 是机器可读 run metadata；`artifacts/` 是该次 one-shot 的交付物目录。
+
+## 什么时候创建
+
+会创建 `.harness/runs/` 的常见入口：
+
+- `loop-agent cursor-prompt ...`
+- Pi `cursor` tool / loop-agent cursor tool 的 one-shot Cursor 调用
+- 内部 two-phase one-shot logging：先 `createActiveCursorRun()`，再 `finalizeCursorRunLog()`
+
+创建条件：
+
+- 调用的 `cwd` 必须是含 `.harness/` 的 harness repo。
+- `cursor-prompt` 会先创建 `.harness/runs/active/<run-id>/`，再把结果归档。
+- 成功时整个目录移动到 `.harness/runs/completed/<run-id>/`。
+- 失败、timeout 或 cancel 时整个目录移动到 `.harness/runs/failed/<run-id>/`。
+
+当前 `pi-prompt` 不创建 `.harness/runs/`。它是 one-shot helper，但不维护 run evidence、task state、verification 或 handoff artifact。
+
+## 与 task / DAG 的关系
+
+| 目录 | 含义 | 是否代表 task 完成 |
+|---|---|---|
+| `.harness/tasks/<task-id>/` | task 运行态状态源 | 是 task 状态源 |
+| `.harness/runs/<state>/<run-id>/` | one-shot tool run evidence | 否，只是一次执行证据 |
+| `.harness/dag-runs/<state>/<run-id>/` | Agent DAG run facts | 否，只是 DAG run facts |
+
+completed one-shot evidence 若要进入 task artifacts，使用：
+
+```bash
+loop-agent promote-run <task-id> --run-id <run-id>
+loop-agent closeout task <task-id>
+```
+
+`promote-run` 只读 `.harness/runs/completed/**`，生成或更新 task `artifacts/修改记录.md` / `artifacts/验证结果.md`，不修改 completed run facts。
+
+## Active 目录清理
+
+`.harness/runs/active/` 只应存在 live one-shot run。治理检查发现 active 内容时会 warning：
+
+```text
+[HARNESS RUNTIME WARNING] .harness/runs/active contains runtime entries
+```
+
+处理规则：
+
+- 如果确有 one-shot 正在执行，可以保留；必要时用 `HARNESS_ALLOW_ACTIVE_TOOL_RUNS=1` 跑治理检查。
+- 如果是已完成、失败或中断残留，应移动到 `completed/` / `failed/`，或在确认无价值后删除。
+- 如果是 `.DS_Store` 等系统垃圾文件，直接删除；它不是合法 run evidence。
+- 不要把 active 残留当作 task 完成证据。
+
+严格检查可用：
+
+```bash
+HARNESS_STRICT_ACTIVE_TOOL_RUNS=1 bash scripts/check-harness-runtime-clean.sh
+```
+
+## 不要做什么
+
+- 不要提交 `.harness/runs/**` 运行态内容。
+- 不要手动改写 `.harness/runs/completed/**` 或 `.harness/runs/failed/**` 事实。
+- 不要把 `.harness/runs/active/**` 当作长期记录。
+- 不要把 one-shot evidence 直接等同于 task artifacts；需要汇总时用 `promote-run`。