@tea-agent/loop-agent 0.11.0 → 0.13.0-alpha.0

package/skills/frontend-implementation/SKILL.md

@@ -3,9 +3,9 @@ name: frontend-implementation
 description: >-
   Use for frontend contract, scout, plan, and implementation DAG nodes.
 references:
-  - path: references/node-contracts.md
-    required: true
-    maxChars: 3000
+  - path: references/node-contracts.md
+    required: true
+    maxChars: 3200
   - path: references/design-spec.md
     required: true
     maxChars: 3000
@@ -16,36 +16,39 @@ references:
 
 # Frontend Implementation
 
-Use for `frontend-contract-pi`, `frontend-scout-pi`, `frontend-plan-pi`, and
-`frontend-implement-pi`. Read every required reference before acting.
+For `frontend-contract-pi`, `frontend-scout-pi`, `frontend-plan-pi`, and
+`frontend-implement-pi`. Read all required references first.
 
 ## Source And Evidence Rules
 
-Use task source and references first, then constraints and `task.json`. Resolve
-component/design rules by the required sequence in `design-spec.md`: connect/query
-the knowledge base first; when it is not configured, connection/query fails, or no
-relevant result exists, search `<repoRoot>/openSpec/**` and treat matching rules as
-the current project's specification. Use other repository evidence only afterward.
+Use task sources/references, constraints, then `task.json`. Resolve design rules in
+`design-spec.md` order: query the knowledge base; if unavailable, failed, or empty,
+search `<repoRoot>/openSpec/**`; only then use other repository evidence.
+
+- Cite paths/symbols or tight lines; label assumptions, questions, and missing evidence.
+- Never invent conventions, APIs, tokens, commands, or knowledge-base results.
+- Record `knowledge-base`, `openSpec fallback`, `repository fallback`, or `unavailable`, plus evidence/conflicts.
+
+### Observable Spec Retrieval
 
-- Cite repository findings with paths and symbols or tight line ranges.
-- Label assumptions, unresolved questions, and unavailable evidence.
-- Never invent conventions, component APIs, tokens, commands, or knowledge-base results.
-- Record the selected source as `knowledge-base`, `openSpec fallback`, `repository fallback`, or `unavailable`, with evidence and conflicts.
+Scout/planner nodes must `grep`/`find` relevant `openSpec/**` and skill references,
+then explicitly `read` every consulted spec (`SKILL.md`, `design-spec.md`,
+`code-standards.md`, etc.). Observe derives evidence from session tool events: only
+successful paired `read` calls count as “已读取规范文件”; summaries do not. If the
+knowledge base is unavailable, record `openSpec/**` search hits before repo fallback.
 
 ## Implementation Discipline
 
-- Treat explicit project specs and repo-local skills as authoritative within their stated scope.
-- Reuse confirmed components, tokens, helpers, APIs, mocks, schemas, and test patterns.
-- Do not add dependencies unless the task allows them and the approved plan justifies them.
-- Cover applicable success, error, loading, empty, disabled, permission, and boundary states; mark non-applicable states with reasons.
-- Keep state and validation logic testable where project conventions support it.
-- Writer nodes stay inside `writeSet`, preserve unrelated behavior, and update tests with behavior.
-- Never relax lint/type/test/build configuration or write unauthorized generated output.
+- Project specs and repo-local skills are authoritative within scope.
+- Reuse confirmed components, tokens, helpers, APIs, mocks, schemas, and tests.
+- Add dependencies only when task and approved plan allow them.
+- Cover success/error/loading/empty/disabled/permission/boundary states; justify N/A.
+- Keep state/validation testable. Writers stay in `writeSet`, preserve unrelated behavior, and update tests.
+- Never relax lint/type/test/build config or write unauthorized generated output.
 
 ## Output And Failure Rules
 
-- Follow the node-specific headings in `node-contracts.md` exactly.
-- Read-only nodes return Markdown and never edit repository files.
-- Missing input blocks a node when proceeding would guess behavior, design compliance, write boundaries, or verification.
-- Keep protocol tokens, commands, paths, identifiers, and configured output language unchanged.
-- Implementation may report attempted checks, but completion requires fresh downstream shell evidence.
+- Follow `node-contracts.md` headings exactly. Read-only nodes return Markdown and never edit files.
+- Missing input blocks work when proceeding would guess behavior, compliance, write bounds, or verification.
+- Preserve protocol tokens, commands, paths, identifiers, and output language.
+- Attempted checks may be reported; completion needs fresh downstream shell evidence.

package/skills/frontend-implementation/references/node-contracts.md

@@ -1,32 +1,63 @@
 # Frontend Node Contracts
 
+Pre-implementation nodes are read-only. Preserve IDs, protocol tokens, source
+labels, language, and named output headings.
+
 ## `frontend-contract-pi`
 
-- Read task source, constraints, `task.json`, and explicit references; do not edit.
-- Define scope, non-goals, routes/components, runtime, user flows, acceptance criteria, states, risks, and verification expectations.
-- Preserve requirement IDs and language; never turn an implementation guess into a requirement.
-- For every standard UI state, specify behavior or mark it not applicable with a reason.
-- Output: `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`, `Risks`, `Verification Expectations`.
+Read task sources, constraints, config, and references. Define scope, non-goals,
+routes/components, runtime, flows, criteria, states, risks, and verification. Never
+turn a guess into a requirement. Output: `Scope`,
+`Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`,
+`Risks`, `Verification Expectations`.
 
 ## `frontend-scout-pi`
 
-- Inspect routes, pages, components, styles/tokens, state/data flow, API/mocks, scripts, tests, and reusable assets; do not edit.
-- Separate confirmed facts, inferred conventions, and missing information.
-- Attempt knowledge-base first. If absent, failed, or unmatched, recursively inspect `<repoRoot>/openSpec/**` before other repo conventions.
-- Record source as `knowledge-base`, `openSpec fallback`, `repository fallback`, or `unavailable`, with query/search terms and matched paths.
-- Output: `Frontend Stack`, `Routes`, `Components`, `Styling System`, `Existing Design Conventions`, `State / Data Flow`, `Test Entry Points`, `Reuse Opportunities`, `Risks`.
+Inspect routes, components, styles/tokens, state/data, APIs/mocks, scripts, tests,
+and assets. Separate facts, inferences, and gaps. Query knowledge-base;
+if absent/failed/unmatched, search and read `<repoRoot>/openSpec/**` before repo
+conventions. Record source, query/terms, and paths. Output: `Frontend Stack`,
+`Routes`, `Components`, `Styling System`, `Existing Design Conventions`,
+`State / Data Flow`, `Test Entry Points`, `Reuse Opportunities`, `Risks`.
 
 ## `frontend-plan-pi`
 
-- Map every acceptance criterion to ordered implementation and verification steps.
-- Name target files and reasons; keep them within allowed paths and expected `writeSet`.
-- Define states, component/styling reuse, interaction behavior, dependency policy, and exact static/behavior commands.
-- Knowledge-base failure is not approval: apply relevant `openSpec/` matches as current-project rules. Request clarification only when neither source resolves required compliance or they conflict materially.
-- Output: `Implementation Steps`, `Target Files`, `UI State Handling`, `Styling / Component Strategy`, `Interaction Notes`, `Dependency Policy`, `Verification Plan`, `Residual Risks`.
+Map each criterion to implementation and verification. Name in-bound files; define
+states, reuse, interactions, dependencies, and commands. Apply `openSpec/` rules
+when knowledge-base fails; ask only for material conflicts. Output: `Implementation Steps`, `Target
+Files`, `UI State Handling`, `Styling / Component Strategy`, `Interaction Notes`,
+`Dependency Policy`, `Verification Plan`, `Residual Risks`.
+
+## First design protocol gate
+
+`frontend-first-design-gate-shell` reads `frontend-design-gate-pi`'s first
+non-empty line. It accepts only `VERDICT: pass` or `VERDICT: request-revision` and
+blocks malformed output. It never authorizes writes; request-revision enters plan
+revision. Line mode: `first-verdict-line`.
+
+## `frontend-plan-revision-pi`
+
+Consume the original plan and first review findings. On first-gate pass, output
+`PASS_NO_REVISION_NEEDED`; on request-revision, address every Required Plan
+Correction in a complete plan with the plan headings above. Always `read-only`;
+never edit code, docs, or artifacts.
+
+## Final design review and gate
+
+`frontend-final-design-review-pi` rechecks the original plan for
+`PASS_NO_REVISION_NEEDED`, otherwise verifies every correction and rejects any
+remaining/new gap. Its first non-empty line is exactly `VERDICT: pass` or
+`VERDICT: request-revision`.
+
+`frontend-final-design-gate-shell` reads that verdict and accepts only
+`VERDICT: pass`. It is the sole write authorization. Failure routes to
+`ContractMismatch` / `frontend-plan-revision-and-rerun`, never `ProductBug` /
+`dev-fix`. Line mode: `first-verdict-line`.
 
 ## `frontend-implement-pi`
 
-- Run only after design gate pass and implement only the approved plan inside `writeSet`.
-- Re-read current files; stop instead of crossing forbidden paths or guessing a blocking decision.
-- Reuse confirmed project primitives and update tests. Do not claim knowledge-base or downstream verification without evidence.
-- Output: `Changed Files`, `Implemented Behavior`, `UI States Covered`, `Styling / Component Notes`, `Verification Attempted`, `Residual Risks`.
+Depends directly on final gate, revision plan, and final review. After pass, re-read
+current files and implement only the approved plan inside `writeSet`; stop on
+forbidden paths or blocking guesses. Reuse primitives and update tests. Output:
+`Changed Files`, `Implemented Behavior`, `UI States Covered`, `Styling / Component
+Notes`, `Verification Attempted`, `Residual Risks`.

package/skills/frontend-review/SKILL.md

@@ -25,7 +25,7 @@ required check, forbidden write, or unmet acceptance criterion forces revision.
 - Inspect every changed file against allowed, forbidden, and approved write scope.
 - Map criteria to behavior, applicable UI states, tests, and shell evidence.
 - Review state/data flow, validation, async/error behavior, components/design, responsive behavior, accessibility, dependencies, maintenance, and regression risk when applicable.
-- Component/design claims require traceable knowledge-base evidence or, after connection/query failure or no match, relevant `<repoRoot>/openSpec/**` evidence. The connector format is TODO; never claim a query or fallback search without evidence.
+- Component/design claims require traceable knowledge-base evidence or, after connection/query failure or no match, relevant `<repoRoot>/openSpec/**` evidence. The connector format is TODO; never claim a query or fallback search without evidence. Execute explicit `grep`/`find` to locate spec files and `read` to load them before referencing their rules. Only successful `read` tool calls are observable as "已读取规范文件" in the spec-evidence inspector.
 - Treat shell exit status as authoritative. Do not edit files.
 
 ## Evidence And Output

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

@@ -276,6 +276,7 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 - Decision Gate prompt 可用 `buildDagDecisionGateEvidence()`（`src/workflows/dag/decision-evidence.ts`）做与 `dag report --json`、`docs/templates/agent-dag-report.schema.json` 对齐的只读摘要；不 mutate run state，不执行 retry/resume。
 - 仅当有意在 `.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`。
+- 业务专用 DAG 通过 `task.json.taskKind` 选择，不扩充 governance profile：`frontend-implementation` 选择前端实现模板，`backend-test` 选择需求分析 → 功能用例 → 评审 → pytest 生成/执行 → 复盘的后端测试模板。
 
 ### Saved Dynamic Workflow operator UX
 ```bash
@@ -391,6 +392,7 @@ agent-worker report metrics --repo <repo-root> --month <YYYY-MM> [--json]
 agent-worker task draft-followup <task-id> --worker-run-id <id> --feature-dir <feature-dir> --repo <repo-root> [--json]
 agent-worker feature approve-followup --feature-dir <feature-dir> --followup-id <id> --repo <repo-root> --owner <owner> [--dry-run] [--json]
 agent-worker task retry <task-id> --repo <repo-root> [--reason "<已修复的原因>"]
+agent-worker batch plan-ready --feature-dir <feature-dir> --repo <repo-root> [--limit <count>] [--json]
 agent-worker batch run-ready \
   --feature-dir <feature-dir> \                   # 含 tasks/task-graph.yaml
   --repo <repo-root> \                            # 目标 repo

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

@@ -14,6 +14,8 @@
 
 此 policy 驱动 `dag run-task --profile auto`：CLI 仍要求显式 `dag run-task`、`dag validate`、`run-dag`，但 `--profile auto` 在确定性 candidate `governanceProfile` 推断后应用 `workflowPolicy.dag.profileRouting`。生成器还会把 `outputLanguage` 写入 DagSpec，runner 在每个 Pi/Cursor 节点 prompt 中注入语言规则；代码、命令、路径、JSON 字段与 gate token 保持原样。`humanGatePolicy` 是默认人机边界声明；真实暂停仍由 DAG 节点的 `decisionGate.mode: "pause-on-human"` 与 decision envelope 触发。无 profile 的 `dag run-task <task-id>` 仍为 standard-compatible，供 legacy/review workflow。
 
+`task.json.taskKind` 负责选择业务专用模板，不扩充 governance profile：`frontend-implementation` 选择前端实现 DAG，`backend-test` 选择后端测试 DAG。后端测试链为 `analyze-inputs-pi → generate-backend-functional-cases-pi → review-backend-cases-pi → review-backend-cases-gate-shell → generate-backend-pytest-pi → execute-backend-pytest-shell → test-retrospect-pi`，治理等级仍由既有 `minimal|standard|reviewed|supervised` 规则推断。
+
 ### DAG workflow 层级
 
 | 优先级 | 入口 | 使用场景 |
@@ -42,7 +44,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 **v2 字段**（均可选；缺失时行为同 v1）：
 
 - 顶层：`objective`、`successCriteria`、`globalConstraints`、`defaults`、`skillsByRole`、`executorModels`
-- 每 node：`role`、`skills`、`writePolicy`、`writeSet`、`piStep`、`shell`、`outputContract`、`executor`（`pi` | `shell` | `static`）；Pi 写入节点额外声明 `toolProfile: "write"`
+- 每 node：`role`、`skills`、`writePolicy`、`writeSet`、`piStep`、`shell`、`outputContract`、`executor`（`pi` | `shell` | `static`）；Pi 写入节点额外声明 `toolProfile: "write"`；安全只读 Pi 节点可选声明 `retryPolicy`（生成器自动注入默认值）
 
 **Model 生成 DAG 的 template 卫生**：
 
@@ -75,7 +77,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 - **Prompt source**：每个 task 仅用一种 prompt source。v1-compatible DAG 用 inline `subtask_prompt`；markdown-backed prompt 用 canonical `subtask_prompt_markdown`。同时提供两字段、皆不提供、或用连字符 alias `subtask_prompt-markdown` 均 fail fast。
 - **勿宣称 live smoke 已通过**，除非真实 `run-dag` execution 中 Pi read-only、Pi writer、显式 Cursor 或 shell node 均按 DAG 完成。
 
-可复用 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/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`。
+可复用 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/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）
 
@@ -107,9 +109,13 @@ contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
 
 **Verdict gate contract（`shell.verdictGate`）**：声明 `fromNodeId`、`accept[]`、可选 `label`、可选 `lineMode`。runner 展开为一条 shell command，从 injected current run directory 读 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`，对 extracted `assistantText ?? stdout` verdict line 与 `accept[]` exact-match。默认 `lineMode` 为 `first-non-empty` 以兼容；supervised gate 用 `first-verdict-line` 选 Pi 在 preamble 或常见整行 Markdown emphasis（如 `**VERDICT: pass**`）后第一条 normalized `VERDICT:` line。勿用 `result.summary.md`、grep VERDICT、latest-active-run discovery 或 multi-command stateful gate。`--strict-governance` 对 anti-pattern fail。supervisor 仍为 `executor: pi` 上的 `role: supervisor`。
 
+**Repair artifact gate contract（`shell.repairArtifactGate`）**：声明 `fromNodeId`（supervisor artifact 节点）与 `repairNodeId`（承接修订的 Pi 修复节点）。runner **不再**按节点名（历史 `repair-cursor` / `repair-pi`）猜测 repair 节点：显式 `repairNodeId` 必须存在、直接 `depends_on` gate、且是受治理 Pi writer（`executor: pi`、`toolProfile: write`、`writePolicy: exclusive`、`allowedPaths`+`writeSet` 非空且 `writeSet` 不与 `forbiddenPaths` 冲突）。新生成的 supervised DAG 总是写入 `repairNodeId`；旧 DAG 缺失时只在能唯一、安全地推导出下游 Pi writer 时兼容，零个或多个候选、或候选不满足契约都在执行前 fail closed。validation 覆盖存在性、直接下游、writer 属性与路径边界。
+
+**Runtime contract 与 controller identity**：新生成的 DagSpec 使用 `version: 3`，并必须携带 `runtimeContract`（`schemaVersion` / `agentRuntime: "pi-only"` / `repairWriterProtocol: "explicit-node-v1"` / 可选 `minimumControllerVersion`）。v3 是旧 controller 无法忽略的解析边界；capability 与最低版本是新 controller 的执行前兼容门。`init-hybrid` 不硬编码 `minimumControllerVersion`，手写 spec 可按需 pin。每个新 run 必须解析并冻结 controller identity（package version、binary SHA-256、portable fingerprint）到 `controller-identity.json`；解析失败不创建 run。`dag report` 展示 identity 与 runtime-contract compatibility，resume 对漂移、篡改或 legacy-unpinned run 全部 fail closed；legacy run 仍可只读报告或显式 reconcile。
+
 Prompt invariant：`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`（启用时）。测试：`npx vitest run test/dag-supervised-template.test.ts test/authority-surface.test.ts`。完整叙述：`docs/agent-dag-runner.md` §「Why main-session interventions happened」。
 
-**未实现**：`executor: supervisor`、automatic retry/resume、`executor: human`/`decision`、browser executor，或 read-only node 对 root `artifacts/**` 的 exemption。
+**未实现**：`executor: supervisor`、whole-run automatic retry/resume、`executor: human`/`decision`、browser executor，或 read-only node 对 root `artifacts/**` 的 exemption。注：有界只读 Pi 节点重试已实现（见下「只读 Pi 节点安全重试」）。
 
 ### Level 3 task-to-DAG（`dag init-hybrid` / `dag run-task`）
 
@@ -179,6 +185,19 @@ loop-agent dag resume --run-id <run-id>   # approve 后继续
 
 **In-flight DAG run 期间的 governance**：live run 内 shell verify node 须用 `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`。run 归档到 `completed/` 后，在 DAG 外跑裸 `bash scripts/check-repo.sh`。
 
+### 只读 Pi 节点安全重试（read-only retry）
+
+planner/scout/reviewer/verifier/closeout 角色的安全只读 Pi 节点可声明 `retryPolicy`，在同一 run 内有界重试模型连接中断、provider 限流、临时不可用或请求 timeout。生成模板自动注入默认策略（总尝试 3 次，手工配置最多 5 次，指数退避，单次等待上限 30s）。supervisor 与 implementer 明确不重试。
+
+- 仅重试原始分类：`timeout`、`network`、`rate-limit`、`unavailable`。`quota` **不**是 rate limit，不重试；`auth`、`invalid-output`、`write-guard`、`decision-envelope` 与未知失败同样不重试。
+- 资格由确定性 helper 判断，executor 内不硬编码循环；仅 `writePolicy=read-only|none`（或 Pi 默认只读）的上述角色可用。supervisor / implementer / writer / docs-only / dynamic / shell / static / decision-gate 节点声明 `retryPolicy` 会在 DAG validation 阶段失败。
+- 每次 attempt 写入独立不可变证据 `<node-id>/attempt-<n>.json`（run-relative path），最终 node record `attempts` 字段引用完整历史；后一次成功不覆盖前一次失败证据。
+- 重试复用同一 run、controller identity、skill snapshot、prompt、model 与上游输入；退避等待刷新 `lastActivityAt` 避免误判 node-quiet。
+- 节点终态聚合全部 attempts 的耗时、Token 与事件数；当前 backoff 等待会占用该节点的并发槽。
+- 未声明 `retryPolicy` 的历史 DAG 行为不变（单次执行，不新增 attempt artifact）。
+
+实现：`src/workflows/dag/retry-policy.ts`、`node-execution.ts`、`validate.ts`。测试：`npx vitest run test/dag-node-retry.test.ts test/dag-validate.test.ts test/dag-init-hybrid.test.ts`。
+
 ### Evidence summary guidance（practice convention — 非 runtime）
 
 review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-summary-shell** 作为 authoring pattern。**不是** runtime executor、schema field 或 parser。

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

@@ -72,6 +72,12 @@ product-line taxonomy 的事实源是 `docs/design/state-and-failure-taxonomy.md
 - 独立 audit 报告用 `handoff coverage <task-id> [--json|--markdown]`。
 - task status、source/artifacts、DAG outcome、verification 记录可能 drift 时用 `dag reconcile-tasks --glob '<pattern>' [--json|--markdown]`。默认仅报告；`--patch` 不能伪造 verification evidence。
 
+### supervised repair gate 与 runtime contract 失败
+
+- `repair artifact gate failed: ... no unique governed Pi writer` / `declares repairNodeId "..." but no task with that id exists`：DagSpec 的 `shell.repairArtifactGate` 未声明 `repairNodeId`，或声明的修复节点缺失、不是 gate 直接下游、不是受治理 Pi writer（`executor: pi`、`toolProfile: write`、`writePolicy: exclusive`、`allowedPaths`/`writeSet` 非空且不与 `forbiddenPaths` 冲突）。用当前 controller 重新生成 supervised DAG，或按上述契约补齐修复节点，不要靠改节点名绕过。
+- `incompatible DAG runtime contract` / `runtime contract requires ...`：DagSpec 的 `runtimeContract` 要求的能力超出当前 controller。升级 controller 或用当前 controller 重新生成 DAG；该 preflight 在任何节点执行前失败，不会留下半执行的 run。
+- `controller identity drifted` / `artifact was tampered with`：resume 时的 controller 与 run 创建时冻结的 identity 不一致（package 内容、binary 或 fingerprint 变化），或 `controller-identity.json` 被篡改。启动新 run，而不是在漂移后 resume；completed run facts 保持只读。
+
 ### Verify 默认保存进度
 `verify` 成功后，loop-agent 默认：