@tea-agent/loop-agent 0.2.0 → 0.2.1

package/package.json

@@ -1,62 +1,62 @@
-{
-  "name": "@tea-agent/loop-agent",
-  "version": "0.2.0",
-  "type": "module",
-  "bin": {
-    "loop-agent": "bin/loop-agent.js"
-  },
-  "files": [
-    "AGENTS.md",
-    "bin/",
-    "dist/",
-    "docs/*.md",
-    "docs/architecture/runtime-boundaries.md",
-    "docs/decisions/README.md",
-    "docs/design/README.md",
-    "docs/exec-plans/README.md",
-    "docs/exec-plans/active/README.md",
-    "docs/exec-plans/completed/README.md",
-    "docs/progress/README.md",
-    "docs/reports/README.md",
-    "docs/templates/",
-    "examples/",
-    "harness.json",
-    "skills/",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "dev": "node --import tsx/esm src/cli.ts",
-    "cursor": "node --import tsx/esm src/cli.ts cursor-prompt",
-    "pi-prompt": "node --import tsx/esm src/cli.ts pi-prompt",
-    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && tsc -p tsconfig.build.json",
-    "prepack": "npm run build",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build",
-    "lint": "tsc --noEmit",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "docs:dev": "npm --prefix website start",
-    "docs:build": "npm --prefix website run build",
-    "docs:serve": "npm --prefix website run serve",
-    "smoke:stale-serial": "tsx scripts/smoke-stale-plan-serial.ts"
-  },
-  "dependencies": {
-    "commander": "^12.1.0",
-    "zod": "^3.25.76"
-  },
-  "optionalDependencies": {
-    "@cursor/sdk": "^1.0.7",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-ai": "*"
-  },
-  "devDependencies": {
-    "tsx": "^4.20.6",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4",
-    "@types/node": "^24.6.0"
-  }
-}
+{
+  "name": "@tea-agent/loop-agent",
+  "version": "0.2.1",
+  "type": "module",
+  "bin": {
+    "loop-agent": "bin/loop-agent.js"
+  },
+  "files": [
+    "AGENTS.md",
+    "bin/",
+    "dist/",
+    "docs/*.md",
+    "docs/architecture/runtime-boundaries.md",
+    "docs/decisions/README.md",
+    "docs/design/README.md",
+    "docs/exec-plans/README.md",
+    "docs/exec-plans/active/README.md",
+    "docs/exec-plans/completed/README.md",
+    "docs/progress/README.md",
+    "docs/reports/README.md",
+    "docs/templates/",
+    "examples/",
+    "harness.json",
+    "skills/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "node --import tsx/esm src/cli.ts",
+    "cursor": "node --import tsx/esm src/cli.ts cursor-prompt",
+    "pi-prompt": "node --import tsx/esm src/cli.ts pi-prompt",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "docs:dev": "npm --prefix website start",
+    "docs:build": "npm --prefix website run build",
+    "docs:serve": "npm --prefix website run serve",
+    "smoke:stale-serial": "tsx scripts/smoke-stale-plan-serial.ts"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "zod": "^3.25.76"
+  },
+  "optionalDependencies": {
+    "@cursor/sdk": "^1.0.7",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*"
+  },
+  "devDependencies": {
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@types/node": "^24.6.0"
+  }
+}

package/skills/loop-agent/SKILL.md

@@ -60,38 +60,38 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
 
 短时规划、审查、失败归因可使用 full-capability `pi-prompt`，默认模型是 `glm-5.2`：
 
-- 只读 sidecar 必须显式传 `--tools read,grep,find,ls`，并在 prompt 中写明不编辑文件。
-- 高复杂度 one-shot 诊断可显式加 `--model gpt-5.5`。
-- 输出是 advisory，不能替代 deterministic verification；发现必须写回 task source、report、progress 或 exec plan。
-
-## Bounded Write Execution
-
-需要写代码时，默认使用 DAG `pi` executor 的 write tool profile。Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证，并在执行后由主会话独立运行 shell verification。
-
-Cursor 只作为显式启用的可选 bounded write backend。调用示例与细节见 `references/pi-prompt.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
-
-Pi writer prompt 与 Cursor prompt 都必须包含：
+- 只读 sidecar 必须显式传 `--tools read,grep,find,ls`，并在 prompt 中写明不编辑文件。
+- 高复杂度 one-shot 诊断可显式加 `--model gpt-5.5`。
+- 输出是 advisory，不能替代 deterministic verification；发现必须写回 task source、report、progress 或 exec plan。
+
+## Bounded Write Execution
+
+需要写代码时，默认使用 DAG `pi` executor 的 write tool profile。Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证，并在执行后由主会话独立运行 shell verification。
+
+Cursor 只作为显式启用的可选 bounded write backend。调用示例与细节见 `references/pi-prompt.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
+
+Pi writer prompt 与 Cursor prompt 都必须包含：
 
 - task id
 - exact objective
 - allowed paths
 - forbidden paths
-- hard constraints
-- expected verification
-- instruction to preserve unrelated files
-
-bounded writer 完成后，主会话必须独立复核；命令清单见 `references/verification-and-failure-handling.md` 的 "Cursor bounded write 后的独立复核"。
+- hard constraints
+- expected verification
+- instruction to preserve unrelated files
+
+bounded writer 完成后，主会话必须独立复核；命令清单见 `references/verification-and-failure-handling.md` 的 "Cursor bounded write 后的独立复核"。
 
 ## 进阶主题路由
 
-以下主题只在 references 中维护细节，不在本文展开：
-
-| 主题 | Reference |
-|---|---|
-| Long-Running Loop（`loop` init/status/run/record-round/add-signal/closeout、auto mode、signals） | `references/long-running-loop.md` |
-| Three-Pass Convergence、repair artifact、spine audit、knowledge curate、SePO-lite prompt evolution | `references/harness-policy.md` |
-| Operator commands（status/doctor/report/closeout/promote/inspect/spine/knowledge/docs/handoff） | `references/command-reference.md` |
-| Post-Cursor 独立验证、verify knobs、failure handling、closeout | `references/verification-and-failure-handling.md` |
+以下主题只在 references 中维护细节，不在本文展开：
+
+| 主题 | Reference |
+|---|---|
+| Long-Running Loop（`loop` init/status/run/record-round/add-signal/closeout、auto mode、signals） | `references/long-running-loop.md` |
+| Three-Pass Convergence、repair artifact、spine audit、knowledge curate、SePO-lite prompt evolution | `references/harness-policy.md` |
+| Operator commands（status/doctor/report/closeout/promote/inspect/spine/knowledge/docs/handoff） | `references/command-reference.md` |
+| Post-Cursor 独立验证、verify knobs、failure handling、closeout | `references/verification-and-failure-handling.md` |
 
 ## Source Layout
 
@@ -111,17 +111,17 @@ bounded writer 完成后，主会话必须独立复核；命令清单见 `refere
 
 不要新增平行兼容入口。CLI public export 的唯一入口是 `src/cli/index.ts`；commander command tree 和 help 实现在 `src/cli/program.ts`。
 
-## Hard Rules
-
-1. One task = one bounded work chunk.
-2. Source materials are mandatory: `source/需求.md` and `source/执行约束.md`.
-3. Agent DAG is the implementation workflow.
-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 and optional Cursor write execution must be bounded by explicit allowed / forbidden paths.
-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.
+## Hard Rules
+
+1. One task = one bounded work chunk.
+2. Source materials are mandatory: `source/需求.md` and `source/执行约束.md`.
+3. Agent DAG is the implementation workflow.
+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 and optional Cursor write execution must be bounded by explicit allowed / forbidden paths.
+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.
 
 ## References
 

package/skills/loop-agent/references/command-reference.md

@@ -2,52 +2,52 @@
 
 需要 loop-agent 的精确 CLI 命令、setup 命令、task lifecycle 命令、docs helper、goal 命令或 stats 时使用本文。
 
-## loop-agent 入口
-
-**优先在目标 repo 目录内执行命令** — loop-agent 通过 `harness.json.project` 自动检测使用哪个 repo adapter。跨目录操作时显式加 `--repo-root <target-repo>`。
-
-默认使用全局 CLI：
-
-```bash
-loop-agent <command> ...
-```
-
-面向自举迭代和日常使用时，全局 CLI 应来自 npm 上已发布的安装包。首次安装或有意升级使用 `@latest`：
-
-```bash
-npm install -g @tea-agent/loop-agent@latest
-npm list -g @tea-agent/loop-agent --depth=0
-loop-agent doctor
-```
-
-一次自举任务启动后不要中途升级控制器；记录 `npm list -g` 显示的实际版本。不要在 DAG 节点中反复用 `npx @latest` 拉取，也不要使用当前工作区的 `npm link` 或 `npm run dev` 作为控制器去修改 loop-agent 本仓库的 CLI、DAG runtime、executor、package metadata 或 build output。`npm run dev -- <command> ...` 只用于源码调试和聚焦 CLI 开发。
-
-发布包入口加载 `dist/cli.js`；开发入口加载 `src/cli.ts`。
-
-发布包携带静态能力资料：`skills/`、`docs/*.md`、`docs/templates/` 和 `examples/`。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 的任务正文属于目标仓库运行中生成的事实，不从 npm 包复制；包内只保留这些目录的 README 说明。
-
-## 命令参考
+## loop-agent 入口
+
+**优先在目标 repo 目录内执行命令** — loop-agent 通过 `harness.json.project` 自动检测使用哪个 repo adapter。跨目录操作时显式加 `--repo-root <target-repo>`。
+
+默认使用全局 CLI：
+
+```bash
+loop-agent <command> ...
+```
+
+面向自举迭代和日常使用时，全局 CLI 应来自 npm 上已发布的安装包。首次安装或有意升级使用 `@latest`：
+
+```bash
+npm install -g @tea-agent/loop-agent@latest
+npm list -g @tea-agent/loop-agent --depth=0
+loop-agent doctor
+```
+
+一次自举任务启动后不要中途升级控制器；记录 `npm list -g` 显示的实际版本。不要在 DAG 节点中反复用 `npx @latest` 拉取，也不要使用当前工作区的 `npm link` 或 `npm run dev` 作为控制器去修改 loop-agent 本仓库的 CLI、DAG runtime、executor、package metadata 或 build output。`npm run dev -- <command> ...` 只用于源码调试和聚焦 CLI 开发。
+
+发布包入口加载 `dist/cli.js`；开发入口加载 `src/cli.ts`。
+
+发布包携带静态能力资料：`skills/`、`docs/*.md`、`docs/templates/` 和 `examples/`。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 的任务正文属于目标仓库运行中生成的事实，不从 npm 包复制；包内只保留这些目录的 README 说明。
+
+## 命令参考
 
 ## 默认选择模型
 
 选择命令时按以下优先级：
 
-1. **主路径 DAG**，用于常规 autonomous work：
-   ```bash
-   loop-agent new-task <task-id> "Task Title"
-   loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-   loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-   loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
-   ```
-   `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
-2. **Operator 工具**，用于 recovery、诊断与 closeout：
-   ```bash
+1. **主路径 DAG**，用于常规 autonomous work：
+   ```bash
+   loop-agent new-task <task-id> "Task Title"
+   loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+   loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+   loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
+   ```
+   `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
+2. **Operator 工具**，用于 recovery、诊断与 closeout：
+   ```bash
    loop-agent dag status --run-id <run-id>
    loop-agent dag doctor
    loop-agent dag report --latest --markdown
    loop-agent dag closeout-draft --run-id <run-id>
    loop-agent dag reconcile-tasks --glob '<pattern>' --markdown
-   loop-agent dag final-verification <task-id> --output <temp-dir>/<task-id>-final-verification-dag.json
+   loop-agent dag final-verification <task-id> --output <temp-dir>/<task-id>-final-verification-dag.json
    loop-agent status <task-id> --json
    loop-agent instructions task-artifacts --task <task-id> --json
    loop-agent promote-run <task-id> --run-id <run-id>
@@ -60,14 +60,15 @@ loop-agent doctor
    ```bash
    loop-agent delegate <task-id> --executor cursor
    loop-agent harvest <task-id>
+   loop-agent cursor-prompt --cwd <repo-root> --file /tmp/bounded-task.md
    loop-agent pi-prompt "Reply with exactly OK."
    ```
 
-### Setup（首次）
-```bash
-npm install -g @tea-agent/loop-agent@latest
-loop-agent --help
-```
+### Setup（首次）
+```bash
+npm install -g @tea-agent/loop-agent@latest
+loop-agent --help
+```
 
 ### 检查 repo harness
 ```bash
@@ -141,9 +142,9 @@ loop-agent --repo-root /path/to/target-repo study init <task-id> "Title" \
   --reference-glob "codex-rs/**/goal*.rs"
 
 # 编辑 source/需求.md + source/执行约束.md，然后走 DAG 路径：
-loop-agent --repo-root <target-repo> dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent --repo-root <target-repo> dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent --repo-root <target-repo> run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <target-repo>
+loop-agent --repo-root <target-repo> dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent --repo-root <target-repo> dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent --repo-root <target-repo> run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <target-repo>
 ```
 
 目标 repo 需有 `.harness/prompts/feature-study-analyze.md` 与 `feature-study-plan.md`（缺失时从 loop-agent 复制）。
@@ -152,6 +153,13 @@ loop-agent --repo-root <target-repo> run-dag --dag <temp-dir>/<task-id>-dag.json
 
 历史顺序式 `run analyze|plan|spec|implement|verify|retrospective|auto|loop|continue|study` 已移除。新任务不要使用这些命令，也不要在 prompt、skill 或 docs 中把它们描述为 fallback。
 
+### Reference helpers（compatibility）
+```bash
+loop-agent reference index
+```
+
+`reference` 是 compatibility / feature-study 辅助入口，用于维护或检查参考资料索引。常规实现任务不要从 `reference` 起步；按 `new-task` + DAG 路径执行。
+
 ### Task goal lifecycle（compatibility-only / deprecated-candidate）
 ```bash
 loop-agent goal set <task-id> "Objective text" [--token-budget <number|null>]
@@ -176,17 +184,17 @@ loop-agent goal clear <task-id>
 
 ### Agent DAG validation 与 execution
 ```bash
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json                 # 常规 validation；无 .harness/dag-runs 副作用
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-models # 非 canonical executorModels 时失败
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance # governance warning 时失败
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance --spine-task <task-id> # 同时消费 minimal spec spine audit
-loop-agent dag validate --dag docs/templates/agent-dag.supervised-implementation.json --strict-models --strict-governance  # role=supervisor + write-set-gate topology
-cp docs/templates/agent-dag.supervised-implementation.json <temp-dir>/supervised-dag.json
-(npx vitest run test/dag-supervised-template.test.ts test/dag-validate.test.ts test/dag-shell-executor.test.ts --reporter=dot)  # supervised template + shell.verdictGate runtime
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --forbid-executor cursor # 存在 cursor node 时失败
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Agent DAG
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> --no-cursor # 执行前若存在 cursor node 则失败
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas view
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json                 # 常规 validation；无 .harness/dag-runs 副作用
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-models # 非 canonical executorModels 时失败
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance # governance warning 时失败
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance --spine-task <task-id> # 同时消费 minimal spec spine audit
+loop-agent dag validate --dag docs/templates/agent-dag.supervised-implementation.json --strict-models --strict-governance  # role=supervisor + write-set-gate topology
+cp docs/templates/agent-dag.supervised-implementation.json <temp-dir>/supervised-dag.json
+(npx vitest run test/dag-supervised-template.test.ts test/dag-validate.test.ts test/dag-shell-executor.test.ts --reporter=dot)  # supervised template + shell.verdictGate runtime
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --forbid-executor cursor # 存在 cursor node 时失败
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Agent DAG
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> --no-cursor # 执行前若存在 cursor node 则失败
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas view
 loop-agent dag init-hybrid <task-id>                     # 生成可审阅的 DAG draft
 loop-agent dag run-task <task-id>                        # generate + validate（安全默认；无 dag-runs；standard-compatible）
 loop-agent dag run-task <task-id> --profile auto         # 推断 governanceProfile，经 workflowPolicy.dag.profileRouting 路由
@@ -213,9 +221,9 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 **In-flight DAG governance**：shell verify node 内用 `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`；run 归档到 `completed/` 后，在 DAG 外跑裸 `bash scripts/check-repo.sh`。
 
 - `dag validate` 做 schema/topology/ranks 检查；审 `warnings` 中的显式 `executorModels` drift 与 governance lint。
-- 手写临时 DAG spec 执行前用 `dag validate --strict-models`，model-matrix drift 应 fail fast。
+- 手写临时 DAG spec 执行前用 `dag validate --strict-models`，model-matrix drift 应 fail fast。
 - read-only artifact-boundary 或 DAG 内 shell governance warning 应 fail fast 时用 `dag validate --strict-governance`。
-- 人工 handoff 视图用 `dag report --markdown`（summary、node timeline、failures、四段 Recovery Plan、artifacts、建议 next action）。仅 derived、advisory；需保存时重定向到平台临时目录或 `docs/reports/`。
+- 人工 handoff 视图用 `dag report --markdown`（summary、node timeline、failures、四段 Recovery Plan、artifacts、建议 next action）。仅 derived、advisory；需保存时重定向到平台临时目录或 `docs/reports/`。
 - operator 聚焦最新 paused run 用 `dag report --paused-latest`（等同 `--lifecycle paused --latest`；勿与显式 `--lifecycle` 并用）。
 - 需 operator 关注的 run 用 `dag report --failed-only`、`--latest`、`--action <recovery-action>` 收窄。category→action 映射见 `docs/agent-dag-recovery-playbook.md`。
 - 只读扫描 `.harness/dag-runs/` 下所有 run 的生命周期 health issue 与建议 action 用 `dag doctor`（`advisoryOnly: true`；不 mutate facts）。
@@ -227,6 +235,18 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 - 仅当有意在 `.harness/dag-runs/active/` 下要 active run snapshot 时用 `run-dag --dry-run`。
 - task source 应从 `harness.json.workflowPolicy.dag.profileRouting` 与确定性 candidate `governanceProfile` 选 standard / review-gated / supervised template 时用 `dag run-task --profile auto`。无 `--profile` 仅用于旧 standard-compatible 输出；强制 template family 用 `--profile minimal|standard|reviewed|supervised`。
 
+### Saved Dynamic Workflow operator UX
+```bash
+loop-agent workflow list
+loop-agent workflow inspect <name>
+loop-agent workflow save --from /tmp/<task-id>.workflow.json --name <name>
+loop-agent workflow run <name-or-path> --cwd <repo-root>
+loop-agent workflow diff <name> --against /tmp/<task-id>.workflow.json
+loop-agent workflow replay <run-id>
+```
+
+`workflow` 是 Dynamic Workflow 的 saved/operator surface。它读取 `WorkflowSpec`，编译为 DAG，再进入同一套 `run-dag` runtime；不会新增 executor 能力或绕过 DAG governance。真实写入任务仍应检查 compiled DAG 的 executor、writeSet、shell gates 和 completed facts 边界。
+
 ### Cursor worker lifecycle
 ```bash
 loop-agent cursor-worker status   # enabled/running/child/entry path
@@ -259,14 +279,14 @@ loop-agent handoff coverage <task-id> [--json|--markdown]
 
 ### Pi runtime reuse benchmark / decision（无 live call）
 ```bash
-loop-agent pi-reuse-benchmark \
-  --report docs/reports/<benchmark-report>.md \
-  --json
-
-loop-agent pi-reuse-benchmark \
-  --report docs/reports/<benchmark-report>.md \
-  --off-executor /path/to/off/executor.jsonl \
-  --on-executor /path/to/on/executor.jsonl \
+loop-agent pi-reuse-benchmark \
+  --report docs/reports/<benchmark-report>.md \
+  --json
+
+loop-agent pi-reuse-benchmark \
+  --report docs/reports/<benchmark-report>.md \
+  --off-executor /path/to/off/executor.jsonl \
+  --on-executor /path/to/on/executor.jsonl \
   --approval /path/to/approval.json \
   --markdown
 ```
@@ -281,6 +301,19 @@ loop-agent loop-benchmark --markdown --output docs/reports/2026-06-30-loop-agent
 
 生成 M0 deterministic baseline，对照 `single-repair`、`3-pass-convergence`、`3-pass-convergence+quota`。**不**跑 live Pi/Cursor call、不创建 task、不改 `convergence.enabled` 默认值。live dogfood 证据缺失时输出 `blocked` 并建议保持 opt-in。
 
+### Long-running loop outer state（experimental）
+```bash
+loop-agent loop init <task-id>
+loop-agent loop status <task-id>
+loop-agent loop run <task-id> --action dag
+loop-agent loop run <task-id> --action shell-verify --command "bash scripts/check-repo.sh"
+loop-agent loop record-round <task-id> --decision continue --summary "..."
+loop-agent loop add-signal <task-id> --kind note --message "..."
+loop-agent loop closeout <task-id>
+```
+
+`loop` 是 Agent DAG 之上的长程状态和 evidence layer，记录 rounds、signals、verification summaries 和 closeout draft。它不是替代 `dag run-task` / `run-dag` 的实现路径；medium/large work 仍需要 DAG evidence 或明确 fallback reason。
+
 ### Minimal spec spine audit
 ```bash
 loop-agent spine audit <task-id> --json
@@ -312,4 +345,13 @@ loop-agent worktree create|list|remove ...
 
 用于 worktree 隔离的 cursor-direct 执行与 merge 收口。常规 autonomous work 应优先 Agent DAG；详见 `multi-worktree.md` 与 `docs/cursor-executor-usage.md`。
 
+### One-shot Cursor sidecar（escape hatch）
+```bash
+loop-agent cursor-prompt --cwd <repo-root> "Review this task without editing files."
+loop-agent cursor-prompt --cwd <repo-root> --file /tmp/bounded-cursor-task.md
+loop-agent cursor-prompt --cwd <repo-root> --model composer-2.5 --timeout 1800000 --file /tmp/bounded-cursor-task.md
+```
+
+`cursor-prompt` 是 one-shot Cursor SDK helper。用于 bounded diagnosis、小修复或调试 executor；写入 prompt 必须包含 task id、objective、allowed paths、forbidden paths、verification 和 preserve-unrelated-changes 要求。需要 `CURSOR_API_KEY`。它会创建 one-shot run evidence，但 Cursor 自报成功不替代 shell verification。
+
 > **Historical（已移除）**：`subagent list|start|wait|wakeup|attach|stop` 与 `dashboard` 已移除，不再出现在 CLI registry。

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

@@ -8,7 +8,7 @@
 - 历史顺序式 `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。
-- **Executors** 实现 bounded work：Pi 在 DAG nodes 做 read-only planning/review/diagnosis，并在节点声明 `toolProfile: "write"` 时做 bounded implementation/repair；Cursor 是显式启用的可选 bounded writer；shell 产出 deterministic verification facts。
+- **Executors** 实现 bounded work：Pi 在 DAG nodes 做 read-only planning/review/diagnosis，并在节点声明 `toolProfile: "write"` 时做 bounded implementation/repair；Cursor 是显式启用的可选 bounded writer；shell 产出 deterministic verification facts。
 - **Shell verification 是 completion fact source**。LLM review 或 advisory output 不能替代 command exit codes 与 archived evidence。
 
 ## Command surface tiers
@@ -33,13 +33,13 @@ Is this only status, diagnosis, recovery, or closeout?
            yes -> Agent DAG.
 ```
 
-在以下任一 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.
-- The change needs multiple files, multiple scouts, review gates, Decision Gate, repair flow, or shell gate.
-- `writeSet` is broad, multiple exclusive writers exist, or public interfaces / architecture boundaries change.
-- Requirement, architecture, credential, cost, deployment, security, or authority surface is unclear.
-- A failure repeats and needs recovery planning rather than blind retry.
+在以下任一 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.
+- The change needs multiple files, multiple scouts, review gates, Decision Gate, repair flow, or shell gate.
+- `writeSet` is broad, multiple exclusive writers exist, or public interfaces / architecture boundaries change.
+- Requirement, architecture, credential, cost, deployment, security, or authority surface is unclear.
+- A failure repeats and needs recovery planning rather than blind retry.
 
 ## Agent DAG path
 
@@ -61,18 +61,18 @@ loop-agent dag validate \
   --strict-models \
   --strict-governance
 
-loop-agent run-dag \
-  --dag <temp-dir>/<task-id>-dag.json \
-  --cwd <target-repo>
-```
-
-`loop-agent` is the preferred global CLI. For self-hosting loop-agent development, the controller must be an installed npm-published package. Use `npm install -g @tea-agent/loop-agent@latest` for first install or intentional upgrades, then treat the installed version as frozen for the current task and record `npm list -g @tea-agent/loop-agent --depth=0`. Do not repeatedly fetch `npx @latest` inside DAG nodes, and do not use the current working tree's `npm link` or `npm run dev` to control tasks that may edit CLI, DAG runtime, executors, package metadata, or build output. Use `npm run dev -- <args>` only for source debugging and focused CLI development.
-
-The npm package carries static capability assets: `skills/`, top-level governance docs, `docs/templates/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`. Generated or historical task facts under `docs/progress/`, `docs/reports/`, `docs/exec-plans/`, and `docs/decisions/` belong to the target repository; package only their directory README files, not prior run content.
+loop-agent run-dag \
+  --dag <temp-dir>/<task-id>-dag.json \
+  --cwd <target-repo>
+```
+
+`loop-agent` is the preferred global CLI. For self-hosting loop-agent development, the controller must be an installed npm-published package. Use `npm install -g @tea-agent/loop-agent@latest` for first install or intentional upgrades, then treat the installed version as frozen for the current task and record `npm list -g @tea-agent/loop-agent --depth=0`. Do not repeatedly fetch `npx @latest` inside DAG nodes, and do not use the current working tree's `npm link` or `npm run dev` to control tasks that may edit CLI, DAG runtime, executors, package metadata, or build output. Use `npm run dev -- <args>` only for source debugging and focused CLI development.
 
-For arbitrary target repositories, DAG skill instructions must not depend on loop-agent source history being copied into the target repo. Resolve configured, user, or target-local skills when present, then fall back to package-bundled `skills/` as the stable default capability set.
-
-`<temp-dir>` means the platform-native temp directory. Use native paths for actual `--output`, `--dag`, and `--cwd` values on macOS and Windows; use `/` only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.
+The npm package carries static capability assets: `skills/`, top-level governance docs, `docs/templates/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`. Generated or historical task facts under `docs/progress/`, `docs/reports/`, `docs/exec-plans/`, and `docs/decisions/` belong to the target repository; package only their directory README files, not prior run content.
+
+For arbitrary target repositories, DAG skill instructions must not depend on loop-agent source history being copied into the target repo. Resolve configured, user, or target-local skills when present, then fall back to package-bundled `skills/` as the stable default capability set.
+
+`<temp-dir>` means the platform-native temp directory. Use native paths for actual `--output`, `--dag`, and `--cwd` values on macOS and Windows; use `/` only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.
 
 Execution 前 review `dag run-task` JSON / `reviewPacket`：
 
@@ -168,12 +168,12 @@ Rules:
 - `dag report --json` 与 markdown 须 expose `convergence.passHistory`。
 - Final completion authority 仍是 full shell verification；quota/focused commands 仅为 intermediate cost controls。
 
-## Structured repair, spine audit, and curator gates
-
-- `shell.repairArtifactGate.fromNodeId` validates the upstream supervisor artifact before repair. Missing/invalid JSON, missing request-revision `fixScope`, or scope outside the downstream repair writer allowedPaths/writeSet fails closed.
-- `spine audit <task-id>` is the deterministic minimal spec spine checker for task source, ownership paths, requirement coverage, and final verification commands.
-- `dag validate --strict-governance --spine-task <task-id>` may consume the same spine audit as part of strict validation.
-- `knowledge curate` reads completed convergence patterns and writes only human-gated proposal Markdown after skill safety preflight.
+## Structured repair, spine audit, and curator gates
+
+- `shell.repairArtifactGate.fromNodeId` validates the upstream supervisor artifact before repair. Missing/invalid JSON, missing request-revision `fixScope`, or scope outside the downstream repair writer allowedPaths/writeSet fails closed.
+- `spine audit <task-id>` is the deterministic minimal spec spine checker for task source, ownership paths, requirement coverage, and final verification commands.
+- `dag validate --strict-governance --spine-task <task-id>` may consume the same spine audit as part of strict validation.
+- `knowledge curate` reads completed convergence patterns and writes only human-gated proposal Markdown after skill safety preflight.
 
 ## SePO-lite prompt evolution
 
@@ -213,11 +213,11 @@ Sidecar output 为 advisory。若须成为 task evidence，通过 loop-agent run
 
 - Agent DAG 用 DAG JSON `executorModels` 加 node `executor` / `complexity`；不要从 repo `harness.json.models` 推断 DAG models。
 - DAG `shell` 与 `static` nodes 不用 models。
-- `harness.json.models.<step>` 下 historical step models 是 legacy metadata，不是新 DAG work 的 routing。
-- `pi-prompt` / `cursor-prompt` models 来自 CLI flags 或 runtime defaults，须 per intervention 选择。
-- Pi DAG nodes 默认 read-only planning/review/diagnosis；声明 `toolProfile: "write"` 时是 bounded writers，须有 explicit write scope。
-- Cursor nodes 是显式启用的可选 bounded writers，须有 explicit write scope。
-- Shell nodes 产出 deterministic verification facts 与 gates。
+- `harness.json.models.<step>` 下 historical step models 是 legacy metadata，不是新 DAG work 的 routing。
+- `pi-prompt` / `cursor-prompt` models 来自 CLI flags 或 runtime defaults，须 per intervention 选择。
+- Pi DAG nodes 默认 read-only planning/review/diagnosis；声明 `toolProfile: "write"` 时是 bounded writers，须有 explicit write scope。
+- Cursor nodes 是显式启用的可选 bounded writers，须有 explicit write scope。
+- Shell nodes 产出 deterministic verification facts 与 gates。
 
 ## Artifacts and facts boundary