@fitlab-ai/agent-infra 0.9.2 → 0.9.4

package/templates/.agents/skills/review-pr/reference/evidence-grading.zh-CN.md

@@ -0,0 +1,65 @@
+# 证据分级参考
+
+本文件固化 `review-pr` 的证据分级主决策流。判定全部由 typed core 纯函数（`lib/pr-review/evidence-grading.ts`）机械执行，skill 提示词层只做编排；本文件用于解释判据与理由，不替代 core。
+
+## 主决策流
+
+```text
+解析 PR base/head 与关联 Issue/task（宿主解析）
+   ├─ 唯一宿主 → 绑定任务，枚举 artifact 存在性 → 证据分类
+   ├─ 多宿主歧义 → fail closed（decide 拒绝分类，要求人工指定）
+   └─ 无宿主 → 默认阻塞要求关联；显式一次性检视 → reviews/{pr-number}/
+        ↓
+证据场景分类（S1/S2/S3）→ 新鲜度/对齐 → 风险分级 → 模式选择
+```
+
+## 宿主解析
+
+- 唯一命中 → `unique`；多个且无法唯一 → `ambiguous`（候选列表）；零命中 → `none`。
+- 多宿主歧义即 fail closed：不进入证据分类；由 `pr-review-grade resolve-host --pr <N>` 返回 typed `HostResolution`，`decide` 对 `ambiguous` 显式拒绝。
+- PR body 的 `Closes/Fixes #N`（大小写不敏感、逗号/空格分隔、支持列表）经 `extractClosingIssueNumbers` 解析；本地 `active/*/task.md` 的 `pr_number` 命中优先于 `issue_number` 反查，同一任务经两条路径命中按单候选去重。
+
+## 证据场景分类（S1 → S2 → S3）
+
+| 场景 | 判据 |
+|------|------|
+| S1 完整可信 | 唯一任务且 issue_number 与远端一致 + `analysis`/`plan`/`code` 及三族 review 齐全 + 最新 `pr-review*` 被审 head == 当前 head + 来源受信 |
+| S2 部分/可疑 | 任务存在但 artifact 缺失关键产物，或 head 漂移，或来源不可信 / 无法证明与当前 head 对齐 |
+| S3 仅 PR | 无宿主；或任务唯一但无任何生命周期 artifact 且无先前 `pr-review*` |
+
+- S3(b) 判据（对称口径）：`!hasAnalysis && !hasPlan && !hasCode && !hasReviewAnalysis && !hasReviewPlan && !hasReviewCode && !hasPriorPrReview`。仅含任一 review 产物（review-analysis / review-plan / review-code）的畸形任务落 S2 → audit。
+- 首次审查（无先前 `pr-review*`）时 S1(c) 不满足，完整生命周期任务落入 S2 → audit。
+
+## 新鲜度与对齐
+
+- 新鲜度基准 = 上一轮 `pr-review*` 记录的被审 head SHA，与当前 head 逐字符比对：一致 → `fresh`，否则 → `stale`。
+- 对齐 = freshness 为 fresh 且 `issue_number` / `pr_number` 与解析结果一致。
+- 无先前 `pr-review*` → `n/a` / `n/a`（首轮特例）。
+
+## 风险分级（纯证据口径）
+
+| 因素 | LOW | HIGH |
+|------|-----|------|
+| 变更规模 | 文件少、净增行少 | 文件多、净增行大 |
+| 变更敏感度 | 未触及受保护路径 | 触及 lifecycle / rule / skill / config / 安全 / 认证 / 幂等 / 并发路径 |
+| 结构性变更 | 无 schema/frontmatter/迁移/接口契约变化 | 涉及 schema / frontmatter / 迁移 / 接口契约 |
+| 测试覆盖 | 有配套测试且可通过 | 无测试或测试缺失/不可通过 |
+| 证据来源可信度 | 存在可复核的受信生命周期且与当前 head 对齐 | 无受信记录，或来源不可复核 |
+| 恢复/合并影响 | 不影响可恢复契约 | 可能破坏可恢复契约或形成双写真源 |
+
+聚合：任一优先因素（敏感度 / 证据来源可信度）HIGH → HIGH；否则任一 HIGH → MEDIUM；全 LOW → LOW。身份因素不参与任何因素判定。
+
+## 模式选择矩阵
+
+| 证据场景 | 新鲜度/对齐 | 风险 | 模式 |
+|----------|-------------|------|------|
+| S1 | fresh + aligned | LOW/MEDIUM | verify（轻量复核） |
+| S1 | fresh + aligned | HIGH | audit（证据审计） |
+| S2 | stale / misaligned / 部分缺失 | 任意 | audit |
+| S3 | n/a | 任意 | reconstruct（重建式审查） |
+
+首次对完整生命周期任务运行 `review-pr` 因无先前 head 记录落入 S2 → audit；「已有可信生命周期记录 → verify」对应「存在上轮 `pr-review*` 且 head 未漂移」的再审查场景。
+
+## 最低充分重建
+
+模式为 `reconstruct`（或 `audit` 证据不足）时，在行级审查前形成重建记录，至少覆盖：需求边界、架构选择、影响面、验证覆盖；顺序保证「重建上下文 → 覆盖矩阵 → 行级 finding」。

package/templates/.agents/skills/review-pr/reference/output-guidance.en.md

@@ -0,0 +1,18 @@
+# Output Guidance
+
+Read this file and `.agents/rules/next-step-output.md` before presenting the final result to the user. `review-pr` has exactly three exits; pick exactly one based on the run outcome.
+
+## Exit Selection
+
+| Exit | Trigger | Present |
+|------|---------|---------|
+| A Published | the formal Review was published (applied/no-op) and verification passed | conclusion, mode, reviewed head SHA, Review URL, receipt, next step |
+| B Blocked, requires linking | `resolve-host` returned none or ambiguous | linking guidance (create/link an Issue and task); do not auto-create an Issue; or explicitly choose the one-shot review |
+| C One-shot review | the user explicitly chose a "one-shot review" | non-recoverable notice, artifact directory `.agents/workspace/reviews/{pr-number}/`, Review URL |
+
+## Presentation Requirements
+
+- On publish (exit A) report: review mode (verify/audit/reconstruct), evidence scenario (S1/S2/S3), reviewed head SHA, finding count, formal Review URL, receipt.
+- On block (exit B) provide concrete commands/steps to establish the link; if `resolve-host` returned `ambiguous`, list the candidate tasks and ask a human to pin the host.
+- On one-shot (exit C) state clearly `recoverable: false` and make no recovery promise.
+- Read `.agents/rules/next-step-output.md` before rendering the next step, and generate the "next step" command per its convention.

package/templates/.agents/skills/review-pr/reference/output-guidance.zh-CN.md

@@ -0,0 +1,18 @@
+# 输出指引
+
+向用户呈现最终结果前先读取本文件与 `.agents/rules/next-step-output.md`。`review-pr` 有且仅有三个出口，按本次运行结果选一个，不要输出多个。
+
+## 出口选择
+
+| 出口 | 触发条件 | 呈现内容 |
+|------|----------|----------|
+| A 正常发布 | 正式 Review 已发布（applied/no-op）且校验通过 | 结论、模式、被审 head SHA、Review URL、receipt、下一步 |
+| B 阻塞要求关联 | `resolve-host` 返回 none 或 ambiguous | 关联指引（创建/关联 Issue 与 task），不自动创建 Issue；或显式选择一次性检视 |
+| C 一次性检视 | 用户显式选择「仅一次性检视」 | 不可恢复提示、产物目录 `.agents/workspace/reviews/{pr-number}/`、Review URL |
+
+## 呈现要求
+
+- 正常发布（出口 A）时报告：审查模式（verify/audit/reconstruct）、证据场景（S1/S2/S3）、被审 head SHA、finding 总数、正式 Review URL、receipt。
+- 阻塞（出口 B）时给出建立关联的具体命令或步骤；如果 `resolve-host` 返回 ambiguous，列出候选任务并要求人工指定。
+- 一次性检视（出口 C）明确 `recoverable: false`，不承诺可恢复。
+- 渲染下一步前读取 `.agents/rules/next-step-output.md`，并按其中的「下一步」命令约定生成。

package/templates/.agents/skills/review-pr/reference/report-template.en.md

@@ -0,0 +1,85 @@
+# PR Review Report Template
+
+Use the following structure when creating `pr-review.md` or `pr-review-r{N}.md`.
+
+```markdown
+# PR Review Report
+
+- **Review Round**: Round {round}
+- **Artifact File**: `pr-review.md` / `pr-review-r{N}.md`
+- **Recoverable**: true (task-anchored path) / false (one-shot path)
+
+## State Check
+
+> Paste the state-check command output verbatim; each command starts with `$ `.
+
+## Identity
+
+- **PR Number**: {pr-number}
+- **Base Branch**: {base-ref} (SHA `{base-sha}`)
+- **Head Branch**: {head-ref}
+- **Reviewed Head SHA**: {40 hex}
+- **Linked Issue**: {issue-number or N/A}
+- **Linked Task**: {task-id or N/A}
+- **Task Directory**: {task-dir or N/A}
+
+## Evidence List
+
+- **Host Resolution**: `unique` / `ambiguous` / `none`
+- **Evidence Scenario**: S{1|2|3}
+- **Freshness**: `fresh` / `stale` / `n/a`
+- **Alignment**: `aligned` / `misaligned` / `n/a`
+- **Review Mode**: `verify` / `audit` / `reconstruct`
+- **Risk Level**: `LOW` / `MEDIUM` / `HIGH`
+- **First Review**: true / false
+- **receipt**: {receipt}
+- **Decision Input and Output**: paste the full `pr-review-grade decide` input JSON and the output DecisionRecord (the decision input includes host, artifact presence, head state, and the six risk factors).
+
+### Reconstruction Context (reconstruct / audit with insufficient evidence)
+
+Land the following in order before the line-level findings, without impersonating a standard lifecycle artifact:
+
+1. **Requirement boundary**: what the PR does and does not do.
+2. **Architecture choices**: key technical paths and trade-offs.
+3. **Impact surface**: modules / rules / contracts touched.
+4. **Validation coverage**: what tests should exist and whether current tests cover them.
+
+## Coverage Matrix
+
+| Review Surface | Evidence | Conclusion | Uncovered / Gap |
+|----------------|----------|------------|-----------------|
+| Requirement boundary | {evidence} | {conclusion} | {gap} |
+| Architecture choices | {evidence} | {conclusion} | {gap} |
+| Impact surface | {evidence} | {conclusion} | {gap} |
+| Validation coverage | {evidence} | {conclusion} | {gap} |
+
+## Findings
+
+### Blockers (must fix)
+
+- **{title}**: {description} · `{file}:{line}` · Evidence: {evidence} · Impact: {impact} · Suggestion: {suggestion}
+
+### Major (should fix)
+
+- **{title}**: {description} · `{file}:{line}` · Evidence: {evidence} · Impact: {impact} · Suggestion: {suggestion}
+
+### Minor (low impact, close the loop)
+
+- **{title}**: {description} · `{file}:{line}` · Evidence: {evidence} · Impact: {impact} · Suggestion: {suggestion}
+
+## Publication Result
+
+- **Formal Review Status**: {pending / applied / no-op / aborted / superseded / blocked / failed}
+- **Review ID**: {review-id or N/A}
+- **Review URL**: {review-url or N/A}
+- **Issue Artifact Comment URL**: {comment-url or N/A}
+
+## Evidence
+
+> Every "I verified X" assertion must pair with the corresponding tool output verbatim; the gate only checks this section exists and has at least one `$ ` line.
+
+- Assertion: {verified claim}
+```text
+$ {command}
+{raw output}
+```

package/templates/.agents/skills/review-pr/reference/report-template.zh-CN.md

@@ -0,0 +1,85 @@
+# PR 审查报告模板
+
+创建 `pr-review.md` 或 `pr-review-r{N}.md` 时使用以下结构。
+
+```markdown
+# PR 审查报告
+
+- **审查轮次**：Round {round}
+- **产物文件**：`pr-review.md` / `pr-review-r{N}.md`
+- **可恢复**：true（任务锚定路径）/ false（一次性检视路径）
+
+## 状态核对
+
+> 粘贴状态核对命令原文；每条命令以 `$ ` 开头。
+
+## 身份信息
+
+- **PR 编号**：{pr-number}
+- **Base 分支**：{base-ref}（SHA `{base-sha}`）
+- **Head 分支**：{head-ref}
+- **被审 head SHA**：{40 位 hex}
+- **关联 Issue**：{issue-number 或 N/A}
+- **关联任务**：{task-id 或 N/A}
+- **关联任务目录**：{task-dir 或 N/A}
+
+## 证据清单
+
+- **宿主解析结果**：`unique` / `ambiguous` / `none`
+- **证据场景**：S{1|2|3}
+- **新鲜度**：`fresh` / `stale` / `n/a`
+- **对齐**：`aligned` / `misaligned` / `n/a`
+- **审查模式**：`verify` / `audit` / `reconstruct`
+- **风险等级**：`LOW` / `MEDIUM` / `HIGH`
+- **是否首次审查**：true / false
+- **receipt**：{receipt}
+- **决策输入与输出**：粘贴 `pr-review-grade decide` 的完整输入 JSON 与输出 DecisionRecord（decision 输入含宿主、artifact 存在性、head 状态、六个风险因素）。
+
+### 重建上下文（reconstruct / audit 证据不足时）
+
+在行级 finding 之前按以下顺序落盘，不冒充标准生命周期产物：
+
+1. **需求边界**：PR 要实现什么、不做什么。
+2. **架构选择**：关键技术路径与取舍。
+3. **影响面**：改动波及的模块 / 规则 / 契约。
+4. **验证覆盖**：应有哪些测试、现有测试能否覆盖。
+
+## 覆盖矩阵
+
+| 检视面 | 证据 | 结论 | 未覆盖/缺口 |
+|--------|------|------|-------------|
+| 需求边界 | {证据} | {结论} | {缺口} |
+| 架构选择 | {证据} | {结论} | {缺口} |
+| 影响面 | {证据} | {结论} | {缺口} |
+| 验证覆盖 | {证据} | {结论} | {缺口} |
+
+## 问题清单
+
+### 阻塞项（必须修复）
+
+- **{标题}**：{描述} · `{file}:{line}` · 证据：{evidence} · 影响：{impact} · 建议：{suggestion}
+
+### 主要问题（建议修复）
+
+- **{标题}**：{描述} · `{file}:{line}` · 证据：{evidence} · 影响：{impact} · 建议：{suggestion}
+
+### 次要问题（低影响但需闭环）
+
+- **{标题}**：{描述} · `{file}:{line}` · 证据：{evidence} · 影响：{impact} · 建议：{suggestion}
+
+## 发布结果
+
+- **正式 Review 状态**：{pending / applied / no-op / aborted / superseded / blocked / failed}
+- **Review ID**：{review-id 或 N/A}
+- **Review URL**：{review-url 或 N/A}
+- **Issue artifact 评论 URL**：{comment-url 或 N/A}
+
+## 证据原文
+
+> 每条「我验证了 X」断言都要配对对应 tool output 原文；gate 仅校验本段存在和至少一行 `$ `。
+
+- 断言：{verified claim}
+```text
+$ {command}
+{raw output}
+```

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

@@ -7,16 +7,16 @@ description: >
 
 # Run Task Lifecycle
 
-The orchestrator delegates only and never executes a stage skill itself. First read `.agents/rules/no-mid-flow-questions.md` and `.agents/rules/lifecycle-orchestration.md`.
+The orchestrator delegates only and never executes a stage skill itself. First read `.agents/rules/no-mid-flow-questions.md`, `.agents/rules/lifecycle-orchestration.md`, and `reference/host-validation.md`.
 
-1. Resolve the task and run `agent-infra-internal task-snapshot {task-id} --format text`.
-2. Run `agent-infra-internal task-orchestration {task-id} begin-or-resume`; stop on structured paused/completed results.
-3. Run `route` and use its single action, role, round, and artifact. Never infer routing from review prose.
-4. Run `agent-infra-internal task-orchestration {task-id} prepare --client {client}` so core records the workspace baseline, then start the specified executor/reviewer with the current client's fresh native subagent mechanism. Pass only the short task reference, skill name, and minimal handoff; never pass receipt identity or inherit orchestrator history.
+1. Resolve the task, current Agent Client, and optional atomic policy flags `--executor-model`, `--executor-reasoning-effort`, `--reviewer-model`, and `--reviewer-reasoning-effort`, then run `task-snapshot`. If any explicit policy flag is present, all four role fields are required and must not be merged with configuration; both roles may use the same model.
+2. Run `task-orchestration {task-id} begin-or-resume --client {client}` with the complete explicit policy. With no explicit policy, core reads only that client's `agentClients[].orchestration`; an existing v2 run uses its persisted policy. Only on `ORCHESTRATION_MODEL_POLICY_REQUIRED`, show the complete/partial/interactive-only `agent-client model-selection` context and collect one complete policy; no answer means no run is created. Stop on paused/completed results.
+3. Run `route` and read its structured result. On `completed`, immediately run `agent-infra-internal task-verify {task-id} run-task.completed --format text` and stop. Only when the result is `running` with a non-null `next`, use its single action, role, round, artifact, `requestedModel`, and `requestedReasoningEffort`; never infer them from review prose, session defaults, or a partial tool schema.
+4. Only for the `running` result from step 3, run `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort}` so core validates both fields and host evidence before snapshotting. Claude Code's native start event currently cannot provide stable actual model/effort evidence, so it returns `ORCHESTRATION_CLIENT_UNSUPPORTED` and stops like any other client without that evidence. Only after validation succeeds, start a fresh native child with the same model/effort overrides and only the short task ref, skill name, literal `--orchestrated` execution marker, and minimal handoff. The child must forward that marker to every provenance-sensitive command in the stage.
 5. Native start/stop hooks correlate the unique pending delegation and let core compute workspace changes and seal the receipt. After the child returns, run `advance`. Repeat step 3 only for `running`; stop immediately for `paused` or `completed`.
-6. Create a new child every round and never follow up with an old reviewer. Capability, hook, identity, model fallback, ledger, or fingerprint failures must call `pause` and fail closed.
-7. On pause or completion, run the matching typed verification and report the structured run summary, pause reason, or commit endpoint.
+6. Create a new child every round and never follow up with an old reviewer. Native start must report actual model and actual reasoning effort; each requested/actual mismatch needs its own host fallback reason, and requested values must never be fabricated as actual evidence. Capability, hook, identity, evidence, ledger, or fingerprint failures must call `pause` and fail closed.
+7. On pause or completion, run the matching typed verification and report the structured run summary, pause reason, commit endpoint, or clean completion evidence.
 
 ## Stop
 
-The first release ends after a safe `commit`; do not create a PR, monitor checks, or complete the task.
+Stop after a safe `commit` or reviewed-head-clean endpoint; do not create a PR, monitor checks, or archive the task.

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

@@ -7,16 +7,16 @@ description: >
 
 # 运行任务生命周期
 
-总控只编排，不直接执行任何阶段技能。执行前先读取 `.agents/rules/no-mid-flow-questions.md` 与 `.agents/rules/lifecycle-orchestration.md`。
+总控只编排，不直接执行任何阶段技能。执行前先读取 `.agents/rules/no-mid-flow-questions.md`、`.agents/rules/lifecycle-orchestration.md` 与 `reference/host-validation.md`。
 
-1. 解析任务引用并执行 `agent-infra-internal task-snapshot {task-id} --format text`。
-2. 调用 `agent-infra-internal task-orchestration {task-id} begin-or-resume`；若为 paused/completed，按结构化结果停止。
-3. 调用 `route` 并读取唯一 action、role、round 和 artifact；不得从审查文案自行推断。
-4. 调用 `agent-infra-internal task-orchestration {task-id} prepare --client {client}`；核心自动记录工作区基线。成功后用当前客户端的 fresh 原生子 Agent 启动指定 executor/reviewer，只传短任务引用、skill 名和最小交接摘要，不传 receipt identity，不继承总控历史。
+1. 解析任务引用、当前 Agent Client，以及可选的原子策略 `--executor-model`、`--executor-reasoning-effort`、`--reviewer-model`、`--reviewer-reasoning-effort`，并执行 `agent-infra-internal task-snapshot {task-id} --format text`。任一显式策略字段出现时四个 role 字段必须完整，不得与配置拼接；两个角色可以使用同一模型。
+2. 调用 `agent-infra-internal task-orchestration {task-id} begin-or-resume --client {client}` 并转发完整显式策略。完全没有显式策略时由核心读取当前 client 的 `agentClients[].orchestration`；已有 v2 run 使用持久化策略。仅当核心返回 `ORCHESTRATION_MODEL_POLICY_REQUIRED` 时，先用 `agent-client model-selection` 展示 complete/partial/interactive-only 来源，再一次收集完整策略；未回答则不创建 run。若为 paused/completed，按结构化结果停止。
+3. 调用 `route` 并读取结构化结果。若返回 `completed`，立即运行 `agent-infra-internal task-verify {task-id} run-task.completed --format text` 并停止；仅当返回 `running` 且 `next` 非空时读取唯一 action、role、round、artifact、`requestedModel` 和 `requestedReasoningEffort`，不得从审查文案、会话默认或局部 tool schema 自行推断。
+4. 仅对步骤 3 的 `running` 结果调用 `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort}`；核心在记录工作区基线前校验两字段与宿主证据能力。当前 Claude Code 的原生 start 事件无法稳定提供 actual model/effort，因此与其他缺少该证据的客户端一样返回 `ORCHESTRATION_CLIENT_UNSUPPORTED` 并停止。只有校验成功时才用当前客户端的 fresh 原生子 Agent 启动指定角色，并显式覆盖同一 model/effort；只传短任务引用、skill 名、字面执行标记 `--orchestrated` 和最小交接摘要，不传 receipt identity，不继承总控历史。子 Agent 必须把该标记转发给本阶段所有 provenance 敏感命令。
 5. 原生 start/stop hook 通过唯一 pending delegation 自动关联任务，并由核心计算工作区变化、封存 receipt；子 Agent 返回后调用 `advance`。只有 `running` 才重复步骤 3；`paused` 或 `completed` 立即停止。
-6. 每轮创建新 child；禁止 follow-up 复用 reviewer。任何 capability、hook、身份、模型降级、账本或 fingerprint 异常都调用 `pause` 并失败关闭。
-7. 完成或暂停后运行对应 typed verification，并把结构化 run 摘要、暂停原因或 commit 终点告知用户。
+6. 每轮创建新 child；禁止 follow-up 复用 reviewer。原生 start 必须回传 actual model 与 actual reasoning effort；任一 actual 与 requested 不同时必须有各自的宿主降级理由，缺失时不得用 requested 值补造。任何 capability、hook、身份、证据、账本或 fingerprint 异常都调用 `pause` 并失败关闭。
+7. 完成或暂停后运行对应 typed verification，并把结构化 run 摘要、暂停原因、commit 终点或 clean completion evidence 告知用户。
 
 ## 停止
 
-首版在安全 `commit` 后结束；不要继续创建 PR、监控 checks 或完成任务。
+在安全 `commit` 或 reviewed-head-clean 终点后结束；不要继续创建 PR、监控 checks 或归档任务。

package/templates/.agents/skills/run-task/config/verify.en.json

@@ -4,6 +4,7 @@
     "task-meta": {
       "required_fields": ["id", "status", "updated_at", "agent_infra_version", "current_step", "assigned_to"]
     },
-    "orchestration-state": {}
+    "orchestration-state": {},
+    "orchestration-evidence": {}
   }
 }

package/templates/.agents/skills/run-task/config/verify.zh-CN.json

@@ -4,6 +4,7 @@
     "task-meta": {
       "required_fields": ["id", "status", "updated_at", "agent_infra_version", "current_step", "assigned_to"]
     },
-    "orchestration-state": {}
+    "orchestration-state": {},
+    "orchestration-evidence": {}
   }
 }

package/templates/.agents/skills/run-task/reference/host-validation.en.md

@@ -0,0 +1,20 @@
+# Host Contract Validation
+
+Before publishing support for a client, prove the lifecycle evidence chain with real host events. Bridge tests prove field mapping only; they do not prove host provenance.
+
+## Required Evidence
+
+- Client version, enabled multi-agent capability, launch surface, and trust boundary.
+- Raw start/stop events stably provide event type, managed agent, parent/child identity, fresh spawn mode, actual model, and actual reasoning effort.
+- Explicit requested model/effort reaches each executor/reviewer. A fallback of either field reports the corresponding actual value and its own non-empty reason.
+- Candidate-checkout and packed-install behavior match, with model policy, receipts, and verification results auditable in `orchestration.json`.
+
+## Validation Sequence
+
+1. Record client version, feature state, and launch command in a clean temporary repository.
+2. Start a fresh executor and reviewer, retaining redacted raw stdin and the structured run. Never synthesize a field the host did not emit.
+3. Validate model/effort match paths, single and dual justified fallbacks, and fail-closed behavior for missing actual fields.
+4. Validate the same commit from a candidate checkout and an `npm pack` install; record the tarball hash and results.
+5. Commit only redacted summaries and non-sensitive fixtures. Remove or replace tokens, user-specific absolute paths, transcript content, and credentials.
+
+If any required field cannot be observed reliably from the real host, keep that client's orchestration capability `unsupported` and record the gap as manual validation.

package/templates/.agents/skills/run-task/reference/host-validation.zh-CN.md

@@ -0,0 +1,20 @@
+# 宿主契约验证
+
+发布支持某个客户端前，必须用真实宿主事件证明生命周期证据链；bridge 单测只证明字段映射，不能证明事件来自宿主。
+
+## 必须证明的字段
+
+- 客户端版本、启用的多代理能力、启动入口与信任边界。
+- 原始 start/stop 事件能稳定给出 event type、managed agent、parent/child identity、fresh spawn mode、actual model 和 actual reasoning effort。
+- 显式 requested model/effort 能传给 executor/reviewer；宿主对任一字段回退时，事件能给出对应 actual 值与独立的非空 fallback reason。
+- candidate checkout 与打包安装后的行为一致，且模型策略、receipt 与验证结果可从 `orchestration.json` 复核。
+
+## 验证顺序
+
+1. 在干净临时仓库记录客户端版本、feature 状态和启动命令。
+2. 分别启动 fresh executor 与 fresh reviewer，保存去敏后的原始 stdin 和结构化 run；不得补写宿主未产生的字段。
+3. 分别验证 model/effort 的 requested/actual 一致路径、单项与双项有理由 fallback 路径，并确认缺 actual 字段会失败关闭。
+4. 对同一 commit 执行 candidate checkout 与 `npm pack` 安装验证，记录 tarball 哈希和结果。
+5. 仅把去敏摘要与非敏感 fixture 纳入版本库；token、绝对用户路径、transcript 内容和凭证必须删除或替换。
+
+任一字段无法从真实宿主稳定观察时，该客户端的 orchestration capability 保持 `unsupported`，并把缺口记录为人工验证项。