@fitlab-ai/agent-infra 0.10.0 → 0.11.0

package/templates/.agents/rules/issue-sync.zh-CN.md

@@ -13,6 +13,9 @@
 | `artifactChunk` | `<!-- sync-issue:{task-id}:{artifact-stem}:{part}/{total} -->` |
 | `summary` | `<!-- sync-issue:{task-id}:summary -->` |
 | `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
+| `recoveryAction` | `<!-- sync-issue:{task-id}:recovery-action:{action-id} -->` |
+| `recoveryPrepare` | `<!-- sync-issue:{task-id}:recovery-prepare:{commit-id} -->` |
+| `recoveryCommit` | `<!-- sync-issue:{task-id}:recovery-commit:{commit-id} -->` |
 
 `prSummary` 属于 `.agents/rules/pr-sync.md`，本规则不实现 PR 聚合。
 
@@ -25,15 +28,19 @@
 ```bash
 agent-infra-internal platform-context resolve [--cwd <path>]
 agent-infra-internal platform-comment list --issue <issue-token> [--cwd <path>]
+agent-infra-internal platform-comment recover --issue <issue-token> --task-id <TASK-id> \
+  --output <.agents/workspace/.restore-staging-*/task.md> [--cwd <path>]
 agent-infra-internal platform-comment owner <task-ref>
 agent-infra-internal platform-comment sync <task-ref> \
-  --kind task|artifact|summary|cancel --agent {standard-agent-token} \
+  --kind task|artifact|summary|cancel|recovery-action|recovery-prepare|recovery-commit --agent {standard-agent-token} \
   [--artifact <canonical.md>] [--body-file <path|->] [--backfill]
 ```
 
 - `applied|no-op|degraded` → exit 0；`failed` → exit 1；`blocked` → exit 2。
-- task 评论保持 `<details>` frontmatter 可逆格式；artifact 原文内联并在超过 profile 上限时使用 `artifactChunk`。
-- task 内容超过平台评论字节上限时不上传，返回 `COMMENT_PAYLOAD_TOO_LARGE` 的 skipped 操作；本地 task 文件保持不变，platform verification 同样跳过 task marker/content 检查。
+- task 评论保持 `<details>` frontmatter 可逆格式，只同步确定性的当前任务投影；活动日志、产物生命周期收据、失效记录等过程章节由 recovery 事务保存。artifact 原文内联并在超过 profile 上限时使用 `artifactChunk`。
+- 长度预检与 platform verification 使用同一最终渲染正文的 UTF-8 字节数。正文超限时失败关闭；本地 task 文件不会被截断。
+
+恢复评论使用 `recovery-action`、`recovery-prepare` 和 `recovery-commit` marker，并携带稳定 recovery id 和 body file。task 同步按 prepare、action、task snapshot 写入并复读、commit 的顺序发布。相同内容重放返回 `no-op`；已有恢复 marker 的正文不同返回 `RECOVERY_IMMUTABLE_CONFLICT`。restore 只接受作者一致、分片完整、phase/摘要/marker 匹配且绑定当前 task 评论正文 SHA-256 的完整事务。
 - 相同 intent 重放必须收敛为 `no-op`；重复 marker 返回 `COMMENT_MARKER_CONFLICT` 且不写入。
 - 外部贡献者锁定统一使用 `platform-comment owner`；不同作者且无 triage 时返回 `COMMENT_OWNER_CONFLICT`。
 

package/templates/.agents/rules/local-artifact-repair.en.md

@@ -7,8 +7,8 @@ This rule covers the pre-completion gate for `analyze-task`, `plan-task`, and `c
 - Run the applicable finalizer before a completed event; pass only that invocation's `artifactSha256` and `semanticDigest` to the event.
 - When artifact content is invalid, the finalizer returns a controlled `recovery` with a `recoveryId`, `candidatePath`, and baseline digests. The formal artifact remains unchanged until recovery commit.
 - After the mechanical safety gates pass, the model may edit only the returned `candidatePath`. After each byte-changing edit, rerun the complete finalizer with the same task, stage/family, artifact, and `--recovery-id`. Never edit the formal artifact directly and call it a candidate.
-- A successful finalizer commits through `finalize-ready → commit-started → passed`; completed events accept only matching `passed` final digests and consume the intent under the task lock.
-- Before `finalize-ready`, the recovery core seals the validated final bytes in the controlled `final.md`; later commit ignores the editable `candidate.md` and validates/publishes only that sealed snapshot, so a post-prepare candidate replacement cannot be published.
+- Preflight stable-reads and validates candidate `S`, then seals immutable digest-addressed generation `R`; candidate SHA is an observation rather than an edit guard.
+- Preflight publishes active `R` through `preflight-ready → preflight-commit-started → preflight-passed`; the business finalizer publishes `F` through `full-finalizer-ready → commit-started → passed` and reuses `R` when `F=R`.
 - Candidate-only is a protocol authorization boundary, not OS isolation: a same-UID process with arbitrary host filesystem write access may tamper with recovery internals. Identity, fingerprint, and state checks detect such anomalies and fail closed, but the protocol does not claim an independent security principal or cross-platform isolation.
 
 ## Authorization boundary
@@ -32,14 +32,15 @@ If any condition fails, stop without editing or publishing a completed event.
 
 | State | Formal artifact | Allowed action |
 | --- | --- | --- |
-| `awaiting-recovery` | baseline `B` | Edit only controlled candidate `S`; rerun the same finalizer |
-| `finalize-ready` | `B` | Recovery core starts the commit under the task lock |
-| `commit-started` | `B` or final `F` | Reconcile only; retry, confirm, or restore from verified `B/F` fingerprints |
+| `awaiting-preflight-recovery` | baseline `B` | Edit `S`; stable-read, validate, and create `R` |
+| `preflight-ready` / `preflight-commit-started` | `B` or `R` | Reconcile/publish only active immutable `R` |
+| `preflight-passed` | `R` | Run the business finalizer for `F` |
+| `full-finalizer-ready` / `commit-started` | `R` or `F` | Reconcile/publish only pending immutable `F` |
 | `passed` | `F` | Completed event validates the final digest and consumes the intent |
 | `consumed` | `F` | Cleanup may reclaim the controlled staging and backup |
 | `aborted` | verified restored `B` | Preserve diagnostics; never fabricate success |
 
-The intent is current-only schema version 3. Legacy schemas fail closed; do not add migration, adapters, or dual writes. Candidate, baseline, and intent files live in controlled repo-local directories and use canonical recovery IDs, regular-file checks, stable reads, the task lock, and expected-value CAS. No cross-file atomicity is claimed; unknown combinations remain indeterminate and retain their evidence.
+The intent is current-only schema version 4. Legacy schemas fail closed; do not add migration, adapters, or dual writes. Candidate, baseline, generation, and intent files live in controlled repo-local directories and use canonical recovery IDs, regular-file checks, stable reads, the task lock, and expected-value CAS. No cross-file atomicity is claimed; unknown combinations remain indeterminate and retain their evidence.
 
 ## Dynamic convergence loop
 

package/templates/.agents/rules/local-artifact-repair.zh-CN.md

@@ -5,10 +5,11 @@
 ## 完成前门禁
 
 - 完成事件前必须运行对应 finalizer；只有同一次返回的 `artifactSha256` 和 `semanticDigest` 才能传给 completed event。
-- finalizer 发现 artifact 内容错误时，返回受控 `recovery`（`recoveryId`、`candidatePath`、baseline 指纹）。正式 artifact 在 recovery commit 前必须保持不变。
+- preflight 先对当前 stable-read candidate 完整验证，并将验证的 `R` 写入 digest-addressed、只读的 generation；在 journal CAS 前正式 artifact 必须保持 baseline `B`。
+- candidate SHA 是 awaiting 状态的最后一次 stable-read 观测值，不是下一次编辑的 guard。合法 `S` 编辑必须重新验证并在成功后 CAS 为 `R`。
 - 只有在机械安全门通过后，模型才可编辑返回的 `candidatePath`；每次实际字节变化后，用同一 task、stage/family、artifact 和 `--recovery-id` 完整重跑 finalizer。不得直接编辑正式 artifact 后假设它属于候选。
-- finalizer 通过后，recovery core 按 `finalize-ready → commit-started → passed` 提交候选；completed event 只接受匹配的 `passed`/final digest，并在任务锁内消费 intent。
-- `finalize-ready` 前 recovery core 会把已校验的最终字节封存为受控 `final.md`；后续 commit 忽略可编辑的 `candidate.md`，只校验并发布该封存快照，避免候选在准备后被替换。
+- preflight 按 `preflight-ready → preflight-commit-started → preflight-passed` 发布 immutable `R`；业务 finalizer 再按 `full-finalizer-ready → commit-started → passed` 将 `F` 发布。`F=R` 复用 active generation。
+- preflight-ready 后 publish 只读取 active/pending generation，绝不再读取可编辑 candidate。
 - candidate-only 是协议授权边界，不是操作系统隔离：拥有同一 UID 且可任意写入宿主文件系统的进程可能篡改 recovery 内部文件；协议会通过身份、指纹和状态校验发现异常并失败关闭，但不承诺独立权限主体或跨平台隔离。
 
 ## 授权边界
@@ -32,14 +33,15 @@
 
 | 状态 | formal artifact | 允许动作 |
 | --- | --- | --- |
-| `awaiting-recovery` | baseline `B` | 只编辑受控 candidate `S`，重跑同一 finalizer |
-| `finalize-ready` | `B` | recovery core 在锁内开始提交 |
-| `commit-started` | `B` 或 final `F` | 只允许 reconcile；按 `B/F` 指纹重试、确认或回滚 |
+| `awaiting-preflight-recovery` | baseline `B` | 只编辑 candidate `S`，稳定读取、验证并生成 `R` |
+| `preflight-ready` / `preflight-commit-started` | `B` 或 `R` | 只可从 active immutable `R` reconcile/publish |
+| `preflight-passed` | `R` | 执行业务 finalizer，生成或复用 `F` |
+| `full-finalizer-ready` / `commit-started` | `R` 或 `F` | 只可从 pending immutable `F` reconcile/publish |
 | `passed` | `F` | completed event 校验 final digest 后消费 |
 | `consumed` | `F` | 可由中间产物清理流程回收受控 staging/backup |
 | `aborted` | 已确认恢复的 `B` | 只保留诊断，不得伪造成功 |
 
-intent 使用 current-only schema version 3。旧 schema 直接失败关闭；不添加迁移、adapter 或双写。candidate、baseline 和 intent 位于 repo-local 受控目录，使用 canonical recovery ID、普通文件检查、stable read、task lock 和 expected-value CAS。跨文件不宣称原子性；未知组合返回 indeterminate 并保留现场。
+intent 使用 current-only schema version 4。旧 schema 直接失败关闭；不添加迁移、adapter 或双写。candidate、baseline、generation 和 intent 位于 repo-local 受控目录，使用 canonical recovery ID、普通文件检查、stable read、task lock 和 expected-value CAS。跨文件不宣称原子性；未知组合返回 indeterminate 并保留现场。
 
 ## 动态收敛循环
 
@@ -50,7 +52,7 @@ intent 使用 current-only schema version 3。旧 schema 直接失败关闭；
 
 ## 共享入口
 
-`task-artifact ... inspect|init|finalize-local` 和 `task-review ... finalize-summary` 是当前入口。恢复重试使用 finalizer 返回的 `recoveryId`，例如：
+`task-artifact ... inspect|init|preflight|finalize-local` 和 `task-review ... finalize-summary` 是当前入口。preflight 不发布 task metadata、ledger、formal provenance、completed event 或平台状态；恢复重试使用 finalizer 返回的 `recoveryId`，例如：
 
 ```text
 agent-infra-internal task-artifact {task-id} finalize-local --family code --artifact {code-artifact} --recovery-id {recovery-id}

package/templates/.agents/skills/code-task/SKILL.en.md

@@ -24,7 +24,7 @@ Before generating the implementation report, read `.agents/rules/evidence-report
 - Before generating task or lifecycle Markdown that will be synchronized to an Issue, read `.agents/rules/sync-content-generation.md` and apply its producer-side constraints; the sync path does not parse or rewrite the body
 - Read `.agents/rules/compatibility-policy.md` before implementation. Implement only the compatibility budget explicitly approved by the plan; never retain old branches, result contracts, or migration shims merely to be “safe”
 - Fix mode verifies each finding of the latest `review-code` one by one: fix it if it holds, or rebut it and record it under unresolved if it is unfounded/hallucinated; do not expand to issues the review did not list; manual-validation items are out of scope
-- Before `code.completed`, the implementation report must pass `task-artifact ... finalize-local --family code`; follow `.agents/rules/local-artifact-repair.md` for controlled recovery candidates in that same report, and pass only that successful call's digests to the completion event
+- Before a checkpoint, ledger write, or `code.completed`, the implementation report must pass `task-artifact ... preflight --family code`. Preflight only validates and seals a generation; `finalize-local` publishes the matching final digest later.
 - If implementation encounters a key design decision not covered by the plan, run `agent-infra-internal task-ledger {task-id} decision-next-id`, write the returned `HD-N` detail block per `.agents/rules/human-decision-context.md` and determine whether implementation is required, then run `decision-upsert --id {HD-N} --stage code --artifact {code-artifact} --needs-implementation {true|false}`. Do not scan ids, assemble ledger rows, ask mid-flow, or silently expand scope
 - Do not invoke the `commit` skill or push to a remote; after tests pass, call the shared commit core with `delivery: { mode: 'local' }` to create the local checkpoint. The durable intent must close only after the checkpoint and task state sync succeed; only then emit `code.completed`
 - Create a new code artifact for each round and never overwrite an older one

package/templates/.agents/skills/code-task/SKILL.zh-CN.md

@@ -24,7 +24,7 @@ description: >
 - 生成会同步到 Issue 的任务或生命周期 Markdown 前，先读取 `.agents/rules/sync-content-generation.md` 并遵循其中的生成端约束；同步端不解析或改写正文
 - 实现前读取 `.agents/rules/compatibility-policy.md`；只实现方案明确批准的兼容预算，不以“稳妥”为由保留旧分支、旧结果契约或迁移 shim
 - 修复模式逐条核实最新 `review-code` 的发现：成立则修复，判定为不成立/幻觉则在报告中反驳并记入 unresolved；不擅自扩大到审查未列出的问题；manual-validation 项不在修复范围
-- 实现报告在 `code.completed` 前必须通过 `task-artifact ... finalize-local --family code`；按 `.agents/rules/local-artifact-repair.md` 使用受控 recovery candidate 处理同一报告内可证明安全的结构修复，并只把同一次通过结果的摘要传给完成事件
+- 实现报告在 checkpoint、账本和 `code.completed` 前必须先通过 `task-artifact ... preflight --family code`；preflight 只验证并封存 generation，不发布 formal/task/ledger/platform 状态。随后 `finalize-local` 才发布同一次通过的 digest。
 - 实现中遇到方案未覆盖的关键设计决策时，先调用 `agent-infra-internal task-ledger {task-id} decision-next-id` 取得 `HD-N`，按 `.agents/rules/human-decision-context.md` 写入实现报告的 `## 人工裁决待办` 详情块并判断是否需要实现，再调用 `decision-upsert --id {HD-N} --stage code --artifact {code-artifact} --needs-implementation {true|false}`；不得扫描编号、手写账本行、中途提问或擅自扩范围
 - 不调用 `commit` 技能，也不推送远端；测试通过后直接调用共享 commit core 的 `delivery: { mode: 'local' }` 创建本地 checkpoint。checkpoint 使用 durable intent，只有 checkpoint 与 task 状态同步成功后才发送 `code.completed`
 - 每轮实现都创建新的实现产物，不覆盖旧文件
@@ -148,7 +148,7 @@ echo "$result"
 
 如果测试失败，先尝试修复并重新运行测试。只有在确认存在外部阻塞、环境缺失或需求不明确且超出任务范围时，才可以停止。
 
-测试通过后，通过 `agent-infra-internal git-workflow commit --input {checkpoint-input}` 调用共享 commit core，输入 `delivery: { "mode": "local" }`、明确 paths、expected HEAD/tree、task ref、agent 和 code round。该调用只创建本地 checkpoint，不访问远端；core 会在 commit 前写入 durable intent，并在 task writer 成功后清理 intent。checkpoint 失败或 task 状态未闭合时，不得发送 `code.completed`。
+测试通过后，先创建报告并运行 `task-artifact {task-id} preflight --family code --artifact {code-artifact}`；preflight 失败只允许在同一受控 candidate 中修复并完整重跑，且不得产生 checkpoint、ledger、completed 或平台副作用。preflight 通过后，才通过 `agent-infra-internal git-workflow commit --input {checkpoint-input}` 调用共享 commit core，输入 `delivery: { "mode": "local" }`、明确 paths、expected HEAD/tree、task ref、agent 和 code round。该调用只创建本地 checkpoint，不访问远端；core 会在 commit 前写入 durable intent，并在 task writer 成功后清理 intent。checkpoint 失败或 task 状态未闭合时，不得发送 `code.completed`。
 
 checkpoint 成功后，若任务存在 `platform_issue_identity`，调用 `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --in-labels from-diff --base {delivery-base-ref}`，由 task-bound `delivery_base_ref` 产生 Issue 的 `in:` target；该同步失败时记录 warning 并停止本轮，不发送 `code.completed`。
 

package/templates/.agents/skills/restore-task/SKILL.en.md

@@ -45,13 +45,14 @@ Run `agent-infra-internal platform-comment list --issue {issue-token}` to read a
 
 ### 3. Determine the task-id and Files to Restore
 
-Filter comments by the task, artifact, and chunked artifact markers defined in `.agents/rules/issue-sync.md`.
+Filter comments by the task, artifact, chunked artifact, and recovery markers defined in `.agents/rules/issue-sync.md`.
 
 Rules:
 - when `{task-id}` was provided, match only that task
 - when `{task-id}` was omitted, infer it from the task comment marker first
 - if you cannot determine a unique task-id, stop and tell the user
 - ignore `summary` marker comments because they are complete-task aggregate output rather than restorable local task files
+- use the `task` comment only for the current projection and snapshot identity; the controlled recovery core validates `recovery-action`, `recovery-prepare`, and `recovery-commit` comments and reconstructs the complete `task.md`
 - map `{file-stem}` back to filenames:
   - `task` -> `task.md`
   - `analysis` / `analysis-r{N}` -> matching `.md`
@@ -68,7 +69,7 @@ Read `.agents/rules/issue-sync.md` before executing this step.
 
 For each file:
 - collect its single comment or chunked comments
-- for `task.md` comments, reverse the `<details>` frontmatter wrapper described in issue-sync.md before reassembling the file body
+- do not reverse the projected task comment directly into `task.md`; the complete task content must come from a recovery commit matching the current projection
 - when a chunk marker includes part and total indexes, sort by part and verify the set is complete
 - extract the file body by removing the hidden marker, heading, and footer
 - concatenate chunk bodies into the final file content
@@ -83,10 +84,14 @@ If the directory already exists, stop immediately and tell the user to handle it
 
 Create the controlled staging directory and write files back in this order:
 
-1. `task.md`
+1. call the recovery core to write `task.md`:
+   ```bash
+   agent-infra-internal platform-comment recover --issue {issue-token} --task-id {task-id} \
+     --output "{staging-dir}/task.md"
+   ```
 2. every other restored artifact file in filename order
 
-Write only files that were actually recovered from Issue comments. Do not invent missing files.
+Write only files that were actually recovered from Issue comments. Do not invent missing files. Stop without calling the lifecycle intent if the recovery core fails.
 
 ### 6. Apply the Restore Lifecycle Intent
 

package/templates/.agents/skills/restore-task/SKILL.zh-CN.md

@@ -44,13 +44,14 @@ description: >
 
 ### 3. 确定 task-id 与待恢复文件
 
-按 `.agents/rules/issue-sync.md` 中定义的 task、artifact 和分片 artifact 标记筛选评论。
+按 `.agents/rules/issue-sync.md` 中定义的 task、artifact、分片 artifact 和 recovery 标记筛选评论。
 
 处理规则：
 - 用户提供了 `{task-id}` 时，仅匹配该任务
 - 未提供时，优先从 task 评论标记推断
 - 若找不到唯一 task-id，立即停止并告知用户
 - 忽略 `summary` 标记评论；它是 complete-task 的聚合产物，不对应本地任务文件
+- `task` 评论仅用于确定当前投影和 snapshot 身份；`recovery-action`、`recovery-prepare`、`recovery-commit` 由受控 recovery core 验证并重建完整 `task.md`
 - 将 `{file-stem}` 映射回文件名：
   - `task` -> `task.md`
   - `analysis` / `analysis-r{N}` -> 对应 `.md`
@@ -67,7 +68,7 @@ description: >
 
 对每个文件执行：
 - 收集单条评论或分片评论
-- 对 `task.md` 评论按 issue-sync.md 中的 `<details>` frontmatter 格式反向拆解，提取 frontmatter 后再与正文拼合
+- 不直接把投影 task 评论反向拆成 `task.md`；完整 task 内容必须来自匹配当前投影的 recovery commit
 - 如分片标记中存在 part 和 total 序号，按 part 升序排序并校验分片完整
 - 从评论正文中提取文件内容，去掉隐藏标记、标题和页脚
 - 拼接得到最终文件内容
@@ -82,10 +83,14 @@ description: >
 
 创建受控 staging 目录，按以下顺序写回：
 
-1. `task.md`
+1. 调用 recovery core 写入 `task.md`：
+   ```bash
+   agent-infra-internal platform-comment recover --issue {issue-token} --task-id {task-id} \
+     --output "{staging-dir}/task.md"
+   ```
 2. 其余产物文件（按文件名排序）
 
-仅写回从 Issue 评论中实际恢复出的文件，不补造缺失文件。
+仅写回从 Issue 评论中实际恢复出的文件，不补造缺失文件。recovery core 返回失败时停止，不调用 lifecycle intent。
 
 ### 6. 执行 restore 生命周期意图
 

package/templates/.agents/skills/review-analysis/SKILL.en.md

@@ -83,7 +83,7 @@ Create `.agents/workspace/active/{task-id}/{review-artifact}`.
 
 ### 6. Update Task Status
 
-After the report, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage analysis --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`; submit prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. Do not scan ids or edit ledger rows. After all ledger writes, make the initial call to `agent-infra-internal task-review {task-id} finalize-summary --stage analysis --artifact {review-artifact} {execution-flag}`; after a failure, follow `.agents/rules/local-artifact-repair.md` to decide whether to edit and rerun, and never treat an error type or `changed=false` as automatic authorization.
+After the report, call `agent-infra-internal task-review {task-id} preflight --stage analysis --artifact {review-artifact} {execution-flag}` before any ledger write. On failure, follow `.agents/rules/local-artifact-repair.md`; on success, bind `{recovery-id}` from the response. Only after preflight passes, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage analysis --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}` or prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. Do not scan ids or edit ledger rows. After all ledger writes, call `agent-infra-internal task-review {task-id} finalize-summary --stage analysis --artifact {review-artifact} --recovery-id {recovery-id} {execution-flag}`; never treat an error type or `changed=false` as automatic authorization.
 
 Bind and reuse this structured mapping from that one response:
 

package/templates/.agents/skills/review-analysis/SKILL.zh-CN.md

@@ -86,7 +86,7 @@ agent-infra-internal task-artifact {task-id} init --family review-analysis --art
 
 ### 6. 更新任务状态
 
-报告完成后，新 finding 逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage analysis --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`；复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。不得扫描编号或手写账本行。全部账本写入完成后首次调用 `agent-infra-internal task-review {task-id} finalize-summary --stage analysis --artifact {review-artifact} {execution-flag}`；失败后是否继续编辑并重跑，必须遵循 `.agents/rules/local-artifact-repair.md`，不能把失败类型或 `changed=false` 当作自动授权。
+报告完成后，先调用 `agent-infra-internal task-review {task-id} preflight --stage analysis --artifact {review-artifact} {execution-flag}`，不得先写入账本。失败后是否继续编辑并重跑，必须遵循 `.agents/rules/local-artifact-repair.md`；通过时从返回值绑定 `{recovery-id}`。只有 preflight 通过后，才逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage analysis --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`，或复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。不得扫描编号或手写账本行。全部账本写入完成后调用 `agent-infra-internal task-review {task-id} finalize-summary --stage analysis --artifact {review-artifact} --recovery-id {recovery-id} {execution-flag}`；不能把失败类型或 `changed=false` 当作自动授权。
 
 从该次返回值绑定并复用以下结构化映射：
 

package/templates/.agents/skills/review-code/SKILL.en.md

@@ -111,8 +111,9 @@ Create `.agents/workspace/active/{task-id}/{review-artifact}`.
 ### 6. Update Task Status
 
 Update task.md:
-- After the report, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage code --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`; submit prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. When escalating to `needs-human-decision`, append `--needs-implementation true|false` using the judgment recorded in the detail block. Do not scan ids or edit ledger rows
-- After all ledger writes, make the initial call to `agent-infra-internal task-review {task-id} finalize-summary --stage code --artifact {review-artifact} {execution-flag}`; after a failure, follow `.agents/rules/local-artifact-repair.md` to decide whether to edit and rerun, and never treat an error type or `changed=false` as automatic authorization
+- After the report, call `agent-infra-internal task-review {task-id} preflight --stage code --artifact {review-artifact} {execution-flag}` before any ledger write. On failure, follow `.agents/rules/local-artifact-repair.md`; on success, bind `{recovery-id}` from the response.
+- Only after preflight passes, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage code --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`; submit prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. When escalating to `needs-human-decision`, append `--needs-implementation true|false` using the judgment recorded in the detail block. Do not scan ids or edit ledger rows
+- After all ledger writes, call `agent-infra-internal task-review {task-id} finalize-summary --stage code --artifact {review-artifact} --recovery-id {recovery-id} {execution-flag}`; never treat an error type or `changed=false` as automatic authorization
 
   Bind and reuse this structured mapping from that one response:
 

package/templates/.agents/skills/review-code/SKILL.zh-CN.md

@@ -109,8 +109,9 @@ agent-infra-internal task-artifact {task-id} init --family review-code --artifac
 
 ### 6. 更新任务状态
 
-- 报告完成后，新 finding 逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage code --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`；复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。升级为 `needs-human-decision` 时，按详情块中的判断追加 `--needs-implementation true|false`。不得扫描编号或手写账本行
-- 全部账本写入完成后首次调用 `agent-infra-internal task-review {task-id} finalize-summary --stage code --artifact {review-artifact} {execution-flag}`；失败后是否继续编辑并重跑，必须遵循 `.agents/rules/local-artifact-repair.md`，不能把失败类型或 `changed=false` 当作自动授权
+- 报告完成后，先调用 `agent-infra-internal task-review {task-id} preflight --stage code --artifact {review-artifact} {execution-flag}`，不得先写入账本。失败后是否继续编辑并重跑，必须遵循 `.agents/rules/local-artifact-repair.md`；通过时从返回值绑定 `{recovery-id}`。
+- 只有 preflight 通过后，新 finding 才逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage code --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`；复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。升级为 `needs-human-decision` 时，按详情块中的判断追加 `--needs-implementation true|false`。不得扫描编号或手写账本行
+- 全部账本写入完成后调用 `agent-infra-internal task-review {task-id} finalize-summary --stage code --artifact {review-artifact} --recovery-id {recovery-id} {execution-flag}`；不能把失败类型或 `changed=false` 当作自动授权
 
   从该次返回值绑定并复用以下结构化映射：
 

package/templates/.agents/skills/review-plan/SKILL.en.md

@@ -83,7 +83,7 @@ Create `.agents/workspace/active/{task-id}/{review-artifact}`.
 
 ### 6. Update Task Status
 
-After the report, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage plan --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`; submit prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. Do not scan ids or edit ledger rows. After all ledger writes, make the initial call to `agent-infra-internal task-review {task-id} finalize-summary --stage plan --artifact {review-artifact} {execution-flag}`; after a failure, follow `.agents/rules/local-artifact-repair.md` to decide whether to edit and rerun, and never treat an error type or `changed=false` as automatic authorization.
+After the report, call `agent-infra-internal task-review {task-id} preflight --stage plan --artifact {review-artifact} {execution-flag}` before any ledger write. On failure, follow `.agents/rules/local-artifact-repair.md`; on success, bind `{recovery-id}` from the response. Only after preflight passes, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage plan --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}` or prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. Do not scan ids or edit ledger rows. After all ledger writes, call `agent-infra-internal task-review {task-id} finalize-summary --stage plan --artifact {review-artifact} --recovery-id {recovery-id} {execution-flag}`; never treat an error type or `changed=false` as automatic authorization.
 
 Bind and reuse this structured mapping from that one response:
 

package/templates/.agents/skills/review-plan/SKILL.zh-CN.md

@@ -86,7 +86,7 @@ agent-infra-internal task-artifact {task-id} init --family review-plan --artifac
 
 ### 6. 更新任务状态
 
-报告完成后，新 finding 逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage plan --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`；复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。不得扫描编号或手写账本行。全部账本写入完成后首次调用 `agent-infra-internal task-review {task-id} finalize-summary --stage plan --artifact {review-artifact} {execution-flag}`；失败后是否继续编辑并重跑，必须遵循 `.agents/rules/local-artifact-repair.md`，不能把失败类型或 `changed=false` 当作自动授权。
+报告完成后，先调用 `agent-infra-internal task-review {task-id} preflight --stage plan --artifact {review-artifact} {execution-flag}`，不得先写入账本。失败后是否继续编辑并重跑，必须遵循 `.agents/rules/local-artifact-repair.md`；通过时从返回值绑定 `{recovery-id}`。只有 preflight 通过后，才逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage plan --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`，或复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。不得扫描编号或手写账本行。全部账本写入完成后调用 `agent-infra-internal task-review {task-id} finalize-summary --stage plan --artifact {review-artifact} --recovery-id {recovery-id} {execution-flag}`；不能把失败类型或 `changed=false` 当作自动授权。
 
 从该次返回值绑定并复用以下结构化映射：
 

package/dist/lib/host-control/audit.js

@@ -1,19 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-export const HOST_CONTROL_AUDIT_FILE = 'audit.ndjson';
-export function hostControlAuditPath(endpoint) {
-    return path.join(path.dirname(endpoint), HOST_CONTROL_AUDIT_FILE);
-}
-export function appendHostControlAudit(endpoint, entry, at = Date.now()) {
-    const filePath = hostControlAuditPath(endpoint);
-    const descriptor = fs.openSync(filePath, 'a', 0o600);
-    try {
-        fs.fchmodSync(descriptor, 0o600);
-        fs.writeFileSync(descriptor, `${JSON.stringify({ version: 1, at, ...entry })}\n`, 'utf8');
-        fs.fsyncSync(descriptor);
-    }
-    finally {
-        fs.closeSync(descriptor);
-    }
-}
-//# sourceMappingURL=audit.js.map

package/dist/lib/host-control/client.js

@@ -1,142 +0,0 @@
-import net from 'node:net';
-import { randomUUID } from 'node:crypto';
-import { inspectHostControlEndpoint, resolveHostControlEndpoint } from './path.js';
-export const HOST_CONTROL_MAX_REQUEST_BYTES = 64 * 1024;
-export const HOST_CONTROL_COMMANDS = Object.freeze([
-    'task-lifecycle', 'task-orchestration', 'task-finalization',
-    'task-artifact', 'task-review', 'task-event', 'task-ledger',
-    'task-invalidation', 'task-warning'
-]);
-export const HOST_CONTROL_TEST_ENVIRONMENT_KEYS = Object.freeze([
-    'TZ', 'AGENT_INFRA_GH_BIN', 'AGENT_INFRA_GH_ARGS_JSON', 'GH_FAKE_PR_PATH', 'GH_FAKE_ARGS_PATH'
-]);
-export class HostControlClientError extends Error {
-    code;
-    retryable;
-    changed;
-    constructor(code, message, retryable = false, submitted = false) {
-        super(`${code}: ${message}`);
-        this.name = 'HostControlClientError';
-        this.code = code;
-        this.retryable = retryable && !submitted;
-        this.changed = submitted ? null : false;
-    }
-}
-function reject(message) {
-    throw new HostControlClientError('HOST_CONTROL_REQUEST_INVALID', message);
-}
-export function validateHostControlRequest(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        reject('request must be an object');
-    const request = value;
-    if (Object.keys(request).sort().join(',') !== 'generation,id,operation,payload,scope,taskId,version'
-        || request.version !== 1 || typeof request.id !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(request.id)
-        || (request.taskId !== null && (typeof request.taskId !== 'string' || !/^TASK-\d{8}-\d{6}$/u.test(request.taskId)))
-        || (request.generation !== null && (typeof request.generation !== 'string' || !request.generation))
-        || request.scope !== 'host-command' || !HOST_CONTROL_COMMANDS.includes(request.operation))
-        reject('request schema is invalid');
-    const payload = request.payload;
-    if (!payload || typeof payload !== 'object' || Array.isArray(payload)
-        || !['args,environment,workingDirectory', 'args,workingDirectory'].includes(Object.keys(payload).sort().join(','))
-        || !Array.isArray(payload.args) || payload.args.length > 128
-        || !payload.args.every((arg) => typeof arg === 'string' && !/[\r\n]/u.test(arg))
-        || typeof payload.workingDirectory !== 'string' || !payload.workingDirectory.startsWith('/'))
-        reject('host-command payload is invalid');
-    if (payload.environment !== undefined) {
-        if (!payload.environment || typeof payload.environment !== 'object' || Array.isArray(payload.environment))
-            reject('host-command environment is invalid');
-        for (const [key, value] of Object.entries(payload.environment)) {
-            if (!HOST_CONTROL_TEST_ENVIRONMENT_KEYS.includes(key)
-                || typeof value !== 'string' || /[\r\n]/u.test(value))
-                reject('host-command environment is invalid');
-        }
-    }
-    return request;
-}
-export function hostControlRequestForCommand(command, args, workingDirectory, environment = {}) {
-    if (!HOST_CONTROL_COMMANDS.includes(command))
-        reject('host-command is unsupported');
-    const taskArg = args[0];
-    const taskId = taskArg && /^TASK-\d{8}-\d{6}$/u.test(taskArg) ? taskArg : null;
-    return validateHostControlRequest({
-        version: 1,
-        id: randomUUID(),
-        taskId,
-        generation: null,
-        operation: command,
-        scope: 'host-command',
-        payload: {
-            workingDirectory,
-            args: [...args],
-            ...(Object.keys(environment).length > 0 ? { environment } : {})
-        }
-    });
-}
-function parseResponse(value, id) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        throw new HostControlClientError('HOST_CONTROL_RESPONSE_INVALID', 'response must be an object');
-    const response = value;
-    if (Object.keys(response).sort().join(',') !== 'error,exitCode,id,status,stderr,stdout,version'
-        || response.version !== 1 || response.id !== id
-        || !['completed', 'rejected', 'unknown'].includes(response.status)
-        || !Number.isSafeInteger(response.exitCode)
-        || typeof response.stdout !== 'string' || typeof response.stderr !== 'string'
-        || (response.error !== null && (!response.error || typeof response.error !== 'object'))) {
-        throw new HostControlClientError('HOST_CONTROL_RESPONSE_INVALID', 'response schema is invalid');
-    }
-    return response;
-}
-export async function requestHostControl(params) {
-    const request = validateHostControlRequest(params.request);
-    const endpoint = params.endpoint ?? resolveHostControlEndpoint();
-    const inspection = inspectHostControlEndpoint(endpoint, { uid: process.getuid?.() });
-    if (!inspection.ok)
-        throw new HostControlClientError(inspection.code ?? 'HOST_CONTROL_UNAVAILABLE', 'fixed host-control endpoint is unavailable', true);
-    const encoded = `${JSON.stringify(request)}\n`;
-    if (Buffer.byteLength(encoded, 'utf8') > HOST_CONTROL_MAX_REQUEST_BYTES)
-        throw new HostControlClientError('HOST_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit');
-    const timeoutMs = params.timeoutMs ?? 30_000;
-    return await new Promise((resolve, rejectPromise) => {
-        const socket = net.createConnection(endpoint);
-        let output = '';
-        let settled = false;
-        let submitted = false;
-        const failure = (code, message, retryable = false) => new HostControlClientError(code, message, retryable, submitted);
-        const finish = (error, response) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            socket.destroy();
-            if (error)
-                rejectPromise(error);
-            else
-                resolve(response);
-        };
-        const timer = setTimeout(() => finish(failure('HOST_CONTROL_TIMEOUT', 'host-control did not respond; inspect task state before retrying', true)), timeoutMs);
-        socket.setEncoding('utf8');
-        socket.on('connect', () => { submitted = true; socket.end(encoded); });
-        socket.on('data', (chunk) => {
-            output += chunk;
-            if (Buffer.byteLength(output, 'utf8') > HOST_CONTROL_MAX_REQUEST_BYTES) {
-                finish(failure('HOST_CONTROL_RESPONSE_TOO_LARGE', 'host-control response exceeds the control limit'));
-                return;
-            }
-            const newline = output.indexOf('\n');
-            if (newline < 0)
-                return;
-            try {
-                finish(undefined, parseResponse(JSON.parse(output.slice(0, newline)), request.id));
-            }
-            catch (error) {
-                finish(failure('HOST_CONTROL_RESPONSE_INVALID', String(error)));
-            }
-        });
-        socket.on('error', (error) => finish(failure('HOST_CONTROL_UNAVAILABLE', error.message, true)));
-        socket.on('close', () => {
-            if (!settled)
-                finish(failure('HOST_CONTROL_RESPONSE_INVALID', 'host-control closed without a response'));
-        });
-    });
-}
-//# sourceMappingURL=client.js.map

package/dist/lib/host-control/command.js

@@ -1,49 +0,0 @@
-import { spawn } from 'node:child_process';
-import fs from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { readHostControlWorkerToken, resolveHostControlEndpoint } from './path.js';
-export async function dispatchHostControlCommand(request) {
-    const { payload } = request;
-    const compiledEntry = fileURLToPath(new URL('../../bin/internal-cli.js', import.meta.url));
-    const sourceEntry = fileURLToPath(new URL('../../bin/internal-cli.ts', import.meta.url));
-    const entry = fs.existsSync(compiledEntry) ? compiledEntry : sourceEntry;
-    const payloadEnvironment = payload.environment ?? {};
-    const env = { ...process.env, ...payloadEnvironment };
-    for (const key of Object.keys(env)) {
-        if (key.startsWith('AGENT_INFRA_CONTROL_')
-            || key === 'AGENT_INFRA_TASK_ID'
-            || key === 'AGENT_INFRA_RUNTIME_DIR'
-            || key === 'AGENT_INFRA_EXECUTOR_MANIFEST'
-            || key === 'AGENT_INFRA_HOST_CONTROL_SOCKET') {
-            delete env[key];
-        }
-    }
-    delete env.NODE_OPTIONS;
-    delete env.NODE_PATH;
-    delete env.AGENT_INFRA_HOST_CONTROL_WORKER;
-    delete env.AGENT_INFRA_HOST_CONTROL_WORKER_TOKEN;
-    env.AGENT_INFRA_HOST_CONTROL_WORKER = '1';
-    env.AGENT_INFRA_HOST_CONTROL_WORKER_TOKEN = readHostControlWorkerToken(process.env.AGENT_INFRA_TEST_HOST_CONTROL_ENDPOINT ?? resolveHostControlEndpoint());
-    return await new Promise((resolve, reject) => {
-        const runtimeArgs = entry.endsWith('.ts') ? ['--experimental-strip-types', '--no-warnings', entry] : [entry];
-        const child = spawn(process.execPath, [...runtimeArgs, request.operation, ...payload.args], {
-            cwd: payload.workingDirectory,
-            env,
-            stdio: ['ignore', 'pipe', 'pipe']
-        });
-        let stdout = '';
-        let stderr = '';
-        child.stdout.setEncoding('utf8');
-        child.stderr.setEncoding('utf8');
-        child.stdout.on('data', (chunk) => { stdout += chunk; });
-        child.stderr.on('data', (chunk) => { stderr += chunk; });
-        child.once('error', reject);
-        child.once('close', (code, signal) => {
-            if (signal)
-                reject(new Error(`HOST_CONTROL_WORKER_TERMINATED: ${signal}`));
-            else
-                resolve({ stdout, stderr, exitCode: code ?? 1 });
-        });
-    });
-}
-//# sourceMappingURL=command.js.map